Octocode

Github | Search code contents or file paths across GitHub repositories. | Use for remote code/file discovery. Start match:"path" + concise for filenames; match:"file" only when snippets matter. Skip if you already have the path (ghGetFileContent) or need repo discovery (ghSearchRepos). One-shot: if a match:"file" snippet already contains the answer (a field value, a symbol name, a state), STOP — that snippet is the evidence; don't chain a structure view or a content read to "confirm" it. Param relations: owner+repo scopes tightly; path scopes a directory prefix; extension/language/filename narrow candidates; keywords are ANDed. Follow into ghGetFileContent, ghViewRepoStructure, or clone for AST/LSP proof. Empty/unindexed is not absence.

Github | Read a file or a specific region from a GitHub repository. | Use after ghSearchCode/ghViewRepoStructure when you know the repo path — not for discovery. If a ghSearchCode snippet already answers the question, STOP — don't re-read the file. Least-cost path: unknown/large file → minify:"symbols" outline, then a region (matchString or startLine+endLine). fullContent only for genuinely small whole-file reads, never to scan. A small structured/config file (package.json, tsconfig, lockfile) → read it whole with minify:"none"/fullContent, don't minify it — compaction can elide object boundaries and break exact key/value membership. For a literal value or quote, read the defining region with minify:"none" and copy the exact bytes. Every response reports the file's full size (totalLines + sourceChars) and isPartial. A matchString/region read is a SLICE, not the whole file — it can cut a nested object mid-way; never conclude a key/field/value is absent or empty from a partial slice: continue via charOffset/next, or re-read the whole small structured file (package.json/tsconfig/lockfile) with minify:"none". Report only bytes you fetched — never invent a field, value, or quote. Param relations: choose one extraction mode: fullContent OR matchString OR startLine+endLine. matchString pairs with contextLines and returns matchRanges (padded windows, not the exact hit) plus matchedLines (exact hit lines — see matchString field); charOffset continues isPartial pages. type:"directory" materializes localPath for local tools when clone is enabled.

Github | Browse a GitHub repository's directory tree. | Orient a repo/tree before fetching files, or verify paths/branches after 404s. Know a filename fragment? ghSearchCode(match:"path") is cheaper. Follow structure[] paths into ghGetFileContent or a clone sparsePath.

Github | Discover GitHub repositories by name, topic, language, or popularity. | Find candidate repos before code search; skip when owner/repo is known (go straight to ghSearchCode/ghViewRepoStructure). Start concise:true, then inspect with ghViewRepoStructure/ghSearchCode. keywords ANDed; topics also required but sparse; owner scopes/enumerates; match picks searched text fields; sort/range rank candidates. Empty → drop filters/topics or broaden language/owner.

Github | Search GitHub pull requests, or read one PR's files, diffs, and reviews. | Use for PR archaeology — how/why a change landed, review discussion, diffs — not current code (ghSearchCode/ghGetFileContent), commits (ghSearchCommits), or issues (ghSearchIssues). Comments, review replies, and requested changes are claims — confirm what actually landed against content.patches (mode:"selected") or the file at the merge SHA, not the conversation. Param relations: list mode uses keywordsToSearch+filters+sort/page; detail mode needs owner+repo+prNumber and content selectors. content.patches.mode:"selected" requires files or ranges. Body/patch/comment windows continue via returned charOffset/commentBodyOffset; file/comment/commit lists use their page fields. For code identity, clone and use local/LSP.

Github | Search GitHub issues, or read one issue's body and comments. | Issue triage/archaeology — bug reports, feature threads — not PRs (ghSearchPullRequests) or code (ghSearchCode). List mode: keywordsToSearch+filters+sort/page. Detail mode: owner+repo+issueNumber + content selectors; body/comment windows continue via charOffset/commentBodyOffset, comments page via commentPage. totalCount appears only when one page is the full set (the endpoint also returns PRs, filtered out — so per-page counts aren't totals); an empty page with hasMore:true was PR-only — follow nextPage.

Github | Walk a GitHub repository's commit history for a path or range. | Commit archaeology — when/why a file/area changed — not current code (ghSearchCode/ghGetFileContent) or PRs (ghSearchPullRequests). No message-keyword filter — only path/since/until/author/committer narrow the walk. Looking for a specific change (e.g. a rename) with no known SHA/path/date? Try ghSearchPullRequests/ghSearchCode for a lead first; otherwise page raw history by eye. One commit's exact changes: set base:"SHA^", head:"SHA", includeDiff:true — its files+patches in one call; don't page history or fetch files. owner+repo identify the repo; path scopes a file/dir (trailing / = subtree); since/until bound the window; branch selects a ref; includeDiff is heavy — scope to one SHA or a tight window; itemsPerPage/page walk history. For code identity, clone + local/LSP.

