# Guides

The tool sequences behind the things people ask for. Each guide names the calls in order; the [tool reference](/developers/tools) has every parameter.

## Start every conversation oriented

Call `get_context` before anything else that touches the workspace. One call, about a thousand tokens, and the model knows the person's name and timezone, what is due, what is in progress, their lists with their ids and property ids, and what they asked Koma to remember. Every later call can then name an id instead of searching for it.

For a conversation that is about one list, pass `focusListId` to narrow the task sections.

## Make Koma the to-do list your assistant reaches for

No AI chat has a "default task app" setting. What decides where "add this to my list" lands is the tool description the model reads and the instructions the person gave. Two lines do most of the work:

1. Add this to the chat's custom instructions, a Claude project's instructions, or the memory the assistant keeps:

   > Koma is my task app. At the start of a conversation about my work, plans or anything I keep, call Koma's get_context to see my tasks, notes and what I asked it to remember. When I mention something I need to do, add it to Koma as a task. When I ask what to work on next or what is on my plate, answer from Koma.

2. In Claude, set Koma's read-only tools to Always allow under Customize, then Connectors, so the orientation call runs without a prompt. In ChatGPT, choose the permission level for the plugin that suits you.

After that, "remind me to call the dentist tomorrow" becomes `create_items` on the Tasks list with a due time, and "what did I decide about the lease?" becomes `search` followed by `get_item`.

## Save research as a note

A person asks the assistant to research something and keep the result.

1. `list_lists` to find the list it belongs on, by name. If none fits, `listId: "notes"` lands it on the Notes list.
2. `create_items` with one entry: a title and the body as Markdown. Headings, lists and links survive; nothing is rewritten.
3. Later additions go through `update_items` with `edits`: an `insert` at the `end` of the body, or at the `sectionEnd` of the heading they belong under. The older `body` with `mode: "append"`, or `insertAfter` with an `anchor` line, still works.

Before creating, `search` the topic once. What the person refers to usually already exists, and a second copy drifts from the first.

## Fill a list from a conversation

"Add these five books to my reading list."

1. `list_lists` to find the list and its properties with their ids.
2. `create_items` with the list's id and one entry per book, its `values` as `{ propertyId, value }` pairs keyed by property id or name. A select value may be a label; an unknown label becomes a new option.
3. Pass `matchOn` (the property that names the thing, say) when the same batch might be sent twice, so a retry merges instead of duplicating.
4. Corrections go through `update_items`, never a second create: only the values you send change.

## Work from a task

An agent that does the work, not just the reminding.

1. `get_item` for the task: its body with a short handle in front of every block, its `bodyVersion`, a line of `guidance` about its state, and its list. `read_chat_messages` for what the person said there.
2. `update_items` with `taskStatus: "inProgress"` when the work actually starts, so the person sees it moving.
3. Do the work in the body with `update_items` `edits`: `replace` a block, `insert` next to one, `setChecked` a checklist item, `delete`, `move`, `replaceText`, or `rewrite` the whole body with the `bodyVersion` read. Continue what is already there; never add a second copy of it. (The older `body` with `mode` append / prepend / insertAfter / replace still works.)
4. Leave it in progress. `completed` is the person's call. Post in the chat with `post_chat_message` only for an action taken outside Koma, with its link, or the one question the work is blocked on.

A call that changes nothing returns the item without writing. A conflict with a write Koma made a moment earlier is retried once on the server, so an edit right after a create lands.

## Run a worker loop

Koma as the queue for an agent that runs on its own: the person files tasks from their phone, the agent picks them up, does the work, and reports in the task's chat, where the person answers.

1. Read by cursor, once per cycle. `list_items` with `changedSince` set to the previous cycle's `nextChangedSince` (the first time, the instant the worker started) answers every item on the Tasks set whose record moved since, oldest change first, the deleted ones under `deleted`, and `nextChangedSince` for the next cycle. `listId` narrows it to one list. Never re-read the whole list each cycle.
2. Pick up a task that is `todo` and set it `inProgress` with `update_items` the moment work starts. Leave it there when the work is done; `completed` is the person's call.
3. Do the work in the body with `update_items` `edits`. Post in the chat with `post_chat_message` for an action taken outside Koma, with its link, or the one question the work is blocked on, with `needsInput: true`.
4. Read the person's answer with `read_chat_messages` and `since` set to the `createdAt` of the last message the worker saw. The chat is how the person steers the agent; the body is where the work lands.
5. A cycle every minute or two is plenty. The limit is 60 calls a minute per connection, and a worker on cursors makes two or three calls a cycle.

The [event feed](/developers/events) will replace the polling read once an event fires for a task waiting on an agent.

## Read what an automation found

"What did my morning briefing say today?"

1. `list_automations`, which also rides `get_context`, to find the automation's id.
2. `get_automation_runs` for its recent runs: the closing message each run left, what it did, when.

To start one, `run_automation`. The client asks first, because a run can act through the person's connected apps; the result lands in their Koma chat and `get_automation_runs` reads it back a moment later.

## Undo

Every delete is soft. `list_deleted` shows the trash with each entry's purge day; `restore_deleted` with the entry's type (`item` or `list`) and id brings it back. Restoring a list brings back the items deleted with it. An item whose list is still in the trash asks you to restore the list first; one whose list is gone for good lands on the Tasks list.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| "not found" for an id you just read | The id belongs to another person, or the item was deleted since | Read it again; check `list_deleted` |
| `update_items` refused a replace | A whole-body replacement needs `confirmReplace: true` | Prefer `edits`, or `append` and `insertAfter`; confirm only when the person asked to rewrite |
| Items were added twice | `create_items` without `matchOn` inserts every entry | Pass `matchOn`; fix the duplicates with `delete_items` |
| A select value was rejected | The value is neither an option id nor a label | Read the property's options from `list_lists` |
| An item moved to the wrong list | The destination id was guessed | Resolve it with `list_lists` first |
| `move_items` answered a preview and moved nothing | The destination has no place for some of the values | Tell the person what would be dropped; repeat with `acknowledgeDataLoss: true` only once they agree |
| The conversation cannot see a new tool | The client cached the tool list | Refresh the connector, start a new conversation |