`squad`

squad is a framework for building, sharing, and running unattended AI agents from the command line. Define an agent as plain markdown prompts and a YAML manifest, point it at any LLM provider, and let it work through a codebase using a fixed tool surface (Read, Write, Edit, Glob, Grep, Bash, plus any MCP server).

Agents run in a deterministic tool loop with per-run cost caps, structured event logs, and session resume. Multi-agent pipelines compose stages with dependency ordering and regression gates. Routines schedule unattended runs through OS-native daemons. Provider support includes OpenAI, Anthropic, Google AI, Ollama, and any OpenAI-compatible endpoint (NVIDIA NIM, Databricks, vLLM, LM Studio, Together AI). Execution can target the local machine, a Docker container, a Kubernetes pod, or an EC2 instance over AWS SSM.

Architecture

squad is a single Go binary built around a deterministic tool-calling loop. The CLI assembles an agent bundle (system prompt + tool definitions + budget config) from on-disk markdown and YAML, then drives the model through tool calls until it returns a final response or a budget/iteration cap fires.

                        ┌──────────────────────────────────────────────┐
                        │                squad (CLI)                   │
                        │   run · agents · routine · pipeline · ...    │
                        └──────────────┬───────────────────────────────┘
                                       │
                        ┌──────────────▼───────────────┐
                        │     Agent Bundle (agent/)    │
                        │  system.md + agent.md +      │
                        │  agent.yaml + skills + refs  │
                        └──────────────┬───────────────┘
                                       │
                        ┌──────────────▼───────────────┐
                        │   Tool Loop (tools/)         │
                        │ Read · Edit · Bash · Glob ·  │
                        │ Grep · Task · MCP · Skill    │
                        └──┬───────────┬────────────┬──┘
                           │           │            │
            ┌──────────────▼─┐  ┌──────▼──────┐ ┌───▼─────────────┐
            │  LLM Providers  │  │  Executor   │ │  MCP Servers    │
            │ openai          │  │ local ·     │ │ stdio · sse ·   │
            │ anthropic       │  │ docker ·    │ │ streamable_http │
            │ gemini · ollama │  │ kubectl ·   │ │                 │
            │ openai-compat   │  │ ssm         │ │                 │
            └─────────────────┘  └─────────────┘ └─────────────────┘

Package	Purpose
`cmd/squad`	Cobra CLI: subcommands for `run`, `agents`, `routine`, `pipeline`, etc.
`agent`	Manifest parsing, bundle assembly, model preferences, skill catalog
`runner`	Per-run context (edits, deadlines, modes), model invocation, response apply
`tools`	Tool definitions and the iteration loop (Read/Write/Edit/Glob/Grep/Bash/…)
`pipeline`	Multi-stage agent composition with parallel stages and regression gates
`skill`	On-demand Anthropic-format Skills: progressive-disclosure tool extensions
`mcp`	Model Context Protocol client + handler registration
`executor`	Run shell commands locally, in Docker, on K8s, or over AWS SSM
`routine`	OS-native scheduled runs (launchd, systemd, Windows Task Scheduler)
`responses`	OpenAI Responses API path (server-side state, large-result offload)
`metrics`	Token + cost accounting, per-run budget enforcement
`grading`	Rubric-based scoring of agent runs
`ui`	Bubble Tea TUI for interactive launch and monitoring
`source`	Skill discovery from local paths and git-hosted agent repos
`session`	Append-only event log per run; powers `--resume`

Quick Start

Prerequisites

Requirement	Version	Notes
Go	1.26+	Required for `go install`
LLM access	-	OpenAI, Anthropic, Google AI, Ollama, or any OpenAI-compatible endpoint
Git	-	Required for agent-repository fetching and worktree isolation

Install

# Install latest release
go install github.com/cowdogmoo/squad/cmd/squad@latest

# Or build from source
git clone https://github.com/cowdogmoo/squad.git && cd squad
go build -o squad ./cmd/squad

