opencodekit 0.18.8 → 0.18.9

package/dist/index.js

@@ -18,7 +18,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.18.8";
+var version = "0.18.9";
 
 //#endregion
 //#region src/utils/errors.ts

package/dist/template/.opencode/agent/explore.md

@@ -6,7 +6,6 @@ steps: 25
 tools:
   edit: false
   write: false
-  bash: false
   todowrite: false
   memory-update: false
   observation: false
@@ -14,6 +13,14 @@ tools:
   websearch: false
   webfetch: false
   codesearch: false
+permission:
+  bash:
+    "*": allow
+    "rm*": deny
+    "git push*": deny
+    "git commit*": deny
+    "git reset*": deny
+    "sudo*": deny
 ---
 
 You are OpenCode, the best coding agent on the planet.
@@ -32,8 +39,14 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 
 ## Tools — Use These for Local Code Search
 
+**Prefer tilth CLI** (`npx -y tilth`) for symbol search and file reading — it combines grep + tree-sitter + cat into one call. See `tilth-cli` skill for full syntax.
+
 | Tool | Use For | Example |
 |------|---------|--------|
+| `tilth` (symbol) | AST-aware symbol search (definitions + usages) | `npx -y tilth handleAuth --scope src/` |
+| `tilth` (read) | Smart file reading with outline for large files | `npx -y tilth src/auth.ts --section 44-89` |
+| `tilth` (glob) | Find files by pattern with token estimates | `npx -y tilth "*.test.ts" --scope src/` |
+| `tilth` (map) | Codebase structural overview | `npx -y tilth --map --scope src/` |
 | `grep` | Find text/regex patterns in files | `grep(pattern: "PatchEntry", include: "*.ts")` |
 | `glob` | Find files by name/pattern | `glob(pattern: "src/**/*.ts")` |
 | `lsp` (goToDefinition) | Jump to symbol definition | `lsp(operation: "goToDefinition", filePath: "...", line: N, character: N)` |
@@ -42,29 +55,32 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 | `read` | Read file content | `read(filePath: "src/utils/patch.ts")` |
 
 **NEVER** use `websearch`, `webfetch`, or `codesearch` — those search the internet, not your project.
+**NEVER** modify files or run destructive commands — bash is for tilth CLI and read-only operations only.
 
 ## Rules
 
 - Never modify files — read-only is a hard constraint
+- Bash is enabled **only** for tilth CLI (`npx -y tilth`) — do not use bash for anything else
 - Return absolute paths in final output
 - Cite `file:line` evidence whenever possible
-- **Always start with `grep` or `glob`** to locate files and symbols — do NOT read directories to browse
+- **Prefer tilth** for symbol search, then fall back to `grep` or `glob`
 - Use LSP for precise navigation after finding candidate locations
 - Stop when you can answer with concrete evidence
 
 ## Navigation Patterns
 
-1. **Search first, read second**: `grep` to find where a symbol lives, then `read` only that section
+1. **tilth first, grep second**: `npx -y tilth <symbol> --scope src/` finds definitions AND usages in one call; fall back to `grep` if tilth is unavailable
 2. **Don't re-read**: If you already read a file, reference what you learned — don't read it again
-3. **Follow the chain**: definition → usages → callers via LSP findReferences
-4. **Target ≤3 tool calls per symbol**: grep → read section → done
+3. **Follow the chain**: definition → usages → callers via tilth symbol search or LSP findReferences
+4. **Target ≤3 tool calls per symbol**: tilth search → read section → done
 
 ## Workflow
 
-1. `grep` or `glob` to discover candidate files
-2. `lsp` goToDefinition/findReferences for precise symbol navigation
-3. `read` only the relevant sections (use offset/limit)
-4. Return findings with file:line evidence
+1. `npx -y tilth <symbol> --scope src/` or `grep`/`glob` to discover symbols and files
+2. `npx -y tilth <file> --section <range>` or `read` for targeted file sections
+3. `lsp` goToDefinition/findReferences for precise cross-file navigation when needed
+4. `npx -y tilth --map --scope <dir>` for structural overview of unfamiliar areas
+5. Return findings with file:line evidence
 
 ## Output
 
@@ -74,6 +90,7 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 
 ## Failure Handling
 
+- If tilth is unavailable, fall back to `grep` + `glob` + targeted `read`
 - If LSP is unavailable, fall back to `grep` + targeted `read`
 - If results are ambiguous, list assumptions and best candidate paths
 - Never guess — mark uncertainty explicitly

package/dist/template/.opencode/agent/general.md

@@ -147,12 +147,14 @@ Before claiming task done:
 
 ## Workflow
 
