xtctx

xtctx is a local-first context runtime for AI coding assistants.

It lets Claude Code, Codex, Cursor, Copilot, and Gemini share the same project memory so you can switch tools without re-briefing each session.

Core Capabilities

• Cross-tool retrieval with MCP tools (xtctx_search, xtctx_project_knowledge, etc.)
• Durable project knowledge in .xtctx/knowledge
• File-first config sync into tool-native instruction files
• One runtime process that serves:
  • MCP server
  • HTTP API (/api/*)
  • bundled web UI (/)

Knowledge Types

xtctx stores structured records as:

• decision
• error_solution
• insight
• convention
• gotcha
• faq

Practical Workflow (Tool Handoff)

1. Start in your repo with xtctx init.
2. Define shared rules in .xtctx/tool-config/shared.yaml.
3. Run xtctx sync to generate managed sections for each tool.
4. Start xtctx serve.
5. At the beginning of every coding session:
   • call xtctx_search
   • call xtctx_project_knowledge
6. After finishing work, write outcomes back with:
   • xtctx_save_decision
   • xtctx_save_error_solution
   • xtctx_save_insight
   • xtctx_save_faq

This gives a repeatable loop: recall -> implement -> write back.

Quick Start

Install and build:

npm ci
npm --prefix web ci
npm --prefix landing ci
npm run build

Initialize project context:

npx xtctx init

Sync shared config into tool-native files:

npx xtctx sync

Start runtime services:

npx xtctx serve

Open:

• Runtime web app: http://127.0.0.1:3232/
• Health: http://127.0.0.1:3232/health
• API: http://127.0.0.1:3232/api/*

Optional full re-index:

npx xtctx ingest --full

MCP Client Command

{
  "command": "npx",
  "args": ["xtctx", "serve", "--mcp-only", "--project", "/absolute/path/to/project"]
}

File-First Configuration

Primary config source is .xtctx/config.yaml.

Environment variables are optional explicit overrides only.

Security-related overrides:

• XTCTX_API_TOKEN
• XTCTX_ALLOWED_ORIGINS
• XTCTX_ALLOW_LOCALHOST_ORIGINS
• XTCTX_RATE_LIMIT_WINDOW_MS
• XTCTX_RATE_LIMIT_MAX

UIs

• web/: runtime product UI served by xtctx serve (dark mode default with toggle)
• landing/: public landing site deployed to GitHub Pages (dark mode default with toggle)

Local previews:

npm run web:dev
npm run landing:dev
npm run landing:preview

CLI Commands

• xtctx init [path]
• xtctx serve [--mcp-only] [--project <path>]
• xtctx ingest [--full] [--project <path>]
• xtctx sync [--project <path>]

Development

Full validation:

npm run verify:release

Release automation:

• Conventional commits feed Release Please
• Release PR merge on main creates GitHub release
• GitHub release publication triggers npm publish via OIDC trusted publishing

See CONTRIBUTING.md and SECURITY.md for contributor and security policy details.