One local control plane for setup, context, memory, permissions, model usage, and workflows across every coding agent you use.
If you've ever opened a repo and had your AI agent lose the thread — project memory, standards, MCP servers, permissions, model choices, and workflow habits — that's the problem squadai solves. You declare the local operating model once in .squadai/project.json, and squadai apply writes the right native files for every supported agent: OpenCode, Claude Code, Cursor, Windsurf, VS Code Copilot, Pi, and Codex.
SquadAI is solo-first: it should make your daily agent sessions predictable on one machine and one repo. The same primitives also scale to teams through policy, verification, backup, rollback, and drift checks.
# macOS / Linux via Homebrew (recommended)
brew install PedroMosquera/tap/squadai
# or via curl
curl -sSL https://raw.githubusercontent.com/PedroMosquera/squadai/main/scripts/install.sh | sh
# or from source
go install github.com/PedroMosquera/squadai/cmd/squadai@latestLinux .deb and .rpm packages are published on every release for Debian/Ubuntu and Fedora/RHEL users. Windows binaries (zip) are also published there.
The fastest path is the interactive TUI wizard:
cd your-project
squadaiRunning squadai with no arguments opens a terminal UI that walks you through choosing a methodology, enabling MCP servers, and selecting plugins. At the end it asks to apply the config. That's it — your agents are configured.
If you'd rather script it:
squadai init --methodology tdd # writes .squadai/project.json
squadai apply # installs agent files for all detected editors
squadai doctor # sanity-check everything looks rightUse a daily-driver preset when you want a ready-made operating model:
squadai init --preset=solo-minimal # lightweight conventional workflow
squadai init --preset=solo-power # TDD workflow with local memory/context defaults
squadai init --preset=team-standard # shared governance-friendly team baseline
squadai init --preset=enterprise-locked # strict SDD-oriented baselineTo see what apply would change before committing:
squadai plan --dry-run
squadai diffWhen you run squadai init, it detects which AI agents are installed on the current machine and writes .squadai/project.json — a config that says which methodology to use, which roles exist, which context profile is active, how memory works, and which components each agent should get.
squadai apply reads that config, figures out which files each agent needs in its native format, and writes them. For Claude Code it updates CLAUDE.md. For OpenCode it writes AGENTS.md and individual agent files under .opencode/agents/. For Cursor it writes .cursor/rules/ and .cursor/agents/. It never touches content outside its own marker blocks, so any customizations you've made in those files stay put.
The result is a team where everyone's agents have:
- A methodology — TDD (6 roles), SDD (8 roles), or Conventional (4 roles), each with an orchestrator that delegates to specialist sub-agents
- Consistent coding standards — auto-detected by language (Go, TypeScript, Python, Rust, and 12 more)
- Shared MCP servers — the SquadAI control plane and Context7 are enabled by default; others are opt-in
- Native memory defaults — local-first project memory metadata with
docs/memory/export/import compatibility - Context profiles — built-in profiles for default, debug, feature, review, docs, incident, and cheap sessions
- Usage controls — approximate session/daily token budgets and enforcement mode metadata
- Model routing metadata — cheap, balanced, and premium profile labels, plus methodology role overrides
- Visual branding — an ASCII-art banner injected into agent files so devs see SquadAI is active at session start (disable with
squadai apply --no-brand)
Different agents handle sub-agents differently. squadai adapts:
| Agent | Config file | Sub-agent strategy |
|---|---|---|
| OpenCode | AGENTS.md |
Native agent files in .opencode/agents/ |
| Claude Code | CLAUDE.md |
Task tool injection (prompt-based delegation) |
| Cursor | .cursor/rules/squadai.mdc |
Native agent files in .cursor/agents/ |
| Windsurf | .windsurf/rules/squadai.md |
Solo all-in-one prompt + workflow files |
| VS Code Copilot | .github/copilot-instructions.md |
Solo all-in-one prompt |
| Pi | ~/.pi/agent/AGENTS.md |
Native agent files in ~/.pi/agent/agents/ + prompts in ~/.pi/agent/prompts/ |
| Codex | AGENTS.md + ~/.codex/config.toml |
Solo all-in-one prompt; MCP servers as TOML tables |
squadai apply registers SquadAI's own MCP server (squadai mcp-server) in every enabled agent — Claude Code, OpenCode, Cursor, Windsurf, VS Code Copilot, and Pi. That means your agents can run SquadAI themselves and get the same outcomes everywhere: check status, plan/apply/verify config changes, run doctor, and search or add project memory — all without leaving the agent console.
It's on by default (the squadai entry in the curated MCP catalog is pre-checked). Deselect it in the wizard or pass --mcp=none (or an explicit --mcp= list without squadai) to squadai init to opt out. The registration invokes the squadai binary from PATH; squadai doctor warns if it can't be found.
Agent files installed by squadai apply contain placeholder blocks. /squadai-init is a command you run inside your AI agent to fill those placeholders with project-specific context: the repo layout, which roles matter most, custom instructions per role.
Agents will remind you when the refinement is stale (e.g. after a major refactor). To refresh it manually, just run /squadai-init in your agent again.
Agents lose context between sessions. SquadAI now defaults new configs to native local memory metadata and keeps the existing docs/memory/ folder as the shared export/import format agents can read and write, structured as indexed notes organized by topic.
# From inside your agent
/memory-search authentication # find prior decisions
/memory-add "switched to JWT, see docs/adr/012.md" # capture a decision
/memory-promote # graduate inbox drafts to permanent storage# From the CLI (for scripting or CI)
squadai memory search --query "authentication"
squadai memory add --note "switched to JWT"
squadai memory statusSee docs/project-memory.md for the full protocol.
Every squadai install adds agent instruction files to each session's system prompt. On a full TDD install those files add up. You can check the cost:
squadai token-budget # human-readable per-component breakdown
squadai token-budget --json # machine-readableExample output:
Component Files Tokens
────────────────────────────────────────────────────────────────
agents 6 4,210
skills 6 3,890
rules 1 480
memory 1 260
mcp 1 90
────────────────────────────────────────────────────────────────
TOTAL 15 8,930
The orchestrator gets the full memory protocol; sub-agents get a two-line stub — that alone cuts roughly 1,000 tokens per session from the default TDD install.
If you want to enforce a standard setup across a team and prevent individuals from overriding it, create .squadai/policy.json:
{
"version": 1,
"mode": "team",
"locked": ["methodology", "mcp"],
"required": {
"methodology": "tdd",
"mcp": { "context7": { "enabled": true } }
}
}Fields listed under locked can't be overridden by a developer's local ~/.squadai/config.json. squadai doctor reports policy violations and squadai validate-policy checks the file itself.
See docs/policy.md for the full reference.
The ones you'll use regularly:
squadai # launch the interactive TUI wizard (first-time setup or re-configure)
squadai init # initialize or re-initialize project.json
squadai apply # install agent files (idempotent — safe to re-run)
squadai diff # preview what apply would change
squadai doctor # run ~22 health checks; --fix auto-resolves common issues
squadai status # quick view of adapters, components, managed files
squadai status --daily # daily control-plane summary for the current repo
squadai token-budget # per-session token cost of the current install
squadai explain <topic> # explain a config field, error code, or concept
squadai memory <subcommand> # manage project memory (search, add, promote, status)Less common but good to know:
squadai verify # post-apply compliance assertions
squadai plan # show the action plan without applying
squadai update # self-update (--check, --enable-checks, or apply latest)
squadai remove --force # remove all managed files
squadai backup create # snapshot managed files manually
squadai restore <id> # restore from a backupFor any command: squadai <command> --help.
squadai init creates .squadai/project.json. Most fields have sensible defaults; the ones you're likely to touch:
{
"version": 1,
"methodology": "tdd",
"adapters": {
"claude-code": { "enabled": true },
"opencode": { "enabled": true }
},
"mcp": {
"context7": {
"type": "local",
"command": ["npx", "-y", "@upstash/context7-mcp@latest"],
"enabled": true
}
},
"meta": {
"name": "my-project",
"language": "go",
"test_command": "go test -race ./..."
}
}Config is merged from three sources in this order (last wins, unless locked by policy):
~/.squadai/config.json personal defaults
.squadai/project.json project config (this file)
.squadai/policy.json team policy — locked fields override everything
If you'd rather have your agent set things up, paste this into it:
Install squadai using the best available method on this machine (
brewif available, otherwise the curl script), verify withsquadai version, runsquadai doctor, and let me know if any checks failed. Don't runsquadai inityet — I'll do that myself.
docs/MANUAL.md— 5-minute user manualdocs/project-memory.md— memory protocol deep divedocs/policy.md— policy and team enforcementdocs/architecture.md— internals and design decisionsdocs/troubleshooting.md— common issues
MIT