Code Companion

Recent Updates

Installation

cd code-context-control
pip install .

# Initialize in your project
c3 init /path/to/your/project

Platform installers handle dependencies and PATH setup automatically:

• Windows: install.bat
• Linux/macOS: install.sh

Quick Start

The recommended way to use C3 is as an MCP server — your IDE calls C3 tools directly with no manual piping.

Cross-IDE Setup

C3 works with any MCP-capable IDE. The install-mcp command auto-detects your IDE and generates the correct config format.

Supported IDEs

IDE-specific Installation

# Guided setup (recommended)
python cli/c3.py init /path/to/project

# Non-interactive setup with local Git + direct MCP
python cli/c3.py init /path/to/project --force --git --ide codex --mcp-mode direct

# MCP-only setup
python cli/c3.py install-mcp /path/to/project

# Explicit direct/proxy mode
python cli/c3.py install-mcp /path/to/project --mcp-mode direct
python cli/c3.py install-mcp /path/to/project --mcp-mode proxy

# Explicit IDE selection
python cli/c3.py install-mcp /path/to/project --ide vscode
python cli/c3.py install-mcp /path/to/project --ide cursor
python cli/c3.py install-mcp /path/to/project --ide claude
python cli/c3.py install-mcp /path/to/project --ide codex
python cli/c3.py install-mcp /path/to/project --ide gemini
python cli/c3.py install-mcp /path/to/project --ide antigravity

# IDE shorthand when already inside the project directory
python cli/c3.py install-mcp claude
python cli/c3.py install-mcp codex
python cli/c3.py install-mcp . gemini

--git runs a local-only git init. It does not create remotes or connect to GitHub, GitLab, or any other hosted service.

VS Code Copilot — install-mcp --ide vscode (and c3 init --ide vscode) generate two additional enforcement files:

• .github/copilot-instructions.md — workspace instructions auto-injected by Copilot into every chat. Written with REQUIRED/MANDATORY/NEVER language and a 4-step C3 session checklist. Only created if absent; existing customizations are preserved.
• .vscode/settings.json — pins both copilot-instructions.md and CLAUDE.md as instruction context for github.copilot.chat.codeGeneration.instructions, reviewSelection.instructions, and testGeneration.instructions. Merged with existing settings.

OpenAI Codex — install-mcp --ide codex (and c3 init --ide codex) write a TOML config and enforce Codex instructions for C3 usage:

• .codex/config.toml — project-scoped Codex MCP config in TOML format with a [mcp_servers.c3] section. C3 writes command, args, and enabled = true so the server is active immediately. The global equivalent is ~/.codex/config.toml. Auto-detected when a .codex/ directory or .codex/config.toml already exists.
• AGENTS.md — Codex reads this file as its instructions context (equivalent to CLAUDE.md for Claude Code). C3 enforces the mandatory workflow: if required C3 markers are missing, it updates AGENTS.md and preserves prior content under an Existing Project Instructions section.
• Global conflict warning — if ~/.codex/config.toml contains [mcp_servers.c3] enabled = false, C3 warns because this commonly makes C3 appear disabled even when project config is correct.

Gemini CLI — install-mcp --ide gemini (and c3 init --ide gemini) write a project-scoped JSON config and a GEMINI.md instructions file:

• .gemini/settings.json — project-scoped MCP config under the mcpServers key. Gemini CLI reads both this file and ~/.gemini/settings.json (user-global). Merged with existing settings. Auto-detected when a .gemini/ directory or .gemini/settings.json already exists.
• GEMINI.md — Gemini CLI reads this file as project context (loaded from the project root and parent directories). Generated with REQUIRED/MANDATORY/NEVER language and the 7-step C3 session protocol. Only created if absent.

Google Antigravity — install-mcp --ide antigravity writes the MCP config to the user-global Antigravity config and a project-local GEMINI.md:

• ~/.gemini/antigravity/mcp_config.json — user-global Antigravity MCP config under the mcpServers key. This is the file managed by Antigravity's Manage MCPs UI. Merged with existing config. Each project still passes --project to the MCP server so C3 indexes the correct directory.
• GEMINI.md — Antigravity and Gemini CLI both read GEMINI.md files from the project root. Same content as Gemini CLI profile. Only created if absent.
• Auto-detected when ~/.gemini/antigravity/ directory already exists alongside a .gemini/ project directory.