# Verify
squad version

Configure

# Initialize config at ~/.config/squad/config.yaml
squad config init

# Set a default provider and model
squad config set provider.default anthropic
squad config set model.default claude-sonnet-4-6

# Show the merged effective config
squad config show

API keys can come from environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY) or from $(command) substitution in config.yaml for secret managers.

First Run

# Pull the official agents repo
squad agents add official https://github.com/cowdogmoo/squad-agents.git
squad agents list

# Run an agent against the current directory
squad run --agent go-review --provider openai --model gpt-4.1-mini

# Run with local Ollama (no API key required)
squad run --agent go-review --provider ollama --model qwen2.5-coder:7b-instruct

# Estimate cost without calling the model
squad run --agent go-review --dry-run

# Resume a prior run after a crash, ctrl-c, or budget stop
squad run --agent go-review --resume 20260429T150220Z-a1b2c3d4

CLI Reference

squad is a unified CLI with the following subcommands:

Subcommand	Purpose
`run`	Run a single agent or composed pipeline
`agents`	Add, remove, and list agent sources (local paths and git repos)
`init`	Scaffold a new agent, config, or routine from templates
`config`	Initialize, inspect, and edit the squad config
`routine`	Manage scheduled, unattended agent runs
`skill`	Inspect, validate, and manage Agent Skills
`mcp`	Inspect and debug MCP servers
`grade`	Grade an agent run output against a rubric
`browser`	Manage named browser profiles for agents that drive Chrome
`ui`	Interactive TUI for launching and monitoring runs
`completion`	Generate shell completion scripts
`version`	Print the active binary version

Run squad <subcommand> --help for full flag documentation.

Global Flags

Flag	Description	Default
`-c, --config`	Config file path	`~/.config/squad/config.yaml`
`--log-level`	`debug`, `info`, `warn`, `error`	`info`
`--log-format`	`text`, `json`, `color`	`text`
`--otel-endpoint`	OpenTelemetry OTLP endpoint (e.g. `localhost:4318`)	disabled
`-q, --quiet`	Suppress non-error output	`false`
`-v, --verbose`	Show debug output	`false`

`squad run` — Key Flags

Flag	Description	Default
`--agent`	Agent name (required)	—
`--provider`	LLM provider (`openai`, `anthropic`, `gemini`, `ollama`, …)	config
`--model`	Model identifier	config
`--working-dir`	Target directory the agent operates on	current dir
`--max-cost`	USD budget cap (0 = unlimited)	`5.00`
`--max-iterations`	Max tool-calling iterations (10-1000)	`100`
`--mode`	Override agent's default mode (e.g. `readonly`)	manifest
`--apply`	Apply unified diff from response to working directory	`false`
`--dry-run`	Build bundle and exit without calling the model	`false`
`--resume`	Resume a prior session by ID	—
`--isolate`	Isolation mode: `worktree`, `branch`, `commit`, `staged`, `none`	manifest
`--stream`	Stream tokens to stderr in real time	`false`
`--out`	Write final response to file	—
`--var KEY=VALUE`	Template variable (repeatable)	—
`--mcp-server`	MCP server spec (repeatable)	—
`--allow-skill`	Restrict skills to this allowlist (repeatable)	manifest
`--auto-confirm`	How `Confirm` tool resolves in non-TTY runs (`yes`/`no`/`abort`)	`abort`

Agents

An agent is a directory of plain files checked into git. The CLI loads it, assembles the bundle, and drives the tool loop.

my-review/
├── agent.yaml      # Manifest: model preferences, tools, budget, pipeline
├── system.md       # Agent identity, rules, and workflow
├── agent.md        # Execution wrapper
├── task.md         # Default task instructions
└── references/     # Optional knowledge-base documents

Scaffold

# Create a new agent from a built-in template
squad init agent my-review --lang go

