task_create MCP tool

Creates a new task in an agent’s checklist. Returns the task ID. Tasks appear in the agent’s status and guide the agent through multi-step work. Equivalent to murmur task create in the CLI.

Parameters

Name	Type	Required	Description
`subject`	string	yes	Short summary of the task.
`description`	string	no	Detailed task description.
`activate_when`	string	no	Activation condition name. When set, the task starts dormant and only blocks the agent’s exit once the condition is met; dormant tasks never block. The valid value is `files_modified`, which is met once a push in the current run changes a file matching `pattern`, relative to the PR base branch.
`pattern`	string	no	Glob matched against the file paths the agent’s branch changed relative to its base (e.g. `.go`, `/_test.go`). Empty matches any push. Only used with `activate_when: files_modified`.
`slug`	string	no	Agent slug. Empty means self (on VMs). Use an absolute path like `/w/{workspace}/{owner_provider}/{account}/{slug}` (e.g. `/w/backend/github_oauth/alice/fix-auth`) to target an agent outside your own path.
`workspace`	string	no	Workspace name. Overrides the session default. Required only when nothing else supplies one: off a VM, with no session default, and with a slug that is not a `/w/{workspace}/...` path.

Conditional activation

When activate_when is set, the task starts in a dormant state and is automatically activated when the condition is met. The only supported condition is files_modified: the task activates once a push in the current run changes a file matching pattern. It is evaluated against the branch’s net changes against its base branch. Files brought in by merging or syncing the base branch don’t count, and neither does what CI runs. While dormant, the task does not block the agent from finishing. Once activated, the agent must resolve it. files_modified is run-scoped. A completed task resets to pending at the start of each new run and must be completed again if that run again modifies matching files. This is useful for attaching review or testing tasks that only make sense after specific files change. For example, a task to “run integration tests” that activates when **/*_test.go files are modified.

Response

Returns a JSON object with the created task’s ID.

Field	Type	Description
`task_id`	string	The ID of the created task, unique within the agent’s checklist (e.g. `"1"`).

Examples

Create a simple task

{
  "subject": "Add pagination to the users API"
}

Response:

{
  "task_id": "1"
}

Create a task on another agent

{
  "slug": "fix-auth",
  "subject": "Update the API docs after fixing auth",
  "description": "The OpenAPI spec needs to reflect the new auth flow."
}

Create a conditionally activated task

{
  "subject": "Run integration tests",
  "description": "Verify the test suite passes after modifying test files.",
  "activate_when": "files_modified",
  "pattern": "**/*_test.go"
}

Errors

Code	Meaning	What to do
none	`unknown activation condition "<value>"`: `activate_when` is not `files_modified`.	Use `files_modified`, or omit `activate_when`.
`INVALID_ARGUMENT`	Missing `subject`.	Pass a `subject`.
`NOT_FOUND`	No agent with that slug exists.	Check the slug. Use `ls` to see running agents.
`UNAUTHENTICATED`	Identity token is missing or expired.	Check credentials.

murmur task create: equivalent CLI command
task_update: update a task’s status or dependencies
task_list: list all tasks
task_get: get a single task
spawn: create an agent with initial tasks via the tasks parameter

Getting Started

Core Concepts

Guides

task_create MCP tool

Parameters

Conditional activation

Response

Examples

Create a simple task

Create a task on another agent

Create a conditionally activated task

Errors

​Parameters

​Conditional activation

​Response

​Examples

​Create a simple task

​Create a task on another agent

​Create a conditionally activated task

​Errors

​Related

Parameters

Conditional activation

Response

Examples

Create a simple task

Create a task on another agent

Create a conditionally activated task

Errors

Related