<!--
hoody-terminal Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-19T22:49:06.267Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: cli


Tokens: 9156

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-terminal Subskill

## Overview

### What This Service Does

hoody-terminal provides HTTP-accessible terminal sessions with multiplayer capabilities. It turns container terminals into REST API endpoints — create sessions, execute commands, capture output, and automate terminal interactions all via `hoody` CLI commands.

Terminal sessions are **multiplayer by default**. Multiple clients can connect to the same session via WebSocket, sharing the same PTY. Commands can execute synchronously or asynchronously, with results retrievable by command ID.

**Core capabilities:**
- Persistent terminal sessions with full PTY emulation
- Synchronous and asynchronous command execution
- Terminal automation: screenshots, snapshots, key presses, mouse events, paste
- Screen search with PCRE2 regex
- Wait conditions: stable screen, regex match, or timeout
- System monitoring: processes, ports, resources, displays
- Process control: signal, freeze, unfreeze

### When to Use

- **Run commands in containers** — any shell command, scripts, or tools
- **Automate interactive programs** — send keys, paste text, read screen state
- **Monitor containers** — check processes, ports, resource usage
- **Manage terminal lifecycle** — create, list, destroy sessions
- **Capture output** — raw buffers, screenshots, command history
- **Execute long-running tasks** — async execution with result polling

### How It Fits Into Hoody Philosophy

Terminal sessions are HTTP endpoints. The `hoody run` shorthand (`hoody terminal exec --ephemeral`) makes ad-hoc execution trivial. All operations require a container target via `-c <container-id>` or `HOODY_CONTAINER` env var. Sessions persist until explicitly destroyed, enabling multiplayer collaboration.

---

## Common Workflows

### Workflow 1: Execute a Command and Get Results

The most common pattern — run a command and read its output.

```
# Step 1: Execute command (returns command_id)
hoody terminal exec -c my-container --command "uname -a"
```

```
{
  "command_id": "cmd-abc123",
  "terminal_id": "term-xyz789",
  "status": "started"
}
```

```
# Step 2: Poll for result
hoody terminal command-result cmd-abc123 -c my-container
```

```
{
  "command_id": "cmd-abc123",
  "status": "completed",
  "exit_code": 0,
  "stdout": "Linux container-abc 5.15.0 #1 SMP x86_64 GNU/Linux\n",
  "stderr": ""
}
```

### Workflow 2: Create Persistent Session and Write Input

For interactive use — create a session, then send input directly.

```
# Step 1: Create a named terminal session
hoody terminal create -c my-container
```

```
{
  "terminal_id": "term-interactive-01",
  "status": "created"
}
```

```
# Step 2: Write input (auto-appends newline by default)
hoody terminal write -c my-container --terminal-id term-interactive-01 --input "ls -la /tmp"
```

```
# Step 3: Get raw output buffer
hoody terminal raw-output -c my-container --terminal-id term-interactive-01
```

```
{
  "terminal_id": "term-interactive-01",
  "content": "ls -la /tmp\ntotal 12\ndrwxrwxrwt 2 root root 4096 Nov  5 10:00 .\ndrwxr-xr-x 1 root root 4096 Nov  5 09:00 ..\n"
}
```

### Workflow 3: Ephemeral Execution with `hoody run`

Quick one-shot commands without managing sessions.

```
# Shorthand: creates ephemeral session, executes, returns output
hoody run -c my-container --command "df -h"
```

```
{
  "command_id": "cmd-ephem-001",
  "status": "completed",
  "exit_code": 0,
  "stdout": "Filesystem      Size  Used Avail Use% Mounted on\noverlay          50G   12G   38G  24% /\n",
  "stderr": ""
}
```

### Workflow 4: Terminal Automation — Snapshot, Find, Press

Interact with terminal UIs programmatically.

```
# Step 1: Get a rendered snapshot of the screen
hoody terminal snapshot -c my-container --terminal-id term-xyz789
```

```
{
  "lines": ["$ echo hello", "hello", "$ _"],
  "cursor": { "row": 2, "col": 2 },
  "title": "bash",
  "fullscreen": false
}
```

```
# Step 2: Search screen for a pattern
hoody terminal find -c my-container --terminal-id term-xyz789 --pattern "hello"
```

```
{
  "hits": [
    { "row": 1, "col": 0, "text": "hello", "match_start": 0, "match_end": 5 }
  ]
}
```

