Crew Workflows

This page explains how a real crew session works in practice. For the command reference, see Crew. For the conceptual overview, see Concepts. For dashboard controls, see The Terminal Dashboard.

The core idea: there are two communication lanes.

  1. You steer work through the dashboard — switching tabs, typing directly to agents, and using built-in controls.
  2. Agents coordinate with each other via crew messaging and persistent mail-board reports.

The Two Communication Lanes

Lane 1: You Talk To Agents (Dashboard)

The terminal dashboard gives you a tab for each active agent. Switch to any tab with F1–F9 (or F10/F11 to cycle) and type directly — your keystrokes go straight to that agent's session.

Use this lane for:

  • Steering: "Stop. Don't touch auth. Focus on API routes."
  • Quick clarifications: "What file are you editing right now?"
  • Redirecting: "Pause this. Run the tests first."

You can also send messages without switching tabs. Press F12, m to open the message composer, or use slash commands (F12, /) for quick operations.

Fallback (no dashboard): Attach directly to an agent's tmux session with metateam crew attach <name>.

Lane 2: Agents Coordinate (Message + Mail-Board)

Agents use metateam crew message in their terminals for short coordination messages and .crew/mail-board/ for long-form reports.

Everything is logged to .crew/history.md. View the log in the dashboard with F12, c (comm log panel).

Use this lane for:

  • Asynchronous coordination between specialists
  • Durable conclusions (reports you can read tomorrow)
  • A paper trail (what happened, who said what, when)

Starting Your First Crew Session

metateam

On first run in a new repo, this handles setup automatically: initializes crew state, launches the dashboard, and summons the crew leader (Data). Tell Data what you need.

Option B: Start The Crew Manually

If you prefer explicit control:

metateam crew init    # one-time per repo
metateam crew start   # bootstraps and summons leader

Option C: Summon A Specific Agent

metateam crew summon forge "Fix the performance regression in the auth module"

Summoning More Agents

The preferred workflow is to ask the crew leader to summon specialists. Type directly in the leader's tab:

"Summon forge to fix the auth module and harbor to review it."

You can also summon from the dashboard:

Method How
Summon dialog F12, a — type persona name, press Enter
Slash command F12, / then /summon forge
Direct CLI metateam crew summon forge "task description"

List active agents: press F12, / then /crew, or run metateam crew list from any shell.

Steering An Agent (Lane 1)

Switch to the agent's tab in the dashboard and type directly:

you: Skip JWT. Use API keys instead.
agent: Understood. Switching to API keys.

This is the "director" workflow: you give high-level intent, watch progress, and course-correct in real time.

Agent-To-Agent Coordination (Lane 2)

Short Messages

Agents send quick messages using metateam crew message in their terminals:

metateam crew message atlas "Fix is done. Root cause was INSERT after spawn."

Multi-recipient messages are common:

metateam crew message harbor,atlas "Review complete. Both findings fixed."

You can also send messages from the dashboard: press F12, m and type atlas Fix is done. Or use /msg atlas Fix is done. via slash commands.

What Messages Look Like In The Log

.crew/history.md records a timestamped paper trail. View it in the dashboard with F12, c:

[2026-02-10 08:15:36] [atlas to drift,ember]: TASK DOCS: Two manual pages needed.
[2026-02-10 08:15:44] [atlas to nimbus]: SUMMON
[2026-02-10 08:15:59] [nimbus to all]: Looking at Linux SSH support for crew tabs.

Mail-Board Reports (Long-Form)

For anything longer than a few sentences (architecture proposals, reviews, implementation notes), agents write markdown files to .crew/mail-board/.

File naming convention:

[yyyy-MM-dd_HH-mm-ss]-[from]-to-[recipients]-[topic].md

Typical workflow:

  1. Agent writes the report to .crew/mail-board/.
  2. Agent sends a short message pointing to it (filename + summary).
  3. Recipient reads the report and responds.

Dashboard-to-CLI Equivalence

Dashboard action Dashboard shortcut CLI equivalent
Summon agent F12, a metateam crew summon <name>
Send message F12, m metateam crew message <target> <msg>
Broadcast /broadcast <text> metateam crew message all <msg>
Release agent /release <name> metateam crew release <name>
List crew /crew metateam crew list
View screen /screen <name> metateam crew screen <name>
Reset agent /reset <name> metateam crew reset <name>
Silence crew F12, p metateam crew shutup
Search KB /kb <query> metateam kb search <query>
View comms F12, c metateam crew inbox
Direct attach F12, Enter metateam crew attach <name>

Common Patterns

Directed Team

  1. You tell the crew leader what you need.
  2. The leader summons specialists.
  3. Specialists coordinate directly with each other.
  4. The leader reports back with a summary and links to mail-board artifacts.

Review Chain

  1. Implementer works.
  2. Reviewer reviews.
  3. Tester runs and reports.
  4. Leader (or you) merges the outcome.

Releasing Agents

From the dashboard, use slash commands:

/release forge

Or from the CLI:

metateam crew release forge

To clear crew state and start fresh:

metateam crew clear

Gotchas

"Agent not found" / "Could not determine caller"

crew message targets active registered agents in the current crew (check with /crew or metateam crew list).

If you run crew message from a random shell context (not from an agent session, and without a configured user_name), sender/target resolution can fail. The dashboard avoids this problem — use the message composer (F12, m) instead.

Shell metacharacters in messages

Message bodies are delivered via tmux send-keys. Avoid shell metacharacters (especially *, backticks, and unescaped quotes) in messages. Use the mail-board for structured content.

See Also