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.
Every agent has a task checklist — a structured list of items the agent should complete. Tasks support dependencies, activation conditions, and status tracking. You can pre-populate tasks at spawn time or manage them dynamically while the agent runs.
murmur task create
Create a new task in an agent’s checklist.
murmur task create [slug] <subject> [flags]
slug is omitted, the command targets the current agent (when run from within a VM).
Flags
| Flag | Short | Type | Description |
|---|
-d | | string | Detailed description of the task |
--activate-when | | string | Activation condition name. Task is dormant until the condition is met. |
--pattern | | string | Glob pattern for file matching. Only used with files_modified. |
# Simple task
murmur task create fix-auth-bug "Fix the session timeout"
# Task with description
murmur task create fix-auth-bug "Update error handling" \
-d "Refactor the error handling in auth.go to use wrapped errors instead of string matching"
# Task with activation condition
murmur task create fix-auth-bug "Run linter on modified Go files" \
--activate-when files_modified \
--pattern "*.go"
# Task that activates when test files change
murmur task create fix-auth-bug "Re-run test suite" \
--activate-when files_modified \
--pattern "**/*_test.go"
Created task: task_01HXYZ123
Activation conditions
| Condition | Description |
|---|
files_modified | Task activates when files matching --pattern are modified by the agent |
murmur task update
Update an existing task’s status, subject, description, or dependency edges.
murmur task update [slug] <task-id> [flags]
Flags
| Flag | Short | Type | Description |
|---|
-s | | string | New task status: pending, in_progress, completed, blocked |
--subject | | string | New task subject line |
-d | | string | New task description |
--blocks | | string | Comma-separated task IDs that this task blocks |
--blocked-by | | string | Comma-separated task IDs that block this task |
# Mark a task as in progress
murmur task update fix-auth-bug task_01HXYZ123 -s in_progress
# Mark a task as completed
murmur task update fix-auth-bug task_01HXYZ123 -s completed
# Update the subject
murmur task update fix-auth-bug task_01HXYZ123 --subject "Fix session timeout and add tests"
# Update the description
murmur task update fix-auth-bug task_01HXYZ123 \
-d "Also need to update the integration tests for the new timeout behavior"
# Add dependency: this task blocks another
murmur task update fix-auth-bug task_01HXYZ123 --blocks task_01HXYZ456
# Add dependency: this task is blocked by another
murmur task update fix-auth-bug task_01HXYZ789 --blocked-by task_01HXYZ123
Task statuses
| Status | Description |
|---|
pending | Not yet started. The default state for new tasks. |
in_progress | Currently being worked on by the agent. |
completed | Finished successfully. |
blocked | Cannot proceed until blocking tasks are completed. |
Dependencies
Tasks can express ordering constraints through dependency edges:
--blocks: “This task must complete before task X can start.” Task X is automatically set to blocked status.--blocked-by: “This task cannot start until task Y completes.” This task is automatically set to blocked status.
# Create a dependency chain: design → implement → test
murmur task create fix-auth-bug "Design the fix"
# Created: task_design
murmur task create fix-auth-bug "Implement the fix"
# Created: task_impl
murmur task create fix-auth-bug "Write tests"
# Created: task_test
# Wire up dependencies
murmur task update fix-auth-bug task_impl --blocked-by task_design
murmur task update fix-auth-bug task_test --blocked-by task_impl
task_design is marked completed, task_impl is automatically unblocked. When task_impl completes, task_test is unblocked.
murmur task ls
List all tasks in an agent’s checklist.
murmur task ls [slug] [flags]
Flags
| Flag | Type | Description |
|---|
--json | bool | Output as JSON array |
--active | bool | Show only active (non-completed, non-dormant) tasks |
# List all tasks
murmur task ls fix-auth-bug
# Active tasks only
murmur task ls fix-auth-bug --active
# JSON output for scripting
murmur task ls fix-auth-bug --json
Example output
ID STATUS SUBJECT
task_01HXYZ123 completed Design the fix
task_01HXYZ456 in_progress Implement the fix
task_01HXYZ789 blocked Write tests (blocked by: task_01HXYZ456)
task_01HXYZ000 dormant Run linter on modified Go files (activates on: *.go modified)
murmur task get
Get a single task by ID with full details.
murmur task get [slug] <task-id>
murmur task get fix-auth-bug task_01HXYZ456
Example output
id: task_01HXYZ456
subject: Implement the fix
description: >
Refactor the error handling in auth.go to use wrapped errors
instead of string matching. Follow the pattern in errors.go.
status: in_progress
blocked_by:
- task_01HXYZ123 (completed)
blocks:
- task_01HXYZ789 (blocked)
created_at: 2025-01-15T10:23:45Z
updated_at: 2025-01-15T10:45:12Z
Pre-populating tasks at spawn time
Use --task flags with murmur spawn to set up the checklist when creating an agent:
murmur spawn fix-auth-bug "Fix the authentication timeout" \
--task "Identify the root cause in session.go" \
--task "Implement the fix" \
--task "Add unit tests" \
--task "Add integration tests" \
--task "Update documentation" \
--out pr
pending status. The agent sees the checklist and works through items in order.
murmur subscriptions
Manage file and branch change subscriptions for agents. Subscriptions notify an agent when specific files or branches are modified.
subscriptions add
Add a subscription for file or branch changes:
murmur subscriptions add <slug> [flags]
Flags
| Flag | Type | Description |
|---|
--branch | string | Branch name to watch for changes |
--file | string | File path or glob pattern to watch. Repeatable. |
# Watch for changes to a specific branch
murmur subscriptions add fix-auth-bug --branch main
# Watch for changes to specific files
murmur subscriptions add fix-auth-bug --file "src/auth/**/*.go"
# Watch for multiple file patterns
murmur subscriptions add fix-auth-bug \
--file "src/auth/**/*.go" \
--file "config/auth.yaml"
# Watch both branch and files
murmur subscriptions add fix-auth-bug \
--branch main \
--file "src/auth/**/*.go"
file_changed event with details about what changed.
subscriptions remove
Remove a specific subscription:
murmur subscriptions remove <slug> [flags]
murmur subscriptions remove fix-auth-bug --branch main
murmur subscriptions remove fix-auth-bug --file "src/auth/**/*.go"
subscriptions flush
Remove all subscriptions for an agent:
murmur subscriptions flush <slug>
murmur subscriptions flush fix-auth-bug
subscriptions ls
List all subscriptions for an agent:
murmur subscriptions ls <slug>
murmur subscriptions ls fix-auth-bug
Example output
TYPE PATTERN
branch main
file src/auth/**/*.go
file config/auth.yaml
Common workflows
Set up a task-driven agent
# Spawn with pre-populated tasks
murmur spawn feature-impl "Implement the new user profile feature" \
--task "Add database migration for profile fields" \
--task "Create API endpoints (GET, PUT)" \
--task "Write handler tests" \
--task "Update OpenAPI spec" \
--out pr
# Monitor task progress
murmur task ls feature-impl
Add reactive tasks to a running agent
# Add a task that fires when Go files change
murmur task create feature-impl "Run go vet on modified files" \
--activate-when files_modified \
--pattern "*.go"
# Add a task that fires when test files change
murmur task create feature-impl "Verify test coverage stays above 80%" \
--activate-when files_modified \
--pattern "**/*_test.go"
Build a dependency chain
murmur task create feature-impl "Design the API schema"
# → task_design
murmur task create feature-impl "Implement handlers"
# → task_handlers
murmur task create feature-impl "Write tests"
# → task_tests
murmur task create feature-impl "Update documentation"
# → task_docs
# Wire dependencies
murmur task update feature-impl task_handlers --blocked-by task_design
murmur task update feature-impl task_tests --blocked-by task_handlers
murmur task update feature-impl task_docs --blocked-by task_handlers
Watch for upstream changes
# Subscribe to main branch changes
murmur subscriptions add feature-impl --branch main
# Subscribe to relevant file changes
murmur subscriptions add feature-impl --file "src/api/**/*.go"
# Agent receives file_changed events and can rebase or adapt
