Connect agents to the context they need—on a workstation, beside a remote worker, or through a shared service.
CTXD separates context ingestion from agent execution. A producer publishes selected text to ctxfs, CTXD's context store. Agents search and read that text through a common interface, independently of where the original files live.
The CTXD support assistant answers setup, integration, and troubleshooting questions using official documentation synced from GitHub. Its HTML interface shows retrieved evidence and citations to a specific source revision. Two Docker containers separate the application from its documentation and context store; four further architectures scope alternative placements.
Explore the agent exemplar · Migrate an existing context backend
Try it: Obtain your own Gemini key, put it in a private .env, and run the example. Visitors use the operator’s shared allowance, with persistent usage limits. Documentation browsing works without a model key.
The hosted assistant is available at ctxd.dev/support.
A documentation checkout or exported collection lives on the source machine. The agent and CTXD locations vary. Each architecture links to a support scenario; Docker containers represent the machine boundaries in the runnable remote-agent example.
Agent on the source workstation
| Architecture / example | CTXD location | Main benefit |
|---|---|---|
| Everything together | Same workstation | Access to selected project files. |
| Local agent, central context | Separate server | Reuse shared team knowledge. |
Agent on a remote worker
| Architecture / example | CTXD location | Main benefit |
|---|---|---|
| Agent remote from sources | Source workstation | Read workstation context remotely. |
| Context beside the remote agent | Worker server | Answer questions while the source is offline. |
| All separate | Dedicated server | Replace workers without rebuilding context. |
For everything together, restricted file access requires an isolated agent and a store containing only its approved material. CTXD does not prevent an agent from bypassing the service if that agent can read the surrounding filesystem. Existing scoped file tools may already meet this need.
A central context service is useful when readers share a corpus, producers contribute from different machines, or storage outlives individual workers. Direct reads are usually simpler for an agent that only needs files already available on its own workstation.
The example guide describes the task, expected behavior, and alternative for each layout. The Docker environment guide defines the simulated connections and configuration boundaries.
A tracker reads supported files and submits their text and metadata to ctxfs. Original files remain in place; the context store holds a served copy. Application records require an export or producer, and unsupported media requires text extraction.
The agent searches and reads through MCP, SDK, CLI, or REST. Its model and application tools turn the retrieved evidence into an answer, review, or other result. The model may run on another service even when the agent and its context tools run on the workstation.
These contracts describe the standalone Python implementation at CTXD revision 3289b13.
- Sources and synchronization. The tracker accepts selected UTF-8 text formats up to 5,000,000 bytes per file. Updates and removals become visible after successful synchronization. Tracking exported files does not refresh their upstream application. See the tracker implementation.
- Retrieval and evidence. The tools are
ls,tree,glob,stat,read,read_lines, andgrep. They provide navigation, lexical matching, and bounded reads. Preserve completeness indicators and available read hashes when building citations; a complete read does not prove complete ingestion. Semantic retrieval and live APIs can complement these tools. See the MCP tools and response models. - Availability and consistency. A reachable store can serve previously submitted text while its producer is offline. An unavailable store requires an application-provided fallback. Reproducible jobs need a defined input snapshot; normalized content hashes alone do not provide a consistent snapshot across documents.
- Readers and writers. Standalone readers can read the whole store. Submission credentials can be restricted by prefix. Private collections require isolated stores or an enforced access layer; applications using several stores handle routing. See the authorization policy.
- Agent responsibilities. The application supplies the model, interface, task state, schedules, action tools, and memory policy. Context synchronization does not start agent tasks. Retrieved passages can also appear in model requests and application logs.
Network deployments require a reachable endpoint and authentication. Non-loopback serving requires explicit opt-in and TLS; follow the server deployment guide.
Version compatibility: The Python 0.1.16 release implementation predates the authenticated network server described here. The Python adapter and npm bridge also share the executable name ctxd-mcp while exposing different contracts. Pin the exact artifact and verify its tools before deployment.
The repository includes migrate-context-to-ctxd, a skill for adapting an existing application's context ingestion and retrieval. It checks compatibility, implements a reversible adapter, compares representative tasks against the original provider, and verifies rollback.
The skill README explains supported inputs, invocation, and expected results. Its agent instructions are stored in the repository and require no global installation.
GitHub Actions checks each push and pull request using hosted runners without model or deployment credentials. CI runs the Python tests, chat adapter and browser checks, Docker isolation and outage checks, dependency audits, and a Git-history secret scan. See local verification commands.
Publishing code does not deploy the hosted assistant. Production deployment is managed separately and requires a manual release selection.
The example code is available under the MIT License. Third-party packages retain their own licenses; the application includes their frontend license notices in Settings.