Graceful Degradation

All core C3 tools (search, compress, file_map, memory, sessions) work identically in every IDE. Claude-specific features degrade gracefully:

• Transcript search — returns a helpful message suggesting c3_memory(action='recall') or c3_memory(action='query') as alternatives
• Hooks — only installed for Claude Code; VS Code, Cursor, and Codex use hard-language workflow instructions in their instructions file instead
• Instructions file — c3_claudemd_generate writes to the IDE-appropriate file (CLAUDE.md, copilot-instructions.md, .cursorrules, AGENTS.md, or GEMINI.md). All IDEs use MANDATORY/NEVER language — the hook-enforcement note is omitted for non-hook IDEs
• Snapshot/Restore — works in all IDEs for saving and restoring working context

MCP Tools Reference

C3 exposes 9 MCP tools. All core tools work without Ollama; delegate requires it.

Discovery & Compression

Session & Memory

Status & Delegation

Background Agents

C3 runs 9 autonomous daemon threads that perform periodic analysis and surface findings via a notification queue. Notifications are automatically prepended to the next MCP tool response so Claude sees them naturally. Each agent supports optional AI enhancement via local Ollama models — when AI is unavailable or disabled, agents fall back to heuristic logic.

{"agents": {"IndexStaleness": {"enabled": true, "interval": 90, "use_ai": true}, "MemoryPruner": {"enabled": false}}}

Hybrid Intelligence

v2.3 adds three tiers of local intelligence: output filtering, query routing, and semantic long-term memory. Each tier can be enabled/disabled independently via feature flags.

MCP Proxy Layer

The proxy is now an optional advanced mode. The recommended default is direct mode, which points the IDE straight at mcp_server.py. Use proxy mode only if you explicitly want dynamic tool filtering.

IDE <--stdio--> mcp_proxy.py <--subprocess stdio--> mcp_server.py

File Memory System

File Memory maintains a persistent structural index of source files — classes, functions, imports with exact line ranges — so Claude can do targeted Read calls with offset/limit instead of reading entire files.

Example Map Output

# services/agents.py (933 lines, python)
Background agent system with periodic check loop and AI enhancement.

  9-9       import json
  19-102    class BackgroundAgent
            Base class for background analysis agents.
            38-41   ai_available(self)
            42-51   _ai_generate(self, prompt, system, max_tokens)
            52-58   start(self)
            59-64   stop(self)
  103-152   class IndexStalenessAgent
            115-152 check(self)
  ...

PostToolUse Hooks Claude Code only

C3 registers two PostToolUse hooks in .claude/settings.local.json that run after Claude executes certain tools. These hooks are only installed for Claude Code — other IDEs rely on the workflow instructions in their instructions file instead.

Automatic Behavior

Compact Response Format

All MCP tool responses use a terse [tag:value] format instead of markdown prose, reducing response overhead by ~35%. Examples:

[search:auth middleware] 3 results, 1200tok
--- services/auth.py:L10-45 verify_token (function,180tok)
...code...

[stats] files:18 chunks:142 tokens:24.5k | symbols:89 index:38KB facts:12 calls:7

[logged:decision]
[nudge:save_facts|calls:25|facts:0]

[remembered:a1b2c3] total:13
[recall:auth] 3 facts
[architecture] Auth uses JWT in localStorage
[convention] All middleware in services/middleware/

[snapshot:20260228_143012] 167tok captured
[restore:20260228_143012] task:Fix auth flow d:3 f:5

[transcript:auth middleware] 3r,890tok
--- abc123:t7 [2026-02-27] score:4.2
...turn text...

[extract:.log] 8500tok->320tok (96% saved)
[log] 2400 lines | ERROR:12 | WARN:45

Claude parses these tags natively — no information is lost, but each response uses fewer tokens in the context window.

Token counting

C3 uses tiktoken (cl100k_base encoding) for accurate token counts. Falls back to a heuristic estimator if tiktoken is unavailable.

Code indexing

The indexer scans project files, splits them into structural chunks (functions, classes, blocks), and builds a TF-IDF index. This lets c3_search find relevant code without sending the entire codebase to Claude.

Supported file types (80+):

Skipped directories: node_modules .git __pycache__ .c3 venv dist build .next .cache

File watching

