squad-opencode

Human-led AI agent teams for OpenCode — implemented in Go.

One binary scaffolds a persistent team in your repo (.squad/) and OpenCode agents (.opencode/). You coordinate work; specialists (Lead, Frontend, Backend, Tester) run as OpenCode agents.

Inspired by bradygaster/squad (MIT). OpenCode-native port — not a Copilot fork.
Host API client: official opencode-sdk-go (github.com/sst/opencode-sdk-go).

Install

No Go toolchain. Download the archive for your OS from GitHub Releases and put squad-oc on your PATH. Assets are squad-oc_<version>_<os>_<arch>.zip (Windows) or .tar.gz (macOS/Linux).

# Scoop
scoop bucket add squad https://github.com/xeaser/squad-opencode
scoop install squad-oc

# Homebrew
brew tap xeaser/squad-opencode https://github.com/xeaser/squad-opencode
brew install squad-oc
# The tap ships a cask; existing formula installs migrate via tap_migrations.json.

# winget (from a clone of this repo)
winget install --manifest packaging/winget

squad-oc upgrade --self replaces the binary from the latest release.

Quick start

# 1. Install OpenCode + /connect a provider — https://opencode.ai/docs/

# 2. Install squad-oc from GitHub Releases (see Install above)

# 3. In your project
mkdir my-app && cd my-app && git init
squad-oc init --preset default
squad-oc doctor

# Interactive TUI (does not listen on :4096)
opencode
# Tab → squad agent → "Set up the team for …" → yes

# HTTP API: run auto-starts `opencode serve` on :4096 if nothing is there
squad-oc run -p "Summarize .squad/team.md"

Full walkthrough: docs/get-started.md

Also useful

docs/workshop/README.md — 90-minute adopt path (squad-oc + OpenCode only)
docs/use-cases.md — workshop mapped to supported / later / won’t port

What to commit

This repo dogfoods Squad on itself. After init + opening OpenCode:

Commit	Do not commit
`.squad/` team, charters, decisions, `.gitignore`	`.squad/comms/*` (folder kept via `.gitkeep`)
`.opencode/agents`, `skills`, `commands`, `.gitignore`	`.opencode/node_modules/`
`opencode.json`	`.opencode/package.json` + lockfiles OpenCode generates

OpenCode creates .opencode/package.json (@opencode-ai/plugin) and runs an install on first launch. That is host runtime, not Squad source.

Commands

Command	Role
`init [--preset default] [--description ] [--global] [--theme office	none]`
`upgrade [--dry-run] [--force] [--global] [--self]`	Refresh host templates; `--self` replaces this binary from GitHub Releases
`doctor` / `heartbeat`	Health checks
`status` / `cast`	Team table
`brief [--json]`	Morning listing: team, PRs, tickets, last done, next, Ralph
`cast --add <name> [--role <role>] [--model <provider/id>]`	Add a member and regenerate `.opencode/agents`
`cast --model <name> <provider/id>`	Pin a member to an OpenCode model id
`cast --model squad <provider/id>`	Pin the coordinator model
`cast --model <name	-> -`
`cast --remove <name>`	Remove a member and regenerate `.opencode/agents`
`cast --theme office` / `none`	`init --theme office` (native `@michael`) or later `cast --theme office` (mention map; `@lead` gone)
`recast`	Regenerate `.opencode/agents` from `.squad/team.md`
`run -p <prompt>` / `--file <path> [--agent name] [--url]`	Prompt the OpenCode HTTP API as `squad`; auto-starts `opencode serve` on :4096 only
`watch` / `triage` / `loop` `[--execute] [--interval minutes] [--once] [--health] [--url] [--overnight-start HH:MM] [--overnight-end HH:MM] [--label name] [--project N] [--column name] [--force] [--retry-label name] [--log-file path] [--verbose] [--notify-level all\|important\|none] [--state-backend memory\|git-notes\|orphan-branch]`	Issue triage (Ralph); `--execute` uses `run`; optional GitHub Project v2 + Status filter; skips issues with an open linked PR unless `--force` or `--retry-label` (default `ralph-retry`)
`export [file]` / `import <file> [--with-host]`	JSON snapshot of `.squad/` (optional host files)
`externalize [--key name]` / `internalize`	Move this project's team out of the worktree
`nap [--dry-run] [--deep]` / `scrub-emails [directory]`	Context and PII hygiene
`upstream add <name> <path\|git-url>` / `list` / `remove` / `sync`	Remember and pull extra agents/skills
`pack <path\|git-url>`	One-shot pull of extra agents/skills
`link <team-dir	git-url>`/`link --sync`/`link --off`
`update-check [--json] [--refresh]`	Prints `up to date` or `update available` vs GitHub latest tag
`traces [--last N] [--json] [--export file] [--follow]`	Local spans plus OpenCode SQLite ingest (TUI/Web/serve); `--export` writes OTLP JSON; optional live push via `OTEL_EXPORTER_OTLP_*`
`mcp apply` / `list` / `init`	Merge org `.squad/mcp-config.json` into `opencode.json`
`marketplace add` / `list` / `remove` / `browse` / `install`	Register a skills pack and copy a plugin into `.opencode/skills/`
`plugin install <name>@<marketplace>` / `list` / `uninstall <name>`	Named skill install; uninstall removes only `.opencode/skills/<name>/`
`help` / `version`	Usage and version string

