> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# task_create

> MCP tool that creates a task on an agent's checklist with subject, description, and dependency edges so the agent picks it up next turn.

Creates a new task in an [agent's](/concepts/agents) 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`](/cli/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. Valid: `files_modified` — met once the agent pushes a commit in the current run touching a file matching `pattern`. |
| `pattern`       | string | no       | Glob matched against the file paths the agent pushes (e.g. `*.go`, `**/*_test.go`). Empty matches any pushed file. Only used with `activate_when: files_modified`.                                                                                                      |
| `slug`          | string | no       | Agent slug. Empty means self. Use an absolute path like `/w/workspace/u/account/slug` to target an agent outside your own path.                                                                                                                                         |
| `workspace`     | string | no       | Workspace name. Overrides the session default.                                                                                                                                                                                                                          |

### Conditional activation

When `activate_when` is set, the task starts in a dormant state and is automatically activated when the condition is met. Currently the only supported condition is `files_modified` — the task activates once the agent pushes a commit in the current run that touches a file matching `pattern`. Activation is evaluated against the files the agent pushes, not against PR contents or which checks CI runs. While dormant, the task does not block the agent from finishing; once activated, the agent must run it and mark it completed.

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. |

## Examples

### Create a simple task

```json theme={null}
{
  "subject": "Add pagination to the users API"
}
```

Response:

```json theme={null}
{
  "task_id": "t_abc123"
}
```

### Create a task on another agent

```json theme={null}
{
  "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

```json theme={null}
{
  "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                                                        |
| ------------------ | --------------------------------------------------- | ----------------------------------------------------------------- |
| `INVALID_ARGUMENT` | Missing `subject` or unknown `activate_when` value. | Check the error message and fix the input.                        |
| `NOT_FOUND`        | No agent with that slug exists.                     | Check the slug. Use [`ls`](/mcp-server/ls) to see running agents. |
| `UNAUTHENTICATED`  | Identity token is missing or expired.               | Check credentials.                                                |

## Related

* [`murmur task create`](/cli/task-create) — equivalent CLI command
* [`task_update`](/mcp-server/task-update) — update a task's status or dependencies
* [`task_list`](/mcp-server/task-list) — list all tasks
* [`task_get`](/mcp-server/task-get) — get a single task
* [`spawn`](/mcp-server/spawn) — create an agent with initial tasks via the `tasks` parameter