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.
Informations de source
- Dépôt
- recca0120/code-quest
- Dernière activité de la source
- 28 mars 2026 à 13:24
- Langue détectée de SKILL.md
- anglais
- Étoiles
- 11
- Forks
- 2
Options d'installation
Le prompt qui vérifie d'abord la source est sélectionné par défaut. Vous pouvez passer à une commande directe ou télécharger une copie locale.
Vérifiez les fichiers source
Lisez SKILL.md et les fichiers associés affichés par SkillsMP avant de décider de l'installer.
Affichage de SKILL.md
SKILL.md
Instructions source · Aperçu en lecture seule- 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
Voir sur GitHub