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 TSX / JSX Rust Go Markdown

Install

pip install codefold                    # Python
npm install @maxenceleguery/codefold    # Node.js
cargo install codefold-cli              # CLI
cargo add codefold-core                 # Rust library

Prebuilt wheels and native binaries for Linux, macOS and Windows.

Token savings on real files

File	Full	signatures	Saving
supabase `GoTrueClient.ts`	59.5k	8.2k	−87%
CPython `asyncio/base_events.py`	15.9k	2.8k	−83%
Go `encoding/json/encode.go`	11.0k	2.2k	−80%
clap_builder `command.rs`	43.5k	10.4k	−77%
CPython `argparse.py`	20.3k	5.2k	−75%
Go `net/http/server.go`	34.7k	11.5k	−67%
serde_json `de.rs`	21.0k	7.8k	−63%
zod `v3/types.ts`	41.4k	21.6k	−48%

Tokens (cl100k) measured with codefold 0.9. Savings follow the body-to-signature ratio: implementation-heavy files shrink most, type-heavy files like zod keep more. public goes further, to 73 to 91% on most of these.

Use it from your agent

codefold setup                  # this project: CLAUDE.md, Cursor, Copilot
codefold setup --scope user     # everywhere: ~/.claude/CLAUDE.md + a Claude Code skill
codefold setup --list           # what's installed, and is it current
codefold setup --uninstall
codefold doctor

setup writes a short, idempotent instruction block telling the agent to reach for codefold before a raw file read, and to brief its subagents about it too.

CLI

codefold src/auth.py                               # signatures (default)
codefold src/auth.py --level bodies --focus login,verify_token
codefold src/*.ts --level public --stats           # many files at once
codefold src/auth.py --format json                 # symbols + hidden line ranges
git show HEAD:src/auth.py | codefold - --lang python

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

# Keep `login` in full, the rest as signatures
r = codefold.read("src/auth.py", focus=["login"])

# Code you already have in memory
r = codefold.read_source(source, "typescript", level="public")

Node.js

import { read, readSource } from "@maxenceleguery/codefold";

const r = read("src/auth.py", "signatures", ["login"]);
const r2 = readSource(buffer, "tsx", "public");

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

signatures: imports, top-level constants, function and class signatures, and the first paragraph of each docstring or doc comment. Bodies become .... Markdown keeps its headings.
public: like signatures, limited to the public surface (Python: no _ prefix; TypeScript: exported; Rust: pub; Go: uppercase-first).
bodies: top-level and method bodies in full, nested function bodies collapsed.
full: the file verbatim, for API symmetry.

focus lifts named symbols to full body and full docs at any level.

Positioning

The agent-tooling space is busy. codefold's niche is a stateless, embeddable primitive: not 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 need granular single-file reads, codefold drops in as a library.