Docs
Agent actions
Saved prompts you can launch against a task or project, with an explicit contract for what they may change.
An agent action is a saved prompt with a contract attached. Instead of retyping "review this and tell me what is wrong" into a terminal, you attach it to a task and launch it from the card. The action carries what it may change and where its result should land, which is what separates it from a bookmarked prompt.
Manage them under Agent actions in the sidebar. Built-in actions ship in code and always exist; custom ones you author sit alongside them.
Use an Agent Panel session when the work benefits from a continuing conversation or permission decisions. Use a terminal launch when you want the provider's raw interactive CLI. The Agent Panel guide includes a compact comparison of all three surfaces.
Built-in actions
| Action | Context | What it does |
|---|---|---|
| Implement | Task | Starts a coding agent to make the changes the task needs |
| Research | Task | Investigates the codebase and writes up options and a recommendation, without changing code |
| Review | Task | Reviews the work for correctness, quality, and relevant security risk, and reports findings, without changing code |
| Break down | Task | Creates a set of smaller follow-up tasks that together complete this one |
| Triage | Project | Reviews the backlog and proposes priorities, tags, and grouping |
Break down creates sibling tasks, not children. Pekan's task model is deliberately flat, with no parent and subtask relationship, so a breakdown produces independent board tasks rather than a hierarchy.
Context types
An action is attached to exactly one surface, and the menu on each surface is filtered to match:
taskactions appear on a task card and detail view.projectactions appear at project level.
Mutation mode
This is the safety contract, and it is worth understanding before you author an action.
proposeruns read-only. It produces a reviewable result, a comment, a handoff, or its run output, and stops. It does not apply board changes.applyis authorized to change the board through the MCP tools, and is confirmed before launch.
The launch dialog is the gate, deliberately. An action runs as a one-shot process, so it cannot be asked for a mid-run confirmation; the decision has to happen before it starts. Of the visible built-ins, Implement and Break down are apply, and Research, Review, and Triage are propose.
Output behavior
Where an action's result should land. It is injected into the prompt, so the launched agent knows whether it is targeting the board or the repository, and it is validated against the context.
| Context | Allowed outputs |
|---|---|
| Task | unspecified, comment, handoff, task_updates, new_tasks |
| Project | unspecified, task_updates, new_tasks, project_context_update, repository_changes |
The validation is what stops incoherent combinations: comment and handoff need a task to attach to, while project_context_update needs a project.
Authoring your own
A custom action needs a name, a prompt, a context type, an output behavior, and a mutation mode. Two optional settings are worth knowing:
- Provider preference pins the action to a particular agent provider, when it matters that a specific one runs it.
- Additional instructions lets you type one-off context in the launch dialog on top of the saved prompt, which is what makes a general action reusable across specific tasks.
Write the prompt to describe the job, not the mechanics. The launched agent already receives the task or project context and the board tools; a prompt that re-explains the board wastes tokens and tends to age badly.
From automation and from agents
Agent actions are not only launched by hand. A workflow hook can fire one with the run_agent_action action when a task enters or leaves a column, which is how you get "every task arriving in Review gets reviewed" without anyone clicking. See Workflows and hooks.
Agents can read the available actions with list_agent_actions, which returns built-in and custom ones together, and can author new ones with create_agent_action.