zot

What is it?

Yet another coding agent harness, lightweight and written (vibe-slopped) in go.

• one static binary.
• 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.
• four tools (read, write, edit, bash).
• three run modes (interactive tui, print, json).
• built-in telegram bot.
• 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.
• user and extension themes via JSON; see docs/themes.md.
• standing instructions via AGENTS.md files (global and per-project); see Persistent instructions.
• reusable instructions via SKILL.md files; see docs/skills.md.
• portable agents from local directories, .zot files, or temporary public GitHub downloads; see docs/zotfiles.md.

Install

One-liner (macOS, Linux)

curl -fsSL https://www.zot.sh/install.sh | bash

Detects 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:

curl -fsSL https://www.zot.sh/install.sh | bash -s -- v0.0.1 ~/bin

One-liner (Windows, PowerShell)

iwr -useb https://www.zot.sh/install.ps1 | iex

Drops zot.exe into $HOME\bin and adds it to the user PATH if missing. Open a fresh terminal afterwards.

go install

go install github.com/patriceckhart/zot/cmd/zot@latest

From source

git clone https://github.com/patriceckhart/zot
cd zot
make build        # produces ./bin/zot
make install      # into $GOPATH/bin

Prebuilt binaries

Every release on the releases page 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.

Authenticate

The 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.

Credential lookup order

1. --api-key flag
2. 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)
3. $ZOT_HOME/auth.json (API key or OAuth token; mode 0600)

$ZOT_HOME defaults to:

• All platforms: $XDG_STATE_HOME/zot when XDG_STATE_HOME is set
• macOS fallback: ~/Library/Application Support/zot
• Linux fallback: ~/.local/state/zot
• Windows fallback: %LOCALAPPDATA%\zot

/login flow

Run zot and type /login. Pick one of two methods:

• 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.
• Subscription: use your Claude Pro/Max, ChatGPT Plus/Pro, Kimi Code, or GitHub Copilot subscription. DeepSeek and Google Gemini do not have a subscription login path. For those, use the API-key flow.
  • 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.
  • Anthropic uses the Claude Code OAuth flow. Messages go to api.anthropic.com with a bearer token and the Claude Code identity headers.
  • 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.
  • 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.
  • 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.

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, 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.

Token refresh

OAuth access tokens are short-lived (Anthropic ~8h, OpenAI ~30d; Kimi and GitHub Copilot also use refresh/exchange flows). zot refreshes or exchanges them automatically:

• 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.
• The telegram bridge additionally refreshes once per turn so a bot that runs for days keeps working without manual intervention.
• 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.

All data lives under $ZOT_HOME:

$ZOT_HOME/
├── config.json         # last-used provider/model/theme, saved automatically
├── auth.json           # api keys and oauth tokens (mode 0600)
├── sessions/           # jsonl transcripts, one dir per cwd
├── models-cache.json   # live /v1/models discovery cache (6h ttl)
├── AGENTS.md           # optional: global instructions appended to the prompt
├── SYSTEM.md           # optional: replaces the default system prompt
├── skills/             # optional: user SKILL.md files
├── themes/             # optional: user theme JSON files
├── extensions/         # installed extensions, one dir per extension
└── logs/               # app log files

Drop 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.

Persistent instructions (AGENTS.md)

Use 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.

zot discovers AGENTS.md files automatically at startup and loads them in this order:

1. $ZOT_HOME/AGENTS.md (global, machine-wide instructions that apply to every project).
2. Every AGENTS.md from the top-most parent directory down to the current working directory. More specific (deeper) files may override earlier ones.

All discovered files are appended to the prompt in that order, so a global baseline can be refined per project.

For a general, non-project-specific instruction set, put your rules in $ZOT_HOME/AGENTS.md, for example:

Treat 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.

AGENTS.md vs the other mechanisms:

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.

Changelog on update

The 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.

Usage

zot                              # interactive tui
zot "fix the failing test"