CodeCaChe (ccc)

CodeCaChe provides insight into your code and improves developer experience by:

• highlighting which tests will be ran with your changes

• showing if your change violates language linting rules

• showing when you create or modify cross-service calls before you commit

• providing language models with accurate real-time insights into your changes

• triggering specific testing tools based on your changes

ccc stands on the shoulders of Tree-Sitter. It scans a project and generates the CodeCaChe in memory. This is a human and machine readable map of the source tree including every source file; its constants, functions (with return types and doc summaries), intra-file call graph, and marker notes (TODO/FIXME/...).

It is designed to give engineers a always-fresh index of a project, the latest changes, how those changes impact tests or other branches (compare working branch against any other branch). In addition it also provides language models a local MCP server for an always up-to-date map of your codebase, dependencies, call-graph and cross-service calls.

Supports: C99, C++ (20 except modules), C#, Rust, Go, Python, Zig, Odin, TypeScript & JavaScript - see LANGUAGES.md for what each one resolves.

Table of content

Expand contents

• Quick-Start
• Usage
• Insights
• Extension
• Dependency Map
• Cross-Repository Calls
• Agents.md
• Test Triggers
• Pipelines (CICD)
• Performance
• MCP Server for Agents
• Token Stream

Quick-Start

1. Install

   a. Latest github release (Linux / macOS / Windows)

   curl -fsSL https://raw.githubusercontent.com/colwill/ccc/main/install.sh | bash

   b. or build from source

   cargo build --release && ./target/release/ccc -- install

2. Initialise ccc changes --init to generate the basic .ccc/map.json

   a. (recommended) edit dependency map .ccc/map.json to include service locations and dependencies

3. Start local MCP ccc serve --html

   a. (recommended) visit http://127.0.0.1:6767/insights for Insights UI

4. Register MCP server with tooling

   a. claude: claude mcp add --transport http ccc http://127.0.0.1:6767/mcp

   b. copilot: copilot mcp add --transport http ccc http://127.0.0.1:6767/mcp

5. Instruct your model to use the MCP tool ccc

6. Work as usual

Usage

ccc changes [PATH] --telemetry        # changes vs the base branch: services to test, dependencies, otel
ccc check [PATH] --format json        # exit non-zero if .ccc is stale - for CI
ccc tokenize [PATH]                   # pre-encode an existing .ccc into tokens.bin + tokens.json
ccc deps [PATH]                       # just the dependency delta of that report, for CI (JSON)
ccc prompts [PATH]                    # which claude/copilot request produced each change (JSON)
ccc serve [PATH] --html               # MCP server and optional insights UI: agents query the in-memory map
ccc export [PATH]                     # publish what this project serves/calls, for other repos
ccc insights [PATH] --html <File>     # the insights analysis as JSON (call graph, triggers, lints)
ccc sast [PATH]                       # security findings; defaults to non-zero on a high finding
ccc audit [PATH]                      # resolve lockfiles and check against the OSV advisory db
ccc install [--dir] <DIR>             # install the ccc binary onto your PATH (Linux)
ccc scan [PATH] --tokens              # regen PATH/.ccc  (PATH defaults to ".") (opt: output token stream)

Insights

The command (ccc serve --html) starts the MCP server with the insights UI on http://localhost:6767/insights. It is disabled by default and fetches /insights.json from the running server, so it tracks the in-memory ccc map at runtime.

ccc serve --html                      # then open http://127.0.0.1:6767/insights
curl -s localhost:6767/insights.json  # the same data, for scripting
ccc insights                          # the same analysis as JSON, no server
ccc insights --html page.html         # insights as a single page, for static hosting

Extension

extensions/vscode is an editor client for the same analysis. It runs ccc serve in the background for each workspace folder and reads it over loopback HTTP, so nothing leaves the machine and no configuration is needed to get started.

See 'EXTENSION.md' for more information.

DependencyMap

The .ccc/map.json file is used to hint to ccc where to find dependencies, for example services that call each other or share common functionality.

{
  "services": {
    "auth":    ["apps/auth/**"],
    "billing": ["apps/billing/**", "libs/money/**"],
    "gateway": ["apps/gateway/**"]
  },
  "deps": {
    "gateway": ["auth"] // gateway calls auth over HTTP, so declare it!
  },
  "externals": {
    "billing": { "repo": "acme/billing", "lang": "go", "path": "../billing" }
  }
}

Externals

Calls do not stop at your project. externals names peer repositories - a sibling checkout, another corner of a monorepo, or a private repo you only have a published surface for - and ccc:serves / ccc:calls comments name the key both ends agree on:

// gateway (rust)
fn checkout(cart: &[Item]) {
    // ccc:calls grpc billing.v1.Charge
    client.charge(total)
}

// billing (go), another repository
// ccc:serves grpc billing.v1.Charge
func Charge(account string, amount int) error { ... }

Matching keys become real edges of the service graph, with a file and line at each end, whatever language each side is written in. Publish a surface for others to consume with ccc export.

See EXTERNALS.md.

Skipping code

A ccc:skip comment withdraws code from the analysis, in whatever comment syntax the file's language uses. Placement decides the scope:

• At the very top of a file - the whole file is skipped.
• Directly above a function (attribute and decorator lines may sit between, a blank line may not) or inside its body - just that function is skipped: it is not measured, not ranked, and calls to it are not resolved.
• Anywhere else at file level - the whole file is skipped.

// ccc:skip generated - do not analyse

Trailing prose after the marker is allowed, so a skip can say why.

AGENTS.md

Note: If you're not using ccc serve, you can generate a .ccc directory using ccc scan and then add a block to your AGENTS.md file to scan the .ccc directory instead.

(recommended) For those using ccc serve and the MCP tools; add the following block to an AGENTS.md file at the root of your project - agents that read an AGENTS.md at the repo root pick this up automatically e.g. Copilot, Claude, Cursor etc.

# AGENTS.md

This repo has a ContextCodeCache - a generated in-memory code map served over MCP at `http://127.0.0.1:6767/mcp`. Use it
as the entry point for everything you do here.

- no bash, grep or sed usage for exploring the project
- Every interaction: use `ccc` tool calls to gather information about the source of this project.
- All thinking, navigation, and questions about the codebase go through the MCP server tools: (index, find, references, dependencies, file, notes, changes, test_triggers, test_targets, lints, hot, services refresh)
- When I ask to *see* the analysis, call `insights` - it opens the insights UI in my browser (needs `ccc serve --html`)
- Make code changes in the source, never to the in-memory map.
- After changing tracked source call the `ccc` tool with `refresh` to ensure you have the latest changes in-memory.

Because the agent loads AGENTS.md at the start of a session, this wires the code map into every interaction: reasoning and answers come from ccc's map, whilst edits still apply to the source and trigger a refresh.

Testing

See TESTING.md

Pipelines

See PIPELINES.md

Performance

See PERF.md

MCP

See MCP.md

Stream

See STREAM.md