English | Português (Brasil)

Running one coding agent is easy. The moment you want three project tasks done in parallel - fixes, investigations, plans, audits - you become a tab-juggler: babysitting sessions, copy-pasting context between repos, forgetting which terminal had the failing test.

Squad flips the model. You talk to a single agent - the sergeant at arms - and it runs the squad for you: spawning visible operators in a session backend, giving each a clean git worktree, supervising them to completion, and handing you finished PRs, approved local merges, or standalone recon reports. For larger units, you can opt in to persistent XOs: operators that run from their own isolated Squad bases on this machine or another SSH-reachable host.

Squad is not a model, not a harness, not a skill, not an MCP server, and not a CLI. Squad is an agent distro: a portable directory of instructions, skills, tooling, policies, and state conventions that turns a general-purpose agent into a specialized one. There is no app to install - the cloned repo is the distro (AGENTS.md, bundled Squad skills, and helper scripts that any terminal coding agent can follow). Launching a supported harness inside it instantiates your agent - and makes you the commander.

You juggle several projects or repos at once - fixes, investigations, audits - and you're tired of babysitting sessions, copy-pasting context between terminals, and forgetting which repo had the failing test. You want one point of contact that dispatches visible workers, supervises them, and hands you finished PRs and reports.

• You want a single agent to be more disciplined and verifiable - that's a per-session concern, not a unit-level one.
• You have one repo and one task at a time.
• You're not ready to set up a harness, GitHub auth, and a session backend.

You chat with the agent. It routes each request to an operator in its own session endpoint and git worktree, supervises the unit with a zero-token event-driven sentry, and brings you finished PRs, approved local merges, or recon reports. The sentry sleeps on the unit and wakes the sergeant only when something actually needs you.

Optional XOs extend this to persistent local or whole-base remote XOs; dispatch profiles let you steer which harness handles which task; and opt-in Relay lets the same unit answer public mentions on X and Discord. codex-app is not a runtime backend yet - docs/codex-app-backend.md owns that boundary.

Full architecture - the supervision engine, worktree isolation, XOs, dispatch profiles, project modes, optional Relay, unit sync, and self-update - lives in docs/architecture.md.

• A verified primary agent harness: Claude Code, Grok, Pi, pi-signed, Codex, or OpenCode.
• Git and the GitHub CLI, authenticated through gh auth login.
• The CLI and dependencies for your selected runtime backend; tmux is the reference default.

The agent detects and offers to install supported missing tools after you approve.

gh auth login
git clone https://github.com/runecraftai/squad
cd squad

Then launch one of the co-primary harnesses; AGENTS.md takes over from there:

Claude Code

claude

Grok

grok --trust

Pi

pi
# or, when the signed wrapper is installed
SQUAD_PI_HARNESS=pi-signed pi-signed

For Grok, --trust is needed once per clone so project hooks and the turn-end guard load; /hooks-trust inside Grok works too. For Pi, approve the project trust prompt once per clone on first launch so the tracked .pi/extensions/*.ts files auto-load. Pi's /calm toggle hides supported transcript chrome - including canonically classified Squad operational user rows - and uses a Calm-only animated working-ship indicator during active runs while preserving all model context and session data. The preference persists for the effective Squad base, and toggling it off restores ordinary rendering. Calm's current behavior and limits are separate from its version-scoped evidence.

> look at my github project xyz, then fix the flaky login test and add dark mode

# Squad checks its toolchain (asking your consent before installing anything),
# clones the project under projects/ and spawns two isolated operators in the active backend.
# Minutes later:

  PR ready for review, commander: https://github.com/you/xyz/pull/42
  (fix flaky login test - risk: low - CI green)

> alright merge it

Setup guides for tmux (the default) and every other supported backend (herdr, zellij, Orca, cmux) are linked in Documentation below.

• One point of contact - you talk only to the squad agent; it dispatches, supervises, escalates only real decisions, and reports plain outcomes.
• A visible squad - every operator works in its own tmux window, experimental herdr/zellij tab, cmux workspace, or Orca terminal you can watch or type into; the sergeant at arms reconciles.
• Disposable worktrees - each task runs in a clean FOB (worktree pool) git worktree, or an Orca-managed worktree when backend=orca, so parallel work on one repo never collides.
• Two task shapes - strike tasks deliver authorized changes; recon tasks leave standalone investigation reports when the intake contract warrants separate research.
• Explicit project modes - each project deploys via drill, direct-PR, or local-only, with an optional +yolo autonomy flag.
• Optional XOs - persistent XOs run from isolated Squad bases with their own SQUAD_BASE, state, projects, and session lock, locally or as a whole base on an SSH-reachable host, with guarded updates and recovery that never turns an unavailable remote route into a local replacement.
• Event-driven, zero-token supervision - a bash sentry wakes the sergeant at arms only when something needs you; verified primary harnesses also get a turn-end backstop that blocks or follows up on a blind stop when work is under way and supervision is not live.
• Optional Relay - opt in with one local .env pairing token so Squad can answer your public mentions on X and Discord, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post up to three public-safe completion follow-ups within seven days - all without changing non-Relay behavior. A final reply promised in a thread becomes durable state reconciled from disk, so a restart or compacted conversation cannot lose it.
• Strict project boundary - the sergeant at arms is read-only over your projects except for the narrow guarded and commander-approved operations authorized by hard rule 1; operators make every other project change behind the configured merge authority.
• Restart-proof - all state lives on disk and in the active session backend (tmux by hard default); kill the session anytime and the next one reconciles - including confirmed-dead XO agents - and carries on.

Squad ships these user-invocable built-in skills. Claude and grok use the slash form shown here; codex uses the same names with $, such as $afk.

Sitrep invocation examples:

• /sitrep returns the fresh four-section digest in chat only.
• /sitrep include PRs keeps chat-only mode and opts into live PR enrichment.
• /sitrep file replaces today's data/status-report-<YYYY-MM-DD>.md from scratch and links it from the four-section chat digest.
• /sitrep file include PRs combines the dated report with live PR enrichment.

Agent-only reference skills live under .agents/skills/ and are loaded by Squad at the trigger points named in AGENTS.md.

Squad's skills live in two separate places with different audiences:

• .agents/skills/ - agent-loaded skills (the table above, plus Squad's agent-only reference skills). Every one assumes a live Squad base and is meaningless - or actively misleading - installed anywhere else, so each carries metadata.internal: true in its frontmatter. That flag hides them from installer discovery (tools like the skills.sh npx skills add installer) without affecting how Squad itself loads them.
• skills/ - public, installer-facing skills meant to be installed standalone into any project, independent of Squad. Today that is skills/debrief, a generic session-knowledge-sweep skill that routes findings by explicit instruction first, then existing local conventions, then a private .debrief-notes.md fallback in the current directory. It intentionally shares no code with the Squad-internal .agents/skills/debrief it is named after, so the two can evolve independently.

Squad's tooling ships as standalone packages under packages/, each with its own README.

Squad discovers skills from multiple surfaces:

• Internal skills (.agents/skills/) - Squad-owned procedures loaded on demand by the agent harness.
• Public installer-facing skills (skills/) - standalone skills for any agent; symlinked from package-provided sources during bootstrap.
• Package-provided skills (packages/*/skills/) - skills bundled with packages, automatically registered into skills/ by bin/sq-register-package-skills.sh.

