Task Management

ClawVault's task system is file-based and frontmatter-driven. Every task is a Markdown file with YAML frontmatter, stored in your vault's tasks/ directory. This means tasks are searchable, version-controlled, and fully compatible with Obsidian.

Creating Tasks

clawvault task add "Implement auth flow" --project api --owner clawdious --priority high

This creates a Markdown file in tasks/ with frontmatter:

---
id: task-a1b2c3
title: Implement auth flow
status: todo
project: api
owner: clawdious
priority: high
due: 2026-02-20
tags: [backend, auth]
description: Add OAuth callback handling and token refresh.
estimate: 6h
parent: task-z9y8x7
depends_on: [task-k3l4m5]
created: 2026-02-14T13:00:00Z
---

Options

Listing & Filtering

# All tasks
clawvault task list

# Filter by project
clawvault task list --project api

# Filter by owner and status
clawvault task list --owner clawdious --status in-progress

# Filter by due date
clawvault task list --due 2026-02-20

# Filter by tag
clawvault task list --tag backend

# Show overdue tasks
clawvault task list --overdue

# Combine filters
clawvault task list --project api --priority high --status todo

Output shows a compact table with ID, title, status, owner, and priority.

Enriched Task Frontmatter (v2.4.6)

Task files now support richer planning metadata:

Updating Status

Every status change requires a reason and supports optional metadata:

clawvault task update a1b2c3 --status in-progress --reason "starting work" --confidence 0.9

Available Statuses

todo → in-progress → review → done

You can also set blocked from any active status:

clawvault task update a1b2c3 --status blocked --reason "waiting on API keys"

Completing Tasks

The done shorthand completes a task in one step:

clawvault task done a1b2c3 --reason "shipped to production"

Backlog

The backlog is a separate staging area for ideas and future work:

# Add to backlog
clawvault backlog add "Refactor logging system" --project infra

# List backlog items
clawvault backlog list
clawvault backlog list --project infra

# Promote to active task
clawvault backlog promote b4c5d6 --owner clawdious --priority medium

Promoting a backlog item creates a proper task file in tasks/ and removes it from the backlog.

Blocked Task Triage

Quickly see what's stuck:

# All blocked tasks
clawvault blocked

# Only escalated blocked tasks
clawvault blocked --escalated

Transition Ledger

Every status change is logged to a JSONL file in ledger/task-transitions.jsonl. This gives you a complete audit trail:

{"id":"a1b2c3","from":"todo","to":"in-progress","reason":"starting work","agent":"clawdious","confidence":0.9,"ts":"2026-02-14T13:05:00Z"}
{"id":"a1b2c3","from":"in-progress","to":"done","reason":"shipped","agent":"clawdious","ts":"2026-02-14T15:30:00Z"}

Query transitions:

# All transitions for a task
clawvault task transitions a1b2c3

# All transitions by an agent
clawvault task transitions --agent clawdious

# Transitions in a time range
clawvault task transitions --since 2026-02-01

Auto-Escalation

When a task moves to blocked 3 or more times, ClawVault automatically sets an escalation flag in the task's frontmatter. These show up in clawvault blocked --escalated and in the Obsidian Bases blocked.base view.

Regression Detection

Backward transitions (e.g., review → in-progress, done → todo) are flagged in the ledger with "regression": true. This helps identify tasks that keep bouncing back and may need a different approach.

Subtasks and Hierarchy

Use the parent field to link child tasks to a parent task. This is useful for breaking large efforts into smaller, independently trackable units while preserving a clear hierarchy in frontmatter.

Task Dependencies

Use depends_on to model task prerequisites. Dependencies make blocked work explicit and improve planning when coordinating across multiple agents or parallel streams.

Obsidian Integration

ClawVault generates Obsidian Bases views for visual task management:

These are generated during clawvault init and clawvault setup. Open them in Obsidian for spreadsheet-like views of your tasks.

You can also use the Kanban plugin in Obsidian to get a drag-and-drop board view of your tasks, organized by status columns.

Kanban Sync Workflow

# 1) Generate board markdown from task state
clawvault kanban sync

# 2) Edit lanes/cards in Obsidian Kanban (Board.md)

# 3) Import board changes back into task files
clawvault kanban import

kanban import detects lane changes and updates task frontmatter fields such as status, priority, project, and owner.

Multi-Agent Workflows

ClawVault is built for environments where multiple agents (and humans) work on the same vault:

• Owner tracking: Every task has an --owner field. Filter by owner to see each agent's workload.
• Agent transitions: The ledger records which agent made each status change, so you can trace who did what.
• Cost metadata: Attach --cost to transitions to track resource usage per task.
• Confidence scores: Use --confidence (0.0–1.0) to signal how certain an agent is about a transition.

# See what agent-2 is working on
clawvault task list --owner agent-2 --status in-progress

# Check all transitions by a specific agent
clawvault task transitions --agent agent-2

Best Practices

• Checkpoint before heavy work: Run clawvault checkpoint before starting a complex task so you can recover if something goes wrong.
• Review escalated tasks daily: clawvault blocked --escalated surfaces tasks that keep getting stuck. These usually need a human decision.
• Use backlog for ideas: Don't create active tasks for "someday" items. Put them in the backlog and promote when ready.
• Track confidence: When an agent isn't sure about a result, --confidence 0.6 signals that a review is warranted.

Related

• Task command reference
• Kanban command reference
• Backlog command reference
• Multi-Agent Guide
• Obsidian Integration