Task Steps and Markdown Notes

Task steps are lightweight subtasks: checklist items inside a Vist task. Task notes are Markdown text on the task itself. You and your AI agents can read and write both, in the app or through MCP and the Vist CLI.

Break a task into a checklist of steps, keep its context in Markdown notes, and let your coding agent tick steps off as it works. What's new is in the changelog.

What they are

• Notes are the body of a task: context, links, a plan, a snippet of code. They're written in Markdown and rendered in the task detail panel.
• Steps are an ordered checklist on a task, like the steps in a to-do app. A step is a title and a checkbox. It has no due date, priority or labels of its own, and it doesn't appear in your task lists by itself.

Both live on the task, so the task's due date, priority, labels and linked note work as before. See Task Management for the basics.

Markdown notes

In the app, a task's notes are its Description in the detail panel. Click it (or "Add a description…") to edit it in a plain text area ("Markdown supported"). Click away and it renders as formatted text.

• What renders: bold, italics, lists, links, inline code, fenced code blocks, tables and strikethrough. Line breaks are kept.
• Links open in a new tab. Clicking a link doesn't open the editor.
• Not supported: images and raw HTML. Unsafe links and scripts are stripped.
• Length: up to 20,000 characters.

Steps

The task detail panel has a Steps section below the notes. Everything happens in place, without a page reload:

• Add a step with the add row.
• Tick a step to complete it, and untick it to reopen.
• Rename a step by clicking its title. Enter saves, Escape cancels.
• Reorder by dragging a step up or down.
• Delete a step you don't need.

When a task has steps, its row in the list and its card on the board show a progress chip such as 2/5. Tasks without steps show nothing.

Completing a task doesn't tick its remaining steps. Steps are also included when you export your data, as a checklist under each task.

Steps or separate tasks?

Use steps for the parts of one piece of work: "write copy", "set up the sequence", "test with a real inbox".

Use separate tasks when a part needs its own due date, priority, labels or reminder, or should show up in Today and Upcoming by itself. You can still connect separate tasks with "Blocked by" dependencies.

Using notes and steps through MCP

The MCP task tools read and write notes and steps directly. In these tools, description is the task's title, so the body is called notes.

update_task(steps:) replaces the list, the same way labels work:

• An item with an id updates that step (title, completed).
• An item without an id creates a new step.
• A step missing from the list is deleted.
• Array order becomes the step order.
• [] clears all steps. Leaving steps out leaves them untouched.

So always call get_task first and send the full list back, changed. For example, to tick step 52, move it first and add a new step:

get_task returns:

{
  "id": 1234,
  "description": "Ship onboarding emails",
  "notes": "Three emails, plain text. Copy is in the linked note.",
  "steps": [
    { "id": 51, "title": "Write copy", "completed": true },
    { "id": 52, "title": "Set up the sequence", "completed": false }
  ]
}

(The other task fields, such as priority, due date and labels, are left out here.)

Send to update_task:

{
  "task_id": "1234",
  "steps": [
    { "id": 52, "title": "Set up the sequence", "completed": true },
    { "id": 51, "title": "Write copy", "completed": true },
    { "title": "Test with a real inbox" }
  ]
}

If any item is invalid (an unknown id, a step from another task, an empty title, or more than 100 steps), the whole update is rejected and nothing changes. The same goes for notes over 20,000 characters.

Existing agents keep working. A call that doesn't send notes or steps changes neither.

Using them from the CLI

The Vist CLI builds its commands from the same tools, so get_task, create_task, update_task and list_tasks have the new fields without an update. Notes are a normal flag, --notes. Steps are a list of objects, which the CLI can't turn into flags, so pass them as JSON with --arg steps=... or put the whole call in a file with --args-file:

vist get_task --task-id 1234
vist create_task --description "Ship onboarding emails" --arg steps='[{"title": "Write the copy"}, {"title": "Send a test"}]'
vist update_task --args-file update.json

As over MCP, update_task replaces the whole list of steps, so start from what get_task returned. vist schema update_task shows the tool's schema and its flags.

Size limits

Limitations

• Phones: task cards show the progress chip, but the phone layout has no task detail view yet, so you can't edit notes or steps there.
• Reordering needs a mouse or trackpad. There's no keyboard or touch reordering yet.
• Checklists inside a note don't become steps. A checklist item in a note can still become a task of its own, as before (see Task Management).
• Steps can't be nested, and a step can't have its own steps.

Frequently asked questions

Are steps the same as subtasks?

They're a lighter version on purpose. A step is a title and a checkbox inside one task. If a part of the work needs its own due date, priority or labels, make it a separate task.

Can my AI agent tick off steps?

Yes. It calls get_task, flips completed on the step, and sends the full list back with update_task(steps:). The progress chip on list rows and board cards counts it.

How do I add subtasks with Claude Code or another MCP client?

Ask your agent to add steps to the task, for example "break task 1234 into steps". For a new task, it can pass steps (a list of steps, each with a title) to create_task. For an existing task, it calls get_task, adds the new steps to the list it got back, and sends the full list to update_task(steps:). Anything it leaves out is deleted, which is why get_task comes first. The same works from the Vist CLI, with the steps passed as JSON (see Using them from the CLI).

Can I convert a step into its own task?

Not with one click. There's no convert action yet. Create a new task with the step's title (in the app, or with create_task), then delete the step. If the work needs its own due date, priority or labels, a separate task is the right home for it.

Do steps show up on the Agent pipeline board?

The card shows the 2/5 progress chip. Steps don't get cards of their own. See Agent Kanban Board.

Why is the task body called notes in MCP?

In the MCP task tools, description already meant the task's title, and renaming it would break existing agents and scripts. So the body got a new name: notes. In the app, the same field is labelled Description.

What happens to steps when I complete a task?

Nothing. Their ticked and unticked states stay as they are.

Which plans include steps and notes?

Available on all plans, including Free.

Do steps have due dates or reminders?

No. Steps have no due date, priority, labels or reminders, and they don't appear in Today or Upcoming. That keeps your task lists unchanged.