# Browser Use Terminal: a Rust TUI that drives real Chrome over CDP

> Browser Use Terminal is a Rust terminal UI for browser agents that keeps the LLM loop, SQLite event log and CDP browser runtime in one binary. It is aimed at engineers who want to watch and steer an agent's browser work instead of firing off a headless script.

**browser-use/terminal** — Terminal UI to get stuff done in the browser

- Repository: https://github.com/browser-use/terminal
- Website: https://browser-use.com/terminal
- Stars: 646 · Forks: 39
- Language: Rust
- License: MIT
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/browser-use-terminal

## The problem Browser Use Terminal targets: agents that need a real logged-in browser

Most browser automation libraries assume a clean, disposable profile. That assumption breaks the moment the task depends on account state: an employee's Azure permissions, a hotel reservation behind a login, a city parking permit tied to your identity. Browser Use Terminal is built for that case. The README says it works with your logged-in Chrome when the task needs real account state, and it supports headless Chromium and Browser Use cloud for clean or remote runs. So the same tool covers the messy authenticated case and the disposable case, with the browser choice made at runtime rather than baked into the code.

The audience is narrow on purpose. This is not a library you import into a test suite. It is a terminal application an engineer runs, watches and interrupts. The README lists the intended verbs directly: watch, steer, stop, retry and resume tasks. If your workflow is a CI job that runs unattended and must produce the same result every time, this is the wrong shape of tool, and the section on limitations below says why.

It also ships a Python package. pyproject.toml declares browser-use-terminal version 0.1.8 with entry points browser-use-terminal, but and browser-use-terminal-ui, so the same harness can be reached from a shell script or from the TUI. The description in that file calls it "a browser-specific LLM harness built around raw CDP, durable sessions, and screenshot timelines." That is a fair summary of the design: the browser is not abstracted away behind a page-object layer.

## How the Rust harness, SQLite log and CDP runtime fit together

The README's architecture diagram is unusually explicit for a project at v0.1.8, and it is worth reading literally. The terminal sits at the top. Below it are four components: a custom Ratatui UI for watch, steer, stop and resume; a Rust LLM harness handling tools, subagents, compaction and cancellation; a SQLite event log for history, screenshots, artifacts and traces; and a CDP browser runtime handling profiles, doctor, recovery and ownership. The runtime then reaches real Chrome, headless Chromium, or Browser Use cloud.

The important claim is the split of responsibilities. Rust owns the agent loop and durable state. The model gets what the README calls raw browser capability: CDP, page JavaScript, screenshots, files and helper code. That means the model is not calling a curated set of high-level actions. It is issuing CDP commands and evaluating JavaScript directly, which is more expressive and correspondingly less predictable. The SQLite event log is what makes the loop recoverable: history and artifacts persist, so a stopped or crashed task has something to resume from.

The Cargo workspace confirms the shape. crates/browser-use-agent, browser-use-browser, browser-use-cli, browser-use-llm, browser-use-providers, browser-use-python-worker, browser-use-runtime, browser-use-protocol, browser-use-secrets, browser-use-store and browser-use-tui are separate members at version 0.1.8, edition 2021. The dependency list is telling: ratatui 0.30 with the crossterm_0_29 feature, rusqlite 0.39 with bundled SQLite, tungstenite for WebSocket work, aes-gcm and rpassword for secrets, and tree-sitter with tree-sitter-bash. Tree-sitter plus a bash grammar suggests the harness parses shell or code the model emits, rather than trusting it blindly. The README also notes release archives include a managed ripgrep binary at bin/agent-tools/rg, and that agent shell commands prepend a temporary tool shim and managed tools directory to PATH. That is a deliberate choice to make rg available to the agent regardless of the user's dotfiles.

## Installing Browser Use Terminal and running a first task

The README gives a one-line install for the terminal app. The script is fetched over HTTPS and piped to sh, which is convenient and also means you are executing whatever that URL returns at the time you run it. Read it first if that matters to you.

