agentboy

A retro handheld-console terminal designed specifically for AI pair programming. Inspired by classic handhelds, agentboy bridges the gap between nostalgic aesthetics and modern agentic workflows.

Website: pedjaurosevic.github.io/agentboy

OSC 98 approval dialog	G-Shock Red theme	cmatrix screensaver

Features

• 🎮 Nostalgic UI: A Game Boy style chassis with labelled function buttons, A/B buttons, a status LED and a speaker grille — all rendered entirely with CSS.
• 🎨 Six Curated Themes: DMG Classic, CRT Phosphor, Monochrome E-Ink, Charcoal & Pale Yellow, Standard RGB and G-Shock Red (black + vivid red; its light variant is a watch-style negative display — red screen, light digits). Each has a dark and a light variant, switchable from the chassis buttons.
• 📺 Authentic CRT Effects: Scanlines, vignette, and screen glow to complete the retro experience, with adjustable scanline density.
• 🤖 LLM Native Approval Flow: CLI tools and agents can request user approval through an escape sequence (OSC 98 ; prompt=<question>) — the terminal shows a retro RPG-style dialog, git-checkpoints the pane's working directory on YES, and answers y/n back to the shell.
• 🔍 Diff Inspector Cartridge: View proposed code changes in a dedicated UI panel before accepting them from the AI agent.
• ⏪ Undo Checkpoints: Natively tracks AI code modifications via Git, in the working directory of the active pane's shell. Right-click the F1 theme button to instantly roll back if the AI makes a mistake.
• 🚦 ACTION Status LED & Audio: A traffic-light style LED shows what is happening at a glance — dim yellow when idle, bright yellow while you type, green while the agent produces output, red when the terminal waits for your approval. CLI tools can drive it via OSC 99 ; led=<state>, with 8-bit success and error audio feedback.
• 🪟 Split Panes: Terminator-style splits, each pane running its own real PTY, with draggable dividers, search, and clipboard support (CLIPBOARD + X11 PRIMARY).
• 📐 Window Modes: Snap grid (3×2), full-height column, expand-over-toolbar, a free-floating resizable mode, and a frameless mode that hides the chassis entirely.
• 🟩 cmatrix Screensaver: One button starts cmatrix in an overlay on its own PTY; any key or click exits. (Install cmatrix to use it.)

Requirements

• Linux with X11 (primary target; window snapping relies on X11)
• Node.js 20+
• Build tools for native modules (python3, make, g++) — needed to compile node-pty
• Optional: cmatrix for the built-in screensaver (sudo apt install cmatrix)

Installation

From npm

npm install -g agentboy
agentboy

node-pty is compiled for Electron during install, so the build tools listed above must be present.

From source

# Clone the repository
git clone https://github.com/pedjaurosevic/agentboy.git
cd agentboy

# Install dependencies (node-pty is rebuilt for Electron automatically)
npm install

# Start the terminal
npm start

If npm start fails with a node-pty ABI error, rebuild the native module manually:

npm run rebuild:native

Chassis Controls

Every button has its function printed on the shell above it. These are on-screen buttons on the chassis, not physical F-keys.

• F1 LIGHT/DARK: switch between the dark and light variant of the current theme — the label always shows the mode you would switch to (right-click: undo — git rollback of the last AI checkpoint in the active pane's working directory)
• F2 FRAME: cycle the chassis frame style — default → dark → retro → white (right-click: cycle the inner divider style the same way)
• F3 THM− / F4 THM+: previous / next theme preset (1–6)
• F5 CRT: CRT scanline overlay on / off (right-click: cycle scanline density)
• F6 CRT− / F7 CRT+: scanline density down / up (20 levels)
• F8 EXPAND: with the full-height column active (B), expand over the toolbar / back; in grid mode it reminds you to press B first
• F9 FLOAT: toggle free-floating mode — the window leaves the 3×2 snap grid and becomes freely resizable
• F10 BOTTOM: scroll the active pane to the bottom (same as Ctrl+End)
• F11 NOFRAME: hide the chassis — bare fullscreen terminal (the keyboard F11 key brings the frame back)
• F12 SAVER: start the cmatrix screensaver (any key or click exits)
• ACTION LED: status traffic light — dim yellow idle, bright yellow typing, green agent output, red waiting on you (approval dialog, or the agent printed a numbered option menu / y/n question and went quiet)
• B MAX / A MIN: full-height column mode / snap back to the 3×2 grid
• Speaker grille: mute / unmute 8-bit sound effects

Keyboard Shortcuts

Run ./terminal-help.sh inside the terminal for the full control reference.

Configuration

Settings are read from ~/.agentboy.json (an existing ~/.retro-terminal.json is migrated automatically):

{
  "shell": "/bin/bash",
  "theme": 1,
  "light": false,
  "border": "dark",
  "fontSize": 14
}

Built With

• Electron
• xterm.js
• node-pty
• esbuild

License

This project is licensed under the MIT License - see the LICENSE file for details.