devlensOSS

<div align="center">

<img src="assets/logo_1.png" alt="DevLens Logo" width="120" />

# DevLens

**Codebase Intelligence for AI agents and Developers.**

Analyze your repo once. Your AI agent then queries a precomputed code graph through MCP — ranked files, call flow, impact, and security — instead of re-reading your codebase file by file. Ranked **first of nine tools** on every quality measure in our public benchmark.

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![npm: @devlensio/cli](https://img.shields.io/badge/npm-%40devlensio%2Fcli-cb3837?logo=npm)](https://www.npmjs.com/package/@devlensio/cli)
[![Built with Bun](https://img.shields.io/badge/Built%20with-Bun-f9f1e1?logo=bun)](https://bun.sh)

**[Join the DevLens Cloud Waitlist →](https://devlens.io)**

</div>

---

[![DevLens Demo](assets/image.png)](https://youtu.be/6OMsk8lNv4c?si=wpYF80IcfuJpN_Gf)

<p align="center"><em>Click the image to watch the demo</em></p>

---

## Why DevLens?

- **Your agent stops burning tokens.** One MCP call returns a task-shaped packet — the files and symbols that matter, ranked, within a token budget. No grep loops, no re-reading files.
- **It wins the benchmark.** First of nine tools on correctness, F1, recall, and precision — the only tool that leads every quality column.
- **It is fast and small.** 67 ms per call, packets 6.7× smaller than the closest graph competitor, and it never exceeds the token budget you set.
- **Developers get it too.** Interactive graph visualization, blast radius before you change a symbol, PR review packets, and per-node security analysis.

---

## Benchmarks

We benchmarked DevLens MCP against seven other code graph and retrieval tools — **Graphify, codegraph, serena, semble, codebase-memory**, and others. One headless coding agent, one model, one real TypeScript repository, 133 real questions written from actual pull requests and symbols, two runs each: **2,394 agent runs in total**.

| | **DevLens OSS** | **Graphify** | codegraph | serena | semble | codebase-memory |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Correctness | **🥇 0.694** | 0.662 | 0.674 | 0.656 | 0.652 | 0.644 |
| F1 | **🥇 0.562** | 0.548 | 0.555 | 0.545 | 0.535 | 0.544 |
| Latency per call | **67 ms** | 2,469 ms | 2,736 ms | 106 ms | 508 ms | 1,100 ms |
| Response packet | **2,230 tokens** | 15,020 tokens | 6,339 tokens | 8 tokens* | 736 tokens | 294 tokens |
| Token budget compliance | **100%** | median 2.5× over | — | — | — | — |
| Graph size | **10,346 nodes / 19,847 edges** | 16,999 / 71,694 | not measured | — | — | 26,299 / 99,321 |

\* serena's symbol tool returned no results on every question, so its tiny packet means it found nothing, not that it is efficient. The low response-payload figures for codebase-memory, semble, and BM25-style tools come from line lists rather than structured answers.

DevLens is **the only tool ranked first on correctness, F1, recall, and precision** — and it wins with the fastest calls and one of the smallest packets. Head-to-head against Graphify on identical questions: packet 6.7× smaller on all 54 of 54 comparable questions, ~37× faster per call, and a paired 15 wins to 9 losses.

> The pattern behind the numbers: syntactic tools return big blobs or bare line lists. DevLens returns a task-shaped packet from a type-resolved graph — the files that matter, ranked, within your token budget, in milliseconds.

**Full methodology, all nine tools, five languages:** [`docs/PUBLIC-BENCHMARKS.md`](docs/PUBLIC-BENCHMARKS.md)

---

## How DevLens compares

DevLens is the only tool in this space that combines native semantic parsing, per-node AI summaries with per-node security analysis, and framework-aware data edges — and the only option you can use commercially under AGPL.

| Dimension | **DevLens** | **Graphify** | **GitNexus** | **Sourcegraph** | **DeepWiki** |
| :-- | :-- | :-- | :-- | :-- | :-- |
| Parsing depth | **Native semantic parsers** (TS compiler, Python `ast`, `go/types`, JavaParser, `syn`), type-resolved | tree-sitter (syntactic, no type info) | tree-sitter + native bindings (no type info) | SCIP/LSIF symbol index + language servers (no semantic parse) | LLM reads source directly (no structured parser) |
| Edge quality | **Type-checked `IMPLEMENTS`/`EXTENDS`**, framework **routes** (Next.js, Django, Spring, Gin, axum), **ORM data edges** (`READS_FROM`/`WRITES_TO`) | `EXTRACTED`/`INFERRED`/`AMBIGUOUS` tags, no type or framework awareness | call chains, clusters, `route_map`, no ORM or data edges | precise symbol cross-references (SCIP), no type-checked inheritance | docs-level relationships (no structured graph) |
| Per-node AI summaries | **Technical + business + security** with severity on every node | No (LLM used for docs and concepts) | No (embeddings for semantic query) | Via Cody (hover and inline docs, chat-level) | Auto-generated docs per symbol (no security, no technical/business split) |
| Security analysis | **Per-node severity + blast-radius reach** with real exploit descriptions | No | Partial (opt-in PDG/taint) | No (compliance certifications only) | No |
| Agent / MCP integration | CLI + **self-describing MCP server** + Web UI | CLI + local skill (no MCP) | CLI + 17-tool MCP + hooks (`AGENTS.md`) | MCP server (cross-repo search, not per-repo graph queries) | Unknown (no public MCP integration) |
| Language coverage | TS/JS, Python, Java, Go, Rust with **native parsers for each** | 12 code families + docs/images (shallow syntactic) | Many via tree-sitter (Dart/Kotlin/Swift), shallow syntactic | 30+ via language servers (symbol-level, no semantic edges) | Any (LLM reads source, no structured extraction) |
| License / pricing | **AGPL-3.0, free, including commercial use** | Apache-2.0 | PolyForm Noncommercial (cannot use commercially) | Open-source core, Enterprise paid | Free for public repos, enterprise tiers unlisted |

*(Feature comparison from public sources, Aug 2026.)*

**Why teams choose DevLens:** semantic edges that syntactic tools cannot produce, per-node security analysis no other open-source tool provides, benchmark-winning retrieval quality, and a single MCP front door — free for commercial use.

---

## Quick Start

### Step 1 — Install the CLI

```bash
npm install -g @devlensio/cli
```

Or install the standalone binary (no Node.js needed):

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/devlensio/devlensOSS/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/devlensio/devlensOSS/main/scripts/install.ps1 | iex
```

### Step 2 — Configure a model (optional)

Only needed if you want AI summaries. Structure-only analysis works offline with no API key.

```bash
devlens init
```

This walks you through picking a provider and model interactively. Local models work too (Ollama, 8 GB+ RAM). See [Configuration](#configuration) for recommended models.

### Step 3 — Analyze your repo

```bash
cd your-project
devlens analyze . --summarize
```

This builds the graph, generates summaries, and creates the search index — once. After this, everything below is instant.

### Step 4 — Connect your AI agent

Start the MCP server:

```bash
devlens mcp
```

Then register it in your agent. Pick your tool:

**Claude Code / Claude Desktop**

```bash
claude mcp add devlens -- devlens mcp
```

**Cursor** — add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "devlens": { "command": "devlens", "args": ["mcp"] }
  }
}
```

**Codex** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.devlens]
command = "devlens"
args = ["mcp"]
```

**Hermes** — add to `config.yaml`:

```yaml
mcp:
  servers:
    devlens:
      command: devlens
      args: [mcp]
```

**Any other MCP client** — the server speaks standard MCP over stdio. Point your client at the command `devlens mcp`. For an HTTP transport instead:

```bash
devlens mcp http -p 7000
```

The server self-describes its full tool list through `tools/list`, so your agent discovers everything on its own. That's it — ask your agent "how does auth work in this repo?" and watch it query the graph instead of reading files.

---

## What your agent can ask

The server self-describes every tool's parameters through `tools/list` — your agent fills them in automatically. Every graph tool takes a `graphId` (returned by `list_analyzed_repos` / `analyze`) plus the arguments below.

| Tool | Key arguments | What it does |
| :-- | :-- | :-- |
| `resolve_context` | `task` (required), `intent`, `focus`, `tokenBudget` | **The front door.** One call returns a task-shaped packet: ranked nodes with one-line meanings, call flow, involved files, key code bodies, security flags, and an id map — all within a token budget. Intents: `pinpoint`, `reference-list`, `flow`, `overview`, `concept`, `security-audit`, `exploratory`. |
| `blast_radius` | `symbol` (required) | Cheap change-impact wrapper: what depends on a symbol, packed small. |
| `find_symbols` | `query` (required) | Cheap BM25F name lookup: nodeIds plus `file:line`, no graph, no source. |
| `get_node` | `nodeId` (required) | Full detail for one node: technical, business, and security summaries plus metadata. |
| `get_node_code` | `nodeId` (required) | Raw source for one node (expensive, so use it last). |
| `get_blast_radius` / `get_khop` | `nodeId` (required), `radius` | Upstream dependents or downstream dependencies out to a chosen radius. |
| `get_summaries` | `nodeIds` (required) | Batch-read summaries for several node ids. |
| `get_security_issues` | `minSeverity` | Security findings ranked by severity then impact, with the severity distribution and how much of the graph was assessed. |
| `check_freshness` | — | Is the graph stale versus the working tree? |
| `get_subgraph` | `seedNodeId` (required) | The cohesive cluster (module) a node belongs to. |
| `list_cycles` | — | Circular dependencies. |
| `get_nodes_in_path` | `path` (required) | Every node in a file