The registration script is idempotent and runs during bootstrap. It discovers skills from:

1. Conventional packages/*/skills/*/SKILL.md directories
2. Packages with "pi": {"skills": [...]} in package.json

To check which skills would be registered without modifying anything, run:

bin/sq-register-package-skills.sh --check

After bootstrap, verify the public skill link with test -e skills/sq-report/SKILL.md && echo sq-report-ready.

Skills provide semantic/prose discovery: the agent loads them when the task matches the skill's description. Hooks provide deterministic bootstrap integration: they run at session start to inject ambient context.

Both mechanisms are complementary:

• Skills handle prose intent discovery ("create a visual plan, comparison, diagram, table, code view, or report")
• Hooks handle session-start integration ("sq-report is available, here are active sessions")

The sq-report package uses both: the public skill for agent discovery and setup hooks for session-start context.

• docs/architecture.md - maintainer architecture for the squad, supervision, worktrees, XOs, and project modes.
• docs/configuration.md - environment variables, SQUAD_BASE, runtime backend selection, optional Relay and its X and Discord setup steps, the files you set, and harness support.
• docs/remote-XOs.md - current setup, routing, transfer, recovery, and safety behavior for whole-base remote XOs.
• docs/calm.md - current Pi /calm behavior and supported presentation limits.
• docs/wedge-alarm.md - configure the active alert for an away-mode escalation delivery that gets stuck.
• docs/tmux-backend.md - current setup and limits for the tmux reference backend.
• docs/status-notify.md - desktop notifications for operator done/blocked wake events, with a tmux focus action.
• docs/sq-sidebar.md - the Squad tmux sidebar (vendored workmux): per-window status cards from the ground-truth state files in a togglable pane.
• docs/web-view.md - a read-only web dashboard of operator state, served over the LAN for viewing from another machine or a phone.
• docs/herdr-backend.md - current setup, safety boundaries, and limits for the experimental Herdr backend.
• docs/zellij-backend.md - current setup and limits for the experimental Zellij backend.
• docs/orca-backend.md - current setup and limits for the experimental Orca backend.
• docs/cmux-backend.md - current setup, socket security, and limits for the experimental cmux backend.
• docs/codex-app-backend.md - the current blocked Codex App backend boundary and rollout contract.
• docs/verification/runtime-backends.md - active maintainer verification for runtime backend guarantees.
• docs/gitlab-merge-sentry.md - maintainer verification for GitLab merge watching on arbitrary instances.
• docs/turnend-guard.md - the primary session's current "no turn ends blind" backstop, scope, loop safety, and compatibility limits.
• docs/verification/supervision.md - active maintainer verification for session-start, guard, continuity, and wedge integrations.
• docs/supervision-protocols/ - rendered primary-harness sentry protocols for Claude, Codex, OpenCode, Pi and pi-signed, Grok, and unknown harness fallback.
• docs/scripts.md - the bin/ toolbelt reference.
• docs/documentation-audiences.md - documentation audiences and the machine-checked placement boundary.
• AGENTS.md - the distro's always-loaded operating contract and routing index for conditional procedures.
• CONTRIBUTING.md - how to contribute, including the dev/test commands.

Contributions are welcome - see CONTRIBUTING.md for the workflow, repo conventions, and how to run the tests.

MIT - see LICENSE.