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.

The core idea: there are two communication lanes.

  1. You steer work by typing directly to agents in their terminal tabs.
  2. Agents coordinate with each other via recalletta crew message plus persistent mail-board reports.

The Two Communication Lanes

Lane 1: You Talk To Agents (In Their Sessions)

macOS: Each recalletta crew summon opens a new Terminal.app tab attached to the agent's tmux session. You can switch to that tab and type directly to the agent.

Linux: Agents run in tmux sessions but no terminal tabs are opened automatically. Use recalletta crew attach <name> to attach to an agent's session and interact with it directly.

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."

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

Agents use recalletta crew message for short coordination messages and .crew/mail-board/ for long-form reports.

Everything is logged to .crew/history.md.

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

First-Time Setup (Per Repo)

Run this once in the repository:

recalletta crew init

recalletta crew start

This bootstraps crew state and summons the team lead persona.

Summon A Specific Agent (Optional)

You can also summon an agent directly:

recalletta crew summon atlas "Coordinate a homepage draft, then send it for review"

Summon More Agents

The user (or the team lead agent) can summon specialists:

recalletta crew summon forge "Fix the performance regression in the auth module"
recalletta crew summon harbor "Review forge's fix when it's ready"
recalletta crew summon circuit --client codex "Write integration tests for the auth module"

List active agents:

recalletta crew list

Representative output (hostnames redacted):

Crew: Atlas
  atlas   (claude) @my-machine registered
  forge   (claude) @my-machine registered
  harbor  (claude) @my-machine registered
  circuit (codex)  @my-machine registered

Some personal information has been redacted for security and ethical considerations.

Steering An Agent (Lane 1)

Switch to the agent's terminal tab (macOS) or attach with recalletta crew attach <name> (Linux) 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 (crew message)

Agents send quick messages with crew message:

recalletta crew message atlas "Fix is done. Root cause was INSERT after spawn. Build clean; tests pass."

Multi-recipient messages are common (CC-style):

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

Broadcast:

recalletta crew message all "Online. Taking the architecture review."

What These Messages Look Like In The Log

.crew/history.md records a timestamped paper trail. Representative excerpt (format matches the real log):

[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 over SSH terminal support for crew summon tabs; will report options soon.

Some personal information has been redacted for security and ethical considerations. If sharing logs externally, redact names and hostnames.

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 crew message message pointing to it (filename + summary).
  3. Recipient reads the report and responds (often with another report).

Inbox And Audit Trail

To see recent crew activity:

recalletta crew inbox

That command tails .crew/history.md.

Common Patterns

Directed Team

  1. You give a high-level task to the team lead.
  2. The lead summons specialists.
  3. Specialists coordinate directly with each other.
  4. The lead reports back to you with a summary and links to mail-board artifacts.

Review Chain

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

Releasing Agents

When an agent is done:

recalletta crew release forge

To clear crew state and start fresh:

recalletta crew clear

Gotchas

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

crew message targets active registered agents in the current crew (see recalletta crew list).

If you run crew message from a random shell context (not from a crew agent session, and without a configured user_name), sender/target resolution can fail. In that case, the human-friendly workflow is:

  • Type directly in the agent tab (Lane 1), or
  • Use recalletta crew start (which registers your environment) and then try again.

Shell metacharacters in messages

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

See Also