error-nav

Error messages as navigation for Claude Code.

A PostToolUse hook that intercepts failed Bash commands, matches stderr against known error patterns, and injects actionable hints into Claude's context. Instead of guessing for 3 iterations, Claude gets told exactly what to do.

Inspiration

Inspired by this r/LocalLLaMA post by u/MorroHsu (former Manus backend lead), specifically the concept of error messages as navigation — where every error tells the agent not just what went wrong, but what to do instead. The full design philosophy is described in the post: progressive --help discovery, navigational error messages, and consistent output format as three heuristic techniques that guide an AI agent.

Also inspired by altRAG's approach to developer tooling: installable, zero-dep, one setup command, deterministic retrieval instead of probabilistic guessing.

Install

# Global — works in every project (recommended)
npx error-nav setup --global

# Per-project only
npx error-nav setup

That's it. No config, no API keys, no dependencies.

What Happens

1. You (or Claude) run a Bash command that fails
2. The PostToolUse hook fires automatically
3. check-error.js matches the error output against 27 built-in patterns
4. If matched, an [error-nav] hint is injected into Claude's context
5. Claude follows the hint instead of guessing

Before

$ npm install
→ ENOENT package.json
→ Claude tries: cd .., ls, find . -name package.json, npm init...
→ 3 wasted iterations

After

$ npm install
→ ENOENT package.json
→ [error-nav] No package.json found. Run `ls` to check cwd.
→ Claude runs ls, finds the right directory
→ 1 iteration

Built-in Patterns (27)

| Category | Count | Examples | |----------|-------|---------| | npm/node | 7 | ENOENT package.json, peer deps, ESM/CJS mismatch, port in use | | Python/pip | 5 | externally-managed-environment, ModuleNotFoundError, venv missing | | Git | 4 | not a repo, merge conflict, push rejected, detached HEAD | | TypeScript | 3 | cannot find module, tsconfig not found, type errors | | Docker | 3 | daemon not running, not installed, port conflict | | General | 5 | command not found, permission denied, disk full, connection refused |

Project-Specific Patterns

Add patterns for your project's unique errors in .error-nav.json at the project root:

{
  "patterns": [
    {
      "id": "our-db-migration",
      "regex": "relation \"\\w+\" does not exist",
      "hint": "Table missing. Run `npm run db:migrate` to apply pending migrations."
    },
    {
      "id": "our-env-missing",
      "regex": "STRIPE_SECRET_KEY.*undefined",
      "hint": "Missing env var. Copy .env.example to .env and fill in values."
    }
  ]
}

Project patterns are checked first and override built-in patterns.

Commands

error-nav setup              # install for this project
error-nav setup --global     # install globally (all projects)
error-nav uninstall          # remove from this project
error-nav uninstall --global # remove globally
error-nav list               # show all active patterns
error-nav test "error text"  # test pattern matching

How It Works

error-nav installs a Claude Code PostToolUse hook on the Bash tool. When a command fails:

1. The hook receives tool_response (the command output) as JSON on stdin
2. Quick-checks for error signal keywords (error, fail, denied, not found, etc.)
3. Matches against patterns: project .error-nav.json first, then built-in builtin.json
4. Returns { "additionalContext": "[error-nav] hint..." } on first match
5. Returns {} if no match (never blocks, never crashes)

Global install

• Hook files: ~/.claude/error-nav/
• Config: ~/.claude/settings.json
• Works in every project automatically

Per-project install

• Hook files: .claude/error-nav/
• Config: .claude/settings.local.json
• Only works in that project

Pattern Format

{
  "id": "unique-id",
  "category": "npm",
  "regex": "ENOENT.*package\\.json",
  "flags": "i",
  "hint": "No package.json found. Run `ls` to check cwd."
}

• id: unique identifier
• category: grouping (optional, for list display)
• regex: JavaScript regex pattern
• flags: regex flags (default: "i" for case-insensitive)
• hint: the navigation text injected into Claude's context

Design Principles

• Zero dependencies — Node.js only (guaranteed by Claude Code)
• Never crash — returns {} on any internal error, Claude proceeds normally
• Fast exit on success — skips pattern matching if output has no error signals
• Deterministic — regex matching, not probabilistic. Debuggable with error-nav test
• Project patterns override built-in — your project knows its errors best

License

MIT