codeview

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

Contents

• Quick start
• Commands
• How it works
• Monorepo
• Agent integration
• Benchmarks
• Comparison
• Development
• Configuration reference
• Requirements

Quick start

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

Commands

How it works

codeview start
  │
  ├─ ts-morph parses your tsconfig(s) — type-aware, not tree-sitter
  ├─ Builds import graph (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

The server auto-shuts down after 30 minutes of idle. Any codeview command auto-starts it if needed.

Degraded mode

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

# Install Ollama for the full experience
brew install ollama && ollama pull nomic-embed-text

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.

Full config reference: cvconfig.example.json.

Embedding providers

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

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

Agent integration

codeview init  # creates .codeview/AGENTS.md

Copy the relevant section into your agent's system prompt. 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

Setup

We tested codeview on three codebases:

Rollup:

Test scenario: "Add a billing route to the API"

Without codeview:

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
→ 4 round-trips, 4 files read

With codeview:

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)
→ 1 round-trip, 2 files read

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

Semantic search quality (fullstack-monorepo)

All domain-specific queries return exactly the right function/type in top 3 results with sub-1.0 distances.

Dogfood: codeview on itself

We ran codeview on its own 18-file codebase. Agent task "add --port flag to start command":

Without: 5 reads to discover cli.ts → server.ts → config.ts → types.ts → server-daemon.ts

With: 1 context call → map shows startServer(rootDir, requestedPort) and CodeviewConfig.port → jump straight to cli.ts

Semantic queries on its own code confirmed accuracy:

• "file watching" → markStale() (1.002) — the exact function that handles file changes
• "embedding vector storage" → EmbeddingProvider (0.896) — the exact type defining embedding providers
• "add new CLI command" → loadConfig() (1.002) — the config loader pattern to follow

Cross-package import edges (monorepo-project)

Test confirmed: app imports from shared are flagged as cross-project edges in the graph. shared/src/index.ts shows [imported by: app/src/index.ts] in the repo map, and inDegree correctly reflects the cross-package dependency.

Comparison

Development

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

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

Runtime: ~9s. Ollama embedding tests run live (not mocked).

Configuration reference

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

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)