Speedy

Local Semantic File System — bridges your local filesystem with AI models.

Speedy indexes your codebase into a SQLite vector database and exposes semantic search over your code through a CLI and an MCP server for AI agents (Claude Code, Cursor, opencode, Windsurf, …).

Default behavior (no daemon). Out of the box Speedy does not run the background daemon. Synchronization happens only through git hooks, which run standalone (no daemon) on each commit/checkout/merge/rebase. The hooks are installed automatically when you register a repo with speedy-cli workspace add (and removed by workspace remove); you can also manage them by hand with speedy install-hooks / uninstall-hooks. Every hook routes through speedy-cli, which fans the work out to all enabled contexts (ai-context, language-context, text-context). The daemon is still available for live file-watching but is never auto-started — launch it explicitly with speedy daemon or the GUI's "Start daemon" button.

All contexts are opt-in. speedy_indexer (semantic index), language_context (code intelligence) and text_context are disabled by default for a new workspace; the workers no-op until you enable them (speedy enable speedy, speedy enable slc). Toggles live under [features] in .speedy/config.toml.

For the full per-binary option reference see commands.md. For the end-to-end runtime flow see flow.md.

┌─────────────────────────────────────────────────────────────┐
│  AI Agent / User                                            │
│       │                                                     │
│       ├─────────────────────┐                               │
│       ▼                     ▼                               │
│  speedy-mcp.exe       speedy-gui.exe   (egui desktop app)   │
│  (MCP / stdio)              │                               │
│       │                     │                               │
│       ▼                     │                               │
│  speedy-cli.exe ◄───────────┘   (thin client, no heavy deps)│
│       │   local socket "speedy-daemon"                      │
│       ▼                                                     │
│  speedy-daemon.exe       ← ONE process, global per user     │
│   • IPC server                                              │
│   • N file watchers (one task per workspace)                │
│   • persistent memory: workspaces.json                      │
│       │                                                     │
│       │ spawn subprocess                                    │
│       ▼                                                     │
│  speedy-ai-context.exe              ← the worker                       │
│   • indexing, query, embedding, SQLite, chunking            │
│   • can also run standalone (no daemon needed)              │
└─────────────────────────────────────────────────────────────┘

• One daemon for everything. Never one daemon per workspace. The same speedy-daemon.exe watches all your projects and survives across CLI invocations.
• Persistent memory. The daemon's workspace registry lives in workspaces.json under your config dir. On reboot, the daemon reads it back and restarts every watcher.
• Worker is autonomous. speedy-ai-context.exe can run on its own — the daemon just orchestrates it for live updates.

Pre-built binaries are available on the Releases page.

Download speedy-setup-<version>.exe from the Releases page and run it. No admin required. Installs the binaries and configures PATH. The daemon is not started or registered for login — Speedy works via git hooks by default; enable launch-at-login from the GUI (Dashboard → "Avvio al login") if you want live file-watching.

To build the installer from source:

.\scripts\build-installer.ps1   # requires Inno Setup 6: winget install JRSoftware.InnoSetup

# 1. Install Rust: https://rustup.rs/
# 2. Install Ollama and pull an embedding model
ollama pull all-minilm

Build + copy to dist/ in one shot (recommended):

cargo xtask dist            # incremental build — only recompiles what changed
cargo xtask dist --clean    # force full rebuild of all 6 binaries

The xtask command builds all binaries in release mode and copies them into dist/.

Or, if you just want the raw release artifacts in target/release/ without copying:

cargo build-all
# (alias for: cargo build --release -p speedy-ai-context -p speedy-daemon
#             -p speedy-cli -p speedy-mcp -p speedy-gui -p speedy-language-context)

Speedy ships as 5 binaries with two distinct lifecycles: a long-running background daemon and four short-lived front-end tools. Install them accordingly.

1. The user-facing tools — in one folder, on PATH

