Choose your path
dctx fits into your work in a few different ways. Pick the situation that sounds most like yours: each path says what you get, what to set up, the first command to run and the one mistake to avoid.
Four paths
- Who it’s for
- You work inside one very large tree, for example a 200 GB monorepo, data or document folder.
- What you get
- Short answers about only the part of the tree you name; the rest is never scanned.
- What you use
- System binary, scoped roots, ignore rules at each root you query.
Setup, first command and the pitfall
Setup
- Install the system binary from GitHub Releases and verify it against SHA256SUMS.
- Write a
.dctxignoreat each root you will query: data, generated output and archives out (.gitignoreis read too). - Decide which sub-roots a task can name: a package, a service, a document set.
- Optional: set fail-fast ceilings with
DCTX_MAX_SOURCE_BYTES,DCTX_MAX_RECORDSandDCTX_MAX_ENTRIES.
First command
$ dctx map find Config --place packages/service-a --budget 500 --limit 5Watch out for
Pointing an agent at the whole root. Every call then has to scan or index far more than the task needs, and the cache cap can refuse it. Name the sub-root in the task, with
--placeor by starting in that folder.- Who it’s for
- You move between many small and medium repositories during the day.
- What you get
- Install once, then run find and read from each project directory.
- What you use
- System binary, called directly from a shell or an agent's shell tool.
Setup, first command and the pitfall
Setup
- Install the system binary once and put it on PATH.
- Run the dctx CLI directly from your agent's shell tool.
- Start in the project directory, or use --place to name the project root.
- Nothing else per project: dctx reads
.gitignoreand.dctxignorewhere they already are.
First command
$ dctx map find NAMEWatch out for
Stale caches of projects you deleted or no longer use. Auto-clean runs once a day and drops unpinned roots after 30 idle days; to clean by hand, run
dctx cache status, thendctx cache gc --dry-runordctx cache purge --root PATH --dry-run.- Who it’s for
- You build an agent, editor or tool and want dctx inside it.
- What you get
- Stable ids and the exact source bytes inside your own app, from the same engine as the CLI.
- What you use
- Project library with its own pinned binary. Install the Node wrapper with
npm install @tejl/dctx; use CI artifacts for Python and Go, embed the Rust facade from a tagged Git dependency, or run a pinned CLI binary and read its--jsonoutput.
Setup, first command and the pitfall
Setup
- Pin one version in your project, for example the Rust facade:
dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" }. - Pass your own ignore rules: the library does not load
.gitignoreby itself; the host supplies selection policy, storage limits and the clock. - Move ids, not text: call
find, keep the returned ids, callreadwith them.
First command
$ cargo test --locked -p dctx-library-example --docWatch out for
Re-implementing engine logic: parsing or slicing pack text, recounting budgets, rebuilding ids. Treat answers as opaque pages and stable ids; if you need a different shape, ask the engine for
--json.- Who it’s for
- You roll dctx out to a team or a fleet of machines.
- What you get
- One verified, pinned version on every machine, with the same safety rules everywhere.
- What you use
- System binary distributed through your own package channel, one pinned version everywhere.
Setup, first command and the pitfall
Setup
- Download the release archives from GitHub Releases and verify them against SHA256SUMS and their cosign signatures; each release also ships an SBOM.
- Ship one pinned version through your own package manager, image or configuration tool.
- Ship shared ignore rules (
.dctxignoreand a global ignore); the built-in deny for secrets,.gitand symlinks always applies. - Tighten the cache cap per machine if you need to:
dctx cache config --max-bytes Ncan only lower it.
First command
$ dctx --versionWatch out for
Mixing project and system versions without checking. Run
dctx doctorto list every binary in reach, and checkdctx --versionon PATH and the version each project pins, as part of onboarding.
Advanced tool, several ways to use it
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.
Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool.
- CLI pack
$ dctx pack .Pack a project or one task into a bounded page for chat, scripts and shell agents.
available
- Map mode for agents
$ dctx map find greetFind, then read by stable id, with skeleton for orientation, in big files and long sessions.
available
- Library and wrappers
Rust · Python · Node · GoEmbed the engine in your own tool; the project pins its own binary and never re-implements engine logic.
Rust from Git now; Python, Node and Go wrappers built in CI, Node on npm; Python and Go from CI
The safe path, if you are not sure
- One project. Start with one project you know, not your whole disk.
- The system binary. Install the release archive from GitHub Releases and verify it against SHA256SUMS.
- Direct CLI commands. Run
dctx map find NAME, thendctx read ID, from the project root. - Measure. Run the same task with grep plus file reads and with dctx; compare whole-session tokens and calls, not only answer size.
Then pick the path above that matches your work. Choosing how to use dctx compares every mode with grep plus file reads.
Two scopes, one binary
- System binary: the
dctxon PATH belongs to you and your agents, and you upgrade it. Interactive agents call this one. - Project binary (Node from npm; Python and Go from CI): a binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Application code and CI call this one; a library never silently falls back to PATH.
- Same engine, different owner.
dctx doctorlists every binary in reach; verify each against SHA256SUMS and its cosign signature.
Who is responsible for what
Each level of use has its own responsibilities. dctx provides the left column; the right column is yours.
| Level | dctx provides | You are responsible for |
|---|---|---|
| System binary | Release archives with SHA256SUMS, cache caps; signed binary, doctor, journals and receipts (planned) | Choosing roots, the ignore rules (a policy file is planned), keeping one version on PATH |
| Project library | Pinned vendored binary, protocol client, same bytes as CLI (Node on npm; Python and Go from CI; Rust facade from Git) | Pinning the version, exclusions in the project policy, not re-implementing engine logic |
| ACP agent setup | ACP planned | Turning off the host's own file tools, picking a profile, session ids and reading receipts (both planned) |
| CI and cache | Byte-stable pack, deterministic exit codes; prefix tiers (planned) | Pinning the binary, caching the index between runs, treating pack drift as a signal not noise |