Getting Started

1. Install the package

Published to PyPI as code-context-control. pipx is recommended — it isolates C3's dependencies from your other Python tools:

pipx install code-context-control

# or, with pip
pip install code-context-control

# with the optional Textual terminal UI
pip install "code-context-control[tui]"

2. Initialize a project

c3 init /path/to/your/project

MCP is wired through the installed c3-mcp console-script entry point, so a later c3 upgrade needs no per-project MCP reconfiguration.

3. From source (contributors)

git clone https://github.com/drknowhow/code-context-control.git
cd code-context-control
pip install -e ".[dev]"          # tests, linters, build tools

# Windows helper
c3.bat init
# Unix/Mac helper
bash install.sh

Run c3 init inside any project you want to use C3 with. This creates the .c3/ data directory, builds the code index, and generates the necessary instruction files.

# Navigate to your project
cd /path/to/my-project

# Initialize C3
c3 init

What init creates

What kind of project is this?

c3 init classifies the project as code, mixed, prose, or empty (fewer than 20 source/document files judged, no opinion) by counting source files against prose/office documents, and prints the result (v2.92.0). For a prose-kind project (a documentation repo with near-zero source), the symbol-aware tools (c3_impact, c3_validate, c3_ci) have little to act on, so a non-interactive install with no explicit --enforcement writes advisory instead of the tier-derived mode (never over an explicit c3 enforce choice or flag). The interactive Step 5/5 suggests the same for a prose repo, with the reason stated. Switch back any time with c3 enforce strict.

Re-init / upgrade

Running c3 init on an existing project is safe — it merges new config without overwriting your customizations.

After init, connect C3 to your IDE. The install-mcp command writes the MCP server configuration for the target IDE.

Claude Code (primary)

c3 install-mcp claude

This writes to .mcp.json (project scope) and optionally configures PreToolUse / PostToolUse hooks in .claude/settings.local.json. Both are merged, not overwritten: C3 only touches its own c3 server entry and its own hooks, leaving any other MCP servers, hooks, and top-level keys you've added in place.

VS Code Copilot

c3 install-mcp vscode

Updates .vscode/mcp.json and .github/copilot-instructions.md. No PreToolUse hooks in this host — VS Code hides MCP tools until the agent searches for them, so the generated instructions open with a tool-load step, and the c3-first rule is a workflow requirement rather than an enforced block.

Cursor

c3 install-mcp cursor

Updates .cursor/mcp.json and .cursorrules. No hooks in this host either.

Codex

c3 install-mcp codex

Updates .codex/config.toml and AGENTS.md.

Antigravity

c3 install-mcp antigravity

Updates the user-global ~/.gemini/antigravity/mcp_config.json and AGENTS.md.

Grok Build

c3 install-mcp grok
grok --trust
c3 doctor --ide grok

Updates .grok/config.toml ([mcp_servers.c3]), writes C3's hooks to .grok/hooks/c3.json, and refreshes the C3 block in AGENTS.md. Grok loads none of them until the folder is trusted, so launch grok --trust once in the project (or run /hooks-trust inside Grok). C3 never writes Grok's trust store or ~/.grok/config.toml. In Grok, C3's tools are reached through search_tool / use_tool as c3__c3_search and so on. Details and limitations: docs/grok-native.md.

The Gemini CLI profile was removed in v2.52 — use Antigravity instead. c3 mcp-remove still cleans up legacy .gemini/settings.json and GEMINI.md files.

Using more than one host in the same project

There is no single "install for every IDE" command — --ide accepts exactly one of auto, claude, vscode, cursor, codex, antigravity, grok per call, and each writes that host's own MCP config file. Run c3 install-mcp once per host you use:

c3 install-mcp claude
c3 install-mcp codex

You do not need to keep CLAUDE.md / AGENTS.md / .github/copilot-instructions.md in sync by hand — every install-mcp run regenerates all of a project's instruction docs from one source of truth, not just the target host's.

Hooks (Claude Code and Codex/Grok — not VS Code, Cursor or Antigravity)

C3 registers one dispatcher, cli/hook_dispatch.py, per lifecycle event; it routes internally to focused sub-hooks so only one process spawns per event:

Codex gets the same dispatcher through .codex/hooks.json (v2.119.0); Grok Build through .grok/hooks/c3.json (v2.131.0). VS Code, Cursor and Antigravity have no PreToolUse hook mechanism, so the c3-first rule there is a written workflow requirement, not a technical block.

