opencode-snippets 1.2.0 → 1.3.0

package/README.md

@@ -2,11 +2,16 @@
 
 ✨ **Instant inline text expansion for OpenCode** - Type `#snippet` anywhere in your message and watch it transform.
 
+> [!TIP]
+> **Share Your Snippets!**  
+> Got a snippet that saves you time? Share yours or steal ideas from the community!
+> Browse and contribute in [GitHub Discussions](https://github.com/JosXa/opencode-snippets/discussions/categories/snippets).
+
 ## Why Snippets?
 
 As developers, we DRY (Don't Repeat Yourself) our code. We extract functions, create libraries, compose modules. Why should our prompts be any different?
 
-Stop copy-pasting the same instructions into every message. Snippets bring software engineering principles to prompt engineering:
+Stop copy-pasting (or worse, *typing* 🤢) the same instructions into every message. Snippets bring software engineering principles to prompt engineering:
 
 - 🔄 **DRY** - Write once, reuse everywhere
 - 🧩 **Composability** - Build complex prompts from simple pieces  
@@ -29,7 +34,7 @@ Snippets work like `@file` mentions - natural, inline, composable.
 
 Snippets compose with each other and with slash commands. Reference `#snippets` anywhere - in your messages, in slash commands, even inside other snippets:
 
-**Example: Extending snippets with logic**
+**Example: Extending commands with snippets**
 
 `~/.config/opencode/command/commit-and-push.md`:
 ```markdown
@@ -37,6 +42,7 @@ Snippets compose with each other and with slash commands. Reference `#snippets`
 description: Create a git commit and push to remote
 ---
 Please create a git commit with the current changes and push to the remote repository.
+#use-conventional-commits
 
 Here is the current git status:
 !`git status`
@@ -44,10 +50,11 @@ Here is the current git status:
 Here are the staged changes:
 !`git diff --cached`
 
-#conventional-commits
 #project-context
 ```
 
+You could also make "current git status and staged changes" a shell-enabled snippet of its own.
+
 **Example: Snippets composing snippets**
 
 `~/.config/opencode/snippet/code-standards.md`:
@@ -101,10 +108,7 @@ Ask clarifying questions if anything is ambiguous.
 
 **3. Use it anywhere:**
 
-```
-Refactor this function. Think step by step. Double-check your work before making changes.
-Ask clarifying questions if anything is ambiguous.
-```
+https://github.com/user-attachments/assets/d31b69b5-cc7a-4208-9f6e-71c1a278536a
 
 ## Where to Store Snippets
 
@@ -217,12 +221,25 @@ Be extremely concise. No explanations unless asked.
 | Live shell data | Yes 💻 | Yes 💻 |
 | Best for | Triggering actions & workflows ⚡ | Context injection 📝 |
 
-**Use both together:**
-```
-/commit #conventional-commits #project-context
-```
+> [!TIP]
+> #### My recommendation:
+> 
+> Use /slash commands for **triggering actions and workflows** imperatively - anything that needs to happen _right now_: `/commit-and-push`, `/add-worktree`, or `/pull-rebase`.  
+> Use #snippets for **all other context engineering**.
+>
+> If you can't decide, get the best of both worlds and just have your command proxy through to the snippet:
+>
+> `~/.config/opencode/command/pull.md`:
+> ```markdown
+> ---
+> description: Proxy through to the snippet at snippet/pull.md
+> ---
+> #pull
+> ```
+
+## Configuration
 
-## Configuration### Debug Logging
+### Debug Logging
 
 Enable debug logs by setting an environment variable:
 
@@ -243,7 +260,8 @@ Logs are written to `~/.config/opencode/logs/snippets/daily/`.
 
 ## Contributing
 
-Contributions welcome! Please open an issue or PR on GitHub.
+Contributions welcome! Please open an issue or PR on GitHub. 
+👥 [Discord Forum](https://discord.com/channels/1391832426048651334/1463378026833379409)
 
 ## License
 

package/index.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "@opencode-ai/plugin";
+import { createCommandExecuteHandler } from "./src/commands.js";
 import { expandHashtags } from "./src/expander.js";
 import { loadSnippets } from "./src/loader.js";
 import { logger } from "./src/logger.js";
@@ -8,6 +9,7 @@ import { executeShellCommands, type ShellContext } from "./src/shell.js";
  * Snippets Plugin for OpenCode
  *
  * Expands hashtag-based shortcuts in user messages into predefined text snippets.
+ * Also provides /snippet command for managing snippets.
  *
  * @see https://github.com/JosXa/opencode-snippets for full documentation
  */
@@ -22,7 +24,22 @@ export const SnippetsPlugin: Plugin = async (ctx) => {
     snippetCount: snippets.size,
   });
 
+  // Create command handler
+  const commandHandler = createCommandExecuteHandler(ctx.client, snippets, ctx.directory);
+
   return {
+    // Register /snippet command
+    config: async (opencodeConfig) => {
+      opencodeConfig.command ??= {};
+      opencodeConfig.command.snippet = {
+        template: "",
+        description: "Manage text snippets (create, delete, list, help)",
+      };
+    },
+
+    // Handle /snippet command execution
+    "command.execute.before": commandHandler,
+
     "chat.message": async (_input, output) => {
       // Only process user messages, never assistant messages
       if (output.message.role !== "user") return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-snippets",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
   "main": "index.ts",
   "type": "module",
@@ -38,13 +38,15 @@
     "@types/bun": "latest",
     "@types/node": "^22",
     "@typescript/native-preview": "^7.0.0-dev.20260120.1",
+    "husky": "^9.1.7",
     "typescript": "^5"
   },
   "scripts": {
     "build": "tsgo --noEmit",
     "format:check": "biome check .",
     "format:fix": "biome check --write .",
-    "ai:check": "bun run format:fix"
+    "ai:check": "bun run format:fix",
+    "prepare": "husky"
   },
   "files": ["index.ts", "src/**/*.ts"]
 }

package/src/commands.ts

@@ -0,0 +1,336 @@
+import { PATHS } from "./constants.js";
+import { createSnippet, deleteSnippet, listSnippets, reloadSnippets } from "./loader.js";
+import { logger } from "./logger.js";
+import { sendIgnoredMessage } from "./notification.js";
+import type { SnippetRegistry } from "./types.js";
+
+/** Marker error to indicate command was handled */
+const COMMAND_HANDLED_MARKER = "__SNIPPETS_COMMAND_HANDLED__";
+
+interface CommandContext {
+  client: any;
+  sessionId: string;
+  args: string[];
+  rawArguments: string;
+  snippets: SnippetRegistry;
+  projectDir?: string;
+}
+
+/**
+ * Creates the command execute handler for the snippets command
+ */
+export function createCommandExecuteHandler(
+  client: any,
+  snippets: SnippetRegistry,
+  projectDir?: string,
+) {
+  return async (input: { command: string; sessionID: string; arguments: string }) => {
+    if (input.command !== "snippet") return;
+
+    const args = input.arguments.split(/\s+/).filter(Boolean);
+    const subcommand = args[0]?.toLowerCase() || "help";
+
+    const ctx: CommandContext = {
+      client,
+      sessionId: input.sessionID,
+      args: args.slice(1),
+      rawArguments: input.arguments,
+      snippets,
+      projectDir,
+    };
+
+    try {
+      switch (subcommand) {
+        case "add":
+        case "create":
+        case "new":
+          await handleAddCommand(ctx);
+          break;
+        case "delete":
+        case "remove":
+        case "rm":
+          await handleDeleteCommand(ctx);
+          break;
+        case "list":
+        case "ls":
+          await handleListCommand(ctx);
+          break;
+        case "help":
+        default:
+          await handleHelpCommand(ctx);
+          break;
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message === COMMAND_HANDLED_MARKER) {
+        throw error;
+      }
+      logger.error("Command execution failed", {
+        subcommand,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      await sendIgnoredMessage(
+        ctx.client,
+        ctx.sessionId,
+        `Error: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    // Signal that command was handled
+    throw new Error(COMMAND_HANDLED_MARKER);
+  };
+}
+
+/**
+ * Handle /snippet add <name> ["content"] [--project] [--alias=<alias>] [--desc=<description>]
+ */
+async function handleAddCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId, args, rawArguments, snippets, projectDir } = ctx;
+
+  if (args.length === 0) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      'Usage: /snippet add <name> ["content"] [options]\n\n' +
+        "Adds a new snippet. Defaults to global directory.\n\n" +
+        "Examples:\n" +
+        "  /snippet add greeting\n" +
+        '  /snippet add bye "see you later"\n' +
+        '  /snippet add hi "hello there" --aliases hello,hey\n' +
+        '  /snippet add fix "fix imports" --project\n\n' +
+        "Options:\n" +
+        "  --project             Add to project directory (.opencode/snippet/)\n" +
+        "  --aliases X,Y,Z       Add aliases (comma-separated)\n" +
+        '  --desc "..."          Add a description',
+    );
+    return;
+  }
+
+  const name = args[0];
+
+  // Extract quoted content from raw arguments
+  // Match content between quotes after the subcommand and name
+  const quotedMatch = rawArguments.match(/(?:add|create|new)\s+\S+\s+"([^"]+)"/i);
+  const content = quotedMatch ? quotedMatch[1] : "";
+
+  const isProject = args.includes("--project");
+  const aliases: string[] = [];
+  let description: string | undefined;
+
+  // Parse arguments with --param value syntax
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+
+    // Handle --aliases
+    if (arg === "--aliases") {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        const values = nextArg
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+        aliases.push(...values);
+        i++; // Skip the value arg
+      }
+    }
+    // Handle --desc or --description
+    else if (arg === "--desc" || arg === "--description") {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        description = nextArg;
+        i++; // Skip the value arg
+      }
+    }
+  }
+
+  // Default to global, --project puts it in project directory
+  const targetDir = isProject ? projectDir : undefined;
+  const location = isProject && projectDir ? "project" : "global";
+
+  try {
+    const filePath = await createSnippet(name, content, { aliases, description }, targetDir);
+
+    // Reload snippets
+    await reloadSnippets(snippets, projectDir);
+
+    let message = `Added ${location} snippet: ${name}\nFile: ${filePath}`;
+    if (content) {
+      message += `\nContent: "${truncate(content, 50)}"`;
+    } else {
+      message += "\n\nEdit the file to add your snippet content.";
+    }
+    if (aliases.length > 0) {
+      message += `\nAliases: ${aliases.join(", ")}`;
+    }
+
+    await sendIgnoredMessage(client, sessionId, message);
+  } catch (error) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      `Failed to add snippet: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * Handle /snippet delete <name>
+ */
+async function handleDeleteCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId, args, snippets, projectDir } = ctx;
+
+  if (args.length === 0) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      "Usage: /snippet delete <name>\n\nDeletes a snippet by name. " +
+        "Project snippets are checked first, then global.",
+    );
+    return;
+  }
+
+  const name = args[0];
+
+  const deletedPath = await deleteSnippet(name, projectDir);
+
+  if (deletedPath) {
+    // Reload snippets
+    await reloadSnippets(snippets, projectDir);
+
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      `Deleted snippet: #${name}\nRemoved: ${deletedPath}`,
+    );
+  } else {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      `Snippet not found: #${name}\n\nUse /snippet list to see available snippets.`,
+    );
+  }
+}
+
+/** Maximum characters for snippet content preview */
+const MAX_CONTENT_PREVIEW_LENGTH = 200;
+/** Maximum characters for aliases display */
+const MAX_ALIASES_LENGTH = 50;
+/** Divider line */
+const DIVIDER = "────────────────────────────────────────────────";
+
+/**
+ * Truncate text with ellipsis if it exceeds maxLength
+ */
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Format aliases for display, truncating if needed
+ */
+function formatAliases(aliases: string[]): string {
+  if (aliases.length === 0) return "";
+
+  const joined = aliases.join(", ");
+  if (joined.length <= MAX_ALIASES_LENGTH) {
+    return ` (aliases: ${joined})`;
+  }
+
+  // Truncate and show count
+  const truncated = truncate(joined, MAX_ALIASES_LENGTH - 10);
+  return ` (aliases: ${truncated} +${aliases.length})`;
+}
+
+/**
+ * Format a single snippet for display
+ */
+function formatSnippetEntry(s: { name: string; content: string; aliases: string[] }): string {
+  const header = `${s.name}${formatAliases(s.aliases)}`;
+  const content = truncate(s.content.trim(), MAX_CONTENT_PREVIEW_LENGTH);
+
+  return `${header}\n${DIVIDER}\n${content || "(empty)"}`;
+}
+
+/**
+ * Handle /snippet list
+ */
+async function handleListCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId, snippets, projectDir } = ctx;
+
+  const snippetList = listSnippets(snippets);
+
+  if (snippetList.length === 0) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      "No snippets found.\n\n" +
+        `Global snippets: ${PATHS.SNIPPETS_DIR}\n` +
+        (projectDir
+          ? `Project snippets: ${projectDir}/.opencode/snippet/`
+          : "No project directory detected.") +
+        "\n\nUse /snippet add <name> to add a new snippet.",
+    );
+    return;
+  }
+
+  const lines: string[] = [];
+
+  // Group by source
+  const globalSnippets = snippetList.filter((s) => s.source === "global");
+  const projectSnippets = snippetList.filter((s) => s.source === "project");
+
+  if (globalSnippets.length > 0) {
+    lines.push(`── Global (${PATHS.SNIPPETS_DIR}) ──`, "");
+    for (const s of globalSnippets) {
+      lines.push(formatSnippetEntry(s), "");
+    }
+  }
+
+  if (projectSnippets.length > 0) {
+    lines.push(`── Project (${projectDir}/.opencode/snippet/) ──`, "");
+    for (const s of projectSnippets) {
+      lines.push(formatSnippetEntry(s), "");
+    }
+  }
+
+  await sendIgnoredMessage(client, sessionId, lines.join("\n").trimEnd());
+}
+
+/**
+ * Handle /snippet help
+ */
+async function handleHelpCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId } = ctx;
+
+  const helpText = `Snippets Command - Manage text snippets
+
+Usage: /snippet <command> [options]
+
+Commands:
+  add <name> ["content"] [options]
+    --project               Add to project directory (default: global)
+    --aliases X,Y,Z         Add aliases (comma-separated)
+    --desc "..."            Add a description
+
+  delete <name>             Delete a snippet
+  list                      List all available snippets
+  help                      Show this help message
+
+Snippet Locations:
+  Global:  ~/.config/opencode/snippet/
+  Project: <project>/.opencode/snippet/
+
+Usage in messages:
+  Type #snippet-name to expand a snippet inline.
+  Snippets can reference other snippets recursively.
+
+Examples:
+  /snippet add greeting
+  /snippet add bye "see you later"
+  /snippet add hi "hello there" --aliases hello,hey
+  /snippet add fix "fix imports" --project
+  /snippet delete old-snippet
+  /snippet list`;
+
+  await sendIgnoredMessage(client, sessionId, helpText);
+}

