GitHub - colwill/ccc: ContextCodeCache generator · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
colwill
ccc
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>4 Commits<br>4 Commits
.ccc
.ccc
.github/workflows
.github/workflows
example
example
src
src
.gitignore
.gitignore
Cargo.lock
Cargo.lock
Cargo.toml
Cargo.toml
README.md
README.md
View all files
Repository files navigation
ContextCodeCache (ccc)
Tool that scans a project and generates a ContextCodeCache - a .ccc<br>directory holding a compact, machine-readable map of every source file: its<br>constants, functions (with return types and doc summaries), intra-file call<br>graph, and marker notes (TODO/FIXME/...). It is designed to give agents a<br>cheap, always-fresh index of a project.
Please ⭐ if you find this useful 💚
Install / build
Requires Rust ≥ 1.77 (the tree-sitter 0.25 stack; some transitive deps use<br>edition 2024) also needs a recent cargo.
cargo build --release # binary @ target/release/ccc<br>./target/release/ccc install # copy it onto your PATH (Linux)
ccc install copies the running binary into ~/.local/bin (the user-local bin<br>dir on Linux — no sudo needed) and marks it executable. Pass --dir to<br>choose a different directory, or --force to overwrite an existing ccc. If the<br>target directory isn't on your $PATH, it prints the line to add to your shell<br>profile.
Usage
ccc scan [PATH] # regen PATH/.ccc (PATH defaults to ".")<br>ccc scan [PATH] --tokens # also pre-encode the cache into a token stream<br>ccc check [PATH] # exit non-zero if .ccc is stale - for CI<br>ccc check [PATH] --format json # same, but print changed cache files as JSON<br>ccc tokenize [PATH] # pre-encode an existing .ccc into tokens.bin + tokens.json<br>ccc install [--dir DIR] # install the ccc binary onto your PATH (Linux)
ccc check --format json prints one line — { root, up_to_date, files[], changes[] } —<br>where files is the repo-relative paths of the out-of-date cache entries. It's<br>meant to be consumed by other tooling; the bundled GitHub Action feeds that array<br>to downstream jobs via fromJSON(...):
{"root":"example","up_to_date":false,<br>"files":["example/.ccc/CCC.md","example/.ccc/src-math.rs.md"],<br>"changes":[{"status":"modified","file":"CCC.md","path":"example/.ccc/CCC.md"}, ...]}
scan rewrites every per-file entry plus the CCC.md index, so committed diffs<br>always come from re-running the generator. check regenerates in memory and<br>compares against the committed .ccc, ignoring generation timestamps, so a<br>freshness gate never fails purely because time passed.
Specification
-..md, one per source file<br>└── src-math.rs.md">.ccc/<br>├── CCC.md # index: totals + one line per file<br>├── src-main.rs.md # -..md, one per source file<br>└── src-math.rs.md
Each per-file entry follows this format:
# math.rs.md (yyyymmdd-hh-mm-ss) UTC<br># source: src/math.rs [rust]<br># const<br>- L4@PI:f64<br># funcs<br>- L7:8@square:f64 // Square a number.<br>- L12:8@circle_area:f64 // Area of a circle with the given radius.<br># refs<br>- circle_area@L14 calls L7:8@square:f64<br># note<br>- @L13 NOTE: uses the truncated PI above, so results are approximate.
const - file-level constants/statics: L@:. Since not<br>every language marks constants, this uses each language's convention: Rust<br>const/static and Go const/var specs; Python only SHOUTING_SNEK_CASE<br>module bindings; JS/TS only const declarations (not let/var). Class/impl<br>attributes in Python and JS/TS are treated as members, not file consts.
funcs - definitions: L:@: // doc summary
refs - intra-file call graph, resolved by scope (not just by name):<br>@L calls L:@:. A bare foo()<br>binds to a same-file free function foo; a receiver call (self.foo(),<br>this.foo(), or a Go recv.Foo()) binds to a method foo on the enclosing<br>type. Calls on any other receiver (other.foo()) need type information to<br>resolve, so no edge is emitted rather than guessing one from the name.
note - marker comments (TODO, FIXME, XXX, HACK, BUG, NOTE, SAFETY)
A worked example lives in example/ with its...