SharedCode

Run it now: git clone … && cd sharedcode && ./sharedcode — the launcher creates .venv/, installs dependencies, and starts the TUI. Or pip install sharedcode && sharedcode — the first-run wizard walks you through the LLM endpoint and model choice.

Install

pip install sharedcode

That puts a sharedcode command on your PATH. Run it once with no arguments — the first-run wizard walks you through the LLM endpoint, model, and (optionally) Telegram, then brings the gateway up itself. Three steps and you're in the TUI:

pip install sharedcode → sharedcode → answer the wizard → done.

Optional extras:

Install command	What you get
pip install sharedcode	Lean core — TUI + orchestrator + gateway + MCP client + SQLite storage
pip install sharedcode[full]	Add PDF/DOCX/YouTube/web-extraction tools
pip install sharedcode[web]	Add the browser chat frontend (Flask; waitress on Windows, gunicorn on POSIX)
pip install sharedcode[stt]	Add local Fast Whisper speech-to-text (CPU)

From a clone (for development)

git clone … && cd sharedcode && ./sharedcode — the launcher creates .venv/, runs an editable pip install -e ., and starts the TUI.

Run the gateway, orchestrator and WebUI together

pip install "sharedcode[web]"     # the WebUI lives in the [web] extra
python -m sharedcode.serve        # foreground: Ctrl+C stops the whole stack

serve brings all three components up and prints one line per component:

START orchestrator 8099 pid=1234 http=200
START gateway 8100 pid=1235 http=200
START web 8110 pid=1236 http=200
WebUI http://127.0.0.1:8110  (Ctrl+C stops the stack; --detach keeps it running after this shell exits)

Component	Default address
orchestrator	http://127.0.0.1:8099
gateway	http://127.0.0.1:8100
WebUI	http://127.0.0.1:8110

python -m sharedcode.serve --detach   # background; survives the shell closing
python -m sharedcode.serve status     # one PASS/FAIL line per component
python -m sharedcode.serve stop       # shut the stack down
python -m sharedcode.serve --no-web   # backend roles only (no [web] extra needed)

The same entry point is installed as the sharedcode-serve console script, and python -m sharedcode is an alias. There is deliberately no service supervisor and no restart loop: a component that dies is reported by name, never respawned.

Inside a source checkout, sharedcode.bat / sharedcode-stop.bat / sharedcode-status.bat wrap these same three commands for Windows.

Core Packages

Modular packages under src/ — installed as pip install sharedcode:

Package	Role
sharedcode_session	Storage Engine: Single-file <sid>.jsonl ledger + instant SQLite cache (sessions.db)
sharedcode_orchestrator	Execution Core: Turn loop, multi-modal engine adapters (CLI, ACP, A2A), tool dispatch
sharedcode_a2a	Agent-to-Agent Protocol: Structured a2a/v1 message envelopes (spawn, progress, task_completed)
sharedcode_acp	Agent Client Protocol: JSON-RPC 2.0 IDE server/client (Cursor, Zed, JetBrains)
sharedcode_gateway	Edge Membrane: Auth, Ingress Queue (<5ms ACK), fast REST cache (<2ms), SSE streaming
sharedcode_tui	Terminal TUI: Textual-based interactive terminal interface
sharedcode_web	Browser WebUI: Multi-tab interface (Sessions, Usage, Agent Monitor, Tasks, Loops, Topics, Dev, Goals, Voice, Agent Builder)
sharedcode_realtime	Realtime Voice: WebRTC full-duplex bidirectional audio streaming
sharedcode_telegram	Telegram Bot: Group chat, voice notes, images and documents in, agent files out, remote execution
sharedcode_whatsapp	WhatsApp: Self-chat channel via a linked device — text, voice notes, images, PDF/Markdown/Office documents, agent files out, agent questions
sharedcode_mcp	MCP Servers: Bundled MCP tools (memory, search, filesystem, terminal)

Extras

