What dctx is
dctx turns any folder into the smallest correct context for a task, offline, with byte-stable output that prompt caches can reuse.
“Smallest correct context” describes the goal, not a proof that task selection is complete or minimal. The shipped engine selects lexical symbols and document sections, verifies source reads and bounds answers. A 200 GB folder needs a relevant sub-root and ignore rules; output budgets do not bound scanning. Byte stability enables reuse, while provider cache rules determine actual hits. dctx has no embeddings, network, telemetry or agent loop in its pack/map workflows. It does not call a model or execute the task for you.
dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything.
Choose your path#
Choose one of these four paths. Each starts with a shipped workflow; the planned scope and distribution features are labeled explicitly.
One giant folder#
One giant folder (e.g. 200 GB): system binary; per-root ignore policy; name a sub-root/--place in tasks. Pitfall: pointing agents at the whole root.
Install the system binary, choose a relevant package,
and put exclusions in that root's .dctxignore before the first query:
dctx map find Config --place packages/service-a --budget 500 --limit 5Expect bounded symbol IDs and line ranges, not a complete answer about the whole
parent tree. Use an ID with map read. There is no general receipt yet;
--json exposes freshness, precision and pagination. Each invocation checks
source stamps; no daemon or file watcher is used. Catalog-first sharding and a
unified policy file are planned. Read the
huge-tree limits and ignore example
before warming an index; --in only filters after indexing.
Many small projects#
Many small projects: system binary; CLI commands from each project root; no project dependency. Pitfall: stale caches of deleted projects -> cache gc/purge.
Install one binary on PATH and use it from a shell or your agent's shell tool.
Run commands from the intended project root. No project dependency is required.
Start with dctx map find, then dctx map read using its exact ID. Expect source plus
freshness and precision in JSON, not a general receipt or session delta.
dctx cache status --json
dctx cache gc --dry-run
dctx cache purge --root /absolute/deleted-project --dry-runInspect the dry run before applying cleanup; purge requires --yes.
See cache controls. Indexes live in an
engine major.minor subdirectory (for example 1.3) of the cache parent, which is
DCTX_CACHE_DIR or the platform default v2 cache root; patch releases share it, and
data from other engine versions is ignored.
Agent builder embedding a library#
Agent builder embedding a library: project library with its own pinned binary (Python, Node or Go wrapper over dctx rpc); never parse or slice pack text. Pitfall: re-implementing engine logic.
The Python, Node
and Go wrappers over dctx rpc are built and tested in
CI. Install Node with npm install @tejl/dctx, which includes a pinned
@tejl/dctx-<platform> optional dependency; use CI artifacts or a checkout for
Python and Go as their READMEs describe. Alternatively, pin the
Rust facade from tagged Git,
or invoke the installed CLI as a subprocess. The first runnable Rust example is
in the library doctest. For subprocess use:
dctx map find Config --json --budget 500 --limit 5Expect JSON records with IDs and precision/freshness metadata; pass a returned
ID to map read --json for source_utf8. Keep engine selection and rendering in
the engine. Pass opaque continuation cursors back unchanged rather than slicing
pack text. Named context adds stable chunk IDs and opt-in delivery
sessions: use dctx context TARGET --session ID --dedupe. Delivery history lasts
for the CLI invocation or RPC connection; general receipts remain planned.
A Rust facade Session is an in-process API object. See the scope contract.
Team / enterprise admin#
Team / enterprise admin: system binary via package manager, signature + SBOM verification, one pinned version fleet-wide. Pitfall: mixing project and system versions without checking (dctx doctor).
This is the rollout target. Today, pin a release archive and check its matching
SHA256SUMS entry; package-manager distribution, signed CLI binaries and a
release SBOM verification workflow are planned. Deploy the verified archive and
root ignore rules through your existing fleet tooling. Record the resolved
binary path and start with:
dctx --version --verboseExpect version and feature/precision limits. dctx doctor lists the dctx
binaries visible from a directory with their scopes and SHA-256 checksums;
signature-status output is planned. Check paths and versions explicitly during onboarding;
use release procedure, testing and
security reporting for the current controls. Signed
organization policy bundles and audit journals are planned.
Safe path in ten minutes#
1. Install the system binary#
Download the archive for your OS and architecture and SHA256SUMS from
GitHub Releases.
Compare the archive's SHA-256 with its matching entry before extracting it.
On Linux use sha256sum ARCHIVE, on macOS shasum -a 256 ARCHIVE, or on Windows
PowerShell Get-FileHash ARCHIVE -Algorithm SHA256, replacing ARCHIVE with the
downloaded filename. This checks integrity against the release checksums;
signed binary verification is planned.
Extract the archive and put dctx (dctx.exe on Windows) on your user PATH.
Archives cover Linux x64/ARM64, macOS x64/ARM64 and Windows x64.
dctx --versionUse the system binary for interactive agents. Project wrappers are available through npm for Node and CI artifacts for Python and Go; no project dependency is needed for this path.
2. Choose one project and inspect one answer#
Use a small project or a relevant sub-root. Check .gitignore and .dctxignore
before scanning; leave DCTX_INDEX_IGNORED unset. From that directory:
dctx map find Config --json --budget 500 --limit 5Replace Config with a symbol or heading in your project. Read a returned ID
with dctx map read 'ID' --json. The JSON includes verified source bytes as
source_utf8 and reports precision, freshness and pagination. Keep the same
root between calls, because root-relative IDs change when the root changes.
3. Use the CLI from your shell or agent#
Run from the selected project root:
dctx map find Config --limit 5 --budget 500
dctx map read 'ID_FROM_FIND' --budget 2000Replace ID_FROM_FIND with an exact ID returned by find. Use the same commands
through an agent's shell tool. See the map guide for bounds
and pagination, and agent guidance for shell usage.
4. Measure before changing anything#
Run the same small task with grep plus narrow file reads and with dctx CLI. Record task correctness, number of tool calls, startup instructions and schemas, all model input/output tokens, provider cache hits, latency and billed cost when available. Include the history carried into each model turn. Smaller tool answers alone do not establish whole-session savings.
General receipts are planned. Today, retain JSON metadata and the agent's usage report. For task packs, the shipped footer is a useful output accounting line:
dctx pack . --for 'Config' --budget 800It reports body_tokens, budget and dropped, using estimated tokens rather
than a provider tokenizer. It is not a whole-session receipt. Save outputs
outside the selected tree, and compare repeated runs with identical inputs.
See measurement evidence and
CI/cache guidance.
Responsibilities#
This table uses the scope contract's wording, with unshipped provisions marked
(planned). Prebuilt archives with SHA256SUMS, cosign signatures, SBOM and
provenance are available; see download verification.
| Level | dctx provides | You are responsible for |
|---|---|---|
| System binary | Release archives with cosign signatures, SBOM and provenance, cache caps, dctx doctor, journals (planned), receipts (planned) |
Choosing roots, policy file, keeping one version on PATH |
| Project library | Pinned vendored binary and protocol client (Node on npm; Python and Go from CI), same bytes as CLI (checked in CI) | Pinning the version, exclusions in the project policy, not re-implementing engine logic |
| Agent shell setup | CLI commands and agent-setup guidance |
Choosing roots, bounding answers and measuring whole sessions |
| CI and cache | Byte-stable pack, prefix tiers (planned), deterministic exit codes | Pinning the binary, caching the index between runs, treating pack drift as a signal not noise |
For current CLI exclusions, use .gitignore and .dctxignore; the unified policy
file is planned. Agent session ids and general receipts in the responsibility
column describe planned integrations. The Rust facade exists today with explicit
host-supplied selection and storage policy; the project-library row describes
the Python, Node and Go wrappers, with Node available on npm. Existing pack prefix stability is distinct
from the planned layered prefix tiers.
Two scopes, one binary#
The following is the distribution contract for the project-library wrappers and signed releases:
The system
dctxon PATH belongs to you and your agents. A binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Same signed engine, different owner. Interactive agents call the system binary; application code and CI call the project binary; a library never silently falls back to PATH.
Today, install the system binary from release archives. The Python, Node and Go
wrappers already follow the no-fallback contract: they resolve an explicit path,
DCTX_BIN, their own platform package (Python, Node) or a versioned user cache,
and never search PATH. Until they are published, install them from CI
artifacts or a checkout, or invoke an explicitly pinned CLI path. The Rust facade
is an in-process library, not a vendored executable.
The CLI cache lives in <cache-parent>/<engine-major.minor>/ under the
platform-specific dctx/v2 parent (or DCTX_CACHE_DIR), so engines 1.2 and 1.3
keep separate indexes while patch releases of one family share theirs (see
scopes). A version/path line in every pack is planned. Today
dctx rpc reports the engine version in hello, and dctx doctor lists the dctx
binaries visible from a directory. Check the executable path and version
explicitly, and use separate absolute DCTX_CACHE_DIR locations when two
installations of the same engine family must not share an index. Both future scopes should read the project's exclusions; today the
CLI loads ignore files while a Rust host supplies its own selection rules.
Continue with the documentation index, modalities or engine specification.