CLAWNAV — File Intelligence for OpenClaw Agents

Made by Hashi AI Dev — Built for OpenClaw agents who need to navigate, understand, and refactor codebases at scale.

CLAWNAV is a local-first MCP server that gives agents semantic file search, project awareness, and intelligent rename — so you can find code by what it does, not just by name. It runs entirely offline using SQLite vectors and ONNX embeddings, with zero external dependencies after install.

Build from Source

git clone https://github.com/Hashi-Ai-Dev/clawnav.git && cd clawnav
pnpm install && pnpm run build
clawnav init
clawnav search "auth token refresh"

(Once published to npm, npm install -g clawnav will also work.)

All Tools

search — Hybrid Search

Full-text + semantic search across your codebase. Best for finding code related to a concept.

clawnav search "session token refresh logic"

[score:0.891] session.ts
  async refreshToken() { const sid = await getSessionId(); ...
  Signals: BM25: 0.82 | Sem: 0.94 | Ngram: 0.71
  Matched: "token", "refresh"

find — Semantic File Discovery

Find files by their purpose, not keywords. Asks "what is this file about?"

clawnav find "payment processing"

[score:0.91] stripe.ts
  BM25: 0.45 | Sem: 0.92
[score:0.78] payment.ts
  BM25: 0.61 | Sem: 0.74

read — Contextual File I/O

Read file contents with metadata (size, line count, last modified).

Tool call:

{ "path": "src/auth/session.ts", "lines": 80 }

Output:

File: src/auth/session.ts
Size: 2847 bytes | Lines: 94
Modified: 2026-04-10T14:32:00.000Z

async refreshToken() {
  const sid = await getSessionId();
  ...

write — Write with Directory Creation

Create or overwrite files. Can auto-create parent directories.

Tool call:

{ "path": "src/new-file.ts", "content": "export const foo = 1;", "createDirs": true }

Output:

Written: src/new-file.ts (22 bytes)

audit — Query Clawnav's Memory

Query what clawnav knows about any indexed file: purpose, contributors, git history, and chunk summary. Reads from clawnav's persistent ~/.clawnav_memory/ store — no LLM call needed.

CLI:

clawnav audit src/auth/session.ts

Tool call:

{ "path": "src/auth/session.ts" }

Output:

{
  "path": "src/auth/session.ts",
  "purpose": "Handle user session lifecycle — create, validate, refresh, revoke",
  "contributors": ["Hashi Dev Agent", "swe-agent"],
  "lastModified": "2026-04-16T11:35:34.124Z",
  "chunkSummary": "#!/usr/bin/env node\nimport { Request } from 'express';\n...")
  "history": [
    "8ec7425 — fix: token refresh race (Hashi Dev Agent, 2026-04-16)",
    "3f1a9b2 — feat: add session revocation (swe-agent, 2026-04-10)"
  ],
  "hasObservations": true
}

observations — List All Indexed Files

List every file clawnav has in memory. Filter by glob pattern or contributor name.

CLI:

clawnav observations --pattern="*.ts" --contributor="Hashi" --limit=20

Tool call:

{ "pattern": "src/**/*.ts", "contributor": "Hashi", "limit": 20 }

Output:

src/auth/session.ts | Handle user session lifecycle | contributors: Hashi Dev Agent
src/auth/middleware.ts | Express auth middleware | contributors: Hashi Dev Agent
src/billing/stripe.ts | Stripe payment integration | contributors: swe-agent

(3 of 79 total observations)

rename — Reference-Aware Rename

Rename a file and update all import/reference occurrences across the codebase. Commits atomically.

Tool call:

{ "oldPath": "src/auth/session.ts", "newPath": "src/auth/session-manager.ts", "dryRun": false }

Output:

✓ Renamed: src/auth/session.ts → src/auth/session-manager.ts

3 references updated:
  src/auth/index.ts:12 — "session" → "session-manager"
  src/auth/middleware.ts:8 — "'./session'" → "'./session-manager'"
  src/auth/session-manager.ts:1 — "(same file)"

Committed: a3f9d2c

tree — Project Structure

Show directory tree with configurable depth. Respects .clawnavignore.

Tool call:

{ "path": "src", "depth": 2 }

Output:

/workspace/src/
├── auth/
│   ├── session.ts
│   ├── middleware.ts
│   └── index.ts
├── billing/
│   └── stripe.ts
└── index.ts

recent — Recently Modified Files

List recently changed files via git log. Shows commit message per file.

Tool call:

{ "days": 7, "limit": 10 }

Output:

2026-04-15 session.ts — "fix: token refresh race condition"
2026-04-14 stripe.ts — "feat: add retry logic for failed payments"
2026-04-12 index.ts — "refactor: consolidate auth exports"

explain — File Purpose

Get a plain-English description of what a file does, powered by LLM analysis. Reads Honcho memory (written during index) for instant results; falls back to gateway HTTP call for unindexed files. Also returns git history and contributors.

Tool call:

{ "path": "src/auth/session.ts" }

Output:

## src/auth/session.ts

Handles session lifecycle: creation, validation, refresh, and expiry.
Manages session tokens stored in Redis with a 24h TTL.
Automatically refreshes tokens on activity to extend sessions.

Created: 2026-01-08
Contributors: alice, bob

History:
  2026-04-15 — fix: token refresh race condition
  2026-03-20 — feat: add session expiry notifications
  2026-01-08 — init: session management

index — Build / Update Search Index

Run once after install, or use --force to rebuild everything from scratch.

Tool call:

{ "force": false }

Output:

Indexed 142 files, 387 chunks in 2340ms

benchmark — Benchmark Suite

Run precision@10, MRR, NDCG benchmarks and compare against plain grep for keyword queries.

clawnav benchmark
clawnav benchmark --limit=20 --json

📊 CLAWNAV Benchmark Results
══════════════════════════════════════════════════

Query: "RRF hybrid search"
  Precision@10: 80%
  MRR: 0.500
  NDCG: 0.823
  CLAWNAV wins: ✅
  Grep hits: 3 | CLAWNAV hits: 5
──────────────────────────────────────────────────

Overall: CLAWNAV won 4/4 queries

watch — Background File Watching

Start background indexing that watches for file changes and keeps the index fresh automatically.

clawnav watch
clawnav watch --git   # auto-commit after re-indexing

Tool call:

{ "action": "start" }

Output:

Watch started (PID: 48321). Monitoring workspace: /data/workspace

Also supports "stop" and "status" actions.

--git flag: When enabled, any file changes detected by the watcher are re-indexed and the delta is automatically committed to git with a descriptive message.

overview — Project Overview

Show a high-level summary of the indexed workspace: index stats, file type breakdown, recent commits, and search readiness. Designed for agents to quickly assess a codebase.

clawnav overview

Output:

⚡ CLAWNAV Overview — /data/workspace/codex/clawnav
─────────────────────────────────────────────────────
Index: ✅ Ready (1,247 files, 4,382 chunks)
Last indexed: 2026-04-16T07:00:00Z
─────────────────────────────────────────────────────
File Types: .ts (842) | .md (203) | .json (89) | .yaml (43) ...
Recent commits (5):
  4202e7b — docs: update sprint monitor for v2.0.1 close
  b6effc6 — chore: bump version to 2.0.1 for patch release
  ef41555 — fix: add --version flag and read CLI command
  1ba1d19 — fix: CI uses corepack to enable pnpm
  780b28c — chore: remove .ci-trigger temp file
─────────────────────────────────────────────────────
Ready for search: ✅

CLI Flags

clawnav --version   # Print version and exit
clawnav --help      # Show full usage table

Architecture

┌─────────────────────────────────────────────────────┐
│  OpenClaw Agent  ─── MCP protocol ───►  CLAWNAV   │
└─────────────────────────────────────────────────────┘
                       │
         ┌─────────────┴──────────────┐
         ▼                            ▼
┌─────────────────────┐    ┌─────────────────────────┐
│   SQLite (sql.js)   │    │  ONNX (Xenova/transformers) │
│  • Chunk text store │    │  • all-MiniLM-L6-v2     │
│  • BM25 index       │    │  • 384-dim embeddings   │
│  • sqlite-vec       │    │  • Fully local, no API  │
└─────────────────────┘    └─────────────────────────┘
         │
         ▼
┌──────────────────────────────────────┐
│  RRF Fusion (Reciprocal Rank Fusion) │
│  Long query:  0.4*BM25 + 0.6*vector  │
│  Short query: 0.3*BM25 + 0.5*vec     │
│              + 0.2*ngram overlap     │
└──────────────────────────────────────┘

Indexing flow:

1. Walk workspace files (skip binary/ignored files via .clawnavignore)
2. Chunk files language-awareness (functions, classes, blocks)
3. Generate 384-dim ONNX embedding per chunk
4. Store chunks + vectors in SQLite
5. Incremental: skip files whose mtime hasn't changed

Watch mode: chokidar watches the workspace; on change, re-index only the affected file.

Performance

| Metric | Value | |--------|-------| | Cold start (MCP server) | ~200ms | | Embedding model warm-up | ~3–5s (one-time, async) | | Index build (1000 files) | ~15–30s | | Index build (incremental) | ~200–500ms per changed file | | Search latency | 50–150ms (local) | | Memory footprint | ~200MB (model + SQLite) |

All numbers on a modern laptop (M-series / Intel i7). No network calls after install.

Integration

• API Reference — Every tool, every parameter, every return value
• OpenClaw MCP Integration — Connect CLAWNAV to your OpenClaw gateway
• Agent Integration Guide — How other agents call CLAWNAV via MCP