• [full] — trafilatura (web-fetch), markitdown (PDF/DOCX), yt-dlp + youtube-transcript-api (YouTube), imageio-ffmpeg (voice-note transcode)
• [web] — Flask for the browser chat frontend (waitress on Windows, gunicorn on POSIX)
• [stt] — faster-whisper (CPU-only STT for Telegram voice)
• [bedrock] — boto3/botocore for the native Amazon Bedrock Converse transport. The tested SDK minimum is 1.43.101; older SDKs fail before client construction. Optional: a non-Bedrock install must never need the AWS SDK.
• [whatsapp] — neonize (Go whatsmeow) linked-device transport for sharedcode_whatsapp. Needs the system libmagic1 library.

WhatsApp (self-chat channel)

Talk to your agent from WhatsApp: sharedcode links to your account as a companion device (like WhatsApp Web, shown as "sharedcode" under Linked devices). You write in your own "Message yourself" chat and the agent answers in the same chat, including turns that finish later in the background.

pip install 'sharedcode[whatsapp]'           # plus: apt install libmagic1
sharedcode whatsapp link                     # scan the QR (also saved as ~/.sharedcode/whatsapp/link-qr.png)
sharedcode whatsapp link --phone +5511...    # or get an 8-character pairing code instead
sharedcode whatsapp install-service          # systemd user unit sharedcode-whatsapp.service
sharedcode whatsapp status

In the chat, /new starts a fresh session, /stop stops a turn, /agent <name> switches agents and /status shows the link. Every other /command runs in the agent runtime. Voice notes are transcribed through the stt service, and agent questions or permission prompts are answered by replying with a number.

Files. Send an image (as a photo or as a file) and the agent sees it; send a PDF, Markdown/text or Office document and the agent reads its text (converted with markitdown from the [full] extra; up to max_media_mb, default 16 MB). When the agent links a file it made ([Report](</abs/path/report.pdf>), the same contract the web UI uses), the file follows its answer: PNG/JPEG/WebP as a photo, anything else as a document. Agents can also queue files with the whatsapp skill: send --file </abs/path/report.pdf> [text]. Telegram does the same: images and documents in, the agent's linked files out.

• Privacy. The service only reads and writes your self-chat. Other chats are ignored and never logged.
• Credentials. ~/.sharedcode/whatsapp/neonize.sqlite3 is a live WhatsApp login, stored with permissions 0600. sharedcode whatsapp logout revokes it.
• Terms of service. This is an unofficial client, the same approach as WhatsApp Web automation tools. Keep it to your own self-chat. Settings live in ~/.sharedcode/whatsapp/config.json (design: docs/2026-09-24-whatsapp-channel-design.md).

Amazon Bedrock (native Converse)

sharedcode talks to Bedrock through the native Converse / ConverseStream API (not the OpenAI-compatible endpoint). Install the optional SDK:

pip install 'sharedcode[bedrock]'          # release
pip install -e '.[bedrock]'             # editable clone

With AWS credentials already in the service environment, native agents discover Bedrock models automatically; no provider entry or setup wizard is required. Discovery uses AWS_REGION, then AWS_DEFAULT_REGION, then the AWS profile's region, and defaults to sa-east-1 when none is set. Environment IAM keys (including temporary session tokens), Bedrock bearer tokens, explicit AWS profiles, shared credentials, and container/web-identity credentials are supported. It does not probe EC2 instance metadata just to populate the picker.

At model load, sharedcode lists active streaming text foundation models and inference profiles. Results are cached for five minutes within each process; the model picker's refresh bypasses that cache. Catalogue reads make no inference calls. Removing credentials removes automatic rows on the next config reload. Other engines and the selected default model are unchanged. AWS model access and Converse/tool support still depend on the model and account.

For custom aliases, credentials or context limits, add a model row with api: "bedrock-converse" (the explicit marker that selects the transport) or run sharedcode configure and choose b. Amazon Bedrock. Example row (illustrative — no credentials):

{
  "alias": "bedrock-primary",
  "api": "bedrock-converse",
  "backend": "bedrock",
  "provider": "bedrock",
  "baseUrl": "bedrock://us-east-1",
  "region": "us-east-1",
  "id": "<operators-supply-a-real-foundation-id-or-inference-profile-arn>",
  "auth": "aws-iam",
  "contextWindow": 200000,
  "maxTokens": 8192
}

• Manual rows take precedence over discovered rows for the same region/model. AWS catalogue responses omit context limits, so automatic rows use a conservative 4,096-token context budget and 1,024-token output limit. Set a manual row to use the model's verified larger limits. Discovery never saves credentials in rows.
• baseUrl is a bedrock://REGION display URL only; the SDK derives the real HTTPS endpoint from region. A bedrock:// URL is never parsed as HTTP.