```bash
curl -fsSL https://browser-use.com/terminal/install.sh | sh
browser
```

The second command launches the TUI. Once inside, setup happens through slash commands rather than flags. The README lists four: /auth to sign in, /model to choose a model, /browser to choose local, headless or cloud browser, and /update to update the app. You need at least an auth step and a browser choice before a task will run.

Credentials come from environment variables. The repository's .env.example shows the expected keys, including BROWSER_USE_API_KEY, OPENAI_API_KEY, an optional LLM_BROWSER_OPENAI_API_KEY override, OPENROUTER_API_KEY, and optional ANTHROPIC_API_KEY and GEMINI_API_KEY entries. It also sets LLM_BROWSER_BROWSER_MODE=cloud and BU_NAME=rust-v14-remote-smoke as examples.

```bash
browser auth status
browser config show
browser diagnostics
```

Those three shell commands are the fastest way to confirm the install is sane before you spend tokens. diagnostics is the one to run first on a new machine, because the browser runtime deals with profiles and recovery and is the component most likely to be affected by local Chrome state.

If you would rather drive it from a coding assistant, the README documents a skill install path. The command browser-use-terminal skill install registers the skill for detected assistants, and browser-use-terminal browser exec takes a Python snippet on stdin. The README's example opens a new tab, waits for load, and prints a screenshot capture.

```bash
browser-use-terminal browser exec <<'PY'
new_tab("https://example.com")
wait_for_load()
print(capture_screenshot())
PY
```

Screenshots are written to files and the path is printed, so the assistant reads them with its own file tools (Claude Code Read, Codex view_image, OpenCode read). The browser persists between calls, which is the point: the assistant keeps one session across many invocations. Further detail is in docs/assistant-plugins.md.

## Where Browser Use Terminal is the wrong tool

The README makes a performance claim about the harness: it is "built to be 2x cheaper and 2x faster than Browser Harness." That is a design goal stated by the project, not an independent measurement, and the README does not publish the workload, model or pricing basis behind it. Treat it as a target, not a number you can budget against.

The larger limitation is structural. Because the model receives raw CDP, page JavaScript, screenshots and files, the set of actions it can take is effectively unbounded. There is no schema of permitted operations to validate against. For a task like "give this employee admin permission in Azure," that expressiveness is the whole value proposition, and it is also the risk: the agent is operating inside an authenticated session with your real permissions. The README describes cancellation and recovery, and the SQLite log gives you an audit trail, but neither is a permission boundary.

There is also a cost shape problem. Screenshots and page content go into the model context, and the harness includes compaction to manage that. Compaction exists because context grows; if your tasks are long, you are paying for tokens on content the model may only need once. The README does not document rollback of side effects performed in the browser. If the agent submits a form, the event log records it; it does not undo it. For irreversible actions, that gap matters more than any speed claim.

Finally, the project is young. The release history shows v0.1.6, v0.1.7 and v0.1.8 within four days in June 2026. The last push to main was on 2026-08-16. That cadence is normal for pre-1.0 work and also means interfaces can move. The README points to docs/terminal-renderer-architecture.md and docs/terminal-ui-testing.md, which is a sign the authors know the UI surface is still settling.

## How it differs from Playwright and Puppeteer

Playwright and Puppeteer are the obvious alternatives, and the difference is not feature parity, it is who decides the next action. In Playwright you write the sequence: selectors, waits, assertions. The program is deterministic, reviewable and cheap to run a thousand times. Browser Use Terminal inverts that. The model decides the next CDP command based on screenshots and page state, and the harness executes it. You get adaptability to pages you did not anticipate, at the cost of determinism and per-run token spend.

A second difference is the session model. Playwright can attach to a Chrome instance with connectOverCDP, but its normal mode is a fresh browser context. Browser Use Terminal treats your logged-in Chrome as a first-class target, alongside headless Chromium and Browser Use cloud. The README's browser runtime section lists profiles, doctor, recovery and ownership, which are the concerns you only have when the browser is long-lived and stateful rather than created per test.

