Getting Started

1. Clone the repository

git clone https://github.com/your-org/claude-companion.git
cd claude-companion

2. Install C3

pip install .

3. Make the CLI available (optional)

On Windows, add the project root to your PATH, or use the provided batch file:

# Windows — run from the project root
c3.bat init

# Unix/Mac — install the CLI
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

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.

VS Code Copilot

c3 install-mcp vscode

Updates .vscode/mcp.json and .github/copilot-instructions.md.

Codex

c3 install-mcp codex

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

Gemini CLI

c3 install-mcp gemini

Updates .gemini/settings.json.

All IDEs at once

c3 install-mcp all

Hooks (Claude Code only)

C3 includes several hook scripts that enforce the c3 discipline:

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_compress + c3_read — never raw file reads.

  c3_search(query='auth middleware', action='code')
  c3_compress(file_path='src/auth.py', mode='map')
  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 three permission tiers that control what Claude Code is allowed to do. Apply them with:

c3 permissions <tier>

Session UI

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

c3 ui

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

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:5001 by default.

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 the MCP configuration from all IDEs without deleting your data:

c3 mcp-remove

To fully remove C3 from a project (including the .c3/ directory):

rm -rf .c3/ CLAUDE.md AGENTS.md .gemini/settings.json .mcp.json