context-router

context-router

A Claude Code plugin and MCP server that gives Claude persistent, cross-surface project memory. Load the right context for any project on demand — in Claude Code via /route, in the Claude desktop app via the MCP server, or in Claude.ai web chat via a generated custom instructions block. Write state back with /context-router:project-sync.

No more re-explaining context at the start of every session.

NOTE: this is a work in progress. Expect troubleshooting occasionally. Claude Code slash commands don't yet work, fix incoming...

---

How it works

All project context lives in a single private GitHub repo (claude-data). The plugin routes between projects by keyword scoring and directory matching — load the right file, write it back when you're done. Reads and writes go through the GitHub API by default; a local clone is optional and not recommended (see Config reference).

Claude Code — /route is the single entry point for both project context and codebase loading. It checks the current directory for a matching project, loads its context file first, then reads the codebase as normal. /context-router:project-sync merges session state + recent repo commits back into the context file and pushes atomically.

Claude desktop app — add the MCP server to claude_desktop_config.json (see Desktop app setup). All 8 tools are available natively — no custom instructions needed.

Claude.ai web chat — the web app cannot connect to local MCP servers. Run /context-router:project-instructions once to generate a custom instructions block and paste it into your Claude.ai Project settings. After that, /route [project] in any chat message triggers read_project reliably.

At Claude Code session start, the plugin runs git pull on your local clone if claudeDataLocal is configured — otherwise no local action is taken. See Config reference for claudeDataLocal trade-offs.

---

Requirements

• Claude Code (plugin system, stable since Oct 2025)
• Node.js 20+
• A private GitHub repo to use as your claude-data store
• A GitHub personal access token with repo scope

---

Installation

1. Clone the plugin

git clone https://github.com/VProPlayer/context-router.git
cd context-router
npm install

2. Create your config

mkdir -p ~/.config/context-router
cp config.example.json ~/.config/context-router/config.json

Edit ~/.config/context-router/config.json:

{
  "claudeDataRepo": {
    "owner": "your-github-username",
    "name": "claude-data",
    "branch": "main"
  },
  "claudeDataLocal": "~/ClaudeData",
  "projects": {
    "my-project": {
      "keywords": ["MyProject", "MP", "relevant-term"],
      "file": "my-project.md",
      "workingDirs": ["~/Developer/my-project"],
      "writeBack": true
    }
  }
}

See Config reference for all options including repo sync.

3. Create a GitHub token

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Enable the repo scope (required to read and write files in your private claude-data repo).

Add the token to ~/.zshrc (or ~/.bashrc):

export GITHUB_TOKEN=ghp_your_token_here

4. Create your claude-data repo

Create a private repo on GitHub named claude-data (or whatever you set in config).

The repo is a flat collection of .md files — one per project, all at the root:

claude-data/
├── my-project.md
├── another-project.md
└── ...

The file field in your config maps directly to the filename. Subfolders are supported ("file": "work/my-project.md") but not required.

Push an initial file for each project you configured:

echo "# My Project\n\nProject context goes here." > my-project.md
git init && git add . && git commit -m "init" && git branch -M main
git remote add origin https://github.com/your-username/claude-data.git
git push -u origin main

Note: A local clone (claudeDataLocal) is not required and not recommended — a stale or diverged clone can cause the plugin to read outdated context. The GitHub API is the default for all reads and writes. Only set claudeDataLocal if you have a specific offline use case and understand the trade-offs.

5. Install the plugin in Claude Code

Add context-router to ~/.claude/settings.json using Claude Code's extraKnownMarketplaces system:

{
  "enabledPlugins": {
    "context-router@context-router": true
  },
  "extraKnownMarketplaces": {
    "context-router": {
      "source": {
        "source": "github",
        "repo": "VProPlayer/context-router"
      }
    }
  }
}

If you already have other plugins in enabledPlugins or extraKnownMarketplaces, add these entries to the existing objects — don't replace them. Restart Claude Code after saving.

---

Usage

Claude Code