Documentation
Claude Code Companion
C3 is a local MCP server that adds token-efficient code search, structural file reading, persistent memory, session management, and multi-model delegation to Claude Code — and, natively, to Codex, Grok Build, VS Code Copilot, Cursor, and Antigravity.
💡
What is C3?
C3 wraps Claude Code with a local MCP server that provides code intelligence tools unavailable in the base product. Every tool call is optimized to minimize token usage — the primary cost driver in long coding sessions.
C3 provides
TF-IDF + semantic code search, structural file compression (40–70% token savings), persistent cross-session memory, session snapshots, multi-model delegation, edit ledger, and agent workflows.
Without C3
Claude reads full files, loses context on /clear, has no persistent memory, and burns tokens on repetitive re-reads of large files.
How it works
C3 runs as an MCP (Model Context Protocol) server. Claude Code connects to it via stdio. All C3 tools are available inside Claude Code sessions as
c3_* tool calls. The server stores data in a hidden .c3/ directory at the project root.
🏗️
Architecture
| Component | Location | Purpose |
|---|---|---|
mcp_server.py |
cli/ |
FastMCP server — exposes all c3_* tools to Claude |
c3.py |
cli/ |
CLI entry point — c3 init, c3 install-mcp, benchmarks |
services/ |
project root | All business logic: memory, compressor, indexer, session, agents… |
hub_server.py |
cli/ |
Flask REST server for the web UI (Hub) |
.c3/ |
project root | Data directory: index, sessions, memory facts, edit ledger |
| Hooks | cli/hook_*.py |
PreToolUse / PostToolUse hooks enforcing c3 discipline |
MCP vs REST
The MCP server and Flask REST server run as separate processes. They share state only through the
.c3/ directory on disk.
🗂️
Tools at a Glance
| Tool | Category | One-liner |
|---|---|---|
c3_search |
Search | TF-IDF / semantic / file discovery across the codebase |
c3_read |
Read | No symbols/lines: structural file (or directory) map. With symbols/lines: exact source. c3_compress did the map role before v2.124.0 and is gone from the MCP surface |
c3_edit |
Write | Read + patch + write + log in one atomic step |
c3_validate |
Write | Syntax-check files after edits |
c3_filter |
Utility | Extract signal from noisy terminal output / log files |
c3_session |
Session | Snapshot, restore, log decisions, compact context |
c3_memory |
Memory | Persistent facts across sessions (add / recall / query…) |
c3_status |
Status | Budget, health, notifications, session overview |
c3_delegate |
AI | Offload tasks to Ollama / Codex / Gemini |
c3_agent |
AI | Multi-step compound workflows (review, investigate…) |
c3_edits |
Ledger | Edit ledger: history, versions, audit trail |
c3_impact |
Analysis | Blast-radius check before editing shared symbols |
c3_shell |
Execute | Structured shell exec — tests, git, build (auto-filtered) |
c3_shell_job |
Execute | Detached long-running shell command — start, poll, tail, cancel |
c3_ci |
Execute | Run this repo's real GitHub Actions workflows locally instead of pushing to find out |
c3_locks |
Collab | Agent leases — who is editing which file, so two agents don't collide |
c3_override |
Access | Request, grant, and consult one-time exceptions to a blocked call |
c3_jira |
PM | Jira Cloud / Data Center: search, create, transition, link issues and sprints |
c3_credentials |
Vault | Named secret vault — inject by name at the subprocess boundary, never reveal a value |
c3_task |
PM | Durable tasks, milestones, and decision notes per project |
c3_artifacts |
Config | Agent-config tracking: history, diff & restore for CLAUDE.md, settings, MCP configs, skills |
c3_bitbucket |
SCM | Bitbucket Data Center: PRs, branches, builds, repo admin |
c3_project |
Multi-project | Discover & operate on other c3-installed projects |
⚡
Quick Reference
Common CLI Commands
c3 init
Initialize C3 for a project (.c3/, index, CLAUDE.md/AGENTS.md)
c3 install-mcp <claude|vscode|cursor|codex|antigravity|grok>
Wire the C3 MCP server into one host — run once per host you use
c3 doctor
Inspect native Codex or Grok Build integration, no model call
c3 upgrade [--check]
Upgrade C3 to the latest PyPI release, or just check for one
c3 map {status|ensure|refresh}
Inspect or rebuild the live repo map at .c3/MAP.md
c3 hub
Launch the Project Hub web dashboard (localhost:3330)
c3 ui
Launch the per-project session web UI (localhost:3333)
c3 oracle serve [--install]
Run (or register at login) the Oracle dashboard + Discovery API
c3 permissions <read-only|c3-strict|standard|permissive>
Apply a Claude Code permission tier
c3 sub <list|tree|link|inspect>
Manage linked sub-projects (nested or elsewhere on disk)
c3 ci <inspect|run|failures>
Run this repo's real GitHub Actions workflows locally
c3 creds <set|list|get>
Named secret vault — store once, inject by name
c3 bitbucket login / c3 jira login
Connect self-hosted Bitbucket or Jira, token in the OS keyring
c3 access list
Show Access Guard deny/read-only/confirm rules
c3 locks list
See who holds which file lease, release a stuck one
c3 terse [dismiss|later|reset|status]
Manage the terse-advisor auto-nudge (silence, snooze 24h, or reset)
Mandatory Workflow
The core order, enforced by hooks in Claude Code. Specialized steps for CI, Bitbucket, Jira, credentials, cross-project work, masked paths, confirm holds and agent-config sit on top of these — see the full guide.
1. c3_memory(action='recall')
Recall relevant facts before any multi-step task
2. c3_search(action='code|files|semantic')
Discover files / content — never start with Grep/Glob
3. c3_read(file_path) + c3_read(symbols=…)
Map (file or directory) then surgically read — never start with native Read
4. c3_impact(target=…)
Blast-radius check before editing a shared symbol
5. c3_edit(file, old, new, summary)
Atomic read-patch-write-log — never use native Edit
6. c3_filter(text=…)
Filter terminal output >10 lines or log files
6.5. c3_shell(cmd, cwd, timeout)
Structured shell exec for tests, git, build
7. c3_validate(file_path)
Syntax/type-check after every edit
8. c3_session(action='log'|'note'|'stale')
Log decisions, leave a note before stopping, snapshot before /clear
9. c3_delegate(task, tier='small')
Offload bounded work one tier down; c3_agent for multi-model pipelines
→ Full workflow guide with every step, examples and anti-patterns