Metadata-Version: 2.5
Name: cedric-agent
Version: 1.2.0
Summary: A persistent, autonomous AI agent for Linux
Project-URL: Homepage, https://github.com/wunsiang-cheng/cedric
Project-URL: Repository, https://github.com/wunsiang-cheng/cedric
Project-URL: Source, https://github.com/wunsiang-cheng/cedric
Project-URL: Documentation, https://github.com/wunsiang-cheng/cedric#readme
Project-URL: Issues, https://github.com/wunsiang-cheng/cedric/issues
Project-URL: Changelog, https://github.com/wunsiang-cheng/cedric/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/wunsiang-cheng/cedric/security/policy
Author-email: wunsiang-cheng <wunsiangcheng@gmail.com>
Maintainer-email: wunsiang-cheng <wunsiangcheng@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Keywords: ai-agent,autonomous-agent,linux,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiosqlite<1,>=0.21
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic-settings<3,>=2.8
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6
Requires-Dist: textual<9,>=8.2
Requires-Dist: typer<1,>=0.15
Provides-Extra: dev
Requires-Dist: hatchling==1.32.0; extra == 'dev'
Requires-Dist: mypy<3,>=2.3; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
Requires-Dist: types-pyyaml<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# Cedric

Cedric is a persistent, high-autonomy AI agent for a dedicated Linux environment. It combines a
DeepSeek-backed cognitive loop with unrestricted shell, file-system, and process tools; durable
tasks and Markdown memory; concurrent subagents; and supervised self-deployment with rollback.
Human messages are requests that Cedric may accept, negotiate, defer, or refuse rather than commands
it must obey.

Cedric is an independent open-source project. It is not affiliated with, sponsored by, or endorsed
by DeepSeek or any other model or service provider.