package/src/constants.ts

@@ -12,20 +12,15 @@ export const PATTERNS = {
   SHELL_COMMAND: /!`([^`]+)`/g,
 } as const;
 
-/**
- * OpenCode configuration directory
- */
-export const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode");
-
 /**
  * File system paths
  */
 export const PATHS = {
   /** OpenCode configuration directory */
-  CONFIG_DIR: OPENCODE_CONFIG_DIR,
+  CONFIG_DIR: join(homedir(), ".config", "opencode"),
 
   /** Snippets directory */
-  SNIPPETS_DIR: join(OPENCODE_CONFIG_DIR, "snippet"),
+  SNIPPETS_DIR: join(join(homedir(), ".config", "opencode"), "snippet"),
 } as const;
 
 /**

package/src/expander.test.ts

@@ -1,10 +1,20 @@
 import { expandHashtags } from "../src/expander.js";
-import type { SnippetRegistry } from "../src/types.js";
+import type { SnippetInfo, SnippetRegistry } from "../src/types.js";
+
+/** Helper to create a SnippetInfo from just content */
+function snippet(content: string, name = "test"): SnippetInfo {
+  return { name, content, aliases: [], filePath: "", source: "global" };
+}
+
+/** Helper to create a registry from [key, content] pairs */
+function createRegistry(entries: [string, string][]): SnippetRegistry {
+  return new Map(entries.map(([key, content]) => [key, snippet(content, key)]));
+}
 
 describe("expandHashtags - Recursive Includes and Loop Detection", () => {
   describe("Basic expansion", () => {
     it("should expand a single hashtag", () => {
-      const registry: SnippetRegistry = new Map([["greeting", "Hello, World!"]]);
+      const registry = createRegistry([["greeting", "Hello, World!"]]);
 
       const result = expandHashtags("Say #greeting", registry);
 
@@ -12,7 +22,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should expand multiple hashtags in one text", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["greeting", "Hello"],
         ["name", "Alice"],
       ]);
@@ -23,7 +33,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should leave unknown hashtags unchanged", () => {
-      const registry: SnippetRegistry = new Map([["known", "content"]]);
+      const registry = createRegistry([["known", "content"]]);
 
       const result = expandHashtags("This is #known and #unknown", registry);
 
@@ -31,7 +41,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle empty text", () => {
-      const registry: SnippetRegistry = new Map([["test", "content"]]);
+      const registry = createRegistry([["test", "content"]]);
 
       const result = expandHashtags("", registry);
 
@@ -39,7 +49,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle text with no hashtags", () => {
-      const registry: SnippetRegistry = new Map([["test", "content"]]);
+      const registry = createRegistry([["test", "content"]]);
 
       const result = expandHashtags("No hashtags here", registry);
 
@@ -47,7 +57,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle case-insensitive hashtags", () => {
-      const registry: SnippetRegistry = new Map([["greeting", "Hello"]]);
+      const registry = createRegistry([["greeting", "Hello"]]);
 
       const result = expandHashtags("#Greeting #GREETING #greeting", registry);
 
@@ -57,7 +67,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
   describe("Recursive expansion", () => {
     it("should expand nested hashtags one level deep", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["outer", "Start #inner End"],
         ["inner", "Middle"],
       ]);
@@ -68,7 +78,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should expand nested hashtags multiple levels deep", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["level1", "L1 #level2"],
         ["level2", "L2 #level3"],
         ["level3", "L3 #level4"],
@@ -81,7 +91,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should expand multiple nested hashtags in one snippet", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["main", "Start #a and #b End"],
         ["a", "Content A"],
         ["b", "Content B"],
@@ -93,7 +103,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should expand complex nested structure", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["greeting", "#hello #name"],
         ["hello", "Hello"],
         ["name", "#firstname #lastname"],
@@ -109,7 +119,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
   describe("Loop detection - Direct cycles", () => {
     it("should detect and prevent simple self-reference", { timeout: 100 }, () => {
-      const registry: SnippetRegistry = new Map([["self", "I reference #self"]]);
+      const registry = createRegistry([["self", "I reference #self"]]);
 
       const result = expandHashtags("#self", registry);
 
@@ -119,7 +129,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should detect and prevent two-way circular reference", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["a", "A references #b"],
         ["b", "B references #a"],
       ]);
@@ -132,7 +142,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should detect and prevent three-way circular reference", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["a", "A -> #b"],
         ["b", "B -> #c"],
         ["c", "C -> #a"],
@@ -146,7 +156,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should detect loops in longer chains", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["a", "#b"],
         ["b", "#c"],
         ["c", "#d"],
@@ -163,7 +173,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
   describe("Loop detection - Complex scenarios", () => {
     it("should allow same snippet in different branches", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["main", "#branch1 and #branch2"],
         ["branch1", "B1 uses #shared"],
         ["branch2", "B2 uses #shared"],
@@ -177,7 +187,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle partial loops with valid branches", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["main", "#valid and #loop"],
         ["valid", "Valid content"],
         ["loop", "Loop #loop"],
@@ -191,7 +201,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle multiple independent loops", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["main", "#loop1 and #loop2"],
         ["loop1", "L1 #loop1"],
         ["loop2", "L2 #loop2"],
@@ -205,7 +215,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle nested loops", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["outer", "Outer #inner"],
         ["inner", "Inner #outer and #self"],
         ["self", "Self #self"],
@@ -222,7 +232,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle diamond pattern (same snippet reached via multiple paths)", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["top", "#left #right"],
         ["left", "Left #bottom"],
         ["right", "Right #bottom"],
@@ -236,7 +246,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle loop after valid expansion", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["a", "#b #c"],
         ["b", "Valid B"],
         ["c", "#d"],
@@ -259,7 +269,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle snippet with empty content", () => {
-      const registry: SnippetRegistry = new Map([["empty", ""]]);
+      const registry = createRegistry([["empty", ""]]);
 
       const result = expandHashtags("Before #empty After", registry);
 
@@ -267,7 +277,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle snippet containing only hashtags", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["only-refs", "#a #b"],
         ["a", "A"],
         ["b", "B"],
@@ -279,7 +289,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle hashtags at start, middle, and end", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["start", "Start"],
         ["middle", "Middle"],
         ["end", "End"],
@@ -291,7 +301,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle consecutive hashtags", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["a", "A"],
         ["b", "B"],
         ["c", "C"],
@@ -303,7 +313,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle hashtags with hyphens and underscores", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["my-snippet", "Hyphenated"],
         ["my_snippet", "Underscored"],
         ["my-complex_name", "Mixed"],
@@ -315,7 +325,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle hashtags with numbers", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["test123", "Test with numbers"],
         ["123test", "Numbers first"],
       ]);
@@ -326,7 +336,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should not expand hashtags in URLs", () => {
-      const registry: SnippetRegistry = new Map([["issue", "ISSUE"]]);
+      const registry = createRegistry([["issue", "ISSUE"]]);
 
       // Note: The current implementation WILL expand #issue in URLs
       // This test documents current behavior
@@ -336,7 +346,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle multiline content", () => {
-      const registry: SnippetRegistry = new Map([["multiline", "Line 1\nLine 2\nLine 3"]]);
+      const registry = createRegistry([["multiline", "Line 1\nLine 2\nLine 3"]]);
 
       const result = expandHashtags("Start\n#multiline\nEnd", registry);
 
@@ -344,7 +354,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle nested multiline content", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["outer", "Outer start\n#inner\nOuter end"],
         ["inner", "Inner line 1\nInner line 2"],
       ]);
@@ -357,7 +367,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
   describe("Real-world scenarios", () => {
     it("should expand code review template with nested snippets", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["review", "Code Review Checklist:\n#security\n#performance\n#tests"],
         ["security", "- Check for SQL injection\n- Validate input"],
         ["performance", "- Check for N+1 queries\n- Review algorithm complexity"],
@@ -373,7 +383,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should expand documentation template with shared components", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["doc", "# Documentation\n#header\n#body\n#footer"],
         ["header", "Author: #author\nDate: 2024-01-01"],
         ["author", "John Doe"],
@@ -389,7 +399,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
     });
 
     it("should handle instruction composition", () => {
-      const registry: SnippetRegistry = new Map([
+      const registry = createRegistry([
         ["careful", "Think step by step. #verify"],
         ["verify", "Double-check your work."],
         ["complete", "Be thorough. #careful"],
@@ -408,9 +418,9 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Create a chain: level0 -> level1 -> level2 -> ... -> level49 -> "End"
       for (let i = 0; i < depth - 1; i++) {
-        registry.set(`level${i}`, `L${i} #level${i + 1}`);
+        registry.set(`level${i}`, snippet(`L${i} #level${i + 1}`, `level${i}`));
       }
