Codigest

Share the code context you choose with an AI: your project, a few files, what changed, or the command that failed.

한국어

Codigest is a command-line tool for the moment you ask ChatGPT, Claude or a coding agent about your code. It turns the part of your project you pick into one block of text you can paste into any chat.

A model only knows what you show it. Copying files by hand is slow, it is easy to miss the one file that matters, and it is just as easy to paste far more than the question needs. Codigest lets you decide what to share and then collects it for you: the whole project, a file and the files it imports, what changed since a point you marked, or a failing test with the code it points at.

What it does

• Bundles code you pick. The whole project, chosen files and folders, or the local files they import (Python, JS/TS), as one block with the file tree.
• Shows what changed. Text or function-level diffs since a baseline you set, without touching your Git history.
• Brings in terminal output. It records commands you run and can hand over a failing one together with the files its error points at.
• Says what it included. Every bundle reports its size, and pack gives the reason for each file and names the ones it left out.
• Keeps secrets out. .env files and keys are never included, and tokens in code or output are masked.
• Works with agents. Claude Code, Cursor and other MCP clients can request the same output.

Codigest does not call any AI model; it only prepares what you send to one. Everything runs on your machine, and your source files and Git history are only read.

_{One of the workflows below: a test fails, and one command collects what the model needs.}

Install

Install it with uv, which also fetches the Python version Codigest needs (3.15) and keeps it apart from your projects:

winget install --id astral-sh.uv                  # Windows (skip if you have uv)
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux

uv tool install codigest
uv tool update-shell                              # then restart your terminal

The command is codigest, or cdg for short. No setup is needed in your projects. If the install fails with a syntax error on lazy import, run uv self update and try again.

Every command below copies its result to the clipboard. Add -s to also print it (for pipes and redirects), -o FILE to also write it to a file, --no-copy to leave the clipboard alone, and -m "..." to put your question or instruction in it.

1. Share your project with an AI chat

Run scan in your project and paste:

cdg scan

$ cdg scan
Copied snapshot to clipboard
Snapshot 3 files, ~121 tokens

The clipboard now holds the file tree and every file, honoring .gitignore:

<project_snapshot project="project">
<project_structure>
├── .gitignore
├── prices.py
└── test_prices.py
</project_structure>
<source_code>
<file path=".gitignore">
.venv/
__pycache__/
.pytest_cache/
</file>

<file path="prices.py">
def apply_discount(price, percent):
    return price * (1 - percent)
</file>

<file path="test_prices.py">
from prices import apply_discount


def test_ten_percent():
    assert apply_discount(200, 10) == 180
</file>
</source_code>
</project_snapshot>

Large projects ask before copying (above 30k tokens or 100 files). For those, share less, as in the next section.

2. Share only part of it, or what changed

cdg scan src/app.py -r       # one file and the local files it imports, recursively
cdg scan src/billing/        # one folder
cdg digest                   # Python signatures and docstrings only, much smaller
cdg tree                     # just the file tree

To share what changed while you work, set a baseline first:

cdg mark                     # e.g. before a refactor
# ... work ...
cdg diff                     # text diff since the mark
cdg semdiff                  # Python: which functions and classes changed

A baseline is a private copy kept in .codigest/; your Git history is not touched.

3. Hand over a failing command

Run the command through cdg cap. The output looks exactly as it would without it; Codigest keeps a copy. Then ask for a pack:

cdg cap -- pytest -q        # or npm test, cargo test, go test ./..., make
cdg pack

$ cdg pack
Packed ~370 / 30,000 tokens
  failed   pytest -q (exit 1, just now)
  changes  uncommitted changes (git)
  + test_prices.py  line 5 in failing output
  + prices.py       changed
Copied pack to clipboard

Read it as: the failing command, your uncommitted Git changes, test_prices.py because the error points at its line 5, and prices.py because you edited it.

