# 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):
```bash
claude mcp add xtage npx -- -y xtage
```

For global installation across all projects, edit `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "xtage": {
      "command": "npx",
      "args": ["-y", "@ruco-ai/xtage"]
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "xtage": {
      "command": "npx",
      "args": ["-y", "@ruco-ai/xtage"]
    }
  }
}
```

## Usage

### 1. Index a repo

```bash
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:
```bash
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

```bash
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

```bash
xtage end
```

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

### 4. Update after commits

```bash
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:
```bash
echo 'xtage update' >> .git/hooks/post-commit
chmod +x .git/hooks/post-commit
```

### 5. Check index freshness

```bash
xtage status
```

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

### 6. Register a local directory

```bash
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