repo-wiki¶
repo-wiki reads a repository's source and writes a local, searchable wiki
of its modules and symbols (functions, classes and methods). It also projects
that source into AKMS code mirrors, which is what the default builtin
code-mirror provider runs.
It is part of the akms package, as the module akms.repo_wiki, and runs on
your machine: the command makes no network calls and calls no language model.
The one exception is in your browser: the graph viewer page loads its
drawing library from a CDN. See Privacy and security.
Ways to run it¶
All three run the same command with the same subcommands and flags.
| Invocation | Notes |
|---|---|
repo-wiki <subcommand> |
Console script installed with akms. |
akms wiki <subcommand> |
Passes everything after wiki through. The root --repo becomes --repo-root; a --repo-root given after wiki takes precedence. |
python -m akms.repo_wiki <subcommand> |
The form the builtin provider uses. |
--repo-root (default .) selects the repository to operate on. It goes
before the subcommand:
Install¶
repo-wiki needs nothing beyond akms itself, which requires Python 3.12:
Python sources are always supported. Other languages are opt-in in the configuration and need extra packages:
| Language | Needs | Install |
|---|---|---|
| Python | nothing extra | — |
| Rust | tree-sitter grammar | pip install "akms[rust]" |
| C++ | tree-sitter grammar, or the doxygen program on PATH |
pip install "akms[cpp]" |
| Julia | tree-sitter grammar | pip install "akms[julia]" |
| all three tree-sitter languages | pip install "akms[multilang]" |
Quote the argument: zsh otherwise treats the brackets as a glob. See Installation for the other extras.
Subcommands¶
| Subcommand | What it does |
|---|---|
init |
Creates .repo_wiki/ with config.yaml, SPEC.md and overlays/. |
scan |
Lists the files that would be processed and counts the skipped ones. |
parse <path> |
Parses one Python file and prints its symbols. |
build |
Scans, parses and writes the wiki pages, local summaries and the search index. Also accepts --changed-only, --force, --no-summaries, --no-index and --json. |
index |
Updates the search index from the generated pages and your overlays. --query prints matching entries as JSON. |
query <question> |
Searches the index and prints ranked results with source citations. |
summarize |
Generates local summary pages. --changed-only, --force and --symbol narrow or force the run. |
export-akms |
Writes AKMS code mirrors. See AKMS export. |
stats |
Prints the number of tracked files and generated pages. |
context <symbol> |
Shows a symbol's definition, callers, callees and module imports. See context. |
impact <symbol> |
Lists what depends on a symbol, by depth, with a risk level. See impact. |
changes |
Maps a git diff to the symbols it touches and their direct callers. See changes. |
flows |
Lists execution flows: entry points followed down their confident calls. See flows and flow. |
flow <flow> |
Shows one execution flow as a call tree. See flows and flow. |
hooks <action> |
install, uninstall or status of the opt-in git hooks that refresh the graph in the background after git changes the tree. See hooks. |
graph [input] |
Serves an interactive viewer for the symbol graph on 127.0.0.1:8765. |
clean |
Not implemented: prints a message and removes nothing. |
Run repo-wiki <subcommand> --help for the flags of each.
In this section¶
- Quickstart: initialize, build, query, and export a mirror.
- Configuration: every key in
.repo_wiki/config.yaml. - Generated files: what is written where, and what to commit.
- Privacy and security: what is scanned and what is excluded.
- AKMS export:
export-akmsflags, output and locking. - context, impact and changes: code intelligence over the symbol graph, for exploring a symbol, checking who depends on it before an edit, and checking a diff before a commit.
- flows and flow: static execution flows from console scripts,
__main__blocks, CLI commands and uncalled public functions, and theflows.jsonformat. - hooks: opt-in git hooks that keep the graph and flows fresh.
- Reading impact and risk: depths, confident and possible links, the risk rule, and what the graph cannot see.