Quickstart

Configuration

Codecrate reads configuration from the repository root. It will look for:

  • .codecrate.toml (preferred, if present)

  • codecrate.toml (fallback)

  • pyproject.toml under [tool.codecrate] (fallback if no codecrate TOML file exists)

Precedence (highest first):

  • CLI flags

  • .codecrate.toml / codecrate.toml

  • pyproject.toml [tool.codecrate]

Example:

[codecrate]
output = "context"
security_check = true
security_content_sniff = false
symbol_backend = "auto"
max_file_bytes = 0
max_total_bytes = 0
max_file_tokens = 0
max_total_tokens = 0
max_workers = 0

Installation

For agent-oriented usage patterns, see Agent Workflows.

From source (recommended while iterating):

pip install -e .

If you build docs locally, install doc deps too (example):

pip install -U sphinx sphinx-rtd-theme

Create a context pack

Pack a repository into context.md:

codecrate pack /path/to/repo -o context.md
codecrate pack /path/to/repo -o context.md --profile agent
codecrate pack /path/to/repo -o context.md --profile hybrid
codecrate pack /path/to/repo -o context.md --manifest-json
codecrate pack /path/to/repo -o context.md --index-json
codecrate pack /path/to/repo -o context.md --index-json-mode normalized
codecrate pack /path/to/repo -o context.md --include "*.java" --symbol-backend tree-sitter --index-json

Pack multiple repositories into one output root:

codecrate pack /path/to/repo1 /path/to/repo2 -o multi
codecrate pack --repo /path/to/repo1 --repo /path/to/repo2 -o multi

Common options:

  • --dedupe: deduplicate identical function bodies (enables stub layout when effective)

  • --profile {human,agent,lean-agent,hybrid,portable,portable-agent}: choose output defaults for human reading, agent tooling, lean retrieval, or portable reconstruction

  • --layout {auto,stubs,full}: control output layout

  • --manifest/--no-manifest: include or omit the Manifest section (omit only for LLM-only packs)

  • --split-max-chars N: emit .index.md and .partN.md split outputs for LLMs

  • --split-strict: fail if a logical split block exceeds the requested limit

  • --split-allow-cut-files: explicitly cut oversized file blocks across multiple parts and record part membership in index-json metadata

  • --max-file-bytes / --max-file-tokens: skip oversized single files with a warning

  • --max-total-bytes / --max-total-tokens: fail fast when total included size exceeds budget

  • --security-redaction: mask flagged files instead of skipping

  • --safety-report: include a Safety Report section with reasons

  • --index-json [PATH]: emit the retrieval sidecar for tooling and agents while preserving profile/config sidecar mode defaults

  • --index-json-mode full|compact|minimal|normalized: choose full v1, compact/minimal v2, or normalized v3 sidecars; agent and portable-agent default to normalized and hybrid defaults to full

  • --index-json-lookup / --no-index-json-lookup: include or trim v2 lookup maps

  • --index-json-symbol-index-lines / --no-index-json-symbol-index-lines: include or trim compact v2 symbol index line ranges

  • --symbol-backend auto|tree-sitter|none: control non-Python symbol extraction and record requested/used backend metadata in index-json output The sidecar includes short display IDs for markdown references and stronger machine IDs for tool-side caching and lookup.

  • --stdin / --stdin0: pack an explicit file list from stdin

  • --print-files / --print-skipped: debug selected and skipped files

  • --print-rules: debug-print effective include/exclude/ignore/safety rules

  • --include-preset: switch between python-only, python+docs, and everything

  • --encoding-errors {replace,strict}: UTF-8 decode policy while reading files

Unpack a context pack

Reconstruct files from a pack into a directory:

codecrate unpack context.md -o /tmp/reconstructed
codecrate unpack context.md -o /tmp/reconstructed --check-machine-header --strict --fail-on-warning

Note

Packs created with --no-manifest are LLM-only and cannot be used for unpack, patch, or validate-pack.

Portable reconstruction without installing Codecrate

Generate a standalone unpacker next to a portable pack:

codecrate pack /path/to/repo -o context.md --profile portable --emit-standalone-unpacker
python3 -S context.unpack.py context.md -o /tmp/reconstructed --check-machine-header --strict --fail-on-warning

This standalone script uses only the Python standard library and reconstructs from the sibling unsplit markdown pack by default.

On Windows, use py -3 -S context.unpack.py context.md -o reconstructed --check-machine-header --strict --fail-on-warning.

If you need a token-efficient portable pack instead, you can still emit the standalone unpacker with --layout stubs.

Generate a patch Markdown

Given an older pack as baseline and a current repo root, generate a diff-only patch:

codecrate patch old_context.md /path/to/repo -o patch.md

Apply a patch Markdown

Apply the patch to a repo:

codecrate apply patch.md /path/to/repo
codecrate apply patch.md /path/to/repo --dry-run
codecrate apply patch.md /path/to/repo --check-baseline
codecrate apply patch.md /path/to/repo --ignore-baseline

Apply validates baseline metadata embedded in generated patches and refuses to apply when baseline file hashes do not match.

Use --check-baseline to require metadata and --ignore-baseline to skip baseline verification.

Validate a context pack

Validate internal consistency (and optionally compare against a repo on disk):

codecrate validate-pack context.md
codecrate validate-pack context.md --root /path/to/repo
codecrate validate-pack context.md --strict
codecrate validate-pack context.md --root /path/to/repo --fail-on-root-drift
codecrate validate-pack context.md --fail-on-warning
codecrate validate-pack context.md --json

Doctor checks

Inspect config precedence, ignore files, and backend availability:

codecrate --version
codecrate doctor /path/to/repo