A sub-project is a C3 project declared a child of another — a service in a monorepo, or a second checkout that lives elsewhere entirely (even another drive). It keeps its own .c3/; retrieval fans out across the hierarchy only when you ask for it (v2.96.0):

c3 sub link ../billing-service      # link an existing project anywhere on disk
c3 sub tree                         # the whole hierarchy
c3_search(query='retry policy', scope='all')   # parent + every descendant

Hierarchy is a strict tree — one parent per project, up to 8 levels deep. See docs/sub-projects.md for the full CLI and Hub UI reference.

Once Claude Code is connected, C3 tools appear automatically. Here's a typical session startup sequence:

• 1
  Recall memory

  Before any work, ask Claude to recall relevant context from previous sessions.

  // Claude will call:
  c3_memory(action='recall', query='your task topic')

• 2
  Check status

  See budget remaining, active session, and health.

  c3_status(view='budget')

• 3
  Search and read

  Claude discovers and reads files using c3_search + c3_read — never raw file reads. c3_read(file_path) with no symbols/lines returns a structural map first (c3_compress did this before v2.124.0 and is gone from the MCP surface); then read the exact symbol.

  c3_search(query='auth middleware', action='code')
  c3_read(file_path='src/auth.py')
  c3_read(file_path='src/auth.py', symbols=['AuthMiddleware'])

• 4
  Edit and validate

  All edits go through c3_edit, followed by c3_validate.

  c3_edit(file_path='src/auth.py', old_string='...', new_string='...', summary='fix token expiry')
  c3_validate(file_path='src/auth.py')

• 5
  Log and snapshot

  Log key decisions. Before ending or running /clear, take a snapshot.

  c3_session(action='log', data='Fixed auth token expiry bug in AuthMiddleware')
  c3_session(action='snapshot')   # before /clear

C3 provides four permission tiers, Claude Code only, that control what native tools and Bash commands are pre-approved. Apply them with:

c3 permissions <tier>      # show | preview | diff | clean | apply a tier

Session UI

A real-time session dashboard showing tool calls, memory facts, edit ledger, and budget.

c3 ui

Opens at http://localhost:3333 by default (auto-picks the next free port if taken).

Project Hub

A multi-project dashboard for managing all C3-enabled projects, viewing cross-session stats, and browsing notifications.

c3 hub

Opens at http://localhost:3330 by default.

Stop pasting API keys into the chat. Store them once, and the agent uses them by name — C3 decodes the value into the subprocess environment, so it never enters the model's context or the conversation transcript.

# Value is read from a hidden prompt — never in shell history
c3 creds set NPM_TOKEN

# Shared across every C3 project on this machine
c3 creds set OPENAI_API_KEY --global

# Names and metadata only — the value is never printed
c3 creds list

The agent then names the secret instead of knowing it:

c3_shell(cmd='npm publish', env_creds='NPM_TOKEN')

Manage everything visually in the Hub's Credentials tab — search across all projects with /, open a settings drawer per credential, right-click for actions.

Storage internals, the global/project override model, exposure flags, search qualifiers, and troubleshooting are on the dedicated credential vault guide.

If your team runs self-hosted Bitbucket Data Center / Server, C3 can connect to it so Claude Code (and the Hub UI) can read and act on pull requests, branches, builds, and repo administration.

One-time setup

# Generate a Personal Access Token in Bitbucket first
# (Profile → Manage account → Personal access tokens)

c3 bitbucket login --url https://bitbucket.example.com
# → prompts for username + PAT (token text masked, stored in OS keyring)

c3 bitbucket set-default --project PROJ --repo my-service
c3 bitbucket status

Tokens live in the OS keyring (Windows Credential Manager / macOS Keychain / Linux Secret Service). The .c3/config.json file only stores a non-secret index of (base_url, username) pairs and the active-account pointer — never the token itself.

Once configured, the new c3_bitbucket MCP tool is available in Claude Code, the Hub UI gains a Bitbucket tab, and the c3 bitbucket CLI exposes login / logout / status / use / set-default subcommands.

To remove C3's MCP server entry from the current host's config without deleting your data:

c3 mcp-remove c3

To fully remove C3 from a project (including the .c3/ directory), delete the data directory plus whichever host config files this project has — not every project has every file:

rm -rf .c3/ CLAUDE.md AGENTS.md .mcp.json .claude/settings.local.json \
       .vscode/mcp.json .github/copilot-instructions.md \
       .cursor/mcp.json .cursorrules \
       .codex/config.toml .codex/hooks.json \
       .grok/config.toml .grok/hooks/