Todozi

Quick Start

As SDK:

from skills.todozi.scripts.todozi import TodoziClient

client = TodoziClient(api_key="your_key")
matrices = await client.list_matrices()
task = await client.create_task("Build feature", priority="high")
await client.complete_item(task.id)

As LangChain Tools:

from skills.todozi.scripts.todozi import TODOZI_TOOLS
# Add to agent tools list

SDK Overview

Class

Purpose

TodoziClient	Async API client
TodoziTask	Task dataclass
TodoziMatrix	Matrix dataclass
TodoziStats	Stats dataclass

Environment

export TODOZI_API_KEY=your_key
export TODOZI_BASE=  # optional, default provided

Client Methods

Matrices

# List all matrices
matrices = await client.list_matrices()

# Create matrix
matrix = await client.create_matrix("Work", category="do")

# Get matrix
matrix = await client.get_matrix("matrix_id")

# Delete matrix
await client.delete_matrix("matrix_id")

Tasks / Goals / Notes

# Create task
task = await client.create_task(
    title="Review PR",
    priority="high",
    due_date="2026-02-01",
    description="Check the new feature",
    tags=["pr", "review"],
)

# Create goal
goal = await client.create_goal("Ship v2", priority="high")

# Create note
note = await client.create_note("Remember to call Mom")

# Get item
item = await client.get_item("item_id")

# Update item
updated = await client.update_item("item_id", {"title": "New title", "priority": "low"})

# Complete item
await client.complete_item("item_id")

# Delete item
await client.delete_item("item_id")

Lists

# List tasks (with filters)
tasks = await client.list_tasks(status="todo", priority="high")

# List goals
goals = await client.list_goals()

# List notes
notes = await client.list_notes()

# List everything
all_items = await client.list_all()

Search

Searches only: title, description, tags (NOT content)

results = await client.search(
    query="pr",
    type_="task",          # task, goal, or note
    status="pending",
    priority="high",
    category="do",
    tags=["review"],
    limit=10,
)

Bulk Operations

# Update multiple
await client.bulk_update([
    {"id": "id1", "title": "Updated"},
    {"id": "id2", "priority": "low"},
])

# Complete multiple
await client.bulk_complete(["id1", "id2"])

# Delete multiple
await client.bulk_delete(["id1", "id2"])

Webhooks

# Create webhook
webhook = await client.create_webhook(
    url="",
    events=["item.created", "item.completed"],
)

# List webhooks
webhooks = await client.list_webhooks()

# Update webhook
await client.update_webhook(webhook_id, url, ["*"])

# Delete webhook
await client.delete_webhook(webhook_id)

System

# Stats
stats = await client.get_stats()

# Health check
health = await client.health_check()

# Validate API key
valid = await client.validate_api_key()

# Register (get API key)
keys = await client.register(webhook="")

LangChain Tools

The skill provides @tool decorated functions for agent integration:

from skills.todozi.scripts.todozi import TODOZI_TOOLS

# Available tools:
# - todozi_create_task(title, priority, due_date, description, thread_id, tags)
# - todozi_list_tasks(status, priority, thread_id, limit)
# - todozi_complete_task(task_id)
# - todozi_get_stats()
# - todozi_search(query, type_, status, priority, limit)
# - todozi_list_matrices()

Categories

Category

Description

do	Do now (urgent + important)
delegate	Delegate (urgent + not important)
defer	Defer (not urgent + important)
done	Completed items
dream	Goals/dreams (not urgent + not important)
dont	Don't do (neither)

Common Patterns

Auto-create default matrix:

task = await client.create_task("My task")  # Creates "Default" matrix if needed

Get stats with completion rate:

stats = await client.get_stats()
rate = stats.completed_tasks / stats.total_tasks * 100 if stats.total_tasks > 0 else 0

Search with multiple filters:

results = await client.search("feature", type_="task", status="pending", priority="high")

Complete multiple tasks:

tasks = await client.list_tasks(status="todo")
ids = [t.id for t in tasks[:5]]
await client.bulk_complete(ids)