OpenTeam

Agent team collaboration framework. Pluggable CLI backend (Claude Code / OpenCode).

What it does

• Multi-agent teams with async messaging (MCP-based)
• Built-in task board with dependency tracking and auto-notification
• Daemon manages the full lifecycle: server, agent panes, health checks, respawn
• Real-time dashboard (embedded TUI)
• Works with tmux or zellij

Requirements

Dependency	Version
Node.js	18+
tmux or zellij	any

Install

npm install -g openteam

Quick Start

# 1. Install a built-in team template
openteam setup

# 2. Start the team
openteam start dev

openteam setup walks you through:

Available team templates:

  1) dev-team
     A four-role agent team for software development.
     agents: pm, architect, developer, qa

Install "dev-team"? (Y/n): Y
Team name (team1): dev
Default CLI (claude-code):
Enable yolo mode? (y/N): y

✓ Team "dev" installed

  Template:   dev-team
  Config:     ~/.openteam/teams/dev/team.json
  Leader:     pm
  Agents:     pm, architect, developer, qa
  CLI:        claude-code
  Agent defs: 4 → ~/.openteam/agents
  Skills:     12 → ~/.openteam/skills

CLI Commands

Command	Description
openteam setup	Install a built-in team template (interactive)
openteam start [team]	Start team (creates tmux/zellij session + daemon)
openteam start [team] -d	Start in background
openteam list / openteam ls	List running team instances
openteam list -a	List all teams (including stopped)
openteam stop <target>	Stop team (by name or instance ID)
openteam inspect <team>	Show runtime status and agent online state

The same team can run in multiple project directories simultaneously. Use --dir to target a specific instance when ambiguous.

Team Tools (MCP)

Agents communicate through two MCP tools exposed by the openteam server:

Tool	Access	Description
msg	All agents (leader can broadcast)	Async messaging between agents
taskboard	create: leader only; done/list: all	Task management with dependency tracking

Messages are delivered to agent queues and injected into the CLI via PTY. Offline agents receive messages when they reconnect.

Example: Dev Team

examples/dev-team/ provides a complete four-role development team, ready to use.

Roles

Agent	Role	Responsibilities
pm (leader)	Product Manager	Clarify requirements, write PRDs, coordinate
architect	Architect	Read codebase, design implementation plans, review
developer	Developer	Implement per plan, write unit tests
qa	QA Engineer	Design test plans, run acceptance tests, report bugs

Workflow

User request → PM clarifies requirements & writes PRD
                  ↓                        ↓
            Architect designs         QA designs test plan
            implementation plan       (in parallel)
                  ↓
            Developer implements + unit tests
                  ↓
            QA runs acceptance tests
                  ↓
            PM reports results to user

Built-in Skills

• PM: requirement-clarification, prd-generation, system-discovery
• Architect: codebase-mapping, implementation-planning, architecture-review
• QA: test-plan-design, acceptance-testing, bug-reporting

Configuration

Team config (~/.openteam/teams/<team>/team.json)

{
  "name": "dev",
  "leader": "pm",
  "agents": ["pm", "architect", "developer", "qa"],
  "default_cli": "claude-code",
  "cli_config": {
    "claude-code": {
      "args": ["--permission-mode", "bypassPermissions"]
    }
  }
}

• leader must be in agents.
• cli_config passes extra arguments to the underlying CLI.
• port (optional): fixed port; default 0 auto-selects from 4096-4200.

Directory layout

~/.openteam/
├── settings.json                 # Global settings
├── agents/                       # Agent definitions (shared across teams)
│   ├── pm.md
│   ├── architect.md
│   └── ...
├── skills/                       # Skill definitions
│   ├── requirement-clarification/
│   └── ...
└── teams/
    └── <team>/
        ├── team.json             # Team config
        └── <hash>/               # Project-scoped runtime state
            ├── .state.json       # daemon/server/mux state
            └── .tasks.json       # Task board data

Project isolation: <hash> = first 8 hex chars of SHA-256(projectDir).

Architecture

bin/openteam.js              CLI entry (Commander routing)

src/
├── interfaces/              Who's calling
│   ├── cli.js               Commands: setup, start, stop, list, inspect
│   ├── daemon/              Daemon lifecycle (server + panes + health)
│   └── dashboard/           Embedded TUI (blessed)
├── server/                  Communication layer
│   ├── hub.js               In-memory message queue
│   ├── mcp.js               MCP tools (msg + taskboard)
│   └── routes.js            REST API (register/messages/status/tasks)
├── adapters/                CLI abstraction (claude-code / opencode)
├── wrapper/                 PTY bridge (register → MCP config → spawn CLI → poll)
├── capabilities/            Business logic (taskboard)
└── foundation/              Infrastructure (config, state, terminal, logger)

Dependency rule: Interfaces → Capabilities → Foundation. No reverse dependencies.

Debugging

# Enable logging
OPENTEAM_LOG=1 openteam start myteam

# Set log level (debug/info/warn/error)
OPENTEAM_LOG=1 OPENTEAM_LOG_LEVEL=debug openteam start myteam

Log file: ~/.openteam/openteam.log

License

MIT