dctx1.3.1
Docs

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

The same engine can live in two places on one machine. Knowing which one you are calling avoids most version confusion.

Same engine, different owner. The system 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:

  1. One machine.
  2. The system dctx on PATH (version 1.3.1) belongs to you and your agents; you decide when to upgrade it.
  3. A project vendors its own dctx inside node_modules or 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.
  4. Both are the same engine at different versions.
  5. Interactive agents call the system binary; application code and CI call the project binary. A library never falls back to PATH silently.
  6. dctx doctor lists every dctx visible from the current folder with its version, build commit, scope and SHA-256. Verify prebuilt archives against SHA256SUMS and 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.

Calls cost more than output size. An illustration, not a measured result: every call re-reads the whole conversation so far.

What the illustration shows (made-up units, not a benchmark):

  1. Each model call reads the whole conversation: the task and prompt, plus every earlier tool result.
  2. 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.
  3. Agent B uses dctx: two calls that return larger, bounded pages, then it is done.
  4. Adding up what every call re-reads (the shaded areas): 164 units for agent A, 29 for agent B.
  5. 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.

Edit a file, keep the cache. Illustrative sizes. The pack keeps a stable order and carries no timestamps by default, so a prompt cache can reuse every byte before the edit.

What the animation shows:

  1. Turn 1: the pack is sent as one strip of bytes, file after file in a fixed order; the model provider caches it.
  2. You edit one file near the end of that order.
  3. Turn 2: the same tree gives the same bytes up to that file, so only the edited file and what follows are new.
  4. The cache reuses the unchanged prefix, here about three quarters of the bytes.
  5. 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; --meta adds them back.
  6. 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.

Index what the task touches, never copy the tree. The catalog and shards are the planned architecture. Today, point dctx at a sub-folder named in the task, not at the whole tree.

What the animation shows (the planned architecture):

  1. A 200 GB folder: photos, datasets, archives and a folder of repositories.
  2. A catalog (planned) sweeps it once and records names and sizes only; no file contents are read.
  3. A task arrives: fix invoice rounding.
  4. Two shards match the task: repos/billing and repos/shared-ui.
  5. Only those two get symbol indexes; the rest of the tree is never indexed or copied.
  6. A bounded page, inside the budget and in a stable order, comes out of the two shards.
  7. 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.

Measure before you change anything. The safe path for a new user, with commands that exist in dctx 1.3.1. Receipts are planned.

If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Step by step:

  1. A new user with one agent and one repository.
  2. Install the system binary: download the archive for your platform from GitHub Releases, check it with sha256sum -c SHA256SUMS --ignore-missing, then run dctx --version.
  3. Pick one project, not your home folder or a huge tree. The system binary serves it; nothing is installed per project.
  4. Run dctx map find NAME from the project root, then read a result with dctx read ID, using the shell or an agent's shell tool.
  5. 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=0 on the sample project.
  6. 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.
  7. Only then change one thing at a time.

Next: Choosing how to use dctx · Examples · Benchmarks