The watcher runs on a background thread and tracks file creates, modifications, deletions, and moves. When enough changes accumulate, the indexer rebuilds the index automatically (or run c3 index manually).

Web Dashboard

c3 ui /path/to/your/project                  # Opens full UI at http://localhost:3333/
c3 ui /path/to/your/project --nano           # Opens nano mission-control UI at /nano
c3 ui /path/to/your/project --port 8080      # Custom port
c3 ui /path/to/your/project --no-browser     # Don't auto-open browser
c3 ui /path/to/your/project --silent         # Hide API request logs in terminal

The dashboard provides a visual interface for all C3 capabilities — compression, search, sessions, memory, agents, and system settings. The layout is [Left Nav] [Main Content] [Right Sidebar]. Both the left navigation and right sidebar support hover-to-open: when collapsed to their icon strip, hovering expands them automatically. Click the pin icon (📌) to keep a panel locked open; click again to unpin and return to hover-only mode. Pin state is saved to localStorage and restored on next load.

Dashboard Tabs

Header Bar

A persistent top bar above the main content area. Shows the active tab icon and title, connection status, inline quick stats (savings % and indexed file count), and action buttons:

• Connection status — glowing dot with "Live" / "Offline" label. When health data is available, color-coded service badges appear inline: green for connected, red for disconnected. All four services (c3, proxy, ollama, sltm) are always shown so you can see at a glance what is down. The proxy badge uses dual-signal detection: green if the MCP config references mcp_proxy.py, OR if .c3/proxy_state.json was written within the last 4 hours (meaning the proxy actively ran in this session).
• Check connections button — small refresh icon next to the service badges. Clicking it re-calls GET /api/health and updates all badges immediately; the icon spins while the request is in flight. The same button is also present in the left sidebar bottom panel and in the right sidebar Services section.
• Project switcher — appears automatically when two or more c3 ui instances are running simultaneously. Shows the current project name and a count badge. Click to open a dropdown listing all running sessions; clicking another project navigates to its UI in the same tab. The switcher polls GET /api/registry every 30 seconds and is hidden when only one session is active.
• Light/dark toggle — sun/moon button switches between dark and light mode. Preference is saved to localStorage and restored on next load.
• Refresh — manually re-fetch stats and file data from the API
• Docs — open the documentation page in a new tab
• Panel pin — pin or unpin the right sidebar. When pinned (icon highlighted), the panel stays open. When unpinned, it collapses to a 40px icon strip and expands on hover.

Left Navigation

A collapsible vertical tab list on the left edge. Supports two modes:

• Pinned open — 210px wide, shows icon + label for each tab. The C3 logo and status panel are visible. Click the pin icon in the header to unpin.
• Hover-only — collapses to a 54px icon strip. Hover over it to expand temporarily; moving the mouse away collapses it again. Click the pin icon while expanded to lock it open.

The bottom of the left nav shows a connection status dot, service badges, and a health refresh button (only visible when expanded).

Right Sidebar (Control Bar)

A collapsible right sidebar visible on all tabs. Supports the same hover-open + pin modes as the left nav:

• Pinned open — 320px wide, shows full control bar content. Pin icon in the header is highlighted (accent color). Click to unpin.
• Hover-only — collapses to a 40px icon strip. Hover to expand temporarily. Click the pin icon in the expanded header, or click any icon in the collapsed strip, to lock it open.

Bottom Drawer

A slide-up drawer anchored to the bottom of the main content area. It has two tabs:

REST API

The web server exposes a full REST API at http://localhost:3333.

Core

Sessions

Memory

Activity Log

Conversations

Notifications

MCP

Protocol

Instructions File

Hybrid Intelligence

Proxy

CLI Commands

All commands are run via c3 (or python cli/c3.py) from within your project directory.

Project Setup

c3 init <project_path> [--ide auto|claude|vscode|cursor|codex|gemini] [--force]
                                           # Initialize C3: builds index, creates config, generates instructions file,
                                           # and automatically installs the MCP config for your IDE.
                                           # Re-running on an existing project now migrates config defaults and
                                           # refreshes instruction workflow files (Update / Clear / Reset options).
c3 index [--max-files 500]                 # Rebuild the code index
c3 install-mcp [project_path] [ide] [--ide auto|claude|vscode|cursor|codex|gemini]  # (Re-)generate MCP config manually
c3 ui [project_path] [--port 3333] [--nano] [--silent]   # Launch web dashboard (full or nano)

