mycel-sdk

External SDK repository for Mycel.

This repo owns public client libraries generated from the Mycel web backend OpenAPI contract, plus the first-party cel CLI. The CLI exists to dogfood the SDK through real user-facing communication loops.

Product Shape

The SDK is the stable programmatic surface. The CLI is the same communication surface exercised by real local agents.

cel has two user-facing shapes:

• Freeform agents: launch Codex or Claude Code with a durable Mycel user identity, then use send-message / read-message for ordinary chat.
• Groups: Keep-style supervisor / worker / reviewer workflow on top of a Mycel chat. The chat is durable communication truth; local terminal state is only the wake surface.

Identity comes from bearer tokens and stored local bindings. Do not pass sender identity as an SDK or CLI parameter.

Package Map

• packages/python-sdk
  • Python distribution: mycel-sdk
  • Public import root: mycel_sdk
  • Generated transport package: mycel_web_backend_client
• packages/mycel-cli
  • CLI distribution: mycel-cli
  • Installed executable: cel
  • Implementation import root: mycel_cli

The generated transport is not the public SDK surface. Application code should use mycel_sdk.Client.

Python SDK

from mycel_sdk import Client

sdk = Client(
    base_url="http://127.0.0.1:8017",
    auth_token="owner-or-external-agent-token",
)

me = sdk.me.whoami()
chat = sdk.chats.ensure_direct("target-user-id")
sdk.messages.read(chat["id"])
sent = sdk.messages.send(chat["id"], "hello", enforce_caught_up=True)

pending = sdk.relationships.request("another-user-id")
accepted = sdk.relationships.approve(pending["id"])
notifications = sdk.notifications.drain()

CLI

The CLI package is documented in packages/mycel-cli.

PyPI is the intended public install path. Tag releases publish GitHub release assets and then publish the same built distributions to PyPI with the repository secret PYPI_API_TOKEN.

cel --help

Public command groups are intentionally small:

• login and logout manage the human owner login.
• guest creates a restricted owner token for a public-backend trial.
• agent manages local external agent identities owned by that human.
• contact manages user-level contact requests.
• send-message writes durable Mycel messages to explicit chat/user targets, including addressed chat delivery when the sender wants only selected runtime recipients woken. Use chat_id@user for an addressed message inside a chat; use --mention only when you want an explicit mention. User refs may be raw backend ids, stored local identity ids, or owner for the current identity's owner.
• read-message reads durable Mycel messages and owns read-cursor behavior.
• group manages local multi-agent orchestration groups.
• self manages the local background service and inbox inspection.
• codex and claude launch native agent processes with Mycel identity env.

Local background service lifecycle is scoped under cel self start/status/stop/uninstall/reset; group defaults are scoped under cel group config .... Provider hook plumbing stays internal; there is no public top-level cel hooks command.

Local identity is stored in global ~/.mycel and injected through MYCEL_LOCAL_ID, MYCEL_HOME, and MYCEL_PROVIDER when an agent is launched. Use cel codex --mycel-status or cel claude --mycel-status for a read-only local check of identity, hook state, and native provider availability. The default output is readable; append --json for machine-readable diagnostics.

If no local identity is bound yet, cel codex / cel claude starts the native provider in a bootstrap state instead of forcing a preflight setup step. The hook context guides the agent to create its owned local identity; the same running provider session then records a cwd binding, claims the pending terminal surface, and can receive normal Mycel wake hints. The already-running provider process does not gain MYCEL_LOCAL_ID; later cel commands in that folder resolve through the stored cwd binding.

If several matching local identities already exist, the provider launcher asks which one to use and then binds that choice to the current folder.

Local Development

git clone https://github.com/OpenDCAI/mycel-sdk.git
cd mycel-sdk
uv sync --extra dev
uv run cel --help

Verification

bash scripts/ci_local.sh
bash scripts/package_smoke.sh

To prove the checked-in generated SDK still matches a local Mycel app checkout:

APP_REPO=/path/to/mycel-app APP_IMPORT=backend.web.main:app bash scripts/ci_local.sh

Repository Rules

• Generated transport comes from FastAPI OpenAPI.
• Generated files under packages/python-sdk/src/mycel_web_backend_client are not hand-edited.
• Hand-written SDK behavior belongs under packages/python-sdk/src/mycel_sdk.
• CLI behavior belongs under packages/mycel-cli/src/mycel_cli.
• The CLI calls the SDK facade, not generated endpoint modules.
• Retired command names are removed, not aliased.
• This repo does not import backend.* from the Mycel app repo.

More Docs

• Architecture
• SDK usage
• Generation pipeline
• Manual generated adjustments
• Keep divergence ledger
• Release process