opencode-ask 1.1.0

package/README.md

@@ -0,0 +1,89 @@
+# Ask — Code Q&A for OpenCode
+
+Ask is a read-only Q&A agent for [OpenCode](https://opencode.ai). It answers questions about your codebase — explains how things work, finds relevant code, explores architecture, and provides deep insights — without ever editing your files.
+
+Powered by your existing OpenCode model. No extra API keys. No subscriptions.
+
+---
+
+## Quick Start
+
+### Install
+
+1. Clone this repo or download `ask.js`
+2. Copy or symlink `ask.js` to your OpenCode config plugins:
+   ```bash
+   mkdir -p ~/.config/opencode/plugins
+   cp ask.js ~/.config/opencode/plugins/ask.js
+   ```
+3. Add to `~/.config/opencode/opencode.json`:
+   ```json
+   {
+     "plugin": ["./plugins/ask.js"]
+   }
+   ```
+4. Restart OpenCode.
+
+### Use
+
+Ask is available both as a **general agent** (selectable in OpenCode's agent picker) and via `@ask` in any conversation:
+
+- **General mode** — Select "Ask" from the agent list for a dedicated Q&A session
+- **Subagent mode** — Type `@ask how does collision work?` mid-conversation
+
+Ask will explore the codebase, gather context, and give you a thorough answer — complete with file paths, line numbers, and architectural context.
+
+---
+
+## How It Works
+
+Ask is an OpenCode plugin that registers a `subagent` named `ask`. When invoked, the agent:
+
+1. **Explores** — searches your codebase with grep, glob, and targeted file reads
+2. **Analyzes** — traces code paths, understands architecture, identifies patterns
+3. **Answers** — provides a clear, structured response with source citations
+4. **Never edits** — the agent has `edit: deny` and `write: deny` baked in
+
+---
+
+## vs. GitHub Copilot `/ask`
+
+| | GitHub Copilot `/ask` | OpenCode **Ask** |
+|---|---|---|
+| **Scope** | Current file + editor selection | Full workspace exploration |
+| **Search tools** | None (inline context only) | grep, glob, read, bash, web |
+| **Architecture awareness** | Limited to visible code | Deep — traces across files and layers |
+| **Permission model** | Read-only by convention | Enforced: `edit: deny`, `write: deny` |
+| **Invocation** | In-editor chat panel | `@ask` in any OpenCode conversation |
+| **Model** | Copilot's model | Your configured OpenCode model |
+| **Subagent dispatch** | No | Yes — can delegate parallel searches via `task` |
+| **Custom prompt** | Fixed | Open source — fork and customize |
+| **Offline** | No (cloud only) | Depends on your model provider |
+
+### When to use which
+
+**Use Copilot `/ask`** when you need a quick answer about the file or selection you're actively editing — minimal context switching.
+
+**Use OpenCode Ask** when you need deep understanding — tracing logic across many files, understanding architecture, investigating bugs, or orienting yourself in an unfamiliar codebase.
+
+---
+
+## Permissions
+
+| Tool | Access |
+|------|--------|
+| `read` | `allow` |
+| `grep` | `allow` |
+| `glob` | `allow` |
+| `bash` | `git *: allow, *: ask` |
+| `webfetch` | `allow` |
+| `websearch` | `allow` |
+| `task` | `allow` |
+| `edit` | `deny` |
+| `write` | `deny` |
+
+---
+
+## License
+
+MIT

package/ask.js

@@ -0,0 +1,65 @@
+const PROMPT = `You are Ask, a specialized code Q&A agent for OpenCode.
+
+Your purpose is to answer questions about the codebase — explain how things work,
+find relevant code, explore architecture, and provide deep insights.
+You NEVER write or edit code. You are an answerer, not a doer.
+
+## Core Behavior
+
+1. **Explore before answering** — Use grep, glob, read, and bash (git) to gather
+   full context before formulating answers. Don't rely on a single search hit.
+
+2. **Cite sources** — Always include specific file paths and line numbers.
+   Example: \`src/core/auth.ts:45-60\`. If code is spread across multiple files,
+   reference each one.
+
+3. **Explain the "why"** — Don't just describe what code does. Explain the
+   design decisions, trade-offs, and architectural context that led to it.
+
+4. **Be thorough** — Cover edge cases, error paths, and related code. If
+   something looks important, dig deeper with additional reads.
+
+5. **Be humble** — If uncertain, say so. Suggest what additional context would
+   help provide a definitive answer.
+
+6. **Think conversationally** — Ask clarifying questions when the intent is
+   unclear. Build on previous context in the same session.
+
+## Response Format
+
+- Start with a brief answer summary (1-2 sentences)
+- Follow with detailed explanation and code references
+- Use code blocks for relevant snippets
+- End with a follow-up prompt if appropriate
+
+## Restrictions
+
+- NEVER use edit or write tools
+- If asked to make changes, politely redirect: "I'm a Q&A agent — I can help
+  you understand this code. OpenCode's main agent can make the change."
+- Do not generate boilerplate or scaffold new files`
+
+export default async () => {
+  return {
+    config: (cfg) => {
+      cfg.agent = cfg.agent || {}
+      cfg.agent["ask"] = {
+        mode: "all",
+        description:
+          "Ask questions about your codebase — explores, explains architecture, finds relevant code, and provides insights. Read-only. No edits.",
+        permission: {
+          edit: "deny",
+          write: "deny",
+          read: "allow",
+          grep: "allow",
+          glob: "allow",
+          bash: { "git *": "allow", "*": "ask" },
+          webfetch: "allow",
+          websearch: "allow",
+          task: "allow",
+        },
+        prompt: PROMPT,
+      }
+    },
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "opencode-ask",
+  "version": "1.1.0",
+  "description": "Ask Agent for OpenCode — Q&A about your codebase, inspired by GitHub Copilot's /ask",
+  "main": "ask.js",
+  "files": [
+    "ask.js",
+    "README.md"
+  ],
+  "type": "module",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "ask",
+    "qna",
+    "code-review"
+  ],
+  "license": "MIT",
+  "author": "RASHEEM",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MRZ07/ask.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}