patriceckhart/zot

zot – a Go‑based coding‑assistant harness

What it does

• Provides a single, static binary that lets you talk to a large‑language‑model (LLM) for code‑related tasks.
• Supports 30+ LLM providers out of the box (Anthropic, OpenAI/Codex, Google Gemini, Ollama, etc.) and can also call local models via Ollama.
• Offers built‑in “tools” (read/write files, edit, run bash commands, globbing) that the model can invoke, turning the LLM into an autonomous coding agent.
• Runs in three modes:
  1. Interactive TUI – a terminal UI where you type prompts and watch the model’s actions.
  2. Print mode – zot "prompt" prints the final generated text and exits.
  3. JSON mode – streams newline‑delimited JSON events for programmatic consumption.
• Includes a Telegram bot bridge, a plug‑in system (subprocess + JSON‑RPC), theming, custom key‑bindings, and persistent “agents”/skills via markdown files.

How to get it

• One‑line installer for macOS/Linux (curl … | bash) or Windows PowerShell.
• go install github.com/patriceckhart/zot/cmd/zot@latest.
• Pre‑built binaries are also available on the GitHub releases page.

Key concepts

Concept	What it is
Providers	Remote LLM services (Anthropic, OpenAI, Gemini, etc.) that zot talks to.
Tools	Built‑in actions the model can request: read/write files, edit, run shell commands, glob patterns.
AGENTS.md	Global or per‑project markdown file that adds standing instructions to every prompt (e.g., “never edit files unless asked”).
SKILL.md	Reusable instruction snippets that can be invoked with /skill:<name>.
Extensions	External programs written in any language; zot talks to them via JSON‑RPC.
Continuous mode	Persistent local store ($ZOT_HOME/sessions/…) that survives crashes and can be served to multiple clients (zot continuous serve).
Themes & keymaps	JSON files under $ZOT_HOME let you customise colours and keyboard shortcuts in the TUI.

Typical workflow

1. Install the binary and run zot. The first launch opens a TUI with a /login command.
2. Log in via API key or OAuth (the tool can launch a browser or use device‑code flows for providers like Anthropic, OpenAI, Kimi, xAI, GitHub Copilot).
3. Type a prompt, e.g. fix the failing test. Zot sends the prompt to the selected model, receives a response, and may invoke tools (edit a file, run a test suite) automatically.
4. The TUI shows the model’s reasoning, tool output, and final answer. You can approve, reject, or edit actions.
5. Optionally add an AGENTS.md or SKILL.md to shape future behaviour, or write a custom extension for domain‑specific tasks.

Configuration & state

• All files live under $ZOT_HOME (defaults to $XDG_STATE_HOME/zot or platform‑specific equivalents).
• config.json stores the last‑used provider/model, UI preferences, HTTP proxy, and custom key‑bindings.
• auth.json holds API keys or OAuth tokens (mode 0600). Tokens are refreshed automatically.
• models.json can define custom endpoints or self‑hosted models.
• Session transcripts are saved as JSONL under sessions/ and can be resumed with zot --continue.

Why it might matter

• Single binary: No Python runtime, Docker, or heavyweight dependencies – just a Go executable.
• Broad provider coverage: Works with major commercial APIs and local Ollama models, making it easy to switch providers without changing code.
• Tool use: The model can read/write files and run shell commands, enabling true “agent” behaviour for code generation, refactoring, or debugging.
• Extensible: Plug‑in architecture lets you add domain‑specific capabilities (e.g., a database query tool) without recompiling.

Limitations / cautions

• Uses the same OAuth client IDs that the official CLIs use; providers could revoke them, so the API‑key flow is the safest fallback.
• Extensions are opt‑in; none are shipped by default.
• Persistent state lives on the local machine; sharing sessions across machines requires running zot continuous serve.

Bottom line zot is a lightweight, Go‑native harness that turns LLMs into interactive coding assistants, with built‑in tool use, multi‑provider support, and a customizable terminal UI.