squadai

README

SquadAI

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.

---

Install

# 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@latest

Linux .deb and .rpm packages are published on every release for Debian/Ubuntu and Fedora/RHEL users. Windows binaries (zip) are also published there.

---

Getting started

The fastest path is the interactive TUI wizard:

cd your-project
squadai

Running 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 right

Use 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 baseline
squadai init --preset=full-squad        # SDD methodology, balanced models, all components
squadai init --preset=lean              # conventional methodology, starter models, core only
squadai init --preset=custom            # explicit flags or wizard defaults

To see what apply would change before committing:

squadai plan --dry-run
squadai diff

---

How it works

When 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. Shared instructions (memory protocol, team standards, session efficiency, the solo orchestrator, the banner) go once into AGENTS.md, which every supported agent reads. CLAUDE.md gets a small block that imports it. Agent-specific files go where each agent expects them, such as .opencode/agents/ or .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
• Optional visual branding: an ASCII-art banner injected into agent files so devs see SquadAI is active at session start. Off by default; opt in with "brand": {"enabled": true} under components in .squadai/project.json (skip it for one run with squadai apply --no-brand)

Adapters and delegation

Different agents handle sub-agents differently. squadai adapts:

Agent	Instructions file	Sub-agent strategy
OpenCode	AGENTS.md	Native agent files in .opencode/agents/
Claude Code	AGENTS.md, imported from CLAUDE.md	Native agent files in .claude/agents/
Cursor	AGENTS.md	Native agent files in .cursor/agents/
Windsurf	AGENTS.md	Solo all-in-one prompt + workflow files
VS Code Copilot	AGENTS.md	Solo all-in-one prompt
Pi	AGENTS.md + ~/.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

The solo orchestrator block is written once, rendered for the first enabled solo agent (VS Code Copilot, then Windsurf, then Codex). Codex reads only the first 32 KiB of project instructions by default (project_doc_max_bytes), and squadai verify warns when AGENTS.md is larger.

Migrating to AGENTS.md

Earlier versions wrote a full copy of every shared block into each agent's own file: CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/squadai.mdc and .windsurf/rules/squadai.md. The next squadai apply after upgrading moves to a single copy in AGENTS.md and prints a one-time note when it does:

• AGENTS.md keeps one copy of each block. The per-agent copies (memory:opencode, memory:pi, and so on) are merged away.
• CLAUDE.md loses squadai's old blocks and gains <!-- squadai:agents-md --> with @AGENTS.md. Claude Code reads AGENTS.md on its own only when no CLAUDE.md exists, so the import keeps it loaded either way.
• .github/copilot-instructions.md loses squadai's old blocks. The copilot instructions template block stays if you use one.
• .cursor/rules/squadai.mdc and .windsurf/rules/squadai.md are deleted when they hold nothing but squadai's frontmatter, team standards and blocks.
• Your own text in any of these files is never touched. A file squadai created that ends up empty is deleted. A populated /squadai-init refinement block is kept where it was.

Commit the result. squadai verify --ci passes once the migrated files are committed. To undo, squadai restore <backup-id> with the backup ID that apply printed.

---

SquadAI inside your agent

squadai apply registers SquadAI's own MCP server (squadai mcp-server) in every enabled agent: Claude Code, OpenCode, Cursor, Windsurf, VS Code Copilot, Pi, and Codex. 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.

Project MCP servers land in each agent's native file: .mcp.json (Claude Code and VS Code share it), .cursor/mcp.json, .windsurf/mcp_config.json, .pi/mcp.json (Pi reads it once you trust the project), opencode.json, and ~/.codex/config.toml.

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.

---

Per-project refinement (/squadai-init)

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.

---

Project memory

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 status

In Claude Code and Codex, set "capture_on_stop": true in the memory block of .squadai/project.json and the agent is asked, once at the end of each non-trivial session, to record what it decided. See Memory capture at the end of Claude Code and Codex sessions.

See docs/project-memory.md for the full protocol.

---

Token cost

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

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

---

Team policy

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.

Verify in CI

Commit the files squadai apply writes, then fail pull requests that drift from .squadai/project.json or carry risky agent config:

on: pull_request
jobs:
  squadai:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: PedroMosquera/squadai@main
        with:
          version: latest       # or a release tag such as v1.2.3
          scan-fail-on: high    # scan: false skips the security scan

The action runs go install github.com/PedroMosquera/squadai/cmd/squadai@<version> (GitHub-hosted runners ship Go), then squadai verify --ci and squadai scan --fail-on <scan-fail-on>. Drift shows up as annotations on the changed files. Pin uses: to a tag or commit SHA for reproducible runs. working-directory points it at a project in a subdirectory.

---

Commands

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 the full health-check suite; --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 memory <subcommand> # manage project memory (search, add, promote, status)

Less common but good to know:

squadai verify              # post-apply compliance assertions (--ci for the CI drift gate)
squadai scan                # security scan of hooks and MCP configs (--fail-on, --json)
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 backup

For any command: squadai <command> --help.

---

Configuration

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

---

Install via your AI agent

If you'd rather have your agent set things up, paste this into it:

Install squadai using the best available method on this machine (brew if available, otherwise the curl script), verify with squadai version, run squadai doctor, and let me know if any checks failed. Don't run squadai init yet — I'll do that myself.

---

More docs

• docs/MANUAL.md — 5-minute user manual
• docs/project-memory.md — memory protocol deep dive
• docs/policy.md — policy and team enforcement
• docs/architecture.md — internals and design decisions
• docs/troubleshooting.md — common issues

---

License

MIT