> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/features/goals-and-todos.md).

# Goals & Todos

OpenHuman keeps the agent aligned with what you actually care about through three complementary layers: durable **long-term goals**, a single **thread goal** per conversation, and a collaborative **task board** of todos. Each one is editable by both you and the agent, and all of them survive restarts.

***

## Long-term goals

A short, human-readable list of your durable objectives — things like *"Ship the desktop app"* or *"Grow the community to 10k."* It lives as a plain Markdown file (`MEMORY_GOALS.md`) in your workspace, so you can open and edit it directly.

The list is deliberately tiny — capped at roughly **8 items / 500 tokens** — so it's cheap for the agent to read on every relevant turn and easy for you to keep honest. Each goal gets a stable short id (`g1`, `g2`, …) so it can be edited or deleted without depending on order.

* **Goals Panel** (Intelligence → Goals) shows the list with add / edit / delete actions.
* **Reflect** runs a background `goals_agent` that reviews your goals against recent memory and conversation, then makes minimal, justified changes — adding what you've clearly started pursuing, retiring what you've dropped. On first run it bootstraps an initial set from your context.
* The agent reads and updates the same list mid-conversation via its `goals_list` / `goals_add` / edit tools, so your edits and the agent's stay in lock-step.

RPC surface: `openhuman.memory_goals_list` / `_add` / `_edit` / `_delete` / `_reflect`.

***

## Thread goals

Each conversation can carry **one** thread goal — a durable "completion contract" the agent works across turns, interrupts, resumes, and budget boundaries. A thread goal has an objective, a status, and an optional **token budget** so you can cap how much work a thread is allowed to consume.

| Status           | Meaning                                                                |
| ---------------- | ---------------------------------------------------------------------- |
| `active`         | The agent may keep working the objective.                              |
| `paused`         | Suspended (e.g. you interrupted); reactivates when the thread resumes. |
| `budget_limited` | Tokens spent ≥ budget; substantive work halts until you raise it.      |
| `complete`       | Objective satisfied.                                                   |

The orchestrator sets a goal with `goal_set`, reads it with `goal_get`, and finishes it with `goal_complete`. Updates emit `thread/goal/updated` events so the UI stays live.

**Autonomous idle continuation.** If a thread has an active goal and goes idle — no in-flight turn, no activity for a configured interval (e.g. 10 minutes) — the [heartbeat](/openhuman/features/subconscious.md) can inject a single continuation turn that resumes the transcript and keeps working the objective. It's opt-in (`heartbeat.goal_continuation_enabled`) and guarded by a one-shot suppression flag per idle period, so the agent never self-drives into a loop.

***

## Task board (todos)

Every conversation also hosts a **kanban-style task board** — a list of discrete work cards that you and the agent build together. Unlike a thread goal (one durable objective), the board is a collection of concrete items, each with rich structure:

* Title / description, and a **status**: `todo`, `in_progress`, `awaiting_approval`, `ready`, `blocked`, `done`, `rejected`.
* Optional objective and desired outcome.
* An ordered **execution plan**, **acceptance criteria** checklist, assigned agent, and an **approval mode** (required / not required).
* Notes, blocker reason, and evidence / links.

The agent reads the board with `todo_list`, appends with `todo_add`, edits with `todo_edit`, and advances status with `todo_update_status`. Destructive operations (clear / remove / replace) are disabled by default. You and the agent share the same persistence, so edits stay consistent.

Two reserved boards back special views:

* **`user-tasks`** — your personal task list, not attached to any conversation. Create and manage these from the **User Task Composer** (Intelligence → Tasks). You can optionally attach a task to a conversation and assign it to the orchestrator with `approvalMode: not_required`, so the background dispatcher auto-picks and runs it.
* **`task-sources`** — an inbox for tasks ingested from external sources before they're promoted to an agent workstream.

RPC surface: `openhuman.todos_list` / `_add` / `_edit` / `_update_status` / `_set_session_thread`. Responses include a rendered `markdown` field so the board renders identically in the UI and in agent transcripts.

***

## How the three relate

| Layer              | Scope              | Count        | Who drives it                        |
| ------------------ | ------------------ | ------------ | ------------------------------------ |
| Long-term goals    | Your whole account | \~8 max      | You + periodic `goals_agent` reflect |
| Thread goal        | One conversation   | 1 per thread | Orchestrator, with optional budget   |
| Task board (todos) | One conversation   | Many cards   | You + agent, collaboratively         |

***

## See also

* [Subconscious Loop](/openhuman/features/subconscious.md) — the background loop that powers idle continuation and task evaluation.
* [Memory Tree](/openhuman/features/obsidian-wiki/memory-tree.md) — what goal reflection reads from.
* [SuperContext](/openhuman/features/super-context.md) — first-turn grounding that complements goal-driven work.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/features/goals-and-todos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.