A text-mode web browser for humans and agents
Web pages, as text you and your agent can click.
medley turns web pages into compact text with every link, button and field numbered, and each action prints only what changed. Your agent browses through MCP or the command line while you watch the same browser session in a terminal UI, talk to it, and take over when it needs you.
The demo shop is an ordinary web page, made for pointing medley at. medley itself runs in your terminal, from its folder (see install): bun src/medley.ts tui nam37.github.io/medley/demo/
main › two drivers, one session
Watch your agent browse, and take over when it matters.
A background session owns the browser. The terminal UI, the command line and every MCP connection are clients of that one session, so you see what the agent does as it happens, with its cursor on what it's working on. Press > to tell it something. When it needs you, for a sign-in, a choice, or a yes before it buys anything, it asks and waits for your answer, and a confirm() on the page waits for you too.
The agent fills the form
agent type 12 sam@example.com. Your terminal UI follows along and marks the line that changed.
The page asks to confirm
agent click 14 opens a confirm(). The page is blocked until someone answers it.
You answer it
you press y in the terminal UI (or run dialog accept), and the page carries on.
$ claude mcp add medley -- bun /path/to/medley/src/medley.ts mcp
The MCP tools (browser_goto, browser_click, browser_type, …) talk to the same session as the command line and the terminal UI.
main › what an agent sees
The page, minus everything that isn't content.
Headings, landmarks, lists, tables and alt text stay; layout and styling go. Every control gets a number that stays the same for as long as the page lives, so an agent can say click 4 instead of guessing at selectors or pixels.
$ medley goto nam37.github.io/medley/demo/ Fernway Outfitters https://nam37.github.io/medley/demo/ · 19 refs · viewport 0–900 of 1671px ── header ── [1]Fernway ── nav "Main" ── [2]Gear [3]Trails [4 button "Menu" collapsed] ── main ── # Pack light. Go far. Gear for weekend trips, tested on real trails and built to be repaired. [5]Shop the gear ## New this season [6][img "A green two-person tent"] ### Ridge 2 tent Two people, 1.4 kg, up in three minutes. $289 [7][img "A glowing camp lantern"] ### Ember lantern Warm light for 40 hours on one charge. $49 [8][img "A rust-red daypack"] ### Trailhead 28 pack A daypack with room for a jacket and lunch. $119 ## Trail guide Table: Weekend loops near Fernway | Trail | Distance | Climb | Best in | |-------------------|----------|-------|---------| | [9]Cedar Falls | 8 km | 310 m | Spring | | [10]Lookout Ridge | 14 km | 720 m | Autumn | | [11]Mirror Lake | 11 km | 240 m | Summer | ── aside "Trail tip" ── ### Tip Start Lookout Ridge before nine to beat the afternoon wind. ## Trail notes ── form "Trail notes" ── [12 textbox "Email"] [13 checkbox "Monthly, not weekly" checked] [14 button "Subscribe"] ── footer ── #### Shop - [15]Gear - [16]Repairs #### Help - [17]Shipping - [18]Returns Fernway Outfitters is a made-up shop: a page for trying [19]medley, the text-mode web browser.
The demo page is 8.1 KB of HTML; medley's text for it is 1.4 KB.
main › act by number
Each action answers with only what changed.
Click, type, select, press a key, hover or scroll, naming the element by its number. medley waits for the page to settle, then prints a diff grouped under the landmark and heading it happened in, or the whole new page when you navigated. An agent reads two lines instead of the whole page again.
$ medley click 4 clicked [4 button "Menu"] · +2 -1 lines @@ nav "Main" @@ ── nav "Main" ── - [2]Gear [3]Trails [4 button "Menu" collapsed] + [2]Gear [3]Trails [4 button "Menu" expanded] + [20]Account [21]Orders
main › the terminal UI
Browse it yourself, with the page's own layout.
A full-screen terminal UI for people: Tab through refs, Enter to open, / to find, [ ] for tabs. Press v to cycle how the page is drawn. The text, the refs and the keys stay the same in every mode.
No grid: the text exactly as an agent gets it, with refs in color and links underlined.
main › under the hood
Built on the real browser.
medley drives headless Chrome or Edge over the DevTools protocol. Its only dependency is OpenTUI, for the terminal UI. It reads what a page renders, so most pages work; canvas and WebGL apps don't become text (a screenshot shows them), and some sites turn headless browsers away. The README lists what doesn't work yet.
01Refs that stay put
An element keeps its number for as long as the document lives, so diffs show only real changes. Refs from before a navigation, or into a frame that has since loaded another page, are refused instead of hitting whatever has that number now.
02Real clicks and typing
Clicks are mouse events at a point hit-testing confirms lands on the element, through any frames around it. If something covers it, the error names what. Typing produces ordinary input events.
03An isolated world
medley's scripts share the page's DOM but not its JavaScript, like an extension's. A page can't see or forge the ref table to steer an agent.
04What's actually rendered
Extraction walks the rendered page, including open shadow roots and iframes, even ones from other sites, like a sign-in or payment form, whose controls work like any other. Hidden content is dropped, labels fold into their controls, and passwords are masked.
05Waits for the page
After each action it waits for any navigation, then for the network and the DOM to go quiet, before it looks.
06Tabs and dialogs
A link that opens a tab moves the session into it; when a tab closes, the session goes back to the one that opened it. Alerts are acknowledged; confirms and prompts wait for an answer.
main › install
Run it from a clone.
- Bun 1.3 or later
- Chrome or Edge (medley finds it, or set
MEDLEY_BROWSERto its path)
$ git clone https://github.com/nam37/medley.git $ cd medley $ bun install $ bun src/medley.ts tui nam37.github.io/medley/demo/
Then bun src/medley.ts goto <url>, snapshot, click <ref> and friends from any shell, or bun src/medley.ts mcp for agents. The examples above write medley for bun src/medley.ts; the README shows how to make a medley command, and lists every command, key and option, and what doesn't work yet.