Components¶

pip install sharedcode installs one distribution that contains twenty-one importable packages: a thin sharedcode umbrella and twenty sharedcode_* siblings. They are not a namespace package and are not published separately. The split keeps dependency arrows pointing one way: the shared core imports none of the transports.

How a turn flows¶

  Clients: terminal UI, web UI, Telegram, WhatsApp, IDEs over ACP
      |
      | submit prompts, subscribe to the event stream
      v
  sharedcode_gateway, north side, 127.0.0.1:8100
    - ingress auth and a priority queue that acknowledges input at once
    - fast reads from the SQLite cache, multi-subscriber SSE stream
      |
      v
  sharedcode_gateway, south side ("orchestrator"), 127.0.0.1:8099
    - owns the turn loop: model calls, tools, delegation, telemetry
      |
      | append events
      v
  sharedcode_session
    - one append-only <session_id>.jsonl per session
    - sessions.db: a rebuildable SQLite cache of those ledgers

The gateway and the orchestrator are both served by sharedcode_gateway. sharedcode gateway start launches the orchestrator first, then the gateway, and sharedcode gateway stop stops both.

The package map¶

Entry points and transports¶

Package	What it does	How you reach it
`sharedcode`	Cross-package glue: runs orchestrator, gateway and web UI as one stack.	`sharedcode-serve`, `python -m sharedcode.serve`, `python -m sharedcode`
`sharedcode_tui`	The Textual terminal UI and the one-shot `-p` mode; a generic ACP client.	`sharedcode`
`sharedcode_gateway`	The north gateway and south orchestrator, the `sharedcode` subcommands that manage them, `doctor`, and the Bedrock worker.	`sharedcode gateway ...`, `sharedcode doctor`
`sharedcode_web`	The browser UI: Flask server plus its templates and static assets, which always ship in the wheel.	`sharedcode-web`, `sharedcode web start`, `python -m sharedcode_web` (needs `[web]`)
`sharedcode_telegram`	The standalone Telegram bot service, and the local speech-to-text server.	`sharedcode telegram ...`, `sharedcode-stt` (needs `[stt]`)
`sharedcode_whatsapp`	The linked-device WhatsApp self-chat channel.	`sharedcode whatsapp ...`, `sharedcode-whatsapp`, `python -m sharedcode_whatsapp` (needs `[whatsapp]`)
`sharedcode_realtime`	Bidirectional realtime voice over an OpenAI-Realtime-style WebSocket, backed by a speech-to-text, LLM and text-to-speech cascade. Runs as its own process.	`python -m sharedcode_realtime` (needs `[realtime]`)
`sharedcode_acp`	The Agent Client Protocol wire library: protocol models, JSON-RPC framing, client and server.	Used by the TUI, Telegram and IDE integrations
`sharedcode_ocuclaw`	A bounded compatibility adapter that loads the OcuClaw 1.3.7 npm plugin and maps its gateway protocol onto native sharedcode sessions for the `jarvis` agent. Off unless `SHAREDCODE_OCUCLAW_ENABLED` is `1`.	Node.js and the OcuClaw npm package

Runtime¶

Package	What it does
`sharedcode_core`	The transport-agnostic shared library: configuration and home layout, errors, attachments, access grants, event bus. Imports nothing from the transports.
`sharedcode_agent`	The agent runtime: engines, agent profiles, the turn loop, tools, delegation, compaction.
`sharedcode_orchestrator`	Turn coordination across multi-modal engines, and per-call telemetry (time to first token, tokens per second, cost).
`sharedcode_session`	Session identity, the append-only event logs, reading, writing and indexing them, and titles.
`sharedcode_model`	Model definitions, provider adapters and presets, local GPU provisioning, stream normalisation and output repair, pricing and token counting.
`sharedcode_command`	The slash-command vocabulary: parsing, dispatch, and discovery of file-based commands.
`sharedcode_skill`	Skill discovery and indexing, plus the shipped skills.
`sharedcode_goal`	Goals: registry, lifecycle, budgets and supervision.
`sharedcode_loop`	Durable scheduled loops: interval and cron schedules that re-prompt a session, with run history and a cross-process lease.
`sharedcode_mcp`	The MCP client used by the tool runners, and the bundled MCP servers (memory, web, delegation, YouTube). Memory search lives here too (`sharedcode_mcp.memory`).

Optional integrations¶

Package	What it does	Needs
`sharedcode_vllm`	A local vLLM replica router: health checks, session affinity, capacity admission, failover between replicas and pools, and optional cloud backup when every local option is down.	`[vllm-router]`; see Operations
`sharedcode_shareddata`	A client for the SharedData worker-pool protocol: queue routine, restart, stop and kill commands on remote workers. Importing it has no side effects.	`pymongo` and `lz4`; see Operations

Agents and skills that ship¶

sharedcode gateway status in the Quickstart listed the agents a fresh install mounts: jarvis (the default, which answers or delegates), general, build, plan, explore and shareddata, plus one agent for each supported coding-agent CLI found on the PATH. On the machine used for these pages those were codex, cursor and antigravity; a CLI that is not installed gets no agent. sharedcode agents --list shows which CLIs it knows and which it found. In that run the list was Pi, Claude Code, OpenAI Codex, Cursor, OpenCode, Kimi Code and Hermes Agent. sharedcode agents installs and configures them.

sharedcode skills list shows the skills. A fresh install enables the shipped set: config-setup, delegate-strategy, moa, nodriver-browser, provider-route, research-wiki, sglang-install, shareddata-data, shareddata-dev, shareddata-ops, skill-builder, telegram-render-verify, vast-ai-rent, vastai-vllm, vllm-install and whatsapp. Your own skills, in the AgentSkills format, go in a directory listed in SHAREDCODE_SKILLS_DIRS.