Metadata-Version: 2.5
Name: codigest
Version: 0.4.1
Summary: Human-Centered Codebase Context Manager for LLMs
Project-URL: Homepage, https://github.com/NaNIsaac/codigest
Project-URL: Repository, https://github.com/NaNIsaac/codigest
Project-URL: Issues, https://github.com/NaNIsaac/codigest/issues
Author-email: Isaac Yong <isaacyong@naver.com>
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.15
Requires-Dist: loguru
Requires-Dist: pathspec
Requires-Dist: pyperclip
Requires-Dist: rich
Requires-Dist: tomli-w
Requires-Dist: typer
Description-Content-Type: text/markdown

# 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

```bash
uv tool install codigest

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).

```powershell
# 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.

```bash
uv tool install codigest
```

### Step 3: Update Path (Important!)

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

```bash
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.

```bash
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.

```bash
# 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.

```bash
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.

```bash
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.

```bash
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."

```bash
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."

```bash
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."

```bash
# 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):** `cdg term install` hooks your PowerShell profile so *every* command is captured without the `cap` prefix. Commands run in your current session (`cd`, variables and functions behave normally). 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'`
* Disable for a session: `$env: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
cdg term install    # PowerShell: capture everything automatically

# 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 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](https://modelcontextprotocol.io) 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`) |
| `scan` | Project snapshot (`targets`, `resolve`, `message`) |
| `diff` / `semdiff` | Text / structural changes since the anchor |
| `digest` | Signatures and docstrings only |
| `tree` | Directory tree |

```bash
# 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`.

```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](LICENSE).
