ctxfs

ctxfs presents tracked local content as a filesystem-shaped tree that agents can inspect with explicit, bounded operations. It runs locally with the tracker and uses exact, path-oriented reads.

Install and start

ctxfs ships in the ctxd package. Install ctxd, then select the backend:

pip install ctxd
ctxd backend set ctxfs
ctxd backend status

The default data root is ~/.ctxd/ctxfs. The managed server listens through the Unix socket ~/.ctxd/local/ctxfs.sock; ctxd backend status prints the effective endpoint. Do not launch a second server against the same data root.

Path model

Every tracked folder has a stable root ID:

local-files/<ROOT_ID>/<path-relative-to-the-tracked-folder>

For example, if root abc123 tracks ~/Projects/example, then ~/Projects/example/docs/runbook.md appears at:

local-files/abc123/docs/runbook.md

The CLI resolves configured folder names to these prefixes, so agents can use a path such as Example/docs/runbook.md without knowing the generated root ID.

Read operations

Operation	Purpose
`stat`	Inspect one path and its metadata
`ls`	List one directory
`tree`	Walk a subtree to an optional depth
`glob`	Match paths with a glob pattern
`read`	Read a complete file up to a byte bound
`read_lines`	Read an inclusive line range
`grep`	Match exact text beneath a prefix

ctxfs deliberately exposes no shell and no arbitrary commands. grep is exact text matching, not semantic search.

Verify a tracked file

ctxd folders list
ctxd tracker start
ctxd files tree Example --depth 2 --limit 100
ctxd files read Example/docs/runbook.md

See the local API reference for every endpoint and parameter.

Bounded results

Listing and matching operations accept a limit. Read operations accept byte or line bounds. Responses include completeness information; callers must not treat a truncated response as exhaustive.

File reads also include content identity information. An agent can use it to detect whether a cited file changed between reads.

MCP

The running ctxfs service exposes the seven read operations through MCP at POST /mcp on its configured endpoint. MCP calls use the same in-process read service as the REST API.

The managed endpoint is a Unix socket, so the simplest MCP client configuration is the stdio bridge installed by the same ctxd package:

{
  "mcpServers": {
    "ctxfs": {
      "command": "ctxd-mcp"
    }
  }
}

The bridge resolves the configured local ctxfs endpoint itself. MCP tools do not accept endpoint, filesystem-root, or user-identity arguments.

Local data

The source folder remains authoritative. The tracker observes it and applies changes to ctxfs. Removing a tracked root does not delete the source folder.

Stop tracking with ctxd tracker stop before uninstalling the package.