zot

README

zot

Hand it a software task and get back finished, tested code. zot is an automated software factory in a single binary - an autonomous coding harness that plans, edits, runs, and verifies until the work is done.

What you get

Give it a brief and walk away:

zot "add rate limiting to the API, with tests"

zot reads the repo, writes and edits the code, runs the build and the tests, and fixes what it broke - on its own, from that one brief to a recorded outcome. When it stops you have a changed working tree and a full session log of every step it took. No chat loop, no approving each edit: one brief in, finished work out.

Why zot exists

Most coding tools optimize the conversation between a developer and an agent. zot optimizes the production run: it drives the whole job from one brief, without a follow-up prompt at every step and without a hosted engine.

It talks straight to a model provider over the OpenAI-compatible API - OpenAI, Anthropic, Groq, Mistral, DeepSeek, OpenRouter, a local Ollama, or anything else that speaks the same API - so all you need is a provider key. No account beyond the provider's own, and nothing is sent anywhere except the provider you configure.

Quickstart

Grab a prebuilt binary from the releases page - no toolchain required:

VERSION=vX.Y.Z; OS=linux ARCH=amd64      # e.g. darwin/arm64 on Apple Silicon
curl -L "https://github.com/openzot/openzot/releases/download/${VERSION}/zot-${VERSION}-${OS}-${ARCH}.tar.gz" | tar xz
mv "zot-${VERSION}-${OS}-${ARCH}/zot" ~/.local/bin/   # or any directory on your PATH

zot defaults to the zai backend running glm-5.2. Export a key and give it a job:

export ZAI_API_KEY="…"
zot "add input validation to the signup handler and a test"

Any OpenAI-compatible provider works - --backend anthropic --model claude-5-sonnet, a local --backend ollama, gateways, or a custom endpoint; see docs/backends.md. To build from source or run the container image, see docs/development.md and docs/docker.md.

How it works

The harness is zot's own, in the agent package:

• agent.ExecuteWithTools runs the model in a loop - it calls tools, sees the results, and goes again - until it records an outcome (_success / _failure) or a budget or guard stops it.
• agent.DefaultTools() gives it the toolbox: read, write, list and shell for the work, plus plan and progress to structure and narrate it.

That package is importable, so the same engine drives more than coding: Rook, an AI bug-hunting and security-audit agent, is built on it with its own toolset and skills.

What sits under that is the part worth knowing about:

• Thread assembly fits the conversation to the model's context window, newest-first, keeping tool calls paired with their results.
• Context strategy decides what happens as that window fills. compact (the default) summarises the older history into a checkpoint with a model call, so a long run keeps a condensed memory of its early turns instead of losing them; truncate simply drops the oldest messages to fit. A checkpoint is preserved verbatim and never re-summarised, and an outright provider rejection falls back to a no-model summary and retries. Configurable - see configs/zot.example.yaml.
• Loop detection notices when the agent has stopped making progress - four overlapping heuristics, because the obvious one (repeated messages) silently misses reasoning models, which interleave a thought between every tool call.
• Settle mode ends a run when the agent records an outcome, not when its prose happens to sound final. An answer containing "task completed" is not an ending. Note the boundary, though: settle mode checks that the agent declared done, not that the work is done. The agent verifies its own work by running the tests (its instructions tell it to); zot does not yet independently gate the outcome on a check of its own.
• Session logs record every run to disk as it happens, so a run nobody watched is still answerable afterwards - and so it can be picked up again with --resume (see docs/configuration.md).

zot itself is a read-only Bubble Tea viewer over that run - it renders the event stream into a scrollable log and has no text input, because the run is autonomous.

Sub-agents and coordination

zot has no native sub-agent primitive, by design. There is no spawn, no built-in supervisor, no fixed orchestration graph baked into the engine - and that absence is deliberate, not a gap waiting to be filled. A fixed hierarchy would decide, in advance, how work should be divided for every task; most tasks do not divide the way the framework guessed.

What the engine gives instead is the raw capability, and it lets the agent decide how to use it:

• An agent can call into itself. It has a shell tool, so it can invoke zot again - a fresh run with its own brief, its own working directory, its own budget - and read back the result. Delegating a self-contained piece of work to a clean context is a shell command, not a special API. Direct instructions in your AGENT.md, or a skill, are what tell it when that is worth doing.
• Agent-to-agent communication is left open, too. zot does not prescribe a message bus or a protocol. Two runs coordinate through whatever they already share - the filesystem (a scratch file, a work queue as a directory of tasks), a git branch, an HTTP endpoint, a channel daemon. The mechanism is a choice the task makes, not one the engine imposes.

The intent is that the agents themselves figure out how to organise and communicate, from the task in front of them, the context in the repository, and any guidance a relevant skill supplies. Encode the pattern you want - a map/reduce fan-out, a reviewer that re-runs the worker, a pipeline of single-purpose runs - as a skill (<name>/SKILL.md), and it becomes available exactly when the model judges it relevant, without changing the engine. Orchestration is content, not framework.

⚠️ Safety

