Zozo Docs

Work Model ​

Core Concepts defines the Provider, Runtime, Thread, Run, and Event vocabulary. This page connects those pieces to the way work enters and moves through your Stack.

How an Issue Becomes a Pull Request ​

Register a Project, a GitHub repository that your Dispatcher watches for eligible Issues. An Issue joins the Frontier when it receives the ready-for-agent label. The Dispatcher applies the remaining eligibility rules before selecting it.

For each fresh Issue attempt, Dispatch carries the work from a clean checkout to a Pull Request:

  1. The Dispatcher creates a Managed Worktree, the Workspace and git branch it owns for this attempt.
  2. It creates a Thread bound to that Workspace and the selected Provider.
  3. It starts a Run with the Issue as the implementation specification and includes the Project's build and test commands.
  4. The Provider launches its Runtime in the Managed Worktree. The Runtime reads the repository, edits the files, runs the build and tests, and commits the completed implementation to the attempt's branch.
  5. Each Run appends normalized Events to the Thread's journal. The Dashboard, the web client for observing and operating the Harness, renders them live.
  6. When the attempt completes with committed changes, the Dispatcher pushes the branch and opens a Pull Request that closes the Issue.
  7. The Project's merge policy leaves the Pull Request open for your review or sends it through Landing, which verifies it against the current main before merging.

What Zozo Can Build ​

Zozo provisions the Toolchain declared by the repository before each Run starts. A Toolchain is the language interpreter and tooling needed to run that commit's build and test commands. It runs inside the Cell, the isolated execution environment created for the Run, and follows the version files committed with the code.

The supported surface includes:

  • Node.js and Python: Zozo can install repository-declared versions that mise can resolve for the Cell's Linux platform. Python requires an available precompiled build because Zozo doesn't compile Python from source.
  • Other preconfigured ecosystems: idiomatic version files are recognized for Ruby, Go, Java, Rust, Perl, Elixir, Crystal, Zig, Swift, .NET, Deno, Bun, Terraform, and OpenTofu.
  • Additional mise tools: .tool-versions and mise.toml can declare any other tool and version supported by the mise release in the Cell. Use the mise registry to find available tools and their installation backends.

Framework choice isn't a separate compatibility gate. A React or Next.js repository uses its Node.js Toolchain, while Django or Flask uses its Python Toolchain. The repository's install, build, and test commands remain responsible for framework dependencies and any external services they need.

Configure Your Repository ​

  1. Choose one version file at the repository root. A mise.toml file is the recommended option for a new setup. Zozo also reads .tool-versions and the enabled idiomatic version files, including .nvmrc, .node-version, and .python-version.

  2. Declare every required language or development tool. If you have mise installed locally, run:

    sh
    mise use --pin node@22 python@3.12

    mise use installs the tools and writes them to mise.toml. The --pin option records the resolved exact versions. You can also create the file manually:

    toml
    [tools]
node = "22.18.0"
python = "3.12.13"

    Replace the example values with the versions your repository uses. Add other tools to the same [tools] table.

  3. Verify that mise can install the declaration. Run the same installation command Zozo runs when a Cell starts:

    sh
    mise install
mise exec -- node --version
mise exec -- python --version

    The mise walkthrough explains how project configuration and mise install work together. Test on Linux when platform-specific availability matters. Python must have a precompiled build available for the Cell's platform.

  4. Commit the version file with the code. Each Run reads the declaration from the commit under test. A package.json engines field doesn't select Node.js for Zozo, so commit .nvmrc, .node-version, .tool-versions, or mise.toml as well.

  5. Keep dependency and verification commands in the repository. Commit the package-manager lockfiles and scripts needed to install dependencies, build, and test. Zozo provisions the Toolchain and puts its binaries on PATH; the repository's normal commands remain responsible for the application dependencies and services used by the build.

Zozo reads tool versions without trusting the repository's mise configuration. Use [tools] for provisioning, and don't rely on mise tasks, hooks, or environment entries to run automatically before the Runtime starts.

For stronger reproducibility, follow mise's mise.lock guide and commit the generated lockfile with the version declaration. A lockfile can preserve exact versions, checksums, and download URLs when the selected backend supports them.

A repository with no version declaration uses the image defaults, currently Node.js 22 and Python 3. See Declare a Toolchain for the recognized files and failure behavior.

How Auto-dispatch Finds Work ​

Auto-dispatch is the standing fleet mode that turns available capacity into Project work. It parks when no Issue can be selected, then wakes when the selection picture may have changed:

  • An interval tick, every 5 minutes by default, checks GitHub for new or newly eligible Issues.
  • A freed fleet slot requests another selection immediately.
  • A concluded Landing, the guarded process that tries to move a successful Pull Request onto main, requests another selection because the affected Project may no longer be held by an outstanding Pull Request.

Interval polling keeps GitHub discovery inside the Dispatcher, which owns all GitHub and Issue logic. You don't need to configure a webhook or another external trigger. See How Dispatch Decides for selection order, manual and targeted Dispatch, and fleet states.

Admission Protects Capacity ​

Your Stack's admission gate limits how many Runs can use resources at once. General Concurrency controls ordinary work, including targeted and fleet Dispatch. A separate Interactive Reserve preserves additional capacity for a person waiting on a live reply.

Changing a concurrency setting doesn't interrupt a Run already in flight. It changes which work the admission gate can start next. Hosted plan caps bound the settings you choose; see Quotas for the hosted limits and How Dispatch Decides for admission priority.

How Delegated Work Stays Organized ​

During a Run, the primary Agent may delegate a focused task, such as exploring part of the repository or reviewing a proposed change, to a subagent. This creates a Subagent Run inside the current Run. It stays with the same Issue, Thread, and Workspace instead of becoming separate project work.

The subagent returns its findings to the primary Agent, which remains responsible for the implementation, tests, and commit. Zozo records the delegated messages and tool use in the Thread's journal under the task that started them. You can keep following the original Issue and Thread in the Dashboard while the agents divide the work internally.

  • Watch a Project: add a Project, tune its settings, and place Issues on the Frontier.
  • Label Reference: look up the control, classification, and inert label vocabularies.
  • Core Concepts: review the Provider, Runtime, Thread, Run, and Event vocabulary.
  • Quotas: understand the hosted limits on concurrent work.
  • Declare a Toolchain: select the language and tooling versions used by your repository.
  • Quickstart: configure your first Project, start Auto-dispatch, and watch a Run stream.

Docs for Zozo: a coding-agent harness.

Copyright © Zozo