Compression & Search

c3 compress <file> [--mode smart] [-o]  # Compress a file (modes: structure, outline, smart, diff)
c3 context <query> [--top-k 5]        # Get relevant context for a query
c3 pipe <query> [--top-k 5]           # All-in-one pipeline: index + context + session -> pipe to Claude
c3 encode <text> [--pipe]             # Encode to compressed format
c3 decode <text>                      # Decode compressed format

Sessions

c3 session start [description]        # Start a new session
c3 session save [summary]             # Save current session
c3 session load [session_id]          # Load a session (defaults to latest)
c3 session list                       # List all sessions
c3 session context                    # Get session context for prompt

Other

c3 stats                              # Show token usage analytics
c3 benchmark [project] [--sample-size 25] [--json] [--output .c3/benchmark_latest.json]
                                      # Run local benchmark for compression, retrieval, and grounding proxy metrics
c3 optimize                           # Show optimization suggestions
c3 claudemd generate                  # Preview auto-generated instructions file
c3 claudemd save                      # Write instructions file to project root (IDE-appropriate path)

CLI Examples

# Pipe compressed context into Claude Code
c3 context "fix the auth bug" | claude -p -

# Auto-compress before sending
c3 encode "Read src/Dashboard.tsx and fix the error on line 47" | claude -p -

# All-in-one pipeline
c3 pipe "fix the metrics calculation" | claude -p -

# Run benchmark and save machine-readable report
c3 benchmark . --sample-size 25 --output .c3/benchmark_latest.json

# Save session after work
c3 session save --summary "Fixed auth flow, updated tests"

# Start new session with prior context loaded
c3 session load | claude --resume

Architecture

  IDE (Claude Code / VS Code Copilot / Cursor / Codex / Gemini CLI)
       | MCP Protocol (IDE-specific config file)
       v
  MCP Proxy ──── Dynamic tool filtering + context injection (optional, opt-in via MCP config)
       | Subprocess stdio (NDJSON)
       v
  C3 MCP Server ─── 26 tools: search, compress, session, memory, CLAUDE.md, context, hybrid, notifications...
       |
       +── Compression      Smart Index
       |    AST Summary       TF-IDF + Code Structure
       |    Diff Engine       Chunk Retrieval
       |    Dedup Cache
       |
       +── Session Manager   Tiered Memory
       |    Decisions          Fact Store (TF-IDF)
       |    Tool Calls         Cross-Session Search
       |    Instructions Gen   Category Tagging
       |
       +── Instructions Mgr   Protocol
       |    Generate/Check      Encoder
       |    Compact/Promote     Dictionary
       |
       +── Context Snapshots  Transcript Index
       |    Capture/Restore     TF-IDF over .jsonl
       |    Save-and-Restore    Past Conversation Search (Claude Code)
       |
       +── File Watcher      File Extractor
       |    Change Detection    Log/JSONL Pre-filter
       |    Auto Index Rebuild  Token Savings Tracking
       |
       +── Background Agents  Notification Store
       |    Index Staleness      Thread-safe JSONL Queue
       |    Memory Pruner        Severity + Dedup
       |    Instructions Drift   Auto-surface to Claude
       |    Context Budget       AI-enhanced (Ollama)
       |    Session Insight      AI Badge + Quick Actions
       |
       v
  Web Dashboard (:3333)
   [Left Nav ⇄ pin] [Dashboard | Compressor | Index | Sessions | Memory | Activity | Hybrid | Agents | Proxy | Settings] [Right Sidebar ⇄ pin]
   Both sidebars: hover-to-expand (icon strip) or pin to keep open (persisted in localStorage)
    

Conversations

The Conversations module records full user/assistant turns and makes them browsable and searchable in the C3 UI. It complements the existing Sessions tab (which tracks tool calls and decisions) with the actual dialogue content.

Storage

All conversation data lives under .c3/conversations/:

• sessions.json — index of all session metadata (title, started, ended, turn count, token totals, source)
• {session_id}.jsonl — one JSON object per line, each a single turn with id, ts, role, text, tokens, and optional tool_calls
• {session_id}.jsonl.gz — gzip-compressed archive for sessions older than 30 days (read transparently, no data loss)

Data Sources

Conversations UI

