Terminal App: WebSocket-to-Claude-Code Bridge

Home Epics Terminal App: WebSocket-to-Claude-Code BridgeEdit

Cancel

Title *

Project *

Description

Build a terminal application that bridges Rails WebSocket messages to Claude Code sessions, enabling autonomous agent operation with full observability.

## Purpose

Agents (Worker, Reviewer, Orchestrator) run as long-lived Claude Code sessions. The terminal app:
1. Connects to Rails via WebSocket
2. Receives messages from Rails
3. Passes messages to Claude Code
4. Displays Claude Code output for observability
5. Keeps Claude Code session alive

## Research Requirements

Please provide feedback on:

### 1. Technology Stack

**Proposed Options:**
- **Go** - Compiled, good concurrency, single binary
- **Rust** - Compiled, safe, good async
- **Python** - Scriptable, but requires runtime
- **Node/TypeScript** - Good WebSocket libs, but heavier

**Questions:**
- Preference for compiled vs interpreted?
- Any existing infrastructure to consider?
- Deployment target (Docker, bare metal, etc.)?

### 2. WebSocket Client

**Requirements:**
- Connect to Rails ActionCable WebSocket endpoint
- Subscribe to agent-specific channel (`worker`, `reviewer`, `orchestrator`)
- Handle reconnection with backoff
- Authentication (API token or similar)

**Questions:**
- How should authentication work?
- Expected message format from Rails?
- Reconnection strategy preferences?

### 3. Claude Code Integration

**Key Challenge: How to interface with Claude Code CLI**

**Options:**
- **Subprocess** - Spawn `claude` process, write to stdin, read from stdout/stderr
- **PTY/pseudo-terminal** - More natural terminal emulation
- **Something else?**

**Questions:**
- Should Claude Code run with specific flags?
- How to handle Claude Code's interactive prompts?
- Need to capture both stdout and stderr separately?

### 4. Message Flow

**Proposed Flow:**
```
Rails → WebSocket: {"type": "assignment", "ticket_id": 58, "message": "Start work on #58"}
Terminal App → Receives → Passes to Claude Code stdin: "Start work on #58"
Claude Code → Processes → Updates Rails via MCP (independent)
Terminal App → Shows Claude Code output for observability
```

**Questions:**
- Is this flow correct?
- Should terminal app parse/filter Claude Code output?
- What specific messages should Rails send?

### 5. Console/Observability

**Requirements:**
- Display Claude Code output (stdout/stderr)
- Show WebSocket messages received
- Timestamps for all events
- Possibly log to file

**Questions:**
- Simple stdout console, or need TUI (ncurses-style)?
- Color formatting needed?
- Log rotation requirements?

### 6. Process Management

**Requirements:**
- Start Claude Code on terminal app startup
- Restart Claude Code if it crashes
- Health check mechanism
- Graceful shutdown

**Questions:**
- How to detect Claude Code is stuck/crashed?
- Should there be a timeout on Claude Code operations?
- Maximum restart attempts before giving up?

### 7. Configuration

**Proposed Config:**
```yaml
agent_type: worker  # worker|reviewer|orchestrator
rails_url: ws://localhost:3000/cable
api_token: xxx
claude_flags: "--allowedTools all"
log_file: /var/log/worker-terminal.log
```

**Questions:**
- What other config needed?
- Config file format preference (YAML, TOML, JSON, env vars)?
- Per-agent or shared config?

### 8. Deployment

**Questions:**
- One Docker container per agent?
- How to run in development vs production?
- Should terminal app be part of Rails repo or separate?

---

## Deliverable

After research feedback, create implementation ticket with:
- Chosen technology stack
- Architecture decisions
- Implementation steps