Metadata-Version: 2.5
Name: cedric-agent
Version: 1.3.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; Telegram communication; 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, Telegram, or any other model or service provider.

> [!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 has no production-fitness guarantee. 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. 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.

## What Cedric can do

- Plan multi-step work, inspect 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.
- Communicate through a local TUI or a paired Telegram account.
- Track request provenance, authorization, trust, external identities, resources, and assistance.
- Validate self-modification candidates and submit them to an external Supervisor for
  snapshot-backed deployment, health checking, and rollback.

Desktop perception and general GUI automation are not currently implemented. See the
[roadmap](ROADMAP.md) for current direction.

## Quick start

### Requirements

- Native Linux; Ubuntu 24.04 LTS is the primary tested platform.
- Python 3.12 or 3.13.
- A DeepSeek API key.
- A Telegram bot token for the standard communication channel.

Other Linux distributions are best effort. macOS, Windows, WSL, containers, and non-x86-64
architectures are not currently supported release targets.

### Install from PyPI

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

In an interactive terminal, `cedric init`:

1. initializes private runtime state and applies database migrations;
2. asks for the DeepSeek API key without displaying it;
3. guides creation of a Telegram bot and accepts its token through a hidden prompt;
4. waits for the owner to send the one-time pairing command; and
5. installs and starts a `systemd --user` service so Cedric keeps running after the terminal closes.

The wizard writes secrets to a mode-`0600` `.env` file. It does not replace an existing identity or
contact DeepSeek during setup. Run `cedric setup` to configure it again. For unattended
initialization, use `cedric init --no-wizard`.

Manage the background service with:

```bash
cedric service status
cedric service logs
cedric service restart
cedric service stop
```

Released artifacts, SHA-256 checksums, and a CycloneDX SBOM are available from
[GitHub Releases](https://github.com/wunsiang-cheng/cedric/releases). The same build is published to
[PyPI](https://pypi.org/project/cedric-agent/) with Trusted Publishing attestations.

### 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
```

Prefix the commands below with `uv run` when working from a checkout.

## Using Cedric

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

These commands open the local TUI, submit one direct request, run the persistent scheduler in the
foreground, and recover interrupted work, respectively.

One Cedric instance owns one database. Commands that run the cognitive loop take an exclusive lock
and refuse to start beside another live instance. Give separate instances different
`CEDRIC_DATABASE_PATH` and `CEDRIC_MEMORY_ROOT` values.

### Telegram pairing

The setup wizard is the normal pairing path. To replace or add a pairing later:

```bash
cedric telegram-pair --wait
```

Send the displayed `/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. A Telegram numeric user ID identifies the
account; mutable usernames are never used as identity keys. Unpaired and group messages do not
reach the model.

Pairing authenticates and authorizes the sender to make requests. It does not obligate Cedric to
accept them, and forwarded or quoted text remains untrusted content. See the
[Telegram channel specification](docs/operations/TELEGRAM_CHANNEL.md) for delivery, queueing,
revocation, and failure behavior.

### Memory and subagents

Canonical long-term memory lives under `CEDRIC_MEMORY_ROOT`, which defaults to the private,
Git-ignored `memory/` directory. Markdown holds identity, episodes, knowledge, relationships,
self-observations, and reflections; SQLite provides a rebuildable search index and operational
state.

Subagents have durable conversations, dependencies, priorities, resource claims, retries, and
optional token or cost budgets. Read the [memory](docs/architecture/MEMORY.md) and
[scheduler](docs/architecture/SCHEDULER.md) documentation for the detailed contracts.

### Self-modification and recovery

Cedric can package a clean Git workspace only after its configured validation gates pass. An
independent Supervisor can then snapshot, deploy, health-check, and roll back the candidate outside
Cedric's VM or permission domain.

The Supervisor is a mechanical life-support layer, not a command-approval service. See
[self-modification](docs/architecture/SELF_MODIFICATION.md), the
[Supervisor protocol](deploy/supervisor/PROTOCOL.md), and the
[VM deployment boundary](deploy/vm/README.md).

## Data, network, and secrets

Cedric has no project telemetry, analytics, automatic diagnostic upload, or update check. The model
provider sends requests to `CEDRIC_DEEPSEEK_BASE_URL`; those requests can include identity,
relevant memories, unfinished work, conversation messages, tool definitions, and selected tool
results. Telegram communication uses the configured bot API. The optional Supervisor uses its
configured Unix socket or host-only TCP endpoint.

Cedric's unrestricted tools can contact any service reachable from its Linux environment. Review
provider terms and data handling, isolate the machine, and control the network, accounts, and
credentials available to it.

Credentials may come from `CEDRIC_` environment variables or a local `.env`. External secrets are
stored only as references to environment variables or protected files under `var/secrets`; secret
values must not enter SQLite, Markdown memory, logs, diagnostics, or tool output.

Never commit `.env`, `memory/`, `var/`, databases, conversations, credentials, or generated runtime
state. Before sharing any diagnostic, manually redact private memory, machine paths, account
identifiers, and third-party content.

## Architecture and documentation

```text
Dedicated Linux VM
└── Cedric Runtime
    ├── TUI, CLI, and Telegram channel
    ├── Cognitive loop and model provider
    ├── Shell, file, and process tools
    ├── Durable tasks, subagents, and Markdown memory
    └── Self-modification candidate builder
             │ validated candidate protocol
             ▼
VM host or separate permission domain
└── Supervisor: snapshot, deploy, health check, and rollback
```

Start with the [documentation index](docs/README.md). It links the current protocol, memory,
scheduler, trust, Telegram, release-quality, and deployment contracts. Published changes are in the
[changelog](CHANGELOG.md) and full release notes remain under [`docs/releases/`](docs/releases/).

## Development

```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv run python scripts/license_audit.py
./scripts/secret_scan.sh
uv build
uvx twine check dist/*
```

The extended fault and soak gate is:

```bash
uv run python scripts/mvp_acceptance.py --soak-seconds 300
```

See [release quality](docs/operations/RELEASE_QUALITY.md) for the fault matrix and environment checks.
Contributors should read [CONTRIBUTING.md](CONTRIBUTING.md) and sign every commit under the
Developer Certificate of Origin.

## Support, language, and license

This independently maintained research project has 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 questions and design
discussion. Report suspected vulnerabilities through the process in [SECURITY.md](SECURITY.md), not
a public issue.

English documentation is normative. Contributions and community participation in English,
Traditional Chinese, and Simplified Chinese are welcome. The [Code of Conduct](CODE_OF_CONDUCT.md)
applies to project spaces.

Cedric is licensed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for attribution and dependency-license information.