Layout

cmd/squad-oc/            # main → internal/cli
internal/cli/            # commands
internal/squad/          # init, upgrade, export, externalize, nap, scrub, templates
internal/opencodeclient/ # SDK + run (needs `opencode serve`)
internal/watch/          # issue triage (Ralph): health, overnight, backends
internal/githubissues/   # gh issue list
internal/share/          # upstream / pack / link
internal/traces/         # local JSONL spans + OTLP export
internal/opencodestore/  # read-only OpenCode SQLite (TUI ingest)
internal/selfupdate/     # upgrade --self
internal/updatecheck/
internal/version/
docs/

Architecture

squad-oc (Go)
  ├── embed templates → .squad / .opencode
  └── github.com/sst/opencode-sdk-go → opencode serve (:4096)

opencode (TUI) and opencode serve (HTTP API) are different. Only serve works with run and watch --execute.

run / watch --execute attach to an existing server, or start opencode serve --hostname 127.0.0.1 --port 4096 in this project. They never auto-start if --url or OPENCODE_BASE_URL is anything other than http://127.0.0.1:4096 / http://localhost:4096. The serve process is left running.

upgrade refreshes host templates (.opencode/). It never overwrites team memory (team.md, decisions, knowledge).

upgrade --self downloads the latest GitHub Release for this OS/arch and replaces the running binary. On Windows, if the exe is locked, it writes squad-oc.exe.new beside it (replaced on next start).

traces lists local spans from run and watch --execute, and ingests completed TUI/Web/serve turns from OpenCode SQLite (default $XDG_DATA_HOME/opencode/opencode.db or ~/.local/share/opencode/opencode.db on every OS, including Windows %USERPROFILE%\.local\share\opencode\opencode.db). Override with OPENCODE_DB or opencode_db in .squad/config.json. Dedup is by assistant messageId so a later TUI turn on a CLI session still ingests. --follow polls every 2s. --export file writes OTLP JSON any collector can ingest. Set OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) to push live during run / watch --execute and on ingest. Protocols: http/protobuf (default) and grpc via OTEL_EXPORTER_OTLP_PROTOCOL. Prompt/completion bodies always land in local JSONL; OTel message attributes only when OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is on (default off). Langfuse groups turns by OpenCode ses_* (session.id). For in-process streaming, the official Langfuse OpenCode plugin is optional and separate; we do not install it. Aspire Dashboard remains a valid OTLP consumer, not a shipped squad-oc command.

Share extra agents (`upstream` / `pack`)

Your company keeps a security pack — extra OpenCode agents and a Designer charter — in a git repo or a folder on disk.

# One-shot: drop those files into *this* project
squad-oc pack https://github.com/acme/squad-security-pack.git
# or a local folder you already cloned
squad-oc pack ~/packs/security