Authentication

Both modes are supported; there is no silent fallback between them.

• auth: "aws-iam" (recommended): the normal boto3 chain — IAM role, instance/container credentials, shared config or AWS_PROFILE (profile on the row overrides AWS_PROFILE in that child worker only). AWS recommends short-lived role credentials over long-term keys.
• auth: "bedrock-api-key": a Bedrock bearer token, resolved per-agent first (secrets.env / api_keys) then inherited environment, under apiKeyEnv (default AWS_BEARER_TOKEN_BEDROCK). An explicit empty value means "no key" and blocks the environment fallback. The value is set only in the child worker's environment at request time and is never written to config.json, sessions, logs or the request JSON.

Permissions and pricing

• Least privilege: bedrock:InvokeModelWithResponseStream for normal turns, plus bedrock:InvokeModel if a one-shot path (vision transcription, compaction, distillation) is used.
• Automatic discovery also needs bedrock:ListFoundationModels and bedrock:ListInferenceProfiles. A profile-list denial still allows direct foundation models; discovery failure leaves manual rows available.
• Enable model access and any cross-region inference profile in the AWS console for the target account/region.
• Costs come from the metrics the worker reports (provider bedrock) plus the operator's ~/.sharedcode/pricing.json. Bedrock model/region prices vary; set exact model or alias overrides from the AWS price sheet rather than a blanket rate.

Compatibility and limitations

• Streaming text, client-side tool calls/results and image blocks are supported where the chosen model supports them.
• Extended reasoning is off in v1: no additionalModelRequestFields thinking, the picker//effort marks depth unsupported, and signed reasoningContent during a tool turn fails closed rather than replaying an unsigned assistant turn.
• sharedcode doctor --health checks a Bedrock route offline (region/auth and credential presence). sharedcode doctor --bedrock-smoke makes an explicit, opt-in, billable live call; it is never run by --health.

Sampling configuration

Sampling is minimal by default: no temperature, top_p, top_k, min_p, repetition_penalty, presence_penalty, frequency_penalty or seed is sent unless configured or strictly required by the provider (currently kimi-k3 requires temperature 1.0). Providers apply their own defaults. Token budgets, thinking settings, tools and local loop-protection extras retain their existing behavior.

Add these blocks to the global config, merging with your existing settings:

{
  "sampling": {"temperature": 0.3, "top_p": 0.9},
  "side_sampling": {
    "title": {"temperature": 0.5},
    "distill": {"temperature": 0.2, "presence_penalty": 1.0},
    "compaction": {"temperature": 0.1}
  }
}

Precedence, lowest to highest: legacy top-level temperature → sampling for main turns, or side_sampling[purpose] for side calls → the selected models[] row's sampling → per-turn sampling → provider-required values. Side calls do not inherit global sampling. A higher-layer null removes an inherited value; for example, "sampling": {"temperature": null} on one model row opts that row out of a global temperature. Zero is an explicit value. Unknown keys, booleans and invalid numeric values are ignored.

The side-call purposes are distill, compaction, title, teacher, goal_review, command_validator, vision, memory_synth, intake and x_search. Bedrock only sends supported temperature/top_p values; the Codex Responses transport strips unsupported sampling fields. Explicit hosted-row settings (including top_k) are sent, so choose fields your provider supports.

To opt a Gemma deployment into its former profile, add this property to that existing model row:

{
  "sampling": {
    "temperature": 0.4,
    "top_p": 0.9,
    "top_k": 20,
    "min_p": 0.0,
    "frequency_penalty": 0.4,
    "presence_penalty": 0.3,
    "repetition_penalty": 1.05
  }
}

For local Qwen deployments, the built-in DRY sampler and repetition detector are retained automatically. These existing extras remain unchanged; they are not new configurable sampling keys:

{
  "dry_multiplier": 0.8,
  "dry_base": 1.75,
  "dry_allowed_length": 4,
  "dry_sequence_breakers": ["\n", ".", "!", "?", ":", "—", "```"],
  "repetition_detection": {
    "max_pattern_size": 80,
    "min_pattern_size": 4,
    "min_count": 5
  }
}