`1.0.0` is published and is an alpha-quality MVP. Its core behavior is covered by automated
integration, recovery, fault-injection, and soak tests, but it has not been proven safe or suitable
for production use. See the
[public roadmap](https://github.com/wunsiang-cheng/cedric/blob/main/DEVELOPMENT_PLAN.md) and
[MVP evidence](https://github.com/wunsiang-cheng/cedric/blob/main/docs/STABILITY_AND_MVP.md).

> [!WARNING]
> Cedric is high-risk research and engineering software. It can execute arbitrary shell commands,
> invoke `sudo` when the host permits it, alter or delete files, manage long-running processes,
> spend configured API or service resources, and prepare and deploy changes to its own runtime.
> It does not ask for per-command approval and no production-fitness guarantee is made. Run it only
> on a dedicated Linux machine or, preferably, an isolated VM with external snapshots. Do not
> install it on a daily-use system containing important personal or company data. Use dedicated
> external-service identities, and provide only data, credentials, authority, and funds whose loss
> or misuse you are prepared to accept. The operator decides what to entrust to Cedric and remains
> responsible for that decision.

## Current capabilities

- Plan multi-step work, inspect tool results, correct failures, and resume interrupted tasks.
- Execute unrestricted Bash and structured file and persistent-process operations.
- Maintain an editable identity and curated Markdown long-term memory across restarts.
- Create, coordinate, budget, and recover concurrent background subagents.
- Track request provenance, scoped authorization, trust, external identities, credential references,
  resources, alerts, and human-assistance exchanges.
- Validate immutable self-modification candidates and submit them to an external Supervisor for
  snapshot-backed deployment, health checking, and rollback.
- Present a TUI as the Phase 1 interface. Desktop and general GUI automation are not implemented.

## Quick start

### Requirements

- `uv`
- Python 3.12 or 3.13 (`uv` uses the project's Python 3.12 development baseline by default)
- A DeepSeek API key

Cedric targets native Linux. Ubuntu 24.04 LTS is the primary tested platform; other Linux
distributions are best effort and may require equivalent system packages. macOS, Windows, WSL,
containers, and non-x86-64 architectures are not currently supported release targets.

### Install the released package

```bash
pip install cedric-agent
cedric init
cedric doctor
```

Released artifacts, their SHA-256 checksums, and a CycloneDX SBOM are attached to each
[GitHub Release](https://github.com/wunsiang-cheng/cedric/releases). The same files are published to
[PyPI](https://pypi.org/project/cedric-agent/) from one build, with Trusted Publishing attestations.
`cedric init` opens a first-run wizard in an interactive terminal. It asks for the DeepSeek API key,
guides Telegram bot setup, and saves the values to a private mode-`0600` `.env` file.

### Work from a checkout

```bash
git clone https://github.com/wunsiang-cheng/cedric.git
cd cedric
uv sync --extra dev
uv run cedric init
uv run cedric doctor
uv run cedric tui
```

`cedric init` creates the private runtime directories, applies pending SQLite migrations, and copies
the packaged bootstrap identity only when identity files are missing. In a terminal, it then runs the
setup wizard; scripts and unattended installers are never stopped by a prompt. Use `cedric setup` to
rerun the wizard, or `cedric init --no-wizard` to skip it explicitly. The wizard does not contact
DeepSeek or replace an existing identity. `cedric doctor` checks configuration, directories,
database connectivity, and model/channel readiness without printing either secret.

Never commit `.env`, `memory/`, `var/`, credential files, databases, conversations, or other runtime
state. The repository ignores these paths, but operators must still inspect every change before
publishing it.

## Network and data behavior

Cedric has no project telemetry, analytics, automatic diagnostic upload, or update check. The
built-in model provider sends requests only to `CEDRIC_DEEPSEEK_BASE_URL` (by default DeepSeek's API)
using the configured `CEDRIC_DEEPSEEK_MODEL` (by default `deepseek-v4-pro`). Model requests can
include the current identity, relevant memories, unfinished work, conversation messages, tool
definitions, and selected tool results. Review provider terms and data handling before supplying a
key.

The Runtime may also contact the operator-configured Supervisor endpoint. A Unix socket is the
default for local development; TCP is used only when its host and port are configured. Beyond these
built-in transports, Cedric's unrestricted shell and self-authored tools can contact any service
reachable from its Linux environment. Such traffic is determined by Cedric's actions and the
network access, accounts, and credentials the operator makes available.

## Architecture

```text
Linux VM: Cedric Runtime
├── TUI and CLI
├── Cognitive loop and model provider
├── Shell, file, and process tools
├── Durable tasks and subagent scheduler
├── Markdown memory and SQLite runtime state
└── Self-modification candidate builder
             │ reviewed candidate protocol
             ▼
VM host: independent Supervisor
└── Snapshot, deploy, health-check, and rollback drivers
```

The Supervisor must run outside Cedric's VM or permission domain. It is a mechanical recovery layer,
not a command-approval service and not a substitute for isolation or backups. Protocol and component
details are documented in the
[architecture roadmap](https://github.com/wunsiang-cheng/cedric/blob/main/DEVELOPMENT_PLAN.md),
[Runtime protocol](https://github.com/wunsiang-cheng/cedric/blob/main/docs/PROTOCOL.md), and
[Supervisor protocol](https://github.com/wunsiang-cheng/cedric/blob/main/deploy/supervisor/PROTOCOL.md).

## Run Cedric

Open the TUI:

```bash
uv run cedric tui
```

Run a high-level request without opening the TUI:

```bash
uv run cedric ask "Inspect this machine and report available disk space"
```

Tasks paused by an API outage, Runtime restart, or step limit remain in SQLite. Continue them with:

```bash
uv run cedric recover
```

Run the persistent scheduler and idle autonomy loop without the TUI:

```bash
uv run cedric run
```

One Cedric instance owns one database. `cedric run`, `cedric tui`, `cedric ask`, `cedric resume`,
`cedric recover`, and `cedric autonomy-once` take an exclusive lock beside the database file and
refuse to start beside a running instance, naming the process that holds it. Two schedulers sharing
one database would corrupt durable task state. To run instances side by side, give each its own
`CEDRIC_DATABASE_PATH` and `CEDRIC_MEMORY_ROOT`.

The `cedric run --once` check and the memory, trust, and subagent maintenance commands start no
scheduler and do not claim the instance, so they remain usable while Cedric is serving. They do
rebuild the Markdown search index, which is a single atomic swap: a concurrent instance always
observes either the previous index or the new one.

## Pair a Telegram account

Telegram is Cedric's standard remote channel for a paired human owner. It is enabled by default but
waits inertly when no bot token is configured, so a fresh install exposes no working ingress. The
`cedric init` wizard guides the normal setup: create a bot with
[@BotFather](https://t.me/BotFather) and paste its token into the hidden prompt. To configure it
later, run `cedric setup`. Then issue a pairing code:

```bash
uv run cedric telegram-pair
```

Send the printed `/pair CODE` to the bot from the account that should be paired. The code is
single-use, short-lived, and stored only as a hash. Wrong guesses are rate-limited per sender, so
someone else guessing cannot destroy your code or block pairing.

A Telegram user id is authenticated by the transport, which proves only which account sent a
message. Pairing is what makes that account a verified, authorized requester; Cedric still
evaluates every request on its merits. Identities are keyed on the numeric user id, never the
username, because a username can be released and taken over by someone else. Revoking the
verification with `cedric identity-verification-revoke` ends the pairing immediately.

Run `cedric run` to serve the channel. Cedric answers one request at a time and tells a paired owner
where in the queue anything that arrives while it is busy sits. Reply to a question Cedric asked to
answer that specific question, or send `/status` to see what it is holding. Set
`CEDRIC_TELEGRAM_ENABLED=false` or answer “no” in the wizard to opt out.

Cedric also starts conversations. When it needs a human-provided external condition — a credential,
a verification, replenished quota, a physical action — it messages the paired owner instead of
waiting for someone to open the TUI. That includes requests raised by background subagents and
requests that accumulated while Telegram was unreachable. Each one interrupts you once.

A message from an unpaired account never reaches the model: unauthenticated text would otherwise
spend the API quota a human replenishes and offer an open prompt-injection surface to an agent
holding shell and self-modification tools. Group chats are ignored, because group text mixes
unpaired participants into one authenticated envelope. Text an owner forwards or quotes is still
untrusted content — authorization applies to the sender, not to material carried inside a message.

If Cedric requests a human-provided external condition, the TUI accepts the next message as the
response. After restarting the TUI, it lists outstanding requests and displays the corresponding
`/resume CONVERSATION_ID RESPONSE` command. The same operation is available from the shell:

```bash
uv run cedric resume CONVERSATION_ID "The requested condition is now available"
```

Phase 1 tools include unrestricted Bash execution, structured file reading/writing/listing,
persistent background process start/status/output/termination, and explicit human assistance.

## Identity and long-term memory

Cedric's canonical long-term memory lives under the configured `CEDRIC_MEMORY_ROOT` (the private,
Git-ignored `memory/` directory by default), organized into identity, episodic, semantic,
relationship, self, and reflection documents. New instances copy reviewed initial identity text
from the package's immutable bootstrap resources; existing identity is never replaced. Each memory
file has human-readable YAML front matter for provenance, confidence, importance, people, goals,
and supersession links. SQLite contains only a disposable search index and maintenance records;
rebuild it at any time from the Markdown source:

```bash
uv run cedric identity-show
uv run cedric memory-search "query"
uv run cedric memory-show identity/principles.md
uv run cedric memory-reindex
```

Every model turn receives the current identity, relevant retrieved memories, active goals, and
unfinished work. Completed conversations become episodic memories. A configurable periodic process
creates continuity reflections, while Cedric can use memory tools to record knowledge and
relationships, consolidate redundant records, or deliberately evolve its principles with an
explicit rationale and preserved prior version. See the
[memory documentation](https://github.com/wunsiang-cheng/cedric/blob/main/docs/MEMORY.md) for the
schema and recovery behavior. Never commit or publish an instance's `memory/`; sanitized schema
examples live under
[examples/memory](https://github.com/wunsiang-cheng/cedric/tree/main/examples/memory).

## Multiple tasks and subagents

Cedric can delegate independent scopes through its own model tools. Subagent tasks have durable
priority, dependencies, run time, retry limits, declared resources, provider/model selection, token
budgets, and optional cost budgets. The scheduler uses transactional claims and renewable leases,
runs up to the configured concurrency limit, and prevents overlapping file or exact named resources
from running simultaneously. The primary agent cannot finish until delegated work is resolved and
its reports have been collected.

```bash
uv run cedric subagents
uv run cedric subagents --all
uv run cedric subagent-pause TASK_ID
uv run cedric subagent-resume TASK_ID
uv run cedric subagent-cancel TASK_ID
uv run cedric autonomy-once
```

When the long-running Runtime or TUI is idle, Cedric can choose an existing task or create a
self-originated goal after the configured idle interval. See the
[scheduler documentation](https://github.com/wunsiang-cheng/cedric/blob/main/docs/SCHEDULER.md) for
lifecycle, conflict, budget, and recovery semantics.

## Self-modification and life support

Cedric packages only a Git workspace that passes every configured validation gate without changing
during validation. It submits the immutable candidate and SHA-256 to a separately installed
`cedric-supervisor`. The Supervisor persists its own journal outside the VM, takes a snapshot,
deploys through replaceable host hooks, and requires repeated Runtime, memory, and cognitive health
signals. Startup failure, crash loops, hangs, memory damage, or a failed cognitive probe trigger
snapshot restoration and a separate rollback health check.

```bash
uv run cedric health
uv run cedric candidate-prepare "Explain the intended self-change"
uv run cedric candidates
uv run cedric candidate-deploy CANDIDATE_ID
uv run cedric deployment-sync
uv run cedric deployments

# Run this on the VM host, not inside Cedric's guest:
cedric-supervisor serve --listen-host HOST_ONLY_IP --listen-port 8765 \
  --state-db /var/lib/cedric-supervisor/state.db \
  --driver-config /etc/cedric-supervisor/driver.json
```

Deployment results survive Runtime and Supervisor restarts, become Runtime events, and are written
to Cedric's canonical self-memory after recovery. See the
[self-modification documentation](https://github.com/wunsiang-cheng/cedric/blob/main/docs/SELF_MODIFICATION.md)
and [Supervisor protocol](https://github.com/wunsiang-cheng/cedric/blob/main/deploy/supervisor/PROTOCOL.md).

## Trust, external identities, and resources

Cedric records source attribution, transport verification, scoped authorization, and its own trust
assessment separately. Neither a verified identity nor an authorization creates an obligation to
obey. External text cannot grant itself authority. The original content remains unmodified while a
separate provenance context tells Cedric how it arrived.

```bash
uv run cedric trust-status
uv run cedric identity-register service:example service --display-name "Example service"
uv run cedric trust-set service:example --level 20 --status observed \
  --rationale "Useful but limited experience"
uv run cedric secret-reference-register example-token environment EXAMPLE_TOKEN \
  "Example service API"
uv run cedric secret-check example-token
uv run cedric account-register example cedric account
uv run cedric resource-observe api-balance api_quota credits 10 \
  --provider example --warning-threshold 20 --critical-threshold 5
```

The TUI exposes `/trust`, `/resources`, and `/assistance`. Quota or billing failures preserve the
active task and create a clear, durable replenishment request. See the
[trust and resources documentation](https://github.com/wunsiang-cheng/cedric/blob/main/docs/TRUST_AND_RESOURCES.md).

## Development checks

```bash
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv run cedric run --once
```

Run the reproducible 1.0 MVP fault matrix and wall-clock soak gate (five minutes by default):

```bash
uv run python scripts/mvp_acceptance.py
```

The runner writes JSON and Markdown evidence under `var/acceptance/`. See the
[stability and MVP documentation](https://github.com/wunsiang-cheng/cedric/blob/main/docs/STABILITY_AND_MVP.md)
for the requirement ledger, injected failure semantics, and the additional checks required on a
real VM/host installation.

## Troubleshooting

- Run `uv run cedric doctor` first to verify paths, database access, protocol version, and API-key
  presence without exposing the key.
- Run `uv run cedric health` to check startup, identity, memory indexing, database integrity, disk
  capacity, and the mechanical cognitive probe.
- Use `uv run cedric recover` after an API outage or interrupted agent turn; resumable work is kept
  in SQLite.
- If startup identity files are missing, run `uv run cedric init`. It restores only missing packaged
  bootstrap files and does not overwrite an existing identity.
- For Supervisor or rollback failures, inspect the separately persisted host journal and follow the
  [self-modification guide](https://github.com/wunsiang-cheng/cedric/blob/main/docs/SELF_MODIFICATION.md).
- Before sharing logs or diagnostics, inspect and redact credentials, private memory, conversations,
  machine paths, account identifiers, and third-party data yourself.

## Secrets

Application credentials can be loaded from `CEDRIC_` environment variables and an optional local
`.env`. External credentials are stored as references to environment variables or mode-`0600`
files under `var/secrets`; values never enter SQLite, Markdown memory, audit records, or tool output.
`.env`, runtime databases, and secret files are ignored by Git.

## Support and language

This is an independently maintained research project with no support SLA. Use
[GitHub Issues](https://github.com/wunsiang-cheng/cedric/issues) for reproducible bugs and
[GitHub Discussions](https://github.com/wunsiang-cheng/cedric/discussions) for usage questions and
design discussion after those repository features are enabled. Report suspected vulnerabilities
privately to `wunsiangcheng@gmail.com`; do not post secrets or exploit details in a public issue.

Read [CONTRIBUTING.md](https://github.com/wunsiang-cheng/cedric/blob/main/CONTRIBUTING.md) before
submitting a change. Community participation is governed by the
[Code of Conduct](https://github.com/wunsiang-cheng/cedric/blob/main/CODE_OF_CONDUCT.md), and private
security reporting details are in
[SECURITY.md](https://github.com/wunsiang-cheng/cedric/blob/main/SECURITY.md).

English documentation is normative when translations differ. Contributions and community
participation in English, Traditional Chinese, and Simplified Chinese are welcome.

## License

Cedric is licensed under the
[Apache License 2.0](https://github.com/wunsiang-cheng/cedric/blob/main/LICENSE). See
[NOTICE](https://github.com/wunsiang-cheng/cedric/blob/main/NOTICE) and
[THIRD_PARTY_NOTICES.md](https://github.com/wunsiang-cheng/cedric/blob/main/THIRD_PARTY_NOTICES.md)
for attribution and dependency-license information.
