@octocodeai/octocode-tools-core 18.1.2 → 18.3.0

package/README.md

@@ -1,4 +1,4 @@
-# Octocode - Agentic Research Platform
+# Octocode: agentic research platform
 
 <div align="center">
   <img src="https://github.com/bgauryy/octocode/raw/main/packages/octocode-mcp/assets/logo_white.png" width="400px" alt="Octocode Logo">
@@ -14,31 +14,31 @@
 
 **Evidence-first code research for AI agents and developers.**
 
-Octocode researches **your local code and external code alike** (GitHub repos, PRs, npm) with one toolset: ripgrep + AST search, trees, precise reads, and LSP. Use it as a **CLI** or **MCP server**, backed by a **Rust engine** for fast, token-efficient results across single files or mega-repos.
+Octocode researches **your local code and external code alike** (GitHub repositories, PRs, npm) with one toolset: ripgrep + AST search, trees, precise reads, and LSP. Use it as a **CLI** or **MCP server**, backed by a **Rust engine** for fast, token-efficient results across single files or mega-repos.
 
 ---
 
-## Table of Contents
+## Table of contents
 
-- [Quick Start](#quick-start)
+- [Quick start](#quick-start)
 - [Why Octocode](#why-octocode)
-- [Built for Research (Benchmarks)](#built-for-research-benchmarks)
+- [Built for research (benchmarks)](#built-for-research-benchmarks)
 - [Tools](#tools)
 - [MCP](#mcp)
 - [CLI](#cli)
 - [Configuration](#configuration)
-- [Authentication Methods](#authentication-methods)
+- [Authentication methods](#authentication-methods)
 - [Security](#security)
-- [Language Support](#language-support)
+- [Language support](#language-support)
 - [Skills](#skills)
 - [Architecture](#architecture)
 - [Documentation](#documentation)
 - [Troubleshooting](#troubleshooting)
-- [Agent Workflows](#agent-workflows)
+- [Agent workflows](#agent-workflows)
 
 ---
 
-## Quick Start
+## Quick start
 
 **Prerequisites:** Node.js 20.12+
 
@@ -108,23 +108,23 @@ Put a GitHub token and options under `env` (see [Configuration](#configuration))
 
 ### Use it as an agentic-friendly CLI
 
-Just run `npx octocode`, agents figure out the rest. The bare command prints built-in usage and the full tool catalog, so any coding agent knows how to drive it out of the box, no MCP client or extra wiring required.
+Run `npx octocode` and agents figure out the rest. The bare command prints built-in usage and the full tool catalog, so any coding agent knows how to drive it out of the box, no MCP client or extra wiring required.
 
 ```bash
 npx octocode                                         # self-describing usage for agents
 npx octocode tools                                   # list every tool
-npx octocode tools localSearchCode --scheme          # inspect a tool's schema
+npx octocode tools localSearch --scheme              # inspect all local discovery modes
 ```
 
 Every MCP tool is also a plain command: JSON in, token-efficient YAML out. Local paths route to local tools; `owner/repo[/path]` routes to GitHub.
 
 ```bash
-npx octocode tools localSearchCode \
-  --queries '{"path":".","searchText":"authenticate","maxFiles":20}'
+npx octocode tools localSearch \
+  --queries '{"operation":"text","path":"/absolute/path/to/project","searchText":"authenticate","maxFiles":20}'
 ```
 ```yaml
 results:
-  - id: localSearchCode-1
+  - index: 0
     data:
       files:
         - path: src/auth.ts
@@ -141,12 +141,12 @@ Learn more at **[octocode.ai](https://octocode.ai)**.
 
 Agents code better from evidence than from guesses. Octocode researches **two worlds with one flow**, your **local code** and **external code** on GitHub and npm, and hands back compact, citable context before an agent changes, reviews, or explains code. *Code is truth; context is the map.*
 
-Most tools do one slice (web search, or grep your repo) and hand back a fixed blob. Octocode covers the whole loop and lets the **agent decide what data it needs next**:
+Most tools do one slice (web search, or grep your repository) and hand back a fixed blob. Octocode covers the whole loop and lets the **agent decide what data it needs next**:
 
 - **Agent-driven, efficient flows.** Instead of one-shot dumps, Octocode chains cheap steps into an optimized research flow: broad code search, then fetch only the **exact matched lines/region**, with **smart pagination** and **out-of-the-box minification** so the model never over-fetches. Every result carries **next-step hints** to the cheapest follow-up.
-- **Scales to monorepos.** Spot a pattern in one repo, follow the PR that introduced it, then trace it across other repos and your own files, without leaving the chat. Clone any repo and study it locally.
-- **Smart GitHub flow.** Parallel bulk queries across code, PRs, commits, issues, and repos, all with the same search-broad, read-narrow, trace-semantically discipline.
-- **Works without GitHub.** Clone any repo and point the local tools (search, AST, LSP, content) at it, same evidence-first flow.
+- **Scales to monorepos.** Spot a pattern in one repository, follow the PR that introduced it, then trace it across other repositories and your own files, without leaving the chat. Clone any repository and study it locally.
+- **Smart GitHub flow.** Parallel bulk queries across code, PRs, commits, issues, and repositories, all with the same search-broad, read-narrow, trace-semantically discipline.
+- **Works without GitHub.** Clone any repository and point the local tools (search, AST, LSP, content) at it, same evidence-first flow.
 - **Reads shape, not noise.** On-the-fly minify/skeletonize across 70+ languages: a 100 KB file in a few hundred tokens, not walls of boilerplate.
 - **Fast, self-contained.** Search, parsing, navigation, and redaction run in one prebuilt **Rust engine**: quick on a laptop or a mega-repo, nothing extra to install.
 - **Safe by default.** Every byte to the model is scanned and secrets redacted first (see [Security](#security)).
@@ -160,117 +160,66 @@ Most tools do one slice (web search, or grep your repo) and hand back a fixed bl
 | **Semantic navigation** | Resolve definitions, references, callers/callees, call hierarchy, hovers, symbols, diagnostics, and type relationships through LSP. |
 | **Structural matching** | Run AST-shaped searches with patterns or YAML rules so comments and strings do not become false positives. |
 | **Large-file context** | Minify, skeletonize, or paginate code so agents spend tokens on relevant structure instead of boilerplate. |
-| **Agent workflows** | Same engine via MCP, CLI, and Agent Skills. |
+| **Agent workflows** | Same engine through MCP, CLI, and Agent Skills. |
 
 ---
 
-## Built for Research (Benchmarks)
+## Built for research (benchmarks)
 
-Octocode is a **research layer for coding agents**: it finds and proves the context an agent
-needs *before* it writes, reviews, or explains code, via **CLI or MCP**. It shines at **deep
-research across many repositories**: connecting the dots from a symbol to its source, the PR
-that changed it, and the same pattern in other repos. The benchmark measures the two things a
-developer actually pays for:
+A blind, head-to-head test on **research-oriented flows rather than plain lookups** (multi-hop traces,
+dependency/call-graph chains, commit ranges, blast-radius, PR reviews across repositories).
 
-- **Accuracy**: did the agent get the answer right?
-- **Context cost**: how many characters the model had to read to get there. Fewer characters =
-  **lower token spend, faster turns, and sharper focus** (the model isn't buried in boilerplate).
+[![Octocode benchmark — same answers, a fraction of the context](assets/benchmark.png)](https://raw.githack.com/bgauryy/octocode/main/packages/octocode-benchmark/results/index.html)
 
-We ran **30 real cross-repo questions** (dependency traces, call graphs, commit ranges, blast
-radius, PR reviews), 3 passes each, against three GitHub setups a developer might use today:
-plain `gh`, `gh` + Headroom (compression), and `gh` + RTK. A blind, neutral judge (gpt-5.5)
-graded every answer.
+**How it works:** 30 GitHub questions × 3 passes; Octocode vs `gh`, `gh`+Headroom, and `gh`+RTK on
+identical questions (only the CLI differs). A blind judge (gpt-5.5) grades correctness; the metric is
+**characters through the model**, counted from instrumented logs (characters, not tokens). **Result:** at
+near-parity correctness, Octocode answers with **~2.0× fewer characters than plain `gh`, ~2.6× fewer
+than `gh`+Headroom, and ~3.2× fewer than `gh`+RTK** in the local-build headline runs.
 
-### Scorecard (30 Q × 3 passes per matchup, local build v18.1.1, blind neutral gpt-5.5 judge, 95% bootstrap CIs)
-
-**Typical context per question**: how many characters the model reads to answer, relative to
-Octocode (lower is better):
-
-```text
-Octocode      ███          1.0× (baseline)
-plain gh      ██████       2.0× more context
-gh + Headroom ████████     2.6× more context
-gh + RTK      ██████████   3.2× more context
-```
-
-| Dimension | Octocode | plain gh | gh + Headroom | gh + RTK |
-|---|---:|---:|---:|---:|
-| Correctness (/10) | ~9.2–9.3 | 9.3 | 8.6 | **9.4** |
-| Chars, per-Q geo-mean (baseline÷Octo, 95% CI) | 1.0× | **2.0×** (1.5–2.6) | **2.6×** (1.9–3.7) | **3.2×** (2.4–4.5) |
-| Correct-and-leaner wins (Octo / baseline) | n/a | 51 / 38 | 60 / 28 | 57 / 33 |
-| Questions Octocode leaner | n/a | 67/89 | 63/88 | 68/90 |
-
-**What this means for you:** at the **same accuracy** (all arms tie at ~9/10), Octocode answers
-in **2–3× fewer characters** than every baseline, every 95% CI stays above 1×, and it is
-leaner on ~72–75% of questions. That is directly less token spend and context bloat on each
-research step. Even versus bare, disciplined `gh` (the leanest baseline) it is ~2× leaner, and
-the lead grows on the hard multi-hop, large-file questions where agents usually derail.
-
-**Why it's leaner without losing anything:**
-- **Exact slices, not dumps**: reads the region, symbol, or diff you asked for, never a whole file or tree.
-- **Lossless minification**: strips boilerplate across 70+ languages with zero data loss: a 100 KB file becomes a few hundred tokens of real structure.
-- **No silent truncation**: you get the full slice; large results continue on demand via exact cursors.
-- **One research loop**: GitHub + local + LSP + npm behind a single flow: structure → search → exact read → prove.
-
-Full reports:
-[vs plain gh](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/results/full-octocode-vs-gh-152630-2026-08-07.md) ·
-[vs gh+Headroom](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/results/full-octocode-vs-headroom-134213-2026-08-07.md) ·
-[vs gh+RTK](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/results/full-octocode-vs-rtk-162848-2026-08-07.md).
-
-### When to reach for Octocode vs a quick check
-
-| Reach for **Octocode** when… | A **quick check** is enough when… |
-|---|---|
-| You need **exact field membership** (peer vs optional vs dev, version ranges). | You already know the file+line and just want to eyeball it. |
-| The answer is a **trace across files/repos** (dependency → source → transport → parser chain). | You need one PR title, issue state, or a single `--json` field. |
-| You want to **stay lean in context**: targeted reads, not whole-file/tree dumps. | The file is tiny and a full fetch is trivially cheap. |
-| You need **reachability / call-graph proof** before a change. | A single grep hit already answers it. |
-
-**Dig deeper:** [run](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/skills/octocode-benchmark) ·
-[design](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/skills/octocode-benchmark/references/BENCHMARK.md) ·
-[questions](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/compare/github-questions) ·
-[stats method](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/skills/octocode-benchmark/references/aggregation-and-stats.md) ·
-[all reports](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/results) (historical runs carry their own caveats).
+▶ **[Open the interactive report](https://raw.githack.com/bgauryy/octocode/main/packages/octocode-benchmark/results/index.html)** · **[run it / method](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/skills/octocode-benchmark)** · [questions](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/compare/github-questions) · [all reports](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/results)
 
 ---
 
 ## Tools
 
-**17 tools in the full catalog.** MCP registers 14 by default; the CLI exposes 15
-because clone is enabled there by default. `ghCloneRepo` is opt-in on MCP
-(`ENABLE_CLONE=true`), while `ghListReleases` and `ghSearchDiscussions` are opt-in
-on both surfaces. Local tools default on for the **CLI** and off for the **MCP
-server** (`ENABLE_LOCAL=true` enables them on MCP; `ENABLE_LOCAL=false` disables on
-CLI). Flags: [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md).
+**10 tools in the full discovery catalog.** Repository cloning is enabled by
+default on both CLI and MCP:
+
+| Surface | Registers | What that set is |
+|---|---:|---|
+| MCP, no flags | 10 | Default GitHub, clone, package, local, graph, and LSP tools |
+| CLI, no flags | 10 | Local tools and clone are on |
+
+Use `TOOLS_TO_RUN` for a strict allowlist or `DISABLE_TOOLS` to remove tools from
+the default set. `ENABLE_LOCAL=false` disables local, graph, and LSP tools;
+`ENABLE_CLONE=false` disables cloning on both surfaces.
+Flags: [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md).
 
 **Token knobs.** `concise:true` returns path/title-only lists. `minify` controls file read density: `symbols` = skeleton with line numbers, `standard` = comments/blanks stripped (default), `none` = exact bytes.
 
-### GitHub Tools
+### GitHub tools
 
 | Tool | What it does | Knob |
 |------|--------------|------|
-| `ghSearchCode` | Code and path search across GitHub by owner, repo, path, filename, extension, and match filters. Accepts 1 to 5 parallel queries. | `concise` |
+| `ghSearch` | Discover GitHub code, repositories, or repository trees through strict `operation:"code"`, `"repositories"`, or `"tree"` queries. Accepts 1 to 5 parallel queries. | `operation` |
 | `ghGetFileContent` | Read a GitHub file or region: full file, line range, match slice, or paginated chars. | `minify` |
-| `ghViewRepoStructure` | Browse a repository's directory tree, plus opt-in repo enrichments. | `include` |
-| `ghSearchRepos` | Discover repositories by keywords, owner, topic, language, stars, updated, license, visibility. | `concise` |
-| `ghSearchPullRequests` | Search pull requests, or deep-read one PR: files, patches, comments, reviews, commits. | `content` |
-| `ghSearchIssues` | Search issues, or read one issue's body and comments. | `content` |
-| `ghSearchCommits` | Walk a repo's commit history, or compare two refs (`base`+`head`). | `includeDiff` |
-| `ghListReleases` | List releases + latest, with opt-in assets. **Opt-in** (`ENABLE_RELEASES=true`). | `includeAssets` |
-| `ghSearchDiscussions` | Search a repo's Discussions (Q&A, RFCs, announcements) via GraphQL. **Opt-in** (`ENABLE_DISCUSSIONS=true`). | `keywordsToSearch` |
-| `ghCloneRepo` | Clone a repo or sparse subtree into the local cache for local/LSP analysis. **Opt-in** on MCP (`ENABLE_CLONE=true`; CLI on by default). | `sparsePath` |
+| `ghSearchHistory` | Search or list pull requests, issues, or commits through strict `operation:"pullRequests"`, `"issues"`, or `"commits"` queries. | `operation` |
+| `ghGetHistoryItem` | Read one pull request or issue by `number`, one commit by `ref`, or a comparison by `base`+`head`. | `operation` |
+| `ghCloneRepo` | Clone a repository or sparse subtree into the local cache for local and LSP analysis. Enabled by default on CLI and MCP; `ENABLE_CLONE=false` disables it. | `sparsePath` |
 
-### Local Tools
+`ghSearch` is the only GitHub discovery interface; select code, repositories,
+or trees with its strict `operation` field.
+
+### Local tools
 
 | Tool | What it does | Knob |
 |------|--------------|------|
-| `localSearchCode` | Local code/text search returning file and line anchors. `mode:"structural"` runs Octocode AST shape queries (`pattern` or `rule`). | `mode` |
-| `localViewStructure` | Browse a local directory tree: depth, filters, pagination, metadata. | `detail` |
-| `localFindFiles` | Find local files and directories by name, path, regex, extension, size, time, permissions, type. | |
-| `localFindDeadCode` | Find likely-unreferenced exports and dead-code clusters using whole-repository reachability analysis. | `entrypoints` |
+| `localSearch` | Discover local code and paths through one discriminated surface: `operation:"text"`, `"structural"`, `"files"`, or `"tree"`. | `operation` |
+| `localAnalyzeGraph` | Analyze bounded file dependencies, paths, reachability, SCCs, and dead-code candidates. Cycle results separate runtime loading cycles from type-only SCCs and include directed edge witnesses. | `operation` |
 | `localGetFileContent` | Read a local file or region: exact slice, match string, line range, or paginated chars. | `minify` |
 
-### Package Search
+### Package search
 
 | Tool | What it does | Knob |
 |------|--------------|------|
@@ -280,7 +229,7 @@ CLI). Flags: [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/
 
 | Tool | What it does |
 |------|--------------|
-| `lspGetSemantics` | Typed semantic navigation: `definition`, `references`, `callers`, `callees`, `callHierarchy`, `hover`, `documentSymbols`, `typeDefinition`, `implementation`, `workspaceSymbol`, `supertypes`, `subtypes`, and `diagnostic`. From the CLI, invoke it directly: `npx octocode tools lspGetSemantics --queries '<json>'`. Navigation runs through installed language servers (see the [LSP Tools Reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md#lsp-tools-reference)). |
+| `lspGetSemantics` | Typed semantic navigation: `definition`, `references`, `callers`, `callees`, `callHierarchy`, `hover`, `documentSymbols`, `typeDefinition`, `implementation`, `workspaceSymbol`, `supertypes`, `subtypes`, and `diagnostic`. From the CLI, invoke it directly: `npx octocode tools lspGetSemantics --queries '<json>'`. Navigation runs through installed language servers (see the [LSP tools reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md#lsp-tools-reference)). |
 
 Full schemas, fields, and examples for every tool live in [`docs/OCTOCODE_TOOLS.md`](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md) (linked under [Documentation](#documentation)).
 
@@ -292,7 +241,7 @@ The MCP server exposes the Octocode tool catalog directly to your AI assistant o
 
 https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071
 
-### Manual Configuration
+### Manual configuration
 
 Add to your MCP client config, using `octocode-mcp`:
 
@@ -318,7 +267,7 @@ Same research engine, no MCP client needed. Local paths route to local tools; `o
 
 ### Commands
 
-#### Tools
+#### Tool commands
 
 | Command | What it does |
 |---------|--------------|
@@ -329,12 +278,12 @@ Same research engine, no MCP client needed. Local paths route to local tools; `o
 
 #### More commands
 
-- **Cache & clone** - `npx octocode clone`, `npx octocode cache fetch|status|clear`
-- **Skills** - `npx octocode skill list|install|check|info|remove` for bundled Octocode skills
-- **Language servers** - `npx octocode lsp-server list|install|status|uninstall|clean`
-- **Setup & introspection** - `npx octocode install`, `npx octocode auth`, `npx octocode status`, `npx octocode context`
+- **Cache and materialize** — `npx octocode cache fetch|status|clear`; use `npx octocode tools ghCloneRepo --scheme` for the clone tool
+- **Skills** — `npx octocode skill list|install|check|info|remove` for bundled Octocode skills
+- **Language servers** — `npx octocode lsp-server list|install|status|uninstall|clean`
+- **Setup and introspection** — `npx octocode install`, `npx octocode auth`, `npx octocode status`, `npx octocode context`
 
-Full syntax, flags, and exit codes: [Octocode CLI Guide](https://github.com/bgauryy/octocode/blob/main/packages/octocode/docs/OCTOCODE_CLI.md)
+Full syntax, flags, and exit codes: [Octocode CLI guide](https://github.com/bgauryy/octocode/blob/main/packages/octocode/docs/OCTOCODE_CLI.md)
 
 ---
 
@@ -350,15 +299,13 @@ environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults
 2. **Global config**: `<octocode-home>/.octocoderc`, machine-wide defaults read by **both the CLI and the MCP server**.
 3. **Built-in defaults**: used when neither is set.
 
-**Octocode home** (`<octocode-home>`) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. It defaults by platform and can be overridden with `OCTOCODE_HOME`:
+**Octocode home** (`<octocode-home>`) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. On every platform it is `.octocode` inside the OS home directory — `~/.octocode` on macOS and Linux, `%USERPROFILE%\.octocode` on Windows. Override it with `OCTOCODE_HOME`.
+
+Remote data is shared by the CLI and MCP under `<octocode-home>/tmp/`: git clones in `clone/`, commit-addressed file trees in `tree/`, and reusable API/package responses in `response/`. A persisted 24-hour maintenance gate bounds automatic cleanup across short-lived CLI processes and long-lived MCP sessions. See the [configuration reference](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#cache-storage-and-lifecycle) for lifecycle and limit details.
 
-| Platform | Location |
-|----------|----------|
-| macOS | `~/.octocode` |
-| Linux | `${XDG_CONFIG_HOME:-~/.config}/.octocode` |
-| Windows | `%APPDATA%\.octocode` |
+For memory-only operation, set `storage.mode` to `"memory"` in `.octocoderc` or set `OCTOCODE_STORAGE_MODE=memory`. This prevents persistent runtime cache, materialization, session, stats, and Pi SQLite writes without deleting existing files or credentials.
 
-Set values as MCP `env` entries (per client; these win over `.octocoderc`) or globally in `<octocode-home>/.octocoderc` (JSON with comments). **Tokens never go in `.octocoderc`** - use `env` or `npx octocode auth login`.
+Set values as MCP `env` entries (per client; these win over `.octocoderc`) or globally in `<octocode-home>/.octocoderc` (JSON with comments). **Tokens never go in `.octocoderc`** — use `env` or `npx octocode auth login`.
 
 ### Common settings
 
@@ -367,15 +314,16 @@ Most-used settings (both CLI and MCP unless noted):
 | Env var | `.octocoderc` key | Default | What it does |
 |---------|-------------------|---------|--------------|
 | `OCTOCODE_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | env only | unset | GitHub token, in priority order. Never in `.octocoderc`. |
-| `ENABLE_LOCAL` | `local.enabled` | CLI `true`, MCP `false` | Local filesystem + LSP tools on/off. |
-| `ENABLE_CLONE` | `local.enableClone` | CLI `true`, MCP `false` | `ghCloneRepo` + directory fetch on/off. |
+| `ENABLE_LOCAL` | `local.enabled` | `true` | Local filesystem and LSP tools on or off. Set `false` to disable them. |
+| `ENABLE_CLONE` | `local.enableClone` | `true` | `ghCloneRepo` + directory fetch on/off. Set `false` to disable them. |
 | `WORKSPACE_ROOT` | `local.workspaceRoot` | `cwd` | Root for resolving relative local paths. |
 | `ALLOWED_PATHS` | `local.allowedPaths` | `[]` | Extra path allowlist for local access. |
 | `OCTOCODE_OUTPUT_FORMAT` | `output.format` | `yaml` | Response format: `yaml` or `json`. |
+| `OCTOCODE_STORAGE_MODE` | `storage.mode` | `persistent` | Set `memory` to prevent persistent runtime state and materialization. |
 
-`OCTOCODE_HOME`, GitHub Enterprise (`GITHUB_API_URL`), MCP tool whitelisting (`TOOLS_TO_RUN`/`ENABLE_TOOLS`/`DISABLE_TOOLS`), and network timeouts/retries: see the [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md).
+`OCTOCODE_HOME`, GitHub Enterprise (`GITHUB_API_URL`), MCP tool filtering (`TOOLS_TO_RUN`/`DISABLE_TOOLS`), and network timeouts/retries: see the [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md).
 
-### Example Configuration
+### Example configuration
 
 **`~/.octocode/.octocoderc`:**
 ```json
@@ -389,6 +337,9 @@ Most-used settings (both CLI and MCP unless noted):
   },
   "output": {
     "format": "yaml"
+  },
+  "storage": {
+    "mode": "persistent"
   }
 }
 ```
@@ -397,11 +348,11 @@ Per-project overrides and custom LSP servers live in a workspace `.octocode/` fo
 
 ---
 
-## Authentication Methods
+## Authentication methods
 
 GitHub-backed tools require authentication. Any one method is enough. Full details: [Authentication Setup](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md).
 
-### Option 1: Octocode CLI (Recommended)
+### Option 1: Octocode CLI (recommended)
 
 ```bash
 npx octocode auth login
@@ -416,44 +367,44 @@ Interactive login lets you choose Octocode browser OAuth or `gh auth login`. Oct
 gh auth login
 ```
 
-Octocode reads the `gh` token automatically - no further config needed.
+Octocode reads the `gh` token automatically — no further config needed.
 
-### Option 3: Personal Access Token (also supported)
+### Option 3: Personal access token (also supported)
 
 Set `OCTOCODE_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` in your shell. Required scopes: `repo`, `read:user`, `read:org`.
 
 Create a token at [github.com/settings/tokens](https://github.com/settings/tokens).
 
-> **Security tip**: Never commit tokens to version control. Use environment variables or secure secret management.
+**Note:** Never commit tokens to version control. Use environment variables or secure secret management.
 
 ---
 
 ## Security
 
-**Every byte to the model is scanned and redacted first.** All content (local files, GitHub/npm responses, errors, tool output) passes through the Rust engine's secret scanner on the way *in* and *out*, so secrets never reach the LLM. Identical under MCP and CLI.
+**Every byte to the model is scanned and redacted first.** All content passes through the Rust engine's secret scanner on the way *in* and *out*, so secrets never reach the model. That covers local files, GitHub and npm responses, errors, and tool output. The behavior is identical under MCP and the CLI.
 
 - **Secret redaction, in and out.** 300+ provider credential patterns (AWS, Azure, GCP, GitHub, OpenAI, Anthropic, Stripe, Slack, 1Password, and more) plus generic JWTs, PEM/private keys, bearer tokens, database connection strings, and high-entropy strings. Masked values surface a redaction warning so the agent knows.
 - **Content sanitized at the source.** Local reads (`localGetFileContent`, ripgrep, structural search, binary, file discovery, structure) and external fetches (GitHub code/files, npm) are scanned as they are read, not only at the boundary.
 - **Path safety.** Relative inputs resolve from `WORKSPACE_ROOT` / config / `cwd`, then local reads are bounded to the engine's allowed roots (home by default, plus `ALLOWED_PATHS` and Octocode-registered roots). Symlinks are resolved and the real target is **re-validated**, so a link cannot escape into a blocked location.
 - **Sensitive files blocked by default.** Reads of known secret-bearing files and folders return a redacted error instead of contents: keys/certs, `.env*`, `.npmrc`/`.netrc`, cloud/infra credentials (`.aws/`, `.kube/`, `*.tfstate`), `.git/`, browser logins, OS keychains, and wallets. Full list in [SECURITY.md](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md).
-- **Command safety.** Normal local search runs in-process inside `octocode-engine`. External helpers are fixed per lane, command/argument allowlisted, and run via `spawn` with argument arrays: no shell strings, no injection.
+- **Command safety.** Normal local search runs in-process inside `octocode-engine`. External helpers are fixed per lane, command/argument allowlisted, and run through `spawn` with argument arrays: no shell strings, no injection.
 - **Schema validation** runs before any tool executes; untrusted input size and shape are bounded.
-- **Credentials.** GitHub auth via env tokens, AES-256-GCM-encrypted on-disk OAuth, or the `gh` CLI; tokens are never logged.
+- **Credentials.** GitHub auth through env tokens, AES-256-GCM-encrypted on-disk OAuth, or the `gh` CLI; tokens are never logged.
 
-**Full security model, pipeline, and threat coverage: [SECURITY.md](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md).** Related: [Configuration & Authentication](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) · [Credentials](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#github-token)
+**Full security model, pipeline, and threat coverage: [SECURITY.md](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md).** Related: [Configuration and authentication](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) · [Credentials](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#github-token)
 
 ---
 
-## Language Support
+## Language support
 
 Four code-intelligence axes; three are native to the Rust engine and need no external tooling:
 
 | Axis | What it does | How to use it |
 |------|--------------|---------------|
-| **Structural AST** | Tree-sitter shape queries (`pattern` or YAML `rule`) across 60+ extensions. | `localSearchCode mode:"structural"` · CLI `tools localSearchCode --scheme` |
-| **Signature outline** | Body-free skeleton with line numbers from real tree-sitter parsing, no heuristics. An anti-growth guard returns the real file when a skeleton wouldn't be smaller. | `minify:"symbols"` · CLI `tools localGetFileContent --scheme` |
+| **Structural AST** | Tree-sitter shape queries (`pattern` or YAML `rule`) across 60+ extensions. | `localSearch operation:"structural"` · CLI `tools localSearch --scheme` |
+| **Signature outline** | Body-free skeleton with line numbers from real tree-sitter parsing, no heuristics. An anti-growth guard returns the real file when a skeleton is not smaller. | `minify:"symbols"` · CLI `tools localGetFileContent --scheme` |
 | **Content minification** | Comment/whitespace stripping for 70+ languages and config formats; HTML/Vue/Svelte also minify embedded `<style>`/`<script>`. | `minify:"standard"` (default) |
-| **LSP navigation** | definition, references, callers/callees, callHierarchy, hover, typeDefinition, implementation, documentSymbols, via an installed language server; JS/TS also have a native, no-server path. | `lspGetSemantics` · CLI `tools lspGetSemantics --scheme` |
+| **LSP navigation** | definition, references, callers/callees, callHierarchy, hover, typeDefinition, implementation, documentSymbols, through an installed language server; JS/TS also have a native, no-server path. | `lspGetSemantics` · CLI `tools lspGetSemantics --scheme` |
 
 📋 **Full support matrix:** every extension with its exact AST, signature, LSP,
 and minify capability lives in the
@@ -475,34 +426,33 @@ npx octocode skill check --json
 npx octocode skill help
 ```
 
-#### Core Research & Extraction
+### Core research and extraction
 | Skill | Use when |
 |-------|----------|
 | ⭐ [**octocode-research**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-research) | Evidence-first research, review, debugging, refactors, prior-art validation. |
+| [**octocode-code-graph**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-code-graph) | Repository dependency topology: cycles, paths, layering, reachability, impact analysis, and verified dead-code candidates. |
 | [**octocode-scraping**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-scraping) | Public page extraction and crawl triage: static corpus + graph v2 (pages/data/actions/risks/evidence), then CDP handoff for dynamic actions and blocked pages. |
 | [**octocode-chrome-devtools**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-chrome-devtools) | Browser/CDP evidence: network, console, performance, cookies/storage, screenshots, auth-gated pages, and live validation of scrape-graph actions. |
 
-#### Planning & Architecture
+### Planning and architecture
 | Skill | Use when |
 |-------|----------|
 | [**octocode-brainstorming**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-brainstorming) | Disciplined idea exploration before building: options, worth-building tests, prior-art maps. |
 | [**octocode-rfc-generator**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-rfc-generator) | Evidence-backed RFCs, design docs, migration plans, option comparisons. |
 | [**octocode-documentation**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-documentation) | Writing or updating README, API docs, runbooks, AGENTS.md, ADRs. |
 
-#### Evaluation & Review
+### Evaluation and review
 | Skill | Use when |
 |-------|----------|
 | [**octocode-roast**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-roast) | Blunt, evidence-backed code critique with severity ranking and repair paths. |
-| [**octocode-graph-eval**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-graph-eval) | Measuring whether a change helped: goal→KPI contracts, baselines, accept/revert loops, eval suites. |
+| [**octocode-eval-benchmark**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-eval-benchmark) | Smart evals and honest benchmarks: goal→KPI contracts, graders, held-out suites, guardrails, and accept/revert loops. |
 | [**octocode-prompt-optimizer**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-prompt-optimizer) | Making prompts, tool schemas, and agent contracts clearer, safer, cheaper, measurable. |
 
-#### Agent Orchestration
+### Agent orchestration
 | Skill | Use when |
 |-------|----------|
-| [**octocode-subagent**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-subagent) | Delegation: spawn gates, decomposition, sealed packets, coordination, synthesis. |
-| [**octocode-awareness**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-awareness) | Shared-repo coordination: collision avoidance, handoffs, verification debt, durable memory. |
+| [**octocode-subagent**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-subagent) | Spawning workers / Task / A2A / challenge techniques, or offloading token-heavy text to local Ollama under a verify gate. |
 | [**octocode-skills**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-skills) | Agent-skill lifecycle: discover, review, create, improve, install, sync. |
-| [**octocode-orchestrator-local-worker**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-orchestrator-local-worker) | Offloading token-heavy text work to a local Ollama worker under a verify gate. |
 
 **Web automation workflow:** `octocode-scraping` performs the safe static pass first (fetch/crawl/extract → local corpus → graph v2). When the graph exposes dynamic actions or static output is blocked/thin, `octocode-chrome-devtools` validates live actionability, cookies/storage, network/HAR bodies, screenshots, or auth-gated state; discovered URLs/data/artifacts can be fed back into the scraping corpus for continued proof.
 
@@ -510,7 +460,7 @@ npx octocode skill help
 
 ## Architecture
 
-A yarn-workspaces monorepo. The **MCP server** and the **CLI** are thin front-ends over one shared TypeScript tool core, which delegates every CPU-heavy path to a single **Rust engine** (compiled via [napi-rs](https://napi.rs) to prebuilt `.node` binaries). One tool catalog, one security layer, one response shaper, reached two ways.
+A yarn-workspaces monorepo. The **MCP server** and the **CLI** are thin front-ends over one shared TypeScript tool core, which delegates every CPU-heavy path to a single **Rust engine** (compiled through [napi-rs](https://napi.rs) to prebuilt `.node` binaries). One tool catalog, one security layer, one response shaper, reached two ways.
 
 ```mermaid
 graph LR
@@ -537,7 +487,7 @@ graph LR
 client → sanitize inputs (Rust) → run tool (GitHub / FS / LSP) → sanitize + YAML-serialize + paginate (Rust) → result + next-step hints
 ```
 
-**One Rust engine** owns secret detection, sanitization, path/command validation, minification (70+ languages), signature extraction, structural AST search, ripgrep parsing, diff filtering, YAML serialization, and LSP, so the Node event loop stays unblocked and there is no duplicate native loader. It ships prebuilt for darwin (arm64/x64), linux (arm64/x64, gnu + musl), and win32-x64; no Rust toolchain is needed at runtime.
+**One Rust engine** owns secret detection, sanitization, path and command validation, minification (70+ languages), signature extraction, structural AST search, ripgrep parsing, diff filtering, YAML serialization, and LSP. The Node event loop therefore stays unblocked, and there is no duplicate native loader. The engine ships prebuilt for darwin (arm64/x64), linux (arm64/x64, gnu and musl), and win32-x64; no Rust toolchain is needed at runtime.
 
 ### Packages
 
@@ -560,45 +510,46 @@ Website: **[octocode.ai](https://octocode.ai)** · Product docs: **[github.com/b
 
 | Area | Docs |
 |---|---|
-| MCP server | [Octocode MCP Server](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md) · [Configuration & Authentication](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) |
-| Tools and workflows | [Octocode Tools Reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md) · [RDD Manifest & Workflows](https://github.com/bgauryy/octocode/blob/main/MANIFEST.md) · [Octocode Research Skill](https://github.com/bgauryy/octocode/tree/main/skills/octocode-research) · [Search Guide](https://github.com/bgauryy/octocode/blob/main/docs/context/SEARCH_GUIDE.md) |
-| CLI | [Octocode CLI Guide](https://github.com/bgauryy/octocode/blob/main/packages/octocode/docs/OCTOCODE_CLI.md) |
+| MCP server | [Octocode MCP server](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md) · [Configuration and authentication](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) |
+| Tools and workflows | [Octocode tools reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md) · [RDD manifest and workflows](https://github.com/bgauryy/octocode/blob/main/MANIFEST.md) · [Octocode research skill](https://github.com/bgauryy/octocode/tree/main/skills/octocode-research) |
+| CLI | [Octocode CLI guide](https://github.com/bgauryy/octocode/blob/main/packages/octocode/docs/OCTOCODE_CLI.md) |
+| Research model | [Octocode research manifest](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_RESEARCH_MANIFEST.md) · [Routing and evidence position paper](https://github.com/bgauryy/octocode/blob/main/docs/ROUTING_EVIDENCE_POSITION_PAPER.md) · [MCP tool quality and agent workflow](https://github.com/bgauryy/octocode/blob/main/docs/MCP_TOOL_QUALITY_AND_AGENT_WORKFLOW.md) |
 | Skills | [Skills](https://github.com/bgauryy/octocode/tree/main/skills) |
-| Development and security | [Security Model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md) · [LSP Server Lifecycle](https://github.com/bgauryy/octocode/blob/main/packages/octocode-engine/docs/LSP_SERVER_LIFECYCLE.md) |
-| Benchmarks and evals | [Benchmark Results](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/results) · [Benchmark Design](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/skills/octocode-benchmark/references/BENCHMARK.md) · [Benchmark Runbook](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/skills/octocode-benchmark/references/INSTRUCTIONS.md) · [Support Matrix](https://github.com/bgauryy/octocode/blob/main/packages/octocode-engine/docs/LSP_SERVER_LIFECYCLE.md#full-format-support-matrix) |
-| Shared internals | [Credentials Architecture](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#github-token) · [Session Persistence](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md#session-persistence) |
+| Development and security | [Security model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md) · [LSP server lifecycle](https://github.com/bgauryy/octocode/blob/main/packages/octocode-engine/docs/LSP_SERVER_LIFECYCLE.md) |
+| Benchmarks and evals | [Benchmark results](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/results) · [Benchmark design](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/skills/octocode-benchmark/references/BENCHMARK.md) · [Benchmark runbook](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/skills/octocode-benchmark/references/INSTRUCTIONS.md) · [Support matrix](https://github.com/bgauryy/octocode/blob/main/packages/octocode-engine/docs/LSP_SERVER_LIFECYCLE.md#full-format-support-matrix) |
+| Shared internals | [Token priority order](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#github-token) · [Session persistence](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md#session-persistence) |
 
 ---
 
 ## Troubleshooting
 
-**Node.js or Environment Issues?**
+**Node.js or environment issues?**
 Run the built-in doctor command to check your environment:
 
 ```bash
-npx node-doctor check --json
+npx node-doctor
 ```
 
-**Common Pitfalls:**
-- **GitHub Auth Failures:** Ensure your Personal Access Token (PAT) has the `repo` and `read:user` scopes. If using the CLI, run `npx octocode auth login` to refresh.
-- **MCP Connection Issues:** If your AI assistant (like Cursor or Windsurf) fails to connect, ensure you have run `npx octocode auth login` in your terminal first, or explicitly pass your `OCTOCODE_TOKEN` in the MCP `env` configuration.
-- **Native Engine Errors:** Octocode uses a prebuilt Rust engine. If it fails to load on Linux, ensure your system has `glibc` or `musl` compatibility. On macOS/Windows, ensure you are on a supported architecture (x64 or arm64).
+**Common pitfalls:**
+- **GitHub auth failures:** Ensure your Personal Access Token (PAT) has the `repo` and `read:user` scopes. If using the CLI, run `npx octocode auth login` to refresh.
+- **MCP connection issues:** If your AI assistant (like Cursor or Windsurf) fails to connect, ensure you have run `npx octocode auth login` in your terminal first, or explicitly pass your `OCTOCODE_TOKEN` in the MCP `env` configuration.
+- **Native engine errors:** Octocode uses a prebuilt Rust engine. If it fails to load on Linux, ensure your system has `glibc` or `musl` compatibility. On macOS/Windows, ensure you are on a supported architecture (x64 or arm64).
 
 ---
 
-## Agent Workflows
+## Agent workflows
 
 ### Recommended dev mode: Pi + Octocode
 
-[Pi](https://github.com/earendil-works/pi) is a fast, local-first coding agent whose stated philosophy is *"CLI tools with READMEs (Skills) over MCP."* Pairing it with Octocode gives a lean, evidence-driven dev loop - **Pi edits, Octocode researches**. Two routes, pick by how much surface you need:
+[Pi](https://github.com/earendil-works/pi) is a fast, local-first coding agent whose stated philosophy is *"CLI tools with READMEs (Skills) over MCP."* Pairing it with Octocode gives a lean, evidence-driven dev loop — **Pi edits, Octocode researches**. Two routes, pick by how much surface you need:
 
-- **Skill route - recommended, leanest.** Drop the [`octocode-research`](https://www.skills.sh/bgauryy/octocode-mcp/octocode-research) skill into Pi's global skills dir. It drives the Octocode **CLI** directly - no MCP transport, minimal token overhead - and Pi auto-discovers it:
+- **Skill route — recommended, leanest.** Drop the [`octocode-research`](https://www.skills.sh/bgauryy/octocode-mcp/octocode-research) skill into Pi's global skills dir. It drives the Octocode **CLI** directly — no MCP transport, minimal token overhead — and Pi auto-discovers it:
 
   ```bash
   npx octocode skill install octocode-research --platform pi
   ```
 
-- **Adapter route - full tool surface.** Install [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) to expose Octocode MCP tools behind a single ~200-token proxy tool, so servers stay disconnected until a tool is actually called. Enable clone tools with `ENABLE_CLONE=true`.
+- **Adapter route — full tool surface.** Install [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) to expose Octocode MCP tools behind a single ~200-token proxy tool, so servers stay disconnected until a tool is called. Clone tools are available by default.
 
 ### Research-driven loop
 

package/dist/cacheMaintenance.d.ts

@@ -0,0 +1,8 @@
+export declare const CACHE_MAINTENANCE_INTERVAL_MS: number;
+export declare function getCacheMaintenanceMarkerPath(octocodeHome: string): string;
+export declare function getCacheMaintenanceDelayMs(octocodeHome: string, now?: number): number;
+/** Cheap persisted bootstrap gate shared by short-lived CLI and MCP processes. */
+export declare function runCacheMaintenanceIfDue(octocodeHome: string, now?: number): Promise<boolean>;
+/** Starts the long-lived MCP cron-style scheduler without keeping Node alive. */
+export declare function startCacheGC(octocodeHome: string): void;
+export declare function stopCacheGC(): void;