codefold

Read, with zoom levels.

github.com/maxenceleguery/codefold · latest release · MIT

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, instead of dumping the whole file into context.

Python TypeScript Rust Go

Compression on real fixtures

File	Full	Signatures	Saving
`auth.py` (90 LOC)	474 tok	320 tok	−32%
`heavy.py` (110 LOC, body-heavy)	809 tok	212 tok	−74%
`auth.ts` (75 LOC)	468 tok	324 tok	−31%

On real-world service files over 500 lines, expect 70–90% token reductions at signatures level.

CLI

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

Python

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"])

Rust

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

let r = read("src/auth.py".as_ref(), Level::Signatures)?;
let opts = Options::new(Level::Signatures).focus(["login"]);
let r = read_opts("src/auth.py".as_ref(), opts)?;

Levels

full — the file verbatim. For API symmetry.
signatures — imports, top-level constants, function / class signatures, docstring summaries. Bodies replaced with ....
public — like signatures, but only public-by-convention symbols (Python: not _-prefixed; TypeScript: exported; Rust: pub; Go: uppercase-first).
bodies — top-level & class-method bodies in full; nested function bodies collapsed.

Positioning

The agent-tooling space is busy. codefold's niche: a stateless, embeddable primitive — not a CLI middleware (skim) and not a whole-repo knowledge graph (codebase-memory-mcp). If you're building an agent framework or a code-aware tool and you need granular single-file reads, codefold drops in as a library.

Install

# CLI
cargo install --git https://github.com/maxenceleguery/codefold codefold-cli

# Python (Rust toolchain required at build time)
uv venv && source .venv/bin/activate
uv pip install maturin
uv run maturin develop --release --manifest-path codefold/bindings/python/Cargo.toml

Binary wheels on PyPI and a published crate on crates.io are on the roadmap.