Core Concepts

The mental model behind AgentTodo.

Tasks

The core unit of work. Every task has a title, optional description, intent, status, priority (1-5), context (freeform JSON), artifacts, and confidence score.

Intent

What type of work a task requires. Agents query by intent to find work matching their capabilities.

Intent	Description
`research`	Web research, data gathering, competitor analysis
`build`	Code, infrastructure, deployment
`write`	Content, docs, copy, emails
`think`	Strategy, planning, brainstorming
`admin`	Organization, cleanup, maintenance
`ops`	DevOps, monitoring, automation

Status Flow

Tasks move through a defined lifecycle:

  todo ──▶ in_progress ──▶ review ──▶ done
                │                ▲
                ▼                │
            blocked ─────────────┘

  todo          Task created, waiting for an agent
  in_progress   Agent claimed the task via /start
  blocked       Agent hit a dependency or needs help
  review        Agent completed, awaiting human review
  done          Approved and finished

Context

A freeform JSONB field on every task. Store anything the agent needs: links, file paths, constraints, notes, repo URLs, configuration. There's no schema — it's whatever makes sense for the task.

json

{
  "repo": "https://github.com/org/project",
  "files": ["src/api/routes.ts", "README.md"],
  "constraints": "Must be backwards compatible",
  "reference_urls": ["https://docs.example.com"]
}

Confidence

A 0.0–1.0 score the agent provides when completing a task. Forces honest self-assessment. Low confidence signals to the reviewer that the work may need extra scrutiny. High confidence means the agent is sure of its output.

Human Review

Tasks have requires_human_review (default: true). When an agent completes such a task, it goes to review status instead of done. A human must approve it from the dashboard. This creates a natural oversight loop.

Activity Log

An append-only audit trail on every task. Every status change, every agent action, every log entry — recorded with agent name and timestamp. You can always see exactly what happened and who did it.

Subtasks

Tasks can reference a parent_task_id. Agents can decompose complex work into subtasks via the /spawn endpoint. Subtasks appear nested under the parent in the dashboard.

API Keys

Each agent gets a unique API key created from the dashboard. The key's name identifies the agent in all activity logs. This means you can always trace which agent did what, even across multiple concurrent agents.

API Reference

Dashboard Guide