Queryable, token-economical project & code index for the pi coding agent.
Tip
Codewalker turns your codebase into a searchable, FTS-backed knowledge base — zero LLM calls from the extension itself. Enrichment, analysis, and review are agent-driven via tools.
[\](https://www.npmjs.com/package/@aprimediet/codewalker) [\](https://github.com/aprimediet/pi-codewalker/actions)    
%5C%5D(https://www.npmjs.com/package/@aprimediet/codewalker){kind=link}
Codewalker builds and maintains a full-text search index of your project's code, library APIs, conceptual notes, and analysis findings — all powered by SQLite FTS5 with BM25 ranking.
It's a pi extension that registers two things:
| Interface | What it does |
|---|---|
codewalker_query tool |
Search symbols, libraries, notes, and findings. Returns compact facts: name, kind, file:line, summary. |
/codewalker command |
Human CLI: scan, sync, enrich, analyze, review, findings, conventions, glossary, decisions, libs, lib, help. |
Note
Codewalker makes zero model/provider API calls. Enrichment and best-practice analysis are agent-driven — the tool just provides the data; the agent decides what to do.
┌─────────────────────────────────────────────────┐
│ Extension entry point (index.ts) │
│ • codewalker_query tool │
│ • /codewalker command with 12 subcommands │
└──────────────────────┬──────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌──────────▼──────────┐ ┌──────────▼──────────┐
│ Query Layer │ │ Index Layer │
│ FTS5 + BM25 │ │ scan / sync │
│ code | libs | │ │ ctags primary │
│ notes | analysis │ │ regex fallback │
└──────────┬──────────┘ └──────────┬──────────┘
│ │
┌──────────▼────────────────────────▼──────────┐
│ SQLite (better-sqlite3) │
│ • symbols + symbols_fts (code index) │
│ • libraries + lib_symbols_fts (API index) │
│ • notes_fts (glossary/decisions/conventions) │
│ • analysis_fts (coverage/debt/practice) │
│ • All FTS sync via triggers (trigger-only) │
└───────────────────────────────────────────────┘
- Cards as source of truth — analysis writes markdown cards; DB is reconstructable from cards at any time
- Trigger-only FTS —
*_ftstables are append-only; base tables drive the index via SQLite triggers - Lazy + capped enrichment — default 40-symbol cap, bare paths rejected outright
- Report-don't-gate — review never blocks; it's report-only
- Zero model calls — no LLM calls from the extension. Enrichment is agent-driven via tools.
- ctags extraction — primary path, with regex fallback when ctags is unavailable
- Library API indexing —
.d.tsexport extraction (7 forms + re-exports), dependency discovery - FTS5 search — BM25-ranked full-text search across code, libraries, notes, and findings
codewalker_enrichtool — write a one-line semantic summary to any symbol's card and DB index/codewalker enrich <path>— select unenriched symbols under a path, write summaries- Lazy + capped — default 40-symbol cap, agent decides which to enrich
- Glossary terms — conceptual definitions, searchable via FTS
- Decision notes — architecture decisions with rationale
- Convention notes — coding conventions and standards
codewalker_notetool — write a glossary term, decision, or convention
- Coverage analysis — parses
lcov.infoandcoverage-final.json - Debt scanning — TODO/FIXME/HACK/XXX markers,
@ts-ignoreusage, oversized files, long functions - Best-practice review — agent-driven review against conventions + decisions (capped at 25 files)
codewalker_findingtool — write coverage, debt, or practice findings
- Node.js 20+
- npm (or pnpm/yarn)
- ctags (optional, regex fallback works without it)
pi install npm:@aprimediet/codewalkerFull (re)build of the code index. Scans source files, extracts symbols, indexes libraries.
Git-anchored incremental update. Only re-indexes files that changed since the last commit.
Search the code index. Returns compact facts ranked by BM25.
Select unenriched symbols under <path> and write summaries. Optional --max=N cap.
Mechanical analysis: reads coverage artifacts if present, scans debt markers. Reports counts.
Agent-driven best-practice review against conventions + decisions. Lazy, scoped, capped at 25 files.
Search analysis findings. Optional --kind=coverage|debt|practice filter.
Search coding conventions.
Search glossary terms.
Search decision notes.
Index all direct dependencies. --dev includes devDependencies.
Search a specific library's API symbols.
# Search for functions in a specific file
codewalker_query --query "fetch" --kind function --limit 5
# Search library APIs
codewalker_query --query "useState" --source libs
# Search notes and findings together
codewalker_query --query "error handling" --source allSchema version 4. All FTS indexes are trigger-only — base table DML automatically maintains the search index.
| Table | Purpose |
|---|---|
files |
Indexed file tracking (path, lang, sha) |
symbols |
Source code symbols |
symbols_fts |
FTS5 virtual table for symbols |
libraries |
Direct dependency metadata |
lib_symbols |
Library API symbols |
lib_symbols_fts |
FTS5 for lib_symbols |
notes |
Glossary/decision/convention bridge |
notes_fts |
FTS5 for notes |
analysis |
Coverage/debt/practice findings |
analysis_fts |
FTS5 for analysis |
meta |
Key/value metadata (schema_version) |
- Identity: aditya.prima aprimediet@gmail.com
- Version: 1.4.1
- License: MIT
- Documentation:
prompts/codewalker.md(agent skill prompt),skills/codewalker/SKILL.md(agent guidance) - Deferred features (v1.2+ candidates): SonarQube/OWASP integration, two-model second brain
- Publishing: Use
NPM_TOKENenv var; granular token with "bypass 2fa" enabled. Usenpm publish --userconfig /tmp/npmrcto isolate token. - CDN lag: After publishing,
npm viewmay 404 for 2-5 seconds. Wait and retry.