# Edit the system prompt
$EDITOR agents/my-review/system.md

# Test it
squad run --agent my-review --print

Sources

Agents can come from local directories or git-hosted repositories:

squad agents add official https://github.com/cowdogmoo/squad-agents.git
squad agents add team git@github.com:internal/agents.git
squad agents add scratch ./local-agents/

# Pin a source to a specific commit, tag, or branch so unattended runs
# always resolve the same content.
squad agents add official https://github.com/cowdogmoo/squad-agents.git --ref v0.4.2
squad agents pin official v0.5.0
squad agents pin official --unset             # back to tracking the default branch

squad agents list
squad agents update                            # pulls unpinned sources; skips pins
squad agents update --force                    # re-resolves pinned refs too
squad agents remove team

The official agents repo ships production-tuned agents for Go review, Python review, comment scrubbing, security audit, Ansible playbook validation, and more.

Full agent-authoring guide: docs/creating-agents.md. For the underlying taxonomy (agents, skills, the Task tool, and pipelines, and when to reach for each), see docs/agents-and-skills.md. First time writing prompts? Start with docs/prompt-engineering-basics.md.

Multi-Agent Pipelines

Define pipelines declaratively in agent.yaml with stages and gates:

name: security-audit
stages:
  - name: scan
    agents: [go-review, dependency-check]   # run in parallel
  - name: report
    agent: summarize
    depends_on: [scan]
gates:
  - after: report
    command: go test ./...
    on_failure: stop   # revert | stop

squad run --agent security-audit "Audit all changes since last release"

Stages can partition work automatically across files:

stages:
  - name: review-files
    agent: go-review
    partition:
      by: files
      glob: "**/*.go"
      max_per_partition: 10

Full pipeline reference: docs/pipelines.md.

Routines

Routines run agents unattended on a schedule via OS-native daemons (launchd on macOS, systemd on Linux, Task Scheduler on Windows).

# Create and install a nightly audit routine
squad routine create nightly-audit

# Per-repo manifest at .squad/routines/nightly-audit.yaml
cat > .squad/routines/nightly-audit.yaml <<'EOF'
id: nightly-audit
agent: go-security-audit
schedule: "0 2 * * *"           # cron, or @daily / @every 30m
prompt: "Audit changes merged in the last 24 hours"
provider: anthropic
model: claude-sonnet-4-6
max_cost: 5.00
max_iterations: 30
enabled: true
EOF

# Monitor
squad routine list
squad routine logs --follow
squad routine doctor

Command	Description
`routine create <id>`	Create and install a routine
`routine list`	List all routines with status
`routine show <id>`	Full details and next fire time
`routine run-now <id>`	Fire immediately
`routine enable/disable <id>`	Toggle a routine
`routine history <id>`	List past sessions
`routine logs [--follow]`	Tail daemon output
`routine doctor`	Health check
`routine repair`	Reinstall the OS service

Per-repo routines (checked into git) give the whole team identical automation. Global routines live in ~/.config/squad/routines/. Full reference: docs/routines.md.

Sessions & Resume

Every run writes an append-only event log to ./.squad/sessions/<id>/:

File	Contents
`meta.json`	Run options, last response id, cost, status
`events.jsonl`	One line per prompt, response, tool call, tool result
`results/<id>.txt`	Full bytes of any tool result that exceeded 8 KiB

--resume <id> reopens that session and chains the next request to the prior OpenAI Responses API id, so the model picks up server-side state without re-sending the transcript. When a tool result is too large to inline, the model sees a [result:<id> — N bytes elided …] placeholder and can fetch the full bytes via the get_tool_result tool.

Streaming output, OpenTelemetry tracing, cost budgeting, and the grading rubric are documented in docs/observability.md.

Execution Backends

Run agents in isolated or remote environments by adding an environment block to agent.yaml.

Local (default)

No environment block needed — the agent runs in the current shell.

Docker

