Build a disposable worker pane

This tutorial builds a small terminal automation workflow. You will create a
pane, retain its session ID, send it a command, read its screen, and close it.

Before you begin

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

1. Create a worker

Create a vertical split and save the new session ID:

worker=$(it2 session split --vertical --quiet --cwd "$HOME/tmp")
printf 'worker=%s\n' "$worker"

Observed output has this shape:

worker=2F669707-CBF2-49D9-9DA6-2BD5D03FC916

Your UUID will differ.

2. Inspect the worker

Ask for structured session information and select three fields:

it2 session get-info "$worker" --format json |
  jq '{session_id, session_badge, grid_size}'

Observed output:

{
  "session_id": "2F669707-CBF2-49D9-9DA6-2BD5D03FC916",
  "session_badge": "\\\\(id)",
  "grid_size": {
    "height": 22,
    "width": 71
  }
}

The UUID, badge, and dimensions depend on your iTerm2 profile and layout.

3. Send work to the pane

Send a command to the saved session. This example skips delivery confirmation
because the next step verifies the result from the screen:

it2 session send-text "$worker" --skip-confirm \
  "printf 'worker ready\\n'"

The command prints a source-and-destination log line on standard error:

[it2:send-text src=6D463C4D dst=2F669707]

4. Verify the result

Read the pane and select the line produced by the command:

it2 get-screen "$worker" | rg 'worker ready' | tail -1

Observed output:

worker ready

This is the important automation pattern: keep the session ID returned by a
creation command, target that session explicitly, and verify the resulting
state.

5. Clean up

Close only the pane created by this tutorial:

it2 session close --force "$worker"

Observed output:

Successfully closed session: 2F669707-CBF2-49D9-9DA6-2BD5D03FC916

Next steps