zot

README

zot

Stop promting. Start shipping.

zot is an automated software factory in a single ~11 MiB binary. It takes a work order - an objective, the acceptance criteria that define done, the constraints to hold - and plans, edits, builds, tests and fixes until the work is done. No chat loop, no approving each edit, no hosted engine, no telemetry. It talks straight to any OpenAI-compatible model provider with your own key.

Install

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

That fetches the latest release for your platform (Linux or macOS, amd64 or arm64), verifies its checksum, and puts zot in ~/.local/bin. Pin a version with ZOT_VERSION=vX.Y.Z, or change the directory with ZOT_INSTALL_DIR.

Prefer to do it by hand? Grab a tarball from the releases page, pull the container image (ghcr.io/openzot/openzot), or build from source.

Use

zot defaults to the zai provider running glm-5.2. Export a key, write an order, hand it over:

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

zot new writes a small YAML order under .zot/orders/; edit its acceptance criteria, then a bare zot runs everything outstanding. zot --watch turns the folder into a drop box. Any OpenAI-compatible provider works - --provider anthropic, a local --provider ollama, a gateway, a custom endpoint - see providers.

Why zot

• Orders, not prompts. One brief in, finished work out - and orders are files, so they compose, queue, and stream. → work orders
• Nothing in the way. No hosted engine, no account, no telemetry. Your key, your provider, your machine. → philosophy
• Built to run unattended. Context compaction, loop detection, settle mode, resumable session logs. → how it works
• Orchestration is content. No sub-agent framework; an agent can call zot again, and skills say when. → sub-agents

Watch it work: the arcade ships a new browser game every 30 minutes from one standing order, with no human in the loop.

⚠️ Safety

zot has real file-write and shell access from --dir, and --dir is not a sandbox. Point it at a disposable checkout, or run the container image. Read safety first.

Documentation

• docs/orders.md - work orders, zot new, the book, watch mode
• docs/providers.md - providers, credentials, gateways, custom endpoints
• docs/configuration.md - config file, flags, controls, sessions, AGENTS.md & skills
• docs/how-it-works.md - the harness, what sits under it, sub-agents
• docs/safety.md - what zot can touch and how to bound it
• docs/docker.md - running the container image
• docs/development.md - building from source, the codebase map
• docs/portable-config.md - baking the configuration into the binary
• docs/philosophy.md - why zot exists, the arcade, status
• CHANGELOG.md · RELEASES.md

Ecosystem

Project	Role
Arcade	A live zot factory shipping one browser game every 30 minutes, unattended
Rook	A fully automated offensive security harness
Pion	A defensive AI security harness for automatic monitoring and incident prevention
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

Status

zot is 0.x and in active use. Flags, config and behavior may change before 1.0 - pin a version and skim the changelog before upgrading. Small, focused pull requests are welcome; anything large is worth an issue first.

Documentation

Overview

Package zot is the embeddable core of the zot automated software factory. It turns a work order - a durable objective, rendered to a 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 NewClient(cfg Config) (*agent.Client, 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 = baseInstructions + "\n\n" + nonInteractiveContract

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.

It is assembled rather than written out because its closing half is not the caller's to drop - see nonInteractiveContract.

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>/AGENTS.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. AGENTS.md content augments (never replaces) the base instructions.

func NewClient

func NewClient(cfg Config) (*agent.Client, error)

NewClient resolves the configuration into a provider-backed client, for engine work outside the main run path - the read-only survey that drafts a work order's acceptance criteria, say. A run of record never takes this path: it goes through Run or RunWith, which render, log, and record an outcome.

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)

	// BatchIndex and BatchSize place this run in a batch - order 2 of 5 - so
	// the viewer can show how much of the queue is left. Zero for a run that is
	// not part of a batch.
	BatchIndex int
	BatchSize  int

	// Title is a short label for the work, shown in the viewer instead of the
	// task text. A work order's title, or one derived from its file name;
	// empty falls back to the task. It is presentation only and never reaches
	// the model - the objective is the contract, a title is a label.
	Title string

	// QuitOnDone closes the viewer as soon as the run ends instead of holding
	// the final screen. Set for the intermediate orders of a batch, where a
	// held screen would stall the orders behind it until a keypress nobody
	// unattended will make; the batch's last order still holds for review.
	QuitOnDone bool
}

RunOptions configures a run beyond the configuration itself.