Overview
ctxd makes indexed content available as agent-readable context. A deployment can use two components:
- ctxfs stores indexed content and exposes it through filesystem-shaped paths with bounded read tools.
- The optional local tracker watches only the folders you choose and sends their content to ctxfs.
Basic workflow
Section titled “Basic workflow”- Install the
ctxdCLI. - Add a folder with
ctxd folders add. The local tracker indexes that folder, and nothing outside the folders you add is tracked. - Read through the ctxd CLI with
ls,tree,glob,stat,read,read-lines, andgrepoperations. The CLI uses the configured local or network ctxfs endpoint.
Architecture
Section titled “Architecture”| Component | Role | Default location |
|---|---|---|
| Local tracker | Watches selected folders and applies changes | Per-user background process |
| ctxfs | Stores indexed content and exposes filesystem-shaped paths | ~/.ctxd/ctxfs |
| CLI | Configures ctxfs and tracked folders, and reads indexed content | ctxd |
| ctxfs API | Provides REST and MCP access | Unix socket or HTTPS endpoint |
The tracker and ctxfs server are separate processes. When ctxd manages ctxfs
locally over its default Unix socket, starting the tracker ensures the local
ctxfs process is running. When configured to use an external endpoint, starting
the tracker verifies that it can authenticate to that server instead of
launching a local ctxfs process.
Authentication
Section titled “Authentication”The managed local Unix socket uses operating-system peer trust. HTTP endpoints require a scoped API key, and non-loopback serving requires HTTPS.
What agents can do
Section titled “What agents can do”ctxfs is path-oriented. Agents can inspect directories, match paths, read complete files or line ranges, and grep with regular expressions. Results report bounds and content identity so callers can tell when output was truncated or content changed.
ctxfs is not a semantic-search index and does not hide the file tree behind ranked chunks.
Next steps
Section titled “Next steps”- Quickstart to track your first folder
- Local tracker for installation and service management
- ctxfs for paths and read operations