cfold

cfold folds a set of files into a single JSON for LLM interaction, unfolds a modified JSON back onto a directory, and summarizes Python trees via AST.

• fold — bundle files into one JSON, with a line-count tree of the selection
• unfold — apply an LLM's modified JSON back onto a directory
• sum — AST map of a Python tree (classes, functions, imports)
• add / view — grow and inspect an existing fold

No prompts or instruction boilerplate: the fold is just {"files": [...]}.

Installation

uv pip install https://github.com/wr1/cfold.git
# or
uv tool install git+https://github.com/wr1/cfold

Usage

CLI help

Example — folding a directory

# fold explicit files
cfold fold src/main.py README.md -o codefold.json -c false

# fold a directory using extension heuristics
cfold fold src/ -o codefold.json -c false

# fold the current directory (no arguments)
cfold fold -o codefold.json -c false

# apply a modified fold
cfold unfold codefold_out.json -i ./project -o ./applied

# summarize a Python tree
cfold sum src/ -o summary.txt -c false

Commands

Command	Description
fold	Fold files or a directory into a JSON file
unfold	Apply changes from a modified JSON file
add	Add files to an existing fold file
view	View the contents of a fold file
sum	Summarize Python codebases via AST

File selection

When a directory is passed (or fold runs with no arguments), files are selected by extension heuristics — covering Python projects, markdown/MDX sites, Typst documents and Hayagriva YAML:

.py  .toml  .md  .mdx  .typ  .yaml  .yml

Common junk directories (.git, .venv, node_modules, __pycache__, build, dist, …) are skipped, and hidden directories are ignored. Pass explicit files to override the heuristics — explicit paths are always included as-is.

Shorthand globs work too, e.g. cfold fold "**.py" (expanded to **/*.py).

Fold file format

A fold is a single JSON object with a files array:

{
  "files": [
    { "path": "src/main.py", "content": "def main(): ..." },
    { "path": "old.py", "delete": true }
  ]
}

• path — relative to the working directory where fold ran.
• content — full file content (required unless delete is true).
• delete — set true to delete the file.

To edit a fold, an LLM returns the same shape:

• modify: set content, keep delete: false
• delete: set delete: true (content optional)
• add: a new entry with path + content
• rename: delete the old path and add the new one

Sum command

sum summarizes the structure of Python codebases via AST, producing an LLM-readable map of classes, functions and non-stdlib imports.

cfold sum codebase/ codebase2/ -o summary.txt -c false
cfold sum src/ -t true -o summary_with_tests.txt -c false   # include tests

Agent skill

SKILL.md at the repo root teaches agents when to use sum vs fold/unfold (and how to build a once-per-tip state pack). Symlink it into your agent skills dir, e.g. ln -sf /path/to/cfold/SKILL.md ~/.claude/skills/cfold/SKILL.md.

Development

A self-documenting Makefile wraps the common tasks (make help lists them):

make install   # uv sync
make test      # pytest with coverage
make lint      # ruff check src tests examples
make fmt       # ruff format src tests examples
make check     # lint then test

License

MIT