CodingAgent

Orchestrate multiple parallel coding agents using tmux sessions for PTY support and git worktrees for isolated development environments.

Workflow Routing

When executing a workflow, call the notification script via Bash:

${PAI_DIR}/tools/skill-workflow-notification WorkflowName CodingAgent

Examples

Example 1: Fix multiple GitHub issues in parallel

User: "Fix issues #123, #124, and #125 in parallel"
→ Invokes SpawnAgents workflow
→ Creates git worktrees for each issue
→ Spawns tmux sessions with Claude Code agents
→ Each agent works on one issue independently
→ Notifies via Telegram when complete

Example 2: Check progress on parallel agents

User: "How are my coding agents doing?"
→ Invokes MonitorSessions workflow
→ Lists active pai-agent-* tmux sessions
→ Captures recent output from each
→ Reports status and progress

Example 3: Collect finished work

User: "Gather the results from all agents"
→ Invokes CollectResults workflow
→ Checks which agents have completed
→ Summarizes changes per worktree
→ Provides merge instructions

Key Concepts

Why tmux?

Claude Code requires a pseudo-terminal (PTY) for interactive features. tmux provides:

• PTY allocation - Full terminal emulation for Claude Code
• Session persistence - Agents continue running if connection drops
• Output capture - Retrieve agent output without interrupting
• Parallel execution - Multiple independent sessions

Socket Isolation

All PAI agent sessions use a dedicated socket:

SOCKET="${TMPDIR:-/tmp}/pai-agents.sock"

This keeps PAI agents separate from user's personal tmux sessions.

Git Worktrees

Each agent gets an isolated worktree:

repo/
├── .git/                    # Main git directory
├── src/                     # Main working copy
└── .worktrees/              # Worktree directory
    ├── issue-123/           # Agent 1's isolated copy
    ├── issue-124/           # Agent 2's isolated copy
    └── issue-125/           # Agent 3's isolated copy

Benefits:

• No branch conflicts between agents
• Each agent has full file access
• Easy to review changes per issue
• Clean merge process

Completion Notifications

Agents send Telegram notifications when done:

bun ${PAI_DIR}/skills/TelegramStatus/tools/send-status.ts "Agent done: Issue #123 fixed"

CLI Tools

SessionManager.ts

Manage tmux sessions for coding agents.

# Create a new agent session
bun ${PAI_DIR}/skills/CodingAgent/tools/SessionManager.ts create issue-123 /path/to/worktree

# List all agent sessions
bun ${PAI_DIR}/skills/CodingAgent/tools/SessionManager.ts list

# Capture session output
bun ${PAI_DIR}/skills/CodingAgent/tools/SessionManager.ts capture issue-123

# Send keys to session
bun ${PAI_DIR}/skills/CodingAgent/tools/SessionManager.ts send issue-123 "your command"

# Kill a session
bun ${PAI_DIR}/skills/CodingAgent/tools/SessionManager.ts kill issue-123

# Attach to session (interactive)
bun ${PAI_DIR}/skills/CodingAgent/tools/SessionManager.ts attach issue-123

WorktreeManager.ts

Manage git worktrees for isolated development.

# Create worktree for an issue
bun ${PAI_DIR}/skills/CodingAgent/tools/WorktreeManager.ts create fix/issue-123 main

# List all worktrees
bun ${PAI_DIR}/skills/CodingAgent/tools/WorktreeManager.ts list

# Remove worktree after merge
bun ${PAI_DIR}/skills/CodingAgent/tools/WorktreeManager.ts remove fix/issue-123

AgentLauncher.ts

High-level tool to spawn complete agent environments.

# Launch agent for a specific issue
bun ${PAI_DIR}/skills/CodingAgent/tools/AgentLauncher.ts \
  --issue 123 \
  --repo /path/to/repo \
  --prompt "Fix the authentication bug in login.ts"

tmux Patterns Reference

See TmuxPatterns.md for detailed tmux command patterns.

Git Worktree Reference

See WorktreeGuide.md for git worktree best practices.

Requirements

• tmux - Terminal multiplexer (apt install tmux)
• git - With worktree support (2.5+)
• Claude Code - Installed and configured
• Telegram (optional) - For completion notifications