Claude Code Companion
C3 is a local intelligence layer for Claude Code — adding token-efficient code search, structural file reading, persistent memory, session management, and multi-model delegation directly into your AI coding workflow.
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.
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.
Claude reads full files, loses context on /clear, has no persistent memory, and burns tokens on repetitive re-reads of large files.
c3_* tool calls. The server stores data in a hidden .c3/ directory at the project root.
| 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 |
.c3/ directory on disk.
| Tool | Category | One-liner |
|---|---|---|
c3_search |
Search | TF-IDF / semantic / file discovery across the codebase |
c3_read |
Read | Targeted symbol or line-range reads (not whole files) |
c3_compress |
Read | Structural file map — 40–70% token savings |
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 |
Common CLI Commands
c3 init
Initialize C3 for a project (.c3/, index, CLAUDE.md)
c3 install-mcp claude
Wire C3 MCP server into Claude Code
c3 install-mcp vscode
Wire C3 MCP server into VS Code Copilot
c3 install-mcp codex
Wire C3 MCP server into Codex
c3 benchmark
Run local token efficiency benchmark
c3 hub
Launch the Project Hub web dashboard
c3 ui
Launch the session web UI
c3 permissions readonly
Apply read-only permission tier
c3 terse [dismiss|later|reset|status]
Manage the terse-advisor auto-nudge (silence, snooze 24h, or reset)
Mandatory Workflow (7 Steps)
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_compress(mode='map') + c3_read(symbols=…)
Map then surgically read — never start with native Read
4. c3_edit(file, old, new, summary)
Atomic read-patch-write-log — never use native Edit
5. c3_filter(text=…)
Filter terminal output >10 lines or log files
6. c3_validate(file_path)
Syntax-check after every edit
7. c3_session(action='log')
Log decisions; snapshot before /clear