Getting Started — C3 Guide

✅ Prerequisites

Requirement	Version	Notes
Python	3.10+	Used to run the MCP server and CLI
Claude Code CLI	latest	Primary IDE C3 is designed for
pip	any	For installing Python dependencies
Git	any	Optional but strongly recommended

💡

Optional: local AI delegation To use c3_delegate with local models, install Ollama and pull at least one model (e.g. ollama pull qwen2.5-coder:7b).

📦 Installation

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

✅

Verify the install Run python cli/c3.py --help (or c3 --help after PATH setup). You should see a list of all available commands.

🏗️ Initializing a Project

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

Path	Purpose
`.c3/`	Data directory — index, sessions, memory, edit ledger
`.c3/index/`	TF-IDF code search index (rebuilt automatically)
`.c3/sessions/`	Session JSON files with decisions and snapshots
`.c3/memory.json`	Persistent memory fact store
`CLAUDE.md`	Project instructions file (mandatory workflow injected here)
`AGENTS.md`	Instructions for Codex sessions
`.gemini/settings.json`	Instructions for Gemini sessions

⚠️

Add .c3/ to .gitignore The .c3/ directory contains session data and should generally not be committed. C3 will prompt you about this during init.

Re-init / upgrade

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

🛡️

Your hand-written content is preserved Generated instruction files (CLAUDE.md, AGENTS.md, GEMINI.md) wrap C3 content in a  /  block. Re-running init (or c3 claudemd save / the Compact action) rewrites only that block — anything you add outside it stays put. An existing hand-written file with no block is kept and the C3 block is appended below it.

🔌 IDE Setup

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.

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

🔗

MCP modes The default mode is direct (stdio). A proxy mode is also available for environments that require HTTP-based MCP. Pass --mode proxy if needed.

Hooks (Claude Code only)

C3 includes several hook scripts that enforce the c3 discipline:

Hook	Effect
`hook_pretool_enforce.py`	Blocks native Read/Grep/Glob/Edit if no prior c3_* call
`hook_edit_ledger.py`	Logs every edit to the edit ledger (PostToolUse)
`hook_ghost_files.py`	Blocks Write to 0-byte or invalid paths (anti-ghost-file)
`hook_session_stats.py`	Tracks tool usage and session metrics
`hook_read.py`	Intercepts native Read to route through c3_read

▶️ Your First Session

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

🔒 Permission Tiers

C3 provides three permission tiers that control what Claude Code is allowed to do. Apply them with:

c3 permissions <tier>

Tier	Bash access	Use case
`readonly`	None	Code review, exploration — no writes, no shell
`standard`	Safe read-only commands only	Normal development — safe git, test runners
`unrestricted`	Full bash access	Power use — trusted, local-only sessions

⚠️

Default is standard The standard tier blocks destructive shell commands (rm -rf, git reset --hard, etc.) while allowing safe operations. Upgrade to unrestricted only when needed.

🛡️

Your custom rules survive a tier change Applying or switching a tier preserves allow/deny entries you added yourself, plus keys like ask and defaultMode. C3 only replaces the entries it manages, so you can mix a tier with project-specific permissions.

🌐 Web UI & Hub

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.

ℹ️

The web UI and Hub run as separate Flask servers from the MCP server. They read shared state from the .c3/ directory on disk.

🪣 Bitbucket Data Center (optional)

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.

ℹ️

Full action reference, security notes, configuration shape, and troubleshooting are on the dedicated Bitbucket integration guide.

🗑️ Removing C3

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

⚠️

Deleting .c3/ permanently removes all sessions, memory facts, and edit history for that project.