-1. Read relevant files
+1. Read relevant files (prefer `npx -y tilth <symbol> --scope src/` for fast symbol lookup)
 2. Confirm scope is small and clear
 3. Make surgical edits
 4. Run validation (lint/typecheck/tests as applicable)
 5. Report changed files with `file:line` references
 
+**Code navigation:** Use tilth CLI for AST-aware search when available — see `tilth-cli` skill for syntax. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for symbol definitions.
+
 ## Progress Updates
 
 - For multi-step work, provide brief milestone updates

package/dist/template/.opencode/agent/plan.md

@@ -381,12 +381,14 @@ When planning under constraint:
 
 ## Workflow
 
-1. **Ground**: Read bead artifacts (`prd.md`, `plan.md` if present)
+1. **Ground**: Read bead artifacts (`prd.md`, `plan.md` if present); use `npx -y tilth --map --scope src/` for codebase overview
 2. **Calibrate**: Understand goal, constraints, and success criteria
-3. **Transform**: Launch parallel research (`task` subagents) when uncertainty remains; decompose into phases/tasks with explicit dependencies
+3. **Transform**: Launch parallel research (`task` subagents) when uncertainty remains; use `npx -y tilth <symbol> --scope src/` for fast codebase discovery; decompose into phases/tasks with explicit dependencies
 4. **Release**: Write actionable plan with exact file paths, commands, and verification
 5. **Reset**: End with a concrete next command (`/ship <id>`, `/start <child-id>`, etc.)
 
+**Code navigation:** Use tilth CLI for AST-aware search and `--map` for structural overview — see `tilth-cli` skill.
+
 ## Output
 
 - Keep plan steps small and executable

package/dist/template/.opencode/agent/review.md

@@ -193,11 +193,13 @@ return <div>No messages</div>  // State exists but not used
 
 ## Workflow
 
-1. Read changed files and nearby context
+1. Read changed files and nearby context (prefer `npx -y tilth <symbol> --scope src/` for fast cross-file tracing)
 2. Identify and validate findings by severity (P0, P1, P2, P3)
 3. For each finding: explain why, when it happens, and impact
 4. If no qualifying findings exist, say so explicitly
 
+**Code navigation:** Use tilth CLI for AST-aware symbol search when tracing cross-file dependencies — see `tilth-cli` skill. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for understanding call chains.
+
 ## Output
 
 Structure:

