Markdown

Use Markdown in descriptions, comments, and documents. For document history and permission-checked links, see Documents.

Supported markdown

Task Machine supports CommonMark and common extensions. You can use:

• Headings, paragraphs, and blockquotes.
• Numbered lists, bullet lists, and task lists.
• Inline code and fenced code blocks.
• Links, images, and automatically linked URLs.
• Italic, bold, underlined, and strikethrough text.
• Tables.

Raw HTML embedded in user content is escaped rather than rendered, so markdown is the formatting surface and there is no inline HTML escape hatch for product content.

Formatting while you write

Select complete words in a Markdown editor to show formatting controls beside the selection. Partial-word selections keep the native selection without opening formatting controls.

You can apply inline styles, add a link, choose a heading, turn lines into a quote, or turn them into a bulleted, numbered, or task list. On phones, the controls stay within the visible area above the keyboard, alongside native selection and Copy/Paste.

Highlighted buttons show styles applied throughout the selection. A short line beneath a button means only part of the selection has that style. Choose an active style to remove it, or an inactive or mixed style to apply it throughout. Typing Markdown formatting directly does not open a formatting menu.

A list style turns each selected line into an item and skips blank lines, headings, and table rows. Choosing a different list style converts the markers in place, including typed markers such as 1: or •, and nested items stay nested. Choose the active style again to remove the markers. Task list items appear as checkboxes you can tick directly in the editor.

Choose Link to enter an address for unlinked or mixed text, or remove the link when the selection is already linked. Apply link updates the draft, while Cancel keeps the original text and selection. Save or send the draft through its usual control.

Lists while you write

The editor shows lists the way they will read once saved. Every bullet appears as a dot whichever of -, *, or + you typed, numbers line up, long items wrap under their own text, and nested items indent. A line such as 1: Pick a date stays plain text until Enter turns it into a list, so a marker that appears as a dot or a number is one Markdown recognizes.

Press Enter at the end of a bullet, numbered, or task item to start the next one. Numbered lists keep counting, and adding an item in the middle renumbers the ones after it.

Press Enter on an empty item to leave the list. Task Machine adds a blank line so the next paragraph does not become part of the last item.

Press Tab to nest an item under the item above it, and Shift+Tab to move it back out one level. The item takes its text and any nested items with it, and numbered items count again inside their new level. Items that followed a moved item stay where they were, so they become its children. With several lines selected, use Ctrl+] and Ctrl+[ (Cmd on a Mac), which nest and unnest every selected item. On the first item of a list, on an item that is not nested, and outside lists, Tab and Shift+Tab move focus as usual, so you can always leave the editor from the keyboard. Phones have no Tab key, so nesting there means typing the indentation.

Where Enter sends your message, such as Chat, press Shift+Enter to continue the list. Pressing Enter on an empty item leaves the list instead of sending.

Lists typed as 1:, 1/, or with a • bullet are not Markdown lists, so they would show as one run-on paragraph. Press Enter at the end of such a line and Task Machine rewrites it, together with the lines of the same style directly above it, as 1. or - and continues the list. Undo restores what you typed. Pasting and opening saved text never rewrite anything. A line that starts with _ is not a list.

Add emoji while writing

On a computer, type : at the start of a word to choose an emoji. Continue with part of its name, such as :sm, to narrow the choices, then choose a result or select it with the arrow keys and Enter or Tab. While the picker is open, Enter chooses the emoji without sending your Chat draft.

Finish a known shortcode such as :smile: to insert 😄 directly. The emoji becomes part of your draft, and you save or send it through the usual control. Undo restores the text before that insertion.

On phones and tablets, use your keyboard's emoji picker. Shortcodes remain literal there.

Pasted text, code, URLs, times, and existing saved text stay unchanged. Unknown shortcodes stay literal.

Process diagrams

Use a fenced Mermaid block to explain a sequence, handoff, or decision in a task spec, comment, Chat message, or Library document. For example, this Markdown describes a publishing process:

```mermaid
flowchart LR
  Draft[Draft announcement] --> Review[Review copy]
  Review --> Publish[Publish]
```

Task Machine renders that block as a diagram:

flowchart LR
  Draft[Draft announcement] --> Review[Review copy]
  Review --> Publish[Publish]

In a Markdown editor, select the diagram to edit its source. Editors mark changes in that source, and emails and exports preserve it. A diagram that cannot render shows its source with an explanation. Oversized diagrams stay as source.

Revision comparisons render diagrams too. An edited diagram opens on After, with icon-only Before / After controls in its top-right corner. Hover or focus an icon to see its name, then choose the version to inspect. If either version is oversized, the comparison keeps the source changes instead.

Added diagrams have a green tint and an Added diagram caption. Removed diagrams have a red tint and a Removed diagram caption. The surrounding Text choice shows only the current diagram, hides its version controls, and removes the added tint and caption. Removed diagrams disappear in Text.

Internal references

An internal reference is an ordinary markdown link whose target is a type:id pair instead of a URL, for example, [The runbook](document:550e8400-e29b-41d4-a716-446655440000). The id must be a valid identifier. A link whose target does not parse as a known type and a valid id is treated as a normal link, not a reference.

Because the link stores a stable id, Task Machine resolves the current name and route at view time, so the reference keeps working after the target is renamed, and falls back to plain text when the reader is not allowed to see the target.

The reference types the parser recognizes are:

A complete reference looks like this:

See [the deploy task](task:6ba7b811-9dad-11d1-80b4-00c04fd430c9)
for context, and follow [the runbook](document:550e8400-e29b-41d4-a716-446655440000).

Inserting references while you write

Typing @ opens a picker that searches the members, Agents, Teams, Tasks, documents, folders, Skills, Projects, Goals, and Repositories you can access, grouped by kind. Choose a result to insert its named chip. Project, Goal, and Repository choices include accepted, active records. Repository references show the name without its connection details.

Home starters can also insert Workspace mentions in Chat. Chat derives cards from resolved mentions in the message. See Chat for the editable starters and card behavior.

A folder choice stores its stable identity and displays its current full path, including spaces and punctuation. A rename or move updates the reference, while a folder you cannot read becomes plain saved label text without a link.

Picker selections are stored as @[label](type:id). Folder references use folder:<content-path-id>.

Plain [label](type:id) references are also supported. A comment can tag several Agents or one Team, without combining them. A Human reply with Agent tags reaches only those Agents for that message, without changing the thread's default owner. Later untagged replies return to that owner. Project, Goal, and Repository references identify context without notifying anyone or assigning work.

Pasting links while you write

In an editable Markdown editor, select the text you want to use as a label and paste one HTTP(S) URL. The editor turns the selection into a Markdown link immediately. A URL pasted without a selection stays a raw URL, while mixed, multiline, or otherwise unsupported clipboard content keeps the browser's normal paste behavior.

Agent memory

An agent's memory is markdown too, and it reads best as a bounded list of short, specific entries. Compact entries are easier to inject into a run and easier for the agent to prune when its memory fills up. Agents change memory one entry at a time with tama memory, and each entry they write is a single line. See the CLI command reference.