Documentation

Use zarlcode to work on a codebase from your terminal, or use zkit to build an agent into your own Go application. These docs cover setup, daily workflows, customization, runtime behavior, and the boundaries of agent execution.

Choose a starting point

• I want to use the coding agent. Install and configure zarlcode, then plan, build, and review a change.
• I want to build an agent in Go. Follow the zkit quickstart, then use the architecture map to choose the packages you need.
• I want to understand what runs on my machine. Read Safety and workspace access before enabling tools or handing off a task.
• I want to understand the harness. Start with the application and runtime layers, then follow a task through the model–tool loop and its extension points.
• Something is not working. Start with Troubleshooting for provider, credential, session, and automation checks.

Use zarlcode

Setup and configuration

• CLI overview — installation options and the main capabilities of the terminal application.
• Install and first run — launch in a workspace, select a local or hosted model, and complete provider setup.
• Providers and credentials — model selection, the global credential vault, and global versus workspace settings.

Work on a codebase

• Your first workflow — investigate in Plan mode, switch to Build, run checks, inspect the diff, and resume later.
• Interface guide — timeline, cockpit, working set, file viewer, model picker, sub-agents, and keyboard shortcuts.
• Sessions and transcripts — local persistence, interruption recovery, compaction, export, and deletion.
• Automation and CLI — headless tasks, named-agent launch options, initialization, diagnostics, and updates.

Customize and control execution

• Files and workspace resources — inspect the files, skills, agents, and hooks visible to the session.
• Sub-agent tasks — named profiles, work modes, task lifecycle, and workspace coordination. This is the shared runtime reference; the TUI guide covers the task panel.
• MCP connections — external tool discovery, connection policy, and name-collision boundaries.
• Web search services — SearXNG and Brave backends, including where to configure them in zarlcode.
• Safety and workspace access — user privileges, Plan mode, shell execution, network integrations, and rollback.

Build with zkit

Create an agent

• Toolkit and runtime design — how the runner calls models, executes tools, stores history, and checks results, plus the Go interfaces you can implement.
• Quickstart — a complete minimal agent with a provider, typed tool, and runner.
• Architecture — what each package does, its dependencies, and how to use it in an application.
• Runnable examples — small programs demonstrating individual features, including scripted modes that run without a model.

Models and tools

• LLM providers — adapters, backend registration, chat templates, recovery, and conformance tests.
• Tool system — interfaces, typed arguments, schemas, registry behavior, tool effects, and output formats.
• Code tools — workspace file operations, managed shell processes, planning, and web tools.
• Tool ecosystem — typed tool construction, runtime tools, MCP, fetching, and search.

Runtime, state, and verification

• Runner — construction, results, streaming events, prompt sources, and terminal conditions.
• Turn lifecycle — follow a zarlcode turn through execution, event application, durable saving, recovery, and shutdown, with implementation and test links.
• Sub-agent tasks — delegation, cancellation, iteration caps, and task ownership.
• Compaction — structural, tiered, and model-assisted approaches to fitting history into a context budget.
• Shared infrastructure — retrieval, indexing, workflows, checkpoints, human review, and local session storage.
• Verified completion — check whether a task succeeded and retry with feedback when it did not.

Safety and package reference

• Guardrails — tool-dispatch middleware, schema repair, shell policy, and post-edit verification.
• Sandboxing — the distinction between static shell checks and kernel-enforced confinement, including platform limitations.
• Foundation packages — supporting packages for configuration, credentials, infrastructure, and applications.

A library capability is not automatically enabled in every application. Consult the application guide for its configured behavior; consult the zkit reference when assembling your own runtime.

Examples and evaluation

• Feature coverage — find an example that exercises a particular capability.
• SWE-bench evaluation — the evaluation driver, its zkit dependencies, build commands, and re-drive telemetry.

Use the documentation search for a command, package, or feature name. For CLI flags, zarlcode --help and the relevant subcommand’s --help describe the version installed on your machine.