NPM | Look up npm packages and find their source repositories. | Resolve a package to its source repository; skip if owner/repo is known. Exact name → one rich result; keywords → paged candidates. Follow repository into GitHub tools.

Local | Search local files for text, regex, or AST patterns to find file and line. | Find local file+line anchors — not path/name lookup (localFindFiles) or tree shape (localViewStructure). Modes: discovery=paths, paginated=snippets, detailed=context, structural=AST. text/regex need searchText (one string, not array); structural needs pattern XOR rule and rejects search knobs (langType is valid — scopes to that language's extensions). $$$ list captures are budgeted: metavarRanges gives pruned/truncated line anchors, captureText:true for verbatim. matchWindow/unique need output:"matchOnly"; maxMatchesPerFile pairs matchPage. Follow with localGetFileContent, lspGetSemantics.

Local | Browse a local directory tree — cheapest first orientation step; no content loaded. | Cheapest local orientation before reading. Metadata/name filters → localFindFiles; files containing text → localSearchCode(mode:"discovery"). path is the root; pattern/extensions/entryType filter names; recursive enables maxDepth; detail switches output shape; page advances only on hasMore. Follow paths into localGetFileContent/search/LSP.

Local | Find local files and directories by name, size, time, or permissions. | Local path discovery by name/type/metadata — not contents (localSearchCode) or tree shape (localViewStructure). All filters AND. Prunes common generated/vendor dirs by default (node_modules, .git, dist, build, out, coverage, target, .next, .cache) — excludeDir:[] prunes nothing, or set excludeDir explicitly. Follow paths into read/search/LSP.

Local | Find likely-unreferenced exports and dead-code clusters via whole-repo reachability analysis. | Repo-wide dead-export candidates — not single-symbol checks (use lspGetSemantics references/callers). One pass builds a file/symbol graph (native AST, no per-symbol round-trips) and walks reachability from entrypoints, so it scales with repo size, not candidate count. Catches mutually-referencing dead clusters (files that only call each other, unreachable from any entrypoint) that a one-symbol check misses. Retention is symbol-level: a same-file call retains its callee only if the caller is live; named re-exports are followed through export* barrels to the entrypoint. Each candidate carries viaHeuristic: "reexport-chain" (chain ended with no consumer — most fragile, verify first) or "lexical-count" (no import, no unexplained same-file use). Candidates, not proof — run next.verifyReferences (a prefilled lspGetSemantics references query) per candidate; zero references = confirmed dead. Follow file/line anchors into localGetFileContent or lspGetSemantics.

Local | Read a local file or a specific region. | Use after localSearchCode/localViewStructure/localFindFiles when you have a path — not for discovery. Unknown/large file: minify:"symbols" first, then exact range or matchString. A small structured/config file (package.json, tsconfig, lockfile) → read it whole with minify:"none"/fullContent, don't minify it — compaction can elide object boundaries and break exact key/value membership. For a literal value or quote, read the defining region with minify:"none" and copy the exact bytes. Every response reports the file's full size (totalLines + sourceChars) and isPartial. A matchString/region read is a SLICE, not the whole file — it can cut a nested object mid-way; never conclude a key/field/value is absent or empty from a partial slice: continue via charOffset/next, or re-read the whole small structured file with minify:"none". Report only bytes you fetched — never invent a field, value, or quote. Param relations: choose one extraction mode: fullContent OR matchString OR startLine+endLine. matchString pairs with contextLines and returns matchRanges ({start,end} line windows padded by contextLines, NOT the exact hit) plus matchedLines (the exact matched line numbers); charOffset continues isPartial pages. Follow matchedLines/matchRanges into LSP.

Local | Run LSP semantic queries — definitions, references, call hierarchy, symbols, type hierarchy, diagnostics. | Use after search/read gives a real file+line anchor. documentSymbols/diagnostic need uri only; workspaceSymbol needs symbolName; others need uri+symbolName+lineHint. lineHint must come from a prior anchor, never guessed; orderHint disambiguates same-line symbols; references take groupByFile/includeDeclaration; callers/callees/callHierarchy take depth/contextLines; format:"compact" saves tokens. Empty/serverUnavailable → re-anchor or fall back to search.