794a9ee8a8
Adds gt peek as ergonomic alias for gt session capture: gt peek gastown/furiosa # Last 100 lines gt peek gastown/furiosa 50 # Last 50 lines Creates nudge/peek pair as canonical session interface: gt nudge - send TO session (reliable delivery) gt peek - read FROM session (capture-pane wrapper) Adds docs/session-communication.md explaining: - Why raw tmux send-keys is unreliable for Claude - The reliable NudgeSession pattern (literal + delay + Enter) - Command reference and common patterns - Guidance for template authors 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
127 lines
3.1 KiB
Markdown
127 lines
3.1 KiB
Markdown
# Session Communication: Nudge and Peek
|
|
|
|
Gas Town agents communicate with Claude Code sessions through **two canonical commands**:
|
|
|
|
| Command | Direction | Purpose |
|
|
|---------|-----------|---------|
|
|
| `gt nudge` | You → Agent | Send a message reliably |
|
|
| `gt peek` | Agent → You | Read recent output |
|
|
|
|
## Why Not Raw tmux?
|
|
|
|
**tmux send-keys is unreliable for Claude Code sessions.**
|
|
|
|
The problem: When you send text followed by Enter using `tmux send-keys "message" Enter`,
|
|
the Enter key often arrives before the paste completes. Claude receives a truncated
|
|
message or the Enter appends to the previous line.
|
|
|
|
This is a race condition in tmux's input handling. It's not a bug - tmux wasn't
|
|
designed for pasting multi-line content to interactive AI sessions.
|
|
|
|
### The Reliable Pattern
|
|
|
|
`gt nudge` uses a tested, reliable pattern:
|
|
|
|
```go
|
|
// 1. Send text in literal mode (handles special characters)
|
|
tmux send-keys -t session -l "message"
|
|
|
|
// 2. Wait 500ms for paste to complete
|
|
time.Sleep(500ms)
|
|
|
|
// 3. Send Enter as separate command
|
|
tmux send-keys -t session Enter
|
|
```
|
|
|
|
**Never use raw tmux send-keys for agent sessions.** Always use `gt nudge`.
|
|
|
|
## Command Reference
|
|
|
|
### gt nudge
|
|
|
|
Send a message to a polecat's Claude session:
|
|
|
|
```bash
|
|
gt nudge <rig/polecat> <message>
|
|
|
|
# Examples
|
|
gt nudge gastown/furiosa "Check your mail and start working"
|
|
gt nudge gastown/alpha "What's your status?"
|
|
gt nudge gastown/beta "Stop what you're doing and read gt-xyz"
|
|
```
|
|
|
|
### gt peek
|
|
|
|
View recent output from a polecat's session:
|
|
|
|
```bash
|
|
gt peek <rig/polecat> [lines]
|
|
|
|
# Examples
|
|
gt peek gastown/furiosa # Last 100 lines (default)
|
|
gt peek gastown/furiosa 50 # Last 50 lines
|
|
gt peek gastown/furiosa -n 200 # Last 200 lines
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Check on a polecat
|
|
|
|
```bash
|
|
# See what they're doing
|
|
gt peek gastown/furiosa
|
|
|
|
# Ask for status
|
|
gt nudge gastown/furiosa "What's your current status?"
|
|
```
|
|
|
|
### Redirect a polecat
|
|
|
|
```bash
|
|
# Stop current work and pivot
|
|
gt nudge gastown/furiosa "Stop current task. New priority: read and act on gt-xyz"
|
|
```
|
|
|
|
### Wake up a stuck polecat
|
|
|
|
```bash
|
|
# Sometimes agents get stuck waiting for input
|
|
gt nudge gastown/furiosa "Continue working"
|
|
```
|
|
|
|
### Batch check all polecats
|
|
|
|
```bash
|
|
# Quick status check
|
|
for p in furiosa nux slit; do
|
|
echo "=== $p ==="
|
|
gt peek gastown/$p 20
|
|
done
|
|
```
|
|
|
|
## For Template Authors
|
|
|
|
When writing agent templates (deacon.md.tmpl, polecat.md.tmpl, etc.), include this guidance:
|
|
|
|
```markdown
|
|
## Session Communication
|
|
|
|
To send messages to other agents, use gt commands:
|
|
- `gt nudge <rig/polecat> <message>` - Send reliably
|
|
- `gt peek <rig/polecat>` - Read output
|
|
|
|
⚠️ NEVER use raw tmux send-keys - it's unreliable for Claude sessions.
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
The nudge/peek commands wrap these underlying functions:
|
|
|
|
| Command | Wrapper | Underlying |
|
|
|---------|---------|------------|
|
|
| `gt nudge` | `tmux.NudgeSession()` | literal send-keys + delay + Enter |
|
|
| `gt peek` | `session.Capture()` | tmux capture-pane |
|
|
|
|
The 500ms delay in NudgeSession was determined empirically. Shorter delays fail
|
|
intermittently; longer delays work but slow down communication unnecessarily.
|