Guides

The tool sequences behind the things people ask for. Each guide names the calls in order; the tool reference 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 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