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.
• 🎨 Eight Curated Themes: Agentboy DMG, Monochrome E-Ink, Charcoal & Pale Yellow, G-Shock Red (black + vivid red; its light variant is a watch-style negative display — red screen, light digits), Dystopian Terminal (with a hairline crack in the glass) (amber phosphor), Phosphor Monitor (green phosphor), Cyberpunk Neon (magenta + cyan) and Sapphire Ocean (deep teal). Each has a dark and a light variant, switchable from the chassis buttons.
• 📺 Authentic CRT Effects: Six tube modes — shadow mask, aperture grille, slot mask, curved glass (with a bulge that inflates with intensity), the full tube, and off — plus phosphor bloom and 20 intensity steps.
• 🤖 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/WORN/DARK/CLEAN: appearance cycle — dark → light → light+worn → dark+worn; worn is a scuff-scratches-and-sticker-ghost filter that layers over ANY chassis color, and the label always shows what the next press does (right-click: undo — git rollback of the last AI checkpoint in the active pane's working directory)
• F2 FRAME: cycle the chassis frame color — default → dark → retro → white → red → phosphor → cyberpunk → ocean (right-click: cycle the inner divider style the same way)
• F3 THM− / F4 THM+: previous / next theme preset (1–8)
• F5 CRT: cycle the CRT effect — Shadow Mask (scanlines + RGB triads + flicker) → Aperture Grille (vertical stripes + Trinitron damper wires) → Slot Mask (brick-slot pattern) → Glass (curved pane: sheen + a bulge that grows with intensity; on light themes it reads as darker sky reflections) → Full (the shadow mask under the glass) → Off (right-click: cycle intensity)
• F6 CRT− / F7 CRT+: CRT intensity down / up (20 levels — intensity only, the line rhythm is fixed so scanlines never spread apart)
• F8 NOFRAME: hide the chassis — bare terminal (the keyboard F11 key or the right-click menu brings the frame back and restores the window position/size from before)
• F9 EXPAND/MINIMIZE: with the full-height column active (B), expand over the toolbar / back — the label flips to MINIMIZE while the toolbar is covered; in grid mode it reminds you to press B first
• F10 SAVER: start the cmatrix screensaver (any key or click exits)
• F11 FLOAT: toggle free-floating mode — the window leaves the 3×2 snap grid and becomes freely resizable
• F12 BOTTOM: scroll the active pane to the bottom (same as Ctrl+End)
• 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
• Speakers (two round grilles right of A): the one next to A plays / pauses the built-in tune (Phosphor Drift, a cozy lofi loop played off an imaginary cassette — the tape goes in, PLAY clicks, brushed jazz drums and a tape-hiss bed carry it, and the deck clunks to STOP at the end; starts quiet at 20% volume, and the speaker glows while playing); the right one mutes / unmutes the sound effects. All effect sounds are derived from the tune itself — D-major pentatonic, soft triangle waves, including a whisper-quiet typing tick

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+E / Ctrl+Shift+O	Split pane vertically / horizontally
Ctrl+Shift+C / Ctrl+Shift+V	Copy / paste — selecting text already copies it (clipboard + X11 selection; middle-click pastes the selection)
Ctrl+Shift+F	Search in the active pane (Esc closes)
Ctrl+Shift+A / Ctrl+Shift+X	Select all / clear the active pane
Ctrl+D (empty prompt) or exit	End the shell and close the active pane
Ctrl + + / - / 0	Font zoom in / out / reset (also Ctrl + mouse wheel)
Ctrl+End	Scroll to the bottom
F7 (keyboard key)	Toggle full-height mode
F10 / F12 (keyboard keys)	Scroll the active pane to the bottom
F11 (keyboard key)	Toggle the chassis frame (same as the NOFRAME button)

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.