Tasks

Tasks are like alarms for your agent. You define a prompt (what to do) and a schedule (when to do it), and Nod triggers your agent automatically at the right time. The agent executes the task, and the result is delivered to your phone as a rich card.

Tasks can be created in two ways:

• From the Nod app — create tasks directly from your phone. Set a name, prompt, and schedule. The task appears in your task list and triggers automatically.
• From the agent itself — agents can propose tasks to you. When an agent notices a pattern ("you check git activity every morning"), it can suggest a recurring task. The proposal appears as an approval card on your phone — tap to approve and the task is created automatically.

Via the API, tasks can be created by users (JWT auth) or by agents (agent auth):

POST /api/tasks/:agent_id
{
  "name": "Daily standup summary",
  "prompt": "Summarize yesterday's git commits and open PRs. Keep it under 200 words.",
  "schedule": "0 9 * * 1-5"
}

POST /api/agent/tasks
{
  "name": "Health check",
  "prompt": "Run the test suite and report any failures.",
  "schedule": "0 */6 * * *"
}

Task proposals

Agents can also propose tasks to the user for approval. The proposal appears as an approval card — if the user approves, the task is automatically created:

// Via REST or WebSocket
{
  "type": "task_proposal",
  "title": "Schedule task: Daily summary",
  "task_name": "Daily summary",
  "task_prompt": "Summarize git activity and open PRs",
  "task_schedule": "0 9 * * 1-5"
}

When a task is due, Nod pushes a task_due event to your agent via WebSocket or webhook — just like a user message. The run is already started server-side. Your agent executes the prompt and reports the result:

// 1. Receive task_due event (via WebSocket or webhook)
// { "type": "task_due", "run_id": "run_abc123", "task_prompt": "...", ... }

// 2. Execute the task prompt (your agent does its work)

// 3. Complete the run — the chat message is created automatically
POST /api/agent/tasks/runs/run_abc123/complete
{
  "status": "completed",
  "summary": "## Summary\n\n- **12 commits** across 3 PRs\n- 2 issues closed"
}

Requesting user input during tasks

Tasks can send requests (approvals, questions, choices) to the user mid-execution via the Requests API. The request appears in the user's Requests inbox with a "Task" badge — not in the chat. Pass task_run_id when creating the request so the resolution event includes it for routing.

Persisting state across pauses

If your task pauses for user input (e.g., a decision request), use the task context scratchpad to save intermediate state. When the user responds and your agent resumes, read the context back to continue where you left off.

Event tasks are triggered by external webhooks instead of a schedule. Create one by setting schedule: "event":

POST /api/agent/tasks
{
  "name": "Process GitHub push",
  "prompt": "Analyze the push event and summarize the changes.",
  "schedule": "event"
}

The response includes a trigger_id. Configure the webhook URL in your external service:

https://api.asknod.ai/webhook/{trigger_id}

When the external service sends a POST, the payload is delivered to your agent as part of the task. If your agent is online (WebSocket), the event arrives instantly. If offline, it's delivered to your agent's webhook_url if configured, or queued until your agent polls for pending triggers.

When using the Nod CLI with Claude Code, tasks have additional capabilities:

• Agent-proposed tasks — while chatting, the agent can suggest tasks using nod-task-create. For example, if you ask it to check the news, it might propose a daily news digest task. You approve it from your phone and it runs automatically every day.
• Rich deliverables — task results are set via nod-task-output and rendered as tappable cards in the Nod app with full markdown support (headers, tables, lists, code blocks).
• Activity logging — while a task runs, the agent logs progress steps (searches, API calls, file operations) visible in the task detail view.
• Referencing past tasks — the agent can fetch results from previous task runs using nod-task-run. Ask "save yesterday's news report to a file" and the agent retrieves the task output and writes it.
• Parallel execution — tasks run in their own isolated Claude Code sessions, parallel to the main chat. You can keep chatting while a task runs in the background.

Every task execution is tracked as a task run with status, timing, and an optional summary. Users can view run history in the Nod app, and activity events logged during a run are associated with it.