Run your first multi-agent workflow

This tutorial teaches the session-targeting pattern used to coordinate coding
agents with it2. You will create two worker panes, give each one a separate
task, verify both results, and close only the panes you created.

The workers use deterministic shell commands so you can complete the tutorial
without agent credentials. Once the workflow is familiar, the same session IDs
can target Codex, Claude Code, Gemini CLI, or another terminal agent.

Before you begin

Complete the quick start first. Run this tutorial from an
iTerm2 session so it2 knows which pane to split.

1. Create two workers

Create vertical and horizontal splits. Save each returned session ID:

worker_a=$(it2 session split --vertical --quiet --cwd "$PWD")
worker_b=$(it2 session split --horizontal --quiet --cwd "$PWD")
printf 'worker_a=%s\nworker_b=%s\n' "$worker_a" "$worker_b"

Observed output has this shape:

worker_a=BB0F42D8-DCB6-4401-828D-AFE6A8DD7DF2
worker_b=B28E7574-DB86-4F24-839A-92A528F1ACDE

Your session IDs will differ. Keep them: each later command targets one worker
explicitly.

2. Dispatch separate tasks

Send a distinct task to each worker. Delivery confirmation is skipped because
the next step reads both screens:

it2 session send-text "$worker_a" --skip-confirm \
  "printf 'worker-a: review complete\n'"
it2 session send-text "$worker_b" --skip-confirm \
  "printf 'worker-b: tests complete\n'"

it2 identifies each source and destination on standard error:

[it2:send-text src=6D463C4D dst=BB0F42D8]
[it2:send-text src=6D463C4D dst=B28E7574]

This is the dispatch step in a coding-agent workflow: retain each worker's
session ID, then send that worker its own prompt or command.

3. Verify both results

Read each worker's visible screen and select the expected result:

it2 get-screen "$worker_a" |
  rg 'worker-a: review complete' | tail -1
it2 get-screen "$worker_b" |
  rg 'worker-b: tests complete' | tail -1

Observed output:

worker-a: review complete
worker-b: tests complete

Do not infer completion from successful delivery alone. Reading the resulting
state gives the coordinator evidence that each worker finished the expected
task.

4. Clean up

Close exactly the sessions created by this tutorial:

it2 session close --force "$worker_a"
it2 session close --force "$worker_b"

Observed output:

Successfully closed session: BB0F42D8-DCB6-4401-828D-AFE6A8DD7DF2
Successfully closed session: B28E7574-DB86-4F24-839A-92A528F1ACDE

You have now practiced the core orchestration loop: create workers, retain
their identities, dispatch independent tasks, verify results, and clean up.

Use the pattern with coding agents

Choose the guide for the agent you run in each worker:

• Automate Claude Code
• Automate Gemini CLI
• Automate OpenAI Codex

For larger shell-driven workflows, continue with the
automation cookbook.