<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>
&nbsp;
<a href="#-prerequisites"><img src="https://img.shields.io/badge/Prerequisites-152024?style=for-the-badge" alt="Prerequisites" /></a>
&nbsp;
<a href="#-mcp-tools"><img src="https://img.shields.io/badge/MCP%20Tools-152024?style=for-the-badge" alt="MCP Tools" /></a>

<br/>

![Platform](https://img.shields.io/badge/platform-Windows-0B1214?style=flat-square)
![Node](https://img.shields.io/badge/node-20%2F22%20recommended-3DB8A8?style=flat-square)
![Runtime](https://img.shields.io/badge/MCP-Cursor-2A9D8F?style=flat-square)
![Auth](https://img.shields.io/badge/auth-GitHub%20OAuth-152024?style=flat-square)
![Release](https://img.shields.io/github/v/release/Dente22/Spokes?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-0B1214?style=flat-square)

<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+), 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](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:

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

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

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

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

```powershell
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)

```powershell
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](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`](.mcp.json) is the machine-readable MCP manifest (used by [cursor.directory](https://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](https://github.com/Dente22/Spokes/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](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)

```powershell
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.

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

```powershell
$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**

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](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with **Desktop development with C++** if you are compiling native addons yourself.

**PowerShell blocks `install.ps1`**

Use `install.bat`, or:

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

```bash
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](https://github.com/Dente22)

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