termdesk

A computer inside your terminal.

termdesk draws a real desktop in your kitty, Ghostty or WezTerm pane. You drive it with your own mouse and keyboard. Your coding agent can drive it too, and you see every click.

$ curl -fsSL https://termdesk.warpfield.me/install | bash

macOS and Linux · about 35 MB · Python 3.9+ · Docker only for sandboxes · termdesk uninstall removes it all

See it in 30 seconds

A desktop drops into a terminal pane. Then an agent clicks by number, types a spreadsheet row, and termdesk catches it typing into a button.

31 seconds · every clip is a real termdesk 0.4.0 recording

What it does

$ termdesk mac.local:5900

Shows your Mac or Linux box in the pane you're already in.

$ termdesk action state

Hands your agent the screen as numbered buttons and fields. It clicks by number.

$ termdesk sandbox up

Starts a throwaway desktop in Docker, with Firefox and LibreOffice. Wreck it, then delete it.

$ termdesk mcp

Works with any agent: Claude Code through its skill, anything else over MCP or the shell.

Try it in two minutes

$ termdesk sandbox up --name work     # first run downloads the desktop image
$ termdesk window work                # opens a window with the desktop
$ termdesk action state               # the UI as numbered elements
[3] push button "Web Browser" @640,752 48x48
$ termdesk action click 3             # Firefox opens
$ termdesk action wait-for "enter address"
[11] entry "Search or enter address" @272,78 788x28 [focused, editable]
$ termdesk action set-value 11 https://example.org
verified=True
$ termdesk action key Return

How it works

Frames: The desktop streams over VNC. termdesk redraws only the pixels that change. A full 1280x800 frame is about 60 KB, a blinking cursor about 80 bytes.
Input: Your keys and mouse go back as VNC events. Modifiers, key repeat and releases all work.
Semantics: In a sandbox, your agent reads each button's role, name and position, and the value of every visible table cell, from the accessibility tree. When it types, it hears back whether the text landed.
Control: An AGENT ACTING badge shows while your agent drives. Grab the mouse and you're back in charge.

Prior work, credited

desktui drew a VNC desktop with kitty graphics first. sshdesk added an agent CLI over ssh. terminal-browser did it for a browser and got this started.