md² documentation

Placeholders

Placeholders let one action definition work for every card. They are written as {{name}} and resolved on the desktop side, just before the process starts.

Placeholder	Resolves to
{{card-file}}	Path to the selected card’s Markdown file.
{{this-card}}	Alias of {{card-file}}; the same path to the selected card’s Markdown file.
{{card-title}}	Title of the selected card.
{{card-prompt}}	The extra text you typed in the action popup for this run.
{{active-cards-folder}}	Absolute path to the configured working folder under the opened repository. Active cards are root-level Markdown files in this folder shown on the dashboard.
{{worktree-folder}}	Absolute path to the action execution checkout.
{{repository-folder}}	Absolute path to the opened repository.
{{project-folder}}	Absolute path to the configured project.projectFolder under the opened repository. Equal to {{repository-folder}} when configuration is empty.
{{releases-folder}}	Absolute path to the configured releases folder under the opened repository.
{{actions-folder}}	Absolute path to the configured actions folder under the opened repository. Includes project.projectFolder when configured.
{{diagram-file}}	Output path for a diagram action. Available when the action has diagram output.
{{parent-node}}	Label of the selected item when running a child diagram action.
{{diagram-changes}}	Generated text from reviewed diagram edits when sending changes to an agent.
{{version}}	Free-form answer confirmed for the current action run. Linked actions use the same answer.
{{conflict-file}}	Path of the conflicted file the action was started for in the merge conflict dialog.
{{conflict-files}}	Paths of all files still conflicted in the merge conflict session, one per line.

They work in both prompt (agent actions) and command (command actions).

Using them

In the prompt editor, type {{ for a typeahead list, or insert one from the toolbar.

{
  "id": "fix-bug",
  "label": "Fix bug",
  "description": "Fix the bug described on the card",
  "type": "agent",
  "prompt": "Fix the bug described in {{card-file}}.\n\nExtra instructions: {{card-prompt}}"
}

{
  "id": "open-in-editor",
  "label": "Open in VS Code",
  "description": "Open the card file in VS Code",
  "type": "command",
  "command": "code {{card-file}}"
}

Notes

• A card placeholder only resolves when the action runs with card context. Use appliesTo with "kind": "card" so an action that needs {{card-file}} or {{this-card}} is only offered where it makes sense.
• Diagram placeholders need diagram context. {{diagram-file}} also needs an output path, {{parent-node}} needs a selected item in a child diagram context, and {{diagram-changes}} needs reviewed changes from the editor.
• Conflict placeholders need merge-conflict context. {{conflict-file}} only resolves when the action was started for one file, not from all remaining files.
• {{card-prompt}} is empty when you run without typing anything. Write prompts that read fine either way.
• {{version}} requires a confirmed or explicitly supplied version. Without one, executable text fails before it runs.
• During linked-worktree actions, {{repository-folder}}, {{project-folder}}, {{active-cards-folder}}, and {{actions-folder}} remain under the opened repository. Only {{worktree-folder}} changes to the linked worktree.
• The diff command in project configuration supports the same six folder placeholders plus {{commit}}, {{branch}}, and {{file}}. For diffs, {{worktree-folder}} and {{repository-folder}} both resolve to the opened repository.
• Custom agent profiles support {{model}} in command and {{sessionId}} in resumeCommand. Those are profile placeholders, not action placeholders.

See also: Action definition, Diagrams, Cookbook.

This site is open source. Improve this page.