Docs
Current release: v0.31.2 — see the changelog.
Install — laptop & desktop
Tagent needs a Linux/Unix environment with git and curl; the installer adds the Bun runtime and dependencies. The web GUI ships pre-built in the repo, so there is nothing to compile. Debian, Ubuntu 20.04+ and WSL2 are tested.
git clone https://github.com/asysurya/tagent.git
cd tagent
bash scripts/setup-ubuntu.sh # bun + deps; --with-browser adds Playwright Chromium# start it on any folder:
bun link
tagent start ~/my-project
# → http://localhost:4020 (GUI + agent, one process)macOS works too (installer detects it), and Windows via WSL2. Prefer manual setup? Install Bun from bun.sh, then bun install inside the repo.
Install — Android phone (UserLAnd)
No root needed. UserLAnd runs a real Ubuntu filesystem on top of Android via proot, and shares the network — so the daemon is reachable from your phone browser at localhost.
# 1. install "UserLAnd" from the Play Store, create an Ubuntu session
# 2. inside the UserLAnd terminal:
sudo apt-get update && sudo apt-get install -y git curl
git clone https://github.com/asysurya/tagent.git
cd tagent && bash scripts/setup-ubuntu.sh# 3. start the agent, then open http://localhost:4020 in Chrome:
tagent web ~/my-project --no-openThe setup script detects phones automatically (skips heavy Chromium, prints mobile hints). Full guide with battery/background/RAM tips: docs/USERLAND.md. iOS users: run Tagent on a PC/VPS and open http://its-ip:4020 (start with --host 0.0.0.0, use a tunnel on untrusted networks).
First run
- Open http://localhost:4020 — the GUI connects over websocket automatically.
- Click the gear icon → add an API key for any provider (OpenAI, Anthropic, Google, OpenRouter, Groq, Ollama, Z.ai). Keys are stored locally only.
- Pick a workspace folder when starting the daemon — that's the agent's playground.
- Try the demo: clone Tagent, point the daemon at demo-workspace and ask it to "fix both bugs in the README".
Using the agent
- Chat — describe the task; the loop plans, calls tools, and reports back. Interrupt any time; steer mid-run.
- Markdown — assistant replies render properly in the terminal: headings, bold/italic, code blocks, lists and tables.
- Keys — ESC stops a running agent (or clears the input when idle); ? on an empty input lists every shortcut; ↑/↓ recall input history; the hint row under the editor keeps model · mode · tokens · ⎇ repo visible. The transcript lives in your terminal's own scrollback — scroll it however your terminal does (mouse wheel, touch, shift+pgup).
- Permissions — every risky action (bash, write, edit, MCP tools) asks first — an arrow-key menu in the TUI, a dialog in the GUI. Choose once / session / always.
- Checkpoints — auto-snapshots before writes; /undo restores.
- Plan mode — read-only exploration before committing to changes. When something material is unknown, the agent interviews you with an ask form (see ask_user below).
- Test mode — tagent test (or /test, or the Test button in the topbar) turns the agent into a QA engineer: it boots the project (auto-detected dev command), clicks through it with a real Chromium — buttons, inputs, forms — and sees the result of every interaction, screenshots mobile/tablet/desktop, runs a deterministic UI audit (horizontal overflow, tap targets, typography, contrast), and writes
TEST-REPORT.mdwith a pass/warn/fail verdict. Vision models (GPT-4o/5, Claude, Gemini, GLM-4V…) see the screenshots themselves; text models get the DOM audit. Test mode never modifies source files — the report is its only write. One-time setup in your project:bun add playwright && bunx playwright install chromium. - Ask forms (ask_user) — when a decision materially changes the work, the agent asks through an interactive form instead of guessing: option (single choice), multi (pick any) and input (free text) fields, up to 6 questions in one call. Option/multi fields always offer + add your own option, and every form carries an optional notes box under the fields. The TUI renders it as an overlay (↑↓ move · space/enter pick · a add option · tab next field · esc cancel), the GUI shows a dialog, and headless runs get an honest "no interactive user" answer so the model proceeds with stated assumptions.
- Z.ai models config — the built-in provider's model list is a file: edit
~/.tagent/zai-models.json(global) or<workspace>/.tagent/zai-models.json(per project) to add, relabel or vision-flag models — same ids replace the built-ins, new ids append,"replace": trueswaps the whole list. No release wait for a new model. - Context window bar — the hint row under the chat input always shows how much of the model's window the session eats, opencode-style:
12.3k/131.1k [██████░░░░] 9%. Live per turn (provider usage when reported, else a local CJK-aware estimate), color-coded green/yellow/red. Model windows come from the catalog (each zai-models.json entry can carrycontextWindow), provider seeds or heuristics —TAGENT_CONTEXT_WINDOWoverrides. - Deterministic compaction (/compact) — when the bar crosses 80% (configurable) you get a one-key prompt to ringkas memory; /compact [keep-tokens] works any time. Old turns become one structured digest (who asked what, which tools ran on which paths, statuses, decisions) while recent turns stay verbatim — a 100k-token history lands near 10k. 100% local code: no AI call, nothing invented — every digest line is copied from the transcript, @attachment bodies drop out (files are on disk), and re-compaction folds the prior digest in. Compaction itself costs zero tokens.
- Real TUI libraries (v0.18.0) — the terminal interface is built on string-width · figures · cli-boxes · picocolors · wrap-ansi: the boot banner and your messages render as rounded cards (
╭─ ❯ you ─╮), tool lines carry emoji icons with a fixed tool-name column, markdown tables draw as full box tables, and every width counts CJK, emoji and combining marks correctly — columns stay aligned in any language. - Subagents — "spawn a subagent to review X" runs research in an isolated context.
- Slash commands — /model /mcp /plugins /sessions /undo /update and plugin-defined ones. Menus are interactive: arrow keys + Enter, type to filter.
- Smart cache — re-reading an unchanged file returns a tiny stub (the bytes are already in context); read_files batches up to 12 paths in one call; attach a file inline by mentioning @src/file.ts in chat. tagent cache inspects and clears it all.
GitHub login & sync
Guest-first: everything works locally, no account needed. When you want your projects on GitHub, log in once. In a terminal the picker defaults to web connect: a one-time page opens in your browser (served on 127.0.0.1 with a one-time secret URL), you paste the token there and the terminal takes it from there — nothing is ever typed into the terminal itself. On UserLAnd/Termux the printed URL opens fine in the phone's own browser. The token is stored in ~/.tagent/credentials.json (chmod 600, never in config.json). After login, if the current workspace has files and is not linked yet, tagent asks once: sync this project to a private GitHub repo? — Sync now / Later / Not this project (remembered).
tagent auth # login — picker: web connect (browser page) or paste a PAT
# --web straight to the browser flow
# --device OAuth device flow (one button on GitHub)
tagent sync # snapshot the current project: commit + push
tagent sync "docs: readme" # …with a custom commit message
tagent projects # linked projects — name, repo, last sync
tagent clone my-app # continue a project on this machine
tagent whoami # guest or login?
tagent logout # remove the local token onlyThe Connect with GitHub button on the web-connect page is the happy path: one click, press Authorize on GitHub, done — no tokens created by hand (OAuth device flow; the tagent app id ships with the binary, so it works out of the box). On the page you'll see a short code like BCB2-5F72 with a copy button — paste it on GitHub if it isn't pre-filled for you. Prefer a PAT? Paste a token instead stays one click away.
- Web connect — a local one-time page on
127.0.0.1: one-click OAuth or the paste-a-PAT fallback (the repo scope is pre-selected via the create-token link), the token is validated against the GitHub API and stored exactly like the paste flow. Loopback-only bind, secret URL path, Origin checks, and the server dies after the login. - Sync — commits the workspace and pushes with a one-shot token; the remote URL stays clean in
.git/configand the repo stays private. - Multi-device — sync fetches and rebases whatever the other devices pushed before pushing, so editing one project from several machines converges instead of colliding: different files (or different regions of one file) merge automatically, and if two devices change the same lines the sync stops with a clear "nothing was lost" message plus the exact
git pull --rebasestep to resolve it. A sync with no local changes doubles as a pull. - Clone — tagent clone owner/repo (or just the project name from your registry) restores it, then cd in and run tagent start.
- Web GUI — the same flow as dialogs: GitHub login, sync workspace, and a project list with last-sync times.
MCP servers
Tagent speaks the Model Context Protocol over stdio. Connect any server — Context7 for up-to-date library docs, filesystem, memory, sequential-thinking or your own — and its tools become agent-callable natives named mcp_<server>_<tool> behind the same permission gates.
# interactive manager — status, one-click templates, custom servers
# TUI: /mcp GUI: Settings → MCP
# or .tagent/config.json:
"mcp": { "servers": {
"context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }
}}Plugins
A plugin is a hot-reloading .mjs file in.tagent/plugins/ exporting any mix of: lifecycle hooks, custom agent tools (plugin_<name>_<tool>) and custom slash commands. Scaffold one from/plugins in the TUI or Settings → Plugins in the GUI.
Configuration
Workspace-local .tagent/config.json overrides ~/.tagent/config.json. Both are gitignored.
{
"defaultProvider": "openai",
"defaultModel": "gpt-5",
"apiKeys": { "openai": "sk-…" },
"permissions": { "tools": { "bash": "ask", "write_file": "ask" } },
"tools": { "bash": true, "browser": false },
"github": { "repo": "my-workspace" },
"maxTurns": 40
}GitHub auth is not configured here — tagent authstores the token in the credentials store; the github.repo key only overrides the repo name tagent sync pushes to.
Updates & version check
On startup the TUI checks for a newer release (at most once a day, result cached locally) and, when one exists, offers an arrow-key y/N update prompt. Answer yes and Tagent updates itself in place — binaries download the matching release asset and swap it, npm/bun installs run the global upgrade, source checkoutsgit pull. An outdated Tagent that declines the update keeps working fully — nothing breaks, nothing locks. Checks are silent when offline.
tagent update # check + self-update (y/N) from the shell
tagent --version # print the running version
tagent --check-update # force a check right now
# override the endpoint (e.g. self-hosted mirror):
export TAGENT_UPDATE_URL=https://your-host/latest.jsonUpdate path: git pull && bash scripts/setup-ubuntu.sh — the pre-built GUI updates with the pull.
Troubleshooting
| Port 4020 already in use | tagent <folder> --port 4021 |
| GUI shows “demo mode” | daemon not running — start it with tagent web <folder> |
| bun: command not found | export PATH="$HOME/.bun/bin:$PATH" |
| No provider key | Settings → add a key, or run a local Ollama and pick it as provider |
| Accidental edit | /undo restores the last auto-checkpoint |
| Version warning wrong | rm ~/.tagent/update-check.json; tagent --check-update |