Agent builder embedding a library
You build an agent, editor or tool and want dctx inside it.
- you get
- Stable ids and the exact source bytes inside your own app, from the same engine as the CLI.
- modality
- 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. - version
- dctx 1.3.1
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 --docWhat to expect
The ten-line library example compiles and runs against an in-memory source. With the CLI, --json answers carry the same records, and read puts the exact source in source_utf8.
A real run on the kiosk sample project, recorded from the release binary by capture.py:
$ dctx map read 's:src/util.rs#greet' --json{ "v": 2, "place": "kiosk", "verb": "read", "freshness": { "mode": "strict", "state": "verified" }, "precision": { "coverage": "syntax", "completion": "complete", "parser": "dctx-lex-rust/syn-3.0.9" }, "records": [ { "id": "s:src/util.rs#greet", "kind": "fn", "path": "src/util.rs", "lines": [ 2, 4 ], "summary": "The greeting shown on the kiosk screen.", "summary_source": "doc", "signature": null, "span": [ 44, 126 ], "source_utf8": "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}", "edge": null, "direction": null, "target": null, "confidence": null } ], "more": 0, "next": null}
The pitfall
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.
Read next
Rust library: embed the facade · Use as a library · Who is responsible for what
Other paths:
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.