Tagent logotagent

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-open

The 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

  1. Open http://localhost:4020 — the GUI connects over websocket automatically.
  2. Click the gear icon → add an API key for any provider (OpenAI, Anthropic, Google, OpenRouter, Groq, Ollama, Z.ai). Keys are stored locally only.
  3. Pick a workspace folder when starting the daemon — that's the agent's playground.
  4. 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.md with 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": true swaps 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 carry contextWindow), provider seeds or heuristics — TAGENT_CONTEXT_WINDOW overrides.
  • 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 only

The 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/config and 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 --rebase step 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.json

Update path: git pull && bash scripts/setup-ubuntu.sh — the pre-built GUI updates with the pull.

Troubleshooting

Port 4020 already in usetagent <folder> --port 4021
GUI shows “demo mode”daemon not running — start it with tagent web <folder>
bun: command not foundexport PATH="$HOME/.bun/bin:$PATH"
No provider keySettings → add a key, or run a local Ollama and pick it as provider
Accidental edit/undo restores the last auto-checkpoint
Version warning wrongrm ~/.tagent/update-check.json; tagent --check-update