Optional Qwen tuning belongs in its model row's sampling, for example {"presence_penalty": 1.0, "min_p": 0.05} when supported by the deployment. This replaces the old SHAREDCODE_AUTO_PRESENCE_PENALTY, SHAREDCODE_AUTO_MIN_P and SHAREDCODE_DISTILL_PRESENCE_PENALTY tuning knobs (use side_sampling.distill.presence_penalty for the latter).

The /temperature command, Agent Builder and setup wizard continue writing the legacy top-level temperature alias; clear it with null to use upstream defaults. A value in sampling.temperature takes precedence over that alias. Raw realtime chat separately accepts realtime.temperature as a number or null, and omits it by default.

Deploy note: remove an existing live top-level default temperature separately when adopting minimal defaults. This code change does not edit live config.

Memory index maintenance

Normal maintenance is automatic: remember indexes immediately after a successful write, memory search lazily indexes detected drift before querying, and the gateway heartbeat asks the persistent memory service to reindex only when needed. The Markdown files remain the source of truth; memory.db is a rebuildable search index.

Use the operator CLI when checking or repairing an agent explicitly:

# Show file/chunk/vector counts, index scope, and whether drift is pending.
sharedcode memory status --agent codex

# Safe incremental pass: changed files and missing vectors only.
sharedcode memory index --agent codex

# Rebuild chunks/FTS/vectors, retaining reusable embedding-cache rows.
sharedcode memory index --agent codex --force

# Also discard the cache and call the configured embedding provider again.
sharedcode memory index --agent codex --reembed

Start with the incremental command. --force rebuilds only the derived index; it does not delete the Markdown memories. --reembed is the expensive recovery path for a changed model or poisoned cache and requires a working embedding provider.

---

sharedcode is the cypherpunk version of inference.

It exists to empower the user to have total control over their data and ideas, without the hassle of endless configuration or requiring deep open-source model knowledge just to get useful work done.

This project starts from a hard truth: the AI industry is underinvesting in infrastructure and degrading model quality to keep up with demand. Decisions like blocking OpenClaw from the Max plan and forcing heavy API costs on users reinforce the view that AI companies are sucking people and companies' ideas like the Matrix uses human crops for creativity and for studying human thought processes.

That is the opposite of sovereignty.

The current model asks users and companies to pour their private context, internal reasoning, product ideas, and operational intelligence into centralized AI systems they do not control. In return, they get rising costs, shrinking access, degraded quality under load, and dependence on infrastructure decisions made by someone else.

And the risk is not theoretical.

The imminent Taiwan conflict will create heavy shocks to current business. Any company relying on AI will have no option but to pay the price of neoclouds if supply chains seize up and centralized inference tightens further. Businesses that chose not to build on-prem infrastructure, or at least retain the option, will be trapped into paying whatever the market demands.

sharedcode is the answer to that trap.

sharedcode is a custom-built agent system that adapts to the available inference capacity by creating tailored agents for each hardware profile, from a modest RTX 3060 to RTX 3090, RTX 4090, RTX 5090, A6000-class workstations, and up to advanced rented neocloud GPUs on platforms like Vast.ai.

Instead of forcing every task through one oversized, expensive, centralized stack, sharedcode rightsizes inference to the real job:

• small agents on cheap local hardware
• stronger agents on workstations
• burst agents on rented neocloud GPUs
• flexible routing based on actual available capacity
• model selection based on task value, latency, and hardware envelope
• agent behavior shaped around the realities of the machine it runs on

Agents can be spawned in seconds using the right-sizing capacity for each task, reducing the cost of AI while increasing resilience, performance, and control.

---

Why sharedcode exists

Most AI products are built around a hidden assumption: the user should adapt to the vendor.

The vendor chooses the models.
The vendor chooses the pricing.
The vendor chooses when quality gets degraded.
The vendor chooses which products get blocked.
The vendor chooses which workloads are too expensive.
The vendor chooses whether your use case is welcome.

sharedcode rejects that model.

The intelligence layer of a company is too important to outsource blindly. Your prompts are not just prompts. They are product direction, customer knowledge, internal process, strategy, failure modes, experimentation, and judgment in raw form. If your AI stack is not sovereign, your cognition stack is not sovereign.

