Fovea CLI

Token-budgeted repository navigation for agent shells and CI: a cross-language code graph with heat-ranked, progressively disclosed context.

Install

Requires Node.js 20+. No Pi installation, TypeScript loader, or Bend compiler is needed.

npm install -g @monotykamary/fovea
# or: bun add -g @monotykamary/fovea

The command is fovea, regardless of the package's scoped name.

The optional @ast-grep/cli dependency provisions the parser for most source languages. An ast-grep on PATH takes precedence over the packaged copy; FOVEA_AST_GREP=/path/to/sg overrides both. Bend-only and config/protocol-only repositories work without it. If optional dependencies were omitted, install ast-grep separately before analyzing languages that require it.

Usage

fovea sketch /path/to/repo 900
fovea focus /path/to/repo "/v1/messages" 800
fovea impact /path/to/repo --base main 1200
fovea rules /path/to/repo
fovea status /path/to/repo

The trailing number is the output token budget. Each CLI invocation is stateless; use the Pi extension for focus and dwell across an interactive session.

Agent skill

The standalone package includes skills/fovea/SKILL.md, a portable fovea skill with navigation, impact, coverage, and stateless CLI workflows. Register that directory with your agent's skill loader, or copy it into the agent's skills directory. Installing the executable alone does not register the skill.

For a global npm install, the skill directory is $(npm root -g)/@monotykamary/fovea/skills/fovea. It is also available in the source repository. The separate pi-fovea skill covers Pi extension tools and session behavior.

Pi extension

Install the separate pi-fovea package in Pi:

pi install npm:pi-fovea

Both distributions share the same engine and release version. The legacy npm install -g pi-fovea also provides fovea; choose only one global package to avoid competing for the same executable. Installing the extension through Pi and this CLI globally is supported.

See the project documentation for language coverage and configuration. Proof sources and generated-kernel receipts are included for auditing, not required at runtime.