The third difference is the interface. Playwright is a library; you consume it from code. Browser Use Terminal is a TUI you sit in front of, with history, artifacts and follow-ups, plus a CLI path for coding assistants. If your team's workflow is a CI pipeline, Playwright remains the better fit. If your workflow is an engineer investigating a task that has no clean API, the TUI is the point.

## Maintenance, upgrades and what the MIT licence means here

Upgrades are handled in-band. The README lists /update as a slash command inside the TUI, and the install script is a single curl line, so refreshing is not a manual build. For source checkouts, the Development section gives the commands the project expects contributors to run: cargo fmt --check, cargo test, uv run --with pytest python -m pytest -q, and scripts/verify-terminal-ui.sh. The README states that terminal UI changes must pass the full verification script, which runs Rust tests, Python tests, deterministic Ratatui dumps and a real tmux smoke test. That is a heavier bar than most pre-1.0 projects set, and it tells you UI regressions are taken seriously.

One maintenance detail worth knowing: release archives bundle a managed ripgrep at bin/agent-tools/rg, and source checkouts install the same binary under target/debug/agent-tools/rg. The README gives scripts/install-agent-ripgrep.sh target/debug/agent-tools as the manual refresh command. If you vendor this into an environment where shell PATH is controlled by policy, that shim behavior is something to verify rather than assume.

The licence is MIT, declared in both the repository and the Cargo workspace. MIT is permissive: you can use, modify and redistribute the code, including in closed products, provided the copyright notice and permission notice are preserved. It offers no patent grant and no warranty. That is the standard trade-off and it is not legal advice; if you are shipping this inside a regulated product, have counsel read the LICENSE file rather than this paragraph.

## Conclusion

Adopt Browser Use Terminal if you need an agent working inside a logged-in Chrome profile and you want to watch, stop and resume it from a terminal. Skip it if you only need scripted, deterministic browser automation, since an LLM harness adds cost and nondeterminism you do not need. Before committing, run browser diagnostics on the target machine, confirm which model provider you will fund, and read docs/terminal-renderer-architecture.md because the renderer and the assistant plugin path are the parts most likely to change between v0.1.6 and v0.1.8.

## FAQ

### Does Browser Use Terminal work with my logged-in Chrome profile?

Yes. The README states that it works with your logged-in Chrome when a task needs real account state, and the browser runtime handles profiles, doctor and recovery. Headless Chromium and Browser Use cloud are also supported as alternatives.

### How do I install Browser Use Terminal?

The README gives a single install line that fetches https://browser-use.com/terminal/install.sh and pipes it to sh, followed by running the browser command to launch the TUI. Setup inside the app is done with the /auth, /model and /browser slash commands.

### Can I use Browser Use Terminal from Claude Code or Codex?

Yes. The README documents browser-use-terminal skill install to register the skill for detected assistants, and browser-use-terminal browser exec to run a Python snippet against the persistent browser. Screenshots are saved as files and the path is printed so the assistant reads them with its own file tools.

### How do I turn off telemetry in Browser Use Terminal?

The README states that telemetry, described there as 100% completely anonymous, can be disabled by setting BUT_TELEMETRY=0. The .env.example lists BUT_TELEMETRY alongside other optional analytics variables.

### Is the 2x cheaper and 2x faster claim about the Browser Use Terminal harness measured?

The README states that the LLM harness is built to be 2x cheaper and 2x faster than Browser Harness, but it does not publish the workload, model or pricing basis behind that figure. Treat it as a design goal rather than a measured result.

## Sources

- [browser-use/terminal on GitHub](https://github.com/browser-use/terminal)
- [License: MIT](https://github.com/browser-use/terminal/blob/main/LICENSE)
- [Project website](https://browser-use.com/terminal)
- [README](https://github.com/browser-use/terminal/blob/main/README.md)
- [Releases](https://github.com/browser-use/terminal/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/browser-use-terminal