dctx1.3.1
Start

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

    1. Install the system binary from GitHub Releases and verify it against SHA256SUMS.
    2. Write a .dctxignore at each root you will query: data, generated output and archives out (.gitignore is read too).
    3. Decide which sub-roots a task can name: a package, a service, a document set.
    4. Optional: set fail-fast ceilings with DCTX_MAX_SOURCE_BYTES, DCTX_MAX_RECORDS and DCTX_MAX_ENTRIES.

    First command

    $ dctx map find Config --place packages/service-a --budget 500 --limit 5

    Watch 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 --place or by starting in that folder.

    Open the full path

  • 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

    1. Install the system binary once and put it on PATH.
    2. Run the dctx CLI directly from your agent's shell tool.
    3. Start in the project directory, or use --place to name the project root.
    4. Nothing else per project: dctx reads .gitignore and .dctxignore where they already are.

    First command

    $ dctx map find NAME

    Watch 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, then dctx cache gc --dry-run or dctx cache purge --root PATH --dry-run.

    Open the full path

  • 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 --json output.
    Setup, first command and the pitfall

    Setup

    1. Pin one version in your project, for example the Rust facade: dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" }.
    2. Pass your own ignore rules: the library does not load .gitignore by itself; the host supplies selection policy, storage limits and the clock.
    3. Move ids, not text: call find, keep the returned ids, call read with them.

    First command

    $ cargo test --locked -p dctx-library-example --doc

    Watch 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.

    Open the full path

  • 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

    1. Download the release archives from GitHub Releases and verify them against SHA256SUMS and their cosign signatures; each release also ships an SBOM.
    2. Ship one pinned version through your own package manager, image or configuration tool.
    3. Ship shared ignore rules (.dctxignore and a global ignore); the built-in deny for secrets, .git and symlinks always applies.
    4. Tighten the cache cap per machine if you need to: dctx cache config --max-bytes N can only lower it.

    First command

    $ dctx --version

    Watch out for

    Mixing project and system versions without checking. Run dctx doctor to list every binary in reach, and check dctx --version on PATH and the version each project pins, as part of onboarding.

    Open the full path

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.

dctx one binary, local and offline
  1. CLI pack$ dctx pack .

    Pack a project or one task into a bounded page for chat, scripts and shell agents.

    available

  2. Map mode for agents$ dctx map find greet

    Find, then read by stable id, with skeleton for orientation, in big files and long sessions.

    available

  3. Library and wrappersRust · Python · Node · Go

    Embed 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

  1. One project. Start with one project you know, not your whole disk.
  2. The system binary. Install the release archive from GitHub Releases and verify it against SHA256SUMS.
  3. Direct CLI commands. Run dctx map find NAME, then dctx read ID, from the project root.
  4. 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 dctx on 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 doctor lists 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.

Items marked planned or pending are not in dctx 1.3.x yet.
Leveldctx providesYou are responsible for
System binaryRelease 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 libraryPinned 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 setupACP plannedTurning off the host's own file tools, picking a profile, session ids and reading receipts (both planned)
CI and cacheByte-stable pack, deterministic exit codes; prefix tiers (planned)Pinning the binary, caching the index between runs, treating pack drift as a signal not noise