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