codigest 0.3.0

Human-Centered Codebase Context Manager for LLMs

Codigest

Codigest is a 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.

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.
• Python 3.14 Native: Built using modern Python features including PEP 750 Tag Strings for safe XML generation.

Installation

Requires Python 3.14+.

# Install via uv
git clone https://github.com/SJB7777/codigest.git
cd codigest
uv tool install .

Workflow & Commands

1. Initialization

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

codigest init

2. Full Context Snapshot (scan)

Scans the entire codebase and generates a structured XML snapshot.

• Output: .codigest/snapshot.xml
• Use Case: Providing the LLM with the full project context at the start of a session.
• Side Effect: Updates the internal Context Anchor to the current state.

codigest scan --m " Python 3.14 project. Do NOT use typing. List/Dict."

3. Incremental Changes (diff)

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

• Output: .codigest/changes.diff
• Use Case: "I modified 3 files. Here is exactly what changed since the last snapshot."
• Note: This is based on the internal Shadow Git, not your project's Git history.

codigest diff

4. Semantic Analysis (semdiff)

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

• Output: .codigest/semdiff.xml
• Use Case: "I refactored the API. Show me which functions were added, removed, or had their signatures changed."
• Benefit: Significantly reduces token usage compared to raw diffs by ignoring formatting/comment changes.

codigest semdiff

5. Architecture Digest (digest)

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

• Output: .codigest/digest.xml
• Use Case: "Don't read the implementation details. Just understand the class hierarchy and available methods."

codigest digest

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.

• 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.
• When you run semdiff, the tool parses the AST of the anchor version and the current version to detect logical drifts.

Safety Mechanisms

• structure-aware dedent: Ensures XML tags are perfectly aligned regardless of code indentation.
• Automatic Exclusion: Self-referential files (.codigest/) are automatically ignored to prevent recursion loops.

License

MIT License