Pick a stable install dir, e.g. C:\Program Files\Speedy\ (or %LOCALAPPDATA%\Programs\Speedy\ if you don't want admin rights), and copy the four front-end binaries into it:

C:\Program Files\Speedy\
├── speedy-ai-context.exe  ← worker (also usable standalone)
├── speedy-cli.exe         ← thin client for scripts / MCP
├── speedy-mcp.exe         ← MCP server for AI coding agents
└── speedy-gui.exe         ← desktop GUI

Adding this folder to your PATH is recommended but not required. With it on PATH you can type speedy-ai-context query … and speedy-cli daemon status from any shell, and MCP clients can reference speedy-mcp without a full path. To add it permanently (PowerShell, current user only):

$dir = 'C:\Program Files\Speedy'
[Environment]::SetEnvironmentVariable(
    'Path',
    [Environment]::GetEnvironmentVariable('Path','User') + ';' + $dir,
    'User')

Open a fresh terminal afterwards.

2. The daemon — optional, opt-in

The daemon is not required: by default Speedy syncs through git hooks (speedy install-hooks), which run the worker standalone on each commit. Run the daemon only if you want live file-watching (auto-reindex on save).

Easiest way: launch the GUI and use Dashboard → "Start daemon", then tick "Launch at login" to have it start automatically at every logon.

Prefer to wire it up by hand? Drop a shortcut to speedy-daemon.exe into the Startup folder (Win + R → shell:startup → Enter):

$startup = [Environment]::GetFolderPath('Startup')
$target  = 'C:\Program Files\Speedy\speedy-daemon.exe'
$ws      = New-Object -ComObject WScript.Shell
$lnk     = $ws.CreateShortcut("$startup\speedy-daemon.lnk")
$lnk.TargetPath = $target
$lnk.Save()

# Register the workspace once: the daemon adds a file watcher
# and keeps the index up to date in the background.
speedy-cli workspace add C:\path\to\project

# Index it (the daemon dispatches to speedy-ai-context.exe under the hood)
speedy-cli index

# Query
speedy-cli query "how does authentication work?" -k 10

# Sanity checks
speedy-cli daemon ping        # → pong
speedy-cli daemon status      # JSON with pid, uptime, watcher_count, …
speedy-cli daemon list        # workspaces currently watched

Or just launch speedy-gui.exe and add workspaces from the Workspaces tab — same operations, with live tail of the daemon logs.

If you don't want a background process at all, speedy-ai-context.exe works on its own:

SPEEDY_NO_DAEMON=1 speedy-ai-context index .
SPEEDY_NO_DAEMON=1 speedy-ai-context query "find auth"

Without the daemon there is no live re-indexing on every save — but if the workspace was added with speedy-cli workspace add (or you ran speedy install-hooks), the git hooks keep the index fresh on every commit/checkout/merge/rebase. Between commits, a query reflects what the last hook run (or manual index / sync / update) captured.

• Rust (edition 2021)
• Ollama running locally, with an embedding model pulled (default: all-minilm)

The exhaustive option list is in commands.md. Brief summary below.

Common subcommands (each honors --json and -p, --path <PATH>):

Top-level shortcut flags (alternative to subcommands): -r/--read, -m/--modify --file, -d/--daemons, -w/--workspaces. Full table in commands.md.

Global flags: -p/--path, --daemon-socket, --json.

Minimal CLI; all management is via the IPC protocol.

An egui-based desktop app that wraps the daemon's IPC. Launch with no arguments. Four tabs:

A system tray icon (green = daemon alive, red = down) provides quick Open Speedy / Restart daemon / Quit actions.

Communicates over stdio. Tools exposed:

Set SPEEDY_BIN to choose the underlying binary (default: speedy-cli).

Minimal:

{
  "mcpServers": {
    "speedy": {
      "command": "speedy-mcp",
      "args": [],
      "env": { "SPEEDY_BIN": "speedy-cli" }
    }
  }
}

Full example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "speedy": {
      "command": "C:\\Program Files\\Speedy\\speedy-mcp.exe",
      "args": [],
      "env": {
        "SPEEDY_BIN": "speedy-cli",
        "SPEEDY_DEFAULT_SOCKET": "speedy-daemon",
        "SPEEDY_MCP_TOP_K": "10"
      }
    }
  }
}

Typical agent flow:

1. User opens their repo and runs speedy-cli workspace add . (or just speedy-ai-context index . once — ensure_daemon auto-registers).
2. The daemon spawns a watcher and keeps the SQLite index fresh on every file change.
3. The agent (Claude / Cursor / opencode / …) calls speedy_query { "query": "where is auth handled?", "top_k": 10 } — the MCP server invokes speedy-cli query "where is auth handled?" -k 10 --json and pipes the ranked chunks back to the agent.
4. Subsequent edits trigger a re-index in the background; the next query sees them.

The daemon listens on a local socket (Windows Named Pipe / Unix Domain Socket via the interprocess crate; default name speedy-daemon). Wire format: one line of UTF-8 per request, one line per response. Full reference in docs/ipc-protocol.md.

Speedy reads configuration in this priority order (highest first):

1. Environment variables
2. .speedy/config.speedy.json in the workspace root
3. ~/.speedy/config.speedy.json (user-level defaults)
4. speedy.toml or .speedy/config.toml in the workspace root

Full provider reference: CONFIG.md.

Place .speedy/config.speedy.json in your workspace (or ~/.speedy/config.speedy.json for user-level defaults). This format supports all providers:

{
  "provider": {
    "type": "ollama",
    "model": "all-minilm"
  },
  "top_k": 10
}

