How dctx works
Five short animations. Each has a caption with its one point and a text version underneath it when motion is off. Use the Motion toggle in the header to switch between them. Planned features are marked planned.
- Two scopes, one binary
- Cost is calls times context
- Edit a file, keep the cache
- The giant folder
- The safe path
Two scopes, one binary
The same engine can live in two places on one machine. Knowing which one you are calling avoids most version confusion.
dctx is yours; a project's dctx is pinned by that project. dctx doctor lists every dctx in reach; release archives are cosign-signed.What the animation shows, step by step:
- One machine.
- The system
dctxonPATH(version 1.3.1) belongs to you and your agents; you decide when to upgrade it. - A project vendors its own
dctxinsidenode_modulesor a virtualenv, pinned by its lockfile and upgraded only when the project bumps it. The Node wrapper is on npm as @tejl/dctx from 1.3.1; the pip package is built in CI, with registry publication pending. - Both are the same engine at different versions.
- Interactive agents call the system binary; application code and CI call the project binary. A library never falls back to
PATHsilently. dctx doctorlists everydctxvisible from the current folder with its version, build commit, scope and SHA-256. Verify prebuilt archives againstSHA256SUMSand their cosign signatures.
Cost is calls times context
Whole-session cost depends on how many times the model reads the conversation, not only on how big one answer is.
What the illustration shows (made-up units, not a benchmark):
- Each model call reads the whole conversation: the task and prompt, plus every earlier tool result.
- Agent A uses grep and file reads: eight calls with small results. The conversation grows a little with each call, and each call reads all of it again.
- Agent B uses dctx: two calls that return larger, bounded pages, then it is done.
- Adding up what every call re-reads (the shaded areas): 164 units for agent A, 29 for agent B.
- So the number of calls matters more than the size of one result. The reverse also holds: dctx used without a plan can add calls instead of removing them, so count the calls of your own sessions. Choosing how to use dctx explains how to count them.
Edit a file, keep the cache
Prompt caches reuse bytes up to the first change. A stable order without timestamps keeps that prefix long.
What the animation shows:
- Turn 1: the pack is sent as one strip of bytes, file after file in a fixed order; the model provider caches it.
- You edit one file near the end of that order.
- Turn 2: the same tree gives the same bytes up to that file, so only the edited file and what follows are new.
- The cache reuses the unchanged prefix, here about three quarters of the bytes.
- If the pack began with a timestamp, the first byte would change and nothing would be reused. dctx answers carry no timestamps, digests or ages by default;
--metaadds them back. - Ordering rarely changed files first (prefix tiers) is planned.
The giant folder
For a very large folder, the plan is to catalog names once and index only the parts a task needs.
What the animation shows (the planned architecture):
- A 200 GB folder: photos, datasets, archives and a folder of repositories.
- A catalog (planned) sweeps it once and records names and sizes only; no file contents are read.
- A task arrives: fix invoice rounding.
- Two shards match the task:
repos/billingandrepos/shared-ui. - Only those two get symbol indexes; the rest of the tree is never indexed or copied.
- A bounded page, inside the budget and in a stable order, comes out of the two shards.
- What works today: start dctx on the sub-folder the task names (for example
dctx map find invoice --place repos/billing), with ignore rules for the rest.
The safe path
The shortest way to find out whether dctx helps your work, without changing several things at once.
If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Step by step:
- A new user with one agent and one repository.
- Install the system binary: download the archive for your platform from GitHub Releases, check it with
sha256sum -c SHA256SUMS --ignore-missing, then rundctx --version. - Pick one project, not your home folder or a huge tree. The system binary serves it; nothing is installed per project.
- Run
dctx map find NAMEfrom the project root, then read a result withdctx read ID, using the shell or an agent's shell tool. - Make the first call, for example
dctx pack . --for 'greet store' --budget 800, and read its last line:# end body_tokens=223 budget=800 dropped=0on the sample project. - Measure: per task, count the calls, the start-up tokens and the total input, and compare with grep and file reads on the same task. Receipts that count this for you are planned.
- Only then change one thing at a time.
Next: Choosing how to use dctx · Examples · Benchmarks