README
¶
Agenton Pocket
Run claude / codex / any CLI agent in daemon-owned sessions, and drive them
from wherever you are: a minimal TUI at the desk, a tap-friendly web client on
your phone. Sessions survive detach, replay scrollback on reattach, and can be
watched from both clients at once. The daemon + wire protocol are designed to
be reused unchanged by a future native iOS client.
Quickstart
./install.sh
It asks where to put the binary, defaulting to /usr/local/bin:
Install agenton to [/usr/local/bin]:
Press enter to accept, or type any directory (~ works). It fetches a prebuilt
release, or builds from source if Go is present and no release matches. To skip
the prompt — for scripts, or curl … | bash, which never prompts — name the
directory up front:
./install.sh -d ~/.local/bin # or AGENTON_INSTALL_DIR=~/.local/bin
After that, from anywhere:
agenton
That starts everything: the daemon (if not running), the web server (if not
running), and drops you into the TUI. With the Tailscale app running on the
computer, it publishes the phone bridge over your tailnet and prints a QR — no
extra config, nothing to approve, works on the free Tailscale plan. Quitting the
TUI leaves the daemon, web server, and all sessions running — agenton again to
come back.
Logs land in ~/.local/state/agenton/.
Headless (a server that only needs daemon + web): agenton up -no-tui.
Prefer to build by hand? go build -o agenton ./cmd/agenton still works; run it
as ./agenton.
Phone access (Tailscale)
Step-by-step tutorial (including phone-side setup and the web client's Terminal/Controller modes): docs/phone-setup.md.
agenton serves the phone bridge over your tailnet through the system Tailscale app on the computer. It registers no tailnet node of its own — nothing to approve, no login link, works on the free plan. One command:
agenton up -no-tui # binds the Mac's tailnet IP and prints a connect QR
On the phone, open the agenton iOS app, tap ⚙︎ → Scan QR, and scan the
block it printed. Reprint any time with agenton qr.
No app? The server also hosts a web client. Open the printed http://…
URL in any browser on your tailnet, or run agenton qr --web for a QR of that
URL you can scan with the phone's plain Camera (it opens straight in the
browser — no scheme, no app).
One time on both machines: install the Tailscale app (App Store / Play Store), log in with the same account, and switch it on — that's how each device gets onto the tailnet.
Modes:
agenton up(default) — over the tailnet via the system Tailscale app.agenton up --lan— localhost only, no tailnet publish.
agenton speaks plain HTTP and terminates no TLS. Your tailnet is the security boundary: only devices logged into your tailnet can reach the port, and nothing is exposed to the internet. Tailscale already encrypts the wire.
Using the TUI
The TUI is a minimal terminal wrapper: at the desk you type to the agent directly, and the TUI just adds session switching on top.
Entry screen (session list): enter attach · n new session · d delete ·
r refresh · q quit. n opens a plain shell in the directory you launched
the TUI from — you run claude/codex (or anything) inside it, cd-ing
wherever you like first. The list auto-refreshes, so sessions you start or kill
from the phone/web client show up on their own, and each row's path tracks
where its agent is actually running (the shell's live working directory), not
where the session was first opened.
Session view: a full-screen raw terminal with no chrome — every key goes
straight to the PTY, exactly as if you'd launched the shell here. The one
reserved key is ctrl+t, which returns to the session list to switch sessions
(the session keeps running, so it doubles as detach). The on-screen button pad
and custom-key rebinding live on the phone/web clients, where there's no
physical keyboard to type with.
Using the web client
Mobile-first mirror of the TUI: session list (tap to attach, ✕ to kill, new
sessions via a command + cwd form), live terminal, a 4×3 button pad
(accept / reject / mode / stop · ▲ ▼ ◀ ▶ · esc / rewind / 2 custom), and a
text bar. The Pad/Term button switches between Terminal (the phone
owns the PTY size, terminal renders correctly) and Controller (the desk
owns it; the phone becomes a full-screen button pad instead of a shrunk
frame) — the phone parks itself into Controller automatically when you start
typing at the desk.
- New-session suggestions: chips above the form — sessions currently
running under the daemon, agent processes discovered elsewhere on the host
(
claude/codex/cortext/ollama run, clonable but not attachable), your recent commands (per-device), then starters. Tap to fill, edit, go. - Rebind custom buttons: long-press Custom 1/2 → tap-to-compose picker (chips for keys/combos, text field for literal strings) — no combo typing on a phone.
Shared sessions
The TUI and web client are two views of the same daemon: create a session in either, attach from both at once — output streams live to every attached client. Exactly one client owns the PTY size at a time (the "active" device): it renders the live terminal, and everyone else parks into a purpose-built role instead of showing a mis-sized frame — the desk TUI freezes its last frame behind a "press any key to take over" hint, and the phone clients (web and iOS) flip to Controller mode. Buttons and text still work while parked; they drive the agent without stealing the size.
Configure (optional)
Presets pin an agent + cwd + custom buttons under a name:
mkdir -p ~/.config/agenton
cat > ~/.config/agenton/config.toml <<'EOF'
[preset.api-refactor]
agent = "claude"
cwd = "~/repos/api"
command = "claude"
# Only the two custom buttons are configurable; accept/reject/mode/
# interrupt/rewind are fixed per agent (claude/codex/shell), detected
# from the session's command line. Each custom button holds one value:
# a key name / combo (Ctrl+O, Shift+Tab, Esc, ...) or a literal string.
[preset.api-refactor.buttons]
custom_1 = "Ctrl+O"
custom_2 = "/compact"
EOF
Commands
agenton # start everything (daemon + web if needed) and open the TUI
agenton up -no-tui # start daemon + web only (headless/server)
agenton tui # just the TUI (daemon must be running)
agenton web # just the web server (default 127.0.0.1:9787)
agenton daemon # just the daemon (socket at ~/.agenton/agenton.sock)
agenton client # stdio bridge (remote transport, future SSH/Tailscale)
agenton qr # publish over Tailscale + print the iOS connect QR
Test
go test ./... # unit + e2e (local, simulated-remote, WS bridge)
Hacking on it? ./dev.sh rebuilds, restarts the daemon + web, and installs a
fresh iOS build on a simulator pointed at it. The steps are independent —
./dev.sh ios leaves your running sessions alone, ./dev.sh -h lists the rest.
Note the web client is embedded in the binary, so editing internal/web/static/
needs a rebuild + restart, not just a browser reload.
Architecture
TUI (Bubble Tea) ────Unix socket────┐
phone browser ⇄ WS ⇄ agenton web ───┤──> daemon (owns PTYs) ──> claude / codex / …
SSH exec `agenton client` (stdio) ──┘
Wire frame: [1 type][4 session_id][4 len][payload]; 0x01=control JSON,
0x02=raw PTY bytes. One WS binary message = one frame. The daemon listens on
a Unix socket only and never opens a public port; remote access rides your
tailnet (the web server binds the machine's tailnet IP, never 0.0.0.0).
Sessions persist across detach (daemon-owned PTYs + scrollback ring buffer);
reattach replays scrollback then streams live output.
Design docs
The architecture is summarized above (protocol, daemon, transport). For the end-to-end walkthrough of connecting a phone to your daemon, see the phone setup tutorial.
License
Copyright © 2026 Niu Du. Licensed under GPL-3.0 — see LICENSE.
The daemon + web source is free software under GPL-3.0. The iOS App Store
binary is a separate proprietary build shipped by the copyright holder — a
paid convenience, not GPL-licensed. This dual arrangement works because all
copyright is held by one author; outside contributions are accepted under a
CLA so that right is preserved. The repo is hosted in the
nduwork workspace, but copyright is held by Niu Du personally.
Third-party licenses (bundled Go modules, including the Tailscale client under BSD-3-Clause): see THIRD_PARTY_LICENSES.md.
Directories