Codigest

Codigest is a standalone CLI tool designed to extract, structure, and track the context of your codebase for Large Language Models (LLMs).

Unlike simple copy-paste tools, Codigest employs a Context Anchor system (Shadow Git) to track changes locally without polluting your main version control history. It also features Semantic Analysis to detect structural changes in your code.

Note: You can use the short alias cdg instead of codigest for faster typing.

Quickstart

uvx codigest scan          # try it without installing
uv tool install codigest  # or install the `cdg` command

cdg scan                  # whole project as LLM-ready XML (copied to clipboard)
cdg init && cdg diff      # set an anchor, later get only what changed
cdg cap -- pytest -q      # run a command and keep its output
cdg term -f               # hand the last failed command + output to your LLM
claude mcp add codigest -- cdg mcp   # let AI agents call all of the above

Core Philosophy

• Read-Only & Safe: Codigest never modifies your source code. It only reads, analyzes, and formats context.
• Context-Aware: Instead of dumping raw text, it structures code into XML snapshots designed for LLM comprehension.
• Session-Based Tracking: It maintains an internal anchor to track "work-in-progress" changes independently of your Git commits.
• Environment Isolated: Runs in its own isolated Python 3.15 environment via uv, ensuring it never conflicts with your project's dependencies.

Installation

Codigest runs as a global tool. You don't need to add it to your project's requirements.txt. We strongly recommend using uv for the best experience.

Step 1: Install uv

If you don't have uv installed, use Winget (Windows) or curl (macOS/Linux).

# Windows (via Winget)
winget install --id astral-sh.uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Install codigest

Install Codigest globally. uv will automatically manage the required Python 3.15 environment for you.

uv tool install codigest

Codigest needs Python 3.15. If uv reports a syntax error on lazy import, it picked an early 3.15 alpha: run uv self update (or upgrade uv) and install again.

Step 3: Update Path (Important!)

To run codigest (or cdg) from any terminal, ensure your tools directory is in your PATH.

uv tool update-shell

> Note: Restart your terminal (or VS Code) after this step to apply changes.

---

Workflow & Commands

Once installed, use the cdg command anywhere.

1. Initialization

Sets up the .codigest directory and captures the initial baseline anchor.

cdg init

2. Full Context Snapshot (scan)

Scans the codebase and generates a structured XML snapshot. Includes a Pre-flight Check to prevent accidental token overflow.

• Output: .codigest/snapshot.txt (or stdout with -s)
• Features:
• Smart Confirmation: Automatically skips confirmation for small contexts, but warns you for large ones (>30k tokens).
• Dependency Resolution (-r): Automatically finds and includes local files imported by your target files.
• Scope Control: You can specify folders or files to scan.
• Terminal Output (-s / --stdout): Output directly to stdout instead of saving to file.

# Basic scan (Interactive confirmation if large)
cdg scan

# Scan specific folder with dependency resolution (Smart Context)
cdg scan src/main.py -r

# Force execution without confirmation (Good for CI/CD)
cdg scan -y --message "Automated snapshot"

# Output directly to stdout
cdg scan -s

3. Incremental Changes (diff)

Tracks text-based changes between the last scan and the current working tree.

• Output: .codigest/changes.diff (or stdout with -s)
• Use Case: "I modified 3 files. Here is exactly what changed since the last snapshot."
• Note: Checks against the internal Shadow Git, enabling tracking without committing to the real Git.

cdg diff

# Output directly to stdout
cdg diff -s

4. Semantic Analysis (semdiff)

Analyzes structural changes (AST-based) rather than line-by-line text differences.

• Output: .codigest/semdiff.txt (or stdout with -s)
• Use Case: "I refactored the API. Show me added/removed functions or signature changes."
• Benefit: Reduces token usage by ignoring formatting/comment changes.

cdg semdiff

# Output directly to stdout
cdg semdiff -s

5. Project Tree (tree)

Visualizes the project structure. Respects .gitignore.

• Style: Professional, cleaner output without emojis for better readability.
• Use Case: Quickly verifying which files are being tracked.

cdg tree

6. Architecture Digest (digest)

Generates a high-level outline of the project structure (Classes, Functions, Methods only).

• Output: .codigest/digest.txt (or stdout with -s)
• Use Case: "Don't read the implementation details. Just understand the class hierarchy."

cdg digest

# Output directly to stdout
cdg digest -s

7. Environment Status (status)

