Documentação

Browser

The in-desktop browser and its pixel view.

Nesta página

Overview

TDE Browser is a real browser in a terminal window. It drives a headless Chromium over the Chrome DevTools Protocol and paints the result into the desktop's cell grid — so the page you see is the page Chromium rendered, with its own JavaScript, cookies and logins, not a text-mode approximation.

That is what makes it useful for the things a text browser cannot do: an OAuth consent screen, a dashboard behind a login, a preview of the app your agent just changed.

The Chromium runtime

The browser looks for a Chromium to drive, in this order:

TDE_BROWSER_CHROMIUM, if you set it to a binary path.
A system install: chromium, chromium-browser, google-chrome, google-chrome-stable or brave-browser on your PATH, then the usual fixed locations under /usr/bin, /opt/google/chrome and /snap/bin.
A TDE-managed Chrome for Testing, downloaded on demand into ~/.local/share/tde/chromium.
A Flatpak com.google.Chrome, last.

Managed downloads track the Chrome for Testing stable channel and are available for linux64, mac-arm64 and mac-x64. Set TDE_BROWSER_NO_DOWNLOAD=1 to forbid them entirely and stay on whatever the system provides.

The browser keeps a persistent profile at ~/.local/share/tde-browser/profile, so a site you logged into stays logged in across restarts. Point TDE_BROWSER_PROFILE somewhere else to keep a separate identity. Diagnostics are written to ~/.tde/log/tde-browser.log; set TDE_BROWSER_LOG=0 to turn that off.

Only one browser window can own that profile at a time.

Render modes

A terminal cell can only carry one glyph and one colour, so the browser offers four strategies for turning a web page into cells. F6 cycles them in the order below, and the current one is shown as View: <mode> on the toolbar.

Mode	What you get	Use it for
Image (default)	A lossless screenshot mirror painted as pixel or block cells. No DOM text at all.	Normal browsing. Highest fidelity.
Mobile	No screenshot. A QR code and PIN appear on screen; you open the URL on your phone, and the LAN relay captures the callback.	Logins and OAuth consent screens.
Page	Screenshot blocks with the page's DOM text drawn in place on top of them.	Reading. Closest to real layout, but dense pages look cramped.
Native	No screenshot. The page's interactive controls — text and password fields, buttons, links, checkboxes — are rebuilt as terminal widgets.	Driving a form or a login entirely from the keyboard.

In Page mode the text overlay is capped at 600 nodes per frame and 200 characters per node, so a very dense page will show fewer labels than it has.

Real pixels versus blocks

Whether Image and Page modes show actual pixels depends on what your terminal supports. TDE probes for this at startup and degrades in three steps:

Tier	Requires	Behaviour
Kitty Unicode placeholders	kitty, Ghostty	Best. The image lives in the grid as placeholder cells, so it clips correctly and respects z-order — it works tiled, floating or partly covered.
Legacy kitty graphics or sixel	kitty, Ghostty, or a sixel terminal	The image is drawn as an overlay. Because those protocols cannot clip to a region or honour z-order, it is only painted when the browser window is focused and maximized, and never in overview or with a dialog open.
Block cells	Any terminal	Always painted underneath as a fallback: half, quadrant, sextant (default) or octant glyphs. Set `TDE_BROWSER_BLOCKS` to pick.

If your terminal advertises no graphics protocol at all, TDE skips the encode work entirely rather than wasting the cycles. The full protocol matrix is in Terminal graphics.

Link-hint mode also suppresses the pixel layer, so the hint labels stay readable over the blocks.

Keys

Focus matters. The address bar has focus when the window opens; clicking the page moves focus to the page, where most keys are forwarded to the site instead of the browser.

Always active

Key	Action
`F6`	Cycle the render mode
`Ctrl+T`	New tab
`Ctrl+W`	Close the tab (ignored on the last one)
`Ctrl+Tab` / `Ctrl+Shift+Tab`	Next / previous tab
`Ctrl+B`	On a narrow window, toggle the tab drawer

When neither the address bar nor the page has focus

Key	Action
`l`	Focus the address bar
`f`	Link hints
`r`	Reload
`j`, `↓` / `k`, `↑`	Scroll down / up

Link hints are the fastest way to click without a mouse. Press f, and every clickable element gets a short label; type the label to click it, Backspace to correct, Esc to cancel.

In the address bar

Enter navigates, Esc gives focus back to the browser, and everything else types.

With the page focused

Typed characters are buffered briefly and sent to the page as text; Enter and Backspace are forwarded as keys, and Esc releases focus back to the browser.

In Native mode

Tab and ↓ move to the next control, Shift+Tab and ↑ to the previous, Enter activates (in a text field, submits the form), and Esc returns to the address bar.

Mouse

Click a tab chip to switch, its × to close, + for a new tab. The toolbar carries Back, Forward, Reload and the View chip. Click a breadcrumb segment to navigate up the URL. Click anywhere in the page to click through to the site, and use the wheel to scroll.

Limits worth knowing

One command at a time. While a CDP round trip is in flight, further navigation is dropped rather than queued — the status line shows Loading… (N). This is deliberate: it stops a click on a heavy news portal from queueing hundreds of screenshots.
Focus is invisible to TDE. The browser cannot ask Chromium whether a page input has focus, which is why page focus is something you set explicitly by clicking.
Narrow windows drop chrome. Below roughly 30 columns there is no room for a tab strip, a toolbar, a breadcrumb and an address field at once, so tabs move into ☰ and actions into ⋮.

From an agent

The narrowest verb opens a URL:

bash

tde agent open-url https://accounts.example.com/authorize?...

It opens the URL in TDE Browser, and it is what the $BROWSER bridge injected into TDE-hosted terminal apps calls — so a CLI that wants to open a consent screen lands in your browser window instead of nowhere.

Beyond that, tde agent browser ID … exposes the window's network layer, so an agent debugging a failing request reads the actual traffic instead of guessing from a screenshot:

bash

tde agent browser 7 capture start
tde agent browser 7 packets --errors --limit 20
tde agent browser 7 body REQ-14
tde agent browser 7 emulate throttle slow-3g

Capture and replay, HAR export, URL breakpoints and network/device emulation are covered in Browser network debugging. Everything else goes through the generic window verbs in the agent API.