Note: add .speedy/config.speedy.json to your .gitignore — it may contain API keys.

model = "all-minilm"
ollama_url = "http://localhost:11434"
provider_type = "ollama"
top_k = 10
max_chunk_size = 1000
chunk_overlap = 200
watch_delay_ms = 500
ignore_patterns = ["target/", ".git/", "node_modules/"]

Each workspace can independently enable or disable the two Speedy subsystems. The setting is stored in <workspace>/.speedy/config.toml under [features].

GUI — Workspaces tab, per-workspace row:

• Speedy Indexer checkbox — file indexer (speedy-ai-context)
• Language Context checkbox — code intelligence / symbol graph (speedy-language-context)

Changes take effect on the next daemon restart for that workspace.

Config file — edit <workspace>/.speedy/config.toml directly:

[features]
speedy_indexer = true    # file indexer (speedy-ai-context)
language_context = true  # code intelligence (speedy-language-context)

The GUI and config file are always in sync: the GUI reads and writes the same config.toml.

CLI shorthand (speedy enable speedy, speedy enable slc, …) is planned but not yet implemented.

Full examples and field reference in CONFIG.md.

Speedy honors .gitignore automatically (via the ignore crate). Add a .speedyignore in the project root for Speedy-specific rules — same syntax as .gitignore.

# .speedyignore
build/
dist/
*.log

The daemon's watcher additionally hardcodes ignores for: target/, .git/, node_modules/, .speedy/, .speedy-daemon/, .idea/, .vscode/, dist/, build/, __pycache__/, .cargo/.

~/.config/speedy/                       (Windows: %APPDATA%\speedy)
├── workspaces.json     ← global registry of every workspace the user
│                         has added — the daemon's persistent memory
└── daemon.pid          ← PID of the running daemon (one only)

<workspace>/
├── .speedy/
│   ├── index.sqlite         ← vector store for THIS workspace
│   ├── config.toml          ← optional per-workspace overrides (TOML)
│   └── config.speedy.json   ← optional per-workspace overrides (JSON, supports all providers)
└── .speedyignore            ← optional, gitignore syntax

• Only the daemon writes to workspaces.json. CLI / MCP / scripts ask the daemon to add / remove; they never write the file directly.
• daemon.pid is used only to clean up a stale instance after a reboot.
• Each workspace has its own .speedy/index.sqlite — the daemon centralizes orchestration, not data.

Cargo.toml (workspace)
└── packages/
    ├── speedy-core/         # shared lib: DaemonClient, workspace registry,
    │                          config, local-socket helpers, embedding type
    ├── speedy-ai-context/   # bin = speedy-ai-context.exe (worker)
    ├── speedy-daemon/       # bin = speedy-daemon.exe (central daemon)
    ├── speedy-cli/          # bin = speedy-cli.exe (thin client)
    ├── speedy-mcp/          # bin = speedy-mcp.exe (MCP server)
    ├── speedy-gui/          # bin = speedy-gui.exe (egui desktop app)
    └── testexe/             # internal test fixture

cargo test --workspace        # run all tests
cargo build --workspace       # debug build
cargo clippy --workspace      # lint

Some daemon tests touch process-wide state (cwd, SPEEDY_DAEMON_DIR) and serialize on a shared mutex — they may run slower on a single thread.

speedy-cli says "Cannot connect to daemon. Is it running?"

Either the daemon was never started or its named pipe is orphaned. Start a fresh one:

speedy-ai-context daemon      # spawns the central daemon detached
speedy-cli daemon ping        # should print `pong`

daemon-pid file is stale (PID points to a dead process)

The daemon now takes an advisory lock on daemon.pid at startup, so a stale PID file alone won't block a new daemon — kill_existing_daemon clears it. If you see "address in use" anyway, kill leftover processes manually:

Get-Process speedy-daemon -ErrorAction SilentlyContinue | Stop-Process -Force
Remove-Item "$env:APPDATA\speedy\daemon.pid" -ErrorAction SilentlyContinue

pkill -f speedy-daemon || true
rm -f ~/.config/speedy/daemon.pid

speedy-cli daemon status hangs

Almost always a named-pipe owned by a frozen daemon. Stop-Process / pkill the daemon and re-spawn.

Watcher is not picking up file changes

Check that the workspace is registered (speedy-cli daemon list). If absent, add it: speedy-cli workspace add <PATH>. Verify the path is not under an ignored prefix (target/, .git/, .speedy/, node_modules/, etc.).

speedy-mcp doesn't see my repo

The MCP server runs SPEEDY_BIN against whatever cwd Claude Desktop sets when launching it — usually not your project. Pass -p <PATH> from the agent prompt or speedy-cli workspace add <PATH> once to register the repo. After that, speedy_query works from anywhere because the daemon already monitors it.

MIT