# @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.

<!-- prettier-ignore -->

\[!\[NPM version\](https://img.shields.io/npm/v/@aprimediet/codewalker.svg)\](https://www.npmjs.com/package/@aprimediet/codewalker)
\[!\[Build Status\](https://github.com/aprimediet/pi-codewalker/actions/workflows/build-test.yml)\](https://github.com/aprimediet/pi-codewalker/actions)
!\[Node version\](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
!\[TypeScript\](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)
!\[License\](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)
!\[Pi package\](https://img.shields.io/badge/pi-extension-blue?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NCA0NCI+PHBhdGggZD0iTTEyIDJMNiA2djE2LjM0TDExLjY3IDMyTDEyIDM0LjM0TDEyLjMzIDM0TDE3IDMzLjY2bDQuMzQgLjM0TDE4IDM0bDQuMzQtLjM0TDIwIDM0LjM0TDE5LjY3IDMyTDE2IDYgTDEyIDJ6IiBmaWxsPSIjYjIyMWJhIi8+PC9zdmc+)

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

```bash
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

```bash
# 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](https://github.com/earendil-works/pi-coding-agent)
- [Pi extension examples](https://github.com/earendil-works/pi-coding-agent/tree/main/examples)