<context_pack project="project">
<terminal_history>
<command index="1" command="pytest -q" exit_code="1" cwd="~/project" duration="1.5s" at="2026-10-17T01:58:14+09:00">
<output>
F                                                                      [100%]
================================= FAILURES ==================================
_____________________________ test_ten_percent ______________________________

    def test_ten_percent():
&gt;       assert apply_discount(200, 10) == 180
E       assert -1800 == 180
E        +  where -1800 = apply_discount(200, 10)

test_prices.py:5: AssertionError
========================== short test summary info ==========================
FAILED test_prices.py::test_ten_percent - assert -1800 == 180
1 failed in 0.11s
</output>
</command>
</terminal_history>
<changes source="uncommitted changes (git)">
diff --git a/prices.py b/prices.py
index 3d691df..428752a 100644
--- a/prices.py
+++ b/prices.py
@@ -1,2 +1,2 @@
 def apply_discount(price, percent):
-    return price * (1 - percent / 100)
+    return price * (1 - percent)
</changes>
<file path="test_prices.py" reason="line 5 in failing output">
1: from prices import apply_discount
2: 
3: 
4: def test_ten_percent():
5:     assert apply_discount(200, 10) == 180
</file>
<file path="prices.py" reason="changed">
1: def apply_discount(price, percent):
2:     return price * (1 - percent)
</file>
</context_pack>

How pack decides

Plain cdg pack fills its token budget (default 30,000) in this order:

1. Files named in the output of the last failed command run in this project in the past hour: File "x.py", line 7 (Python), x.py:7 (pytest, ruff, gcc, rustc, eslint), x.ts(7,3) (tsc). Once the same command passes again, that failure is no longer used. A file that is only named in the output, not changed by you, comes as an excerpt: ten lines around each place the output points at, marked with a lines="40-60" attribute. Short files come whole.
2. Files you changed: uncommitted and untracked files in Git, or changes since cdg mark.
3. Tests that import those files (test_*.py, *_test.py, *.test.ts, *.spec.js, ...).
4. Project files they import: Python imports, and relative imports in JS/TS (./x, ./x.js for x.ts, ./dir for dir/index.ts).

When you name files, you get only those files. --with adds automatic sources back:

cdg pack src/prices.py                         # just this file
cdg pack src/prices.py --with tests            # this file and its tests
cdg pack --with changes                        # only your changes, no failure
cdg pack --with failure,changes,tests,imports  # the same as plain `cdg pack`

The failed command and the diff are always included when their source is on. Tokens are estimated at four characters each, so the budget is approximate.

Making it smoother

cdg term install hooks your shell so every command is captured without typing cdg cap (cdg term uninstall removes it). cdg term shows what was captured; see Terminal capture.

4. Let an agent fetch it

Connect your coding agent over MCP and it requests context itself instead of asking you to paste:

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

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

Reference

• All commands
• Terminal capture
• MCP tools
• Configuration
• Privacy and safety
• Upgrading from 0.8
• How it works
• Development

All commands

cdg --help lists them in the same groups.

Shared options: -s / --stdout also prints the result (status messages go to stderr), --no-copy skips the clipboard, -o FILE also writes it to a file, -m / --message adds an instruction. scan -l adds line numbers, scan -a ignores the config filters, scan -y skips the confirmation (CI). -r / --resolve on scan, diff, semdiff and digest also pulls in local files imported by the targets. cdg <command> --help lists everything.

Terminal capture

cdg cap streams the command's output live and records the command line, combined stdout/stderr, exit code and working directory. Captures from all projects share one store on your machine, so cap and term work in any directory.

cdg cap "npm run build | tail -20"  # quote pipelines
cdg term              # last command and its output
cdg term -n 3         # last 3
cdg term -f           # last failed one
cdg term --here -n 3  # last 3 run in this project
cdg term -i 2         # only the command from 2 runs ago
cdg term path         # where captures are stored (override with CODIGEST_HOME)
cdg term clear        # delete all captures

Commands not run through cap are read from the native shell history (PowerShell, bash, zsh, fish), without their output.