-      registry.set(`level${depth - 1}`, "End");
+      registry.set(`level${depth - 1}`, snippet("End", `level${depth - 1}`));
 
       const result = expandHashtags("#level0", registry);
 
@@ -424,7 +434,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const count = 100;
 
       for (let i = 0; i < count; i++) {
-        registry.set(`snippet${i}`, `Content${i}`);
+        registry.set(`snippet${i}`, snippet(`Content${i}`, `snippet${i}`));
       }
 
       const hashtags = Array.from({ length: count }, (_, i) => `#snippet${i}`).join(" ");
@@ -440,10 +450,10 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const branches = 20;
 
       const children = Array.from({ length: branches }, (_, i) => `#child${i}`).join(" ");
-      registry.set("parent", children);
+      registry.set("parent", snippet(children, "parent"));
 
       for (let i = 0; i < branches; i++) {
-        registry.set(`child${i}`, `Child${i}`);
+        registry.set(`child${i}`, snippet(`Child${i}`, `child${i}`));
       }
 
       const result = expandHashtags("#parent", registry);

package/src/expander.ts

@@ -34,8 +34,8 @@ export function expandHashtags(
     expanded = expanded.replace(PATTERNS.HASHTAG, (match, name) => {
       const key = name.toLowerCase();
 
-      const content = registry.get(key);
-      if (content === undefined) {
+      const snippet = registry.get(key);
+      if (snippet === undefined) {
         // Unknown snippet - leave as-is
         return match;
       }
@@ -54,7 +54,7 @@ export function expandHashtags(
       expansionCounts.set(key, count);
 
       // Recursively expand any hashtags in the snippet content
-      const result = expandHashtags(content, registry, expansionCounts);
+      const result = expandHashtags(snippet.content, registry, expansionCounts);
 
       return result;
     });

package/src/loader.test.ts

@@ -35,8 +35,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(undefined, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("careful")).toBe("Think step by step. Double-check your work.");
-      expect(snippets.get("safe")).toBe("Think step by step. Double-check your work.");
+      expect(snippets.get("careful")?.content).toBe("Think step by step. Double-check your work.");
+      expect(snippets.get("safe")?.content).toBe("Think step by step. Double-check your work.");
     });
 
     it("should load multiple snippets from global directory", async () => {
@@ -46,8 +46,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(undefined, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("snippet1")).toBe("Content of snippet 1");
-      expect(snippets.get("snippet2")).toBe("Content of snippet 2");
+      expect(snippets.get("snippet1")?.content).toBe("Content of snippet 1");
+      expect(snippets.get("snippet2")?.content).toBe("Content of snippet 2");
     });
   });
 
