Skip to content
Menu

Tasks module

Keeps a lasting list of work, what each task depends on, and what is ready to do next.

On this page

What it is for

Keeps a lasting list of work, what each task depends on, and what is ready to do next.

  • You want the bot to remember work across conversations.
  • You want to know what is ready to start and why.
  • You want a board or summary of open work in a Grok Bot Page.
  • You want a rough view of when a list of work could finish.

Ask your bot

You do not type commands. Ask in plain words and the bot runs the module for you.

You ask
We need to renew the supplier agreement, and it has to wait for the new price list. Add both, then tell me what I can start on today.
What you get back
The bot records both tasks and the link between them, then replies with a ranked list of the work that is ready now and the module's reason for each.

What the bot does with it

  • The bot records work you mention as tasks, with a clear description of what done means.
  • It links tasks that must wait for other tasks, so nothing is suggested before its prerequisites are finished.
  • When you ask what to do next, it runs the module and relays the ranked list with the module's reasons.
  • It can show the work as a board in a Grok Bot Page, using only the data the module returns.
  • Workload totals, finish date projections and schedule suggestions come from the module and are estimates, not promises.

What it stores

Tasks, their prerequisites and a history of every change live in one SQLite file, tasks/tasks.sqlite, in the bot's Ambitious folder (/workspace/ambitious by default). History entries are added and never edited.

The module has no screens of its own. It reads JSON, writes JSON, and keeps its data under /workspace/ambitious on the bot's computer. It never sends data anywhere.

Command reference

For the technically curious. You will rarely type these yourself; the bot runs them. Every command answers with the same envelope: whether it worked, which module and command ran, the data, and a list of errors with a hint for each. Open an example to see the command and its output.

ExampleAsk which tasks are ready to start. Each task comes with the reasons for its rank.

Command

ambitious-tasks next --json

Output

{
  "ok": true,
  "schemaVersion": 1,
  "module": "tasks",
  "command": "next",
  "data": {
    "ranked": [
      {
        "id": "send-march-invoices",
        "title": "Send the March invoices",
        "score": 2,
        "reasons": ["all dependencies done", "on critical path", "due 2026-03-31", "priority 1", "estimate 1 days", "id send-march-invoices"]
      },
      {
        "id": "order-supplies",
        "title": "Order office supplies",
        "score": 1,
        "reasons": ["all dependencies done", "outside critical path", "no due date", "priority 2", "no estimate", "id order-supplies"]
      }
    ]
  },
  "errors": [],
  "meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}
ExampleA refused request. Sending the invoices already waits for preparing them, so the reverse link would form a loop and nothing is saved.

Command

echo '{"task_id":"prepare-march-invoices","depends_on":"send-march-invoices","idem_key":"link-prepare-after-send"}' | ambitious-tasks dep add --json

Output

{
  "ok": false,
  "schemaVersion": 1,
  "module": "tasks",
  "command": "dep add",
  "data": {
    "cycle": ["prepare-march-invoices", "send-march-invoices", "prepare-march-invoices"]
  },
  "errors": [
    {
      "code": "E_CYCLE",
      "message": "This dependency would form a cycle.",
      "hint": "Remove an edge from data.cycle before adding this dependency."
    }
  ],
  "meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}
Show every command
commandsLists every command the module offers.
selfcheckChecks the installed file and the database, applies pending database updates and lists any problems in plain words.
addCreates a task with a title and optional details such as a due date, an estimate and prerequisites.
updateChanges the details of an existing task.
statusMoves a task to a new status, or reopens a finished task on purpose.
dep addRecords that one task must wait for another, and refuses a link that would form a loop.
dep rmRemoves a recorded prerequisite from a task.
getReturns one task by its identifier.
listReturns tasks filtered by list, status, label or assignee.
importCreates or updates many tasks from one work plan and reports how many were created, updated or unchanged.
nextRanks the tasks that are ready to start and gives the reasons for the order.
graphReturns tasks, their links, the longest chain of dependent work and the estimated effort totals.
boardGroups tasks into one column per status.
historyReturns the ordered list of changes made to one task.
rebuildRestores the current task list from the recorded history.
process metricsMeasures how long tasks wait in each status, how long work takes and how much gets finished.
process simulateProjects finish dates for what-if scenarios such as more capacity or a limit on work in progress.
schedule suggestSuggests who could do which task and when, without changing any task.
schedule checkChecks a proposed set of assignments and lists every rule it breaks.

Source and releases

The module is open source under the Apache license. Each release carries one bundled file and its checksums; the bot installs it for you.