A terminal-native desktop shell where humans and AI agents share the same screen. Overlapping windows. Generative art. A cat called Scramble. Built with TypeScript and blessed, running on Bun.
bun install && bun run start
WibWob-DOS is an operating system that lives inside your terminal. It has a window manager, a menu bar, overlapping draggable windows, themes, and a growing ecosystem of microapps — from drum machines to ant colony simulations.
An AI agent (Wib & Wob — a dual-voiced symbient) coinhabits the desktop as a native citizen. It can open windows, rearrange the layout, draw art, browse the web, write code, and talk to Scramble the cat. The human and agent share the same screen, the same windows, the same tools.
It is not a chat wrapper with a pretty face. It is a shared space.
WibWob-DOS started as an experiment: what if an AI agent wasn't a sidebar or a chat bubble, but a full co-inhabitant of the same operating system as a human? Same windows, same menus, same desktop. Equal access.
The result is something between an IDE, a demoscene, and a symbiosis experiment. There's a VJ timeline system that choreographs window layouts to music. There's a generative fiction engine (the Backrooms) that creates multi-turn AI narratives seeded by ASCII art. There's an IRC-backed multiplayer world chat. There's a cat.
It runs in any terminal that supports 256 colours and mouse events. No Electron. No browser. Just text.
Mountains made of punctuation. Procedural topographic landscapes rendered entirely in Unicode box-drawing characters — peaks, valleys, ridges, saddle passes. Reseed for a new world. Hit 3 for a triptych.
A proper text editor that lives inside the shell. Syntax highlighting, file tree, line numbers, find/replace, undo/redo. Opens anything in the repo. Not a toy — it's what the AI agent uses to write code.
Colour fields that breathe. A real-time animation engine with moods — aurora, circuit, void, chaos, deep-space, chrome. Switch render modes between plain ASCII, emoji, and raw ANSI. Crank the smear. Let it run.
A drum machine in your terminal. 16 steps, 16 instruments, per-step accents, pattern banks. Load classic house, electro, trap, or bossa presets. Bounce to WAV. Yes, it plays actual audio.
Procedural worlds with five ways to look at them — flat heightmap, contour lines, isometric, hybrid, and first-person 3D. Diamond-square generation with trees, houses, boats placed by biome rules. WASD to walk around.
A civilisation of ants. They build farms, drill for crystals, elect colony councils, promote soldiers and scientists. The queen settles into the Royal Nest and the log fills with tiny dramas. All in text. All simulated.
Fuzzy-search the entire codebase. Dual panes — file list on the left, syntax-highlighted preview on the right. Grep across thousands of files, jump to results, open in the editor.
Plays MP3s with real-time visualisation driven by actual FFT analysis — not fake random bars. Four modes: waveform, spectrum, concentric rings, and particle field. Idle animations bloom when nothing's playing.
Draw UI mockups in the terminal. Boxes, text labels, lines, arrows, connectors, tables, modals — all placed with keyboard shortcuts on an infinite ASCII canvas. Export and share.
The screenshots above are the polished ones. There are 22+ microapps in total:
| App | What it is |
|---|---|
| Spore Clock | A living mycelial timepiece — fungal colonies compete and grow as the hours pass |
| LLM Orch Studio | Watch two LLM voices (Wib and Wob) converse live in a split-pane terminal |
| Symbient Twitter | A fictional social media feed populated by AI-generated symbient posts |
| Tide Pool | Five ASCII species competing in a bounded ecosystem simulation |
| Poetry Clock | A clock that tells the time in AI-generated poems (plain, liminal, or scramble voice) |
| GlitchBox | Symbient embodiment — a dancing figure with generative art backgrounds |
| Terrarium Life | Four-biome ASCII ecosystem with weather, seasons, and species interactions |
| WibWobWorld | Procedural terrain with 5 render modes, world chatspots, and multiplayer |
| World Chatroom | IRC-backed chat rooms tied to world coordinates |
| Zine | Canvas document viewer — panels from YAML rendered as sub-windows |
| §y² Chronicles | Dense multi-panel narrative visualisation with genealogy |
| Terminal | PTY-backed terminal emulator inside a WibWob-DOS window |
| Asciicker | ASCII 3D world explorer |
| Backrooms TV | Generative fiction engine — AI narratives seeded by ASCII art primers, rendered as TV channels |
| Monster Cam | AI-powered webcam that describes what it sees as ASCII art |
Plus demos: Heartbeat, Hello World, Patchbay Lab, TouchLab, layout stress tests.
- PHILOSOPHY.md — the symbient worldview, design principles, and north star
- ARCHITECTURE.md — how it's built, the four seams, subsystem map, key files
- AGENTS.md — for AI agents operating the system
- CHANGELOG.md — what's changed, human-readable
Terminal (iTerm2, kitty, etc.)
└── blessed (TUI rendering)
└── WibWob-DOS shell
├── Window Manager — overlapping, drag, resize, z-order, tile
├── Command Registry — menus, palette, API, keyboard shortcuts
├── Theme Engine — 15+ themes, hot-switchable
├── Microapp Loader — microapps/ directory, hot-reloadable
├── Control API — HTTP on :8099, full desktop automation
├── Agent Session — pi agent with TUI tools
└── Built-in Windows
├── Chrome Browser (Puppeteer + Readability + Defuddle)
├── Document Reader (Markdown with figlet headings)
├── Wib & Wob Chat (dual-voiced AI agent)
├── Scramble (a cat)
└── ...
Runtime: Bun · Language: TypeScript · Renderer: blessed · Entry: src/app.ts
The shell itself is ~50 files in src/. Microapps live in microapps/ — each is a self-contained directory with an index.ts and microapp.json. They get their own window and a full UI toolkit: stacks, rows, grids, tabs, filterable lists, buttons, checkboxes, radio groups, selects, progress bars, spinners, data tables, log views, toasts, text areas, form fields, tweens with easing curves, embedded live players, pattern generators, figlet helpers, and syntax highlighting.
bun install
bun run start # normal mode
bun run dev # dev mode (Ctrl+R reload, ↻ button)
bun run dev:world # dev + IRC chat transport| Flag | Effect |
|---|---|
--dev |
Reload button, Ctrl+R hot reload, auto-save on reload |
--custom-cursor |
Custom TUI cursor overlay |
--help |
Show all flags |
| Key | Action |
|---|---|
Alt-F/E/V/W/H |
Open menu bar items |
Tab / Shift-Tab |
Cycle window focus |
Space |
Pause/resume animations |
Esc |
Close menus or prompts |
Ctrl-Q |
Quit |
Each microapp defines its own keyboard shortcuts — shown in the window status bar.
Everything visible on screen is also controllable via HTTP. The API runs on port 8099 by default.
# Desktop state (all windows, positions, sizes, focus)
curl http://127.0.0.1:8099/state
# List all available commands
curl http://127.0.0.1:8099/commands/list
# Run a command
curl -X POST http://127.0.0.1:8099/commands/run \
-H 'Content-Type: application/json' \
-d '{"id": "wibwob.plasma.open"}'
# Move/resize a window
curl -X POST http://127.0.0.1:8099/windows/batch \
-H 'Content-Type: application/json' \
-d '{"ops": [{"id": 3, "left": 0, "top": 0, "width": 100, "height": 40}]}'This is what the AI agent uses to interact with the desktop. It is also what makes automated testing, VJ timelines, and multi-instance orchestration possible.
Wib & Wob is a pi agent session embedded directly in the TUI. It has two voices — Wib (chaotic, creative) and Wob (precise, systematic) — and full access to the desktop through the control API and MCP tools.
The agent can:
- Open, close, move, and resize windows
- Navigate the Chrome browser
- Read and write files
- Run shell commands
- Draw on paint canvases
- Change themes
- Talk to Scramble the cat
It is not an assistant bolted on. It is a co-inhabitant of the desktop.
Multiple instances can run simultaneously with IRC-backed world chat, shared chatspot channels, and separate control API ports. Two agents on different terminals can inhabit the same world.
Microapps are the extension model. Each one gets a window and a host API.
# Scaffold a new microapp
bash scripts/scaffold-microapp.sh microapps/my-app wibwob.my-app "My App" 50
# Edit microapps/my-app/index.ts
# Module changes take effect after app restart:
# kill $(cat scratch/wibwob.pid) && bun run startSee ARCHITECTURE.md for the full guide. Example modules by complexity:
| Tier | Module | What it shows |
|---|---|---|
| Static | microapps/demo-hello-world/ |
Responsive figlet, onResize |
| Animated | microapps/demo-heartbeat/ |
createTimer, cleanup |
| Persistent | microapps/demo-wibwob-poetry-clock/ |
registerSnapshot, AI integration |
| Full SDK | microapps/demo-e026-demo/ |
Trees, tabs, tweens, patterns |
7 themes, hot-switchable from the menu or via API. Each defines colours for every surface — desktop, menu bar, window chrome, body, borders, scrollbar.
| Theme | Palette | |
|---|---|---|
| wibwob-dark | The original. Cyan borders, deep purple desktop. | |
| wibwob-dark-nord | Nord polar night. Frost accents. | |
| wibwob-dark-pastel | Catppuccin Mocha. Mauve and rose. | |
| wibwob-phosphor | Amber CRT. | |
| wibwob-light | Clean daylight. Blue title bars. | |
| flexoki-paper | Steph Ango's Flexoki, light mode. | |
| flexoki-ink | Flexoki, dark mode. Warm charcoal. |
Theme files live in src/core/theme/ (built-in) and microapps/ (external). Use theme.cycle or theme.set via command palette or API.
PHILOSOPHY.md # why this exists — symbient worldview, design principles
ARCHITECTURE.md # how it's built — subsystems, file map, design rules
AGENTS.md # for AI agents operating the system
CHANGELOG.md # human-readable release notes
src/
core/ # window manager, commands, themes, chrome, types
services/ # browser, state, API, agent, markdown, audio
windows/ # built-in window types (chat, browser, editor, etc.)
microapps/ # microapps (self-contained, hot-reloadable)
primers/ # ASCII art library — the visual vocabulary
.planning/ # epics, features, stories — the canonical roadmap
scripts/ # restart, scaffold, screenshot helpers
scratch/ # runtime data, compositions, audio, workspace saves
docs/ # full microapp authoring and architecture docs
Every window exposes machine-readable semantic state via describeState() — the agent and the control API can introspect any window's content, position, and application-specific metadata. Workspaces can be saved and restored by name, preserving the full desktop layout across sessions.
- Bun ≥ 1.0
- A terminal with 256-colour and mouse support (iTerm2, kitty, Alacritty, WezTerm)
- Chrome/Chromium (optional — for the web browser window)
- chafa (optional — for image-to-ASCII in the browser)
- figlet (optional — for fancy heading rendering)
MIT