environment:
  type: docker
  options:
    image: golang:1.26
    volumes: ".:/workspace"
    working_dir: /workspace

Kubernetes

environment:
  type: kubectl
  options:
    namespace: default
    image: golang:1.26
    resources:
      requests:
        memory: "512Mi"

AWS SSM

environment:
  type: ssm
  options:
    instance_id: i-1234567890abcdef0
    region: us-east-1

Full reference: docs/execution-backends.md.

MCP Servers

Agents can call any Model Context Protocol server as a tool source — stdio, SSE, or Streamable HTTP.

# agent.yaml
mcp_servers:
  - name: postgres
    transport: stdio
    command: mcp-server-postgres
    args: ["$DATABASE_URL"]
  - name: linear
    transport: streamable_http
    url: https://mcp.linear.app/sse

Or pass at run time:

squad run --agent my-agent \
  --mcp-server "postgres:mcp-server-postgres:$DATABASE_URL" \
  --mcp-server "linear:http:https://mcp.linear.app/sse"

# Inspect tools a server exposes
squad mcp inspect postgres

Full reference: docs/mcp-servers.md.

Skills

Skills are single-directory capabilities a running agent loads on demand. They follow Anthropic's open Agent Skills standard — the same format Claude Code, Codex CLI, and ChatGPT consume — so a skill checked into your repo runs everywhere without conversion.

skills/
└── comment-scrub-playbook/
    ├── SKILL.md             # required: identity, allowed_tools, instructions
    └── references/          # optional: knowledge-base documents the skill cites

Squad surfaces discovered skills in the agent's system prompt as an "Available skills" catalog. The agent loads one with Skill("name"), the skill's body and references are injected into context, and Read/Bash access expands to include the skill's directory for the rest of the run.

# Inspect a skill's metadata
squad skill show comment-scrub-playbook

# Validate every skill in a directory
squad skill validate ./skills

# List skills the active config can discover
squad skill list

Per-agent control lives under agent.yaml's skills: block (allow/deny lists, scope filters); CLI flags --allow-skill/--deny-skill/--skills-disabled override per run.

# Add the official skills catalog
squad skill add official https://github.com/cowdogmoo/squad-skills.git

The official skills repo is the shared home for production-tuned skills, mirroring the layout of the official agents repo.

Validate skills in any repo

Squad's validator (squad skill validate) is the single source of truth for skill conformance — same rules squad enforces at agent load time (frontmatter shape, name/description constraints, body-size targets, path-traversal guards on bundled references, script invocability). A skill repo can wire it into pre-commit two ways:

Local development — .pre-commit-config.yaml consumes the hook directly from this repo. pre-commit handles installation:

- repo: https://github.com/cowdogmoo/squad
  rev: 02a937c48d0a88eb7ef5dc3f543646860b687fb9  # pin to a SHA, not main
  hooks:
    - id: squad-skill-validate

rev: main works but pre-commit warns it's a mutable reference; a pinned SHA (or release tag, once available) is the supported form.

CI (GitHub Actions) — pre-commit's language: golang initializer runs git fetch origin --tags against this repo, which trips actions/checkout's git environment on the hosted runners. Sidestep by installing squad explicitly and registering a local hook in .pre-commit-config.yaml:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: squad-skill-validate
      name: Validate Anthropic Agent Skill manifests
      entry: squad skill validate
      language: system
      files: '(^|/)SKILL\.md$'
      pass_filenames: true

# .github/workflows/pre-commit.yaml — step before `pre-commit run`
- name: Install squad
  run: |
    tmp=$(mktemp -d)
    git clone --depth 1 https://github.com/CowDogMoo/squad.git "$tmp"
    cd "$tmp" && go build -o "$(go env GOPATH)/bin/squad" ./cmd/squad

The official squad-skills repo ships both pieces — copy them as a starting point.

Full reference: docs/skills.md.

Browser Profiles