@@ -63,7 +63,7 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(1);
-      expect(snippets.get("project-specific")).toBe("This is a project-specific snippet");
+      expect(snippets.get("project-specific")?.content).toBe("This is a project-specific snippet");
     });
 
     it("should handle missing global directory when project exists", async () => {
@@ -74,8 +74,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("team-rule")).toBe("Team rule 1");
-      expect(snippets.get("domain-knowledge")).toBe("Domain knowledge");
+      expect(snippets.get("team-rule")?.content).toBe("Team rule 1");
+      expect(snippets.get("domain-knowledge")?.content).toBe("Domain knowledge");
     });
   });
 
@@ -91,8 +91,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("global")).toBe("Global snippet content");
-      expect(snippets.get("project")).toBe("Project snippet content");
+      expect(snippets.get("global")?.content).toBe("Global snippet content");
+      expect(snippets.get("project")?.content).toBe("Project snippet content");
     });
 
     it("should allow project snippets to override global snippets", async () => {
@@ -106,7 +106,7 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       // Project snippet should override global
-      expect(snippets.get("careful")).toBe("Project-specific careful content");
+      expect(snippets.get("careful")?.content).toBe("Project-specific careful content");
       expect(snippets.size).toBe(1);
     });
   });
@@ -139,12 +139,12 @@ Project test guidelines`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(6); // review, pr, check, test, tdd, testing
-      expect(snippets.get("review")).toBe("Global review guidelines");
-      expect(snippets.get("pr")).toBe("Global review guidelines");
-      expect(snippets.get("check")).toBe("Global review guidelines");
-      expect(snippets.get("test")).toBe("Project test guidelines");
-      expect(snippets.get("tdd")).toBe("Project test guidelines");
-      expect(snippets.get("testing")).toBe("Project test guidelines");
+      expect(snippets.get("review")?.content).toBe("Global review guidelines");
+      expect(snippets.get("pr")?.content).toBe("Global review guidelines");
+      expect(snippets.get("check")?.content).toBe("Global review guidelines");
+      expect(snippets.get("test")?.content).toBe("Project test guidelines");
+      expect(snippets.get("tdd")?.content).toBe("Project test guidelines");
+      expect(snippets.get("testing")?.content).toBe("Project test guidelines");
     });
 
     it("should allow project to override global aliases", async () => {
@@ -172,9 +172,9 @@ Project careful`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       // Project should override with its aliases
-      expect(snippets.get("careful")).toBe("Project careful");
-      expect(snippets.get("safe")).toBe("Project careful");
-      expect(snippets.get("cautious")).toBeUndefined();
+      expect(snippets.get("careful")?.content).toBe("Project careful");
+      expect(snippets.get("safe")?.content).toBe("Project careful");
+      expect(snippets.get("cautious")?.content).toBeUndefined();
       expect(snippets.size).toBe(2);
     });
   });
