Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs: add plugin slash command reference and missing environment variables (#2090)
Akshat malik0629f5ecf730
diff --git a/docs/README.md b/docs/README.mdindex 4cb43ad61..70e845ef4 100644--- a/docs/README.md+++ b/docs/README.md@@ -30,6 +30,7 @@ For a map of every layer and how they feed each other, read| [start/QUICKSTART.md](start/QUICKSTART.md) | Install, index, and connect your agent || [agent/INTEGRATIONS.md](agent/INTEGRATIONS.md) | Which agents are supported at what depth, and how to add one || [agent/MCP_TOOLS.md](agent/MCP_TOOLS.md) | The ten task-shaped tools, what each answers, and the opt-in extras |+| [agent/CLAUDE_CODE_COMMANDS.md](agent/CLAUDE_CODE_COMMANDS.md) | The 18 `/repowise:*` slash commands in the Claude Code plugin || [agent/HOOKS.md](agent/HOOKS.md) | Context and warnings that reach the agent without it asking || [agent/DISTILL.md](agent/DISTILL.md) | Compress noisy command output before your agent reads it || [agent/LENS.md](agent/LENS.md) | Lens in the Claude Code plugin: the spinner, change review, Flow and the `/lens` map shown while Claude works |diff --git a/docs/agent/CLAUDE_CODE_COMMANDS.md b/docs/agent/CLAUDE_CODE_COMMANDS.mdnew file mode 100644index 000000000..baab993b9--- /dev/null+++ b/docs/agent/CLAUDE_CODE_COMMANDS.md@@ -0,0 +1,62 @@+# Claude Code Slash Commands++The [Repowise Claude Code plugin](../../plugins/claude-code/README.md) ships 18+slash commands under the `/repowise:` namespace. Install the plugin with+`/plugin install repowise@repowise` (see the plugin README), then run+`/repowise:init` to index the repo.++## How they work++- Each command is a Markdown instruction file in+ [`plugins/claude-code/commands/`](../../plugins/claude-code/commands/). Claude+ reads it, runs the matching `repowise` CLI command, and presents the result.+- The file's `allowed-tools:` frontmatter scopes what Claude may run: each+ command allows only its own CLI subcommand (for example+ `Bash(repowise health:*)`) plus `Read`.+- `/repowise:init` also allows the install commands (`uv tool install`,+ `pipx install`, `pip install`) and `AskUserQuestion`, so it can install+ repowise and ask about your setup. `/repowise:reindex` also allows+ `AskUserQuestion`.+- Text after the command name reaches the command as `$ARGUMENTS`:++```+/repowise:search authentication middleware+/repowise:context src/auth/token.py+/repowise:dead-code safe+/repowise:risk main..HEAD+```++## Command reference++| Command | What it does |+|---------|--------------|+| `/repowise:init` | Install repowise if needed, ask about your preferences, and index the repo |+| `/repowise:status` | Index health: sync state, page counts, provider, token usage |+| `/repowise:update` | Incremental update to bring the index up to recent commits |+| `/repowise:search` | Search the wiki by natural language, full text, or symbol |+| `/repowise:ask` | Cited answer to a codebase question with a confidence rating (one LLM call) |+| `/repowise:context` | Triage card for files, modules, or symbols: layer, hotspot, fix history, freshness |+| `/repowise:symbol` | One symbol's body with live-verified line bounds (`path::Name`, a line range, or a distill omission ref) |+| `/repowise:reindex` | Re-embed every wiki page into the vector store. Embedding calls only, no LLM calls |+| `/repowise:health` | Code health: KPIs, lowest-scoring files, refactoring targets, trends, per-file markers |+| `/repowise:coverage` | Ingest or inspect coverage reports (LCOV, Cobertura, Clover, Go, JaCoCo, Apex, repowise JSON; a coverage.py `.coverage` file builds the per-test map), or gate a change on patch coverage |+| `/repowise:impacted-tests` | Tests whose coverage touches a change's lines, for a commit, a `base..head` range, or the staged diff |+| `/repowise:risk` | Rank a change against recent history: repo-relative percentile plus a supporting diff-shape score |+| `/repowise:security` | Security signals. Working-tree scanning runs during `init` and `update`; `--history` walks the full git history for leaked secrets |+| `/repowise:dead-code` | Unreachable files, unused exports, and zombie packages, tiered by confidence |+| `/repowise:export` | Export the wiki or architecture model to Markdown, HTML, JSON, or Structurizr DSL |+| `/repowise:decision` | List, inspect, add, or confirm architectural decisions |+| `/repowise:why` | Why the code is shaped this way: decisions, rationale, git archaeology |+| `/repowise:doctor` | Diagnose the setup (install, API keys, index and store drift) and optionally repair it |++## Slash commands and MCP tools++- **Slash commands** are for you: run one when you want a specific report, such+ as dead code before a cleanup or risk before a merge.+- **MCP tools** are for Claude: it calls them on its own while working, for+ example `get_risk` before editing a hotspot. See [MCP_TOOLS.md](MCP_TOOLS.md).++Both read the same `.repowise/` index. The command files add presentation+rules on top of the CLI output, such as showing the confidence with every+`/repowise:ask` answer and treating only `safe_to_delete` findings as+deletions in `/repowise:dead-code`.diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.mdindex 4e3bdfde1..86d998afc 100644--- a/docs/reference/CONFIG.md+++ b/docs/reference/CONFIG.md@@ -1071,6 +1071,37 @@ Anonymous usage telemetry is **on by default** (opt-out).| `REPOWISE_FORGE_HOSTS` | `host=forge` pairs, comma separated (`git.corp.com=gitlab,tfs.corp.com=azure`); wins over `forges.hosts` || `REPOWISE_CHANGELOG` | Changelog source for the "what's new" check || `REPOWISE_PARSE_WORKERS` | Indexing parse processes: default CPU count capped at 8, never above the files to parse. Each holds about 50 MB; above 8 is not measurably faster |+| `REPOWISE_NO_SAVE_KEY` | Truthy: `init` does not save the provider API key to `.repowise/.env`, like `init --no-save-key`. Use it where credentials are injected at runtime and must not be written to disk |+| `REPOWISE_MCP_NO_WATCHDOG` | `1`, `true` or `yes` turns off the parent-process watchdog in `repowise mcp --transport stdio`, which exits the server when the MCP client dies abnormally (crash, force-quit, killed terminal) |+| `REPOWISE_INDEX_INFORMATION_FLOOR` | Minimum characters of substantive prose a wiki page needs to get a vector in the search index. Pages below it stay readable and linkable, they are only left out of semantic search. Default `0` (off) |++### BLAS thread pool++repowise caps the BLAS thread pool to 1 before numpy loads. An uncapped pool costs about 32 MB of memory per thread (about 750 MB on a 32-core machine) and does not speed up the sparse graph work repowise runs. Spawned worker processes inherit the cap through the environment.++A value you set yourself always wins:++```bash+OPENBLAS_NUM_THREADS=4 repowise init # 4 BLAS threads instead of 1+```++| Variable | Applies to | Default |+|----------|-----------|---------|+| `OPENBLAS_NUM_THREADS` | OpenBLAS | `1` unless set |+| `MKL_NUM_THREADS` | Intel MKL | `1` unless set |+| `NUMEXPR_NUM_THREADS` | NumExpr | `1` unless set |+| `VECLIB_MAXIMUM_THREADS` | Apple Accelerate | `1` unless set |++`OMP_NUM_THREADS` is not set: igraph's community detection uses OpenMP threads and is slower without them.++### Cache integrity key++repowise integrity-checks its on-disk caches with a machine-local key.++| Variable | Description |+|----------|-------------|+| `REPOWISE_CACHE_HMAC_KEY` | Hex-encoded key (at least 32 hex characters, 16 bytes) used instead of the key file. For CI and tests where the home directory is ephemeral or shared |+| `REPOWISE_CACHE_KEY_PATH` | Path to the key file. Default `$XDG_CONFIG_HOME/repowise/cache_hmac_key`, or `~/.config/repowise/cache_hmac_key` when `XDG_CONFIG_HOME` is unset |## Exclude patternsdiff --git a/docs/scale/AUTO_SYNC.md b/docs/scale/AUTO_SYNC.mdindex 8314c5392..eff27a4ea 100644--- a/docs/scale/AUTO_SYNC.md+++ b/docs/scale/AUTO_SYNC.md@@ -217,6 +217,21 @@ LLM cost. `POST /api/repos/{id}/full-resync` also regenerates every page.---+## Concurrent updates++Rapid commits through the post-commit hook and a manual `repowise update` can+start updates at once. One update runs at a time; a second one that finds the lock held+records its commit and exits, and the running update rolls forward to it.++| File | Purpose |+|------|---------|+| `.repowise/.update.lock` | Held by the running update. Records its PID, a process creation token and the target commit, so a lock left by a crashed update is cleared. A workspace update uses `.repowise-workspace/.update.lock` |+| `.repowise/.update.queued` | Written by the post-commit hook before it starts the background update, so agent hooks stop reporting a stale wiki right away |+| `.repowise/.update.pending` | Written by an update that found the lock held. Carries the newest HEAD, which the running update processes in an extra pass before it exits |+| `.repowise/.update.log` | Output of background updates. Capped at 256 KB, keeping the last 64 KB |++---+## Environment variables| Variable | Used by | Description |