zot is fully autonomous and has real file-write and shell-exec access from --dir. The flag changes the process working directory; it is not a filesystem sandbox. Absolute paths and shell commands retain all permissions of the zot process. Point it at a scratch directory or a disposable git checkout you are happy for it to change - not your home directory.

Configured backend credentials are resolved into zot's in-memory configuration and then removed from the process environment before the agent starts, so its shell commands do not inherit those API keys. Other secrets already present in the environment or readable from disk remain accessible to those commands.

The published container image is the practical way to bound this: the agent can only touch the volume you mounted, and docker run gives you the rest of the levers (read-only root, dropped capabilities, resource limits) in one place.

Status

zot is 0.x: functional and in active use, with improvements landing release to release. Until 1.0 the CLI flags, config, and behavior may still change between versions - pin a version and skim the changelog before upgrading.

Documentation

• docs/backends.md - providers, credentials, gateways, custom endpoints, the Responses API
• docs/configuration.md - config file, flags, controls, sessions, AGENT.md & skills
• docs/development.md - building from source, release vs developer builds, the codebase map
• docs/portable-config.md - baking the configuration into the binary
• docs/docker.md - running the container image
• CHANGELOG.md · RELEASES.md

Ecosystem

Project	Role
Rook	An AI bug-hunting and security-audit agent built on zot's engine
Pantalk	Connect coding agents to the chat platforms people already use
MCPShim	Turn MCP servers and HTTP APIs into standard CLI commands
crmkit	Give agents a shared CRM and system of record over HTTP or MCP

Documentation

Overview

Package zot is the embeddable core of the zot automated software factory. It turns a single plain-English task into an agentic run - plan, act, observe, exit - and renders the run in a read-only terminal UI.

The agentic loop is zot's own (see the agent package): thread assembly, compaction, loop detection and the tool-call cycle all run locally, against any OpenAI-compatible provider. zot needs no account and no hosted engine.

The standalone binary is cmd/zot; an embedding program can import this package and call Run directly while zot's internals stay internal.

Index

• Constants
• Variables
• func DefaultConfigPath() string
• func LoadProjectContext(cfg *Config, dirs ...string) error
• func Run(ctx context.Context, cfg Config, task string) error
• func RunWith(ctx context.Context, cfg Config, task string, options RunOptions) error
• func Version() string
• type Config
  • func Load(path string) (Config, error)
• type RunOptions

Constants

const DefaultInstructions = `` /* 1549-byte string literal not displayed */

DefaultInstructions is the system prompt handed to the agent when the configuration does not override it. It establishes the fully-autonomous, no-questions-asked contract: zot has no input channel, so the agent must never wait for the user.

The opening and the "act, don't narrate" rule imitate the batch-mode prompt of the engine zot was derived from: a run is a non-interactive background session whose deliverable is the changed working tree, not prose, and which ends only by recording an outcome with a terminal tool.

Variables

var ExampleConfigYAML []byte

ExampleConfigYAML is the commented starter config baked into the binary, used by `zot config` to seed ~/.config/zot/config.yaml when it does not exist yet.

Functions

func DefaultConfigPath

func DefaultConfigPath() string

DefaultConfigPath is the default config file location.

func LoadProjectContext

func LoadProjectContext(cfg *Config, dirs ...string) error

LoadProjectContext augments cfg with on-disk context discovered under the given directories, searched in order (typically the config directory first, then the working directory):

• <dir>/AGENT.md - appended to the agent instructions
• <dir>/skills/ - loaded via the SDK and added as a "skills" feature

Missing files and directories are ignored, and duplicate directories are searched once. AGENT.md content augments (never replaces) the base instructions.

func Run

func Run(ctx context.Context, cfg Config, task string) error

Run executes one autonomous coding task, rendering the agent's activity in the read-only TUI. The agent's file and shell tools operate on the current working directory, so callers should chdir into the target project first. Run blocks until the user quits the viewer or the program errors.

func RunWith

func RunWith(ctx context.Context, cfg Config, task string, options RunOptions) error

RunWith is Run with session recording and resume.

func Version

func Version() string

Version reports the build version of the linked zot core.

Types

type Config

type Config = config.Config

Config is the fully-resolved zot configuration. Load it with Load; its Validate method enforces the same checks the standalone binary runs.

func Load

func Load(path string) (Config, error)

Load reads configuration, layering defaults < file < env. A missing default file is fine (env vars alone can configure zot).

type RunOptions

type RunOptions struct {
	// SessionDir is where the run's log is written. Empty disables recording.
	SessionDir string

	// Resume seeds the conversation from an earlier session, so a run that ran
	// out of budget or died overnight continues rather than starting again.
	Resume *session.Session

	// OnSession is called once the log is open, with its path. Used to tell the
	// operator where the record is before the run takes over the screen.
	OnSession func(path string)

	// Prompt is an optional user message that opens the run, distinct from the
	// task. The task (in the instructions) is the durable objective; the prompt is
	// an ephemeral nudge - "start with the error handling" - and may be
	// compacted away later, which is fine because it is not the objective.
	Prompt string
}

RunOptions configures a run beyond the configuration itself.