Installation

Covers: system prerequisites, installing SPEED, initializing a project, configuring speed.toml and CLAUDE.md, and setting up your agent provider.

Prerequisites

SPEED requires bash 4.3+, a handful of CLI tools, and at least one AI agent provider.

Dependency	Why	macOS install
bash >= 4.3	Associative arrays, string ops	brew install bash
Node.js >= 18	Required to install agent provider CLIs	brew install node
git	Worktree isolation, branch management	Xcode CLT or brew install git
jq	JSON parsing for task state and agent output	brew install jq
curl	Installer bootstrap, network operations	Pre-installed
GNU timeout	Agent time limits	brew install coreutils (provides gtimeout)

On Linux, all of these ship with standard packages (apt install nodejs jq coreutils git curl).

Agent provider

You need at least one AI coding agent CLI on your PATH. Both are installed via npm (hence the Node.js prerequisite above):

# Claude CLI (default provider)
npm install -g @anthropic-ai/claude-code

# Or Codex CLI (alternative)
npm install -g @openai/codex

The installer verifies a provider is present and exits with an error if neither is found.

Install

Recommended: curl installer

The installer handles everything: downloads the repo, installs uv (Python package manager), creates a Python 3.12 venv with all dependencies (tree-sitter grammars, scikit-learn, ast-grep), patches your shell rc, and writes a receipt file for future updates.

curl -fsSL https://raw.githubusercontent.com/sanjayk/SPEED/main/install.sh | bash

What it does, step by step:

1. Checks bash version, system deps, and agent provider
2. Installs uv if not already present
3. Clones the SPEED repo to ~/.speed/versions/{hash}/
4. Strips non-runtime directories (site, tests, working-docs)
5. Creates a Python 3.12 venv at ~/.speed/venv/ with all pip dependencies
6. Verifies tree-sitter grammars and core Python modules load
7. Symlinks ~/.speed/bin/speed → the active version
8. Adds PATH and SPEED_PYTHON to your shell rc (.zshrc, .bashrc, or fish config)
9. Writes ~/.speed/receipt.json (prevents duplicate installs, used by speed self-update)

After install, restart your shell (or source ~/.zshrc) and verify:

speed help

Installer flags:

Flag	Purpose
--proxy URL	Route curl and git through a corporate proxy
-q, --quiet	Suppress non-error output (for CI)

Environment overrides for the installer:

Variable	Purpose
SPEED_REPO	Git repo URL (for internal mirrors)
SPEED_TARBALL_URL	Tarball URL (when git is unavailable)
HTTP_PROXY / HTTPS_PROXY	Inherited by curl and git

Alternative: manual clone

If you prefer not to run the installer, clone the repo and manage the Python environment yourself.

Per-project (subdirectory):

cd my-project
git clone git@github.com:sanjayk/SPEED.git speed
pip install -r speed/requirements.txt
./speed/speed help

Global (PATH):

git clone git@github.com:sanjayk/SPEED.git ~/speed
pip install -r ~/speed/requirements.txt
export PATH="$HOME/speed:$PATH"   # add to shell profile
speed help

With a manual install, you are responsible for the Python dependencies in requirements.txt and keeping them updated.

What requirements.txt installs

The installer handles all of this automatically. For manual installs, here’s what you’re pulling in:

Package	Purpose
tree-sitter >= 0.23	AST parsing engine
tree-sitter-python, -javascript, -typescript, -go, -rust, -java, -ruby, -c, -cpp, -c-sharp, -bash, -html, -css, -json, -yaml	Language grammars for codebase analysis
ast-grep-cli	Structural code search via AST patterns
scikit-learn	TF-IDF similarity for related spec matching
fastapi, strawberry-graphql, uvicorn, watchdog	Dashboard backend (optional, only needed for speed dashboard)

Initialize a project

From your project root:

speed init

speed init creates:

Path	Purpose
.speed/	Runtime state directory (gitignored)
speed.toml	Project configuration
CLAUDE.md	Agent instructions, coding conventions, quality gate commands
specs/product/overview.md	Product vision template
.gitignore entries	Excludes .speed/ runtime state from version control

All four files are scaffolded from templates. The initial commit is created automatically.

Configure speed.toml

The generated speed.toml has all options commented out with their defaults. Uncomment what you need.

