Why ctxd: Let the agent grep

Building an agent shouldn't mean building a whole context stack.

We kept writing the same sync, search and read tools for our applications. The data changed. The agent needed the new version. Getting that right took more infrastructure than the application itself should need.

That's why we're building ctxd: open-source context infrastructure between agents and data.

Our starting point is simple: keep source content current, give the agent tools to find it, and let it read the source before answering. No embedding service required.

Start with source access

An agent often needs more than a matching paragraph. It needs the instructions above it, the configuration beside it, or the document that explains an exception.

Take a deployment runbook. A search for rollback finds the instruction to restore the previous image. The line above says to stop the rollout first. Reading the surrounding source changes the answer.

ctxd gives the agent a way to follow that trail:

• Explore folders and paths.
• Search text through Python or the CLI.
• Read a file or a range of lines.
• Use what it finds to choose the next search or read.

The agent chooses the queries and reasons about the results. ctxd supplies the source access and synchronization behind those calls.

Fewer pieces to keep in sync

An embedding-based retrieval pipeline usually creates chunks, embeds them and maintains a vector index. You choose chunk boundaries, an embedding model and retrieval settings. When the source changes, the derived data needs to change too.

ctxd starts with searchable source content and paths. You don't need an embedding model, a chunking strategy or a vector database for this workflow.

That removes embedding generation and re-embedding from the work your application has to do. It also removes those embedding API fees. Your application still runs the agent, but it doesn't need a second model just to turn its source material into vectors.

Similarity search is useful when the wording of a question differs from the source. With ctxd, the agent can inspect paths, read headings and try alternative terms. It can search for rollback, then try revert or undo, and read the relevant passage.

The useful question is what your application needs to retrieve. Start with the source-access workflow you can inspect, then add complexity when you have a reason.

Keep context current as the source changes

ctxd's tracker synchronizes source content into ctxfs, its context filesystem. The application uses a common interface to inspect and read that content.

For example, your team changes a runbook, project document or set of operating instructions:

1. The source is edited.
2. The tracker completes a sync.
3. The agent reads the changed content through ctxd.

If a tracked source is removed, synchronization removes it from the context store too. There are no embeddings to regenerate before the changed text can be searched.

This gives the application a source path and readable content to work with. You can inspect what the agent actually read instead of guessing which fragment shaped its answer.

Use it from your application or agent client

ctxd is available through:

• Python: integrate context access into your application.
• CLI: inspect, search and read from the command line.
• MCP: connect an agent client to the Model Context Protocol bridge for path inspection and source reads.

Install it in your Python environment:

pip install ctxd

Then follow the quickstart to configure a source and start synchronization.

We're building ctxd for developers who want their agents to work with current source material without rebuilding the context infrastructure for every application.

Try ctxd with your own sources, and star the project if it's useful.

ctxd.dev · GitHub · Why ctxd, with the full walkthrough