The .repowise/ directory, config.yaml and its blocks, providers, keys and
environment variables.
Everything Repowise knows about your repository, created at the repo root by
init.
.repowise/
├── wiki.db # SQLite database: all pages, symbols, graph, git metadata, decisions
├── lancedb/ # Vector search index (LanceDB)
├── omissions/ # Distill omission store + savings ledger (omissions.db)
├── config.yaml # Provider, model, embedder, exclude patterns, distill/mcp/refactoring blocks
├── events.jsonl # Typed events as CloudEvents JSON lines (the jsonl event sink)
├── events.key # Random key the owner digests in component snapshots are made with
├── health-rules.json # Per-file code-health marker overrides
├── state.json # Last sync commit, page counts, token usage
├── mcp.json # MCP server configuration
└── .env # API keys (gitignored automatically)
.repowise/ is a local cache, not a source of truth: add it to your
.gitignore if you like, as Repowise does not edit that file during init. Only
decisions.yaml is meant to be committed. The secrets
.env and events.key are ignored by .repowise/.gitignore, so they stay out
of git even where .repowise/ is committed.
init creates it; flags such as --commit-limit, --follow-renames and
--wiki-style update it. Hand edits apply on the next init, update or
serve.
The key and variable tables in this file are generated from the settings
registry in repowise.core.settings, so each lists every key or variable
its block reads. Where an environment variable sets a key, the Env var
column names it and says whether it or the file wins.
Checking the file. Commands read an unknown or misspelled key as nothing and most bad values as the default.
repowise doctorchecks every key in this file and every variable in these tables against the registry: a value repowise cannot use fails with the form it accepts and therepowise config setorresetcommand that fixes it, an unknown key warns with the closest real key, and a variable that decides against the file is named.repowise doctor --repairresets bad file values to their defaults (outsidedecisions:and the provider selection, which take the row's command).
provider: anthropic
model: claude-sonnet-4-6
embedder: mock
embedding_model: text-embedding-3-small
reasoning: auto
max_tokens: 16384
commit_limit: 5000
follow_renames: false
wiki_style: comprehensive
language: en
enable_onboarding: true
max_file_pages: 2000
folder_coverage: ["src/core=1.0", "src/legacy=0.5"]
exclude_patterns: [vendor/, "*.generated.*", proto/]
distill: {enabled: true}
mcp: {tools: ["+get_execution_flows", "-get_dead_code"]}| Key | Default | Values | What it does | Env var |
|---|---|---|---|---|
provider |
unset | Which model service writes docs and answers (anthropic, openai, gemini, ollama, claude_cli and others). Unset: the saved global choice (provider_config.json), then REPOWISE_PROVIDER, then the first provider whose API key is present. | REPOWISE_PROVIDER (when the file is unset) |
|
model |
unset | The model id to use with the provider. Unset: the saved global choice (provider_config.json), then REPOWISE_MODEL, then the provider's default model. | REPOWISE_MODEL (when the file is unset) |
|
reasoning |
auto |
auto, off, none, minimal, low, medium, high, xhigh, max |
How much the model thinks before writing. | REPOWISE_REASONING (wins over the file) |
max_tokens |
16384 |
> 0 | Most output tokens for one generated page. | |
context_window |
unset | > 0 | Tokens (prompt plus answer) the model runs with; page material shrinks to fit. Unset: no limit for hosted models, 16384 for a local server (Ollama reports its own num_ctx). | |
wiki_style |
comprehensive |
How the wiki reads: comprehensive, caveman, reference, tutorial, or a custom style under .repowise/styles/. | ||
language |
en |
en, ru, es, fr, de, zh, ja, ko, it, pt, nl, pl, tr, ar, hi |
Language the docs are written in. | |
max_file_pages |
unset | >= 0 | Most per-file pages to write; 0 means every file. Unset lets the repo size decide. | |
folder_coverage |
[] |
Least share of files per folder that get their own page, as "glob=0.5". | ||
enable_onboarding |
true |
Write the onboarding pages. | ||
embedder |
unset | Which embedding service powers semantic search: openai, gemini, ollama, openrouter, edenai, a plugin's, or mock for none. Unset: the first embedder whose API key is present, then the embedder in ~/.repowise/config.yaml, then mock. | REPOWISE_EMBEDDER (wins over the file) |
|
embedding_model |
unset | The embedding model id. Unset uses the embedder's default. | REPOWISE_EMBEDDING_MODEL (wins over the file) |
|
exclude_patterns |
[] |
Extra paths to skip, as gitignore patterns. | ||
commit_limit |
5000 |
>= 1 | How many of the newest commits are analysed. | |
follow_renames |
false |
Follow files across renames in git history. | ||
sql_dialect |
unset | SQL dialect for parsing .sql files (a sqlglot name such as postgres). | ||
forges.hosts |
{} |
Which forge a self-hosted git host is: host to github, gitlab, azure, bitbucket or generic. | ||
editor_setup |
true |
Let update keep agent and editor files current. init --no-editor-setup writes false, which leaves them alone. | ||
changes.outcome_fix_days |
30 |
1-365 | Days after a change in which fix commits to its files are counted. | |
managed_checkout |
false |
This checkout is a clone the server owns: before each server sync it fetches the tracked branch and fast-forwards to it. Leave off for a working tree you edit. |
More on commit_limit, reasoning,
max_tokens, max_file_pages,
folder_coverage, wiki_style and
language below; exclude_patterns in
Exclude patterns, embedder in
Embeddings, forges.hosts in
GIT_HOSTS.md, and
changes.outcome_fix_days under repowise changes,
and managed_checkout in
AUTO_SYNC.md.
Blocks, each with its own section: generation_context,
distill, hooks, mcp,
editor_files, decisions,
coverage, security,
attribution, agent_provenance,
events, refactoring,
assertions, tests, and
<provider>.base_url.
Code-health rules live in health-rules.json.
--skip-tests, --skip-infra and --include-submodules apply only to their
run and are not stored here; --include-submodules is recorded in state.json
(workspace state).
- Sets how far back churn, co-change, the commit list and change records (newest 10,000 at most) see.
- The first
repowise updateafter upgrading re-reads history once, with no model calls. - A value written here is kept; below the default,
updatesays so once.
Applies to documentation-generation calls on reasoning-capable chat models.
autokeeps provider defaults, except on Ollama, where it turns thinking off.off/nonedisable Qwen3-style thinking on OpenAI-compatible vLLM/SGLang (sendsextra_body.chat_template_kwargs.enable_thinking=false) and map to OpenRouter'sreasoning.effort=nonefor effort-capable families.minimaltomaxrequest that effort where supported (e.g. OpenAI reasoning models, OpenRouter'sreasoning.effort).- A provider or model that cannot translate an explicit mode fails before any API call.
- One persistent setting for
init,update,generate,restyle, workspace and server-triggered generation; providers may enforce less. - A page that hits the limit before completing is rejected, not saved.
- Unset: the size policy decides, untouched below 4,500 documentable files and held to 4,500 above (about 1 repo in 100).
0: one page per eligible file. Positive: a hard cap.initoffers a tighter cap in advanced mode above 2,000 documentable files;--max-file-pages Nsets it non-interactively.update --fullandgeneratehonour the recorded value.- File pages are rendered from structure, so a cap does not reduce model spend.
"src/core=1.0"gives every eligible code file undersrc/corea file page whatever its importance or the cap;"src/legacy=0.5"gives the top half.- A floor, not a cap: pinned files are added to the selection and never displace a global pick, so the estimate rises with them.
init --folder-coverage GLOB=PCT(repeatable) sets it. Every run reads it, and editing it re-renders the wiki on the nextupdate.
- Set with
init --wiki-style, orrepowise restyle <style>, which also regenerates the wiki. Hand-editing it and runningupdatedoes not. - A custom style lives in
.repowise/styles/<name>/style.yaml(WIKI.md). An unknown name falls back tocomprehensivein generation; the CLI and API validate it up front.
- Code, paths and symbol names stay untranslated.
- Reaches model-written pages, and the headings and fixed sentences of template-rendered ones (file, symbol, infrastructure, cycle, API-contract) for languages with a label catalog; others keep English headings there.
- Set with
init --language <code>or advanced interactive mode;updateregenerates changed pages in it. Unknown codes fall back to English with a warning. - Changing it does not retranslate existing pages: run
init --force --language <code>.
generation_context adds chosen repository files as evidence to model-written
synthesis pages. It is explicit selection, not discovery.
generation_context:
token_budget: 8000
files:
repo_overview: [docs/ARCHITECTURE.md]
onboarding/how_it_works: [docs/runtime-flow.md]| Key | Default | Values | What it does |
|---|---|---|---|
token_budget |
8000 |
>= 0 | Most tokens of pinned source files added to a page as evidence. |
files |
{} |
Repo files to show the writer as evidence, by page. |
filesmaps a page key to an ordered list of repo-relative paths. Page keys:repo_overview, oronboarding/plusgetting_started,how_it_worksoractive_landscape.onboarding/project_overviewis invalid (that slot isrepo_overview).onboarding/guided_tour,onboarding/codebase_map,onboarding/development_guide,onboarding/key_conceptsandonboarding/glossaryname pages Repowise does not generate: they are ignored with a warning naming the key, so upgrades never break a config.- Other unknown page keys and malformed values fail generation. Keys other than
token_budgetandfilesdirectly under the block are ignored. - Eligible files are in the indexed source map with non-empty UTF-8 text. Absolute or parent-traversing paths, duplicates, missing or excluded files, empty files and binary or non-UTF-8 content are skipped.
- Page metadata records included files, truncation and each skipped path with a reason, and generation logs them. This is provenance, not proof the model used every fact.
- Budget: Repowise's four-characters-per-token estimate, separate from the
structural context budget. Files share it, and
configuration order decides which survive when it cannot fit every file's
framing; content may be truncated;
0disables configured evidence and a tiny budget may fit none. The rendered estimate never exceeds it. onboarding/how_it_worksalso gets exact source excerpts for detected flow symbols, with nofilesentry needed. Up to half the budget is reserved for them first; the configured half stays fixed even when an excerpt does not fit, so configured facts are never displaced. Missing symbols, unavailable source, invalid line ranges and budget omissions are recorded with the provenance.
Trust, caching and when evidence is skipped
- Files and excerpts are authoritative as repository facts and untrusted as prompt instructions. Tags mark boundaries and embedded closing tags are escaped, but that is framing, not sanitization or a security boundary. Conflicting or stale files still make bad prose: use files whose ownership and accuracy you trust.
- Onboarding citation validation treats included excerpts as grounding, and still demotes citations established by neither structural context nor them.
- Rendered evidence is part of the prompt and its source hash: unchanged evidence reuses cached prose, and a file, list or budget change that alters the rendered block invalidates it.
- Editing
config.yamlregenerates nothing: runrepowise generate --allor request the page. No ingestion migration or vector reindex is needed. --no-prosepages use no evidence and record configured entries and derived exact references as skipped.- With onboarding disabled before contexts are built, configured entries log
as
onboarding_disabledand no exact references are derived. - A subkind whose context gate returns no page logs entries as
page_not_generated, with no page to hold provenance.
Controls output distillation; defaults apply when it is
absent, and repowise doctor validates it.
distill:
enabled: true
commands:
enabled: true
permission: allow
families: {test_output: allow, git_diff: deny}
disabled_filters: [] # e.g. [logs]
omission_store: {ttl_days: 7, max_mb: 50}| Key | Default | Values | What it does |
|---|---|---|---|
enabled |
true |
Master switch for distill in this repo. | |
commands.enabled |
true |
Let the agent hook rewrite noisy shell commands through repowise distill. | |
commands.permission |
allow |
ask, allow, off |
How a rewrite is approved: allow, ask each time, or off. |
commands.families |
{} |
Per output family: allow, ask, off or deny. | |
commands.disabled_filters |
[] |
Filters never applied, by name (for example logs). | |
omission_store.ttl_days |
7 |
> 0 | Days a dropped piece of output stays recoverable. |
omission_store.max_mb |
50 |
> 0 | Size cap of the store of dropped output; oldest goes first. |
allowauto-approves rewrites for the main agent and every subagent. It is not an escalation: a rewrite is alwaysrepowise distill <one recognized command>from a closed family set.askshows each for approval;offdisables rewrites here.- Filter names:
test_output,build_output,lint_output,install_output,infra_plan,git_status,git_log,git_diff,git_diff_stat,search_results,file_listing,file_read,logs.repowise doctorchecks them against the live registry. - Declining the
repowise initopt-in writescommands.enabled: false, so a rewrite hook installed globally from another repo stays inert here.
Opt-in behaviour for the agent hooks; every key is off
when absent. REPOWISE_HOOK_<KEY> (e.g. REPOWISE_HOOK_READ_REREAD=1)
overrides a key for one session.
| Key | Default | Values | What it does | Env var |
|---|---|---|---|---|
read_skeleton |
false |
Serve a whole-file Read of a large indexed file as its outline. | REPOWISE_HOOK_READ_SKELETON (wins over the file) |
|
read_reread |
false |
Serve an unchanged repeat Read as a short notice. | REPOWISE_HOOK_READ_REREAD (wins over the file) |
|
search_digest |
false |
Serve a search that floods many files as a digest. | REPOWISE_HOOK_SEARCH_DIGEST (wins over the file) |
|
coverage_reingest |
false |
Re-read coverage reports after an agent's full test run. | REPOWISE_HOOK_COVERAGE_REINGEST (wins over the file) |
|
measure |
false |
On update, check locally whether agents acted on each hook firing. | REPOWISE_HOOK_MEASURE (wins over the file) |
|
health_gate |
false |
Block an agent's commit or push that fails repowise health check. | REPOWISE_HOOK_HEALTH_GATE (wins over the file) |
|
read_skeleton_mode |
smart |
smart, plus |
What a served outline keeps: smart, or plus to keep all code outside function bodies. | REPOWISE_HOOK_READ_SKELETON_MODE (wins over the file) |
coverage_reingeststarts a process per shell command; see test intelligence.measurereads this repo's recent agent transcripts locally, with no model, forrepowise hook stats.repowise hook backfilldoes the same on demand either way.health_gateis set withrepowise hook health-gate install(CI).
read_skeleton
- Once per file per session, the PostToolUse Read hook returns signatures with
bodies as
... N lines (a-b)markers (1-indexed), so a ranged Read recovers any span and a second Read returns the whole file. plusmode keeps imports, constants, class fields, decorators and comments, eliding only function and method bodies.- A file whose skeleton is over the 10,000-character hook output cap is served as an outline: one line per symbol, long signatures cut, the same range markers. When the outline is still over the cap, it lists as many symbols as fit (top-level types first, then the longest functions) and says how many.
- A file edited since the last index is passed through whole, so the line numbers are never off.
- Savings show in
repowise savedunderread_skeleton. Needs Claude Code 2.1.218+; older clients get the one-line pointer atget_context(include=["skeleton"]). - The
repowise initrewrite-hook question turns it on too (that question already asks whether Repowise's hooks may intervene, and a shell rewrite is the larger intervention);--no-editor-setupand--no-distill-hookturn it off. Per repo:repowise hook read-skeleton install | uninstall | status. - While off, skeleton-eligible Reads are measured and
repowise savedshows them under "Not saved": what replacement would have saved, and nothing about whether the agent wanted the whole file.
read_reread
- Answers a repeat Read with a notice naming the earlier read and its tool
call, when the same range was served this session, no
EditorWritecame between, and the bytes hash the same. - A changed file is served in full, with a line saying it changed on disk outside this session's edits, which nothing else in the session can detect.
- Never twice in a row for one file: compaction can drop the earlier copy and a hook cannot tell, so the next Read returns content, as the notice says.
- Savings show under
read_reread. Needs Claude Code 2.1.218+; older clients are untouched.
Chooses the tools the MCP server advertises. The default is curated: 10 tools
in single-repo mode, plus list_repos in workspace mode. repowise mcp --tools / --all override it for one launch.
| Key | Default | What it does |
|---|---|---|
tools |
unset | Which MCP tools are offered, for every client: a profile (core, lean, standard, all), optionally followed by +name or -name; +name or -name alone to adjust each client's default; or plain names as the exact list. Unset: Claude Code gets standard, clients that load every schema up front get core. |
always_load |
false |
Claude Code only: load the four read tools (get_answer, get_context, search_codebase, get_symbol) from the first turn instead of through tool search, for about 2k to 2.6k more tokens per turn, depending on the model. |
tools value |
Effect |
|---|---|
["+name", "-name"] |
Add to or remove from the default set. |
["get_answer", "get_context"] |
Unprefixed: an explicit allowlist. |
all |
Everything available. |
lean |
get_answer, get_context, get_symbol, search_codebase, get_risk, get_why (plus list_repos in workspace mode), small enough for Claude Code to keep every schema loaded. |
The seven opt-in tools are get_dependency_path, get_execution_flows,
generate_refactoring_code, set_finding_status and the workspace-only
get_blast_radius, get_conformance and get_architecture (ignored in
single-repo mode). See MCP_TOOLS.md.
The generated block in .claude/CLAUDE.md and AGENTS.md, read into the
agent's context every turn, so the default is lean.
editor_files:
claude_md: true
sections: ["+commands", "+fix_first"]| Key | Default | What it does |
|---|---|---|
claude_md |
true |
Write .claude/CLAUDE.md. |
agents_md |
true |
Write AGENTS.md. |
cursor_rules |
true |
Write the Cursor rules file. |
kiro_steering |
true |
Write the Kiro steering file. |
vscode_mcp |
true |
Write the VS Code MCP entry. |
sections |
[decisions, how_to_work] |
Sections of the generated agent block. +name or -name adjusts the default; plain names replace it. Extra: architecture, key_modules, entry_points, hotspots, health, code_health, fix_first, commands, how_to_work_full, tools. |
falseon a file key stops Repowise writing that file.- Every block leads with one line telling the agent to call a Repowise tool first for any question about the codebase.
- Default sections:
how_to_work(one line per moment: rename, edit, finish, noisy commands, settings) anddecisions(whether decisions govern files, plus up to five pinned titles). The default block stays within about 250 tokens; a test holds it there. - Opt-in:
architecture,key_modules,entry_points,hotspots,health(score and worst file),code_health(all health signals, replaceshealth),fix_first,commands(build, test and lint from manifests),how_to_work_full,tools(the MCP tool table). For examplesections: [+key_modules, +hotspots].
The decisions layer: one mode for the whole layer, then which sources
init mines, whether any may call a model, and the switches for each hook.
One resolved policy backs the CLI, API, hooks, MCP tools and index pipeline.
Every key is optional.
decisions:
mode: full
preset: balanced
sources:
comment: false
session: {enabled: true, llm: false}
session_discovery: true
discovery: {max_sessions: 12, max_input_tokens: 30000}
harnesses: [claude_code, codex]| Key | Default | Values | What it does |
|---|---|---|---|
mode |
full |
off, read_only, full |
The one switch for decisions: full (capture and show), read_only (show what exists, capture nothing) or off. |
preset |
unset | default, off, local_only, balanced, full |
A named set of capture sources to start from. Unset reads as default. |
enabled |
true |
Master switch for automatic capture. Stored decisions and manual entry work either way. | |
llm |
true |
Allow a model call while capturing decisions. Off keeps capture local. | |
agent_acceptance |
unset | Let a coding agent accept a decision, signed as the agent's. Unset: depends on decisions.mode: off under off, read_only; on under full. | |
capture_prompt |
unset | Ask the agent to record a decision when a commit states a choice. Unset: depends on decisions.mode: off under off, read_only; on under full. | |
require_approval |
false |
Make every new decision wait for a person before it applies. | |
sync |
false |
Send this repo's decisions to and from its copy on repowise.dev on update. | |
session_start |
false |
Open each agent session with the decisions relevant to its work. | |
upkeep_prompt |
false |
After a commit, ask the agent to settle the decisions it touched. | |
update_mining |
unset | Let repowise update call a model to find decisions in new commits and PRs. Unset: off, unless the decisions block names a preset or lists sources, which keeps an older setup mining. | |
discovery.max_sessions |
12 |
1-24 | Most sessions read in one discovery pass. |
discovery.max_input_tokens |
30000 |
2000-60000 | Most input tokens one discovery pass may send. |
harnesses |
[claude_code] |
Which coding agents' local session transcripts may be read. |
More on mode, sources, presets,
require_approval, sync,
update_mining, session_start and
upkeep_prompt below.
The one switch for the layer. Each position sets the defaults of the finer
switches below; a switch you set explicitly wins over its mode's default,
except under off.
| Mode | Shows decisions | Records decisions | Defaults it sets |
|---|---|---|---|
full |
Yes | Yes | The defaults in the table above |
read_only |
Yes: the edit notice, get_why, get_answer, the agent-file pointer and pins, and pulls from repowise.dev when sync is on |
No: no mining, no capture prompt, no agent putting a decision in force, nothing sent to repowise.dev, no landing granting force | capture_prompt, agent_acceptance off |
off |
No: every hook, MCP surface and the agent-file block stay silent; get_why answers that decisions are off |
No | Everything off; explicit switches are ignored |
repowise decision config mode off|read-only|full sets it and resets the
finer switches to that mode's defaults; set one afterwards to differ. A bare
mode: off in YAML reads as off, and an unknown value reads as read_only
with a warning. Manual entry (repowise decision add by a person) works in
every mode.
Keys under decisions.sources.:
| Key | Default | What it does |
|---|---|---|
inline_marker.enabled |
true |
Capture from inline markers. WHY:/DECISION:/TRADEOFF: comment markers in source files. A preset may change the default. |
inline_marker.llm |
true |
Allow a model call when capturing from inline markers. |
git_archaeology.enabled |
true |
Capture from git archaeology. Commit messages carrying one of the decision verbs. A preset may change the default. |
git_archaeology.llm |
true |
Allow a model call when capturing from git archaeology. |
adr.enabled |
true |
Capture from ADR files. Nygard and MADR architecture decision records. A preset may change the default. |
adr.llm |
true |
Allow a model call when capturing from ADR files. |
pr.enabled |
true |
Capture from pull request bodies. Squash-merge and PR bodies that read as a description. A preset may change the default. |
pr.llm |
true |
Allow a model call when capturing from pull request bodies. |
comment.enabled |
true |
Capture from comment archaeology. Rationale prose in comments on high-centrality files. A preset may change the default. |
comment.llm |
true |
Allow a model call when capturing from comment archaeology. |
session.enabled |
false |
Capture from agent sessions. Durable choices mined from local coding-agent transcripts. A preset may change the default. |
session.llm |
true |
Allow a model call when capturing from agent sessions. |
session_discovery.enabled |
false |
Capture from session discovery. One broad model pass over new transcript prose each update. A preset may change the default. |
session_discovery.llm |
true |
Allow a model call when capturing from session discovery. |
conventions.enabled |
false |
Capture from conventions. Import patterns the graph proves: a wrapper most files reach a library through. A preset may change the default. |
- Session mining and session discovery
have their own sections below.
git_archaeology,pr,commentandsession_discoveryare model-only. - A source is a boolean or
{enabled, llm}.llm: falsematters only for sources with a deterministic stage (inline_marker,adr,session): it keeps the parse and skips the model. - A model-only source with its model stage off is skipped entirely: it would produce a zero indistinguishable from an empty repository.
- Unknown keys warn instead of silently reading as a switch;
code_comment,changelogandreadme_miningare unknown keys. - With no block, the policy is
default: long-standing sources and model stages on, exceptsession.session_discoveryandconventionsstay off until asked for, so upgrading never starts an unrequested model call. sessionships off because its captures read as working agreements, not decisions.repowise decision source set session --onenables it;local_onlyincludes it.- A config naming a preset and listing sources keeps that list, so a source later added to the preset does not join; re-apply the preset.
- Legacy
decisions.session_mining: true|falsemaps tosessionboth ways; an explicitsources.sessionmay narrow, never widen it. The first CLI or API write replaces it withsources.session.
| Preset | Effect |
|---|---|
default |
No block. Long-standing sources on; session mining and broad discovery off. |
off |
No automatic capture; stored decisions and manual entry still work. |
local_only |
Deterministic only, session mining included (the only lane that produces without a key); zero extraction model calls. |
balanced |
High-signal sources, session mining and the discovery it feeds; comment archaeology off. |
full |
Every source and model stage. |
Editing a key after a preset drops the preset line; the policy reads custom.
Sources say what is mined at init (and update --full). Whether update
mines too is update_mining, which no preset changes.
llm: false is complete, not degraded: transcripts are read, markers and ADRs
parsed, episodes recorded, manual decisions work and accepted ones govern. It
is the one switch proving no extraction reaches a model.
Neither is about capture, and no preset changes them.
agent_acceptanceon (default): an agent may accept, recorded as an agent's with the signing session, on every surface, never as yours. Off: an agent can propose and withdraw authority, never grant it.falseis written to the config so it survives a reload.capture_prompton (default): a successfulgit commitwith two or more decision signals prompts the agent, once per session, to runrepowise decision add; never for a commit a record already cites, and only as a proposal.falseis written to the config so it survives a reload.- It fires from a separate
Bash|PowerShellPostToolUse entry, whichinitand the Claude Code plugin install. The entry tests the payload forgit commitin the shell, so other shell calls never start Python. repowise decision config capture-prompt --offswitches the prompt off for one repository and leaves the per-install entry, which stays silent there.--onreinstalls the entry if it is missing.
Off by default: a decision an agent records comes into force when the commit
it cites lands on the default branch. On, the landing grants nothing and an
agent's own acceptance is refused; a person puts each new decision in force
with repowise decision confirm. repowise decision config approval --on
writes it. A value that is not a boolean reads as on.
Off by default, and no preset changes it. On, and with this machine signed in
(repowise login) and a GitHub origin, every update runs
decision push then decision pull against the repo on repowise.dev. No
model runs, and a failure prints one line without failing the update. Under
mode: read_only only pull runs. A value that is not a boolean reads as off. repowise decision config sync --on|--off
writes it.
Off by default: init reads PR bodies, commit messages and comments once,
and the records it mines are background, served by get_why when asked.
update then makes no model call for decisions. Inline markers are still read
on changed files, and decisions an agent recorded still come into force when
their commit lands.
- On: each
updatealso mines new PR bodies and commits, structures new inline markers, and asks the model whether a change replaced a decision it touches.repowise decision config update-mining --on. - With no
update_miningkey, adecisions:block that names apresetor listssourcesreads as on, so a repository configured before this setting keeps mining on update. No block reads as off. The key is written on every CLI or API write. - While off, each source's mining pointer stays where it was; switching on mines the missed range, bounded by each miner's cap.
Off by default: an agent sees a decision when it edits a file the decision
governs, and get_why answers for any path, so a session that never touches
governed code pays nothing for decisions.
- On: the session start hook also lists up to six decisions in force over the
files the session is likely to touch (changed, staged, on the branch, or
edited last session), plus at most two labelled background records.
repowise decision config session-start --on.
Off by default. On, a successful git commit that changes files governed by
decisions in force gets one line naming up to three of them, each once per
session, with the one command for each outcome:
- still holds:
repowise decision reaffirm <id> --agent <slug> - replaced by this change:
repowise decision deprecate <id> --superseded-by <new id> --agent <slug> - knowingly broken:
repowise decision deprecate <id> --reason '<why>' --agent <slug>
It fires from the same shell entry as capture_prompt; repowise decision config upkeep-prompt --on installs it if missing. Every firing is logged, and
repowise hook stats reports how often a session settled a decision it named.
repowise decision config show # the resolved policy, per source
repowise decision config mode read-only # off | read-only | full
repowise decision config preset local_only
repowise decision source set comment --off
repowise decision source set adr --no-llm # keep the parse, skip the model
repowise decision source set session_discovery --on
repowise decision config discovery --max-sessions 6 --max-input-tokens 12000
repowise decision llm --offMutating commands take --dry-run and --format json; writes are atomic and
keep unrelated keys.
session (off by default) lets repowise update read coding-agent transcripts
(Claude Code's ~/.claude/projects/) for user corrections, explicit choices
with a stated reason, and failed approaches replaced by working ones.
- Deterministic gates first, then one batched LLM structuring call per update; any field not quoting the transcript verbatim is dropped.
- Mined records are background however often they recur;
repowise decision confirmputs one in force. - All local: transcripts are read on your machine, staging is
.repowise/sessions/sessions.db, and only distilled decision text is stored.
session_discovery sends the prose an update newly read (bounded by
discovery.max_sessions and discovery.max_input_tokens) to the model in one
call per update, for decisions the gates missed. It reuses the session
source's read and needs it on.
- Each candidate cites span ids, and each quote is verified against the span. Citing an unsent span, quoting nothing a span says, or naming a file the cited turns never touched is rejected and counted.
- Scope is the files those turns' tools touched; the model may pick among them, not add.
- Output is background (
proposed); onlyrepowise decision confirmputs it in force. - Prose over budget queues in
sessions.dband goes oldest-first next update, never aged out unread. A provider failure retries it on the next two updates before dropping it. - Switching off keeps the queue; prose read while off is never backfilled.
Dismissals are sticky: repowise decision dismiss keeps a dismissed
tombstone, so reindexing never re-proposes it, and re-extraction never moves a
confirmed (active) decision back to proposed.
The committed record of decisions in force; the rest of .repowise/ can be
deleted and rebuilt.
repowise decision exportwrites it and un-ignores it if a.repowise/rule hid it;repowise decision importreconciles the store to it.- It carries a
version; a file from a newer Repowise is refused, not downgraded. Round trip: DECISIONS.md.
Components are what health, hotspots, bus factor, test reach and dead code roll
up to. The file is multi-document Backstage YAML (Component, System,
Group on backstage.io/v1alpha1); a repo-root catalog-info.yaml is read
the same way, so a developer portal shares it. See
examples/components and
repowise components check.
| Annotation | Holds |
|---|---|
repowise.dev/paths |
Gitignore-style globs with /, case-sensitive. |
repowise.dev/criticality |
low, medium, high, critical. |
repowise.dev/tags, repowise.dev/capability |
Tags and capability. |
- Without a file, components derive from workspace services, then module pages, then top-level directories.
- A declared component claims files its globs match; the first declared wins. One named like a derived component replaces it and, without paths, keeps its directory.
- Derived names come from the directory, skipping route parameters and groups
(
[id],(group)). On a clash the shallowest keeps the name and the others add their nearest parent other thansrc,liborapp(workspace-web), so catalog names stay stable.
The change policy repowise check evaluates.
version: 1
rules:
- name: agent-pci-needs-owner
match:
components: {tags: [pci]} # also names, criticality; each list is any-of
when:
attribution: agent # agent, human_attested or unknown
reaching_tests: missing # a changed file in scope has no reaching test
action: require_owner_review
- name: no-new-secrets
gate: security
with: {fail_on: high, baseline: .security-baseline.json}
action: fail # the default for a gate| Rule key | What it does |
|---|---|
name |
Unique; lowercase letters, digits, _, -, starting alphanumeric, at most 63 characters. |
description, message |
Optional text. |
match, exclude |
Select components by names, tags, criticality. |
when |
Conditions; all must hold. |
action |
warn, require_owner_review, require_tests, fail. |
gate, with |
Wrap security, coverage, doc_drift or health with that command's options. |
- Conditions:
attribution,agent_tier(1, 2 or 3),reaching_tests(missingorpresent),contract_break,decision_crossed,bus_factor_below. No risk-score condition. - Missing evidence (no index, attribution off) leaves a rule unevaluated; it never fires.
- A wrapped gate runs exactly as the command alone;
doc_driftis scoped to the change (since) unless set. require_owner_reviewandrequire_testsare advisory: reported in every format, exit 0. Onlyfailexits 1.- Exit 2 (
policy_invalid, all problems listed): unknown key, condition or gate option, bad action, duplicate name, or a file over 256,000 bytes. Also exit 2 when afailgate cannot be evaluated.
Teams whose members count as the team's activity, for repowise components ownership and get_context(include=["ownership"]) on a component.
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
name: payments
annotations:
repowise.dev/member-emails: "ana@acme.com, li@acme.com"
spec:
type: team
children: []
members: [ana-acme, li-acme]spec.memberslists forge logins;repowise.dev/member-emailslists git author emails. Members only match commits and never appear in output.- CODEOWNERS
@org/team(GitHub or GitLab, sections included) and a catalogspec.ownerofgroup:default/teamresolve to the Group namedteam. - Group entities in catalog files add team names; their
spec.membersis not read.
Coverage reports and gates; behaviour in test intelligence, gates in CI.md.
| Key | Default | Values | What it does |
|---|---|---|---|
auto_discover |
true |
Look for coverage reports in the usual places. | |
artifacts |
[] |
Where to look for coverage reports instead of the usual places. | |
paths |
[] |
Report paths or globs from the repo root, read without discovery. An entry may be {path, path_prefix}. | |
ignore |
[] |
Files coverage leaves out. | |
format |
unset | Force a report format instead of detecting it. | |
strip_prefix |
unset | Path prefix to strip from report paths. | |
path_prefix |
unset | Path prefix to add to report paths. | |
reingest_on_update |
unset | Re-read reports on every update. Unset re-reads only newer reports. | |
fail_under |
unset | 0-100 | The coverage gate fails below this percent. |
fail_under_risky |
unset | 0-100 | The coverage gate fails when risky files are below this percent. |
max_drop |
unset | 0-100 | The coverage gate fails when coverage falls from the base by more than this many points. |
fail_under_branches |
unset | 0-100 | The coverage gate fails below this branch percent. |
min_coverable_lines |
unset | >= 0 | Changes with fewer coverable lines than this pass the gate. |
gates |
[] |
Coverage gates scoped to paths. |
gates holds path-scoped gates.
Unset reingest_on_update: repowise update re-reads when a report in
coverage.paths or at a fixed discovery location (e.g. coverage/lcov.info)
is newer than the last ingest, replacing hand-added coverage. A report only a
** glob finds is not watched; list it in paths.
Your own secret shapes for repowise security check.
security:
patterns:
- name: internal_token
regex: 'itk_[A-Za-z0-9]{32}'
severity: high| Key | Default | What it does |
|---|---|---|
patterns |
[] |
Your own secret shapes for security check, each {name, regex, severity}. |
Each pattern:
| Field | Default | What it does |
|---|---|---|
patterns[].name |
required | 1 to 40 of a-z, 0-9, _, -; unique. |
patterns[].regex |
required | The secret shape. |
patterns[].severity |
high |
low, med, high. |
- Each is secret kind
custom:<name>(SARIF rulecustom/<name>): changed lines only, every commit of the change, matches masked to four characters and****in every format, severity kept under test, fixture and example paths. - Findings key on file, kind and masked line, so same-prefix matches on one line share a baseline entry.
- At most 50 patterns of 500 characters. Lines over 4096 characters are skipped
and counted (
long_lines_skipped); a slow regex that passes the checks stays slow. - Exit 2 (
config_invalid, all problems listed): unknown key, missing name or regex, duplicate or badly shaped name, bad severity, or a regex that does not compile, can match empty, or nests repetition like(a+)+or(a|aa)+(best effort).
| Key | Default | Values | What it does |
|---|---|---|---|
enabled |
true |
Read public AI-authorship markers: bot authors, commit trailers and footers, git-ai notes, Agent Trace files. The same key in ~/.repowise/config.yaml can turn it off for every repo. | |
capture |
off |
off, local, notes |
Record listed agents' edits as they write them: local keeps line hashes in .repowise/attribution/, notes also writes git-ai notes on refs/notes/ai. The lower of this and the same key in ~/.repowise/config.yaml applies, so both must turn it on; DO_NOT_TRACK turns it off. |
agents |
[] |
Agent target ids whose edits are recorded, such as claude-code or codex. Only agents named both here and in ~/.repowise/config.yaml are recorded. |
~/.repowise/config.yamlmay hold the same block for every repository; the stricter value wins per key (enabled: falsein either, the lower capture, agents both list). A key unset in one file takes its default first, so capture needs both files: repo-onlycapture: localresolves tooff.enabled: falsestores and shows nothing about AI in the API, CLI, MCP, web or wiki.DO_NOT_TRACK=1keeps capture off.repowise attribution statusshows effective, repo and user values and history coverage. What leaves the machine: ATTRIBUTION.md.- The same consent lets
repowise attribution backfill --agent claude-code,codexbind past commits from those agents' local transcripts.
Your own bots and footers, added to the built-in agent markers (ATTRIBUTION.md).
agent_provenance:
service_emails:
mybot@example.com: {agent: mybot, tier: 1}
footer_patterns:
- {pattern: "Generated by MyBot", agent: mybot}
coauthor_patterns:
- {pattern: "^co-authored-by: mybot <[^>]*@example\\.com>", agent: mybot}| Key | Default | What it does |
|---|---|---|
service_emails |
{} |
Your bots' commit emails, each mapped to {agent, tier}, so their commits count as that agent's. |
footer_patterns |
[] |
Commit-message footer regexes that mark an agent's commit, as {pattern, agent}. |
coauthor_patterns |
[] |
Co-author trailer regexes that mark an agent's commit, as {pattern, agent}. |
| Key | Default | Values | What it does |
|---|---|---|---|
enabled |
true |
Snapshot components each index run and record what changed. | |
retention_days |
365 |
> 0 | Days runs and their events are kept. |
compact_after_days |
30 |
> 0 | Days after which only one run a week is kept. |
kinds.ownership_shift |
true |
Record when a file's main owner changes. | |
kinds.owner_inactive |
true |
Record when a file's owner goes quiet. | |
kinds.bus_factor_drop |
true |
Record when fewer people know a component. | |
kinds.new_hotspot |
false |
Record when a file becomes a hotspot. | |
kinds.contract_added |
true |
Record when a new API contract appears. | |
kinds.contract_broken |
true |
Record when an API contract breaks. | |
kinds.decision_stale |
true |
Record when a decision goes stale. | |
kinds.dead_code_growth |
true |
Record when dead code grows. | |
kinds.test_reach_drop |
true |
Record when test reach drops. | |
sinks |
[] |
Where events go: jsonl, stdout or a plugin sink. Empty writes jsonl. |
- A run diffs against the previous one when both share the analyzer and parser stamp; a stamp change or an intervening run without a snapshot starts a new baseline.
- Owners compare as digests keyed by
.repowise/events.key; a declared owner is named only when it is a group. Severity followsrepowise.dev/criticality. repowise doctornames values that fell back to defaults. Read events withrepowise eventsorGET /api/repos/{id}/events.
Caps on the runtime evidence repowise evidence add stores (profiles,
benchmark results, test timings, query counts). A capped run keeps its
costliest entries and counts the rest, so a reader shows them as unknown,
never as zero. How evidence is collected and joined:
RUNTIME_EVIDENCE.md.
| Key | Default | Values | What it does |
|---|---|---|---|
max_file_mb |
20 |
> 0 | Largest evidence file read, in MB; a bigger one is refused before it is read. |
max_symbols_per_run |
1500 |
>= 1 | Most functions stored from one profile, costliest self time (waits excluded) first; the rest are counted. |
max_rows_per_run |
30000 |
>= 1 | Most benchmark, test or query rows stored from one run; the rest are counted. |
history_runs |
20 |
>= 1 | Runs kept per workload and environment for each evidence kind; oldest go first. |
max_runs |
50 |
>= 1 | Runs kept per evidence kind across all workloads; oldest go first, but each workload and environment always keeps its newest run, so the kind can exceed this by up to the number of workloads. |
rank_top_n |
10 |
>= 1 | A measured function is ranked when it is among this many production functions with the most self time in its run (built-ins and libraries it calls included, waits excluded). |
rank_min_samples |
30 |
>= 1 | Fewest self samples on a function for it to be ranked; below this the run has not enough samples in repo code. Runs that count no samples rank by their order alone. |
lead_min_share |
0.05 |
0-1 | Share of all samples a ranked function needs, in a workload class that may lead, to become a lead candidate from one run. |
lead_min_lower_bound |
0.02 |
0-1 | Lower bound of the 95% interval on that share a lead candidate needs from one run. |
lead_min_runs |
2 |
>= 2 | Independent runs, in workload classes that may lead, in which a function must be ranked to become a lead candidate without the share rule. |
Tunes the Extract Class / Extract Method / Extract Helper / Move Method / Break
Cycle / Split File plans behind repowise health --refactoring-targets,
get_health(include=["refactoring"]) and the web Refactoring tab.
| Key | Default | Values | What it does |
|---|---|---|---|
enabled |
true |
Work out refactoring plans in the health pass. | |
detectors.disabled |
[] |
Refactoring detectors to silence, such as extract_class or split_file. | |
min_confidence |
unset | low, medium, high |
Least confidence a refactoring plan needs to show. |
llm.enabled |
false |
Let a model write refactoring code when asked; indexing never calls it. |
- Code generation uses chat's provider and model, and is the only part that calls a provider.
min_confidenceapplies at detection, so plans below it are never persisted (like a disabled marker); changes apply on the nextinit/update. Amin_confidencequery parameter can only narrow further.- Per-path disables use the
health-rules.jsonglob mechanism markers use. Full reference: REFACTORING.md.
Your own assertion helpers, for test-quality markers that divide by a test's assertion count.
assertions:
extra_names: [ensureInvariant, mustMatch] # exact callee names, not prefixes| Key | Default | What it does |
|---|---|---|
extra_names |
[] |
Your own assertion helpers, by exact name, counted as assertions. |
Repowise knows the xUnit and BDD families (assert*, expect*) and
per-language idioms such as Go's t.Fatalf and testify's require. A house
helper outside those is invisible, and a test of only such helpers reads as
assertion-free; this block is the escape hatch other test linters also offer.
- Names are exact and case-insensitive, never prefixes:
ensureInvariantdoes not matchensureConnectionPool. Prefixes, measured on three real test corpora, matched production functions more often than assertions. - A name counts as the call or as its receiver (
ensureInvariant(x).isTrue()). - These names reach only the advisory assertion total; the calibrated
large_assertion_blockandduplicated_assertion_blockmarkers use a separate count, so a wrong name costs signal, never a score. - Changes re-walk affected files on the next
init/update.
Rules repowise impacted-tests adds to its selection; see
CI.md.
tests:
full_run_on: [schema/**, "*.proto"]
always_run: [tests/smoke/test_boot.py]| Key | Default | What it does |
|---|---|---|
full_run_on |
[] |
Gitignore patterns whose change makes impacted-tests select every test. |
always_run |
[] |
Tests added to every impacted-tests selection, as written. |
A separate JSON file tuning code-health biomarkers: which run, their severity, and per-path overrides. Malformed JSON warns and falls back to an empty config.
{
"profile": null,
"disabled_biomarkers": [],
"severity_overrides": {"high_churn": "low"},
"rules": [
{
"path": "legacy/**",
"disabled_biomarkers": ["long_function"],
"severity_overrides": {"duplication": "critical"}
}
]
}| Key | Default | What it does |
|---|---|---|
profile |
null |
Calibration profile; only "small-team" exists. |
disabled_biomarkers |
[] |
Biomarkers skipped repo-wide. |
severity_overrides |
{} |
Biomarker name to severity label. |
rules[] |
[] |
Per-path overrides, in order. |
rules[].path |
required | Gitignore-style glob (* stops at /; use ** for nested files); aliases path_glob, glob. |
rules[].disabled_biomarkers, rules[].severity_overrides |
[], {} |
As above, for matching files. |
Labels are low, medium, high, critical; only the label is overridable,
never the weights or caps behind the score.
Full reference: CODE_HEALTH.md.
Choices for this machine's user, read in every repository.
repowise telemetry disable writes telemetry_enabled; the variables under
Telemetry and account override both keys.
| Key | Default | What it does |
|---|---|---|
telemetry_enabled |
true |
Send anonymous usage counts. DO_NOT_TRACK, REPOWISE_TELEMETRY_DISABLED and REPOWISE_OFFLINE turn it off whatever this says. |
hints_enabled |
true |
Show occasional repowise.dev tips in the CLI and web UI. |
export ANTHROPIC_API_KEY="sk-ant-..."
repowise init --provider anthropic --model claude-haiku-5-5Models: claude-haiku-5-5 (default, fastest, cheapest), claude-sonnet-5-5
(best balance), claude-opus-5-5 (highest quality, higher cost).
export OPENAI_API_KEY="sk-..."
repowise init --provider openai --model gpt-5.6-lunaAn OpenAI-compatible Qwen3 endpoint on vLLM or SGLang:
export OPENAI_BASE_URL="http://localhost:8000/v1"
repowise init --provider openai --model qwen3 --reasoning offThe same adapter serves local gateways such as 9router and any
OpenAI-compatible provider: the gateway key in OPENAI_API_KEY,
OPENAI_BASE_URL at its /v1 endpoint, and a model id from its /models
(namespaced ids work as-is, no gpt- prefix needed). For another local
provider, swap the key, URL and model.
export OPENAI_API_KEY="your-9router-dashboard-key"
export OPENAI_BASE_URL="http://localhost:20128/v1"
repowise init --provider openai --model ag/gemini-3.7-flash-mediumInteractive gateway setup
In interactive repowise init, choose OpenAI-compatible (Custom / local
gateway). Repowise validates the endpoint, takes the key without echo,
verifies it through /models, and lets you search the models or type an id.
Without /models you can retry, enter an id manually, or go back:
Base URL [http://localhost:20128/v1]:
API key (hidden): <paste the gateway key>
✓ Connected — discovered 47 model(s).
Select model: ag/gemini-3.7-flash-medium
- The endpoint goes in the gitignored
.repowise/.env; the key only after confirmation, never with--no-save-key. config.yamlgetsprovider: openaiand the exact model id.- The separate openai row is the official endpoint.
- Scripted runs (
--yes, CI, non-TTY) stay non-interactive: use environment variables and--provider openai.
export OPENROUTER_API_KEY="sk-or-..."
repowise init --provider openrouter --model openai/gpt-5 --reasoning minimal
repowise init --provider openrouter --model x-ai/grok-4 --reasoning offexport GEMINI_API_KEY="AI..." # or GOOGLE_API_KEY
repowise init --provider geminiWith GEMINI_API_KEY set, Gemini is also the default embedder.
export DEEPSEEK_API_KEY="..."
repowise init --provider deepseek --model deepseek-flashexport KIMI_API_KEY="..."
repowise init --provider kimi --model kimi-for-codingThe default Kimi Code endpoint serves kimi-for-coding and
kimi-for-coding-highspeed. K2.x models need a Kimi Open Platform key and its
OpenAI-compatible endpoint. Repowise sets the required sampling parameters for
both, including K2.x thinking or instant mode.
export KIMI_BASE_URL="https://api.moonshot.ai/v1"
repowise init --provider kimi --model kimi-k2.6export OLLAMA_BASE_URL="http://localhost:11434"
repowise init --provider ollama --model llama3.2- The window is the model's own
num_ctxif its Modelfile sets one, else 16384, never above its trained context length. Page material (code excerpts, source evidence) shrinks to fit it, least important first, so a 4B model on a laptop writes a page in seconds instead of minutes. REPOWISE_OLLAMA_NUM_CTXpinsnum_ctxand sizes material to it, which gives a bigger model more to read;context_windowinconfig.yamlsizes material only, andnum_ctxgrows to hold the prompt.reasoning: autoturns thinking off for page generation;low,mediumorhighturn it on, and the window grows to hold the longer answer.- Requests go one at a time; with server
OLLAMA_NUM_PARALLELabove 1, set the same value where Repowise runs.
export LITELLM_API_KEY="..."
repowise init --provider litellm --model azure/gpt-4Eden AI is a hosted gateway with an EU endpoint, so
inference stays in the EU without self-hosting. Every other hosted provider
here terminates in the US; under a DPA the alternatives are Ollama or LiteLLM
on your own infrastructure. EDENAI_BASE_URL selects the EU endpoint for the
LLM and the embedder; without it, requests use the global endpoint.
export EDENAI_API_KEY="..."
export EDENAI_BASE_URL="https://api.eu.edenai.run/v3"
repowise init --provider edenai --model mistral/mistral-small-latest
repowise init --provider edenai --model openai/gpt-5-mini --reasoning low- One key reaches many vendors (Mistral, GPT, Claude, Gemini, Cohere,
DeepSeek, Llama) through one OpenAI-compatible endpoint, as
vendor/model. - Public catalogue, no auth: https://api.edenai.run/v3/models; embedding models: https://api.edenai.run/v3/embeddings/models.
reasoningmaps to OpenAIreasoning_effortfor OpenAI reasoning models (e.g.openai/gpt-5*); other models accept onlyauto.- The key also selects the
edenaiembedder, defaultamazon/amazon.titan-embed-text-v2:0(EU-served, cheapest per token here). Change it withREPOWISE_EMBEDDING_MODEL, e.g.google/gemini-embedding-001. - Only models in
EdenAIEmbedder._DIMSare accepted, since a wrong width silently mis-sizes stored vectors; adding one means adding its measured width.
The CLI, repowise serve chat and jobs, and the MCP server resolve provider,
model and base URL the same way; first match wins:
--provider/--modelflags, or a per-request choice in the web UIprovider,model, and<provider>: {base_url: ...}in.repowise/config.yaml- the global default saved from the web UI (
~/.repowise/provider_config.json) REPOWISE_PROVIDER/REPOWISE_MODELand the provider's*_BASE_URLvariable- API key env vars:
ANTHROPIC_API_KEY→OPENAI_API_KEY→OPENROUTER_API_KEY→OLLAMA_BASE_URL→GEMINI_API_KEY→DEEPSEEK_API_KEY→KIMI_API_KEY→EDENAI_API_KEY
- A model picked in the web UI is written to the repo's
config.yaml, so the CLI uses it too. - A local OpenAI-compatible server such as LM Studio:
provider: openaiwithopenai: {base_url: http://localhost:1234/v1}. Loopback URLs need no key. Page material is sized for a 16384-token window, since the server does not report its own; start the server with at least that context, or setcontext_windowto the context length it runs with. A local backend behind LiteLLM is sized the same way. - Since
config.yamlmay be committed, a non-local base URL there gets a key not in.repowise/.envonly after you confirm in Settings orrepowise init. - The repo's Settings page sets all this: the model field lists live models and takes any id, and Test connection checks a base URL before saving.
A provider's block in .repowise/config.yaml names its endpoint, ahead of
the provider's *_BASE_URL variable (order above).
provider: openai
openai: {base_url: http://localhost:1234/v1}| Key | Default | Values | What it does |
|---|---|---|---|
<provider>.base_url |
unset | provider: gemini, anthropic, openai, deepseek, kimi, edenai, ollama, litellm |
Custom http(s) endpoint for a provider (openai.base_url and the like), such as a proxy or a local server. |
The embedder is separate from the LLM provider.
| Embedder | Env var | Notes |
|---|---|---|
gemini |
GEMINI_API_KEY (or GOOGLE_API_KEY) |
Default when the key is present |
openai |
OPENAI_API_KEY |
text-embedding-3-small |
openrouter |
OPENROUTER_API_KEY |
Routed through OpenRouter |
ollama |
OLLAMA_EMBEDDING_MODEL |
Local, no API key |
edenai |
EDENAI_API_KEY |
See Eden AI |
mock |
n/a | No semantic search; default when no key is found |
repowise init --embedder openai
repowise reindex --embedder gemini # switch embedder and rebuild indexResolution, first match wins: --embedder, REPOWISE_EMBEDDER, the
embedder pin in .repowise/config.yaml, the first key present (gemini,
openai, openrouter, ollama, edenai), embedder in ~/.repowise/config.yaml,
then mock. reindex skips a mock pin when a real embedder is found.
- The pin records what built the vector store.
search,serveand MCP read it first and use the environment only when unpinned; otherwise a keyless index would be queried with whatever key is exported, and wider query vectors would match nothing in the narrower table. reindexwrites its embedder back to the pin; otherwise the nextupdatewould write old-width vectors and rebuild the store, discarding the reindex.REPOWISE_EMBEDDING_MODEL,REPOWISE_EMBEDDING_DIMSandREPOWISE_EMBEDDING_TIMEOUTapply to the active embedder; provider-prefixed variants take precedence for theirs.
The gemini embedder supports gemini-embedding-2; its default remains
gemini-embedding-001. To switch an existing index:
export GEMINI_API_KEY="..."
export REPOWISE_EMBEDDER=gemini
export REPOWISE_EMBEDDING_MODEL=gemini-embedding-2
export REPOWISE_EMBEDDING_DIMS=768
repowise reindex --embedder geminiKeep the same model and dimension settings in the environment of update,
serve and the MCP server. Embedding 2 and Embedding 001 use incompatible
vector spaces, even at the same dimension, so switching requires a full
reindex. Restart a running server after switching.
Repowise applies Google's code-retrieval instruction to queries and document
formatting to stored text, and requests a separate vector for each input.
Embedding 2 does not accept task_type. See Google's
embedding instructions.
Keys resolve in order:
- Environment variable
.repowise/.env: saved by interactive setup, loaded automatically, gitignored~/.repowise/provider_config.json: keys saved from the web UI- Interactive prompt during
init, saved to.repowise/.env
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
Anthropic |
OPENAI_API_KEY |
OpenAI or an OpenAI-compatible gateway |
GEMINI_API_KEY / GOOGLE_API_KEY |
Google Gemini |
OPENROUTER_API_KEY |
OpenRouter |
DEEPSEEK_API_KEY |
DeepSeek |
KIMI_API_KEY |
Kimi |
LITELLM_API_KEY |
LiteLLM proxy key |
LITELLM_API_BASE |
LiteLLM proxy base URL |
| Variable | Description |
|---|---|
ANTHROPIC_BASE_URL, GEMINI_BASE_URL, DEEPSEEK_BASE_URL, KIMI_BASE_URL, LITELLM_BASE_URL |
Override that provider's API base URL |
OPENAI_BASE_URL |
Override the OpenAI base URL (vLLM/SGLang, 9router, other compatible endpoints) |
OLLAMA_BASE_URL |
Ollama server (default http://localhost:11434) |
OLLAMA_NUM_PARALLEL |
Ollama requests sent at once (default 1) |
| Variable | Default | Values | What it does | Config key |
|---|---|---|---|---|
REPOWISE_PROVIDER |
unset | Which model service writes docs and answers (anthropic, openai, gemini, ollama, claude_cli and others). Unset: the saved global choice (provider_config.json), then REPOWISE_PROVIDER, then the first provider whose API key is present. | provider (the file wins) |
|
REPOWISE_MODEL |
unset | The model id to use with the provider. Unset: the saved global choice (provider_config.json), then REPOWISE_MODEL, then the provider's default model. | model (the file wins) |
|
REPOWISE_REASONING |
auto |
auto, off, none, minimal, low, medium, high, xhigh, max |
How much the model thinks before writing. | reasoning (this wins) |
REPOWISE_EMBEDDER |
unset | Which embedding service powers semantic search: openai, gemini, ollama, openrouter, edenai, a plugin's, or mock for none. Unset: the first embedder whose API key is present, then the embedder in ~/.repowise/config.yaml, then mock. | embedder (this wins) |
|
REPOWISE_EMBEDDING_MODEL |
unset | The embedding model id. Unset uses the embedder's default. | embedding_model (this wins) |
|
REPOWISE_DOC_MODEL |
unset | A different model just for get_answer write-ups. | ||
REPOWISE_EMBEDDING_DIMS |
unset | > 0 | Force the embedding vector width. | |
REPOWISE_EMBEDDING_DECLARED_DIMS |
unset | > 0 | Vector width an OpenAI-compatible server really returns, when it differs from the width requested. | |
REPOWISE_EMBEDDING_TIMEOUT |
unset | > 0 | Seconds one embedding request may take. Unset uses the embedder's own. | |
REPOWISE_EMBED_DOC_PREFIX |
unset | Text put before each document before embedding (e.g. "passage: "). | ||
REPOWISE_EMBED_QUERY_PREFIX |
unset | Text put before each search query before embedding (e.g. "query: "). | ||
REPOWISE_NO_COST_TRACKING |
off | 1, on, true, yes |
Do not save model cost records to the database. |
| Variable | Description |
|---|---|
OPENAI_, GEMINI_, OPENROUTER_, EDENAI_, OLLAMA_EMBEDDING_TIMEOUT |
That embedder only; wins over the shared variable |
OLLAMA_EMBEDDING_MODEL |
Ollama embedding model; also selects the ollama embedder |
OLLAMA_EMBEDDING_DIMS |
Ollama output dimensions (optional; inferred from the model) |
REPOWISE_EMBEDDING_TIMEOUTunset: 30 seconds forollama, 10 elsewhere. Raise it for a local endpoint: one request embeds a whole batch, and an expired batch shows only asN/N items failed to embed.- With no Ollama or shared timeout set, an Ollama request gets 30s plus 2ms per input character, so long pages on a CPU-only model are not cut off.
- A cold first vector query (
REPOWISE_VECTOR_SEARCH_TIMEOUT_S) pays for the store open, first embed and first ANN probe (past 13s where a warm query takes under a second). Raise the timeout on a slow disk or large wiki; a timeout drops the semantic leg with a warning, leaving full-text hits. - An unparseable timeout warns and keeps the default.
- The
openaiembedder applies the embed prefixes. Set them only for a model trained with them (such asquery:/passage:), then runrepowise reindex: vectors stored before a prefix was set or changed stop matching, with no error.
| Variable | Default | Values | What it does |
|---|---|---|---|
REPOWISE_CLAUDE_CLI_CONCURRENCY |
4 |
>= 1 (clamped) | How many Claude Code CLI calls run at once. |
REPOWISE_CODEX_CLI_CONCURRENCY |
4 |
>= 1 (clamped) | How many Codex CLI calls run at once. |
REPOWISE_COPILOT_CLI_CONCURRENCY |
4 |
>= 1 (clamped) | How many Copilot CLI calls run at once. |
REPOWISE_OPENCODE_CONCURRENCY |
4 |
>= 1 (clamped) | How many OpenCode CLI calls run at once. |
REPOWISE_OLLAMA_NUM_CTX |
unset | > 0 | Context window for Ollama. Unset uses the model's own. |
REPOWISE_CONFIG_DIR |
~/.repowise |
Folder holding the saved global provider choice (provider_config.json). |
REPOWISE_OLLAMA_NUM_CTX sizes page material to it. Unset: the Modelfile's
num_ctx, else 16384.
| Variable | Default | Values | What it does |
|---|---|---|---|
REPOWISE_FORGE_HOSTS |
unset | Comma-separated host=forge pairs, added to forges.hosts. | |
REPOWISE_PARSE_WORKERS |
unset | > 0 | Parallel parse workers for init and update. Unset sizes to the machine. |
REPOWISE_PARSE_TIMEOUT_S |
60 |
>= 0 | Seconds one file may take to parse; 0 turns the limit off. |
REPOWISE_GIT_WORKERS |
unset | > 0 | Parallel git processes while indexing history. Unset sizes to the machine. |
REPOWISE_GIT_INDEX_TIMEOUT_S |
120 |
> 0 | Seconds one file's git history lookup may take. |
REPOWISE_GIT_SCOPE |
module |
Set to repo to index the whole repository's history when indexing one module. | |
REPOWISE_GIT_WINDOW_ANCHOR |
unset | Set to now to measure git windows (recent churn, prior defects, blame age) from today instead of from the indexed commit's date. | |
REPOWISE_GRAMMAR_DIR |
unset | Folder of pre-downloaded language grammars, for offline machines. | |
REPOWISE_WORKTREE_FALLBACK |
on | on unless 0, false, no, off |
Let a git worktree read its main checkout's index; 0 turns it off. |
REPOWISE_INDEX_INFORMATION_FLOOR |
0 |
>= 0 | Least characters of real prose a wiki page needs to be found by semantic search. Shorter pages stay readable, just not in that search. 0 is off. |
REPOWISE_PARSE_WORKERS defaults to the CPU count capped at 8, never above
the files to parse. Each worker holds about 50 MB; above 8 is not measurably
faster.
| Variable | Default | Values | What it does |
|---|---|---|---|
REPOWISE_ANSWER_TIMEOUT_S |
unset | 0-600 (clamped) | Seconds get_answer may spend writing one answer. Unset uses the provider's own. |
REPOWISE_EMBED_TIMEOUT_S |
8 |
0-120 (clamped) | Seconds a get_answer question may wait to be embedded. |
REPOWISE_VECTOR_SEARCH_TIMEOUT_S |
30 |
0-120 (clamped) | Seconds one semantic search may take. |
REPOWISE_WORKSPACE_CONCURRENCY |
4 |
1-64 (clamped) | How many repos one workspace query asks at once, never more than the server keeps open. |
REPOWISE_WORKSPACE_REPO_TIMEOUT_S |
60 |
0-300 (clamped) | Seconds each repo gets in a workspace query. |
REPOWISE_MCP_NO_WATCHDOG |
off | 1, true, yes |
Keep the MCP server running when the app that started it exits. |
REPOWISE_ANSWER_TIMEOUT_S defaults to 60s for remote API providers, 120s
for ollama and litellm, and 50s for agent CLI providers (claude_cli,
codex_cli, copilot_cli, opencode). Raise it for a slow model, lower it to
fail fast. Your MCP client's own tool timeout sits underneath: a higher value
yields a client error instead of Repowise's "synthesis exceeded its budget".
REPOWISE_MCP_NO_WATCHDOG 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).
Each variable sets its hooks: key for one session.
| Variable | Default | Values | What it does | Config key |
|---|---|---|---|---|
REPOWISE_HOOK_READ_SKELETON |
off | 1, on, true, yes |
Serve a whole-file Read of a large indexed file as its outline. | hooks.read_skeleton (this wins) |
REPOWISE_HOOK_READ_REREAD |
off | 1, on, true, yes |
Serve an unchanged repeat Read as a short notice. | hooks.read_reread (this wins) |
REPOWISE_HOOK_SEARCH_DIGEST |
off | 1, on, true, yes |
Serve a search that floods many files as a digest. | hooks.search_digest (this wins) |
REPOWISE_HOOK_COVERAGE_REINGEST |
off | 1, on, true, yes |
Re-read coverage reports after an agent's full test run. | hooks.coverage_reingest (this wins) |
REPOWISE_HOOK_MEASURE |
off | 1, on, true, yes |
On update, check locally whether agents acted on each hook firing. | hooks.measure (this wins) |
REPOWISE_HOOK_HEALTH_GATE |
off | 1, on, true, yes |
Block an agent's commit or push that fails repowise health check. | hooks.health_gate (this wins) |
REPOWISE_HOOK_READ_SKELETON_MODE |
smart |
smart, plus |
What a served outline keeps: smart, or plus to keep all code outside function bodies. | hooks.read_skeleton_mode (this wins) |
| Variable | Default | Values | What it does |
|---|---|---|---|
REPOWISE_API_KEY |
unset | Shared secret that protects the API and the MCP HTTP server; needed for requests from other machines. | |
REPOWISE_HOST |
127.0.0.1 |
Address the servers listen on. 0.0.0.0 without an API key prints a warning. | |
REPOWISE_PORT |
7337 |
1-65535 | Port for the API server. |
REPOWISE_API_URL |
http://localhost:7337 |
Where the web UI finds the API. repowise serve sets it. | |
REPOWISE_NO_OPEN |
off | 1, on, true, yes |
Do not open a browser when repowise serve starts. |
REPOWISE_DB_URL |
unset | Database to use instead of the repo's SQLite file, for example Postgres. | |
REPOWISE_DATABASE_URL |
unset | Older name for REPOWISE_DB_URL, read when that is unset. | |
REPOWISE_POSTGRES_KEEPALIVE |
off | 1, on, true, yes |
Send server-side TCP keepalive settings and a command timeout on asyncpg connections. Leave off behind a pooler that rejects startup parameters. |
REPOWISE_POSTGRES_KEEPALIVES_IDLE |
60 |
>= 1 | Seconds idle before the server's first keepalive probe, when REPOWISE_POSTGRES_KEEPALIVE is on. |
REPOWISE_POSTGRES_KEEPALIVES_INTERVAL |
15 |
>= 1 | Seconds between keepalive probes, when REPOWISE_POSTGRES_KEEPALIVE is on. |
REPOWISE_POSTGRES_KEEPALIVES_COUNT |
4 |
>= 1 | Unanswered keepalive probes before the server drops the connection, when REPOWISE_POSTGRES_KEEPALIVE is on. |
REPOWISE_POSTGRES_COMMAND_TIMEOUT |
300 |
>= 1 | Seconds one database command may run, when REPOWISE_POSTGRES_KEEPALIVE is on. |
REPOWISE_CORS_ORIGINS |
unset | Comma-separated web origins allowed to call the API from a browser. Unset allows any origin without credentials. | |
REPOWISE_PUBLIC_URL |
unset | Public https address of the MCP server behind a proxy. | |
REPOWISE_TOKENS_FILE |
~/.repowise/tokens.yaml |
File of scoped access tokens for the server. | |
REPOWISE_GITHUB_WEBHOOK_SECRET |
unset | Secret that verifies GitHub webhooks. | |
REPOWISE_GITLAB_WEBHOOK_TOKEN |
unset | Token that verifies GitLab webhooks. | |
REPOWISE_GITEA_WEBHOOK_SECRET |
unset | Secret that verifies Gitea webhooks. | |
REPOWISE_PLUGINS |
unset | Comma-separated extra plugin modules to load (module or module:attr). |
- Without
REPOWISE_API_KEYthe server answers local callers only and refuses other hosts with 403. REPOWISE_HOSTis the default host forrepowise mcpover HTTP/SSE;repowise servesets it from--host.- The MCP SSE port is the
repowise mcp --portflag (default7338).
Anonymous usage telemetry is on by default (opt-out). DO_NOT_TRACK with
any truthy value turns it off (cross-tool convention).
| Variable | Default | Values | What it does |
|---|---|---|---|
REPOWISE_OFFLINE |
off | 1, on, true, yes |
Block repowise's own network calls: telemetry, update checks, plan status, agent sign-in checks and decision sync. |
REPOWISE_TELEMETRY_DISABLED |
off | 1, on, true, yes |
Turn off anonymous usage telemetry. |
REPOWISE_TELEMETRY_DEBUG |
off | 1, on, true, yes |
Print the telemetry payload instead of sending it. |
REPOWISE_NO_HINTS |
off | 1, on, true, yes |
Hide repowise.dev tips in the CLI and web UI. |
REPOWISE_NO_SAVE_KEY |
off | on when set, unless 0, false, no |
Do not copy an API key into the repo's .repowise/.env. For CI and shared machines. |
REPOWISE_CHANGELOG |
unset | A changelog file for the what's-new check to read instead of the bundled one. |
REPOWISE_OFFLINE also turns off the PyPI release check and the init probe
of signed-in agent CLIs (DO_NOT_TRACK and REPOWISE_TELEMETRY_DISABLED turn
those off too).
| Variable | Default | Values | What it does |
|---|---|---|---|
REPOWISE_SKIP_EDITOR_SETUP |
off | on when set, unless 0, false, no |
Do not register repowise in editors' and agents' global config. |
REPOWISE_SKIP_EDITOR_SETUP makes init skip machine-wide editor config
(Claude Code / Claude Desktop MCP entry, Claude Code hooks, distill
rewrite-hook offer), like init --no-editor-setup
(CLI_REFERENCE.md). Use it for CI,
sandboxes and benchmark runs. Project files (.repowise/mcp.json,
CLAUDE.md, Codex config) are still written.
| Variable | Default | What it does |
|---|---|---|
REPOWISE_GITLAB_TOKEN |
unset | GitLab access token (api scope) that posts the CI summary as a merge-request note. |
REPOWISE_GITLAB_TOKEN is read by repowise ci-summary --gitlab-note; set it
as a masked CI/CD variable (CI.md).
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:
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.
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 |
Repowise honours .gitignore (git's gitwildmatch format), including nested
.gitignore files, so a monorepo or workspace package's own build exclusions
(dist/, coverage/, generated bundles) apply without repeating them at the
root.
repowise init -x vendor/ -x "*.generated.ts" -x proto/ -x "**/*.pb.go"--exclude/-xpatterns are saved toexclude_patternsand reused byupdate.- A
.repowiseIgnorefile (gitignore syntax) at the root or in any subdirectory excludes without touching.gitignore. - Always excluded:
.git/,.repowise/,node_modules/,__pycache__/,*.pyc,.venv/, binary files, lockfiles, minified assets. --skip-tests(test files) and--skip-infra(Dockerfiles, Makefiles, shell scripts) apply only to their run; pass them again each time.
Submodule directories are excluded by default; Repowise finds them in
.gitmodules.
repowise init --include-submodulesThe flag is not written to config.yaml; a workspace records it in
state.json.
For team deployments or larger repos:
export REPOWISE_DB_URL="postgresql+asyncpg://user:pass@localhost:5432/repowise"
repowise initREPOWISE_DATABASE_URL is a still-honored alias. Alembic manages the schema.
For a direct PostgreSQL connection using asyncpg, enable session keepalive probes and a bounded wait for commands:
export REPOWISE_POSTGRES_KEEPALIVE=1
# Optional overrides (seconds, except COUNT):
export REPOWISE_POSTGRES_KEEPALIVES_IDLE=60
export REPOWISE_POSTGRES_KEEPALIVES_INTERVAL=15
export REPOWISE_POSTGRES_KEEPALIVES_COUNT=4
export REPOWISE_POSTGRES_COMMAND_TIMEOUT=300| Variable | Default when enabled | Meaning |
|---|---|---|
REPOWISE_POSTGRES_KEEPALIVE |
Off unless set to 1, true, yes, or on (case-insensitive) |
Enables all four settings below |
REPOWISE_POSTGRES_KEEPALIVES_IDLE |
60 |
Seconds of inactivity before the server's first TCP keepalive probe |
REPOWISE_POSTGRES_KEEPALIVES_INTERVAL |
15 |
Seconds between subsequent probes |
REPOWISE_POSTGRES_KEEPALIVES_COUNT |
4 |
Unanswered probes before the server considers the peer dead |
REPOWISE_POSTGRES_COMMAND_TIMEOUT |
300 |
asyncpg's per-command timeout in seconds; raise it for legitimate long-running statements or bulk writes |
Values must be positive integers; invalid values raise an error naming the
variable when the engine is created. They are read for each new engine. With
the switch off (including 0 or false), all four overrides are ignored and
the existing behavior is preserved: server keepalive defaults and no added
command timeout. SQLite and explicitly selected drivers other than asyncpg
ignore these variables.
The tcp_keepalives_* values are sent in asyncpg server_settings as startup
parameters. Leave this disabled for PgBouncer or hosted poolers unless the
pooler supports these parameters (for example, via PgBouncer's
ignore_startup_parameters). A pooler may reject them, and ignoring them does
not apply them to the backend; configure backend keepalive separately in that
case. Repowise does not auto-detect poolers or retry without the parameters.
The defaults let the server detect a dead TCP peer in roughly two minutes
(60 + 15 × 4 seconds, subject to OS support). They configure the server's
probes, not the client's socket; a tunnel's peer may only be the tunnel
endpoint, so SSH keepalive must be configured separately. The command timeout
bounds an active command, not an idle session, and does not guarantee recovery
of an interrupted transaction. pool_pre_ping still checks connections at
checkout.
A multi-repo workspace is configured at its root.
Beside the repo list it takes repos[].tags, conformance:, and a
contracts: block that tunes cross-repo contract detection.
Free-form tags that group services in conformance rules:
repos:
- path: web
alias: frontend
tags: [ui, edge]
- path: services/db
alias: db
tags: [data]Allow/deny dependency rules checked by repowise workspace check and the
Conformance view (Architecture Conformance).
conformance:
rules:
- source: frontend
target: db
allow: false
description: "..."
- source: "tag:ui"
target: "tag:data"
- source: "*"
target: legacy-payments| Field | Default | Meaning |
|---|---|---|
source |
required | Dependent side: * (any service), tag:<name> (repos with that tag), or a glob over node id / repo alias / display name |
target |
required | Depended-upon side, same forms |
allow |
false |
false denies (a match is a violation); true whitelists an otherwise-denied edge |
description |
"" |
Rationale shown in reports |
Rules apply only to structural edges (HTTP, gRPC, socket, event, package, db), never to behavioral co-change.
| Old name | Current name | Notes |
|---|---|---|
max_pages_pct |
coverage_pct |
Internal alias, still read |
REPOWISE_DATABASE_URL |
REPOWISE_DB_URL |
Still honored |