@aprimediet/codewalker

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)    

Overview

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.

Architecture

┌─────────────────────────────────────────────────┐
│  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)    │
└───────────────────────────────────────────────┘

Design Principles

• Cards as source of truth — analysis writes markdown cards; DB is reconstructable from cards at any time
• Trigger-only FTS — *_fts tables 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.

Features

Tier 1 — Code Indexing

• ctags extraction — primary path, with regex fallback when ctags is unavailable
• Library API indexing — .d.ts export extraction (7 forms + re-exports), dependency discovery
• FTS5 search — BM25-ranked full-text search across code, libraries, notes, and findings

Tier 2 — Enrichment

• codewalker_enrich tool — 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

Tier 3 — Notes & Knowledge

• Glossary terms — conceptual definitions, searchable via FTS
• Decision notes — architecture decisions with rationale
• Convention notes — coding conventions and standards
• codewalker_note tool — write a glossary term, decision, or convention

Tier 4 — Analysis

• Coverage analysis — parses lcov.info and coverage-final.json
• Debt scanning — TODO/FIXME/HACK/XXX markers, @ts-ignore usage, oversized files, long functions
• Best-practice review — agent-driven review against conventions + decisions (capped at 25 files)
• codewalker_finding tool — write coverage, debt, or practice findings

Getting Started

Prerequisites

• Node.js 20+
• npm (or pnpm/yarn)
• ctags (optional, regex fallback works without it)

Install

pi install npm:@aprimediet/codewalker

Command Reference

/codewalker scan

Full (re)build of the code index. Scans source files, extracts symbols, indexes libraries.

/codewalker sync

Git-anchored incremental update. Only re-indexes files that changed since the last commit.

/codewalker query <text>

Search the code index. Returns compact facts ranked by BM25.

/codewalker enrich <path>

Select unenriched symbols under <path> and write summaries. Optional --max=N cap.

/codewalker analyze [path]

Mechanical analysis: reads coverage artifacts if present, scans debt markers. Reports counts.

/codewalker review <path>

Agent-driven best-practice review against conventions + decisions. Lazy, scoped, capped at 25 files.

/codewalker findings [query]

Search analysis findings. Optional --kind=coverage|debt|practice filter.

/codewalker conventions [query]

Search coding conventions.

/codewalker glossary [query]

Search glossary terms.

/codewalker decisions [query]

Search decision notes.

/codewalker libs [--dev]

Index all direct dependencies. --dev includes devDependencies.

/codewalker lib <pkg> [query]

Search a specific library's API symbols.

Query Examples

# 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 all

Database Schema

Schema 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)

Additional Notes

• 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_TOKEN env var; granular token with "bypass 2fa" enabled. Use npm publish --userconfig /tmp/npmrc to isolate token.
• CDN lag: After publishing, npm view may 404 for 2-5 seconds. Wait and retry.

Resources

• Pi coding agent documentation
• Pi extension examples