codefold

Read, with zoom levels.

A structural code reader for LLM agents. Hand it a file and a zoom level — it gives you back the slice of the file the model actually needs to see.

Supported today: Python, TypeScript, Rust, Go. Rust core, Python wheel, optional CLI. Node binding on the roadmap.

Why

LLM agents waste enormous amounts of context reading entire files when they only need the public surface. cat-equivalent reads are ~3-5× larger than they need to be on real-world codebases.

Numbers from this repo's test fixtures:

Compression scales with the body-to-signature ratio. On real-world service files (>500 lines), expect 70-90% reductions at signatures.

Install

CLI (Rust toolchain required):

cargo install codefold-cli

Rust library:

cargo add codefold-core

Python (prebuilt wheels for Linux/macOS/Windows):

pip install codefold
# or with uv:
uv add codefold

Node.js (prebuilt binaries for Linux/macOS/Windows):

npm install @maxenceleguery/codefold

import { read } from "@maxenceleguery/codefold";
const r = read("src/auth.py", "signatures");

The bare codefold name on npm was blocked as too similar to an existing code-fold; the package lives under the maintainer's user scope.

Use

codefold src/auth.py --level signatures
codefold src/auth.py --level bodies --focus login,verify_token
codefold src/handlers.ts --level signatures --stats

Subcommands

codefold update                  # check + interactively upgrade via `cargo install codefold-cli --force`
codefold update --check          # check only; don't upgrade
codefold update --yes            # upgrade without prompting (for scripts / CI)
codefold setup                   # install integration into agent harnesses (project scope)
codefold setup --scope user      # install user-level (~/.claude/CLAUDE.md + skill)
codefold setup --dry-run         # show what would change without writing
codefold setup -H claude-code    # target a specific harness (claude-code|cursor|copilot)

update requires cargo on PATH (it self-upgrades via crates.io). If you installed via pip or npm, those need to be updated separately — the CLI will print the right command if cargo isn't found.

codefold setup writes a delimited <!-- codefold:start --> ... <!-- codefold:end --> block to:

The block is idempotent — re-running setup updates in place. It explicitly tells the agent to brief any subagents it spawns about codefold, since subagents don't inherit conversation context.

As a Rust library:

use codefold_core::{read, read_opts, Level, Options};

// Quick read
let r = read("src/auth.py".as_ref(), Level::Signatures)?;
println!("{}", r.content);
println!("≈{} tokens, {} symbols", r.tokens_est, r.symbols.len());

// With focus: keep `login` and `verify_token` at full body, the rest as signatures.
let opts = Options::new(Level::Signatures).focus(["login", "verify_token"]);
let r = read_opts("src/auth.py".as_ref(), opts)?;

As a Python library:

import codefold

r = codefold.read("src/auth.py", level="signatures")
print(r.content)
print(f"~{r.tokens_est} tokens, {len(r.symbols)} symbols, {r.language}")

# With focus
r = codefold.read("src/auth.py", level="signatures", focus=["login", "verify_token"])

Levels

--focus name1,name2,... elevates the named symbols to bodies regardless of base level. A class name in focus expands to "every method of that class".

Positioning

The agent-tooling space is busy. codefold's niche:

• vs skim — skim is shell middleware: it rewrites your commands and compresses their output. codefold is a primitive: a stateless library you import from inside your agent framework. Different distribution shape, different integration point.
• vs codebase-memory-mcp — codebase-memory builds a persistent SQLite knowledge graph of a whole repo, queried over MCP. codefold answers "give me this one file at level X" with no indexing, no server, no state.

If you're building an agent framework or a code-aware tool and you need granular file reads, you want codefold. If you want a turnkey CLI for your shell or a whole-repo retrieval layer, look at skim or codebase-memory.

Status

Early. v0.8.1. Python, TypeScript, Rust, Go. API is not yet stable.

Changelog

• 0.8.3 — CI fix: switch publish job from npm ci to npm install --omit=optional since npm ci enforces lock-vs-package.json sync even for self-referential optional deps that aren't on the registry yet at release time.
• 0.8.2 — CI fix: npm ci --omit=optional so the publish job doesn't choke on out-of-sync lock entries for our own (not-yet-published) scoped sub-packages. (Insufficient — superseded by 0.8.3.)
• 0.8.1 — CI fixes: upgrade npm on the release runner to >=11.5 (needed for Trusted Publishing OIDC); make the setup test platform-agnostic on Windows.
• 0.8.0 — codefold update (self-upgrade via cargo), codefold setup (install integration into Claude Code / Cursor / Copilot — project or user scope, idempotent block-replace, propagates to subagents). npm publish migrated to Trusted Publishing (OIDC).
• 0.7.0 — npm publish pipeline. codefold on npm with prebuilt binaries for Linux x86_64/aarch64, macOS x86_64/arm64, Windows x64. Uses napi-rs's per-platform sub-package pattern with provenance.
• 0.6.0 — Publishing pipeline: codefold-core and codefold-cli to crates.io, codefold (Python wheel) to PyPI via Trusted Publishing on tag pushes. Node.js binding (@codefold/node) scaffolded with napi-rs; npm publishing pipeline arrives in v0.7.0. MSRV bumped to 1.77 (napi-rs requirement).
• 0.5.1 — Fix Windows CI: the Go newline regression test asserted on \n directly, which broke when Windows checked out the fixture as CRLF. Switched to .lines() and added .gitattributes forcing LF.
• 0.5.0 — Go language support (.go). Public = uppercase-first identifier. Fixed gap rendering for grammars (like Go) that expose statement terminators as anonymous siblings.
• 0.4.0 — Python bindings via PyO3 + maturin (import codefold). Pinned CI clippy to a known-good toolchain.
• 0.3.0 — Rust language support (.rs). pub filter at Public level; trait-impl methods kept regardless of pub. GitHub Actions CI on Linux/macOS/Windows.
• 0.2.0 — Public level (Python _-prefix filter, TypeScript export/private filter). Level enum marked #[non_exhaustive].
• 0.1.0 — Initial release. Python and TypeScript, Full / Signatures / Bodies levels, focus=[...], token estimation, CLI, criterion benchmarks.

Contributing

Branch off develop, open a PR against develop. Releases are tagged on main. See CONTRIBUTING.md.

License

MIT