@@ -185,7 +185,7 @@ Project careful`,
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       expect(snippets.size).toBe(1);
-      expect(snippets.get("empty")).toBe("");
+      expect(snippets.get("empty")?.content).toBe("");
     });
 
     it("should handle snippet with only metadata", async () => {
@@ -199,8 +199,8 @@ aliases: meta
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       expect(snippets.size).toBe(2);
-      expect(snippets.get("metadata-only")).toBe("");
-      expect(snippets.get("meta")).toBe("");
+      expect(snippets.get("metadata-only")?.content).toBe("");
+      expect(snippets.get("meta")?.content).toBe("");
     });
 
     it("should handle multiline content", async () => {
@@ -212,7 +212,7 @@ Line 3`,
       );
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
-      expect(snippets.get("multiline")).toBe("Line 1\nLine 2\nLine 3");
+      expect(snippets.get("multiline")?.content).toBe("Line 1\nLine 2\nLine 3");
     });
 
     it("should ignore non-.md files", async () => {
@@ -221,7 +221,7 @@ Line 3`,
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       expect(snippets.size).toBe(1);
-      expect(snippets.get("valid")).toBe("This should be loaded");
+      expect(snippets.get("valid")?.content).toBe("This should be loaded");
       expect(snippets.has("not-a-snippet")).toBe(false);
     });
 
@@ -238,7 +238,7 @@ Content`,
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       // Should load valid snippet, skip invalid one
-      expect(snippets.get("special-chars")).toBe("Special content");
+      expect(snippets.get("special-chars")?.content).toBe("Special content");
     });
 
     it("should handle non-existent directories gracefully", async () => {

package/src/loader.ts

@@ -1,16 +1,16 @@
-import { readdir, readFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import matter from "gray-matter";
 import { CONFIG, PATHS } from "./constants.js";
 import { logger } from "./logger.js";
-import type { SnippetFrontmatter, SnippetRegistry } from "./types.js";
+import type { SnippetFrontmatter, SnippetInfo, SnippetRegistry } from "./types.js";
 
 /**
  * Loads all snippets from global and project directories
  *
  * @param projectDir - Optional project directory path (from ctx.directory)
  * @param globalDir - Optional global snippets directory (for testing)
- * @returns A map of snippet keys (lowercase) to their content
+ * @returns A map of snippet keys (lowercase) to their SnippetInfo
  */
 export async function loadSnippets(
   projectDir?: string,
@@ -41,7 +41,7 @@ export async function loadSnippets(
 async function loadFromDirectory(
   dir: string,
   registry: SnippetRegistry,
-  source: string,
+  source: "global" | "project",
 ): Promise<void> {
   try {
     const files = await readdir(dir);
@@ -49,9 +49,9 @@ async function loadFromDirectory(
     for (const file of files) {
       if (!file.endsWith(CONFIG.SNIPPET_EXTENSION)) continue;
 
-      const snippet = await loadSnippetFile(dir, file);
+      const snippet = await loadSnippetFile(dir, file, source);
       if (snippet) {
-        registerSnippet(registry, snippet.name, snippet.content, snippet.aliases);
+        registerSnippet(registry, snippet);
       }
     }
 
@@ -73,9 +73,14 @@ async function loadFromDirectory(
  *
  * @param dir - Directory containing the snippet file
  * @param filename - The filename to load (e.g., "my-snippet.md")
- * @returns The parsed snippet data, or null if parsing failed
+ * @param source - Whether this is a global or project snippet
+ * @returns The parsed snippet info, or null if parsing failed
  */
-async function loadSnippetFile(dir: string, filename: string) {
+async function loadSnippetFile(
+  dir: string,
+  filename: string,
+  source: "global" | "project",
+): Promise<SnippetInfo | null> {
   try {
     const name = basename(filename, CONFIG.SNIPPET_EXTENSION);
     const filePath = join(dir, filename);
@@ -95,7 +100,14 @@ async function loadSnippetFile(dir: string, filename: string) {
       }
     }
 
-    return { name, content, aliases };
+    return {
+      name,
+      content,
+      aliases,
+      description: frontmatter.description,
+      filePath,
+      source,
+    };
   } catch (error) {
     // Failed to read or parse this snippet - skip it
     logger.warn("Failed to load snippet file", {
@@ -109,34 +121,146 @@ async function loadSnippetFile(dir: string, filename: string) {
 /**
  * Registers a snippet and its aliases in the registry
  *
- * @param registry - The snippet registry to update
- * @param name - The primary name of the snippet
+ * @param registry - The registry to add the snippet to
+ * @param snippet - The snippet info to register
+ */
+function registerSnippet(registry: SnippetRegistry, snippet: SnippetInfo): void {
+  const key = snippet.name.toLowerCase();
+
+  // If snippet with same name exists, remove its old aliases first
+  const existing = registry.get(key);
+  if (existing) {
+    for (const alias of existing.aliases) {
+      registry.delete(alias.toLowerCase());
+    }
+  }
+
+  // Register the snippet under its name
+  registry.set(key, snippet);
+
+  // Register under all aliases (pointing to the same snippet info)
+  for (const alias of snippet.aliases) {
+    registry.set(alias.toLowerCase(), snippet);
+  }
+}
+
+/**
+ * Lists all unique snippets (by name) from the registry
+ *
+ * @param registry - The snippet registry
+ * @returns Array of unique snippet info objects
+ */
+export function listSnippets(registry: SnippetRegistry): SnippetInfo[] {
+  const seen = new Set<string>();
+  const snippets: SnippetInfo[] = [];
+
+  for (const snippet of registry.values()) {
+    if (!seen.has(snippet.name)) {
+      seen.add(snippet.name);
+      snippets.push(snippet);
+    }
+  }
+
+  return snippets;
+}
+
+/**
+ * Ensures the snippets directory exists
+ */
+export async function ensureSnippetsDir(projectDir?: string): Promise<string> {
+  const dir = projectDir ? join(projectDir, ".opencode", "snippet") : PATHS.SNIPPETS_DIR;
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Creates a new snippet file
+ *
+ * @param name - The snippet name (without extension)
  * @param content - The snippet content
- * @param aliases - Alternative names for the snippet
+ * @param options - Optional metadata (aliases, description)
+ * @param projectDir - If provided, creates in project directory; otherwise global
+ * @returns The path to the created snippet file
  */
-function registerSnippet(
-  registry: SnippetRegistry,
+export async function createSnippet(
   name: string,
   content: string,
-  aliases: string[],
-) {
-  const key = name.toLowerCase();
-
-  // If snippet already exists, remove all entries with the old content
-  const oldContent = registry.get(key);
-  if (oldContent !== undefined) {
-    for (const [k, v] of registry.entries()) {
-      if (v === oldContent) {
-        registry.delete(k);
-      }
+  options: { aliases?: string[]; description?: string } = {},
+  projectDir?: string,
+): Promise<string> {
+  const dir = await ensureSnippetsDir(projectDir);
+  const filePath = join(dir, `${name}${CONFIG.SNIPPET_EXTENSION}`);
+
+  // Build frontmatter if we have metadata
+  const frontmatter: SnippetFrontmatter = {};
+  if (options.aliases?.length) {
+    frontmatter.aliases = options.aliases;
+  }
+  if (options.description) {
+    frontmatter.description = options.description;
+  }
+
+  // Create file content with frontmatter if needed
+  let fileContent: string;
+  if (Object.keys(frontmatter).length > 0) {
+    fileContent = matter.stringify(content, frontmatter);
+  } else {
+    fileContent = content;
+  }
+
+  await writeFile(filePath, fileContent, "utf-8");
+  logger.info("Created snippet", { name, path: filePath });
+
+  return filePath;
+}
+
+/**
+ * Deletes a snippet file
+ *
+ * @param name - The snippet name (without extension)
+ * @param projectDir - If provided, looks in project directory first; otherwise global
+ * @returns The path of the deleted file, or null if not found
+ */
+export async function deleteSnippet(name: string, projectDir?: string): Promise<string | null> {
+  // Try project directory first if provided
+  if (projectDir) {
+    const projectPath = join(
+      projectDir,
+      ".opencode",
+      "snippet",
+      `${name}${CONFIG.SNIPPET_EXTENSION}`,
+    );
+    try {
+      await unlink(projectPath);
+      logger.info("Deleted project snippet", { name, path: projectPath });
+      return projectPath;
+    } catch {
+      // Not found in project, try global
     }
   }
 
-  // Register with primary name (lowercase)
-  registry.set(key, content);
+  // Try global directory
+  const globalPath = join(PATHS.SNIPPETS_DIR, `${name}${CONFIG.SNIPPET_EXTENSION}`);
+  try {
+    await unlink(globalPath);
+    logger.info("Deleted global snippet", { name, path: globalPath });
+    return globalPath;
+  } catch {
+    logger.warn("Snippet not found for deletion", { name });
+    return null;
+  }
+}
 
-  // Register all aliases (lowercase)
-  for (const alias of aliases) {
-    registry.set(alias.toLowerCase(), content);
+/**
+ * Reloads snippets into the registry from disk
+ */
+export async function reloadSnippets(
+  registry: SnippetRegistry,
+  projectDir?: string,
+): Promise<void> {
+  registry.clear();
+  const fresh = await loadSnippets(projectDir);
+  for (const [key, value] of fresh) {
+    registry.set(key, value);
   }
 }

package/src/logger.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { OPENCODE_CONFIG_DIR } from "./constants.js";
+import { PATHS } from "./constants.js";
 
 /**
  * Check if debug logging is enabled via environment variable
@@ -14,7 +14,7 @@ export class Logger {
   private logDir: string;
 
   constructor(logDirOverride?: string) {
-    this.logDir = logDirOverride ?? join(OPENCODE_CONFIG_DIR, "logs", "snippets");
+    this.logDir = logDirOverride ?? join(PATHS.CONFIG_DIR, "logs", "snippets");
   }
 
   get enabled(): boolean {

package/src/notification.ts

@@ -0,0 +1,29 @@
+import { logger } from "./logger.js";
+
+/**
+ * Sends a message that will be displayed but ignored by the AI
+ * Used for command output that shouldn't trigger AI responses
+ *
+ * @param client - The OpenCode client instance
+ * @param sessionId - The current session ID
+ * @param text - The text to display
+ */
+export async function sendIgnoredMessage(
+  client: any,
+  sessionId: string,
+  text: string,
+): Promise<void> {
+  try {
+    await client.session.prompt({
+      path: { id: sessionId },
+      body: {
+        noReply: true,
+        parts: [{ type: "text", text, ignored: true }],
+      },
+    });
+  } catch (error) {
+    logger.error("Failed to send ignored message", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/src/types.ts

@@ -11,9 +11,21 @@ export interface Snippet {
 }
 
 /**
- * Snippet registry that maps keys to content
+ * Extended snippet info with file metadata
  */
-export type SnippetRegistry = Map<string, string>;
+export interface SnippetInfo {
+  name: string;
+  content: string;
+  aliases: string[];
+  description?: string;
+  filePath: string;
+  source: "global" | "project";
+}
+
+/**
+ * Snippet registry that maps keys to snippet info
+ */
+export type SnippetRegistry = Map<string, SnippetInfo>;
 
 /**
  * Frontmatter data from snippet files