Core Concepts

How Ark orchestrates autonomous agents.

Sessions

A session is a unit of work. It binds a task (summary/ticket) to a repository, a flow, and a compute target. Sessions track status, events, agent output, and conversation history.

Session statuses: ready, running, waiting, blocked, stopped, failed, completed.

Flows

A flow is a YAML-defined pipeline of stages. Each stage has an agent (or action), a gate, and optional configuration.

Example flow (default):

name: default
stages:
  - name: plan
    agent: planner
    gate: manual
  - name: implement
    agent: implementer
    gate: auto
    on_failure: "retry(3)"
  - name: review
    agent: reviewer
    gate: auto

The bare flow is a single stage with one agent — use it for quick tasks.

Stages and Gates

Each stage has a gate that controls advancement:

• auto: advances when the agent completes without errors
• manual: waits for human approval (press Enter in TUI or ark session advance)
• review: waits for GitHub PR approval (via webhook)
• condition: evaluates an expression

Agents

An agent is a YAML-defined Claude Code configuration. It specifies:

• model: opus, sonnet, or haiku
• system_prompt: with template variables ({repo}, {summary}, {ticket}, {workdir}, {branch})
• tools: which Claude tools the agent can use
• permission_mode: bypassPermissions, default
• max_turns: conversation turn limit

Agents are resolved with a 3-tier lookup: builtin (shipped with Ark), project (in your repo's agents/ directory), and global (in ~/.ark/agents/). Project agents override builtins of the same name, and global agents override both. You can create, edit, copy, and delete custom agents from the TUI Agents tab.

Built-in agents: planner, implementer, reviewer, documenter, worker.

Autonomy Levels

Each stage can set an autonomy level:

• full: agent can do anything (bypassPermissions)
• execute: can read, write, edit, and run commands
• edit: can read, write, edit but not execute
• read-only: can only read files

Channels

Channels are the communication layer between you and running agents. The conductor runs an HTTP server; each session gets a dedicated MCP channel on a deterministic port. You can send messages via the TUI (press t) or CLI (ark session send).

Hooks

Ark uses Claude Code hooks for agent status detection. At dispatch time, hooks config is written to the session's working directory. Hooks POST status events (busy/idle/error/done) to the conductor.

The Conductor

The conductor is the central HTTP server that:

• Receives hook status reports from agents
• Routes channel messages between humans and agents
• Serves the GitHub webhook endpoint for PR monitoring
• Polls scheduled sessions

It runs automatically when you use ark tui or ark exec.

PR Monitoring

Ark can monitor GitHub PRs via webhooks. When a reviewer leaves comments:

• changes_requested: the agent is steered with the review feedback
• approved: the review gate opens and the flow advances

Set up by pointing a GitHub webhook at your conductor's /api/webhook/github endpoint.

Skills

Skills are reusable prompt fragments that can be attached to agents. They encapsulate domain knowledge, coding patterns, or procedural instructions into standalone files that agents include in their context.

Skills use three-tier resolution (highest priority first):

• project: .ark/skills/ in the repo
• global: ~/.ark/skills/
• builtin: skills/ shipped with Ark

Attach skills to agents via the skills field in agent YAML. When a session is dispatched, Ark automatically injects the content of each listed skill into the agent's system prompt. Manage with ark skill list and ark skill show.

Recipes

Recipes are session templates with variables and a repo field. They let you quick-launch sessions from presets without manually filling in flow, agent, summary, and compute each time.

Recipes use the same three-tier resolution as skills: .ark/recipes/ (project), ~/.ark/recipes/ (global), recipes/ (builtin).

Built-in recipes: quick-fix, feature-build, code-review. You can create a recipe from an existing session with sessionToRecipe.

Intelligence Features

Ark includes several intelligence features that enhance agent autonomy:

• Fail-loopback: when a stage fails, Ark retries it with error context injected into the agent prompt (up to 3 retries). Configured via on_failure: "retry(3)" in flow stage definitions.
• Sub-agent fan-out: decompose a task into N parallel child sessions. The parent waits for all children to complete before advancing. Use ark session fork and ark session join.
• Skill extraction: analyze agent conversations for reusable procedures and save them as skills for future sessions.
• Structured review output: the reviewer agent produces machine-parseable JSON with P0–P3 severity levels for each finding.

Guardrails

Guardrails are pattern-based tool authorization rules that restrict what agents can do. They block dangerous commands (e.g. rm -rf /, git push --force) before the agent executes them. Guardrails are evaluated at the tool-call level and apply regardless of the agent's permission mode.

Remote Sync

When dispatching to remote compute targets, Ark syncs project-local configuration to the remote environment. The following paths are pushed at dispatch time:

• .claude/commands/
• .claude/skills/
• CLAUDE.md

Focus System

The TUI uses a focus stack for keyboard input ownership. When a form or overlay opens, it pushes onto the focus stack and takes ownership of all keyboard input (including Tab). App-level shortcuts only fire when no child component owns focus. This prevents key conflicts between overlays and the main navigation.