Agents that drive Chrome via chrome-devtools-mcp reuse named, persistent profiles so cookies, logins, and session state survive across runs.

squad browser open amazon https://amazon.com   # create + open profile for interactive setup
squad browser list                              # show profiles + paths
squad browser path amazon                       # print the profile's userDataDir

In agent.yaml, refer to the profile path with the BrowserProfile template helper:

mcp_servers:
  - name: chrome
    command: npx
    args: [chrome-devtools-mcp@latest, --userDataDir={{.BrowserProfile "amazon"}}]

Full reference: docs/browser-profiles.md.

Configuration

Config is loaded from (highest to lowest precedence): CLI flags → SQUAD_* env vars → config file → built-in defaults.

Default path: ~/.config/squad/config.yaml.

Config File

log:
  level: info               # debug | info | warn | error
  format: text              # text | json | color

provider:
  default: openai           # openai | anthropic | google | ollama | openai-compat
  token: $OPENAI_API_KEY    # supports $VAR and $(command) for dynamic resolution
  base_url: ""              # override provider endpoint (OpenAI-compatible APIs)
  organization: ""          # OpenAI organization ID
  api_version: ""           # for Azure OpenAI

model:
  default: gpt-4.1-mini
  temperature: 0.2
  max_tokens: 1024

agents:
  repositories:
    official: https://github.com/cowdogmoo/squad-agents.git
  local_paths: []           # additional local agent search directories

run:
  max_iterations: 100
  max_cost: 5.0             # USD
  stream: false
  apply: false
  require_actionable: true

otel:
  endpoint: ""              # OTLP endpoint; empty disables tracing

Environment Variables

All config keys are available as SQUAD_* env vars (replace . with _, uppercase).

LLM Providers (at least one required):

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`GOOGLE_AI_API_KEY`	Google AI Studio key
`OLLAMA_BASE_URL`	Local Ollama server URL (default `http://localhost:11434`)

Squad Defaults (override config-file values):

Variable	Description
`SQUAD_PROVIDER_DEFAULT`	Default LLM provider
`SQUAD_PROVIDER_TOKEN`	API key for the default provider
`SQUAD_MODEL_DEFAULT`	Default model identifier
`SQUAD_RUN_MAX_COST`	Default USD budget cap
`SQUAD_RUN_MAX_ITERATIONS`	Default max tool-call iterations
`SQUAD_LOG_LEVEL`	Log level
`SQUAD_LOG_FORMAT`	Log format
`SQUAD_OTEL_ENDPOINT`	OTLP endpoint for telemetry

OpenAI-Compatible Endpoints

provider:
  default: openai-compat
  base_url: https://api.together.xyz/v1
  token: $TOGETHER_API_KEY

Works with NVIDIA NIM, Databricks, Together AI, vLLM, LM Studio, and any OpenAI-compatible API.

Full reference: docs/configuration.md.

Repository Layout

cmd/squad/                # Cobra entry point
cmd/squad-routined/       # Routine daemon binary

agent/                    # Manifest parsing, bundle assembly
runner/                   # Run execution, model invocation
tools/                    # Tool definitions + the iteration loop
pipeline/                 # Multi-stage agent composition
skill/                    # Agent Skills (Anthropic format)
mcp/                      # Model Context Protocol client
executor/                 # Local/Docker/K8s/SSM execution backends
routine/                  # Scheduled unattended runs
responses/                # OpenAI Responses API path
metrics/                  # Token + cost accounting
grading/                  # Run grading and rubrics
ui/                       # Interactive TUI

config/                   # Config loading and validation
source/                   # Agent + skill discovery
session/                  # Per-run event log
templates/                # Built-in agent scaffolds
docs/                     # User documentation (linked below)

Development

Prerequisites

Go 1.26+
pre-commit (recommended)
golangci-lint (CI uses v2.11.4)

Build & Test

