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 --jsonOutput
{
"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 --jsonOutput
{
"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
| commands | Lists every command the module offers. |
|---|---|
| selfcheck | Checks the installed file and the database, applies pending database updates and lists any problems in plain words. |
| add | Creates a task with a title and optional details such as a due date, an estimate and prerequisites. |
| update | Changes the details of an existing task. |
| status | Moves a task to a new status, or reopens a finished task on purpose. |
| dep add | Records that one task must wait for another, and refuses a link that would form a loop. |
| dep rm | Removes a recorded prerequisite from a task. |
| get | Returns one task by its identifier. |
| list | Returns tasks filtered by list, status, label or assignee. |
| import | Creates or updates many tasks from one work plan and reports how many were created, updated or unchanged. |
| next | Ranks the tasks that are ready to start and gives the reasons for the order. |
| graph | Returns tasks, their links, the longest chain of dependent work and the estimated effort totals. |
| board | Groups tasks into one column per status. |
| history | Returns the ordered list of changes made to one task. |
| rebuild | Restores the current task list from the recorded history. |
| process metrics | Measures how long tasks wait in each status, how long work takes and how much gets finished. |
| process simulate | Projects finish dates for what-if scenarios such as more capacity or a limit on work in progress. |
| schedule suggest | Suggests who could do which task and when, without changing any task. |
| schedule check | Checks 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.