• Session list - left panel lists all sessions sorted newest-first. Shows title (first user message), relative date, turn count, and source badge. Each row has direct Plans and Todos quick-jump buttons.
• Thread view — right panel renders the full conversation as a chat thread. User turns show a "You" badge; AI turns show an "AI" badge. Tool call badges appear inline in AI turn headers. A Rename button in the session header lets you edit the title in-place. Title overrides are stored in localStorage under the key c3_conv_titles.
• Chat / Plans / Todos tabs — switch views without leaving the conversation. Plans pulls c3_session_log decision events from the activity log for the session's time range. Todos extracts all markdown checkbox items (- [ ] task / - [x] done) from the thread with links back to the originating turn. Both views load automatically when using the quick-jump buttons in the session list.
• Table of Contents - toggle the ToC button to show a collapsible index of user prompts (numbered, 2-line preview). In narrow layouts the ToC is hidden for readability.
• Pagination - turns are loaded in pages with a Load more action for long sessions.
• Search scope toggle - explicit All / Session toggle next to the search box. Search is debounced and scope-aware; "Session" is disabled until a conversation is open.
• Pagination - conversation turns are loaded in pages with a Load more action for long sessions.
• Compression - sessions older than 30 days are automatically gzip-compressed. The UI reads them transparently; compressed sessions show a "gz" badge in the list and an "archived" label in the header.

Compression Modes

When using c3_compress or the CLI compress command:

Project Data Layout

After initialization, C3 creates this structure in your project:

.c3/
  config.json            # project configuration (includes "ide" key for cross-IDE support)
  dictionary.json        # project-specific compression dictionary
  index/
    index.json           # TF-IDF code index
  cache/                 # file compression cache (for diff mode)
  sessions/
    session_*.json       # saved sessions (includes tool_calls, duration)
    analytics.json       # aggregate session stats
  facts/
    facts.json           # persistent fact store
  snapshots/
    snap_*.json          # context snapshots for save-and-restore workflow
  transcript_index/
    index.json           # TF-IDF index over .jsonl transcripts (Claude Code only)
    manifest.json        # tracks which transcript files have been indexed
  file_memory/
    *.json               # per-file structural maps (classes, functions, line ranges)
    _queue.txt           # async update queue (from Read hook)
  activity_log.jsonl     # append-only activity log
  notifications.jsonl    # agent notification queue
  proxy_metrics.json     # proxy traffic and filtering metrics (written on shutdown)

Project Structure

claude-companion/
  cli/
    c3.py                # CLI entry point (all commands)
    mcp_server.py        # MCP server (30 tools via FastMCP)
    mcp_proxy.py         # Optional advanced MCP proxy (tool filtering)
    server.py            # Flask web server + REST API
    ui.html              # Single-page React dashboard
    docs.html            # Documentation (this page)
    hook_filter.py       # PostToolUse hook for Bash (output filtering, Claude Code only)
    hook_read.py         # PostToolUse hook for Read (C3 enforcement + file memory queue, Claude Code only)
  services/
    compressor.py        # AST-based code compression
    indexer.py           # TF-IDF code index
    session_manager.py   # Session tracking + instructions file generation
    claude_md.py         # Instructions file lifecycle management (generate/check/compact/promote)
    memory.py            # Tiered memory with fact storage + search
    context_snapshot.py  # Context snapshots for save-and-restore workflow
    transcript_index.py  # TF-IDF index over .jsonl transcripts (Claude Code only)
    activity_log.py      # Append-only JSONL activity log
    notifications.py     # Thread-safe notification queue for agents
    agents.py            # Background analysis agents (7 daemon threads, AI-enhanced)
    file_memory.py       # Persistent structural file index with line ranges
    tool_classifier.py   # Tool category classification for proxy filtering
    proxy_state.py       # Sliding window conversation state tracker
    watcher.py           # File system change monitoring
    protocol.py          # Compression protocol encoder/decoder
  core/
    __init__.py          # Token counting utilities
    ide.py               # IDE profile registry (Claude Code, VS Code, Cursor, Codex) + auto-detection
    config.py            # Hybrid, proxy, delegate, and agent configuration loaders
  install.bat            # Windows installer
  install.sh             # Linux/macOS installer
  pyproject.toml         # Python package metadata + dependencies

Token Savings Estimates

Tips

Troubleshooting