@lucas-bur/pix

Lightweight local semantic project indexer. Zero external services, 100% local and offline. Installs as a devDependency and provides agent-ready structured JSON output.

Quick Start

npm install --save-dev @lucas-bur/pix
pix init
pix index
pix query "authentication middleware"

Commands

| Command | Description | JSON flag | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------- | | pix init | Create .pix/config.json with defaults | --json | | pix index | Scan, chunk, embed, and store project files | --json | | pix query "<text>" [flags] | Semantic search via cosine similarity (--top, --context-lines, --ignore-path, --only-path, --max-characters, --no-content) | --json | | pix status | Show index statistics | --json | | pix reset | Delete index files (chunks + vectors) | --json |

All commands support --json for structured output on stdout — ideal for piping to AI agents.

Agent-Ready Output

$ pix status --json
{"chunks":59,"files":37,"model":"Xenova/all-MiniLM-L6-v2","lastIndex":1715030400000,"totalLines":1260,"byteSize":16128}

Errors use the same structured format:

{
  "error": true,
  "code": "CONFIG_NOT_FOUND",
  "message": "No .pix/config.json found",
  "cause": "..."
}

Architecture

pix follows hexagonal architecture (ports and adapters) with three layers:

• Domain (src/domain/) — Pure types, entities, port declarations
• Application (src/application/) — Use cases orchestrating business logic
• Infrastructure (src/services/) — Concrete adapters (filesystem, ONNX models, gitignore-based scanning)

See CONTEXT.md for architecture decisions and docs/adr/ for decision records.

Quality

• vp check — Format, lint, type-check
• vp test — Unit and integration tests
• vp run lint:fallow — Dead code, duplication, complexity analysis

License

MIT