Type a #hashtag anywhere in an OpenCode prompt.
It expands into the instructions you would otherwise type again.
InstallΒ Β Β Quick startΒ Β Β FeaturesΒ Β Β LibraryΒ Β Β ConfigurationΒ Β Β Share snippets
Tip
Got a snippet that saves you time? Share it, or borrow ideas from others, in GitHub Discussions.
A snippet is a Markdown file with an instruction you use often. Write it once, then add it to any message with its #name instead of pasting or typing it again.
| π Write once Keep an instruction in one file and use it in every session. |
π§© Compose Build large prompts from small pieces. Snippets can include other snippets. |
π§ Update once Edit the file and the next message uses the new text everywhere. |
π Discover Type # to list every snippet and pick one with autocomplete. |
OpenCode's /slash commands must come first in a message. Snippets work anywhere, like @file mentions:
/git-status Review my changes β command: first word only
Review my changes #git-status, then #code-style β snippets: anywhere
/commands |
#snippets |
|
|---|---|---|
| Position | First word only | Anywhere |
| Several per message | No | Yes |
| Live shell data | Yes | Yes |
| Best for | Triggering actions and workflows | Context engineering |
Can't decide? Make a command that forwards to a snippet.
Use slash commands for actions that must happen now (/commit-and-push, /add-worktree, /pull-rebase) and snippets for everything else. A command can also forward to a snippet of the same name:
---
description: Forward to the snippet at snippet/pull.md
---
#pullAdd opencode-snippets to plugins in opencode.json. OpenCode loads the terminal parts as well: autocomplete, field forms and the snippet library.
{
"plugins": ["opencode-snippets"]
}Local development build
Run bun install and bun run build, then add the built dist directory to plugins in both opencode.json and cli.json:
{
"plugins": ["file:///absolute/path/to/opencode-snippets/dist"]
}Rebuild after every source change to test the updated server and terminal entry points.
-
Run
/snippets, choose New, name itcarefuland select Global. -
Enter this source and press Ctrl+S:
--- aliases: safe --- Think step by step. Double-check your work before committing changes. Ask clarifying questions if anything is ambiguous.
-
Type
#careful, or its alias#safe, anywhere in a message.
WindowsTerminal_X5l2ZdlbiH.mp4
Snippets work in messages, in slash commands and inside other snippets. Small files combine into layered prompts: #tdd #careful for careful test-driven work, /commit #conventional-commits #project-context for context-aware commits.
| A command that uses snippets | Snippets that use snippets |
|---|---|
|
---
description: Commit and push
---
Create a git commit with the current
changes and push it.
#use-conventional-commits
Status: !`git status`
Staged: !`git diff --cached`
#project-context |
#style-guide
#error-handling
#testing-requirements
#code-standards
#security-checklist
#performance-tipsType |
WindowsTerminal_teq3AHQgII.mp4
π·οΈ Aliases#cp, #pick and #cherry-pick for one file. |
π Fields and forms Typed inputs, a form in the terminal and Handlebars output. |
π» Shell substitution!`git status` in any prompt, with an optional echo of the command. |
π Recursive includes Snippets include snippets, with loop protection. |
| π Prepend and append Long reference text goes to the start or end of the message. |
π Inject blocks Context that the model receives for the whole turn, outside your message. |
π§ Skills$review loads an OpenCode skill. <skill> inlines one. |
π Library A Vim-style browser and editor for all snippets. |
---
aliases:
- cp
- pick
description: "Git cherry-pick helper"
---
Always pick parent 1 for merge commits.#cherry-pick, #cp and #pick now expand to the same text. One alias needs no list (aliases: safe), and JSON style works too (aliases: ["cp", "pick"]).
Declare typed inputs in YAML frontmatter and use the answers as Handlebars variables:
---
fields:
count:
label: Options
type: number
default: 5
min: 0
integer: true
---
{{#if (gt count 0)}}Offer {{count}} {{plural count "option" "options"}}.{{/if}}Accept a completion, or type a space after a snippet name, to fill its form. Autocomplete marks these snippets with β·. Confirming writes a readable reference such as #options(count=3) into the composer, and sending the message expands it. Ctrl+G edits the fields of the reference under the cursor.
Field types, keys, arguments and presets
- Types: text, multiline text, number, checkbox, select and
multiselect. Select options are YAML lists such asoptions: [quick, normal, thorough]. - Form keys: Tab/Shift+Tab move between fields and buttons, arrows select, Space toggles, Ctrl+J inserts a newline, Enter confirms and Esc cancels. Help shows all keys.
- Multiselect:
defaultis a list of selected strings.required: trueneeds at least one choice.{{checks}}prints the choices separated by commas, and{{#each checks}}- {{this}}{{/each}}prints one per line. See the audit-tests example. - Arguments: named keys with JSON-quoted text, numbers,
yes/noand lists of strings, for example#audit-tests(checks=["No meaningful assertions"]).checks=[]clears a selection. Answers stay literal, even when they contain hashtags, shell commands or template syntax. - Presets: put
#options(count=10)inten-options.md. An outer answer such as#ten-options(count=2)overrides it. Nested snippets share their parent's answers. - Opt-in: the
fieldsmapping turns Handlebars on and sets the order of inputs. Usefields: {}for a template without inputs. Snippets withoutfieldskeep{{ }}as literal text. - Headless runs use defaults and reject missing required answers before any effect runs.
The fields and forms reference covers constraints, escaping and conditional prose. The example templates include review, reword and options presets.
Shell substitution works in snippet files and in every message you type in OpenCode.
| You write | The model receives |
|---|---|
Branch: !`git branch --show-current` |
Branch: main |
!>`ls` |
$ ls--> README.md src β¦ |
The !> form adds the command line above its output, so the model can tell which command produced the text. A failed command keeps its original syntax in the message.
A snippet can reference other snippets with #name. Expansion repeats up to 15 times per message, which supports deep nesting. A circular reference (#a includes #b, which includes #a) stops after 15 rounds, leaves the last hashtag as text and logs a warning.
Reference material that would interrupt your sentence goes into <append> (end of the message) or <prepend> (start of the message):
snippet/jira.md | Input and expanded message |
|---|---|
---
aliases: jira-mcp
---
Jira MCP server
<append>
## Jira MCP usage
- field_16570 => Acceptance Criteria
- field_11401 => Team
</append> |
|
Block rules
- Text outside the blocks replaces the hashtag. A snippet with only blocks removes the hashtag.
- Several blocks of one type join in order of appearance, including blocks from nested snippets.
- An unclosed tag turns the rest of the snippet into the block.
- Nested blocks are not allowed. The hashtag stays unchanged.
Note
Experimental. Set "experimental": { "injectBlocks": true } in the configuration.
<inject> sends context to the model for the whole agent turn, without showing it in your message:
---
aliases: safe
---
Think step by step.
<inject>
IMPORTANT: Check all code for security vulnerabilities.
Always suggest tests for any implementation.
</inject>Review this code #safe shows Review this code Think step by step. in the transcript. The model also receives the inject content as a separate message, placed 5 messages from the bottom (injectRecencyMessages) so that it does not read as your latest instruction. The injection placement notes explain why.
Note
Experimental. Enable skillLoading and skillRendering under experimental in the configuration.
| Syntax | Effect |
|---|---|
$review |
Loads the skill. The transcript shows β³ Loaded review, and the model receives the skill content after your message. |
#skill("Release Notes") |
The same, for display names and IDs outside the $ grammar. |
<skill>jira</skill> or <skill name="jira" /> |
Inlines the skill body, without its frontmatter, into the message. |
{{skill "review"}} |
Inlines a skill inside a snippet template. |
Autocomplete uses OpenCode's own skill registry: $ lists skills, # lists snippets and skills.
Expansion runs in this order:
---
config:
look: classic
themeVariables:
edgeLabelBackground: transparent
---
flowchart LR
classDef step fill:#0C969B1a,stroke:#0C969B,stroke-width:1.5px
A["#lt;skill#gt;"]:::step --> B["#hashtags"]:::step --> C["$skill"]:::step --> D["!`shell`"]:::step
When does $ stay literal?
$id uses lowercase letters, digits, - and _, needs at least one letter and can carry : namespaces such as $host:proof. These stay literal: $HOME, prices, foo$review, $review.path, anything inside code spans, code blocks, shell substitutions, regex literals and $β¦$ math, field answers and attachments. Write \$review to keep a reference literal. In Bash, quote it: opencode run '$review'.
Run /snippets to browse, edit and test project and global snippets. In OpenCode V2, every open terminal picks up saved, added, renamed and deleted snippet files at once, including edits by agents and other editors.
| Key | Action |
|---|---|
| Enter | Edit the Markdown source. Ctrl+S saves. |
| Shift+Enter | Open the file in $VISUAL or $EDITOR. |
| : | Actions: new, reload, duplicate, rename, move, delete, copy reference, test form. |
| / | Filter by name, alias or description. |
| Esc / q | Step back / close. Drafts stay open for the next visit. |
| F1 | Show every key. |
Vim navigation keys
| Keys | Navigation |
|---|---|
| j / k, arrows, Ctrl+N / Ctrl+P | Next / previous row |
| gg / G, Home / End | First / last row or preview line |
| 3j, 5G, 5gg | Repeat a motion, or go to a numbered row or line |
| H / M / L | Top / middle / bottom visible row |
| Ctrl+D / Ctrl+U | Half page down / up |
| Ctrl+F / Ctrl+B | Full page down / up |
| Ctrl+E / Ctrl+Y | Scroll one line |
| zt / zz / zb | Align the selected row at the top / middle / bottom |
| h / l | Focus the list / preview |
| Ctrl+W then w | Switch panes |
| / / ?, then n / N | Filter forward / backward, next / previous match |
| Ctrl+O / Ctrl+I | Back / forward through jumps |
| i | Open the source editor |
Counts and unfinished key sequences show in the footer. Esc cancels them.
|
---
aliases: ctx
---
Project: !`basename $(pwd)`
Branch: !`git branch --show-current`
Changes: !`git diff --stat HEAD~3` |
---
aliases:
- min
- terse
---
Be extremely concise.
No explanations unless asked. |
Project snippets in .opencode/snippet/ win over global snippets with the same name in ~/.config/opencode/snippet/. Both scopes also read a snippets/ directory, and snippet/ wins over it. The global root follows OPENCODE_CONFIG_DIR, then $XDG_CONFIG_HOME/opencode, then ~/.config/opencode. The globalDirectory plugin option overrides it. Symlinked project snippet directories are rejected.
What happens when a message is processed
Each new message reads the current snippet files, so saved edits apply to the next message. Replayed messages keep their original expansion.
If processing fails, the original message goes through unchanged and a warning is logged. Validation finishes before any shell command runs.
The plugin stores a small record of processing output so that rebuilt history and server restarts never repeat shell side effects. Records live in $XDG_DATA_HOME/opencode/opencode-snippets/v2 (default ~/.local/share/opencode/opencode-snippets/v2), with mode 0700 for directories and 0600 for files. They contain hashed IDs, status, timestamps and replay output, but no prompts or project paths. Records expire after 30 days, with at most 100 sessions per project and 1,000 messages per session. Deleting a session deletes its records.
The plugin creates ~/.config/opencode/snippet/config.jsonc on first run. A project file at .opencode/snippet/config.jsonc overrides it.
For editor completion, set "$schema" to the config schema.
Boolean settings also accept "enabled" and "disabled".
- Snippets expand in chat messages, question answers, skills and slash commands. Assistant messages are never processed.
- Hashtags are case-insensitive (
#Hello=#hello). Unknown hashtags stay unchanged. - Frontmatter is removed from expanded text.
- Logs go to
$XDG_DATA_HOME/opencode/log/snippets/daily/. Info, warnings and errors are always written, andlogging.debugadds debug lines.
Issues and pull requests are welcome. Questions go to the Discord forum.
bun test # unit and renderer tests
bun run test:v2 # the built plugin in real OpenCode 2 processesAbout the OpenCode 2 runtime tests
Install the CLI version that matches @opencode/plugin in package.json, or point OPENCODE_BIN at a specific executable. The suite uses isolated home, config and data directories and a local deterministic model endpoint. It checks saved messages and real model requests across CLI submissions, attachments, skill tool calls, queued input, commands, restarts, forks and project boundaries. A failed test keeps its temporary directory and prints the path.
MIT Β© JosXa
{ "logging": { "debug": false // logs: $XDG_DATA_HOME/opencode/log/snippets/daily/ }, "experimental": { "injectBlocks": false, // <inject>β¦</inject> "skillRendering": false, // <skill>name</skill> "skillLoading": false // $id and #skill(name) }, "injectRecencyMessages": 5 // distance of injected context from the bottom }