Bun Do API

bun-do — your local task backend

"Add P1 task: renew passport, due March 30, recurring yearly, with €85 payment"

bun-do is a local-first todo app. REST API at http://localhost:8000. All data persists to JSON on disk. Nothing leaves your machine.

Start: bun-do start (install: bun install -g bun-do) Data: ~/.bun-do/ (override: BUNDO_DATA_DIR) Port: 8000 (override: --port=PORT)

How users talk (map these to API calls)

Important: Always resolve relative dates ("tomorrow", "next Friday") to YYYY-MM-DD before sending.

API reference

Task fields

{
  "title": "string (required)",
  "date": "YYYY-MM-DD (default: today)",
  "priority": "P0 | P1 | P2 | P3 (default: P2)",
  "type": "task | deadline | reminder | payment (default: task)",
  "notes": "string",
  "done": false,
  "amount": "string (for payments)",
  "currency": "CHF | USD | EUR | BRL (default: CHF)",
  "recurrence": null | {"type": "weekly", "dow": 0-6} | {"type": "monthly", "day": 1-31} | {"type": "yearly", "month": 1-12, "day": 1-31}
}

Priorities: P0 = critical/drop everything, P1 = high/do today, P2 = normal, P3 = backlog (not on calendar). Types: task = actionable, deadline = hard date, reminder = FYI, payment = bill/invoice tracker. Recurring: When a recurring task is marked done, the next occurrence is auto-created.

Curl patterns

Before any operation — check server is up

curl -sf http://localhost:8000/api/tasks > /dev/null && echo "OK" || echo "Server not running — run: bun-do start"

Add a task

curl -s -X POST http://localhost:8000/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title": "Buy milk", "date": "2026-03-01", "priority": "P2"}'

Add a recurring payment

curl -s -X POST http://localhost:8000/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title": "Server hosting", "date": "2026-03-01", "priority": "P1", "type": "payment", "amount": "29", "currency": "USD", "recurrence": {"type": "monthly", "day": 1}}'

Find task by title → get ID

curl -s http://localhost:8000/api/tasks | python3 -c "
import sys, json
for t in json.load(sys.stdin)['tasks']:
    if 'SEARCH' in t['title'].lower(): print(t['id'], t['title'])
"

Edit (only send fields to change)

curl -s -X PUT http://localhost:8000/api/tasks/TASK_ID \
  -H 'Content-Type: application/json' \
  -d '{"priority": "P0", "date": "2026-03-15"}'

Mark done

curl -s -X PUT http://localhost:8000/api/tasks/TASK_ID \
  -H 'Content-Type: application/json' \
  -d '{"done": true}'

Delete

curl -s -X DELETE http://localhost:8000/api/tasks/TASK_ID

Add subtask

curl -s -X POST http://localhost:8000/api/tasks/TASK_ID/subtasks \
  -H 'Content-Type: application/json' \
  -d '{"title": "Step one"}'

Log project progress

curl -s -X POST http://localhost:8000/api/projects/PROJECT_ID/entries \
  -H 'Content-Type: application/json' \
  -d '{"summary": "Shipped v1.3 with MCP server and OpenClaw skill"}'

Proactive patterns

Use these patterns for scheduled/autonomous behavior:

Morning briefing: GET /api/tasks, filter for today + overdue, summarize by priority. End of day: Mark completed tasks done, add entries to active projects. Weekly review: List all tasks, highlight overdue + P0/P1 without progress. Payment forecast: List tasks where type=payment, group by month, sum amounts.

Rules

• Always verify the server is running before any API call.
• Never guess IDs — search by title first, then use the UUID.
• Dates must be YYYY-MM-DD. Resolve "tomorrow", "next Monday", etc. before sending.
• Only send fields you want to change on PUT requests.
• The API returns the created/updated object on success.
• GET /api/tasks auto-carries overdue non-payment tasks to today.