```
# Step 3: Send key presses (e.g., Enter)
hoody terminal press -c my-container --terminal-id term-xyz789 --keys "Enter"
```

```
{
  "status": "ok",
  "keys_sent": 1
}
```

### Workflow 5: Wait for Screen Condition

Block until the terminal shows expected output.

```
# Wait for a regex pattern to appear on screen
hoody terminal wait -c my-container --terminal-id term-xyz789 --mode regex --pattern "Build complete"
```

```
{
  "mode": "regex",
  "matched": true,
  "snapshot": {
    "lines": ["$ make build", "Building...", "Build complete."],
    "cursor": { "row": 2, "col": 14 }
  }
}
```

```
# Wait for screen to stabilize (no changes for debounce period)
hoody terminal wait -c my-container --terminal-id term-xyz789 --mode stable --debounce 500
```

### Workflow 6: Paste Multi-line Text

Paste text with bracketed paste mode for safe multi-line input.

```
hoody terminal paste -c my-container --terminal-id term-xyz789 --text 'for i in 1 2 3; do
echo $i
done' --bracketed
```

```
{
  "status": "ok",
  "bytes_written": 42
}
```

### Workflow 7: Capture Screenshot

Convert terminal output to an image file.

```
hoody terminal screenshot -c my-container --terminal-id term-xyz789
```

```
{
  "terminal_id": "term-xyz789",
  "path": "/hoody/storage/hoody-terminal/screenshots/term-xyz789/2025-11-05T10-30-00.png",
  "format": "png"
}
```

### Workflow 8: List and Manage Sessions

```
# List all active sessions
hoody terminal list -c my-container
```

```
[
  {
    "terminal_id": "term-xyz789",
    "created_at": "2025-11-05T09:00:00Z",
    "command_count": 5,
    "last_activity": "2025-11-05T10:15:00Z"
  }
]
```

```
# Get command history for a session
hoody terminal history term-xyz789 -c my-container
```

```
# Destroy a session (requires confirmation)
hoody terminal delete term-xyz789 -c my-container --yes
```

### Workflow 9: Abort a Running Command

```
# Graceful abort (SIGINT — like Ctrl+C)
hoody terminal abort cmd-long-task-001 -c my-container
```

```
{
  "command_id": "cmd-long-task-001",
  "status": "aborted",
  "signal": "SIGINT"
}
```

---

## Advanced Operations

### Workflow 10: System Process Management

Monitor and control processes inside the container.

```
# List all processes with filtering
hoody terminal list -c my-container --sort cpu --limit 10 -o json
```

```
[
  { "pid": 142, "name": "node", "cpu_percent": 12.5, "mem_percent": 3.2, "state": "running" },
  { "pid": 87, "name": "nginx", "cpu_percent": 0.1, "mem_percent": 1.0, "state": "sleeping" }
]
```

```
# Get detailed info for a specific process
hoody terminal get 142 -c my-container -o json
```

```
# Freeze a process (SIGSTOP)
hoody terminal signal -c my-container --pid 142 --signal SIGSTOP

# Unfreeze a process (SIGCONT)
hoody terminal signal -c my-container --pid 142 --signal SIGCONT

# Kill a process by name (all matching)
hoody terminal signal -c my-container --name "zombie-worker" --signal SIGKILL
```

### Workflow 11: System Resource Monitoring

```
# Get comprehensive system resources
hoody terminal resources -c my-container -o json
```

```
{
  "cpu": { "usage_percent": 24.5, "cores": 4 },
  "memory": { "total_mb": 8192, "used_mb": 3072, "available_mb": 5120 },
  "disk": { "total_gb": 50, "used_gb": 12, "available_gb": 38 },
  "uptime_seconds": 86400
}
```

```
# List listening network ports
hoody terminal ports -c my-container -o json

# Get display information
hoody terminal display-info -c my-container -o json

# Get daemon configuration
hoody terminal daemon-config -c my-container -o json
```

### Workflow 13: Check Automation Metrics and State

```
# Global automation metrics
hoody terminal metrics -c my-container -o json
```

```
{
  "active_vterm_sessions": 3,
  "memory_used_mb": 45,
  "memory_cap_mb": 512,
  "active_waiters": 1,
  "max_sessions": 100
}
```