Displays the health of .codigest, anchor snapshot baseline, pending working tree changes, and generated artifacts.

• Use Case: "Check what files have changed since my last snapshot and inspect the state of generated context artifacts."

cdg status

8. Environment Cleanup (clean)

Removes the .codigest/ environment and resets all context anchors and artifacts.

• Use Case: "Clean up context files and resets Codigest tracking."

# Interactive confirmation
cdg clean

# Force clean without prompt
cdg clean -y

9. Terminal Capture & Recall (cap, term)

Runs a command transparently (output still streams live) and records its command line, combined stdout/stderr, exit code and cwd in a machine-global store. term then recalls recent entries as a <terminal_history> block for your LLM. Works in any directory, no cdg init needed.

• Use Case: "This test failed. Here's exactly what I ran and what it printed."
• Safety: Known secret shapes (API keys, tokens, password=...) are redacted before anything touches disk. Output of credential commands (env, printenv, gh auth token, ...) is never stored.
• Fallback: Commands not run through cap are read from the native shell history (PowerShell, bash, zsh, fish), without output.

Automatic capture (PowerShell, bash, zsh): cdg term install hooks your shells so every command is captured without the cap prefix. It writes to your PowerShell profile, ~/.bashrc and ~/.zshrc, for whichever of these shells is installed; pick one with --shell powershell|bash|zsh|all. On Windows, Git Bash counts as bash. Commands run in your current session (cd, variables and functions behave normally) and your history shows them as typed. Editors, pagers, REPLs and ssh are skipped automatically.

• Skip one command: start the line with a space.
• Skip more programs: $env:CODIGEST_CAP_SKIP = '^\s*(myrepl|mytui)\b' (bash/zsh: export CODIGEST_CAP_SKIP='^(myrepl|mytui)( |$)', an extended regex)
• Disable for a session: $env:CODIGEST_NOCAP = 1 (bash/zsh: export CODIGEST_NOCAP=1). Remove: cdg term uninstall.
• Trade-off: captured programs write to a pipe, not a TTY, so some lose colors or progress bars.
• bash (4+) and zsh do not capture multi-line commands (loops typed over several lines, heredocs), background jobs (cmd &) or lines using ! history expansion; those run normally.

cdg term install    # capture everything automatically (PowerShell, bash, zsh)

# Run and capture (prefix with -- so flags reach the command)
cdg cap -- pytest -q
cdg cap "npm run build | tail -20"

# Recall
cdg term            # last command
cdg term -n 3       # last 3 commands
cdg term -i 2       # only the command from 2 runs ago
cdg term -f         # last failed command
cdg term --here -n 3  # last 3 commands run in this project

cdg term path       # where captures are stored (override with CODIGEST_HOME)
cdg term clear      # delete all captures

10. For AI Agents (mcp)

cdg mcp serves Codigest as an MCP server over stdio, so coding agents can pull context themselves instead of asking you to paste it.

Tool	Returns
terminal_history	Recent commands with output and exit code (count, failed, here: only this project, default on)
scan	Project snapshot (targets, resolve, message)
diff / semdiff	Text / structural changes since the anchor
digest	Signatures and docstrings only
tree	Directory tree

# Claude Code
claude mcp add --scope user codigest -- cdg mcp

Other clients (Cursor, VS Code, Claude Desktop): add a stdio server with command cdg and args ["mcp"].

---

Configuration

You can customize behavior in .codigest/config.toml.

[filter]
# Target extensions
extensions = [".py", ".ts", ".rs", ".md", ".json"]

# Exclude patterns (Gitignore syntax)
exclude_patterns = [
    "*.lock",
    "tests/data/",
    "legacy_code/"
]

[output]
format = "xml"

Architecture Details

Context Anchor (Shadow Git) Codigest maintains a hidden, lightweight Git repository inside .codigest/anchor/.shadow_git.

• It is renamed to .shadow_git to prevent VS Code and other IDEs from confusing it with your project's actual repository.
• When you run scan, the current state is committed to this anchor.
• When you run diff, the tool compares your working directory against this anchor.

Safety Mechanisms

• Pre-flight Check: Calculates estimated token count before processing to prevent context overflow errors.
• Structure-Aware Dedent: Ensures XML tags are perfectly aligned (flush-left) to prevent indentation artifacts in LLM prompts.
• XML Injection Protection: Automatically escapes content within XML tags.

License

MIT. See LICENSE.