Supported agents

diri knows how to launch and read 20 terminal coding agents, plus a plain shell. Each one is described by a JSON manifest that says how to start it, how to resume it, and how to tell from its screen whether it is working, idle or waiting for you.

#Agent catalog

What the columns mean:

#Install and detect agents

diri does not bundle any agent. It finds the CLIs already on your machine.

Open Settings → Agents:

On your Mac, diri looks for agents on the PATH from your login shell, then in common user install folders such as pnpm, Bun, Cargo, mise and Volta. A path you choose with Add… wins over PATH. Missing agents stay listed in Settings but are hidden from quick-create menus.

#Add your own agent

You can add an agent diri does not ship, or replace a built-in manifest, without building diri.

1. Write a JSON manifest. The filename, top-level id and agent.id must match, for example my-agent.json with "id": "my-agent".
2. Put it in the overrides folder:

3. Restart the Engine. The catalog is read once when the Engine starts. Quitting diri with no running sessions stops the Engine, and opening diri starts it again.

A file with the same id as a built-in manifest replaces it. A new id adds an agent. A malformed file is skipped and the rest of the catalog still loads.

#A minimal manifest

This screen-driven manifest is enough for most terminal agents:

{
  "schemaVersion": 2,
  "id": "my-agent",
  "version": "2026.10.01.1",
  "statusModel": "full",
  "agent": {
    "id": "my-agent",
    "displayName": "My Agent",
    "shortLabel": "my-agent",
    "aliases": ["myagent"],
    "firstClass": true,
    "statusAuthority": "screen",
    "binary": "my-agent",
    "returnToLoginShell": true,
    "approve": { "text": "y", "submit": true }
  },
  "rules": [
    {
      "id": "permission",
      "state": "blockedPermission",
      "priority": 1000,
      "region": "bottom_non_empty_lines",
      "regionLines": 8,
      "when": { "contains": "allow this command?" }
    },
    {
      "id": "working",
      "state": "working",
      "priority": 900,
      "region": "bottom_non_empty_lines",
      "regionLines": 3,
      "when": { "contains": "esc to cancel" }
    },
    {
      "id": "idle",
      "state": "idle",
      "priority": 500,
      "region": "bottom_non_empty_lines",
      "regionLines": 1,
      "when": { "lineRegex": "^>\\s*$" }
    }
  ]
}

#Essentials

Rule states are working, idle, blockedPermission, blockedQuestion and skip. Predicates are contains, regex, lineRegex, progress, and any, all and not to combine them. Regexes use Rust's regex syntax, which has no lookaround or backreferences.

Put blockers around priority 1000, working around 900 and idle around 500, so a permission form beats a spinner still visible behind it. Match several literal strings the agent really draws rather than one broad regex.

#Validate it

• Start the agent from diri and walk it through idle, working and a permission prompt.
• If a state is wrong, open Session Inspector → Info → Why Diri thinks this and use Copy status debug info to see which rule matched.
• When contributing a manifest to diri, run the engine tests, which decode every bundled manifest and reject unsupported regexes:

cd diri
cargo test -p diri-engine

The full schema, regions, capture settings and safe fixture capture are in docs/AGENT-MANIFESTS.md.