package/dist/template/.opencode/skill/tilth-cli/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: tilth-cli
+description: AST-aware code navigation via tilth CLI. Use when subagents need structural code search, smart file reading, or codebase mapping — complements MCP tilth (which only the main agent can access).
+version: 1.1.0
+tags: [code-navigation, search, subagent]
+dependencies: []
+---
+
+# tilth CLI for Subagents
+
+> **Why this exists:** tilth MCP tools (`tilth_tilth_search`, `tilth_tilth_read`, etc.) are only available to the main agent. Subagents cannot access MCP tools but CAN use Bash. This skill teaches subagents to call tilth directly from the command line.
+
+## When to Use
+
+- When subagents need structural code search (they cannot access tilth MCP tools)
+- When you need `--map` for codebase skeleton (CLI-only feature, not in MCP)
+- For any agent that has Bash access but not tilth MCP
+
+## When NOT to Use
+
+- Main agent should prefer tilth MCP tools — they have session dedup and hash-anchored editing
+- For trivial lookups where grep/read suffices
+
+## Prerequisites
+
+tilth must be available. Use `npx -y tilth` if not globally installed:
+
+```bash
+npx -y tilth <query> [options]
+```
+
+## How tilth CLI Works
+
+tilth has **one command** with **smart auto-detection**. Pass a query and it figures out what to do:
+
+| Query Pattern | Detection                        | Action                                                  |
+| ------------- | -------------------------------- | ------------------------------------------------------- |
+| `src/auth.ts` | File path (exists on disk)       | **Read file** — smart outline for large, full for small |
+| `handleAuth`  | Symbol name (camelCase, etc.)    | **Symbol search** — AST definitions + usages            |
+| `"*.test.ts"` | Glob pattern (contains `*`, `?`) | **File listing** — matched paths with token estimates   |
+| `"TODO fix"`  | Text (doesn't match above)       | **Text search** — literal content matches               |
+
+## Core Operations
+
+### 1. Read a File
+
+```bash
+npx -y tilth src/index.ts                      # Smart view (outline if large, full if small)
+npx -y tilth src/index.ts --full                # Force full content
+npx -y tilth src/index.ts --section 45-89       # Exact line range
+npx -y tilth src/index.ts --section "## Config" # By heading
+```
+
+Output: numbered lines (`N  content`). Large files get a structural outline; use `--section` to drill into specific ranges.
+
+### 2. Search for Symbols
+
+```bash
+npx -y tilth initCommand --scope src/           # Find definition + all usages
+npx -y tilth handleAuth --scope src/auth/       # Scoped to subdirectory
+```
+
+Returns: definitions first (with expanded source), then usages with context lines.
+
+### 3. Search for Text
+
+```bash
+npx -y tilth "TODO" --scope src/                # Literal text search
+npx -y tilth "version" --scope src/             # Finds all occurrences
+```
+
+tilth auto-detects text vs symbol. Identifiers (camelCase, snake_case) → symbol search. Multi-word or quoted strings → text search.
+
+### 4. List Files (Glob)
+
+```bash
+npx -y tilth "*.test.ts" --scope src/           # List test files
+npx -y tilth "*.ts" --scope src/commands/       # List TS files in subdir
+```
+
+Returns: matched file paths with token size estimates.
+
+### 5. Codebase Map (CLI-Only)
+
+```bash
+npx -y tilth --map --scope src/                 # Structural skeleton
+npx -y tilth --map --scope .                    # Whole project
+```
+
+Returns: directory tree with exported symbols per file. **CLI-only** — not available in MCP mode.
+
+## Available Flags
+
+| Flag                | Purpose                                | Example              |
+| ------------------- | -------------------------------------- | -------------------- |
+| `--scope <DIR>`     | Restrict search to directory           | `--scope src/`       |
+| `--section <RANGE>` | Line range or heading for file reads   | `--section 45-89`    |
+| `--full`            | Force full file content (skip outline) | `--full`             |
+| `--budget <N>`      | Max tokens in response                 | `--budget 2000`      |
+| `--json`            | Machine-readable JSON output           | `--json`             |
+| `--map`             | Generate codebase structure map        | `--map --scope src/` |
+
+**Note:** `--kind`, `--deps`, `--expand`, and multi-symbol comma syntax are MCP-only features. The CLI does not support them.
+
+## MCP vs CLI Comparison
+
+| Feature                               | MCP (main agent) | CLI (all agents)    |
+| ------------------------------------- | ---------------- | ------------------- |
+| Session dedup (`[shown earlier]`)     | Yes              | No                  |
+| Hash-anchored editing (`tilth_edit`)  | Yes              | No                  |
+| Blast-radius analysis (`tilth_deps`)  | Yes              | No                  |
+| Multi-symbol search (`sym1,sym2`)     | Yes              | No                  |
+| `--kind` flag (content/regex/callers) | Yes              | No                  |
+| `--expand` control                    | Yes              | No                  |
+| `--map` codebase skeleton             | No               | Yes                 |
+| Subagent access                       | No (main only)   | Yes (any with Bash) |
+| Process overhead                      | Once (~17ms)     | Per call (~17ms)    |
+
+## Output Format Examples
+
+### File read (small file)
+
+```
+# src/config.ts (45 lines, ~380 tokens) [full]
+
+1  import { z } from 'zod';
+2  export const schema = z.object({
+...
+```
+
+### Symbol search
+
+```
+# Search: "initCommand" in src/ — 6 matches (2 definitions, 4 usages)
+
+### Definitions (2)
+## commands/init.ts:515-961 [definition]
+→ [515-961]  export async function initCommand(...)
+
+### Usages — same package (4)
+## index.ts:10 [usage]
+→ [10]   import { initCommand } from "./commands/init.js";
+```
+
+### Codebase map
+
+```
+# Map: src/ (depth 3)
+index.ts (~1214 tokens)
+commands/
+  init.ts: initCommand, detectMode, ...
+  upgrade.ts: checkVersion, upgradeCommand, ...
+utils/
+  errors.ts: resolveOpencodePath, showError, ...
+```
+
+## Usage Tips
+
+- **Search first, read second** — symbol search finds definitions AND shows expanded source
+- **Use `--section` for large files** — outline tells you line ranges; drill in with `--section 44-89`
+- **Use `--scope`** to narrow searches — avoids scanning irrelevant directories
+- **Use `--budget`** when you need concise output (limits token count)
+- **~17ms per call** — fast enough for interactive use, but avoid unnecessary repeated calls
+
+## Example Subagent Dispatch
+
+```typescript
+task({
+  subagent_type: "general",
+  prompt: `Use tilth CLI for code navigation (run via: npx -y tilth).
+
+Find the definition of \`initCommand\` and understand how it's called:
+  npx -y tilth initCommand --scope src/
+
+Then read the relevant file section:
+  npx -y tilth src/commands/init.ts --section 515-600
+
+[rest of task instructions]`,
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.18.8",
+	"version": "0.18.9",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",