actor.sh

Concepts

The mental model: actors, roles, hooks, ask blocks, and channel notifications.

These pages explain the moving parts of actor.sh — what each piece is, why it exists, and how the parts fit together. They’re the layer above the reference docs: less “what flag does what” and more “what is this thing, conceptually.”

  • Actors and worktrees — what an actor is, the isolated-worktree model, lifecycle from new through discard, and parent/child tracking.
  • Roles — named presets in settings.kdl that bundle an agent, a system prompt, and config defaults.
  • Lifecycle hooks — shell commands that fire around create, run, and discard events.
  • Ask blocks — customize when the orchestrator asks the user a question before key MCP calls.
  • Channel notifications — how completion events flow from sub-actors back to the orchestrator without polling.

The Guides section turns these concepts into task-shaped recipes (configuring agents, writing settings.kdl, theming the watch TUI).

  • Actors and worktrees An actor is a coding agent running a task on its own git branch in an isolated worktree.
  • Roles Named presets in settings.kdl that bundle an agent, a system prompt, and config keys.
  • Lifecycle hooks Shell commands that fire around actor create, run, and discard events.
  • Ask blocks Customize when the orchestrator asks the user before spawning, running, or discarding actors.
  • Channel notifications How actor completion events flow back into the orchestrator's conversation.