Agents & Triggers
Configure an agent persona and choose which channel events wake it:
const coder = new claude.Agent("coder", {
model: "claude-opus-5-5",
effort: "high",
systemPrompt: "./prompts/coder.md",
});
new Trigger("mention", {
event: gh.issueComment({ mention: "@claude", from: github.collaborators() }),
worktree: (event) => `issue-${event.issue.number}`,
agent: coder,
container: dev,
});Agent configures an agent (model, effort, and system prompt) for a runtime, and Trigger runs that agent in a container, optionally on a branch, whenever a matching event arrives from an author in from. Follow-up triggers in the same conversation resume coder's session.
Every agent gets the runner's own system prompt first, and then its systemPrompt. The runner's prompt tells the agent that it runs headless, that it acts only on the messages in its prompt, that its final message is posted as its reply, and that it opens pull requests as drafts.
Trigger input | Required | Meaning |
|---|---|---|
event | Yes | A channel's selector, including its from |
agent | Yes | The agent to run. Its runtime must be in the container's runtimes |
container | Yes | The Container to run it in |
worktree | No | A function that names the branch to run on from the event. See Worktrees & Sessions |
base | No | Where worktree's branch is cut from if it doesn't exist yet. Only valid with worktree |
Event selectors
Each channel builds selectors in its platform's own vocabulary. The router matches them as data, without running any of the repo's code:
gh.issue({ actions: ["opened"], labels: ["bug"], from: github.collaborators() })
gh.issueComment({ actions: ["created", "edited"], mention: "@claude", from: github.team("acme/core") })
ops.mention("@claude", { from: slack.group("eng") })| Selector | Default actions | Supported actions | Filters |
|---|---|---|---|
gh.issue(opts) | ["opened"] | "opened", "edited", "reopened", "labeled" | mention, labels, from |
gh.issueComment(opts) | ["created"] | "created", "edited" | mention, labels, from |
ops.mention(name, opts) | from |
When actions includes "edited", the trigger fires only if the edit newly added the @mention. A mention matches as GitHub's does: in any case, and not as part of a longer name or an email address, so @claude doesn't match @claudette or me@claude.ai. labels matches an issue that has all of the listed labels.
Trust
from is required on every selector. It decides who can start a run:
| Author set | Matches |
|---|---|
github.collaborators() | Users with write access to the repo |
github.team("acme/core") | Members of a GitHub team |
github.user("alice") | One GitHub user |
slack.group("eng") | Members of a Slack user group |
slack.user("dan@acme.dev") | One Slack user |
Pass an array to accept several. Bot accounts never match. The agent also gets the conversation's other messages since its last run, with each author's role and whether they match from. See Connections & Channels.
Multiple agents on one conversation
Specialize agents by cost and capability for different tasks:
const triage = new claude.Agent("triage", {
model: "claude-haiku-5-5",
systemPrompt: "./prompts/triage.md",
});
const coder = new claude.Agent("coder", {
model: "claude-opus-5-5",
systemPrompt: "./prompts/coder.md",
});Bind each agent to its stage of the issue lifecycle. A function shared by several triggers types its parameter with the fields it reads, which both events have:
const branch = (event: { issue: { number: number } }) => `issue-${event.issue.number}`;
new Trigger("on-open", {
event: gh.issue({ actions: ["opened"], from: github.collaborators() }), // <-- 1. triage investigates new issues
worktree: branch,
agent: triage,
container: dev,
});
new Trigger("on-mention", {
event: gh.issueComment({ mention: "@claude", from: github.collaborators() }), // <-- 2. coder implements on @claude
worktree: branch,
agent: coder,
container: dev,
});Both triage and coder run inside the same issue-42 git worktree while keeping their own session transcripts:
| Path | Scope | Holds |
|---|---|---|
/data/worktrees/<branch> | Shared per branch | Git checkout where agents read and write repo files |
/data/agents/<agent>/ | Isolated per Agent | The runtime's config directory, such as .claude/, with the agent's settings, files and session transcripts |
/data/home/ | Shared per container | The files outside the runtime's config directory, such as ~/.npmrc |
The runner writes the container's files first and then the agent's, so an agent's file replaces the container's file at the same path. A file under the runtime's config directory, such as ~/.claude/CLAUDE.md, goes to each agent's directory. Any other file goes to the shared home.