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

# murmur task create

> Add a new task to an agent's checklist with a subject, description, and optional dependency edges so the agent picks it up on the next turn.

Adds a new [task](/concepts/agents) to an [agent's](/concepts/agents) checklist. Returns the ID of the created task.

Tasks are checklist items that track what an [agent](/concepts/agents) needs to do. Each [task](/concepts/agents) has a subject line, an optional description, and an optional activation condition that keeps the [task](/concepts/agents) dormant until a trigger fires.

## Synopsis

```bash theme={null}
murmur task create [flags] [slug] <subject>
```

On a VM, the slug is optional — omitting it creates a [task](/concepts/agents) on the current [agent's](/concepts/agents) own checklist.

## Arguments

| Name              | Type   | Required  | Description                                                                                                                                                                                                                                                                                              |
| ----------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`            | string | on laptop | The [agent's](/concepts/agents) slug. Optional on VMs (defaults to self).                                                                                                                                                                                                                                |
| `subject`         | string | yes       | Short summary of the [task](/concepts/agents).                                                                                                                                                                                                                                                           |
| `-d`              | string | no        | Detailed [task](/concepts/agents) description.                                                                                                                                                                                                                                                           |
| `--activate-when` | string | no        | Activation condition name. When set, the [task](/concepts/agents) stays dormant — it doesn't block the [agent](/concepts/agents) — until the condition is met. Valid: `files_modified` — met once the [agent](/concepts/agents) pushes a commit in the current run touching a file matching `--pattern`. |
| `--pattern`       | string | no        | Glob pattern for file matching. Used with `--activate-when files_modified`. Supports `path.Match` syntax plus `**` for recursive directory matching.                                                                                                                                                     |
| `--workspace`     | string | no        | [Workspace](/concepts/workspaces) name. Overrides the value from `murmur.yaml`.                                                                                                                                                                                                                          |

## Examples

### Create a basic task

```bash theme={null}
murmur task create fix-auth "Add rate limiting to the login endpoint"
```

```
t_8f3a1b2c
```

### Create a task with a description

```bash theme={null}
murmur task create fix-auth -d "Limit to 5 attempts per minute per IP" "Add rate limiting to the login endpoint"
```

```
t_8f3a1b2c
```

### Create a conditionally activated task

This [task](/concepts/agents) stays dormant until the [agent](/concepts/agents) pushes a commit that modifies a Go test file:

```bash theme={null}
murmur task create fix-auth --activate-when files_modified --pattern "**/*_test.go" "Run the full test suite"
```

```
t_9d4e2f1a
```

The [task](/concepts/agents) only appears in [`murmur task ls --active`](/cli/task-ls) after the [agent](/concepts/agents) pushes a matching file.

### Self-create on a VM

When running on an [agent](/concepts/agents) VM, omit the slug:

```bash theme={null}
murmur task create "Update the migration script"
```

```
t_7c5b3a0e
```

## Errors

| Code               | Meaning                                             | What to do                                                                                     |
| ------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `NOT_FOUND`        | No [agent](/concepts/agents) with that slug exists. | Check the slug spelling. Use [`murmur ls`](/cli/ls) to see running [agents](/concepts/agents). |
| `UNAUTHENTICATED`  | Identity token is missing or expired.               | Run `murmur auth` or check your `murmur.local.yaml` configuration.                             |
| `INVALID_ARGUMENT` | Unknown activation condition.                       | Use a valid `--activate-when` value. Currently only `files_modified` is supported.             |

## Related

* [Agents](/concepts/agents) — concept overview
* [`murmur task update`](/cli/task-update) — change a [task's](/concepts/agents) status, subject, or dependencies
* [`murmur task ls`](/cli/task-ls) — list all [tasks](/concepts/agents) on an [agent's](/concepts/agents) checklist
* [`murmur task get`](/cli/task-get) — retrieve details for a single [task](/concepts/agents)
* [`murmur status`](/cli/status) — query [agent](/concepts/agents) status
* [`murmur spawn`](/cli/spawn) — start an [agent](/concepts/agents)