Custom commands

Create custom commands to automate tasks & actions

Custom commands let you define reusable prompts that run when you type /command-name in the TUI. They support dynamic flow via arguments, shell output, and file references.

Creating commands

Markdown files (recommended)

Create .md files in one of two directories:

Scope	Directory
Global	~/.symbiotic/commands/
Project	.symbiotic/commands/

The filename (without .md) becomes the command name.

If your command file is in a project directory, it will only be available if you launch Symbiotic Code from that directory.

Example

1. Create a file named test.md in .symbiotic/commands/ with the following content:

---
description: Run tests with coverage
model: claude-opus-4-6
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

2. Use it in Symbiotic Code TUI:

/test

JSON config

Alternatively, define commands in symbiotic.json or .symbiotic/symbiotic.json (project), or the same files under ~/.symbiotic/ (global):

{
  "command": {
    "fix": {
      "template": "Fix all issues in @$ARGUMENTS and explain each change.",
      "description": "Fix a file"
    },
    "review": {
      "template": "Review $1 focusing on $2.\\n\\nRecent changes:\\n!`git diff HEAD~1 HEAD -- $1`",
      "description": "Review a file with git context"
    },
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "model": "claude-sonnet-4-5"
    }
  }
}

Supports // single-line comments (.jsonc style).

---

Frontmatter Options

Field	Required	Description
description	No	Short description shown in the command palette
model	No	Override the model used for this command

---

Template syntax

Use these placeholders in your command templates:

$ARGUMENTS — full argument string

Pass the entire argument string as a value in the prompt.

Example:

---
description: Fix a file
---

Fix all issues in $ARGUMENTS and explain each change.

/fix src/core/session.ts

↪ $ARGUMENTS is replaced with src/core/session.ts in the prompt written from the custom command template.

---

$1, $2, $3… — positional arguments

Pass the argument at the specified position as a value in the prompt.

Example:

---
description: Create a component
---

Create a TUI component named $1 in $2.
Follow the existing patterns in that directory.

/create-component Sidebar src/cli/tui/components

• $1 → Sidebar
• $2 → src/cli/tui/components

Arguments also support quoting:

/create-component "My Component" src/cli/tui/components

---

!command“ — shell output injection

Inject the output of a shell command into the prompt.

---
description: Review recent git changes
---

Recent git changes:
!`git diff HEAD~1 HEAD --stat`

Review these changes and suggest improvements.

The shell command runs in the current working directory. Its stdout is injected inline into the prompt.

---

Commands priority

When the same command name exists in multiple sources, the highest-priority source wins:

Priority	Scope	Source
1	Project	.symbiotic/symbiotic.json
2	Project	symbiotic.json
3	Project	markdown file
4	Global	.symbiotic/symbiotic.json
5	Global	symbiotic.json
6	Global	markdown file

This lets project commands override global defaults, and JSON config override markdown for the same name.