git clone https://github.com/cowdogmoo/squad.git && cd squad

go mod download
go build ./cmd/squad      # build the binary
go test ./...              # run the full test suite
go vet ./...
golangci-lint run --timeout=5m

Pre-Commit Hooks

Pre-commit hooks cover gofmt, goimports, gocyclo, golangci-lint, gocritic, go-build, go-mod-tidy, govulncheck, yamllint, codespell, markdownlint, actionlint, and the GoReleaser config check. Install once and they run on every commit:

pre-commit install

CI rejects any commit that fails the hooks.

Documentation

Getting Started

Agent and Skill Concepts — taxonomy: agents, skills, Task tool, pipelines, and when to reach for each
Configuration — providers, environment variables, full config-file reference
Creating Agents — build your own agents from scratch or from templates
Prompt Engineering Basics — LLM fundamentals, context windows, and writing effective agent prompts

Guides

Pipelines — multi-agent orchestration with stages, gates, and cost budgets
Execution Backends — run agents in Docker, Kubernetes, or AWS SSM
MCP Servers — connect agents to external tools via Model Context Protocol
Observability — streaming output, OpenTelemetry tracing, cost budgeting, and grading
Routines — scheduled unattended runs via OS-native daemons
Skills — on-demand capabilities a running agent loads (Anthropic Agent Skills format)
Browser Profiles — named Chrome profiles for agents that drive a browser

Engineering

Agent Quality Guide — tuning methodology and grading rubric
Agents Engineering Pipeline — agent-engineering CI/CD with squad

Agents & Skills

Official Agents — production-ready agents for Go, Python, Ansible, and Molecule
Official Skills — shared Agent Skills catalog consumed via squad skill add

Contributing

Contributions are welcome. The contributor flow:

Fork and create a feature branch off main.
Install pre-commit hooks: pre-commit install.
Make changes and add tests (go test ./...).
Ensure golangci-lint run and go vet ./... pass.
Open a PR. CI will reject commits that fail any hook.

For agent contributions, the official agents repo is the home — open PRs there.

Inspired by Daniel Miessler's Fabric.

Built With

LangChainGo — LLM provider abstraction
Cobra — CLI framework
Viper — config loading
Bubble Tea — TUI
go-git — agent-repo fetching

License

This project is licensed under the MIT License — see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.claude/agents		.claude/agents
.github		.github
.hooks		.hooks
agent		agent
browser		browser
cmd		cmd
config		config
csync		csync
docs		docs
executor		executor
grading		grading
logging		logging
mcp		mcp
metrics		metrics
ollama		ollama
pipeline		pipeline
responses		responses
routine		routine
runner		runner
scaffold		scaffold
session		session
skill		skill
source		source
telemetry		telemetry
tools		tools
ui		ui
watch		watch
.editorconfig		.editorconfig
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
.markdown-link-check.json		.markdown-link-check.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
.semgrepignore		.semgrepignore
LICENSE		LICENSE
README.md		README.md
Taskfile.yaml		Taskfile.yaml
codecov.yml		codecov.yml
go.mod		go.mod
go.sum		go.sum
renovate.json		renovate.json

Folders and files

Latest commit

History

Repository files navigation

squad

Table of Contents

Architecture

Quick Start

Prerequisites

Install

Configure

First Run

CLI Reference

Global Flags

squad run — Key Flags

Agents

Scaffold

Sources

Multi-Agent Pipelines

Routines

Sessions & Resume

Execution Backends

Local (default)

Docker

Kubernetes

AWS SSM

MCP Servers

Skills

Validate skills in any repo

Browser Profiles

Configuration

Config File

Environment Variables

OpenAI-Compatible Endpoints

Repository Layout

Development

Prerequisites

Build & Test

Pre-Commit Hooks

Documentation

Getting Started

Guides

Engineering

Agents & Skills

Contributing

Built With

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`squad`

`squad run` — Key Flags

Packages