pty-architecture
PTY-based multi-session architecture for Code Quest. Covers three-layer design, node-pty spawn config, and worktree isolation. Use when implementing or modifying session management, PTY spawning, or terminal integration.
Datos de origen
- Repositorio
- recca0120/code-quest
- Última actividad en el origen
- 28 de marzo de 2026 a las 13:24
- Idioma detectado de SKILL.md
- inglés
- Estrellas
- 11
- Forks
- 2
Opciones de instalación
De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.
Revisa los archivos de origen
Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.
Mostrando SKILL.md
SKILL.md
Instrucciones de origen · Vista previa de solo lectura- name
- pty-architecture
- description
- PTY-based multi-session architecture for Code Quest. Covers three-layer design, node-pty spawn config, and worktree isolation. Use when implementing or modifying session management, PTY spawning, or terminal integration.
# PTY Architecture
## Three-Layer Design
```
React UI (xterm.js) ←→ Socket.IO ←→ Battle Server (node-pty) ←→ Claude CLI
```
- **UI Layer**: xterm.js renders terminal output, Socket.IO for real-time events
- **Server Layer**: BattleBridge manages PTY sessions, OutputParser converts stream-json to events
- **CLI Layer**: Each session = independent PTY process running Claude CLI
## Key Design Decisions
### Why node-pty over child_process.spawn?
| Feature | node-pty | child_process |
|---------|----------|---------------|
| ANSI colors | Full support | Claude disables colors |
| Terminal resize | `pty.resize()` | Not supported |
| Session isolation | Simple per-process | Complex |
### PTY Spawn Config
```typescript
spawn(command, args, {
name: 'xterm-256color',
cols: 120, rows: 30,
cwd: workingDir,
env: { ...process.env, TERM: 'xterm-256color', FORCE_COLOR: '1', COLORTERM: 'truecolor' }
});
```
### Circular Buffer (10KB)
Output buffer capped at 10KB, sliced to last 5KB on overflow. Prevents memory leaks in long sessions while keeping recent output for late-joining viewers.
### Graceful Shutdown
SIGTERM → wait 5s → SIGKILL. Allows CLI to save state before forced termination.
### Worktree Isolation
Worktree battles use isolated `cwd` paths (e.g., `/worktrees/feature-branch`), preventing concurrent sessions from conflicting on the same working directory.
## Troubleshooting
- **`posix_spawnp failed`**: `chmod +x node_modules/node-pty/build/Release/spawn-helper`
- **No ANSI colors**: Ensure `TERM=xterm-256color` and `FORCE_COLOR=1` in env
- **Zombie process**: Use SIGTERM→SIGKILL pattern with 5s timeout
Ver en GitHub