All docs

Start

Concepts

The things in the system and how they connect.

You face one Agent Desk. The Desk is connected to each of your machines; the Daemon on each machine starts harness sessions, runs shell commands and operates repositories on the Desk's behalf. What gets done and how it flows is decided by plugins in Git.

On the machines

Name What it is
Agent Desk (Desk) Your centre: host of the UI, the engine and the database. One per person. It checks out no repositories itself
Client A machine connected to the Desk. It belongs to exactly one Desk
Client Daemon (Daemon) The resident process on a Client. It dials the Desk and, on its behalf, starts Workers, runs shell commands, opens consoles, operates repositories and builds the UI
Harness An agent program installed on a Client that speaks ACP. Each harness has a definition that says how to start it
Worker A harness session started by the system. To the engine and the UI, all Workers are alike
Compute and environment The two "wheres" of a session: which Client the harness runs on, and which directory on which Client it works against. They need not be the same machine
Shell execution Running one PowerShell or Bash command non-interactively on a Client and getting a structured result back
Console An interactive terminal you open in the UI
The ail command line How agents inside a session, and you in a terminal, get things done through the Desk

Plugins

Name What it is
Plugin directory A directory given to the Daemon at start-up. All plugins on that Client are checked out flat inside it
Main repository The global entry point, a local directory or a Git repository. It registers every other plugin and holds the Journal
Official plugin The roles, workflows, harness definitions, prompts and base UI that ship with the system. Once in the plugin directory it is an ordinary Git repository that you change as you need
Repo plugin A Git repository to work in. Registering one takes a Git URL, a name and a description
Role A role description plus its binding: which Client to start on, which harness, which model, how much thinking
Workflow The sequence of steps for an intent: which role does each step, and whether it has a review gate
UI plugin The source of a React UI, built and then served to browsers by the Desk

There is one global set of roles and workflows, not one per repository. A repository that needs to disable or restrict some of them says so in its registration.

Work

Name What it is
Router The one you talk to, a resident Worker. It only judges: what intent this is and which Repo it belongs to, then dispatches
Run One pass of a workflow for one request. Each step is a Worker; a gated step also has a reviewer
Report block The structured data a Worker gives the engine at the end of each turn: how far it got, whether you must answer, when to wake it. The engine moves only by it
Workflow organization A run together with every run it triggers, directly or indirectly
Review Report, Presentation Report Pages a Worker pushes to you: the first asks you to answer, the second shows you a result
Tasks and maps Task records in a repository; a large piece of work is planned by an architect into a map, and the engine dispatches tasks by dependency
Journal Your history: what was done and what was delivered. Files in the main repository, written only by the engine
Board The engine's overview for you: which runs are waiting for you, in progress, or ended

The five main paths

  1. Dispatching work. You tell the Router; the Router dispatches with the command line; the engine creates a run and starts the first step's Worker. The Worker works and ends its turn with a report block; the engine follows it to review, to the next step, or to closing.
  2. Asking you. A Worker pushes a Review Report; you answer on the Desk; the answer goes straight into that Worker's queue, not through the Router.
  3. Opening a session directly. On the new session page pick a Client, a folder and a harness; you get a session page and talk to it.
  4. Cross-device shell. An agent or you name a target Client and a command; the Desk checks authorization; the target Daemon runs it; the result comes back the way it went.
  5. Changing a plugin. Edit a file in a plugin and the Daemon notices: roles and workflows take effect the next time they are used, the UI after a rebuild and a refresh.

Any message sent to a busy session is queued and delivered when its turn ends.