check

name	check
description	Use to check on background feature agents launched via /kickoff — running in tmux sessions or docker/podman containers. Reports each agent's state (Working / Idle / Waiting / Done / Error), captures recent output, and offers next-step commands. Trigger when the user says "check on the agent(s)", "how's the kickoff going", or names a `feat-*` / `crosslink-task-*` session.

Check — status of background feature agents

The user optionally provides an agent name (e.g. crosslink-task-add-batch-retry or feat-add-batch-retry). If no name is given, check all active feature agents (both containers and tmux sessions) and report a summary for each.

1. Identify agents to check

a. Find container-based agents

1. Get this repo's worktree paths: git worktree list --porcelain | grep '^worktree ' | sed 's/^worktree //'
2. List crosslink containers: docker ps -a --filter label=crosslink-agent=true --format '{{.Names}} {{.Status}} {{.Label "crosslink-task"}}' 2>/dev/null
3. Match containers to this repo: for each container, check if its crosslink-task label value matches any of this repo's worktree directory names (the last path component)
4. If the user provided a name starting with crosslink-task-, filter to that specific container

b. Find tmux-based agents

1. Get feat-* tmux sessions: tmux list-sessions -F '#{session_name} #{session_path}' 2>/dev/null | grep '^feat-'
2. Only include sessions whose session_path matches one of this repo's worktree paths
3. If the user provided a name starting with feat-, filter to that specific session

If no agents found in either mode, report "No active feature agents for this repo."

2. For each agent, perform these checks

For container-based agents

a. Check the sentinel file

Get the worktree path by matching the container's crosslink-task label to a worktree directory name from git worktree list.

• Check: cat <worktree-path>/.kickoff-status 2>/dev/null
• If it contains DONE, mark as finished.
• If it contains CI_FAILED, mark as CI failure.

b. Check container status

docker inspect --format '{{.State.Status}} (exit {{.State.ExitCode}})' <container-name>

Possible states: running, exited (check exit code), restarting, paused.

c. Capture recent output

docker logs --tail 80 <container-name> 2>&1

d. Analyze state

• Working: Container status is running, no sentinel file, recent tool calls visible in logs
• Idle: Container is running but no recent output changes — may be thinking or waiting for API
• Error: Container exited with non-zero exit code, or error messages in recent logs
• Done: Sentinel file says DONE, or container exited with code 0
• CI Failed: Sentinel file says CI_FAILED

For tmux-based agents

a. Check the sentinel file

Get the worktree path for this session from tmux: tmux display-message -t <session-name> -p '#{session_path}'. Alternatively, match the session name to a feature branch in git worktree list.

• Check if .kickoff-status exists in the worktree: cat <worktree-path>/.kickoff-status 2>/dev/null
• If it contains DONE, mark this session as finished.

b. Capture the terminal state

tmux capture-pane -t <session-name> -p -S -80

This captures the last ~80 lines of visible output.

c. Analyze state

Read the captured output and determine the agent's current state:

• Working: Tool calls in progress, code being written/read
• Waiting for input: A question or prompt is displayed (look for ?, option lists, or input prompts)
• Error/stuck: Error messages, repeated failures, or no recent activity
• Completed: The sentinel file says DONE, or the claude process has exited

3. Report

When checking multiple agents, use a compact table format with a backend indicator:

Feature Agents:

  crosslink-task-add-retry    [container]  Working    Implementing retry logic in _sources.py
  crosslink-task-fix-lens     [container]  Done       All changes committed and reviewed
  feat-new-cli-cmd            [tmux]       Waiting    Asking about CLI argument format

When checking a single agent, use the detailed format:

Agent:    <name>
Backend:  <container|tmux>
Status:   <Working | Idle | Waiting | Done | Error>

<2-3 sentence summary of what the agent is currently doing or has accomplished>

For container agents, also show resource usage:

docker stats --no-stream --format '  CPU: {{.CPUPerc}}  Memory: {{.MemUsage}}' <container-name> 2>/dev/null

4. Offer actions

For container agents

• If working/idle: "Check back later, or view live logs: crosslink container logs <name> -f"
• If done: "Agent finished. Review the changes: cd <worktree-path> && git log --oneline <base-branch>..HEAD"
• If error: Show the relevant error output. Suggest: "Debug with: crosslink container shell <name> or view full logs: crosslink container logs <name> --tail 500"
• If exited (non-zero): "Container exited with error. View logs: crosslink container logs <name>. Restart with: crosslink container kill <name> && crosslink container start <worktree-path>"

For tmux agents

• If working: "Check back later, or attach directly: tmux attach -t <name>"
• If waiting for input: Read the question, and ask the user what to answer. If the user provides an answer, send it: tmux send-keys -t <session-name> "<response>" Enter
• If done: "Agent finished. Review the changes: cd <worktree-path> && git log --oneline <base-branch>..HEAD"
• If error: Show the relevant error output and suggest the user attach to debug: tmux attach -t <name>

Constraints

• Do not modify any files in the worktree — this is a read-only check.
• Do not kill containers or tmux sessions unless the user explicitly asks.
• When relaying a user's answer to a waiting tmux prompt, send exactly what the user provides — do not embellish or modify.