codigest 0.8.0__tar.gz → 0.10.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codigest-0.10.0/PKG-INFO +546 -0
- codigest-0.10.0/README.md +520 -0
- codigest-0.10.0/pyproject.toml +160 -0
- codigest-0.10.0/pyproject.toml.orig +77 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/clean.py +1 -1
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/diff.py +10 -24
- codigest-0.10.0/src/codigest/commands/digest.py +79 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/init.py +2 -10
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/mcp.py +19 -2
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/pack.py +43 -43
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/scan.py +60 -59
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/semdiff.py +8 -23
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/status.py +0 -4
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/term.py +5 -4
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/tree.py +11 -4
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/cache.py +10 -12
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/common.py +14 -5
- codigest-0.10.0/src/codigest/core/outline.py +70 -0
- codigest-0.10.0/src/codigest/core/output.py +88 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/processor.py +20 -5
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/prompts.py +32 -79
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/redact.py +49 -7
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/resolver.py +37 -4
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/semdiff.py +68 -42
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/structure.py +11 -6
- codigest-0.10.0/src/codigest/core/tags.py +45 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/main.py +18 -15
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/options.py +13 -3
- codigest-0.8.0/.gitattributes +0 -1
- codigest-0.8.0/.github/workflows/publish.yml +0 -51
- codigest-0.8.0/.github/workflows/tests.yml +0 -15
- codigest-0.8.0/.gitignore +0 -87
- codigest-0.8.0/.python-version +0 -1
- codigest-0.8.0/CITATION.cff +0 -24
- codigest-0.8.0/LICENSE +0 -21
- codigest-0.8.0/PKG-INFO +0 -402
- codigest-0.8.0/README.ko.md +0 -371
- codigest-0.8.0/README.md +0 -376
- codigest-0.8.0/docs/demo/demo.gif +0 -0
- codigest-0.8.0/docs/demo/make_gif.py +0 -134
- codigest-0.8.0/docs/dogfood.md +0 -64
- codigest-0.8.0/pyproject.toml +0 -39
- codigest-0.8.0/server.json +0 -28
- codigest-0.8.0/src/codigest/commands/digest.py +0 -102
- codigest-0.8.0/src/codigest/core/output.py +0 -50
- codigest-0.8.0/src/codigest/core/tags.py +0 -37
- codigest-0.8.0/tests/test_pack.py +0 -87
- codigest-0.8.0/tests/test_shadow.py +0 -14
- codigest-0.8.0/tests/test_structure.py +0 -11
- codigest-0.8.0/tests/test_term_install.py +0 -61
- codigest-0.8.0/tests/test_termstore.py +0 -79
- codigest-0.8.0/uv.lock +0 -172
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/__init__.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/__main__.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/cap.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/commands/mark.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/config.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/git_ops.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/runner.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/scanner.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/shadow.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/shellhist.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/termstore.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/core/tokenizer.py +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/shell/hook.ps1 +0 -0
- {codigest-0.8.0 → codigest-0.10.0}/src/codigest/shell/hook.sh +0 -0
codigest-0.10.0/PKG-INFO
ADDED
|
@@ -0,0 +1,546 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: codigest
|
|
3
|
+
Version: 0.10.0
|
|
4
|
+
Summary: Human-Centered Codebase Context Manager for LLMs
|
|
5
|
+
Author: Isaac Yong
|
|
6
|
+
Author-email: Isaac Yong <isaacyong@naver.com>
|
|
7
|
+
License: MIT
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
13
|
+
Classifier: Topic :: Utilities
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Requires-Dist: typer
|
|
16
|
+
Requires-Dist: rich
|
|
17
|
+
Requires-Dist: loguru
|
|
18
|
+
Requires-Dist: pathspec
|
|
19
|
+
Requires-Dist: pyperclip
|
|
20
|
+
Requires-Dist: tomli-w
|
|
21
|
+
Requires-Python: >=3.15.0b1
|
|
22
|
+
Project-URL: Homepage, https://github.com/NaNIsaac/codigest
|
|
23
|
+
Project-URL: Repository, https://github.com/NaNIsaac/codigest
|
|
24
|
+
Project-URL: Issues, https://github.com/NaNIsaac/codigest/issues
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# Codigest
|
|
28
|
+
|
|
29
|
+
[](https://pypi.org/project/codigest/) [](https://github.com/NaNIsaac/codigest/actions/workflows/ci.yml) [](LICENSE)
|
|
30
|
+
|
|
31
|
+
<!-- mcp-name: io.github.NaNIsaac/codigest -->
|
|
32
|
+
|
|
33
|
+
**Share the code context you choose with an AI: your project, a few files, what changed, or the command that failed.**
|
|
34
|
+
|
|
35
|
+
[한국어](README.ko.md)
|
|
36
|
+
|
|
37
|
+
Codigest is a command-line tool for the moment you ask ChatGPT, Claude or a coding agent about
|
|
38
|
+
your code. It turns the part of your project you pick into one block of text you can paste into
|
|
39
|
+
any chat.
|
|
40
|
+
|
|
41
|
+
A model only knows what you show it. Copying files by hand is slow, it is easy to miss the one
|
|
42
|
+
file that matters, and it is just as easy to paste far more than the question needs. Codigest
|
|
43
|
+
lets you decide what to share and then collects it for you: the whole project, a file and the
|
|
44
|
+
files it imports, what changed since a point you marked, or a failing test with the code it points
|
|
45
|
+
at.
|
|
46
|
+
|
|
47
|
+
## What it does
|
|
48
|
+
|
|
49
|
+
- **Bundles code you pick.** The whole project, chosen files and folders, or the local files they
|
|
50
|
+
import (Python, JS/TS), as one block with the file tree.
|
|
51
|
+
- **Shows what changed.** Text or function-level diffs since a baseline you set, without touching
|
|
52
|
+
your Git history.
|
|
53
|
+
- **Brings in terminal output.** It records commands you run and can hand over a failing one
|
|
54
|
+
together with the files its error points at.
|
|
55
|
+
- **Says what it included.** Every bundle reports its size, and `pack` gives the reason for each
|
|
56
|
+
file and names the ones it left out.
|
|
57
|
+
- **Keeps secrets out.** `.env` files and keys are never included, and tokens in code or output
|
|
58
|
+
are masked.
|
|
59
|
+
- **Works with agents.** Claude Code, Cursor and other MCP clients can request the same output.
|
|
60
|
+
|
|
61
|
+
Codigest does not call any AI model; it only prepares what you send to one. Everything runs on
|
|
62
|
+
your machine.
|
|
63
|
+
|
|
64
|
+
<p align="center">
|
|
65
|
+
<img src="docs/demo/demo.gif" alt="cdg cap runs a failing pytest, then cdg pack bundles the failure, the test file it names and the changed file" width="760">
|
|
66
|
+
<br>
|
|
67
|
+
<sub>One of the workflows below: a test fails, and one command collects what the model needs.</sub>
|
|
68
|
+
</p>
|
|
69
|
+
|
|
70
|
+
## Install
|
|
71
|
+
|
|
72
|
+
Install it with [uv](https://docs.astral.sh/uv/), which also fetches the Python version Codigest
|
|
73
|
+
needs (3.15) and keeps it apart from your projects:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
winget install --id astral-sh.uv # Windows (skip if you have uv)
|
|
77
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux
|
|
78
|
+
|
|
79
|
+
uv tool install codigest
|
|
80
|
+
uv tool update-shell # then restart your terminal
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The command is `codigest`, or `cdg` for short. No setup is needed in your projects.
|
|
84
|
+
If the install fails with a syntax error on `lazy import`, run `uv self update` and try again.
|
|
85
|
+
|
|
86
|
+
In a terminal, every command below copies its result to the clipboard. Add `-s` to also print it,
|
|
87
|
+
`-o FILE` to also write it to a file, `--no-copy` to leave the clipboard alone, and `-m "..."` to
|
|
88
|
+
put your question or instruction in it. When the output goes to a pipe or a file instead
|
|
89
|
+
(`cdg scan > ctx.xml`, `cdg digest | less`, a script, a coding agent's shell), it is printed and
|
|
90
|
+
the clipboard is left alone; add `--copy` to copy it anyway.
|
|
91
|
+
|
|
92
|
+
## 1. Share your project with an AI chat
|
|
93
|
+
|
|
94
|
+
Run `scan` in your project and paste:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
cdg scan
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```console
|
|
101
|
+
$ cdg scan
|
|
102
|
+
Copied snapshot to clipboard
|
|
103
|
+
Snapshot 3 files, ~121 tokens
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The clipboard now holds the file tree and every file, honoring `.gitignore`:
|
|
107
|
+
|
|
108
|
+
```xml
|
|
109
|
+
<project_snapshot project="project">
|
|
110
|
+
<project_structure>
|
|
111
|
+
├── .gitignore
|
|
112
|
+
├── prices.py
|
|
113
|
+
└── test_prices.py
|
|
114
|
+
</project_structure>
|
|
115
|
+
<source_code>
|
|
116
|
+
<file path=".gitignore">
|
|
117
|
+
.venv/
|
|
118
|
+
__pycache__/
|
|
119
|
+
.pytest_cache/
|
|
120
|
+
</file>
|
|
121
|
+
|
|
122
|
+
<file path="prices.py">
|
|
123
|
+
def apply_discount(price, percent):
|
|
124
|
+
return price * (1 - percent)
|
|
125
|
+
</file>
|
|
126
|
+
|
|
127
|
+
<file path="test_prices.py">
|
|
128
|
+
from prices import apply_discount
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def test_ten_percent():
|
|
132
|
+
assert apply_discount(200, 10) == 180
|
|
133
|
+
</file>
|
|
134
|
+
</source_code>
|
|
135
|
+
</project_snapshot>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Large projects ask before copying (above 30k tokens or 100 files). For those, share less, as in
|
|
139
|
+
the next section.
|
|
140
|
+
|
|
141
|
+
## 2. Share only part of it, or what changed
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
cdg scan src/app.py -r # one file and the local files it imports, recursively
|
|
145
|
+
cdg scan src/billing/ docs/ # folders, files, or both
|
|
146
|
+
cdg scan src/app.py -l # with line numbers, so answers can say "line 42"
|
|
147
|
+
cdg scan src/app.py:40-80 # only lines 40 to 80, numbered (src/app.py:42 for one line)
|
|
148
|
+
cdg digest # signatures and docstrings only, much smaller
|
|
149
|
+
cdg digest src/billing/ # the same for one folder
|
|
150
|
+
cdg tree -L 2 # the file tree, two levels deep
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`digest` is the overview to start a conversation with. It lists every function, class and
|
|
154
|
+
top-level variable of Python files, and the functions and `%%` sections of MATLAB files, in the
|
|
155
|
+
order they appear, with the line they start on and the first line of their docstring (or, in
|
|
156
|
+
MATLAB, of their help comment). Class attributes and dataclass fields are listed with their
|
|
157
|
+
values, shortened when long:
|
|
158
|
+
|
|
159
|
+
```console
|
|
160
|
+
$ cdg digest -s
|
|
161
|
+
<code_digest project="project" contents="signatures and docstrings, no bodies">
|
|
162
|
+
<project_structure>
|
|
163
|
+
├── .gitignore
|
|
164
|
+
├── legacy
|
|
165
|
+
│ └── discount.m
|
|
166
|
+
├── prices.py
|
|
167
|
+
└── test_prices.py
|
|
168
|
+
</project_structure>
|
|
169
|
+
<file path="legacy/discount.m">
|
|
170
|
+
1: function p = discount(price, percent)
|
|
171
|
+
Price after taking off percent percent.
|
|
172
|
+
3: %% Apply
|
|
173
|
+
</file>
|
|
174
|
+
<file path="prices.py">
|
|
175
|
+
1: TAX_RATE = 0.1
|
|
176
|
+
4: def apply_discount(price: float, percent: float) -> float
|
|
177
|
+
Price after taking off `percent` percent.
|
|
178
|
+
9: class Cart
|
|
179
|
+
Items and the discount that applies to all of them.
|
|
180
|
+
12: def __init__(self, percent: float=0)
|
|
181
|
+
16: def total(self) -> float
|
|
182
|
+
Sum after discount and tax.
|
|
183
|
+
</file>
|
|
184
|
+
<file path="test_prices.py">
|
|
185
|
+
4: def test_ten_percent()
|
|
186
|
+
</file>
|
|
187
|
+
</code_digest>
|
|
188
|
+
Digest 3 files, ~192 tokens
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
A model that has seen this can ask for exactly what it needs ("show me `Cart.total`"), and
|
|
192
|
+
`cdg scan prices.py:16-19` gives it just that method, numbered the same way:
|
|
193
|
+
|
|
194
|
+
```console
|
|
195
|
+
$ cdg scan prices.py:16-19 -s
|
|
196
|
+
<project_snapshot project="project">
|
|
197
|
+
<project_structure>
|
|
198
|
+
└── prices.py
|
|
199
|
+
</project_structure>
|
|
200
|
+
<source_code>
|
|
201
|
+
<file path="prices.py" lines="16-19">
|
|
202
|
+
16: def total(self) -> float:
|
|
203
|
+
17: """Sum after discount and tax."""
|
|
204
|
+
18: subtotal = sum(apply_discount(p, self.percent) for p in self.items)
|
|
205
|
+
19: return subtotal * (1 + TAX_RATE)
|
|
206
|
+
</file>
|
|
207
|
+
</source_code>
|
|
208
|
+
</project_snapshot>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`tree -L` keeps a large or vendored folder from flooding the output:
|
|
212
|
+
|
|
213
|
+
```console
|
|
214
|
+
$ cdg tree -L 1
|
|
215
|
+
├── .gitignore
|
|
216
|
+
├── legacy/ (1 file)
|
|
217
|
+
├── prices.py
|
|
218
|
+
└── test_prices.py
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
To share what changed while you work, set a baseline first:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
cdg mark # e.g. before a refactor
|
|
225
|
+
# ... work ...
|
|
226
|
+
cdg diff # text diff since the mark
|
|
227
|
+
cdg semdiff # Python: which functions and classes changed
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
A baseline is a private copy kept in `.codigest/`; your Git history is not touched.
|
|
231
|
+
|
|
232
|
+
## 3. Hand over a failing command
|
|
233
|
+
|
|
234
|
+
Run the command through `cdg cap`. The output looks exactly as it would without it; Codigest
|
|
235
|
+
keeps a copy. Then ask for a pack:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
cdg cap -- pytest -q # or npm test, cargo test, go test ./..., make
|
|
239
|
+
cdg pack
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
```console
|
|
243
|
+
$ cdg pack
|
|
244
|
+
Packed ~370 / 30,000 tokens
|
|
245
|
+
failed pytest -q (exit 1, just now)
|
|
246
|
+
changes uncommitted changes (git)
|
|
247
|
+
+ test_prices.py line 5 in failing output
|
|
248
|
+
+ prices.py changed
|
|
249
|
+
Copied pack to clipboard
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Read it as: the failing command, your uncommitted Git changes, `test_prices.py` because the error
|
|
253
|
+
points at its line 5, and `prices.py` because you edited it.
|
|
254
|
+
|
|
255
|
+
<details>
|
|
256
|
+
<summary>What exactly was copied</summary>
|
|
257
|
+
|
|
258
|
+
```xml
|
|
259
|
+
<context_pack project="project">
|
|
260
|
+
<terminal_history>
|
|
261
|
+
<command index="1" command="pytest -q" exit_code="1" cwd="~/project" duration="1.5s" at="2026-10-17T01:58:14+09:00">
|
|
262
|
+
<output>
|
|
263
|
+
F [100%]
|
|
264
|
+
================================= FAILURES ==================================
|
|
265
|
+
_____________________________ test_ten_percent ______________________________
|
|
266
|
+
|
|
267
|
+
def test_ten_percent():
|
|
268
|
+
> assert apply_discount(200, 10) == 180
|
|
269
|
+
E assert -1800 == 180
|
|
270
|
+
E + where -1800 = apply_discount(200, 10)
|
|
271
|
+
|
|
272
|
+
test_prices.py:5: AssertionError
|
|
273
|
+
========================== short test summary info ==========================
|
|
274
|
+
FAILED test_prices.py::test_ten_percent - assert -1800 == 180
|
|
275
|
+
1 failed in 0.11s
|
|
276
|
+
</output>
|
|
277
|
+
</command>
|
|
278
|
+
</terminal_history>
|
|
279
|
+
<changes source="uncommitted changes (git)">
|
|
280
|
+
diff --git a/prices.py b/prices.py
|
|
281
|
+
index 3d691df..428752a 100644
|
|
282
|
+
--- a/prices.py
|
|
283
|
+
+++ b/prices.py
|
|
284
|
+
@@ -1,2 +1,2 @@
|
|
285
|
+
def apply_discount(price, percent):
|
|
286
|
+
- return price * (1 - percent / 100)
|
|
287
|
+
+ return price * (1 - percent)
|
|
288
|
+
</changes>
|
|
289
|
+
<file path="test_prices.py" reason="line 5 in failing output">
|
|
290
|
+
1: from prices import apply_discount
|
|
291
|
+
2:
|
|
292
|
+
3:
|
|
293
|
+
4: def test_ten_percent():
|
|
294
|
+
5: assert apply_discount(200, 10) == 180
|
|
295
|
+
</file>
|
|
296
|
+
<file path="prices.py" reason="changed">
|
|
297
|
+
1: def apply_discount(price, percent):
|
|
298
|
+
2: return price * (1 - percent)
|
|
299
|
+
</file>
|
|
300
|
+
</context_pack>
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Files that did not fit the budget would be listed in an `<omitted>` block, so the model knows
|
|
304
|
+
what it is not seeing.
|
|
305
|
+
|
|
306
|
+
</details>
|
|
307
|
+
|
|
308
|
+
### How `pack` decides
|
|
309
|
+
|
|
310
|
+
Plain `cdg pack` fills its token budget (default 30,000) in this order:
|
|
311
|
+
|
|
312
|
+
1. Files named in the output of the last failed command run in this project in the past hour:
|
|
313
|
+
`File "x.py", line 7` (Python), `x.py:7` (pytest, ruff, gcc, rustc, eslint), `x.ts(7,3)` (tsc).
|
|
314
|
+
Once the same command passes again, that failure is no longer used. A file that is only named
|
|
315
|
+
in the output, not changed by you, comes as an excerpt: ten lines around each place the output
|
|
316
|
+
points at, marked with a `lines="40-60"` attribute. Short files come whole.
|
|
317
|
+
2. Files you changed: uncommitted and untracked files in Git, or changes since `cdg mark`.
|
|
318
|
+
3. Tests that import those files (`test_*.py`, `*_test.py`, `*.test.ts`, `*.spec.js`, ...).
|
|
319
|
+
4. Project files they import: Python imports, and relative imports in JS/TS (`./x`, `./x.js` for
|
|
320
|
+
`x.ts`, `./dir` for `dir/index.ts`).
|
|
321
|
+
|
|
322
|
+
When you name files, you get only those files. `--with` adds automatic sources back:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
cdg pack src/prices.py # just this file
|
|
326
|
+
cdg pack src/prices.py --with tests # this file and its tests
|
|
327
|
+
cdg pack --with changes # only your changes, no failure
|
|
328
|
+
cdg pack --with failure,changes,tests,imports # the same as plain `cdg pack`
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
The failed command and the diff are always included when their source is on. Tokens are estimated
|
|
332
|
+
at four characters each, so the budget is approximate.
|
|
333
|
+
|
|
334
|
+
### Making it smoother
|
|
335
|
+
|
|
336
|
+
`cdg term install` hooks your shell so every command is captured without typing `cdg cap`
|
|
337
|
+
(`cdg term uninstall` removes it). `cdg term` shows what was captured; see
|
|
338
|
+
[Terminal capture](#terminal-capture).
|
|
339
|
+
|
|
340
|
+
## 4. Let an agent fetch it
|
|
341
|
+
|
|
342
|
+
Connect your coding agent over MCP and it requests context itself instead of asking you to paste:
|
|
343
|
+
|
|
344
|
+
```bash
|
|
345
|
+
claude mcp add --scope user codigest -- cdg mcp # Claude Code
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Other clients (Cursor, VS Code, Claude Desktop): add a stdio server with command `cdg` and args
|
|
349
|
+
`["mcp"]`. The tools are listed under [MCP tools](#mcp-tools).
|
|
350
|
+
|
|
351
|
+
An agent that can run shell commands needs no setup at all. Its shell is not a terminal, so `cdg`
|
|
352
|
+
prints the result for it and never touches your clipboard. A way of working that suits agents:
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
cdg tree -L 2 # where things are
|
|
356
|
+
cdg digest src/ # what is defined where, with line numbers
|
|
357
|
+
cdg scan src/prices.py:16-19 # read the parts that matter, numbered the same way
|
|
358
|
+
cdg mark # before editing
|
|
359
|
+
cdg semdiff # afterwards: which functions it changed
|
|
360
|
+
cdg cap -- pytest -q && cdg pack # run the tests; on failure, the pack has what to fix
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
The code in every block is exactly as written in the file (`->`, `<`, `&` are not escaped), so
|
|
364
|
+
code copied out of it can be pasted back. A large `scan` with nobody to answer the size question
|
|
365
|
+
stops with a hint instead of waiting; `-y` takes it all.
|
|
366
|
+
|
|
367
|
+
## Reference
|
|
368
|
+
|
|
369
|
+
- [All commands](#all-commands)
|
|
370
|
+
- [Terminal capture](#terminal-capture)
|
|
371
|
+
- [MCP tools](#mcp-tools)
|
|
372
|
+
- [Configuration](#configuration)
|
|
373
|
+
- [Privacy and safety](#privacy-and-safety)
|
|
374
|
+
- [Upgrading from 0.9](#upgrading-from-09)
|
|
375
|
+
- [How it works](#how-it-works)
|
|
376
|
+
- [Development](#development)
|
|
377
|
+
|
|
378
|
+
### All commands
|
|
379
|
+
|
|
380
|
+
`cdg --help` lists them in the same groups.
|
|
381
|
+
|
|
382
|
+
| Command | What it gives you | Writes to your project |
|
|
383
|
+
| --- | --- | --- |
|
|
384
|
+
| `scan` | The whole project, or chosen paths, as one block | nothing |
|
|
385
|
+
| `digest` | Numbered signatures and docstrings, no bodies (Python, MATLAB) | nothing |
|
|
386
|
+
| `tree` | Project tree (`-L N` limits the depth) | nothing |
|
|
387
|
+
| `mark` | Sets the baseline | `.codigest/` |
|
|
388
|
+
| `diff` | Text diff since the baseline | nothing |
|
|
389
|
+
| `semdiff` | Function and class level changes since the baseline (Python) | nothing |
|
|
390
|
+
| `cap` | Runs a command and keeps its output | nothing |
|
|
391
|
+
| `term` | Recent captured commands with output | nothing |
|
|
392
|
+
| `pack` | Last failure, the files it names, your changes | nothing |
|
|
393
|
+
| `mcp` | MCP server for agents | nothing |
|
|
394
|
+
| `status` | What `pack` would use here: last failure, changes, baseline | nothing |
|
|
395
|
+
| `init` | `.codigest/config.toml` for [file filters](#configuration) | `.codigest/`, `.gitignore` |
|
|
396
|
+
| `clean` | Deletes `.codigest/` (asks first, `-y` to skip) | removes `.codigest/` |
|
|
397
|
+
|
|
398
|
+
Shared options: `-s` / `--stdout` also prints the result (status messages go to stderr; on by
|
|
399
|
+
default when piped), `--copy` / `--no-copy` overrides the clipboard default (copy in a terminal,
|
|
400
|
+
not when piped), `-o FILE` also writes it to a file, `-m` / `--message` adds an
|
|
401
|
+
instruction.
|
|
402
|
+
`scan -l` adds line numbers, `scan -a` ignores the config filters, `scan -y` skips the
|
|
403
|
+
confirmation (CI). `-r` / `--resolve` on `scan`, `diff`, `semdiff` and `digest` also pulls in
|
|
404
|
+
local files imported by the targets. `cdg <command> --help` lists everything.
|
|
405
|
+
|
|
406
|
+
### Terminal capture
|
|
407
|
+
|
|
408
|
+
`cdg cap` streams the command's output live and records the command line, combined
|
|
409
|
+
stdout/stderr, exit code and working directory. Captures from all projects share one store on
|
|
410
|
+
your machine, so `cap` and `term` work in any directory.
|
|
411
|
+
|
|
412
|
+
```bash
|
|
413
|
+
cdg cap "npm run build | tail -20" # quote pipelines
|
|
414
|
+
cdg term # last command and its output
|
|
415
|
+
cdg term -n 3 # last 3
|
|
416
|
+
cdg term -f # last failed one
|
|
417
|
+
cdg term --here -n 3 # last 3 run in this project
|
|
418
|
+
cdg term -i 2 # only the command from 2 runs ago
|
|
419
|
+
cdg term path # where captures are stored (override with CODIGEST_HOME)
|
|
420
|
+
cdg term clear # delete all captures
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
Commands not run through `cap` are read from the native shell history (PowerShell, bash, zsh,
|
|
424
|
+
fish), without their output.
|
|
425
|
+
|
|
426
|
+
#### Automatic capture
|
|
427
|
+
|
|
428
|
+
`cdg term install` edits your PowerShell profile, `~/.bashrc` and `~/.zshrc` for whichever of
|
|
429
|
+
these shells is installed; choose with `--shell powershell|bash|zsh|all`. On Windows, Git Bash
|
|
430
|
+
counts as bash. Commands still run in your current session (`cd`, variables and functions work
|
|
431
|
+
normally) and appear in your history as typed. Editors, pagers, REPLs and `ssh` are skipped.
|
|
432
|
+
|
|
433
|
+
- Skip one command: start the line with a space.
|
|
434
|
+
- Skip more programs: `$env:CODIGEST_CAP_SKIP = '^\s*(myrepl|mytui)\b'` (bash/zsh:
|
|
435
|
+
`export CODIGEST_CAP_SKIP='^(myrepl|mytui)( |$)'`, an extended regex).
|
|
436
|
+
- Disable for a session: `$env:CODIGEST_NOCAP = 1` (bash/zsh: `export CODIGEST_NOCAP=1`).
|
|
437
|
+
- Remove the hooks: `cdg term uninstall`.
|
|
438
|
+
|
|
439
|
+
Limitations:
|
|
440
|
+
|
|
441
|
+
- Captured programs write to a pipe, not a TTY, so some lose colors or progress bars.
|
|
442
|
+
- In bash (4+) and zsh, multi-line commands (loops typed over several lines, heredocs),
|
|
443
|
+
background jobs (`cmd &`) and lines using `!` history expansion are not captured; they run
|
|
444
|
+
normally. In bash, neither are lines that start with a subshell `( ... )`.
|
|
445
|
+
- In bash the hook uses the DEBUG trap and keeps one set before the first prompt (starship,
|
|
446
|
+
bash-preexec); a DEBUG trap set later replaces it.
|
|
447
|
+
|
|
448
|
+
### MCP tools
|
|
449
|
+
|
|
450
|
+
| Tool | Returns |
|
|
451
|
+
| --- | --- |
|
|
452
|
+
| `pack` | Last failure, the files it names, changes and their imports, cut to a budget (`targets`, `with`, `budget`, `message`) |
|
|
453
|
+
| `terminal_history` | Recent commands with output and exit code (`count`, `failed`, `here`: only this project, default on) |
|
|
454
|
+
| `scan` | Project snapshot (`targets`, `resolve`, `message`) |
|
|
455
|
+
| `diff` / `semdiff` | Text / structural changes since the baseline |
|
|
456
|
+
| `digest` | Signatures and docstrings only |
|
|
457
|
+
| `tree` | Directory tree |
|
|
458
|
+
|
|
459
|
+
The tools return the same text the CLI prints. None of them moves the baseline, and paths
|
|
460
|
+
outside the project the server was started in are refused.
|
|
461
|
+
|
|
462
|
+
### Configuration
|
|
463
|
+
|
|
464
|
+
`cdg init` writes `.codigest/config.toml`. The `[filter]` section controls which files every
|
|
465
|
+
command considers:
|
|
466
|
+
|
|
467
|
+
```toml
|
|
468
|
+
[filter]
|
|
469
|
+
# Only these extensions (omit to include every non-ignored file)
|
|
470
|
+
extensions = [".py", ".ts", ".rs", ".md", ".json"]
|
|
471
|
+
|
|
472
|
+
# Extra exclusions, in .gitignore syntax (.gitignore itself is always honored)
|
|
473
|
+
exclude_patterns = [
|
|
474
|
+
"*.lock",
|
|
475
|
+
"tests/data/",
|
|
476
|
+
"legacy_code/"
|
|
477
|
+
]
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
`.git/`, `.codigest/`, virtual environments, `node_modules/` and `__pycache__/` are always
|
|
481
|
+
skipped.
|
|
482
|
+
|
|
483
|
+
### Privacy and safety
|
|
484
|
+
|
|
485
|
+
- **Credential files.** `.env*` (except `.env.example` and similar templates), `*.pem`, `*.key`,
|
|
486
|
+
`*.p12`, `*.pfx`, keystores, `.netrc`, `.pgpass` and SSH private keys are never included by any
|
|
487
|
+
command. `scan` says which it withheld, `pack` lists them as omitted, and their hunks in a diff
|
|
488
|
+
are replaced with a notice.
|
|
489
|
+
- **Tokens in code and diffs.** Private keys, JWTs, vendor tokens (OpenAI, GitHub, AWS, Google,
|
|
490
|
+
Slack, GitLab, npm) and passwords in URLs are masked in everything Codigest outputs. Ordinary
|
|
491
|
+
code such as `token = get_token()` is left alone.
|
|
492
|
+
- **Secrets in captures.** On top of that, terminal output is checked for `password=...` style
|
|
493
|
+
values and `Authorization` headers before it is written to disk, and the output of credential
|
|
494
|
+
commands (`env`, `printenv`, `gh auth token`, `aws configure`, ...) is never stored.
|
|
495
|
+
- These rules catch common formats, not every possible secret.
|
|
496
|
+
- **Your project.** No command changes your source files. Only `mark` and `init` create
|
|
497
|
+
`.codigest/`, which `init` adds to `.gitignore`.
|
|
498
|
+
- **Where captures live.** `cdg term path` shows the file. On macOS and Linux it is readable only
|
|
499
|
+
by you. `cdg term clear` deletes it.
|
|
500
|
+
- **Nothing leaves your machine.** Codigest makes no network requests. Context goes where you
|
|
501
|
+
paste it, or to the MCP client you connected.
|
|
502
|
+
|
|
503
|
+
### Upgrading from 0.9
|
|
504
|
+
|
|
505
|
+
- Piped or redirected output is printed without `-s` and no longer copied; add `--copy` if a
|
|
506
|
+
script relied on the clipboard.
|
|
507
|
+
- `<file>` blocks hold the code verbatim instead of XML-escaped. A custom template in
|
|
508
|
+
`.codigest/prompts.toml` now receives the blocks unescaped too; only `{instruction}` is escaped.
|
|
509
|
+
- `digest` output is numbered, in source order, with docstrings, and takes several paths.
|
|
510
|
+
|
|
511
|
+
### Upgrading from 0.8
|
|
512
|
+
|
|
513
|
+
- `scan`, `diff`, `semdiff` and `digest` no longer save into `.codigest/*.txt`; use `-o FILE`.
|
|
514
|
+
`diff --no-save` and the like are gone.
|
|
515
|
+
- `cdg init` no longer sets a baseline; run `cdg mark`.
|
|
516
|
+
- `cdg pack FILES` packs only those files; add `--with failure,changes,tests,imports` for the
|
|
517
|
+
previous behavior.
|
|
518
|
+
- Outputs no longer start with built-in instructions to the model ("You are an expert..."). Put
|
|
519
|
+
your own with `-m`, or a template in `.codigest/prompts.toml`.
|
|
520
|
+
|
|
521
|
+
### How it works
|
|
522
|
+
|
|
523
|
+
- **Baseline.** A Git repository at `.codigest/anchor/.shadow_git`, separate from your project's
|
|
524
|
+
repository. `mark`
|
|
525
|
+
commits the current state to it; `diff`, `semdiff`, `status` and `pack` compare the working tree
|
|
526
|
+
against it.
|
|
527
|
+
- **Captures.** One newline-delimited JSON file holds the last 200 commands; each output is capped
|
|
528
|
+
at 64 KB, keeping the head and tail.
|
|
529
|
+
- **Output.** File contents go into `<file>` blocks verbatim. Only a closing tag of one of
|
|
530
|
+
Codigest's own blocks inside a file (a literal `</file>`) is written as `</file>`, so it
|
|
531
|
+
cannot end the block early.
|
|
532
|
+
- **MCP.** The server is a small JSON-RPC loop over stdio. Each tool runs the regular CLI with
|
|
533
|
+
`-s --no-copy`, so an agent sees exactly what you would paste.
|
|
534
|
+
|
|
535
|
+
### Development
|
|
536
|
+
|
|
537
|
+
```bash
|
|
538
|
+
git clone https://github.com/NaNIsaac/codigest
|
|
539
|
+
cd codigest
|
|
540
|
+
uv run cdg --help # run from the checkout
|
|
541
|
+
uv run --with pytest pytest -q # tests
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
## License
|
|
545
|
+
|
|
546
|
+
MIT. See [LICENSE](LICENSE).
|