Spokes

Local MCP memory of your GitHub repositories for Cursor.

Your agent reuses code you already wrote instead of reinventing the wheel.

   

Why Spokes

AI agents love to reinvent things you already built. You have working auth, a music catalog, a UI kit, a bot — scattered across your GitHub repos — but the agent writes it all again from scratch, slightly differently, every time.

Spokes gives the agent a memory of your repositories. Before writing new code, it checks what you already have, pulls the useful spokes, and adapts them into the current project. If nothing fits, it codes as usual.

Think of each of your repos as a spoke. Spokes brings the right ones into the hub — your active project.

Features

• Repo memory cards — short summary, tags, tree overview, and entry points per repo

• On-demand code access — files & trees fetched from GitHub only when needed

• Reuse journal — every search and every piece taken is logged

• Live Reuse flow UI — real-time diagram of task → repo → code → logic → result

• Local-first — runs on your machine; token stays in local SQLite

• GitHub OAuth (Device Flow) — connect once, no Personal Access Token juggling

Prerequisites

You need these before (or during) install:

Do I need to install Node.js myself?

Usually no. The one-command installer detects your environment and, if Node is missing or too new (Node 24+), it downloads a portable Node 22 into %LOCALAPPDATA%\SpokesRuntime\. It also skips the native node-gyp rebuild, so typical Windows users do not need Visual Studio.

Install Node yourself only if you prefer a system-wide runtime or are doing manual development.

Option A — install Node 22 LTS (recommended if you want system Node)

1. Open https://nodejs.org

2. Download the LTS build for Windows (prefer 22.x if available)

3. Run the installer (leave “Add to PATH” enabled)

4. Open a new PowerShell window and verify:

node -v
npm -v

You should see something like v22.x.x.

Avoid Node 24+ on Windows for Spokes unless you also install Visual Studio Build Tools with the Desktop development with C++ workload. Native SQLite modules need prebuilds or a C++ toolchain.

Option B — install with winget

winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements

Then open a new terminal and check node -v.

Option C — let Spokes handle it

Skip Node entirely and run the installer below — it will fetch portable Node 22 when needed.

Optional: Git

winget install Git.Git --accept-package-agreements --accept-source-agreements

Optional: fix PowerShell script policy (only if .ps1 is blocked)

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Or always run the installer via install.bat (it uses -ExecutionPolicy Bypass).

Quick Start

Cursor has no public API to auto-register an MCP from an .exe, so Spokes ships an installer that writes the config for you and copies the skill.

One command (recommended)

irm https://raw.githubusercontent.com/Dente22/Spokes/main/scripts/install.ps1 | iex

Then:

1. Fully restart Cursor (quit and reopen — required to reload MCP)

2. Open http://127.0.0.1:3847 → click Connect GitHub

3. Approve Spokes in the browser — done

No OAuth developer setup. No Personal Access Token.

Directory / Open Plugins: the repo-root .mcp.json is the machine-readable MCP manifest (used by cursor.directory auto-detect). Day-to-day installs still use the one-liner above — it writes absolute paths into ~/.cursor/mcp.json (required on Windows).

Double-click / release ZIP

1. Download the latest release: Releases

2. Extract the ZIP

3. Run install.bat

4. Restart Cursor → Connect GitHub

What the installer does

• Places Spokes in %LOCALAPPDATA%\Spokes

• Uses portable Node 22 when system Node is missing or Node 24+

• Runs npm install --ignore-scripts and checks the bundled better-sqlite3 prebuild (no Visual Studio)

• Merges a "spokes" entry into %USERPROFILE%\.cursor\mcp.json (other MCPs kept)

• Injects the public GitHub OAuth Client ID (SPOKES_GITHUB_CLIENT_ID)

• Copies the skill to %USERPROFILE%\.cursor\skills\spokes\

Uninstall: uninstall.bat or scripts\uninstall.ps1 -RemoveFiles.

How it works

                ┌──────────────────────────────────────────────┐
   You ask ───▶ │  Cursor agent  +  Spokes skill               │
                └───────────────┬──────────────────────────────┘
                                │ search_repos / get_file / log_step
                                ▼
                ┌──────────────────────────────────────────────┐
                │  Spokes MCP (local)                          │
                │   • repo memory cards (SQLite)               │
                │   • GitHub API on demand                     │
                │   • task journal                             │
                └───────────────┬──────────────────────────────┘
                                │ SSE
                                ▼
                     http://127.0.0.1:3847  ── Reuse flow UI

1. The skill tells the agent to consult Spokes before writing non-trivial code.

2. search_repos finds candidate repos; list_tree / get_file pull only what's needed.

3. Each reuse is recorded with log_step.

4. The Reuse flow tab renders the chain live.

Web UI

Open http://127.0.0.1:3847 (starts with the MCP). The browser tab shows the Spokes favicon/logo.

MCP tools

Manual install (developers)

git clone https://github.com/Dente22/Spokes.git
cd Spokes
# Prefer Node 20 or 22 on Windows. `.npmrc` skips node-gyp (bundled sqlite prebuild).
npm install
npm run verify:sqlite

Merge mcp.json.example into ~/.cursor/mcp.json (adjust absolute paths), copy skill/SKILL.md to ~/.cursor/skills/spokes/, restart Cursor, open the UI, Connect GitHub.

Official Spokes builds already ship a public Device-Flow Client ID. If you fork the project, register your own GitHub OAuth App, enable Device Flow, and set:

$env:SPOKES_GITHUB_CLIENT_ID = "your_client_id"

An OAuth Client ID is public — never embed a client secret in this local application.

Sync modes

• On start (default) — refresh when Spokes/Cursor starts

• Manual — only when you click Sync

• Hourly — while the process is running

Privacy

• Runs only on your machine

• Token stored locally in SQLite under ~/.spokes

• Code is fetched from GitHub on demand; cards keep only short navigation memory

Data location

All local state lives in ~/.spokes/:

• spokes.db — cards, settings, task journal

• cache/ — reserved for future file cache

Portable Node (if installed by Spokes): %LOCALAPPDATA%\SpokesRuntime\

Troubleshooting

npm install fails on better-sqlite3 / node-gyp / Visual Studio

This is the usual Windows failure: better-sqlite3 v13 already ships a prebuild, but npm still runs node-gyp rebuild at the end and then asks for Visual Studio. You do not need Visual Studio. Fix:

1. Re-run the official installer (it uses npm install --ignore-scripts and verifies the prebuild), or

2. From a clone: npm install --ignore-scripts then npm run verify:sqlite, or

3. If you are on Node 24+, also install Node 22 LTS (or let the installer download portable Node 22)

Only install Visual Studio Build Tools with Desktop development with C++ if you are compiling native addons yourself.

PowerShell blocks install.ps1

Use install.bat, or:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Cursor shows Cannot find module '...\src\index.ts'

Cursor does not reliably apply cwd. Paths in mcp.json must be absolute. Re-run the installer to rewrite them.

UI shows an old/unknown API response

An older Spokes process may still be on port 3847. Restart Spokes in Cursor (Settings → MCP) and hard-refresh the page.

Favicon / logo not updating in the browser

Hard refresh (Ctrl+F5) on http://127.0.0.1:3847 after updating Spokes.

Development

npm run dev        # MCP stdio + web UI
npm run dev:web    # web UI only
npm run resync     # re-pull repo cards
npm run typecheck

License

MIT © Dente22