codeview

Local codebase intelligence server for coding agents. Type-aware repo maps + semantic search via Ollama — pluggable into any agent via HTTP.

Requirements

• Bun ≥ 1.1.0
• Ollama (optional, for semantic search)
• macOS: Homebrew SQLite required for sqlite-vec (brew install sqlite3 — automatic detection)
• Linux: Works out of the box (Bun SQLite has extension loading)
• Windows: Works out of the box (file watching degrades gracefully to manual rebuild)

Quick start

bun add -D @ramankarki/codeview
bunx @ramankarki/codeview start
bunx @ramankarki/codeview context "add Stripe webhook handler"

No Ollama? No problem — structural + keyword search work without it.

Why codeview?

codeview gives coding agents structural understanding of your TypeScript codebase — type-aware, not regex or tree-sitter. It builds an import graph, extracts chunks with full type signatures, and runs semantic search locally via Ollama. Everything stays on your machine.

Commands

The daemon auto-shuts down after 30 minutes idle.

Agent integration

codeview was built for coding agents. One command gives them everything:

codeview init  # creates .codeview/AGENTS.md

Copy into your agent's system prompt, then your agent calls:

codeview context "your task"          # at task start: map + search + graph walk
codeview find <name>                  # exact location
codeview references <name>            # who imports this
codeview search "concept"             # find relevant code

Benchmarks

Real-world scenario: "Add a billing route to the API"

Without codeview — 4 round-trips, 4 files read:

1. read api/src/index.ts         → find route registration
2. read api/src/routes/products  → copy pattern  
3. read shared/src/index.ts      → find Product/Currency types
4. read middleware/auth.ts       → auth guard pattern

With codeview — 1 round-trip, 2 files read:

1. codeview context "add billing route"
   → repo map shows all exports grouped by package
   → semantic search returns Product (0.938), Currency (0.822)
   → graph walk shows products route as neighbor
2. read products.ts (for pattern), shared/index.ts (for types)

75% fewer round-trips, 50% fewer files read.

Semantic search quality

Tested on 3-package monorepo (Hono API + TanStack Start + shared types):

All queries return the exact symbol in top 3 results, sub-1.0 distances.

Dogfood: codeview on itself

Agent task: "add --port flag to start command"

Test fixtures

How it works

codeview start
  │
  ├─ ts-morph parses your tsconfig(s) — type-aware AST, not tree-sitter
  ├─ Builds import graph with PageRank centrality
  ├─ Chunks functions/classes/interfaces/types → SQLite
  ├─ Embeds via Ollama (nomic-embed-text, 768d) → sqlite-vec ANN index
  ├─ Starts Bun HTTP server on auto-assigned port
  ├─ Writes .codeview/port + .codeview/pid
  └─ Watches files via fs.watch, marks stale on change

Degraded mode

Without Ollama, structural + keyword search work at full capacity:

brew install ollama && ollama pull nomic-embed-text  # optional, for semantic search

Monorepo

cvconfig.json at project root:

{
  "projects": [
    { "name": "api", "tsconfig": "packages/api/tsconfig.json" },
    { "name": "web", "tsconfig": "packages/web/tsconfig.json" },
    { "name": "shared", "tsconfig": "packages/shared/tsconfig.json" }
  ],
  "exclude": ["**/*.test.ts", "**/__mocks__/**"],
  "tokenBudget": 5000
}

Output groups by project, flags cross-package edges in [imported by: ...] annotations.

Embedding providers

{
  "embedding": {
    "provider": "openai",
    "apiKey": "$OPENAI_API_KEY",
    "model": "text-embedding-3-small"
  }
}

Supports ollama (default, free), openai, and voyage.

Configuration reference

All options in cvconfig.json. Copy from cvconfig.example.json:

Development

bun install
bun test           # 72 tests, 14 files
bun run typecheck  # tsc --noEmit

Runtime: ~9s. Ollama embedding tests run live.

Test fixtures

test/fixtures/
├── tiny-project/          # 5 files, 1 tsconfig — unit test target
├── monorepo-project/      # 2 packages, cross-package imports
└── fullstack-monorepo/    # 3 packages, Hono RPC + TanStack Start

Test matrix

Contributing

Conventional Commits required. Pre-commit hook runs bun test.

git checkout -b feat/my-feature
# code... (pre-commit runs bun test)
git commit -m "feat: add my feature"
git push → open PR → CI runs (typecheck + test + build + commitlint)

See CODEVIEW_SPEC.md for full production infrastructure details.

License

MIT © Raman Karki