1# zot
2
3yet another coding agent harness, lightweight and written (vibe-slopped) in go.
4
5- one static binary.
6- two providers atm (anthropic, openai/codex).
7- four tools (read, write, edit, bash).
8- three run modes (interactive tui, print, json).
9- built-in telegram bot.
10- no extensions atm.
11- no community atm.
12
13## install
14
15### one-liner (macos + linux)
16
17```bash
18curl -fsSL https://raw.githubusercontent.com/patriceckhart/zot/main/install.sh | bash
19```
20
21detects your os/arch, downloads the latest release from github, verifies the sha256 against the release's `checksums.txt`, extracts the binary, and drops it in `/usr/local/bin`, `~/.local/bin`, or `~/bin` — whichever is writable first. pass a version or prefix to pin:
22
23```bash
24curl -fsSL https://raw.githubusercontent.com/patriceckhart/zot/main/install.sh | bash -s -- v0.0.1 ~/bin
25```
26
27### one-liner (windows, powershell)
28
29```powershell
30iwr -useb https://raw.githubusercontent.com/patriceckhart/zot/main/install.ps1 | iex
31```
32
33drops `zot.exe` into `$HOME\bin` and adds it to the user PATH if missing. open a fresh terminal afterwards.
34
35### homebrew (macos + linux)
36
37```bash
38brew install patriceckhart/tap/zot
39```
40
41the tap lives at `patriceckhart/homebrew-tap`.
42
43### go install
44
45```bash
46go install github.com/patriceckhart/zot/cmd/zot@latest
47```
48
49### from source
50
51```bash
52git clone https://github.com/patriceckhart/zot
53cd zot
54make build        # produces ./bin/zot
55make install      # into $GOPATH/bin
56```
57
58### prebuilt binaries
59
60every release on the [releases page](https://github.com/patriceckhart/zot/releases) ships archives for linux, macos, and windows on amd64 + arm64 (except windows/arm64), plus a `checksums.txt` file. download, verify, `chmod +x`, and drop on your `$PATH`.
61
62## authenticate
63
64the easiest way is to just run `zot` and type `/login`. the tui opens even without credentials and walks you through a browser-based login flow.
65
66### credential lookup order
67
681. `--api-key` flag
692. `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` env var
703. `$ZOT_HOME/auth.json` (api key or oauth token; mode 0600)
71
72`$ZOT_HOME` defaults to:
73- macOS: `~/Library/Application Support/zot`
74- linux: `$XDG_STATE_HOME/zot` or `~/.local/state/zot`
75- windows: `%LOCALAPPDATA%\zot`
76
77### `/login` flow
78
79run `zot` and type `/login`. pick one of two methods:
80
81- **api key** — a small local web server starts on `127.0.0.1:<free-port>`, your browser opens a form, you paste your `sk-ant-...` or `sk-...` key. zot probes the provider once and saves it to `auth.json` if accepted.
82- **subscription** — use your claude pro/max or chatgpt plus/pro subscription. the oauth flow pins the callback to a fixed port per provider (`localhost:53692` for anthropic, `localhost:1455` for openai) because those are the only ports their auth servers will redirect to.
83  - anthropic uses the claude code oauth flow; messages go to `api.anthropic.com` with a bearer token and the claude-code identity headers.
84  - openai uses the codex cli oauth flow; messages go to `chatgpt.com/backend-api/codex/responses` with the `chatgpt-account-id` extracted from the returned id_token.
85
86> **note on subscription login**: the oauth client ids used are the ones published in anthropic's claude code cli and openai's codex cli. reusing them from a third-party tool is against their terms of service and may be revoked at any time. use it at your own risk; the api-key flow is the safe default.
87
88### token refresh
89
90oauth access tokens are short-lived (anthropic ~8h, openai ~30d). zot refreshes them automatically:
91
92- at every credential lookup, zot checks the stored `expiry` and — if past it (with a 60s safety margin) — hits the provider's `oauth/token` endpoint with the stored `refresh_token`, persists the new `access_token` + `refresh_token` + `expiry` back to `auth.json`, and hands the fresh token to the client.
93- the telegram bridge additionally refreshes once per turn so a bot that runs for days keeps working without manual intervention.
94- if the refresh itself fails (the `refresh_token` was revoked, or the account was logged out everywhere), the error bubbles up to the caller: the tui shows it in the status line, the bot replies with it in your dm. run `/login` to get a fresh token pair.
95
96all data lives under `$ZOT_HOME`:
97
98```
99$ZOT_HOME/
100├── config.json         # last-used provider/model/theme, saved automatically
101├── auth.json           # api keys and oauth tokens (mode 0600)
102├── sessions/           # jsonl transcripts, one dir per cwd
103├── models-cache.json   # live /v1/models discovery cache (6h ttl)
104└── logs/               # app log files
105```
106
107## usage
108
109```bash
110zot                              # interactive tui
111zot "fix the failing test"       # tui, pre-filled prompt
112zot -p "list all go files"       # print final text, exit
113zot --json "refactor main.go"    # newline-delimited json events, exit
114zot --continue                   # resume the most recent session for this cwd
115zot --resume                     # pick a session to resume
116zot --list-models                # show supported models
117zot --help
118```
119
120## flags
121
122| flag | description |
123|---|---|
124| `--provider anthropic\|openai` | pick the provider |
125| `--model <id>` | pick the model (see `--list-models`) |
126| `--api-key <key>` | override api key |
127| `--base-url <url>` | override provider base url (tests / self-hosted) |
128| `--system-prompt <text>` | replace the default system prompt |
129| `--append-system-prompt <text>` | append text to the system prompt (repeatable) |
130| `--reasoning low\|medium\|high` | enable reasoning on supported models |
131| `-c`, `--continue` | resume the latest session for this cwd |
132| `-r`, `--resume` | pick a session to resume |
133| `--session <path>` | resume a specific session file |
134| `--no-session` | don't read or write session files |
135| `--cwd <path>` | use `<path>` as the working directory |
136| `--no-tools` | disable all tools |
137| `--tools <csv>` | only enable the listed tools |
138| `--max-steps <n>` | cap agent loop iterations (default 50) |
139
140## tools
141
142- `read` — read text files (or inline images: png / jpg / gif / webp)
143- `write` — create or overwrite files, making parent directories as needed
144- `edit` — one or more exact-match replacements in an existing file
145- `bash` — run a shell command in the session cwd, with merged stdout/stderr and a timeout
146
147when the sandbox is on (see `/lock`), all four tools refuse paths outside the session cwd.
148
149## modes
150
151- **interactive** (default): chat tui with streaming output, spinner, cost meter, slash commands.
152- **print**: `zot -p "prompt"` runs the agent to completion and writes only the final assistant text to stdout.
153- **json**: `zot --json "prompt"` emits one json object per agent event to stdout, newline-delimited. the schema is documented in `instructions.md` §8.
154
155## slash commands
156
157type `/` in the tui to open the autocomplete popup. available commands:
158
159| command | description |
160|---|---|
161| `/help` | show key bindings and commands |
162| `/login` | log in via api key or subscription (opens a dialog) |
163| `/logout [provider]` | clear credentials for `anthropic`, `openai`, or all when omitted |
164| `/model` | pick a model from a list (or `/model <id>` to set directly) |
165| `/sessions` | resume a previous session for this directory |
166| `/jump` | scroll the chat to a previous turn (or `/jump <text>` to filter) |
167| `/compact` | summarize the transcript into one message to free up context |
168| `/lock` | confine tools to the current directory |
169| `/unlock` | allow tools to touch paths outside again |
170| `/clear` | clear the chat transcript |
171| `/exit` | exit zot |
172
173### `/sessions`
174
175shows previous sessions for the current working directory, newest first, with timestamp, model, message count, cost, and the first user prompt. pick one with `↑/↓`, `enter` to resume, `esc` to cancel. zot swaps the current session file for the selected one and replays the full transcript (including tool calls) into the agent. sessions remember the model they ended on, so resuming picks up on that exact model even if your global default changed.
176
177### `/jump`
178
179opens a turn picker for the current session — one row per user prompt, each showing the turn number, how many tools that turn invoked, and the first line of the prompt. `↑/↓` to pick, `enter` to jump, `esc` to cancel. any printable rune while the picker is open extends a filter; backspace narrows it back. `/jump <text>` pre-applies the filter; if exactly one turn matches, zot jumps straight there without showing the picker.
180
181jumping is non-destructive — the transcript is untouched, the viewport just scrolls so the chosen turn is at the top. a muted line at the top of the chat reads `↑ viewing turn N of M · pgdn to catch up`; scroll back to the bottom with `pgdn` (or keep scrolling with the arrow keys) and the indicator goes away.
182
183### `/compact`
184
185sends the current transcript through the model with a structured summarization prompt. the returned summary replaces the transcript as one synthetic user message, with the last few exchanges kept verbatim for continuity. status bar's `ctx N/M (P%)` meter resets. use it when the context meter creeps past ~80%.
186
187zot also auto-compacts in the background: after any turn that leaves context usage ≥ **85%** of the model's window, the agent kicks off a condense pass on its own. you'll see `condensing history… (esc to cancel)` above the status bar and an `(auto)` tag next to the context percentage; esc aborts it without touching the transcript.
188
189### `/lock`
190
191enforces a sandbox rooted at the cwd shown in the status bar. `read` / `write` / `edit` resolve their target path (including through symlinks) and refuse anything outside the sandbox. `bash` refuses obvious escape patterns: `sudo`, `rm -rf /`, leading `cd /` / `cd ..` / `cd ~`, `chmod -R`, `dd of=/`, etc. status bar shows `· locked · ~/your/cwd` while active.
192
193this is a guardrail against accidents, not a hard security boundary. if you need real isolation, run zot under docker or a proper sandbox.
194
195## sessions
196
197every interactive or print/json run (unless `--no-session`) writes a jsonl transcript under `$ZOT_HOME/sessions/<cwd-hash>/`. resume any of them with `--continue`, `--resume`, `--session <path>`, or interactively via `/sessions` inside the tui.
198
199## models
200
201`--list-models` or the `/model` picker shows the full catalog. three sources:
202
203- **catalog** — models baked into zot, always available
204- **live** — ids discovered from `GET /v1/models` using your stored api key (cached for 6h in `$ZOT_HOME/models-cache.json`, refreshed in the background on startup)
205- **speculative** — ids that appear in the upstream generator but aren't live on the public api yet; they'll 404 today and start working the moment the provider ships them
206
207the context meter in the status line (`ctx N/M (P%)`) uses the model's advertised context window to show how much of it your last turn consumed.
208
209## inline images
210
211when a tool returns an image (e.g. `read` on a png), zot renders it inline on terminals that support it: **iterm2**, **wezterm**, **kitty**, **ghostty**. on other terminals you see a text placeholder with mime type, pixel dimensions, and byte size. control with the `ZOT_INLINE_IMAGES` env var:
212
213| value | effect |
214|---|---|
215| unset (default) | auto-detect based on `TERM_PROGRAM` |
216| `iterm` / `iterm2` | force iterm2 osc 1337 protocol |
217| `kitty` | force kitty graphics protocol |
218| `off` / `none` | always use the text placeholder |
219
220frames containing images are full-repainted (no differential diff) to prevent stale image pixels from lingering through scroll. that costs one terminal flash per image-containing frame; set `ZOT_INLINE_IMAGES=off` if that bothers you.
221
222## queued messages
223
224you can keep typing while the agent is working. pressing enter during a turn queues the message instead of interrupting: it shows up above the status bar as `▸ sliding in: <text>` and is delivered as the next user turn the moment the current one finishes. queue as many as you want; they run in order. esc / ctrl+c cancels the active turn and drops the queue so a runaway turn doesn't flood you with stale follow-ups.
225
226slash commands also work while the agent is busy. read-only ones (`/help`, `/jump`, `/sessions`, `/lock`, `/unlock`, `/exit`) take effect immediately. destructive ones (`/clear`, `/compact`, `/login`, `/logout`, `/model`) cancel the active turn first and then run.
227
228## keys (interactive mode)
229
230### input
231
232| key | action |
233|---|---|
234| `enter` | submit (queued if the agent is busy) |
235| `alt+enter` | newline |
236| `tab` | complete the selected slash command |
237| `esc` | cancel the current turn (while busy); clear input (while idle) |
238| `ctrl+c` | exit when idle; cancel the current turn while busy |
239| `ctrl+d` | exit on empty input |
240| `ctrl+l` | redraw the screen |
241| `ctrl+o` | expand / collapse long tool results |
242
243### editor line navigation
244
245| key | action |
246|---|---|
247| `ctrl+a` / `ctrl+e` | jump to start / end of line |
248| `alt+←` / `alt+→` | jump one word back / forward |
249| `ctrl+u` / `ctrl+k` | delete to start / end of line |
250| `ctrl+w` · `alt+backspace` | delete the previous word |
251| `up` / `down` (editor non-empty) | cycle through prompt history |
252
253### chat scroll
254
255| key | action |
256|---|---|
257| `pgup` / `pgdn` | scroll one page up / down |
258| `up` / `down` (editor empty) | scroll three lines up / down — this is how the mouse wheel reaches the scroll logic on most terminals |
259
260## telegram bot (bridge)
261
262zot can run as a telegram bot so you can dm it from your phone. it's a built-in subcommand, not a plugin:
263
264```bash
265zot telegram-bot setup     # paste a BotFather token, verify, save
266zot telegram-bot run       # foreground: long-poll in this terminal (ctrl+c to stop)
267zot telegram-bot start     # background: detach and return immediately
268zot telegram-bot stop      # sigterm the background bot (sigkill after 5s)
269zot telegram-bot logs -f   # tail $ZOT_HOME/logs/bot.log (omit -f to just cat)
270zot telegram-bot status    # config (token masked) + running/stopped
271zot telegram-bot reset     # forget the token + paired user
272# short alias: `zot tg ...` is accepted for every subcommand
273```
274
275the background flavor writes the child's pid to `$ZOT_HOME/bot.pid` and redirects stdout+stderr to `$ZOT_HOME/logs/bot.log`. `zot telegram-bot stop` reads that pid, sends sigterm, waits up to five seconds, then escalates to sigkill if the child is still alive. running two instances at once is refused at startup.
276
277> **use the installed binary for `start`.** `go run ./cmd/zot telegram-bot start` won't work — `go run` builds a binary in a temp directory and deletes it when it exits, which kills the detached child. run `make install` (or `go build`) first and invoke the installed binary.
278
279setup flow:
280
2811. talk to [@BotFather](https://t.me/BotFather) on telegram, run `/newbot`, copy the token it gives you.
2822. run `zot telegram-bot setup` and paste the token when prompted.
2833. run `zot telegram-bot run` in the directory you want the agent to operate in.
2844. open your bot on telegram, send `/start`. the first user to do this claims the bridge (stored as `allowed_user_id`); every other user is rejected.
285
286from then on, any dm you send is forwarded to the agent as a user prompt. attached photos or image/* documents are downloaded and passed to vision-capable models. in-bot telegram commands: `/help`, `/status`, `/stop` (cancel the current turn). config lives in `$ZOT_HOME/bot.json` (mode 0600).
287
288bot mode respects the usual zot flags — `--provider`, `--model`, `--cwd`, `--reasoning`, `--continue`, `--no-session`, `--no-tools`, etc. run `zot tg run -c --model claude-opus-4-1` to resume the latest session on opus, for example.
289
290## development
291
292```bash
293make build     # build ./bin/zot
294make test      # go test -race ./...
295make lint      # go vet + gofmt check
296make fmt       # gofmt -w .
297make release   # cross-compile linux/darwin/windows × amd64/arm64
298```
299
300source layout:
301
302```
303cmd/zot/                      main()
304internal/agent/               cli wiring, arg parsing, system prompt, config
305internal/agent/modes/         interactive tui, print, json, dialogs
306internal/agent/tools/         read, write, edit, bash, sandbox
307internal/auth/                credential store, api-key probe, oauth, login server
308internal/core/                agent loop, sessions, cost tracking
309internal/provider/            anthropic + openai streaming clients, model catalog
310internal/tui/                 terminal raw-mode, input parser, editor, renderer, markdown, view
311```
312
313## license
314
315MIT