<div align="center">

<img src="assets/logo.svg" alt="Spokes logo" width="96" height="96" />

Spokes

Local MCP memory of your GitHub repositories for Cursor.

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

<br/>

<a href="#-quick-start"><img src="https://img.shields.io/badge/Quick%20Start-3DB8A8?style=for-the-badge&logoColor=white" alt="Quick Start" /></a>   <a href="#-prerequisites"><img src="https://img.shields.io/badge/Prerequisites-152024?style=for-the-badge" alt="Prerequisites" /></a>   <a href="#-mcp-tools"><img src="https://img.shields.io/badge/MCP%20Tools-152024?style=for-the-badge" alt="MCP Tools" /></a>

<br/>

<br/>

<img src="assets/banner.png" alt="Spokes — reuse your own code" width="100%" />

</div>

---

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:

Requirement	Required?	Notes
Windows 10/11	Yes	Installer is PowerShell / .bat based
Cursor	Yes	MCP must be enabled
GitHub account	Yes	Used for Connect GitHub (Device Flow)
Git	Recommended	Faster installs; ZIP fallback exists
Node.js 20 or 22	Optional	Installer can download a portable Node 22 for you

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+ often breaks native better-sqlite3 on Windows without Visual Studio), it downloads a portable Node 22 into %LOCALAPPDATA%\SpokesRuntime\.

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
• 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.

Tab	What it does
Connection	GitHub login (OAuth Device Flow) and sync settings
Repositories	Searchable list of repos with enable toggles
Reuse flow	Live task → repo → code → logic → result diagram

MCP tools

Tool	Purpose
list_repos	List known repo cards
search_repos	Find candidate repos for a task
get_repo_card	Full brief card for one repo
list_tree	Browse repo paths
get_file	Read a file or line range
search_in_repo	GitHub code search within one repo
start_task	Open an audit task
log_step	Record a reuse step
get_task_journal	Read task steps

Manual install (developers)

git clone https://github.com/Dente22/Spokes.git
cd Spokes
# Prefer Node 20 or 22 on Windows
npm install

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.

<details> <summary><b>Custom OAuth App (forks / advanced)</b></summary>

<br/>

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.

</details>

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

You are probably on Node 24+ without C++ Build Tools. Fix:

1. Re-run the official installer (it switches to portable Node 22), or
2. Install Node 22 LTS from nodejs.org and re-run install, or
3. Install Visual Studio Build Tools with Desktop development with C++

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

<div align="center"> <br/> <img src="assets/logo.svg" alt="Spokes" width="40" height="40" /> <br/> _{Built to stop reinventing the wheel.} </div>