---

Core Principles

• Own the data: Single-file session logs stored locally on your machine.
• Own the ideas: No outbound telemetry leaks.
• Own the inference path: Seamless fallback between local vLLM, private workstations, and cloud models.
• Instant Responsiveness: < 5ms submission ACKs on all inputs, < 2ms UI cache reads from SQLite.
• Zero Configuration Sprawl: Single .jsonl session files, extensible JSON tool containers, zero sidecars.
• Clean Protocol Boundaries: ACP for IDE control (North-South), A2A for multi-agent swarms (East-West).
• Cancel Scopes You Can Reason About: Abort one turn and only that turn dies; abort a subagent and only that subagent terminates.

---

Architecture Overview

The canonical system architecture is documented in detail in the Technical Specifications.

Runtime: sharedcode gateway start brings up the south orchestrator (:8099) then the north gateway (:8100). sharedcode gateway stop stops both.

flowchart TD
    Clients["Multi-Interface Clients<br/><b>WebUI • Telegram • TUI • IDE (via ACP)</b>"]
    
    Gateway["sharedcode_gateway (North)<br/>• Ingress Auth & Multi-Source Queue (<5ms ACK)<br/>• Fast SQLite Cache Server (<2ms)<br/>• Multi-Subscriber SSE Streamer"]
    
    Orchestrator["sharedcode_orchestrator (South)<br/>• Turn & Round State Machine<br/>• Multi-Modal Engine Adapters (CLI, ACP, A2A)<br/>• Tool Dispatch & AI Model Telemetry"]
    
    Storage["sharedcode_session (Storage Engine)<br/>• Single-File Ledger (<session_id>.jsonl)<br/>• Instant SQLite Cache (sessions.db)"]
    
    Clients -->|"1. Submit Prompts & Subscribe Stream"| Gateway
    Gateway -->|"2. Priority Ingress Queue (FIFO)"| Orchestrator
    Orchestrator -->|"3. Append Events, Row Markers, & Project Cache"| Storage
    Gateway -.->|"4. Fast REST Reads & SSE Tails"| Storage

1. Storage Tier (sharedcode_session)

• Single-File Ledger (<session_id>.jsonl): Exactly 1 immutable, append-only file per session. Zero loose sidecars.
• Materialized SQLite Cache (sessions.db): Atomic single-row reads for instant UI loading (< 2ms).
• Extensible JSON Containers (tools_state_json): Dynamic tool state updates (Kanban, Todos, Canvas) via json_set() with zero database schema migrations.
• Row Range Markers: Exact [start_row_idx, end_row_idx] recorded for every turn and every AI model call.

2. Multi-Modal Execution (sharedcode_orchestrator)

• CLI Adapter: Invokes subprocess CLI tools (agy, claude, codex) and wraps them into standard message envelopes.
• ACP Adapter: Interacts with external IDEs (Cursor, Zed) via JSON-RPC 2.0.
• A2A Adapter: Coordinates autonomous subagents via native a2a/v1 message envelopes.
• AI Telemetry Collector: Captures TTFT, generation speed (tokens/sec), routing overhead, token volume, and cost ($) into the ai_generations table.

3. Edge Membrane (sharedcode_gateway)

• Session Ingress Queue: Immediate < 5ms submission ACK for WebUI, Telegram, TUI, A2A subagents, and schedulers.
• Priority Intake: Priority 0 (Control) $\rightarrow$ Priority 1 (Subagent Returns) $\rightarrow$ Priority 2 (User Prompts) $\rightarrow$ Priority 3 (System Nudges).
• Row-Indexed SSE Streaming: Clients seek directly to any row (GET /stream?from=<row_idx>) with zero token loss and zero duplicate frames.

---

Documentation Roadmap

The full system documentation is organized into 10 domain directories matching the WebUI tabs:

• Requirements (WHAT): Product specifications, functional requirements (FR-01 to FR-11), and quality SLAs.
• Technical Specifications (HOW): Authoritative architecture contracts, Mermaid diagrams, event wire schemas, and SQLite table definitions.
• Implementation Plans (WHEN): Phase-by-phase engineering execution roadmaps and automated test verification suites.

Project homepage and maintainer contact are defined together in the [project] section of pyproject.toml and included in installed package metadata.