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.
• built-in tools (read, write, edit, bash, glob).
• 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

The installed binary reports the tagged module version and supports zot update.

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

API keys from commands

To keep an API key in a password manager instead of auth.json, configure an api_key_command for the provider:

{
  "anthropic": {
    "api_key_command": {
      "program": "op",
      "args": ["read", "op://Work/Anthropic/credential"],
      "timeout_ms": 120000
    }
  }
}

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

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

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

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

Token refresh

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

• 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 zot-docs guidance for every run. --system-prompt still wins per-invocation. Pass an empty value (--system-prompt "") to intentionally omit the built-in identity. Custom prompts still receive appended instructions and generated context, including AGENTS.md, skills, auto-swarm guidance when enabled, and the date/cwd footer. Delete the file to revert to the default.

HTTP proxy

To route zot-managed HTTP and HTTPS requests through one proxy, add http_proxy to $ZOT_HOME/config.json:

{
  "http_proxy": "http://127.0.0.1:7890"
}

The setting is applied at startup to both HTTP and HTTPS traffic. Existing HTTP_PROXY, HTTPS_PROXY, http_proxy, and https_proxy environment variables take precedence for their corresponding protocol. NO_PROXY and no_proxy continue to control bypasses. Restart zot after changing the config file. If the URL contains proxy credentials, prefer protected environment variable