```
# Per-session automation state
hoody terminal automation-state term-xyz789 -c my-container -o json
```

```
# List supported key names for press endpoint
hoody terminal keys -c my-container -o json
```

### Error Recovery Patterns

**Pattern: Command timeout — retry with wait**

```
# If a command seems stuck, check its result first
hoody terminal command-result cmd-stuck-001 -c my-container

# If still running after reasonable time, abort gracefully
hoody terminal abort cmd-stuck-001 -c my-container

# Retry with a fresh command
hoody terminal exec -c my-container --command "timeout 30 long-running-task"
```

**Pattern: Session unresponsive — destroy and recreate**

```
# Delete the stuck session
hoody terminal delete term-stuck -c my-container --yes

# Create a fresh session
hoody terminal create -c my-container
```

**Pattern: Verify service health before operations**

```
# Always check health first
hoody terminal health -c my-container
```

```
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 3600
}
```

### Performance Considerations

- **Session reuse**: Create persistent sessions for multiple commands instead of ephemeral ones to avoid PTY startup overhead.
- **Async execution**: Use `hoody terminal exec` for long-running commands; poll `command-result` instead of blocking.
- **Wait with debounce**: Use `--mode stable` with appropriate debounce (200-500ms) to avoid false positives from streaming output.
- **Scrollback size**: Snapshots include visible screen only. For full history, use `raw-output`.
- **Automation metrics**: Monitor `active_vterm_sessions` and `memory_used_mb` to prevent resource exhaustion.

---

## Quick Reference

### Essential Commands

| Task | Command |
|------|---------|
| Health check | `hoody terminal health -c <id>` |
| Run one command | `hoody run -c <id> --command "cmd"` |
| Create session | `hoody terminal create -c <id>` |
| List sessions | `hoody terminal list -c <id>` |
| Execute in session | `hoody terminal exec -c <id> --command "cmd"` |
| Get command result | `hoody terminal command-result <cmd-id> -c <id>` |
| Get history | `hoody terminal history <term-id> -c <id>` |
| Write input | `hoody terminal write -c <id> --terminal-id <term-id> --input "text"` |
| Snapshot screen | `hoody terminal snapshot -c <id> --terminal-id <term-id>` |
| Search screen | `hoody terminal find -c <id> --terminal-id <term-id> --pattern "regex"` |
| Wait for condition | `hoody terminal wait -c <id> --terminal-id <term-id> --mode regex --pattern "done"` |
| Send keys | `hoody terminal press -c <id> --terminal-id <term-id> --keys "Enter"` |
| Paste text | `hoody terminal paste -c <id> --terminal-id <term-id> --text "content"` |
| Screenshot | `hoody terminal screenshot -c <id> --terminal-id <term-id>` |
| Abort command | `hoody terminal abort <cmd-id> -c <id>` |
| Delete session | `hoody terminal delete <term-id> -c <id> --yes` |
| System resources | `hoody terminal resources -c <id>` |
| List processes | `hoody terminal list -c <id>` |
| List ports | `hoody terminal ports -c <id>` |

### Essential Parameters

| Parameter | Description |
|-----------|-------------|
| `-c <container-id>` | **Required** — target container |
| `--terminal-id <id>` | Target terminal session |
| `--command "cmd"` | Command string to execute |
| `-o json` | Machine-readable JSON output |
| `--yes` | Skip confirmation prompts |
| `--mode <type>` | Wait mode: `stable`, `regex` |
| `--pattern <regex>` | PCRE2 pattern for find/wait |
| `--keys <name>` | Key names for press endpoint |
| `--text <content>` | Text for paste/write |
| `--signal <name>` | Unix signal name (SIGTERM, SIGKILL, etc.) |

### Typical Response Formats

**Command execution:**
```
{
  "command_id": "string",
  "status": "started|completed|failed|aborted",
  "exit_code": 0,
  "stdout": "string",
  "stderr": "string"
}
```

**Terminal snapshot:**
```
{
  "lines": ["string"],
  "cursor": { "row": 0, "col": 0 },
  "title": "string",
  "fullscreen": false
}
```

**Session list item:**
```
{
  "terminal_id": "string",
  "created_at": "2025-01-01T00:00:00Z",
  "command_count": 0,
  "last_activity": "2025-01-01T00:00:00Z"
}
```