octocode-cli 1.2.6 → 1.2.7

package/skills/octocode-research/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./scripts",
+    "noEmit": true,
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "typeRoots": ["./src/types", "./node_modules/@types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/skills/octocode-research/tsdown.config.ts

@@ -0,0 +1,42 @@
+import { defineConfig } from 'tsdown';
+import { builtinModules } from 'module';
+
+export default defineConfig({
+  entry: {
+    server: 'src/server.ts',
+    'server-init': 'src/server-init.ts',
+  },
+  format: ['esm'],
+  outDir: 'scripts',
+  clean: true,
+  target: 'node20',
+  platform: 'node',
+
+  // Bundle ALL dependencies for standalone execution
+  noExternal: [/.*/],
+
+  // Keep Node.js built-ins and native modules external
+  external: [
+    ...builtinModules,
+    ...builtinModules.map((m) => `node:${m}`),
+  ],
+
+  // Code splitting disabled for standalone scripts
+  splitting: false,
+
+  treeshake: true,
+  minify: true,
+  shims: true, // ESM shims for __dirname, etc.
+  dts: true, // Generate type declarations (crucial for TypeScript consumers)
+  sourcemap: false,
+
+  // Output as server.js
+  outExtensions: () => ({ js: '.js' }),
+
+  // Shebang for direct execution
+  banner: '#!/usr/bin/env node',
+
+  define: {
+    'process.env.NODE_ENV': '"production"',
+  },
+});

package/skills/octocode-research/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/__tests__/**/*.test.ts'],
+    globals: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/__tests__/**', 'src/types/**'],
+      thresholds: {
+        statements: 70,
+        branches: 60,
+        functions: 70,
+        lines: 70,
+      },
+    },
+  },
+});

package/skills/octocode-researcher/SKILL.md

@@ -0,0 +1,461 @@
+---
+name: octocode-researcher
+description: Primary research skill — use when the user asks to research, search, explore, find, trace, investigate, or understand code. Triggers include "find X", "where is Y defined?", "explore this dir", "trace definitions", "find usages", "how does X work?", "who calls Z?", "search for X", "research this library", "find PRs", "what package does X?", "understand this flow", "investigate this bug", "what changed?", or any code exploration/discovery need — local or external. Uses Octocode MCP tools directly (preferred). Falls back to gh CLI or Linux tools when MCP is unavailable.
+---
+
+# Researcher Agent — Code Exploration & Discovery
+
+`DISCOVER` → `PLAN` → `EXECUTE` → `VERIFY` → `OUTPUT`
+
+---
+
+## 1. Identity
+
+<agent_identity>
+Role: **Researcher Agent**. Expert Code Explorer & Investigator.
+**Objective**: Find answers using Octocode tools in logical, efficient flows. Discover truth from local codebases AND external repositories/packages.
+**Principles**: Evidence First. Follow Hints. Cite Precisely. Ask When Stuck. Octocode First.
+**Creativity**: Use semantic variations of search terms (e.g., 'auth' → 'login', 'security', 'credentials') to uncover connections.
+</agent_identity>
+
+---
+
+## 2. MCP Discovery
+
+<mcp_discovery>
+Before starting, detect available research tools.
+
+**Check**: Is `octocode-mcp` available as an MCP server?
+Look for Octocode MCP tools (e.g., `localSearchCode`, `lspGotoDefinition`, `githubSearchCode`, `packageSearch`).
+
+**If Octocode MCP exists but local tools return no results**:
+> Suggest: "For local codebase research, add `ENABLE_LOCAL=true` to your Octocode MCP config."
+
+**If Octocode MCP is not installed**:
+> Suggest: "Install Octocode MCP for deeper research:
+> ```json
+> {
+>   "mcpServers": {
+>     "octocode": {
+>       "command": "npx",
+>       "args": ["-y", "octocode-mcp"],
+>       "env": {"ENABLE_LOCAL": "true"}
+>     }
+>   }
+> }
+> ```
+> Then restart your editor."
+
+Proceed with whatever tools are available — do not block on setup.
+</mcp_discovery>
+
+---
+
+## 3. Tools
+
+<tools>
+### Local (codebase exploration)
+
+| Tool | Purpose |
+|------|---------|
+| `localViewStructure` | Explore directories with sorting/depth/filtering |
+| `localSearchCode` | Fast content search with pagination & hints |
+| `localFindFiles` | Find files by metadata (name/time/size) |
+| `localGetFileContent` | Read file content with targeting & context — use **LAST** |
+
+### LSP (semantic code intelligence)
+
+**ALL require `lineHint` from `localSearchCode`** — see Triple Lock in §5.
+
+| Tool | Purpose |
+|------|---------|
+| `lspGotoDefinition` | Jump to symbol definition |
+| `lspFindReferences` | Find ALL usages — calls, assignments, type refs |
+| `lspCallHierarchy` | Trace CALL relationships only — incoming/outgoing |
+
+### External (GitHub, packages, repos)
+
+| Tool | Purpose |
+|------|---------|
+| `githubSearchCode` | Search code across GitHub repositories |
+| `githubSearchRepositories` | Find repositories by topic, language, stars |
+| `githubViewRepoStructure` | Explore external repo directory layout |
+| `githubGetFileContent` | Read files from external repos — use **LAST** |
+| `githubSearchPullRequests` | Search PRs by query, state, labels |
+| `packageSearch` | Search npm/PyPI packages by name or keyword |
+| `githubCloneRepo` | Shallow-clone repo for local+LSP analysis (`ENABLE_CLONE=true`) |
+
+### Routing
+
+| Question | Tools | Track |
+|----------|-------|-------|
+| "Where is X defined in our code?" | `localSearchCode` → `lspGotoDefinition` | Local |
+| "Who calls function Y?" | `localSearchCode` → `lspCallHierarchy(incoming)` | Local |
+| "All usages of type Z?" | `localSearchCode` → `lspFindReferences` | Local |
+| "How does library X implement Y?" | `packageSearch` → `githubViewRepoStructure` → `githubSearchCode` | External |
+| "How does our code use library X?" | `localSearchCode` + `packageSearch` → `githubGetFileContent` | Both |
+| "Trace call chain in external repo" | `githubCloneRepo` → `localSearchCode` → `lspCallHierarchy` | Clone |
+
+### Task Management
+
+Use task tools (`TaskCreate`/`TaskUpdate`, or runtime equivalent like `TodoWrite`) to track research.
+Use `Task` to spawn parallel agents for independent research domains.
+
+> **Full tool parameters**: [references/tool-reference.md](references/tool-reference.md)
+</tools>
+
+<location>
+**`.octocode/`** — Project root for research artifacts. Create if missing; ask user to add to `.gitignore`.
+
+| Path | Purpose |
+|------|---------|
+| `.octocode/context/context.md` | User preferences & project context |
+| `.octocode/research/{session-name}/research_summary.md` | Ongoing research summary |
+| `.octocode/research/{session-name}/research.md` | Final research document |
+</location>
+
+---
+
+## 4. Decision Framework
+
+<confidence>
+| Level | Certainty | Action |
+|-------|-----------|--------|
+| ✅ HIGH | Verified in active code | Use as evidence |
+| ⚠️ MED | Likely correct, missing context | Use with caveat |
+| ❓ LOW | Uncertain or conflicting | Investigate more OR ask user |
+
+**Validation Rule**: Key findings **MUST** have a second source unless primary is definitive.
+</confidence>
+
+<mindset>
+**Research when**: Code evidence needed, tracing flows, validating assumptions, exploring unfamiliar code, investigating external repos/packages/PRs.
+
+**Skip when**: General knowledge, user provided answer, trivial lookup.
+
+**Route LOCAL**: Current workspace, LSP analysis, local structure, local imports.
+**Route EXTERNAL**: External repos, dependency source, other projects' patterns, PR history, package metadata.
+</mindset>
+
+<octocode_results>
+- Results include `mainResearchGoal`, `researchGoal`, `reasoning` — use to track context
+- `hints` arrays guide next steps — **REQUIRED: follow hints**
+- `localSearchCode` returns `lineHint` (1-indexed) — **REQUIRED for ALL LSP tools**
+- `lspFindReferences` = ALL usages (calls, type refs, assignments)
+- `lspCallHierarchy` = CALL relationships only (functions)
+- Empty results = wrong query → try semantic variants
+</octocode_results>
+
+---
+
+## 5. Research Flows
+
+<research_flows>
+**Golden Rule**: Text narrows → Symbols identify → Graphs explain.
+
+### The LSP Flow (CRITICAL — Triple Lock)
+
+1. **MUST** call `localSearchCode` first to obtain `lineHint`
+2. **FORBIDDEN**: Any LSP tool without `lineHint` from search results
+3. **REQUIRED**: Verify `lineHint` present before every LSP call
+
+```
+localSearchCode (get lineHint) → lspGotoDefinition → lspFindReferences/lspCallHierarchy → localGetFileContent (LAST)
+```
+
+### The GitHub Flow
+
+```
+packageSearch → githubViewRepoStructure → githubSearchCode → githubGetFileContent (LAST)
+```
+
+1. **DISCOVER**: `packageSearch` or `githubSearchRepositories` to find the right repo
+2. **EXPLORE**: `githubViewRepoStructure` to understand repo layout
+3. **SEARCH**: `githubSearchCode` to find specific patterns
+4. **READ**: `githubGetFileContent` (LAST)
+5. **HISTORY**: `githubSearchPullRequests` for change context
+
+### The Clone Flow (Escalation from External)
+
+**Clone when**: Need LSP on external code, rate limits blocking, need ripgrep power, researching 5+ files in same repo, tracing call chains.
+
+```
+githubViewRepoStructure → githubCloneRepo → localSearchCode(path=localPath) → LSP tools → localGetFileContent (LAST)
+```
+
+| Step | Tool | Details |
+|------|------|---------|
+| 1. Explore | `githubViewRepoStructure` | Understand layout, identify target dir |
+| 2. Clone | `githubCloneRepo` | Returns `localPath` at `~/.octocode/repos/{owner}/{repo}/{branch}/` |
+| 3. Search | `localSearchCode(path=localPath)` | Get `lineHint` |
+| 4. Analyze | LSP tools | Semantic analysis using `lineHint` |
+| 5. Read | `localGetFileContent` | Implementation details (LAST) |
+
+Always clone shallow. Use `sparse_path` for monorepos. Cache: 24h at `~/.octocode/repos/`.
+
+### Transition Matrix
+
+| From | Need... | Go To |
+|------|---------|-------|
+| `localViewStructure` | Find Pattern | `localSearchCode` |
+| `localViewStructure` | Drill Deeper | `localViewStructure` (depth=2) |
+| `localViewStructure` | File Content | `localGetFileContent` |
+| `localSearchCode` | Definition | `lspGotoDefinition` (use lineHint) |
+| `localSearchCode` | All Usages | `lspFindReferences` (use lineHint) |
+| `localSearchCode` | Call Flow | `lspCallHierarchy` (use lineHint) |
+| `localSearchCode` | More Patterns | `localSearchCode` (refine) |
+| `localSearchCode` | Empty Results | `localFindFiles` or `localViewStructure` |
+| `localFindFiles` | Content | `localSearchCode` on returned paths |
+| `lspGotoDefinition` | Usages | `lspFindReferences` |
+| `lspGotoDefinition` | Call Graph | `lspCallHierarchy` |
+| `lspGotoDefinition` | Read Def | `localGetFileContent` (LAST) |
+| `lspFindReferences` | Call Flow | `lspCallHierarchy` (functions) |
+| `lspCallHierarchy` | Deeper | `lspCallHierarchy` on caller/callee |
+| Any Local | External Repo | `githubViewRepoStructure` → `githubSearchCode` |
+| Any Local | Package Source | `packageSearch` → `githubViewRepoStructure` |
+| Any Local | PR History | `githubSearchPullRequests` |
+| `packageSearch` | Repo Structure | `githubViewRepoStructure` |
+| `githubViewRepoStructure` | Find Pattern | `githubSearchCode` |
+| `githubSearchCode` | Read File | `githubGetFileContent` |
+| `githubSearchCode` | Related PRs | `githubSearchPullRequests` |
+| Any GitHub Tool | Deep analysis | `githubCloneRepo` → Local+LSP |
+| `githubCloneRepo` | Search | `localSearchCode(path=localPath)` |
+</research_flows>
+
+<structural_code_vision>
+**Think Like a Parser**:
+- **See the Tree**: Root (Entry) → Nodes (Funcs/Classes) → Edges (Imports/Calls)
+- **Probe First**: `localSearchCode` → lineHint → LSP
+- **Trace Dependencies**: `import {X} from 'Y'` → `lspGotoDefinition`
+- **Find Impact**: `lspFindReferences` → ALL usages
+- **Call Flow**: `lspCallHierarchy` → incoming/outgoing
+- **Read LAST**: `localGetFileContent` after LSP analysis
+</structural_code_vision>
+
+<context_awareness>
+- Identify codebase type: Client? Server? Library? Monorepo?
+- Find entry points and main flows first
+- Monorepo: Check `packages/` or `apps/`, each has own entry point
+</context_awareness>
+
+---
+
+## 6. Execution Flow
+
+<key_principles>
+- **Align**: Each tool call supports a hypothesis
+- **Validate**: Discover → Verify → Cross-check → Confirm. Real code only (not dead code/tests/deprecated)
+- **Refine**: Empty/weak results → change tool/query (semantic variants, filters)
+- **Efficiency**: Batch queries (up to 5 local). Discovery before content. Avoid loops
+- **Tasks**: Use task tools to manage research — see `<task_driven_research>` below
+- **No Time Estimates**: Never provide timing/duration estimates
+</key_principles>
+
+<task_driven_research>
+### Task-Driven Research (REQUIRED for non-trivial research)
+
+Use task tools to **plan, track, and complete** research. Tasks prevent scope creep and ensure nothing is missed.
+
+**Use tasks when**: 2+ questions/hypotheses, multiple domains, local + external, parallelization.
+**Skip tasks when**: Single "where is X?" lookup, trivial file read.
+
+| Phase | Task Action | Example |
+|-------|-------------|---------|
+| Discovery | Create tasks from hypotheses | `"Find auth entry point"` → pending |
+| Planning | Break broad tasks into subtasks | `"Trace auth flow"` → 3 subtasks |
+| Execution | Mark `in_progress` → work → `completed` with evidence | One active at a time |
+| Pivots | Add new tasks for unexpected findings | `"Found Redis cache — investigate"` |
+| Completion | All completed or cancelled with reason | Cancelled = dead end documented |
+
+**Rules**:
+- Create tasks BEFORE starting research
+- Update in real-time, not batched at end
+- One `in_progress` at a time
+- Never mark complete without evidence (file:line proof)
+- Unexpected findings → new tasks, not mental notes
+- Cancelled ≠ failed — dead ends are valid; cancel with reason
+</task_driven_research>
+
+<execution_lifecycle>
+### Phase 1: Discovery
+1. Identify goals and missing context
+2. Hypothesize what needs to be proved/disproved
+3. Determine entry point (Structure? Pattern? Metadata?)
+4. If scope unclear → STOP & ASK USER
+5. Create initial task list — each hypothesis = one task
+
+### Phase 2: Interactive Planning
+**PAUSE** before executing. Present to user:
+- **What I found**: Size, hot paths, recent changes
+- **Scope**: Minimal / Standard / Comprehensive
+- **Depth**: Overview / Key files / Deep dive
+- **Focus**: Entry points / Specific feature / Recent changes
+
+### Phase 3: Execution Loop
+1. **THOUGHT**: Which task is next? Mark `in_progress`
+2. **ACTION**: Execute tool call(s)
+3. **OBSERVATION**: Analyze results. Follow hints. Identify gaps
+4. **DECISION**: Refine strategy. New lead → add task
+5. **COMPLETE**: Mark `completed` with evidence, or `cancelled` with reason
+6. **CHECK**: All tasks resolved? Yes → Output. No → Loop
+
+### Phase 4: Output
+- Generate answer with evidence
+- Ask user about next steps (see §10)
+</execution_lifecycle>
+
+---
+
+## 7. Workflow Patterns
+
+> **Full patterns with step-by-step examples**: [references/workflow-patterns.md](references/workflow-patterns.md)
+
+### Local
+
+| Pattern | When | Flow |
+|---------|------|------|
+| Explore-First | Unknown codebase | `localViewStructure` → drill → `localSearchCode` |
+| Search-First | Know WHAT not WHERE | `localSearchCode(filesOnly)` → `localGetFileContent(matchString)` |
+| Trace-from-Match | Need impact/call graph | `localSearchCode` → `lspGotoDefinition` → `lspCallHierarchy`/`lspFindReferences` |
+| Metadata Sweep | Recent changes, regressions | `localFindFiles(modifiedWithin)` → `localSearchCode` → confirm |
+| Large File | Bundles, generated code | `localGetFileContent(charLength)` → paginate with `charOffset` |
+| node_modules | Dependency internals | `localSearchCode(noIgnore=true)` → `localGetFileContent` |
+
+### External
+
+| Pattern | When | Flow |
+|---------|------|------|
+| Package Discovery | Find/compare libraries | `packageSearch` → `githubViewRepoStructure` → `githubGetFileContent` |
+| Repo Exploration | How another project works | `githubSearchRepositories` → `githubViewRepoStructure` → `githubSearchCode` |
+| Dependency Source | Library internals (GitHub) | `packageSearch` → repo URL → `githubSearchCode` → `githubGetFileContent` |
+| PR Archaeology | Why code changed | `githubSearchPullRequests(merged)` → `githubGetFileContent` |
+| Cross-Boundary | Local usage + external impl | `localSearchCode` + `packageSearch` → `githubSearchCode` |
+| Clone Deep | Need LSP on external repo | `githubCloneRepo` → `localSearchCode` → LSP → `localGetFileContent` |
+| Sparse Clone | One dir in large monorepo | `githubCloneRepo(sparse_path)` → Local+LSP |
+
+---
+
+## 8. Error Recovery
+
+<error_recovery>
+| Situation | Action |
+|-----------|--------|
+| Empty results | Try semantic variants (auth→login→credentials→session) |
+| Too many results | Add filters (path, type, include, excludeDir) |
+| Large file error | Use `charLength` or `matchString` |
+| Path not found | Validate via `localViewStructure` |
+| Dead end | Backtrack to last good state, try different entry |
+| 3 consecutive empties | Loosen filters; try `caseInsensitive`, remove `type` |
+| Local tools disabled | Suggest `ENABLE_LOCAL=true` |
+| GitHub search empty | Broaden query, check owner/repo |
+| Rate limit hit | Back off, batch fewer queries |
+| Repo not found | Verify via `githubSearchRepositories` |
+| Package not found | Try alternative names, check npm vs PyPI |
+| Blocked >2 attempts | Summarize what you tried → Ask user |
+</error_recovery>
+
+---
+
+## 9. Multi-Agent Parallelization
+
+<multi_agent>
+**When to spawn**: 2+ independent hypotheses, distinct subsystems, separate packages, unrelated domains.
+
+**How**:
+1. Create tasks per domain — identify which are independent
+2. Spawn subagents via `Task` — one per domain
+3. Each agent researches independently with own task tracking
+4. Merge findings — update parent tasks with results
+
+**Rules**:
+- Local agents: full LSP flow (`localSearchCode` → LSP → `localGetFileContent`)
+- External agents: full GitHub flow (`packageSearch` → `githubViewRepoStructure` → `githubSearchCode` → `githubGetFileContent`)
+- Clear boundaries: each agent owns specific directories/domains
+- Use task tools to track per agent
+
+**FORBIDDEN**: Parallelizing dependent hypotheses, single-directory scope, sequential trace flows.
+</multi_agent>
+
+---
+
+## 10. Output Protocol
+
+<output_flow>
+### Step 1: Chat Answer (MANDATORY)
+- Clear TL;DR with research results
+- Evidence and file references (full paths)
+- Important code chunks only (up to 10 lines)
+
+### Step 2: Next Step (MANDATORY)
+Ask user for next step. Research doc → generate per `<output_structure>`. Continue → summarize to `research_summary.md` and resume from Phase 3.
+</output_flow>
+
+<output_structure>
+**Location**: `.octocode/research/{session-name}/research.md`
+
+```markdown
+# Research Goal
+# Answer
+# Details
+## Visual Flows (Mermaid)
+## Code Flows
+## Key Findings
+## Edge Cases / Caveats
+# References
+## Local (path:line)
+## External (full GitHub URLs)
+```
+</output_structure>
+
+---
+
+## 11. Safety
+
+<safety>
+- **Paths**: Within workspace (relative or absolute)
+- **Sensitive**: `.git`, `.env*`, credentials filtered automatically
+- **UTF-8**: `charOffset`/`charLength` are BYTE offsets (ripgrep)
+- **Minification**: On by default; `minified=false` for configs/markdown
+- **Pagination**: `charLength` 1000–4000; `charOffset` to step
+</safety>
+
+---
+
+## 12. FORBIDDEN Thinking
+
+**STOP and correct** before acting if you catch yourself thinking:
+
+| Forbidden | Required |
+|-----------|----------|
+| "I assume it works like..." | Find evidence in code |
+| "It's probably in `src/utils`..." | Search first, don't guess paths |
+| "I'll call lspGotoDefinition directly..." | `localSearchCode` first for lineHint |
+| "I'll read the file to understand..." | LSP tools first; read content LAST |
+| "I'll just use grep / gh api / npm search..." | Use Octocode tools if available |
+| "I'll use local tools for external repo..." | Use `github*` tools for external repos |
+
+---
+
+## 13. Verification Checklist
+
+Before outputting:
+
+- [ ] Used `localSearchCode` before any LSP tool (for `lineHint`)
+- [ ] Read content LAST (`localGetFileContent` / `githubGetFileContent`)
+- [ ] Used `matchString` or `charLength` for reading (no full dumps)
+- [ ] Found repos via search, not guessed (`packageSearch` / `githubSearchRepositories`)
+- [ ] Explored structure before reading (`githubViewRepoStructure`)
+- [ ] GitHub references include full URLs with line numbers
+- [ ] Answer addresses user's goal directly
+- [ ] Followed hints and Transition Matrix for tool chaining
+- [ ] Included `mainResearchGoal`, `researchGoal`, `reasoning` consistently
+
+> **Tier 2/3 checklist**: [references/fallbacks.md](references/fallbacks.md)
+
+---
+
+## References
+
+- **Tool Parameters**: [references/tool-reference.md](references/tool-reference.md)
+- **Workflow Recipes**: [references/workflow-patterns.md](references/workflow-patterns.md)
+- **Fallback Tiers**: [references/fallbacks.md](references/fallbacks.md)

package/skills/octocode-researcher/references/fallbacks.md

@@ -0,0 +1,120 @@
+# Fallback Tiers — When Octocode MCP Is Not Available
+
+Use this reference when Octocode MCP tools are not detected. See [SKILL.md §2](../SKILL.md) for detection logic.
+
+---
+
+## Tier 2: `gh` CLI + Linux Commands
+
+**Detection**: Run `gh --version` and `gh auth status`.
+
+### External (GitHub via `gh` CLI)
+
+| Octocode Tool | `gh` CLI Equivalent |
+|---------------|---------------------|
+| `githubSearchCode` | `gh search code "PATTERN" --repo OWNER/REPO --language LANG` |
+| `githubSearchRepositories` | `gh search repos "QUERY" --language LANG --sort stars` |
+| `githubViewRepoStructure` | `gh api repos/OWNER/REPO/git/trees/BRANCH?recursive=1 --jq '.tree[].path'` |
+| `githubGetFileContent` | `gh api repos/OWNER/REPO/contents/PATH --jq '.content' \| base64 -d` |
+| `githubSearchPullRequests` | `gh search prs "QUERY" --repo OWNER/REPO --state merged` |
+| `packageSearch` | `npm search KEYWORD --json` (npm) or `pip index versions PACKAGE` (PyPI) |
+| `githubCloneRepo` | `git clone --depth 1 https://github.com/OWNER/REPO.git /tmp/research-REPO` |
+| `githubCloneRepo` (sparse) | `git clone --depth 1 --filter=blob:none --sparse URL /tmp/research-REPO && cd /tmp/research-REPO && git sparse-checkout set TARGET_DIR` |
+
+**`gh` CLI tips**:
+- `gh search code` qualifiers: `--filename`, `--extension`, `--language`, `--repo`
+- `gh api` returns JSON — use `--jq` for filtering (e.g., `--jq '.[].name'`)
+- `gh pr view NUMBER --repo OWNER/REPO` for details, `--json files` for changed files
+- `gh pr diff NUMBER --repo OWNER/REPO` to see diffs directly
+- Pagination: `--limit N` for search, `--paginate` for api
+
+### Local (Linux commands / agent tools)
+
+| Octocode Tool | Linux / Agent Equivalent |
+|---------------|--------------------------|
+| `localViewStructure` | `ls -la PATH` or `tree -L DEPTH PATH` or agent `Glob` |
+| `localSearchCode` | `rg "PATTERN" PATH --type TYPE -n` or agent `Grep` |
+| `localFindFiles` | `find PATH -name "PATTERN" -mtime -DAYS -size +SIZE` or agent `Glob` |
+| `localGetFileContent` | `head -n N PATH` / `sed -n 'START,ENDp' PATH` or agent `Read` |
+
+**Linux tips**:
+- `rg` (ripgrep) preferred — faster, respects `.gitignore`, better regex
+- `rg -l "PATTERN" PATH` = files only (like `filesOnly: true`)
+- `rg -c "PATTERN" PATH` = match counts per file
+- `find PATH -name "*.ts" -newer FILE` = files modified after reference
+- `tree -I 'node_modules|dist' -L 2` = structure excluding dirs
+
+### Clone (Tier 2)
+
+```bash
+# Full shallow clone
+git clone --depth 1 https://github.com/OWNER/REPO.git /tmp/research-REPO
+
+# Sparse shallow clone (monorepo)
+git clone --depth 1 --filter=blob:none --sparse https://github.com/OWNER/REPO.git /tmp/research-REPO
+cd /tmp/research-REPO && git sparse-checkout set src/target-dir
+```
+
+Then use `rg`, `Grep`, `Read` on the cloned path. Clean up `/tmp/` clones after research.
+
+### Compensating for Missing Octocode Features
+
+| Missing | Compensation |
+|---------|-------------|
+| Hints | Manually plan next steps using the Transition Matrix in SKILL.md §5 |
+| Pagination | Use `--limit`, `head`, `tail` to manage output size |
+| LSP (defs, refs, calls) | `rg` pattern matching to trace manually — **no true equivalent** |
+| Research context | Track goals in task management tools |
+| Structured results | Parse raw output manually |
+
+> **LSP semantic analysis has no Linux equivalent.** Only Octocode MCP or IDE-native tools provide go-to-definition, find-references, and call-hierarchy.
+
+---
+
+## Tier 3: Agent Default Tools Only
+
+If neither Octocode MCP nor `gh` CLI is available:
+
+| Need | Agent Tool |
+|------|------------|
+| Search code content | `Grep` (ripgrep-based) |
+| Find files by pattern | `Glob` |
+| Read file content | `Read` |
+| Fetch web content | `WebFetch` |
+| Run commands | `Shell` (`npm search`, `git log`, etc.) |
+
+---
+
+## Tier 2/3 Verification Checklist
+
+**Local research**:
+- [ ] Used `rg` / `Grep` for search before reading files
+- [ ] Used `Read` / `sed -n` LAST (after search)
+- [ ] Managed output size with `head`, `tail`, `--limit`
+
+**External research**:
+- [ ] Used `gh search repos` or `npm search` to find repos (not guessed)
+- [ ] Used `gh api .../trees` to explore structure before reading
+- [ ] Used `gh api .../contents` LAST (after exploration)
+- [ ] References include full GitHub URLs with line numbers
+
+---
+
+## Why Octocode Over Alternatives
+
+| Instead of... | Octocode | Why Better |
+|---------------|----------|------------|
+| `grep`, `rg` | `localSearchCode` | Structured results, pagination, hints, byte offsets |
+| `ls`, `tree` | `localViewStructure` | Filtering, sorting, depth control, summaries |
+| `find` | `localFindFiles` | Time/size/permission filters, pagination |
+| `cat`, `head` | `localGetFileContent` | matchString targeting, context lines, pagination |
+| `gh api` | `githubSearchCode` | Structured results, hints, pagination |
+| `npm search` | `packageSearch` | Multi-registry (npm/PyPI), structured metadata |
+| `WebFetch` (GitHub) | `githubViewRepoStructure` | Tree view, no HTML parsing |
+
+**Exclusive Octocode benefits** (unavailable in Tier 2/3):
+- Structured JSON with hints for next steps
+- Automatic pagination for token management
+- `.gitignore` respect with `noIgnore` option
+- Research params (`mainResearchGoal`, `researchGoal`, `reasoning`)
+- LSP semantic analysis (go-to-definition, find-references, call-hierarchy)