# Remember it and pull again when the pack updates
squad-oc upstream add security https://github.com/acme/squad-security-pack.git
squad-oc upstream sync security     # next quarter: same command
squad-oc upstream list

pack / sync refresh .opencode/ (agents, skills, commands). New .squad/agents/<name>/ files are added only if missing. team.md, decisions, and existing knowledge are never overwritten.

A pack is just a directory that contains .opencode/ (or a bare agents/ / skills/ / commands/ tree). Optional .squad/agents/… stubs are fine.

Share one team across repos (`link`)

Platform Lead, decisions, and knowledge live in one place. Billing and Checkout both use that team.

# once: a dedicated team folder (or any repo that already has .squad/)
mkdir -p ~/teams/platform && cd ~/teams/platform
git init && squad-oc init --preset default --description "Platform team"

cd ~/code/billing
squad-oc init --preset default
squad-oc link ~/teams/platform          # also accepts ~/teams/platform/.squad

cd ~/code/checkout
squad-oc init --preset default
squad-oc link ~/teams/platform

squad-oc status                         # both show the same members
# later
squad-oc link --off                     # this repo uses its local .squad/ again

# or, no local clone — cache lives in ~/.squad-oc/links/
squad-oc link https://github.com/acme/squad-platform.git
squad-oc link --sync                    # fetch updates
squad-oc link --off

link does not move files. Config stays in each repo; team.md / charters / decisions are read from the shared directory. Cannot combine with externalize (that moves this project's own team out of the worktree).

Change the cast (`cast --add` / `cast --remove` / `recast`)

squad-oc cast --add Designer --role Design
# appends Designer to team.md, writes charter/knowledge, regenerates .opencode/agents

squad-oc cast --remove Designer
# drops the member and regenerates .opencode/agents

# or edit .squad/team.md by hand, then:
squad-oc recast

OpenCode only sees agents that exist under .opencode/agents/. Recast is what makes a new row in team.md show up as @designer. It never touches squad.md (the coordinator).

Overnight watch

# poll and execute during the day; sleep 18:00–08:00 local
squad-oc watch --execute --interval 10 --overnight-start 18:00 --overnight-end 08:00

During the quiet window it does not call opencode serve. Stop anytime with touch .squad/ralph-stop.

watch --health prints the last ralph-status.json snapshot. --state-backend git-notes or orphan-branch persists that snapshot across restarts (default is the local file).

Non-goals

Original-Squad / Copilot-host pieces we are not building:

GitHub Copilot CLI / Copilot SDK
Interactive Ink/squad shell (use the OpenCode TUI)
Aspire / .NET dashboard (won’t ship; point any OTLP consumer at optional push or traces --export)

Develop

go test ./...
go build -o squad-oc ./cmd/squad-oc

Requires Go 1.26.6+. How to send a change: CONTRIBUTING.md.

License

MIT — see LICENSE.

Navigation Menu

Repository files navigation

squad-opencode

Install

Quick start

Also useful

What to commit

Commands

Layout

Architecture

Share extra agents (`upstream` / `pack`)

Share one team across repos (`link`)

Change the cast (`cast --add` / `cast --remove` / `recast`)

Overnight watch

Non-goals

Develop

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.beads		.beads
.github		.github
.opencode		.opencode
.squad		.squad
Casks		Casks
bucket		bucket
cmd/squad-oc		cmd/squad-oc
docs		docs
internal		internal
packaging/winget		packaging/winget
scripts		scripts
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
go.mod		go.mod
go.sum		go.sum
opencode.json		opencode.json
tap_migrations.json		tap_migrations.json

Latest commit

History

Folders and files

Repository files navigation

squad-opencode

Install

Quick start

Also useful

What to commit

Commands

Layout

Architecture

Share extra agents (upstream / pack)

Share one team across repos (link)

Change the cast (cast --add / cast --remove / recast)

Overnight watch

Non-goals

Develop

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Share extra agents (`upstream` / `pack`)

Share one team across repos (`link`)

Change the cast (`cast --add` / `cast --remove` / `recast`)