xtage

CLI + MCP server that gives Claude persistent, semantic knowledge of a codebase — across every session, without manual context-setting.

Author: ruco-ai | Date: 2026-04-26

Overview

Claude starts every session cold. xtage fixes this by maintaining a persistent knowledge base that Claude reads before touching any source files.

The knowledge base lives in ~/xtage/ and is structured in three tiers:

1. Structural map — CODEINDEX.md, REPO.md, PROJECTINSIGHTS.md per repo
2. Per-file compressed summaries — files/{slug}.md per source file
3. Source files — opened only when the above tiers are insufficient

All files are generated by your local Claude, live in ~/xtage/, and stay on your machine. No external AI API. No cloud.

Installation

Claude Code (recommended):

claude mcp add xtage npx -- -y xtage

For global installation across all projects, edit ~/.claude/settings.json:

{
  "mcpServers": {
    "xtage": {
      "command": "npx",
      "args": ["-y", "@ruco-ai/xtage"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "xtage": {
      "command": "npx",
      "args": ["-y", "@ruco-ai/xtage"]
    }
  }
}

Usage

1. Index a repo

xtage init

Indexes the current directory. Local filesystem by default — works offline, works for private repos, indexes your actual working state.

To index a public GitHub repo instead:

xtage init https://github.com/owner/repo

Claude fetches, chunks, and writes REPO.md and CODEINDEX.md to ~/xtage/{repo-name}/. A spinner shows live progress.

2. Start a session

xtage start

Loads your codebase context into Claude at the start of a session. Claude reads the knowledge base silently and answers your first question with it already loaded.

3. End a session

xtage end

Claude reflects on what was learned and writes new entries to PROJECTINSIGHTS.md or GENERALINSIGHTS.md.

4. Update after commits

xtage update

Incrementally refreshes CODEINDEX.md based on what changed since the last index. Much faster than a full re-init.

Install as a git post-commit hook to run automatically:

echo 'xtage update' >> .git/hooks/post-commit
chmod +x .git/hooks/post-commit

5. Check index freshness

xtage status

Shows when the index was last updated and whether it's stale.

6. Register a local directory

xtage link

Registers the current directory in the local repo registry (~/xtage/registry.json), so xtage can resolve which indexed repo corresponds to the current working directory.

MCP Tools

Fetch tools

| Tool | Description | |------|-------------| | fetch_repo_data | Fetch a public GitHub repo in token-sized chunks | | fetch_local_repo_data | Fetch files from a local directory in token-sized chunks | | get_file | Fetch a single file from a GitHub repo | | check_for_updates | Check if CODEINDEX.md is stale vs latest GitHub commit |

Write tools

| Tool | Description | |------|-------------| | write_repo_md | Write REPO.md (architecture, stack, workflow) | | write_codeindex | Write CODEINDEX.md (file-by-file semantic map) | | write_project_insights | Write PROJECTINSIGHTS.md (design decisions, gaps) | | write_general_insights | Write global GENERALINSIGHTS.md (cross-repo patterns) | | write_file_chunk | Write a per-file prose summary to files/{slug}.md |

Read tools

| Tool | Description | |------|-------------| | read_codeindex | Read CODEINDEX.md | | read_repo_md | Read REPO.md | | read_project_insights | Read PROJECTINSIGHTS.md | | read_file_chunk | Read a per-file summary from files/{slug}.md | | list_file_chunks | List available file chunk summaries for a repo | | get_session_stats | Token savings stats for the current session |

Registry tools

| Tool | Description | |------|-------------| | register_repo | Map a local path → repo name in ~/xtage/registry.json | | lookup_repo | Resolve local path → repo name (or list all registered repos) |

Memory sync

| Tool | Description | |------|-------------| | sync_from_claude_memory | Merge Claude auto-memory files (~/.claude/projects/.../memory/) into PROJECTINSIGHTS.md. Wired automatically via a Claude Code PostToolUse hook — fires whenever a memory file is written. Silently skips repos not registered in xtage. |

Storage Layout

~/xtage/
  registry.json               ← local path → repo name mappings
  GENERALINSIGHTS.md          ← cross-repo patterns and standing instructions
  {repo-name}/
    REPO.md                   ← architecture, stack, workflow
    CODEINDEX.md              ← file-by-file semantic map
    PROJECTINSIGHTS.md        ← design decisions, known gaps
    files/
      {slug}.md               ← per-file compressed prose summary

Configuration

| Variable | Default | Description | |----------|---------|-------------| | XTAGE_NO_TELEMETRY | unset | Set to 1 to disable anonymous telemetry |

Add a .xtage-ignore file to your repo root to exclude paths (same format as .gitignore).

Default ignores: .env, *.pem, *.key, secrets/, node_modules/, dist/, *.lock.

Project Structure

xtage/
  src/
    cli.ts          ← CLI entry point (commands are thin proxies for claude -p)
    server.ts       ← MCP server setup
    tools.ts        ← MCP tool definitions
    resources.ts    ← MCP resources (xtage:// URIs)
    prompts.ts      ← MCP prompts (repo-init, repo-update, session-start, session-end)
    chunker.ts      ← token-aware file chunker
    github.ts       ← GitHub REST API fetcher
    local.ts        ← local filesystem repo reader
    ignore.ts       ← ignore chain + secretlint scanning
    store.ts        ← read/write ~/xtage/ files + registry
    progress.ts     ← spinner progress state (CLI ↔ MCP via env var)
    sessions.ts     ← session token tracking
    telemetry.ts    ← anonymous usage telemetry
    hook.ts         ← git diff parser (installGitHook removed; parseGitDiff + getGitDiff only)
    tokens.ts       ← local token counter
    version.ts
  templates/        ← mdblu templates for xtage index files

Telemetry

xtage collects anonymous usage data to understand how the tool is used. It is opt-in — you are asked on first run, and the default is off. Set XTAGE_NO_TELEMETRY=1 to disable permanently without being asked.

What is collected: event type (init, update, error, general_insights_write), timestamp, repo URL, file/chunk counts, word count of insights written. No source code, no file contents, no personal data.

Preference is stored at ~/.xtage/telemetry.json.

Release Notes

0.4.0

• New: sync_from_claude_memory MCP tool — reads Claude auto-memory files and merges them into PROJECTINSIGHTS.md. Wire it with a Claude Code PostToolUse hook so every memory write propagates to xtage automatically.
• Removed: dead init.ts and update.ts modules (logic had already moved to cli.ts via runClaude); removed installGitHook from hook.ts.
• Fixed: sync_from_claude_memory added to XTAGE_TOOLS so ensureXtagePermissions() grants it on xtage init.

0.3.x

• Session token tracking and get_session_stats tool
• Per-file chunk summaries (write_file_chunk, read_file_chunk, list_file_chunks)
• Open-source release: LICENSE, telemetry disclosure, .npmignore

License

MIT