tell

name	tell
description	Delegate tasks to other agents - pi sessions or external agents (claude, opencode, aider). Non-blocking with task tracking and completion notifications.
script	scripts/tell.sh

Tell / Delegate

Delegate tasks to other agents. Works with both pi agent sessions and external agents (Claude Code, opencode, aider).

Script location: ~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh

Note: All commands below use tell.sh for brevity. Always use the full path above when executing.

Auto-notification: When a delegated task completes, you'll be notified via:

1. ntfy - Push notification to your devices
2. Session message - [TASK_RESULT:id] sent to your pi session

Tell a pi agent

Send a task to another pi agent running in a tmux session:

# Use full path (recommended)
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh mega "fix the failing tests in src/auth"
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh rx "review PR #42 and leave comments"

Explicit window targeting with session:window syntax:

~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh rx:agent "do something"    # Target rx session, agent window
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh mega:0 "do something"      # Target mega session, window 0

Modern /tell and tell_pi routing: Prefer the Pi extension over this legacy script. It discovers live Pi manifests and sockets, excludes the originating instance from implicit selection, and hard-errors when an explicit target is missing, ambiguous, or busy/unreachable. In non-interactive tool calls, it never opens selector UI or falls back to the current instance; errors list reachable non-current candidates.

Machine + tmux target syntax: /tell also accepts a machine before the tmux target. It SSHes to the machine, resolves ${PI_STATE_DIR:-~/.local/state/pi}/sockets/pi-{session}-{window}.sock there, and sends the same pi.tell.v1 payload.

/tell megabookpro mega "do something special"       # Remote machine, best Pi socket in tmux session mega
/tell megabookpro mega:agent "do something special" # Remote machine, explicit window
/tell workbookpro mega "do something special"       # Local machine prefix; routes as /tell mega ... on workbookpro

Multi-instance support: If a session has multiple pi instances (e.g., mega:0 and mega:agent), the tell skill will:

1. If session:window specified → use that socket directly
2. Otherwise try socket first (cleaner, no shell pollution)
3. Prefer the agent window socket, then window 0, then any available
4. Fall back to tmux send-keys if no socket available

Socket pattern: ${PI_STATE_DIR:-~/.local/state/pi}/sockets/pi-{session}-{window}.sock

Delegate to external agents (yolo mode)

Spawn an external agent in a tmux session to handle a task:

~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --agent claude "run the user-story-sync skill"
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --agent opencode "fix the failing tests in src/auth"
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --agent aider "refactor the database module"

Supported agents:

• claude - Claude Code (runs with --dangerously-skip-permissions)
• opencode - OpenCode
• aider - Aider (runs with --yes-always)
• codex - Codex CLI (runs with --full-auto)

Returns immediately. The agent runs in a background tmux session.

Task management

~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --list                    # List all tasks
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --status TASK_ID          # Check task status & output
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --watch TASK_ID           # Watch external task live
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --kill TASK_ID            # Kill a running external task

When you receive a task (pi agents)

You'll see: [TASK:abc123 from mega] do the thing

Send updates:

~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --update abc123 "halfway done"
~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh --done abc123 "finished, all tests pass"

Attach to external agent session

For interactive debugging, attach directly:

tmux -S ~/.local/state/pi/agent-sockets/tasks.sock attach -t task-abc123-claude

Detach with Ctrl+b d.

Completion notifications

When a task completes (either external agent or pi agent calling --done):

1. ntfy notification sent with task summary

2. Message sent to delegator's session:

   [TASK_RESULT:abc123] claude completed: Task finished successfully
   Original task: run the user-story-sync skill...
   

This lets you fire-and-forget tasks and get notified when they're done.

Examples

# Define shorthand for readability
TELL="~/.dotfiles/home/common/programs/pi-coding-agent/skills/tell/scripts/tell.sh"

# Tell specific window in a session
$TELL rx:agent "review the changes and suggest improvements"

# Auto-select best window (prefers 'agent', then '0')
$TELL mega "run the test suite"

# Delegate to Claude Code
$TELL --agent claude "run the user-story-sync skill"

# Check what's happening
$TELL --list
$TELL --status abc123