Developers
Use this page when you want to change Agent Teams itself, debug a team launch, or extend a runtime with MCP tools. The links below point to the canonical repo documents so implementation rules stay in one place.
Start here
| Need | Go to |
|---|---|
| Repo overview, scripts, and source setup | README.md |
| Agent navigation and architecture index | AGENTS.md |
| Working conventions for agents and contributors | CLAUDE.md |
| Hard implementation guardrails | AGENT_CRITICAL_GUARDRAILS.md |
| Medium and large feature structure | Feature architecture standard |
| Launch, bootstrap, and teammate messaging debugging | Agent team debugging runbook |
| Contribution process | Contributing guide |
| Release notes / Changelog | RELEASE.md — CHANGELOG.md |
Local development path
Run the desktop Electron app for normal development:
pnpm install
pnpm devThe browser/web path is not a replacement for the desktop runtime. Desktop mode is the supported local path because it includes IPC, terminals, provider auth, team lifecycle handling, launch diagnostics, and the runtime bridges used by real teams.
Architecture checkpoints
Before changing a feature, identify its boundary:
| Area | Expected home |
|---|---|
| Medium or large product feature | src/features/<feature-name>/ |
| Electron main process orchestration | src/main/ |
| Preload-safe API surface | src/preload/ |
| Renderer UI and app state | src/renderer/ |
| Shared types and pure helpers | src/shared/ |
| Agent Teams board MCP server | mcp-server/ |
| Board data controller | agent-teams-controller/ |
Use src/features/recent-projects as the reference slice for feature organization. Keep cross-process contracts explicit, and avoid deep imports across feature boundaries.
Debugging path
For launch hangs, OpenCode registered / bootstrap-unconfirmed states, missing teammate replies, or suspicious task logs:
- Start with the debugging runbook.
- Inspect the newest artifact pack under
~/.claude/teams/<team>/launch-failure-artifacts/latest.json. - Open the artifact
manifest.jsonand checkclassification, bootstrap breadcrumbs, launch diagnostics, member spawn statuses, and redacted log tails. - Clean up only the team, run, pane, or process you can identify as owned by the smoke test or failed launch.
MCP development path
Agent Teams uses a built-in MCP server named agent-teams for board operations. User and project MCP servers can add external capabilities for runtimes. See MCP integration for setup examples, .mcp.json structure, and tool registration guidance.