README.md RawHistoryFolder

1<div align="center">
2  <a href="https://www.zot.sh">
3    <img src="packages/provider/auth/assets/zot-logo.png" alt="zot coding agent harness" width="130" height="130" />
4  </a>
5</div>
6<br>
7<p align="center">
8  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
9  <img alt="Go 1.25+" src="https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white">
10  <img alt="30+ providers" src="https://img.shields.io/badge/providers-30+-34E2EA">
11</p>
12<p align="center">
13  <a href="https://www.zot.sh">zot.sh</a>
14</p>
15
16## What is it?
17
18Yet another coding agent harness, lightweight and written (vibe-slopped) in go.
19
20- one static binary.
21- built-in providers for Anthropic, OpenAI/Codex/Responses, Kimi, DeepSeek, Google Gemini/Vertex, GitHub Copilot, Bedrock, Azure OpenAI, OpenRouter, Groq, Cerebras, xAI, Together, Hugging Face, Mistral, Moonshot, Z.AI, Xiaomi, MiniMax, Fireworks, Vercel AI Gateway, OpenCode, Cloudflare AI, and Ollama/local models.
22- four tools (read, write, edit, bash).
23- three run modes (interactive tui, print, json).
24- built-in telegram bot.
25- extensions in any language via subprocess + json-rpc. None installed by default; opt in with `zot ext install` or `zot --ext`. See [docs/extensions.md](docs/extensions.md).
26- user and extension themes via JSON; see [docs/themes.md](docs/themes.md).
27- standing instructions via `AGENTS.md` files (global and per-project); see [Persistent instructions](#persistent-instructions-agentsmd).
28- reusable instructions via `SKILL.md` files; see [docs/skills.md](docs/skills.md).
29- portable agents from local directories, `.zot` files, or temporary public GitHub downloads; see [docs/zotfiles.md](docs/zotfiles.md).
30
31## Install
32
33### One-liner (macOS, Linux)
34
35```bash
36curl -fsSL https://www.zot.sh/install.sh | bash
37```
38
39Detects your OS and architecture, downloads the latest release from GitHub, verifies the SHA-256 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:
40
41```bash
42curl -fsSL https://www.zot.sh/install.sh | bash -s -- v0.0.1 ~/bin
43```
44
45### One-liner (Windows, PowerShell)
46
47```powershell
48iwr -useb https://www.zot.sh/install.ps1 | iex
49```
50
51Drops `zot.exe` into `$HOME\bin` and adds it to the user PATH if missing. Open a fresh terminal afterwards.
52
53### go install
54
55```bash
56go install github.com/patriceckhart/zot/cmd/zot@latest
57```
58
59The installed binary reports the tagged module version and supports `zot update`.
60
61### From source
62
63```bash
64git clone https://github.com/patriceckhart/zot
65cd zot
66make build        # produces ./bin/zot
67make install      # into $GOPATH/bin
68```
69
70### Prebuilt binaries
71
72Every release on the [releases page](https://github.com/patriceckhart/zot/releases) ships archives for Linux, macOS, and Windows on amd64 and arm64 (except windows/arm64), plus a `checksums.txt` file. Download, verify, `chmod +x`, and drop on your `$PATH`.
73
74## Authenticate
75
76The 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.
77
78### Credential lookup order
79
801. `--api-key` flag
812. provider-specific env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `KIMI_API_KEY`, `MOONSHOT_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY`, `CEREBRAS_API_KEY`, `TOGETHER_API_KEY`, `HF_TOKEN`, `ZAI_API_KEY`, `XIAOMI_API_KEY`, `MINIMAX_API_KEY`, `FIREWORKS_API_KEY`, `AI_GATEWAY_API_KEY`, `COPILOT_GITHUB_TOKEN`, `GITHUB_COPILOT_TOKEN`, and others for provider-specific backends)
823. `$ZOT_HOME/auth.json` (API key or OAuth token; mode 0600)
83
84`$ZOT_HOME` defaults to:
85- All platforms: `$XDG_STATE_HOME/zot` when `XDG_STATE_HOME` is set
86- macOS fallback: `~/Library/Application Support/zot`
87- Linux fallback: `~/.local/state/zot`
88- Windows fallback: `%LOCALAPPDATA%\zot`
89
90### API keys from commands
91
92To keep an API key in a password manager instead of `auth.json`, configure an `api_key_command` for the provider:
93
94```json
95{
96  "anthropic": {
97    "api_key_command": {
98      "program": "op",
99      "args": ["read", "op://Work/Anthropic/credential"],
100      "timeout_ms": 120000
101    }
102  }
103}
104```
105
106For a provider added through `models.json`, put the same credential object under `additional_api_key_creds` using its provider ID. `program` is executed directly, without a shell, so each argument must be a separate `args` entry. `timeout_ms` is optional and defaults to 120 seconds.
107
108zot runs the command only when that provider is selected, not while checking login status or refreshing model catalogs in the background. Successful output is cached in memory for the rest of the zot process and is never written to disk. The command must print one non-empty line to stdout; zot removes trailing CR/LF characters, limits output to 64 KiB, and does not include command output in errors. Saving a normal key through `/login` replaces the command configuration, and `/logout` removes it.
109
110Treat `auth.json` as executable configuration: anyone who can modify it can cause zot to run a program under your user account. zot does not interpret `!` prefixes or execute command strings through a shell.
111
112### `/login` flow
113
114Run `zot` and type `/login`. Pick one of two methods:
115
116- **API key**: a small local web server starts on `127.0.0.1:<free-port>`, your browser opens a form, you pick a provider from the full API-key provider list, paste the key, and zot saves it to `auth.json` if accepted. Providers with a lightweight model-list endpoint are probed before saving; provider backends that need extra project/account env vars are saved directly.
117- **Subscription**: use your Claude Pro/Max, ChatGPT Plus/Pro, Kimi Code, SuperGrok/X Premium, or GitHub Copilot subscription. DeepSeek and Google Gemini do **not** have a subscription login path. For those, use the API-key flow.
118  - Anthropic and OpenAI pin the browser callback to fixed provider-specific ports (`localhost:53692` for Anthropic, `localhost:1455` for OpenAI) because those are the only ports their auth servers will redirect to.
119  - Anthropic uses the Claude Code OAuth flow. Messages go to `api.anthropic.com` with a bearer token and the Claude Code identity headers.
120  - 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.
121  - Kimi uses the Kimi Code device-code OAuth flow. zot opens the verification URL, polls until you approve it in the browser, then sends messages to `api.kimi.com/coding/v1` with the Kimi Code identity headers.
122  - xAI uses a device-code OAuth flow. zot opens a prefilled authorization URL, polls for approval, and uses the resulting token with the xAI API.
123  - GitHub Copilot uses GitHub's device-code login flow. zot stores the GitHub access token and exchanges it for short-lived Copilot inference tokens on demand.
124
125> **Note on subscription login.** The OAuth client IDs used are the ones published in Anthropic's Claude Code CLI, OpenAI's Codex CLI, Kimi Code CLI, xAI's device flow, and GitHub Copilot's device-code flow. Reusing them from a third-party tool may be 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.
126
127### Token refresh
128
129OAuth access tokens are short-lived (Anthropic ~8h, OpenAI ~30d; Kimi, xAI, and GitHub Copilot also use refresh/exchange flows). zot refreshes or exchanges them automatically:
130
131- 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`, and `expiry` back to `auth.json`, and hands the fresh token to the client.
132- The telegram bridge additionally refreshes once per turn so a bot that runs for days keeps working without manual intervention.
133- 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.
134
135All data lives under `$ZOT_HOME`:
136
137```
138$ZOT_HOME/
139├── config.json         # last-used provider/model/theme, saved automatically
140├── auth.json           # api keys and oauth tokens (mode 0600)
141├── sessions/           # jsonl transcripts, one dir per cwd
142├── models-cache.json   # live /v1/models discovery cache (6h ttl)
143├── AGENTS.md           # optional: global instructions appended to the prompt
144├── SYSTEM.md           # optional: replaces the default system prompt
145├── skills/             # optional: user SKILL.md files
146├── themes/             # optional: user theme JSON files
147├── extensions/         # installed extensions, one dir per extension
148└── logs/               # app log files
149```
150
151Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and guidelines for every run. `--system-prompt` still wins per-invocation. Delete the file to revert to the default.
152
153## Persistent instructions (AGENTS.md)
154
155Use `AGENTS.md` to give zot standing instructions that layer **on top of** the default system prompt, without replacing it. This is the friendliest way to shape behavior (for example, taming local models that jump straight to code edits) because it adds guidance rather than taking over the base identity the way `SYSTEM.md` does.
156
157zot discovers `AGENTS.md` files automatically at startup and loads them in this order:
158
1591. `$ZOT_HOME/AGENTS.md` (global, machine-wide instructions that apply to every project).
1602. Every `AGENTS.md` from the filesystem root down to the current working directory. More specific (deeper) files may override earlier ones. This includes `~/AGENTS.md` when the working directory is inside your home directory.
161
162All discovered files are appended to the prompt in that order, so a global baseline can be refined per project. To list the active Zotfile agent, loaded context paths, extensions, and user-installed skills above the interactive transcript, enable **show loaded resources at startup** in `/settings`. The agent section appears only for `zot run`, the setting is off by default, built-in skills are omitted, and the displayed lists are not sent to the model or stored in the session transcript.
163
164For a general, non-project-specific instruction set, put your rules in `$ZOT_HOME/AGENTS.md`, for example:
165
166```markdown
167Treat questions and discussions as requests for explanation. Do not edit files or run tools unless explicitly asked to make a change. Ask before modifying code.
168```
169
170`AGENTS.md` vs the other mechanisms:
171
172| Mechanism | Scope | Effect |
173|---|---|---|
174| `$ZOT_HOME/AGENTS.md` | global, every run | appended to the default prompt |
175| `./AGENTS.md` (and parent dirs) | project | appended to the default prompt |
176| `$ZOT_HOME/SYSTEM.md` | global, every run | replaces the default prompt entirely |
177| `--append-system-prompt <text>` | single run | appends for one invocation (repeatable) |
178| `--system-prompt <text>` | single run | replaces the prompt for one invocation |
179
180> **Note:** zot does not read a `CLAUDE.md` instruction file. The only Claude-compatible thing it picks up is skills under `.claude/skills/`. If you are migrating from Claude Code, move that content into `AGENTS.md` (global or per-project) and zot will use it.
181
182## Changelog on update
183
184The first time you launch a newer zot binary, the TUI shows the GitHub release notes once in a dismissible overlay. Press any key to close. The version is recorded in `config.json`'s `last_changelog_shown` so the same release notes never reappear. Fresh installs don't see a changelog (no upgrade has happened yet). The fetch is best-effort: a network failure or a missing release page silently skips, with another attempt on the next launch.
185
186## Usage
187
188```bash
189zot                              # interactive tui
190zot "fix the failing test"       # tui, pre-filled prompt
191zot -p "list all go files"       # print final text, exit
192zot -p --stats stats.json "task" # print final text and write generation stats
193zot --json "refactor main.go"    # newline-delimited json events, exit
194zot --continue                   # resume the most recent session for this cwd
195zot --resume                     # pick a session to resume
196zot --list-models                # show supported models
197zot --help
198```
199
200Print-mode stats contain `provider`, `model`, `prompt_tokens`, `reasoning_tokens`, `generated_output_tokens`, and `elapsed_ms`. Counts cover all model turns triggered by the prompt, including tool loops. Prompt tokens include cache reads and writes. `reasoning_tokens` is `null` when the provider does not report a separate count; in that case `generated_output_tokens` is the provider's total output count and may include reasoning. Elapsed time covers the agent run, not startup and credential resolution. The file is written only after a successful run.
201
202## Flags
203
204| Flag | Description |
205|---|---|
206| `--provider <id>` | Pick the provider (for example `anthropic`, `openai`, `openai-codex`, `kimi`, `google`, `github-copilot`, `groq`, `openrouter`, `amazon-bedrock`, `ollama`; see Providers). |
207| `--model <id>` | Pick the model (see `--list-models`). |
208| `--api-key <key>` | Override the API key. |
209| `--base-url <url>` | Override the provider base URL (tests, self-hosted). |
210| `--insecure` | Skip TLS certificate verification for the explicit `--base-url` endpoint or a `baseUrl` defined for a user model in `models.json` (self-signed local/internal inference servers). Built-in providers, auth, and model discovery keep normal TLS verification. |
211| `--system-prompt <text>` | Replace the default system prompt for this run (also overrides `$ZOT_HOME/SYSTEM.md`). |
212| `--append-system-prompt <text>` | Append text to the system prompt (repeatable). |
213| `--reasoning off\|minimum\|low\|medium\|high\|xhigh\|max` | Set thinking level on supported models (default: off). `max` is a separate opt-in tier above `xhigh`. |
214| `--stats <path>` | With `-p`/`--print`, write generation statistics as JSON. |
215| `-c`, `--continue` | Resume the latest session for this cwd. |
216| `-r`, `--resume` | Pick a session to resume. |
217| `--session <path>` | Resume a specific session file. |
218| `--no-session` | Don't read or write session files. |
219| `--cwd <path>` | Use `<path>` as the working directory. |
220| `--no-tools` | Disable all tools. |
221| `--tools <csv>` | Only enable the listed tools. |
222| `--max-steps <n>` | Cap agent loop iterations (default 50). |
223| `-e`, `--ext <path>` | Load an extension from `<path>` for this run (repeatable; wins against installed extensions of the same name). |
224| `--no-ext` | Skip extension discovery for this run. `--ext` still works on top, so `--no-ext --ext ./x` runs only `x`. |
225| `--no-skill` | Disable all skills, including built-ins. No `skill` tool is registered and the system prompt has no skill manifest. |
226| `--no-yolo` | Confirm every tool call before it runs (interactive TUI only). A dialog shows the tool name and a one-line preview of its args, while edit calls show the proposed diff in the tool panel, with four choices: yes, yes-always-this-tool-this-session, yes-always-this-session, no. Press `/` while the dialog is focused to run a slash command first; closing its input or child dialog returns to the pending confirmation. Ignored with a stderr warning in print / json / rpc modes, where tools still run freely so scripts and automation keep working. |
227
228## Tools
229
230- `read`: read text files, or inline images (PNG, JPEG, GIF, WebP).
231- `write`: create or overwrite files, making parent directories as needed.
232- `edit`: one or more exact-match replacements in an existing file.
233- `bash`: run a command in the session cwd with merged stdout/stderr and a timeout. On Unix, zot uses `/bin/bash -c` when available, then `bash -c` from `PATH`, and falls back to POSIX `/bin/sh -c` when Bash is unavailable. On Windows, it uses `cmd /C`. macOS ships Bash 3.2 by default, so newer Bash features may be unavailable.
234
235When the sandbox is on (see `/jail`), all four tools refuse paths outside the session cwd.
236
237## Modes
238
239- **Interactive** (default): chat TUI with streaming output, spinner, cost meter, slash commands.
240- **Print**: `zot -p "prompt"` runs the agent to completion and writes only the final assistant text to stdout.
241- **Stream**: `zot --stream "prompt"` runs without the TUI and writes assistant text to stdout as it arrives. Tool activity goes to stderr.
242- **JSON**: `zot --json "prompt"` emits one JSON object per agent event to stdout, newline-delimited. The schema is documented in [docs/rpc.md](docs/rpc.md).
243- **RPC**: `zot rpc` runs as a long-lived child process; commands in on stdin, events and responses out on stdout, both as NDJSON. Designed for embedding zot in third-party apps written in any language. See [docs/rpc.md](docs/rpc.md) for the wire schema and `examples/rpc/{python,node,shell,go}` for working clients.
244
245## zotfile agents
246
247A zotfile packages an agent's instructions, skills, requirements, and enforced tool permissions as a shareable agent. Run one from a local directory, a packed `.zot` artifact, a short name, or directly from a public GitHub repository:
248
249```bash
250zot run ./my-agent
251zot run ./my-agent.zot
252zot run zot-maintenance --cwd /path/to/zot
253zot run https://github.com/patriceckhart/agents/zot-maintenance --cwd /path/to/zot
254```
255
256Short names resolve local-first: zot checks the matching directory and `.zot` archive before falling back to the official GitHub agent collection. For GitHub sources, zot downloads the repository archive into a temporary directory, validates and runs the selected agent, then removes the downloaded source when the command exits. Agent data, consent receipts, and sessions still persist under `$ZOT_HOME`. See [docs/zotfiles.md](docs/zotfiles.md) for authoring, permissions, packaging, and current limitations.
257
258## Embedding
259
260Two ways to drive zot from another program:
261
262- **Go in-process**: import `github.com/patriceckhart/zot/packages/agent/sdk`. One `Runtime` per project; `Prompt(ctx, text, images)` returns a channel of `Event`. Small example in `examples/sdk/`.
263- **Any language, out-of-process**: spawn `zot rpc` as a subprocess and exchange newline-delimited JSON over its stdin/stdout. Wire format and event schema in [docs/rpc.md](docs/rpc.md). Reference clients live under `examples/rpc/`.
264
265Both interfaces share the same event schema, so transcripts captured by one can be replayed through the other.
266
267## Slash commands
268
269Slash command names are case-insensitive in the TUI and messaging backends; arguments keep their original case. Type `/` in the TUI to open the autocomplete popup. Available commands:
270
271| Command | Description |
272|---|---|
273| `/help` | Show key bindings and commands. |
274| `/login` | Log in via API key or subscription (opens a dialog). |
275| `/logout [provider]` | Clear credentials for any logged-in provider, or all when omitted. `/logout openai-codex` clears ChatGPT/Codex subscription auth while preserving a public OpenAI API key; `/logout kimi` also disables fallback to the official Kimi Code CLI token until you log in to Kimi through zot again. |
276| `/model` | Pick a model from a list (or `/model <id>` to set directly). |
277| `/llama` | Connect to the configured llama.cpp router, load, unload, or remove cached models, and search/download GGUF models from Hugging Face with live progress. Shown after llama.cpp login is configured. |
278| `/sessions` | Resume a previous session for this directory. |
279| `/session` | Four ops on the current session: `export` to a portable `.zotsession` file, `import` one back in, `fork` from a past user message into a new branch, `tree` to switch between branches. Opens a picker without an argument; direct forms: `/session export [path]`, `/session import <path>`, `/session fork`, `/session tree`. Default export destination is `~/Downloads`. |
280| `/jump` | Scroll the chat to a previous turn (or `/jump <text>` to filter). |
281| `/btw` | Side chat with full context that doesn't add to the main thread. |
282| `/swarm` | Spawn, monitor, and chat with background subagents. Each runs in parallel with your main session and shares its working directory. |
283| `/skills` | List discovered skills (SKILL.md files) and preview their bodies. |
284| `/compact` | Summarize the transcript into one message to free up context. |
285| `/study` | Run the canned prompt "Read and understand everything in the current directory." so the agent has full project context before you start asking targeted questions. Pass a path — typed, drag-dropped, or selected via `@` — to target a specific file or directory instead: `/study [dir:packages/]`, `/study cmd/zot/main.go`. |
286| `/jail` | Confine tools to the current directory. |
287| `/unjail` | Allow tools to touch paths outside again. |
288| `/reload-ext` | Hot-reload all extensions (re-read manifests, respawn subprocesses, rebuild tool registry). |
289| `/telegram` | Connect, disconnect, or show status of the Telegram bridge (takes `connect` / `disconnect` / `status` as an optional argument; opens a picker without one). When connected, DMs from the paired user become prompts in the running session and the assistant's replies are mirrored back to Telegram. Alias: `/tg`. |
290| `/settings` | Change persistent settings, including inline images, auto-swarm, and the auto-compact threshold. Saved to `$ZOT_HOME/config.json`; takes effect immediately. |
291| `/clear` | Clear the chat transcript. |
292| `/exit` | Exit zot. |
293
294Extension-registered commands appear under a divider at the bottom of the popup, sorted by name.
295
296### Shell escape (`!command`)
297
298Type `!` followed by a command to run it directly without going through the model. Everything after the `!` is passed to the same shell the `bash` tool uses (`/bin/bash -c` when available on Unix, then `bash -c` from `PATH`, with POSIX `/bin/sh -c` as a fallback; `cmd /C` on Windows), runs in the session working directory, and honors the `/jail` sandbox. The command, merged output, and exit status are appended to the transcript as user context, so the model can use them on the next turn. Running the command does not itself start a model turn. A running `!command` shares the busy state with the agent: `esc` cancels it, and you cannot start one while a turn (or another shell escape) is in flight.
299
300### `/sessions`
301
302Shows previous sessions for the current working directory, newest first, with timestamp, model, message count, cost, and the first user prompt. Pick one with `up`/`down`, `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.
303
304### `/session`
305
306Four ops on the current session. `/session` alone opens a picker; each is also runnable directly.
307
308- **`/session export [path]`**. Writes the running transcript to a portable `.zotsession` file. Default destination is `~/Downloads/<timestamp>-<session-id>-<prompt-slug>.zotsession`. Pass a path to override; a directory is fine (a dated name is built inside), a bare name gets `.zotsession` appended. The meta's cwd is stripped on the way out so the recipient doesn't see your filesystem layout.
309
310  **What's included.** Only the main chat thread of the running session — messages, tool calls, tool results, compactions, and usage. **`/swarm` subagents are NOT included.** Their transcripts, unix-socket inboxes, and per-agent session files are all machine-local; a `.zotsession` is just a chat transcript and has no way to revive a unix socket on another box. If you want the conversation, copy it out of the dashboard manually.
311- **`/session import <path>`**. Copies a `.zotsession` file into `$ZOT_HOME/sessions/<cwd-hash>/` with a fresh id and the current cwd, then switches the running agent onto it. Imported sessions are first-class: they show up in `/sessions`, `/jump`, and the tree. Drag-drop paths in the editor are accepted (zot strips the surrounding quotes automatically).
312- **`/session fork`**. Opens a turn picker (same shape as `/jump`). Pick any past user message; zot copies every message up to and including that turn into a new session, records `parent` + `fork_point` in the new meta, and switches onto the branch. The parent session stays on disk. Use it to try a different question without polluting the original transcript, or to rewind after the agent went down the wrong path.
313- **`/session tree`**. Shows every session in the current cwd arranged by parent/child relationships, depth-first with indent per level. The current session is tagged `[current]`. Pick any entry to switch into it. Parentless sessions are roots; branches created via `/session fork` nest under whichever session they were forked from. Orphaned children (whose parent file was deleted) still show as roots so they stay discoverable.
314
315### `/jump`
316
317Opens 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. `up`/`down` 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.
318
319Jumping 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.
320
321### `/btw`
322
323Opens a side-chat overlay with the full main session as frozen context, so you can ask quick clarifying questions ("does asyncio.gather() catch exceptions?", "btw the bundle budget is 10MB", "what's the default fetch timeout?") without bloating the main thread.
324
325Each question runs an isolated agent turn against `system + main transcript + side-chat history so far`. The side chat has the same tools and guards as the main chat, including per-tool confirmation when `--no-yolo` is active. Responses, tool calls, and tool results stay in the overlay. When you press `esc` to close, **nothing** has been added to the main session and subsequent main-thread turns don't re-read any of the side-chat exchanges, keeping the running context window lean.
326
327```
328/btw                              # open the overlay, type questions interactively
329/btw does PUT replace the whole resource?
330```
331
332Inside the overlay: `enter` sends, `esc` cancels an in-flight call (or closes the overlay if idle), `ctrl+c` closes immediately. Side-chat exchanges never touch the transcript and aren't persisted to the session file.
333
334### `/swarm`
335
336Background subagents that run alongside your main session. Each one is a separate `zot` subprocess with its own model loop, its own persistent session file, and its own chat in the dashboard — but they all run in **the same working directory as the host**, so they see and edit the same files you do. Spawn one for a side task (“draft the migration”, “investigate this stack trace”, “write the test harness for module X”), keep going in the main thread, check in on it whenever you want.
337
338> **Agents edit the same files you do.** They use the same `read` / `write` / `edit` / `bash` tools as the main agent against the host's working directory. There's no per-agent worktree or branch. If you need parallel edits on isolated checkouts, set that up yourself with `git worktree` outside zot.
339
340```
341/swarm                            # open the dashboard
342/swarm new <task>                 # spawn an agent
343/swarm new --model gpt-5 <task>    # pin the new agent to a specific model
344/swarm logs <id>                  # jump straight into one agent's transcript
345/swarm send <id> <text>           # send a follow-up without opening the dashboard
346/swarm resume                     # pick a stopped agent to bring back
347/swarm resume <id>                # bring a specific agent back
348/swarm kill <id>                  # stop a running agent (its state stays)
349/swarm remove <id>                # delete the agent's session and state
350/swarm list                       # alias for opening the dashboard
351```
352
353**Dashboard (`/swarm` with no arg)** — a list of every agent for the current session, with status, age, and current activity. Keys:
354
355| Key | Action |
356|---|---|
357| `↑` / `↓` | Move cursor between rows. |
358| `enter` | Open the highlighted agent's transcript view. |
359| `n` | Spawn a new agent (opens an inline task editor; inherits the host's current model). |
360| `p` | One-off prompt editor for the selected row (without entering the transcript). |
361| `R` | Resume a stopped agent in place. |
362| `k` | Kill the selected running agent. Its session and state stay so you can resume it later. |
363| `r` | Remove the selected agent entirely (session + meta gone). |
364| `esc` | Close the dashboard. |
365
366**Inside an agent's transcript** — a chat overlay with an always-on inline composer at the bottom. The conversation flows above it; type and `enter` to send a follow-up. The view auto-follows streaming output and shows an inline spinner with the agent's current activity (`thinking`, `tool: edit_file`, etc.) while it's busy. `esc` returns to the dashboard.
367
368**Switching the spawn model from inside the editor** — while composing a task in the `n`-prompt, type `/model` on its own line and `enter`. The standard `/model` picker pops up; pick a model, the picker closes, and the editor reopens with your typed task intact and the new model pinned for the spawn.
369
370**Session scoping** — each agent is stamped with the host session that spawned it and only shows up in that session's dashboard. Swap sessions with `/sessions` and the dashboard re-narrows accordingly. Agents from other sessions keep running in the background and reappear when you switch back.
371
372**Persistence across zot restarts** — every spawn writes a `meta.json` next to its event log and session file under `$ZOT_HOME/swarm/agents/<id>/`. On the next `zot` launch they show up in the dashboard as **detached**; press `R` (or `/swarm resume <id>`) to bring one back. Resumed agents reattach to the same session and inbox socket, so the conversation continues from where it left off.
373
374**Where state lives** — everything per-agent (session file, events log, inbox socket, meta) lives under `$ZOT_HOME/swarm/agents/<id>/`. The agent's actual code edits land directly in your repo; track them with normal `git status` / `git diff`.
375
376**`/session export` does NOT bundle subagents.** A `.zotsession` is just the main chat transcript; per-agent state (session file, unix-socket inbox) is machine-local and doesn't round-trip through a JSONL file. To share what an agent said, copy it out of the transcript view manually.
377
378**Auto-swarm.** With `/settings` -> auto-swarm on, the main agent gets a built-in `swarm_spawn` tool and a system-prompt nudge to use it. It can then fork sub-agents on its own when a request naturally splits into independent parallel work ("implement A and B", "investigate three files"). Each spawn returns the sub-agent id immediately and the main turn keeps going. When every sub-agent the agent spawned in that batch finishes its initial task, zot injects one `[auto-swarm update]` message back into the main chat recapping each agent's status, task, and complete final response. If an agent produced no assistant response, zot includes a truncated transcript tail for diagnostics instead. The main agent then writes a short follow-up summary referencing the agents by id. Off by default; toggle from `/settings`.
379
380### `/settings`
381
382Opens a dialog with every persistent setting. `up`/`down` to navigate, `enter` or `space` to change the selected row, `esc` to close (rows that open a sub-view, like model shortcuts, use `esc` to go back one level first). Changes are written to `$ZOT_HOME/config.json` and take effect on the next turn (no restart needed). Current settings:
383
384- **render images when supported** — draw screenshots / `read`-returned images inline using the terminal's image protocol, or fall back to a text placeholder. Auto-detected from `TERM_PROGRAM`; the toggle overrides the detection. The row is greyed out and forced off on terminals that don't speak any image protocol.
385- **auto-swarm** — let the main agent spawn background sub-agents in parallel via a built-in `swarm_spawn` tool. Off by default. When on, the tool is registered with the running agent, the system prompt gains a short addendum telling the model to delegate independent sub-tasks proactively, and zot watches every sub-agent the main agent spawns. As soon as the last sub-agent in a batch finishes its initial task, an `[auto-swarm update]` message is injected back into the chat with each agent's status / task / transcript tail, so the main agent can summarise the collective outcome. Flipping off mid-session removes the tool from the live agent and strips the addendum on the next turn — the model stops trying to delegate. See `/swarm` for the dashboard that lets you monitor, message, kill, or remove the spawned agents.
386- **auto-compact threshold** — choose `off`, `70%`, `80%`, `85%` (default), or `90%` of the model's advertised context window. The selected percentage controls automatic compaction before and after interactive turns and persists as `auto_compact_threshold`. `off` disables percentage-based triggers but keeps manual `/compact` and automatic recovery from context-window and payload-too-large responses.
387- **jail new sessions by default**: start every new agent with tools confined to its working directory. Off by default. The setting applies to interactive, print, JSON, RPC, and background-agent runs, persists as `jail_by_default`, and immediately updates the current interactive session. `/jail` and `/unjail` remain session-scoped overrides and do not change this default.
388- **compact transcript rendering**: reduce visual chrome in the chat transcript. Tool calls render as a quiet header plus indented output instead of a bordered box, and sent messages render without padded background bubbles. Off by default. Changes apply immediately and persist to `config.json` as `compact_mode`.
389- **show loaded resources at startup**: list the active Zotfile agent (for `zot run`), loaded `AGENTS.md` paths, extensions, and user-installed skills in compact sections above the transcript. Built-in skills are omitted. Off by default. Changes apply immediately and persist to `config.json` as `show_instructions_at_startup`.
390- **TUI settings**: opens a sub-view for input layout and status placement. **Input style** can be `plain` (default prompt line), `lines` (separator lines above and below the input), or `block` (a user-bubble-style input block). **Status position** places model, usage, and working-directory information above or below the input. **Working spinner position** places the busy spinner above or below the input. Changes apply immediately and persist to `config.json` as `tui_input_style`, `tui_status_position`, and `tui_working_position` (`above_input` or `below_input` for the position fields).
391- **thinking level**: choose reasoning for supported models: off, minimum, low, medium, high, xhigh, or max. The `max` tier is opt-in and sent natively to GPT-5.6 and adaptive-thinking Claude models; unsupported backends clamp it to their highest accepted effort. The change is persisted to `config.json` and applied to the next model call.
392- **color theme** — choose the built-in auto/dark/light theme or any JSON theme discovered under `$ZOT_HOME/themes` or a loaded extension. Theme files can override any subset of UI colors, syntax colors, and spinner frames/messages. Changes apply immediately; if a selected theme file is deleted, zot resets to auto. See [docs/themes.md](docs/themes.md).
393- **model shortcuts** — opens a sub-view with nine slots (`model 1` ... `model 9`). `enter` on a slot opens the same `/model` selector and binds the chosen provider/model to that slot; `backspace` clears a slot. Once assigned, press `Ctrl+1` ... `Ctrl+9` from the editor to switch the active model instantly (the same cross-provider swap `/model` performs, transcript and cost carried over). Assigning a shortcut does not change the current model. Shortcuts are skipped while a turn is running.
394
395### `/skills`
396
397Opens a picker listing every discovered SKILL.md file, built-ins hidden. Each row shows the skill name, source, and description. `enter` opens the body inline (scrollable with `up`/`down`/`pgup`/`pgdn`); `esc` goes back. Re-runs discovery each time it opens, so edits to a SKILL.md during a session are reflected immediately.
398
399### `/compact`
400
401Sends 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. The status bar's context meter resets. Use it when the context meter creeps past ~80%.
402
403zot also auto-compacts in the background: after any turn that reaches the configured context threshold, the agent kicks off a condense pass on its own. Choose `off`, `70%`, `80%`, `85%` (default), or `90%` under `/settings` → **auto-compact threshold**. 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. Turning the percentage trigger off does not disable automatic compaction and retry after a context-window or payload-too-large response.
404
405### `/jail`
406
407Enforces a sandbox rooted at the cwd shown in the status bar. `read`, `write`, and `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=/`, and similar) and rejects shell arguments or redirections that point outside the sandbox. The status bar shows `jailed, ~/your/cwd` while active. Enable **jail new sessions by default** in `/settings` to persist this behavior across launches; `/unjail` then unlocks only the current session.
408
409This is a guardrail against accidents, not a hard security boundary. If you need real isolation, run zot under docker or a proper sandbox.
410
411## Sessions
412
413Every 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. Empty sessions (the user exited without prompting) are deleted on close so the list stays tidy.
414
415## Providers
416
417zot's built-in provider catalog includes:
418
419- **Subscription-capable**: Anthropic Claude Pro/Max (`anthropic`), OpenAI Codex / ChatGPT Plus/Pro (`openai-codex`), Kimi Code (`kimi`), SuperGrok/X Premium (`xai`), GitHub Copilot (`github-copilot`).
420- **Direct API providers**: Anthropic, OpenAI Chat Completions, OpenAI Responses, DeepSeek, Google Gemini, Kimi/Moonshot, Moonshot CN, Groq, Cerebras, xAI, Together AI, Hugging Face Router, OpenRouter, Mistral, Z.AI, Xiaomi/MiMo token-plan regions, MiniMax global/CN, Fireworks, Vercel AI Gateway, OpenCode/OpenCode Go.
421- **Cloud/platform providers**: Amazon Bedrock, Google Vertex AI, Azure OpenAI, Cloudflare Workers AI, Cloudflare AI Gateway.
422- **Local/compatible**: Ollama, llama.cpp router mode, and OpenAI-compatible local endpoints via `--base-url`.
423
424Use `/login` to store API keys or subscription credentials. `/model` only shows models from providers that are currently available from env vars, `auth.json`, Kimi CLI fallback, local Ollama, or a configured llama.cpp router.
425
426## Models
427
428`--list-models` or the `/model` picker shows the full catalog across all built-in providers. Three sources:
429
430- **Catalog**: models baked into zot, covering Claude, GPT/Codex, Gemini/Gemma, Kimi/Moonshot, DeepSeek, Groq-hosted Llama/Gemma/Compound, OpenRouter-routed models, Bedrock model ids, Vertex model ids, Azure OpenAI deployments, Copilot models, and other provider-specific catalog entries.
431- **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).
432- **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.
433
434The context meter in the status line uses the model's advertised context window to show how much of it your last turn consumed.
435
436### Model fallback (rescue)
437
438When a turn fails because of a recoverable provider error — expired token (`401`), permission denied (`403`), rate limit (`429`), provider outage (`502`/`503`/`504`), or a transient network failure — zot opens a **rescue** picker over the chat instead of just painting a red banner.
439
440The picker is the same vertical list / fuzzy filter UI as `/model`, but it only shows models from providers you're currently logged in to (env vars, `auth.json`, Kimi CLI fallback, ollama). The failed model is excluded. Press `↑`/`↓` to choose, `enter` to retry the **same prompt** on the new model, `esc` to dismiss.
441
442Before the actual provider request fires, the OpenAI / Anthropic / Kimi / DeepSeek / Google / OpenAI-Codex clients also do up to two silent retries with short backoff (250ms, 750ms) on `502`/`503`/`504` and connection-reset / EOF-before-headers errors. Most edge-proxy blips disappear without you ever seeing the rescue picker.
443
444A rescue retry always **drops launch-time `--api-key` and `--base-url`** before rebuilding the agent. Those overrides are usually the reason the rescue triggered (bad key, typo'd base URL, corporate gateway only valid for the originally-picked provider), so the retry re-resolves credentials from env vars / `auth.json` / provider defaults instead. Use `/model` if you want overrides to stick.
445
446No configuration is required — the candidate list is built dynamically from your active credentials. Bad-request / context-length / serialization errors are NOT routed to the rescue picker, because switching models won't fix them; those still surface as a normal error.
447
448### Custom models
449
450Place a `models.json` in `$ZOT_HOME` (`$XDG_STATE_HOME/zot/` when set, otherwise the platform default above) to add models that aren't in the baked-in catalog or to override existing entries:
451
452```json
453{
454  "providers": {
455    "openai": {
456      "models": [
457        {
458          "id": "gpt-5.5",
459          "name": "GPT-5.5",
460          "reasoning": true,
461          "contextWindow": 400000,
462          "maxTokens": 128000
463        }
464      ]
465    }
466  }
467}
468```
469
470Supported fields per model: `id` (required), `name`, `reasoning`, `contextWindow`, `maxTokens`, `baseUrl`, `priceInput`, `priceOutput`, `priceCacheRead`, `priceCacheWrite`.
471
472Provider keys are normalized: `openai-codex` and `openai-responses` map to `openai`, `anthropic-messages` maps to `anthropic`, `moonshot`, `moonshot-ai`, and `kimi-code` map to `kimi`, and `deepseek-chat` and `deepseek-ai` map to `deepseek`. Built-in provider ids such as `groq`, `openrouter`, `github-copilot`, `amazon-bedrock`, `google-vertex`, `azure-openai-responses`, `fireworks`, `vercel-ai-gateway`, `mistral`, and `xai` can also be used directly.
473
474User-defined models show `source: user` in `--list-models` and take precedence over both the baked-in catalog and live-discovered models. Adding a `models.json` does not hide the built-in catalog; entries are merged on top of it. Missing or invalid files are silently ignored.
475
476#### Custom providers
477
478A top-level provider key that is not a built-in id defines a custom provider. Give it a provider-level `baseUrl` and an `api` wire format (`openai` for OpenAI-compatible Chat Completions, the default, `openai-responses` for the OpenAI Responses API, or `anthropic` for the Anthropic Messages API). A model-level `baseUrl` overrides the provider-level one for that model; an unknown `api` value falls back to `openai` with a warning.
479
480```json
481{
482  "providers": {
483    "my-company": {
484      "baseUrl": "https://llm.mycompany.com/v1",
485      "api": "openai",
486      "models": [
487        { "id": "company-llm-v2", "name": "Company LLM v2" }
488      ]
489    }
490  }
491}
492```
493
494Custom providers are first-class: they appear in `--list-models`, `/model`, and `/login`. `models.json` never stores secrets. Supply the key through `/login`, `--api-key`, or a derived environment variable in upper snake case (so `my-company` reads `MY_COMPANY_API_KEY`). Because many self-hosted gateways do not expose a model-list endpoint, custom provider keys are accepted and stored without a verification probe; an invalid key surfaces on the first model call.
495
496To retrieve this custom provider's key from a password manager, add a matching entry to `$ZOT_HOME/auth.json`:
497
498```json
499{
500  "additional_api_key_creds": {
501    "my-company": {
502      "api_key_command": {
503        "program": "op",
504        "args": ["read", "op://Work/OpenAI/credential"],
505        "timeout_ms": 120000
506      }
507    }
508  }
509}
510```
511
512The provider IDs in `models.json` and `auth.json` must match. Then select the custom model directly:
513
514```bash
515zot --provider my-company --model company-llm-v2
516```
517
518### Kimi Code
519
520zot has built-in Kimi support through the Kimi Coding endpoint and Moonshot's OpenAI-compatible chat API.
521
522```bash
523zot --provider kimi
524```
525
526By default this uses:
527
528- model: `kimi-for-coding`
529- base URL: `https://api.kimi.com/coding/v1`
530
531Credential lookup order for Kimi:
532
5331. `--api-key`
5342. `KIMI_API_KEY`
5353. `MOONSHOT_API_KEY`
5364. `$ZOT_HOME/auth.json`
5375. the official Kimi Code CLI token at `~/.kimi/credentials/kimi-code.json`, unless disabled by `/logout kimi`
538
539Use `/login` for either API-key login or Kimi Code subscription login. The subscription flow uses Kimi Code's device-code OAuth flow: zot opens the verification URL, waits for browser approval, stores the token in `auth.json`, and refreshes it automatically.
540
541For direct Moonshot API keys or a custom compatible endpoint:
542
543```bash
544zot --provider kimi --model kimi-k2-0905-preview --base-url https://api.moonshot.ai/v1 --api-key "$KIMI_API_KEY"
545```
546
547Kimi K3 is built in as `kimi/k3`, `moonshotai/kimi-k3`, `moonshotai-cn/kimi-k3`, `opencode-go/kimi-k3`, `openrouter/moonshotai/kimi-k3`, and `vercel-ai-gateway/moonshotai/kimi-k3`. Its output limit is 131,072 tokens on every built-in route.
548
549You can add additional Kimi/Moonshot model IDs to `models.json` under the `kimi` provider.
550
551### xAI
552
553xAI supports either `XAI_API_KEY` or `/login` subscription authentication. The subscription option is labeled `Sign in with SuperGrok or X Premium`, opens a prefilled device-authorization URL, and refreshes the stored token automatically. The default xAI model is `grok-4.5`, sent through the Responses API.
554
555### DeepSeek
556
557zot has built-in DeepSeek support through DeepSeek's OpenAI-compatible chat API.
558
559```bash
560zot --provider deepseek
561```
562
563By default this uses:
564
565- model: `deepseek-v4-pro`
566- base URL: `https://api.deepseek.com/v1`
567
568Catalog ships with `deepseek-v4-pro` (reasoning) and `deepseek-v4-flash`. These are exactly the IDs returned by `GET https://api.deepseek.com/models` today. You can add additional model IDs to `models.json` under the `deepseek` provider.
569
570Credential lookup order for DeepSeek:
571
5721. `--api-key`
5732. `DEEPSEEK_API_KEY`
5743. `$ZOT_HOME/auth.json`
575
576Use `/login` and pick **api key** to paste a DeepSeek key. zot probes `/v1/models` once and stores the key under `deepseek` in `auth.json`.
577
578> **Auth model: API key only.** DeepSeek does not offer a subscription OAuth flow. The `/login subscription` step lists only Anthropic, OpenAI, and Kimi; DeepSeek shows up only under `/login → api key`.
579
580> **Text only at the wire level.** DeepSeek's chat-completions endpoint currently rejects the multimodal content schema (`unknown variant image_url, expected text`). When the active provider is `deepseek`, zot silently drops `ImageBlock` parts from outgoing user/tool messages and keeps only the text. Switching back to a vision-capable model (Claude, GPT-4o/5, Gemini) re-sends the image normally because the session file still stores it.
581
582For a custom-compatible endpoint (mirror, gateway, self-host):
583
584```bash
585zot --provider deepseek --base-url https://my-deepseek-mirror.example.com/v1 --api-key "$DEEPSEEK_API_KEY"
586```
587
588### Google Gemini
589
590zot has built-in Google Gemini support through the [AI Studio Generative Language API](https://aistudio.google.com/).
591
592```bash
593zot --provider google
594```
595
596By default this uses:
597
598- model: `gemini-2.5-pro`
599- base URL: `https://generativelanguage.googleapis.com`
600
601Catalog ships with `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`, and `gemini-2.0-flash-lite`. Live discovery against `/v1beta/models` adds anything else your key can see.
602
603Credential lookup order for Google:
604
6051. `--api-key`
6062. `GEMINI_API_KEY`
6073. `GOOGLE_API_KEY`
6084. `$ZOT_HOME/auth.json`
609
610Use `/login` and pick **api key** to paste an AI Studio key. zot probes `/v1beta/models` once and stores the key under `google` in `auth.json`.
611
612> **Auth model: API key only (this provider).** Google does not issue OAuth tokens for consumer Gemini Advanced / Google One AI Premium subscriptions, so there is no "log in with your Google subscription" flow. The `/login subscription` step quietly downgrades to the api-key form when you pick Google so you don't end up in a dead end. If you need OAuth/service-account auth instead of an API key, use the `google-vertex` provider below.
613
614> **Free-tier rate limits.** AI Studio's free tier has tight per-minute and per-day caps that vary by model: `gemini-2.5-pro` is the strictest (a few requests per minute, ~50 per day), Flash and Flash-Lite are far more generous. If a Pro turn 429s with `"You exceeded your current quota"` while Flash on the same key still works, you've hit the Pro free-tier RPD. Either switch to Flash for agent loops, or [enable billing](https://aistudio.google.com/app/apikey) on your AI Studio project to flip the same key from free to pay-as-you-go pricing (`$1.25/M` input, `$10/M` output for Pro).
615
616Reasoning levels (`--reasoning off|minimum|low|medium|high|xhigh|max`, also configurable in `/settings` as **thinking level**) map differently per generation. `max` is a distinct opt-in tier above `xhigh`. GPT-5.6 and adaptive-thinking Claude models receive native `max`; unsupported providers clamp it to their highest accepted effort. Budget-based providers retain their provider/model caps. Gemini 3.x uses the `thinkingLevel` enum (`MINIMAL`/`LOW`/`MEDIUM`/`HIGH`), with Gemini-3-Pro pinned to `LOW` minimum and `HIGH` for any medium-or-higher request. `off` sends no reasoning config. Gemini 2.0 models have no thinking config.
617
618You can add additional Gemini model IDs to `models.json` under the `google` provider.
619
620### Gemini Enterprise Agent Platform (formerly Google Vertex AI)
621
622zot also has built-in support for [Gemini Enterprise Agent Platform](https://cloud.google.com/products/gemini-enterprise-agent-platform), Google's enterprise/GCP-hosted Gemini endpoint. Unlike the AI Studio `google` provider above, the `google-vertex` provider supports a Google Cloud API key plus `service_account` and `authorized_user` credential files. It does not support consumer Google login or the complete ADC credential chain, such as metadata-server and workload-identity credentials.
623
624```bash
625zot --provider google-vertex
626```
627
628Required configuration (env vars, read at construction time):
629
630- `GOOGLE_CLOUD_PROJECT` — required, your GCP project id.
631- `GOOGLE_CLOUD_LOCATION` — optional, defaults to `us-central1`.
632
633Credential lookup order for Vertex:
634
6351. `GOOGLE_CLOUD_API_KEY`: simplest option. An API key created in the GCP console is sent as `x-goog-api-key`, without a token exchange.
6362. `GOOGLE_APPLICATION_CREDENTIALS`: path to a supported credential JSON file.
6373. **Default ADC file**: if neither of the above is set, zot checks the file written by `gcloud auth application-default login`. This is `~/.config/gcloud/application_default_credentials.json` on Unix systems and `%APPDATA%\gcloud\application_default_credentials.json` on Windows.
638
639Two credential file shapes are supported:
640
641- `type: "service_account"`: zot signs a JWT with the private key and exchanges it for a short-lived access token.
642- `type: "authorized_user"`: zot exchanges the stored client ID, client secret, and refresh token for a short-lived access token.
643
644Access tokens are cached in memory and refreshed on demand.
645
646If none of these are available, zot errors with `vertex: no auth — set GOOGLE_CLOUD_API_KEY or GOOGLE_APPLICATION_CREDENTIALS`.
647
648### Local models with ollama
649
650zot works with [ollama](https://ollama.com) out of the box. Ollama serves an OpenAI-compatible API locally, so any model you have pulled works with zot.
651
652Quick start:
653
654```bash
655ollama pull qwen3.5:4b
656zot --provider ollama --model qwen3.5:4b
657```
658
659That's it. No API key needed for local models. zot defaults to `http://localhost:11434`.
660
661For a remote ollama instance or one behind auth:
662
663```bash
664zot --provider ollama --model llama3 --base-url https://my-server.com/v1 --api-key my-token
665```
666
667You can also add models to your `models.json` so you don't need flags every time:
668
669```json
670{
671  "providers": {
672    "ollama": {
673      "models": [
674        {
675          "id": "qwen3.5:4b",
676          "name": "Qwen 3.5 4B",
677          "contextWindow": 32768,
678          "maxTokens": 8192
679        }
680      ]
681    }
682  }
683}
684```
685
686The `ollama` provider uses the OpenAI chat completions protocol internally, so it also works with any OpenAI-compatible server (vLLM, LM Studio, LocalAI, etc.).
687
688### Local models with llama.cpp router mode
689
690zot can connect to a recent [llama.cpp](https://github.com/ggml-org/llama.cpp) router, manage its GGUF files, and use loaded models through the router's OpenAI-compatible inference API. This is separate from Ollama. An Ollama server normally listens on port `11434` and should use zot's `ollama` provider instead.
691
692Install or update llama.cpp. On macOS with Homebrew:
693
694```bash
695brew install llama.cpp
696# or, when already installed
697brew upgrade llama.cpp
698```
699
700Create a directory for GGUF files and start `llama-server` without `--model`, `-m`, or `-hf`. Supplying one of those options starts a single model rather than the router API zot needs.
701
702```bash
703mkdir -p ~/llama-models
704
705llama-server \
706  --models-dir ~/llama-models \
707  --no-models-autoload \
708  --jinja \
709  --host 127.0.0.1 \
710  --port 8080 \
711  -ngl 999 \
712  -c 32768
713```
714
715`--no-models-autoload` leaves load decisions to `/llama`. `--jinja` enables model chat templates and improves tool-call compatibility. `-ngl 999` requests maximum GPU offload, while `-c 32768` limits each loaded model to a 32K context. Adjust these values for your hardware.
716
717Confirm that router mode is active before configuring zot:
718
719```bash
720curl http://127.0.0.1:8080/health
721curl http://127.0.0.1:8080/models
722```
723
724The models request must return JSON with a `data` array. A 404 usually means the server is outdated, running on a different port, or was started in single-model mode.
725
726In zot, run `/login`, choose **api key**, and select **llama.cpp**. Enter `http://127.0.0.1:8080` as the router URL and leave the API key empty for a local-only server. Do not enter `/v1`; zot derives the inference URL itself. The saved URL and optional key live in `$ZOT_HOME/auth.json`.
727
728You can configure the same connection through environment variables:
729
730```bash
731export LLAMA_BASE_URL=http://127.0.0.1:8080
732export LLAMA_API_KEY=optional-secret
733```
734
735When using a key, launch the server with the matching `--api-key` value. Keep `--host 127.0.0.1` unless remote clients must reach the router.
736
737Run `/llama` to:
738
739- inspect the router's current model states
740- search Hugging Face for GGUF repositories
741- choose a quantization and download it with byte progress
742- explicitly load or unload a model
743- press `d` to ask the router to remove a downloaded cache model after confirmation
744
745Models discovered through `--models-dir` or a preset cannot be removed by zot. Delete those files from their configured source instead. The router removes the selected GGUF from its Hugging Face cache, but some llama.cpp versions retain shared repository artifacts such as `mmproj` files. Remove the repository's cache directory manually if those artifacts are no longer needed. Hugging Face search uses `HF_TOKEN` when available. Gated repositories require prior access approval, and the `llama-server` process also needs an authorized `HF_TOKEN` because the server performs the download.
746
747Opening `/model` refreshes the router and lists every loaded model under provider `llama.cpp`. Unloaded models are intentionally omitted because they cannot answer inference requests. Load them through `/llama` first, then select them through `/model`.
748
749A model installed through Ollama is kept in Ollama's internal storage and is not automatically available as a llama.cpp GGUF file. Download a GGUF copy through `/llama` or place GGUF files in `~/llama-models`, then restart the router so it discovers files added manually.
750
751## Inline images
752
753When a tool returns an image (for example `read` on a PNG), zot renders it inline on terminals that support it: **Ghostty**, **Kitty**, **iTerm2**, **WezTerm**. On other terminals you see a text placeholder with MIME type, pixel dimensions, and byte size. Control with the `ZOT_INLINE_IMAGES` env var:
754
755| Value | Effect |
756|---|---|
757| unset (default) | Auto-detect based on `TERM_PROGRAM`; use the text placeholder inside VS Code and Herdr. |
758| `iterm`, `iterm2` | Force the iTerm2 OSC 1337 protocol. |
759| `kitty` | Force the Kitty graphics protocol. |
760| `off`, `none` | Always use the text placeholder. |
761
762Herdr's Kitty graphics support is currently experimental, so zot does not enable inline images there automatically. After enabling `experimental.kitty_graphics` in Herdr, set `ZOT_INLINE_IMAGES=kitty` to opt in.
763
764Frames 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.
765
766## Tool rendering
767
768By default each tool call (bash, read, write, edit) renders inside a bordered panel — a `┌─ header ─┐`, `│`-prefixed body rows, and a `└─┘` footer. On a screen with many calls the borders can read as busy, so zot also offers a **flat** mode: a single quiet header line per call (`▌ bash …`) with indented, border-free output. Same information — tool name, arg summary, streamed output, the `... (N more lines, ctrl+o to expand)` truncation — just no frame.
769
770Set the `tool_render` key in `$ZOT_HOME/config.json`:
771
772```json
773{
774  "tool_render": "flat"
775}
776```
777
778| Value | Effect |
779|---|---|
780| unset / `"box"` (default) | Each tool call is wrapped in a bordered panel. |
781| `"flat"` | Boxless: a quiet header line plus indented output. |
782
783The `ZOT_FLAT_TOOLS` env var overrides the config for a single run, which is handy for trying it without editing the file:
784
785| Value | Effect |
786|---|---|
787| `1`, `true`, `yes`, `on`, `flat` | Force flat rendering. |
788| `0`, `false`, `no`, `off`, `box` | Force the bordered panel. |
789| unset | Fall back to the `tool_render` config key. |
790
791```sh
792ZOT_FLAT_TOOLS=1 zot   # flat, just this run
793ZOT_FLAT_TOOLS=0 zot   # boxes, even if config.json says "flat"
794```
795
796Either way, theme colors still drive the rendering (the header uses your accent/foreground, output uses the tool-output color) and `ctrl+o` still expands a truncated result.
797
798### Tool arg width
799
800The header line for a tool call shows the tool name plus a one-line summary of its primary argument — a `path`, a `command`, or a query. That summary is truncated to 60 cells by default (`web_answer What is the best architecture to implement resilience wit...`). On a wide terminal that can clip long queries more than you'd like, so set the `ZOT_TOOL_ARG_WIDTH` env var to raise (or lower) the limit:
801
802```sh
803ZOT_TOOL_ARG_WIDTH=120 zot   # allow up to 120 cells before truncating
804```
805
806| Value | Effect |
807|---|---|
808| unset (default) | Truncate the arg summary at 60 cells. |
809| integer in `[20, 500]` | Truncate at that many cells instead. |
810| anything else | Ignored; falls back to the 60-cell default. |
811
812## Compact input
813
814By default a message you send renders as a padded, background-tinted bubble: a blank tinted row above and below the text, with a `▌` accent bar down the left. So even a one-line prompt occupies three rows. Set `compact_input` to collapse it to a single quiet `▌ your text` gutter line per wrapped row — no padding rows, no background tint.
815
816```json
817{
818  "compact_input": true
819}
820```
821
822| Value | Effect |
823|---|---|
824| unset / `false` (default) | Padded, background-tinted user bubble. |
825| `true` | One quiet gutter line per wrapped row. |
826
827The `ZOT_COMPACT_INPUT` env var overrides the config for a single run (`1`/`true`/`on`/`compact` force compact; `0`/`false`/`off`/`bubble` force the bubble):
828
829```sh
830ZOT_COMPACT_INPUT=1 zot   # compact, just this run
831```
832
833## Queued messages
834
835You 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` cancels the active turn and drops the queue so a runaway turn doesn't flood you with stale follow-ups; `ctrl+c` while busy arms the exit hint instead of interrupting, a second `ctrl+c` within two seconds exits zot.
836
837To recover the most recently queued message back into the editor (to tweak it before it runs), press `Option+↑`. In VS Code's integrated terminal that chord doesn't survive xterm.js's macOS key handling — use `Option+Shift+↑` there. zot's hint line under the sliding-in queue adapts automatically based on `$TERM_PROGRAM`.
838
839Slash commands also work while the agent is busy. Read-only ones (`/help`, `/jump`, `/btw`, `/sessions`, `/skills`, `/settings`, `/jail`, `/unjail`, `/exit`) take effect immediately. Destructive ones (`/clear`, `/compact`, `/login`, `/logout`, `/model`, `/reload-ext`) cancel the active turn first and then run.
840
841
842## Keys (interactive mode)
843
844### Input
845
846| Key | Action |
847|---|---|
848| `enter` | Submit (queued if the agent is busy). |
849| `alt+enter` | Newline. |
850| `tab` | Complete the selected slash command. |
851| `esc` | Cancel the current turn (while busy); clear input (while idle). |
852| `ctrl+c` | Clear the input and queue (while idle) or arm the exit hint (while busy). Press again within 2s to exit. Use `esc` to cancel a running turn. |
853| `ctrl+d` | Exit on empty input. |
854| `ctrl+l` | Redraw the screen. |
855| `ctrl+v` | Paste clipboard text into the focused chat, side chat, dialog, filter, or credential input. On Linux this uses `wl-paste`, `xclip`, or `xsel`; terminal-native bracketed paste remains available without those commands. In the main chat on macOS, image-only clipboard content is saved as a temporary PNG and attached to the next prompt. |
856| `ctrl+o` | Expand or collapse long tool results (read, write, edit, bash outputs over ~12 lines). |
857| `ctrl+1` ... `ctrl+9` | Switch to the model bound to that quick-model slot (configured in `/settings` -> model shortcuts). No-op while a turn is running. |
858| `@` | Open the file picker. Browse files and directories in the working directory. |
859
860### File picker (`@`)
861
862| Key | Action |
863|---|---|
864| `@` | Open the file picker (type after a space or at the start of input). |
865| `up`, `down` | Navigate the file list. |
866| `right` | Open the selected directory. |
867| `left` | Go back to the parent directory. |
868| `enter` | Select the file or directory and insert it as a chip (`[file:name]` or `[dir:name/]`). |
869| `esc` | Close the file picker. |
870
871Type `@` followed by a filter string to narrow the list (e.g. `@read` shows only entries containing "read"). Selected files are inserted as compact chips that expand to the full path on submit. Dragged-and-dropped files and directories also collapse to chips automatically.
872
873### Editor line navigation
874
875| Key | Action |
876|---|---|
877| `ctrl+a`, `ctrl+e` | Jump to start or end of line. |
878| `alt+left`, `alt+right` | Jump one word back or forward. |
879| `ctrl+u`, `ctrl+k` | Delete to start or end of line. |
880| `ctrl+w`, `alt+backspace` | Delete the previous word. |
881| `up`, `down` | Move within multi-line input. At the top edge, `up` recalls previous prompts and `down` moves forward through prompt history. |
882
883### Chat scroll
884
885| Key | Action |
886|---|---|
887| `pgup`, `pgdn` | Scroll one page up or down. |
888| `up`, `down` (editor empty, not browsing prompt history) | Scroll three lines up or down. This is how the mouse wheel reaches the scroll logic on most terminals. |
889
890## Extensions
891
892zot can be extended in any language via a subprocess + JSON-RPC protocol. Extensions can register slash commands, expose tools to the model, intercept tool calls (block or rewrite args), gate whole turns before the model is called, and rewrite the assistant's visible text before it reaches the user. None are installed by default; opt in explicitly. Hot-reload any time with `/reload-ext`.
893
894### Install and manage
895
896```bash
897zot ext install <path|git-url>   # copy / clone into $ZOT_HOME/extensions/
898zot ext list                      # show installed extensions
899zot ext doctor                    # diagnose load, registration, and conflict issues
900zot ext logs <name> [-f]          # cat or tail the extension's stderr log
901zot ext enable <name>             # re-enable a disabled extension
902zot ext disable <name>            # disable without removing
903zot ext remove <name>             # delete an extension directory
904```
905
906`zot ext doctor` keeps normal extension startup fail-soft, but gives
907you an explicit troubleshooting view: manifest errors, disabled or
908shadowed extensions, subprocess load errors, ready/auto-ready status,
909registered commands/tools, registration conflicts, warnings, and the
910stderr log path.
911
912For development, point `zot --ext <path>` at a working directory and skip the install step entirely. Repeatable; takes precedence over installed extensions of the same name.
913
914### Updating extensions
915
916`zot update` refreshes the zot binary **and** every installed extension that lives in a git checkout. Per-extension behaviour:
917
918- Disabled extensions are skipped.
919- Extensions without a `.git/` directory (installed by `zot ext install ./local-path`) are skipped — there is no remote to pull from.
920- For the rest, zot stashes any dirty worktree state (including untracked runtime files like `todos.json` or `config.json`), runs `git pull --ff-only`, and pops the stash. If the pop produces conflicts, the conflict markers are left in place and you'll see a warning.
921- Diverged branches, offline pulls, or any other git failure are reported as `failed` and the next extension is processed. `zot update` itself never aborts because of an extension.
922- zot does **not** run any build step (`go build`, `npm install`, `make`) after the pull. Extension authors are expected to commit the runnable artifact (binary, transpiled JS, etc.). If you need a build, rebuild manually and use `/reload-ext`.
923
924### Theme-only extensions
925
926An extension may ship only a theme: `extension.json` plus `theme.json` (or `themes/theme.json`) and no executable. zot loads it without spawning a subprocess and shows it in `/settings` with source information. See [docs/themes.md](docs/themes.md).
927
928### Reference
929
930`examples/extensions/` ships reference implementations in Go, TypeScript, Node, and shell. See [docs/extensions.md](docs/extensions.md) for the full protocol, the SDK API (`packages/agent/ext`), and the phase roadmap.
931
932## Skills
933
934A skill is a per-folder `SKILL.md` file with a YAML frontmatter header. zot discovers skills at startup, surfaces their names in the system prompt, and exposes a built-in `skill` tool the model uses to load the body on demand.
935
936By default zot loads built-in skills plus user-installed skills from:
937
938- `./.zot/skills/<name>/SKILL.md` (project)
939- `$ZOT_HOME/skills/<name>/SKILL.md` (global)
940- `./.claude/skills/<name>/SKILL.md`, `~/.claude/skills/<name>/SKILL.md` (Claude-compatible layout)
941- `./.agents/skills/<name>/SKILL.md`, `~/.agents/skills/<name>/SKILL.md` (agent-compatible layout)
942
943See [docs/skills.md](docs/skills.md) for the frontmatter fields, authoring tips, and example skills under `examples/skills/`.
944
945## Telegram bot (bridge)
946
947zot can run as a telegram bot so you can DM it from your phone. Two ways to run it: **from inside the TUI** (the running session mirrors into Telegram) or **as a standalone background daemon** (a headless bot with its own independent agent).
948
949### From inside the TUI
950
951Type `/telegram` in the running TUI to open a picker with **connect**, **disconnect**, and **status**. When connected:
952
953- DMs from the paired user become prompts in the **same** session you're typing in, so you can continue a conversation from the terminal on your phone and back again.
954- Messages you type in the TUI are mirrored into the Telegram thread prefixed `you: ...` and the assistant's replies come back prefixed `zot: ...`, so the Telegram chat stays a complete record of both sides of the conversation.
955- Messages sent from Telegram show up as your own bubble in Telegram (no mirror) and the assistant's reply to them comes back bare (no prefix).
956- The status bar shows a `- tg -` tag while the bridge is active.
957- `/telegram connect` / `/telegram disconnect` / `/telegram status` (or `/tg`) also work as direct commands without the picker.
958
959The in-TUI bridge refuses to start while the standalone daemon (below) is running, since two concurrent long-poll consumers of the same bot race on every update and silently drop messages.
960
961### Standalone daemon
962
963For headless servers or long-running bots unattached to a TUI:
964
965```bash
966zot telegram-bot setup     # paste a BotFather token, verify, save
967zot telegram-bot run       # foreground: long-poll in this terminal (ctrl+c to stop)
968zot telegram-bot start     # background: detach and return immediately
969zot telegram-bot stop      # SIGTERM the background bot (SIGKILL after 5s)
970zot telegram-bot logs -f   # tail $ZOT_HOME/logs/bot.log (omit -f to just cat)
971zot telegram-bot status    # config (token masked) + running/stopped
972zot telegram-bot reset     # forget the token and paired user
973# short alias: `zot tg ...` is accepted for every subcommand
974```
975
976The background flavor writes the child's PID to `$ZOT_HOME/bot.pid` and redirects stdout and 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.
977
978> **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.
979
980Setup flow:
981
9821. Talk to [@BotFather](https://t.me/BotFather) on telegram, run `/newbot`, copy the token it gives you.
9832. Run `zot telegram-bot setup` and paste the token when prompted.
9843. Run `zot telegram-bot run` in the directory you want the agent to operate in.
9854. 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.
986
987From 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 are case-insensitive: `/help`, `/status`, `/stop` (cancel the current turn). Config lives in `$ZOT_HOME/bot.json` (mode 0600).
988
989Starting either Telegram bridge removes any webhook configured for that bot before long polling begins, while preserving pending updates. Telegram does not allow webhooks and `getUpdates` polling at the same time, so do not share the bot token with another service that expects to keep a webhook active.
990
991Bot mode respects the usual zot flags: `--provider`, `--model`, `--cwd`, `--reasoning`, `--continue`, `--no-session`, `--no-tools`, and so on. Run `zot tg run -c --model claude-opus-4-1` to resume the latest session on Opus, for example.
992
993### Architecture: protocol-agnostic bot core
994
995The messenger functionality is split in two layers. A generic, protocol-agnostic core lives in `packages/agent/modes/bot`: it owns the turn queue, agent prompting, built-in command dispatch (`/start`, `/help`, `/status`, `/stop`), status formatting, and per-turn credential refresh. Concrete transports implement the small `BotAdapter` interface (inbound polling, sending replies, a typing indicator, and optional protocol-specific status text); the Telegram support in `packages/agent/modes/telegram` is one such adapter.
996
997This means additional messaging backends (Discord, Slack, Signal, and similar) can be added by implementing `BotAdapter` in a new package and wiring up a subcommand. No changes to the runner, agent, or core are required. Channel IDs are opaque strings owned by the adapter, so the shared runner stays free of protocol-specific types.
998
999## Development
1000
1001```bash
1002make build     # build ./bin/zot
1003make test      # go test -race ./...
1004make lint      # go vet + gofmt check
1005make fmt       # gofmt -w .
1006make release   # cross-compile linux/darwin/windows on amd64 and arm64
1007```
1008
1009Source layout (single Go module, four packages under `packages/`):
1010
1011```
1012cmd/zot/                              main()
1013packages/provider/                    LLM client surface, model catalog, streaming clients
1014packages/provider/auth/               credential store, api-key probe, oauth, login server
1015packages/core/                        agent loop, sessions, cost tracking, compaction
1016packages/tui/                         terminal raw-mode, input parser, editor, renderer, markdown, view
1017packages/agent/                       cli wiring, arg parsing, system prompt, config
1018packages/agent/extensions/            extension subprocess manager
1019packages/agent/extproto/              extension wire-format types
1020packages/agent/modes/                 interactive tui, print, json, dialogs
1021packages/agent/modes/bot/             protocol-agnostic bot runner (BotAdapter interface)
1022packages/agent/modes/telegram/        telegram adapter, api client, daemon
1023packages/agent/tools/                 read, write, edit, bash, sandbox
1024packages/agent/skills/                skill discovery, frontmatter parser, skill tool
1025packages/agent/swarm/                 background subagent runtime
1026packages/agent/sdk/                   public Go SDK for embedding zot in-process (package sdk)
1027packages/agent/ext/                   public Go SDK for writing extensions (package ext)
1028```
1029
1030Downstream consumers can depend on individual packages:
1031`go get github.com/patriceckhart/zot/packages/core` pulls only `core` and its transitive deps (today: `provider`), no agent or TUI code.
1032
1033## License
1034
1035MIT