[agent]
provider = "claude-code"       # or "codex-cli"
planning_model = "opus"        # architect, verifier, coherence checker
support_model = "sonnet"       # developer, reviewer, guardian, debugger
timeout = 600                  # seconds per agent invocation
max_turns = 50                 # max turns for developer agents

[worktree.symlinks]
# Symlink heavy dirs from main repo into worktrees to avoid duplication.
# "node_modules" = "node_modules"
# ".venv" = ".venv"

[subsystems]
# Map names to glob patterns for targeted quality gates.
# "frontend" = ["src/frontend/**"]
# "backend" = ["src/backend/**"]

[specs]
# vision_file = "specs/product/overview.md"

[ui]
# theme = "default"         # or "colorblind" (blue/orange palette)
# ascii = false              # true for ASCII-only output
# verbosity = "normal"       # quiet, normal, verbose, debug

[security]
# sast_cmd = "semgrep --config auto --json"
# sca_cmd = "npm audit --json"
# severity_threshold = "medium"
# secrets_patterns = ["AWS", "GITHUB_TOKEN", "GENERIC_SECRET"]
# secrets_exclude = [".env*", "*.example", "tests/fixtures/**"]

Precedence rule: environment variable > speed.toml > built-in default. Every TOML key has a corresponding SPEED_* env var override (see Environment variables below).

Configure CLAUDE.md

CLAUDE.md tells agents how your project works: coding conventions, directory structure, and quality gate commands. The template is a starting point. Edit it to match your project.

The critical section is the quality gate commands, which agents and SPEED’s grounding system use to verify work:

## Quality Gates

### Lint
npm run lint

### Test
npm test

### Typecheck
npx tsc --noEmit

Gate commands can be scoped per subsystem (matching the [subsystems] globs in speed.toml). Without subsystem scoping, gates run against the whole project.

Environment variables

All take precedence over speed.toml values.

Variable	Default	Purpose
SPEED_PROVIDER	claude-code	Agent CLI provider
SPEED_PLANNING_MODEL	opus	Model for architect, verifier, coherence
SPEED_SUPPORT_MODEL	sonnet	Model for developer, reviewer, guardian
SPEED_TIMEOUT	600	Agent timeout in seconds
SPEED_MAX_TURNS	50	Max turns for developer agents
SPEED_TPM_BUDGET	200000	Token budget per minute
SPEED_RPM_BUDGET	5	Request budget per minute
SPEED_VERBOSITY	1	0=quiet, 1=normal, 2=verbose, 3=debug
SPEED_PROJECT_ROOT	$(pwd)	Override project root detection
SPEED_PYTHON	system python3	Python binary (set by installer)
NO_COLOR	—	Disable ANSI color output
ANTHROPIC_API_KEY	—	Passed through to Claude CLI

Directory layout after install

SPEED home (created by installer):

~/.speed/
├── bin/speed              → symlink to current/speed
├── current/               → symlink to versions/{hash}
├── venv/                  → Python 3.12 virtual environment
├── versions/{hash}/       → immutable version snapshot
│   ├── speed              → main CLI entry point
│   ├── agents/            → agent role definitions (markdown)
│   ├── providers/         → provider implementations (bash)
│   ├── lib/               → library modules + Python context engine
│   └── templates/         → scaffolding templates
└── receipt.json           → install metadata

Project state (created by speed init):

my-project/
├── .speed/
│   ├── state.json         → global runtime state
│   ├── features/{name}/   → feature-scoped task state, logs
│   ├── worktrees/         → git worktrees for isolated branches
│   └── logs/              → cross-feature logs
├── CLAUDE.md              → agent instructions + gate commands
├── speed.toml             → project configuration
└── specs/
    └── product/overview.md → product vision

Troubleshooting

Problem	Fix
bash version too old	brew install bash (macOS ships 3.2)
timeout command not found	brew install coreutils
jq not found	brew install jq or apt install jq
No agent provider found	Install Claude CLI: npm install -g @anthropic-ai/claude-code
python3 not found	The installer creates its own venv; for manual installs, ensure python3 is on PATH
speed.toml parse failed	Check TOML syntax; the parser requires Python 3.11+ (for tomllib)
SPEED is already installed	Run speed self-update to update, or rm -rf ~/.speed and reinstall
Git worktree conflicts	speed clean all removes all worktrees and state

After resolving prerequisites, head to Getting Started for the full workflow walkthrough.