Automatic capture

cdg term install edits your PowerShell profile, ~/.bashrc and ~/.zshrc for whichever of these shells is installed; choose with --shell powershell|bash|zsh|all. On Windows, Git Bash counts as bash. Commands still run in your current session (cd, variables and functions work normally) and appear in your history as typed. Editors, pagers, REPLs and ssh are skipped.

• 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 the hooks: cdg term uninstall.

Limitations:

• Captured programs write to a pipe, not a TTY, so some lose colors or progress bars.
• In bash (4+) and zsh, multi-line commands (loops typed over several lines, heredocs), background jobs (cmd &) and lines using ! history expansion are not captured; they run normally. In bash, neither are lines that start with a subshell ( ... ).
• In bash the hook uses the DEBUG trap and keeps one set before the first prompt (starship, bash-preexec); a DEBUG trap set later replaces it.

MCP tools

The tools return the same text the CLI prints. None of them moves the baseline, and paths outside the project the server was started in are refused.

Configuration

cdg init writes .codigest/config.toml. The [filter] section controls which files every command considers:

[filter]
# Only these extensions (omit to include every non-ignored file)
extensions = [".py", ".ts", ".rs", ".md", ".json"]

# Extra exclusions, in .gitignore syntax (.gitignore itself is always honored)
exclude_patterns = [
    "*.lock",
    "tests/data/",
    "legacy_code/"
]

.git/, .codigest/, virtual environments, node_modules/ and __pycache__/ are always skipped.

Privacy and safety

• Credential files. .env* (except .env.example and similar templates), *.pem, *.key, *.p12, *.pfx, keystores, .netrc, .pgpass and SSH private keys are never included by any command. scan says which it withheld, pack lists them as omitted, and their hunks in a diff are replaced with a notice.
• Tokens in code and diffs. Private keys, JWTs, vendor tokens (OpenAI, GitHub, AWS, Google, Slack, GitLab, npm) and passwords in URLs are masked in everything Codigest outputs. Ordinary code such as token = get_token() is left alone.
• Secrets in captures. On top of that, terminal output is checked for password=... style values and Authorization headers before it is written to disk, and the output of credential commands (env, printenv, gh auth token, aws configure, ...) is never stored.
• These rules catch common formats, not every possible secret.
• Your project. No command changes your source files. Only mark and init create .codigest/, which init adds to .gitignore.
• Where captures live. cdg term path shows the file. On macOS and Linux it is readable only by you. cdg term clear deletes it.
• Nothing leaves your machine. Codigest makes no network requests. Context goes where you paste it, or to the MCP client you connected.

Upgrading from 0.8

• scan, diff, semdiff and digest no longer save into .codigest/*.txt; use -o FILE. diff --no-save and the like are gone.
• cdg init no longer sets a baseline; run cdg mark.
• cdg pack FILES packs only those files; add --with failure,changes,tests,imports for the previous behavior.
• Outputs no longer start with built-in instructions to the model ("You are an expert..."). Put your own with -m, or a template in .codigest/prompts.toml.

How it works

• Baseline. A Git repository at .codigest/anchor/.shadow_git, separate from your project's repository. The directory is not named .git so editors don't mistake it for yours. mark commits the current state to it; diff, semdiff, status and pack compare the working tree against it.
• Captures. One newline-delimited JSON file holds the last 200 commands; each output is capped at 64 KB, keeping the head and tail.
• Output. File contents are XML-escaped inside <file> blocks, written flush-left so no stray indentation reaches the prompt.
• MCP. The server is a small JSON-RPC loop over stdio. Each tool runs the regular CLI with -s --no-copy, so an agent sees exactly what you would paste.

Development

git clone https://github.com/NaNIsaac/codigest
cd codigest
uv run cdg --help              # run from the checkout
uv run --with pytest pytest -q # tests

The demo GIF is rendered from recorded output by docs/demo/make_gif.py; its docstring explains how to record a new one.

License

MIT. See LICENSE.