Skip to content

About

Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts

Resources

Stars

93 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

261 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

opencode-snippets logo: a hashtag assembled from puzzle pieces

opencode-snippets

Type a #hashtag anywhere in an OpenCode prompt.
It expands into the instructions you would otherwise type again.

npm version npm downloads per month GitHub stars OpenCode plugin MIT license

InstallΒ Β Β Quick startΒ Β Β FeaturesΒ Β Β LibraryΒ Β Β ConfigurationΒ Β Β Share snippets


Typing 'Review my diff #careful #ctx' expands into step-by-step instructions plus live project and branch information

Tip

Got a snippet that saves you time? Share it, or borrow ideas from others, in GitHub Discussions.

Why snippets?

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
---
#pull

Install

Add 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.

Quick start

  1. Run /snippets, choose New, name it careful and select Global.

  2. 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.
  3. Type #careful, or its alias #safe, anywhere in a message.

WindowsTerminal_X5l2ZdlbiH.mp4

Compose snippets

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

command/commit-and-push.md

---
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

snippet/code-standards.md

#style-guide
#error-handling
#testing-requirements

snippet/full-review.md

#code-standards
#security-checklist
#performance-tips

Type #full-review to add every standard at once. Each concern keeps its own file.

WindowsTerminal_teq3AHQgII.mp4

Features

🏷️ 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

---
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"]).

Fields and forms

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 as options: [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: default is a list of selected strings. required: true needs 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/no and 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) in ten-options.md. An outer answer such as #ten-options(count=2) overrides it. Nested snippets share their parent's answers.
  • Opt-in: the fields mapping turns Handlebars on and sets the order of inputs. Use fields: {} for a template without inputs. Snippets without fields keep {{ }} 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

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.

Recursive includes

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.

Prepend and append blocks

Reference material that would interrupt your sentence goes into <append> (end of the message) or <prepend> (start of the message):

snippet/jira.mdInput and expanded message
---
aliases: jira-mcp
---
Jira MCP server
<append>
## Jira MCP usage
- field_16570 => Acceptance Criteria
- field_11401 => Team
</append>
Create a bug ticket in #jira-mcp
about the memory leak
Create a bug ticket in Jira MCP server
about the memory leak

## Jira MCP usage
- field_16570 => Acceptance Criteria
- field_11401 => Team
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.

Inject blocks

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.

Skills

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
Loading
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'.

Snippet library

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.

Example snippets

snippet/context.md

---
aliases: ctx
---
Project: !`basename $(pwd)`
Branch: !`git branch --show-current`
Changes: !`git diff --stat HEAD~3`

snippet/minimal.md

---
aliases:
  - min
  - terse
---
Be extremely concise.
No explanations unless asked.

Where snippets live

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.

Configuration

The plugin creates ~/.config/opencode/snippet/config.jsonc on first run. A project file at .opencode/snippet/config.jsonc overrides it.

{
  "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
}

For editor completion, set "$schema" to the config schema.

Boolean settings also accept "enabled" and "disabled".

Behavior notes

  • 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, and logging.debug adds debug lines.

Contributing

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 processes
About 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.

License

MIT Β© JosXa

About

Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts

Resources

Stars

93 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages