Metadata-Version: 2.4
Name: devkb
Version: 0.2.14
Summary: A software-process knowledge graph for software development agents: extraction, pre-computed context packs, and an MCP server
Author: Hung T. Le
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/namiq-ai/devkb
Project-URL: Issues, https://github.com/namiq-ai/devkb/issues
Project-URL: Benchmark, https://github.com/namiq-ai/devkb/blob/main/docs/BENCHMARK.md
Keywords: knowledge graph,software development agents,coding agents,mcp,code intelligence,call graph,software process
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyyaml>=6
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.23; extra == "mcp"
Provides-Extra: study
Requires-Dist: scipy>=1.10; extra == "study"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: mcp<2,>=1.23; extra == "dev"
Requires-Dist: scipy>=1.10; extra == "dev"
Dynamic: license-file

# devkb

[![PyPI](https://img.shields.io/pypi/v/devkb)](https://pypi.org/project/devkb/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24267143.svg)](https://doi.org/10.5281/zenodo.24267143)

**A knowledge graph of your repository for software development agents.** Agents answer "what calls this, what breaks, which tests"
in one step instead of searching file by file: 55% cheaper, with better answers, in our benchmark.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/img/benchmark-dark.svg">
  <img alt="Median cost per task: plain search $0.070 (quality 0.931); devkb 12 tools $0.059, 18% cheaper (0.955); devkb 7 tools $0.040, 38% cheaper (0.963); devkb pack $0.025, 55% cheaper (0.981)" src="docs/img/benchmark-light.svg">
</picture>

## 1. What devkb is

- **A graph** built from your source and git history: functions, calls, tests, routes, errors, configuration,
  commits, pull requests, tickets ([ontology](devkb/ontology.md)).
- **Packs**: one command answers a whole question (who calls this, what breaks, which tests to run), each item with
  the source line that proves it, and a statement of what the graph could not see.
- **An MCP server** giving agents the same answers as tools, for Claude Code, Codex and any MCP client.

Everything runs locally: devkb reads files and runs `git`, never your code (unless `devkb.json` opts in), and the graph never leaves your machine.

### Languages

| Language | Status | What devkb understands |
|---|---|---|
| Python | ✅ Supported | functions, classes, calls (imports, typed objects, base classes), tests, FastAPI/Flask/Odoo routes, errors, environment variables |
| C# | ✅ Supported | types, members, calls through typed receivers, generics, LINQ and overloads, tests; checked against the compiler on five open-source repositories |
| C, C++ | 🟡 Partial | functions, classes, calls, tests, error messages, calls across languages (`extern "C"`, ctypes, pybind11); no preprocessor expansion, no overload resolution, no type inference; a function-pointer or ops table is an unresolved indirect reference; a cross-language pack is Complete only for the languages read |
| TypeScript, JavaScript | 🟡 Partial | functions, components, classes and their HTTP calls to backend routes; not calls between them |
| Odoo XML | 🟡 Partial | templates, views, menus |
| Java, Go, Rust, shell, others | ⬜ Not yet | files and history only |

Where a call cannot be attributed, an answer says Incomplete instead of guessing.

"Files and history" is the language-independent layer every repository gets: files, commits, pull requests and
tickets.

## 2. How much it saves

Latest benchmark: the 7 open-source repositories in [`bench/repos.yaml`](bench/repos.yaml), 57 tasks, 1,138 agent
runs, the same model (Sonnet) in every arm, answers scored against truth computed from the source. Cost, turns and
tokens are the median run; saving is per task against plain search, averaged over tasks; quality is the mean score:

| | Plain search | devkb, 12 tools | devkb, 7 tools | devkb pack |
|---|---|---|---|---|
| **Cost per task** | $0.070 | $0.059 | $0.040 | **$0.025** |
| **Saving** | — | 18% | 38% | **55%** |
| **Quality** (0–1) | 0.931 | 0.955 (+0.024) | 0.963 (+0.032) | **0.981 (+0.050)** |
| Turns | 4 | 6 | 5 | **3** |
| Context processed (tokens) | 126k | 169k | 147k | **75k** |
| of which cache reads | 123k | 163k | 141k | 74k |
| of which new input and cache writes | 8.3k | 4.1k | 2.0k | 1.3k |
| Output tokens | 1.4k | 1.8k | 1.3k | 0.9k |

Saving and quality gain by repository (95% intervals in the results):

| Repository | Tasks | 7 tools: saving / quality | pack: saving / quality |
|---|---|---|---|
| lnbits | 10 | 53% / +0.032 | **66%** / +0.049 |
| Netflix Dispatch | 8 | 45% / +0.040 | **61%** / +0.081 |
| Prefect | 9 | 41% / −0.017 | **59%** / +0.047 |
| lattice-scan | 12 | 36% / +0.052 | **51%** / +0.058 |
| Mealie | 6 | 18% / +0.095 | **42%** / +0.062 |
| devkb | 4 | 1% / +0.004 | **40%** / +0.004 |
| click | 8 | 6% / +0.016 | 15% / +0.023 |

The saving is in call chains (66–77% on tasks that trace an error or a change to the route handlers that reach it);
on one-hop questions, as in click, plain search is already good. An earlier pre-registered study (30 held-out tasks,
1,020 runs, two model sizes) found packs 41% cheaper and the lean tools 35% ([`study/`](study/); `make verify`
recomputes it). Details and corrections: [`bench/results/2026-11-15-registry`](bench/results/2026-11-15-registry/);
add a repository: [`docs/BENCHMARK.md`](docs/BENCHMARK.md).

## 3. Set up

```bash
uv tool install "devkb[mcp]"      # or: pipx install "devkb[mcp]"
cd your-repo
devkb init --hooks
```

This builds the graph into `.devkb/`, adds a short devkb section to `AGENTS.md` and `CLAUDE.md`, registers the MCP
server in `.mcp.json`, and rebuilds the graph after each commit. Your own content in those files is kept;
`devkb init --remove` undoes it.

Install devkb as a tool, as above, so the `devkb` command is on your PATH: agents start the server from there, and a
devkb installed only inside a virtual environment never starts (`devkb init` warns if that is the case).

Ask it directly:

```bash
devkb pack --project . refactor my_function     # who calls it, which tests
devkb pack --project . error "message text"     # which route handlers reach it
devkb pack --project . file path/to/file.py     # before editing a file
```

### Your agent

**Claude Code**: `devkb init` registered the server in `.mcp.json` and pointed `CLAUDE.md` at the instructions, which
say which tool to use at which step. Start `claude` in the repository, approve the `devkb` server when asked, and check
it with `/mcp`. Agents told to run a pack before editing mostly do not, so add the hook that does it for them: run
`devkb init --claude-hook`, and when the agent is about to Edit or Write a file the graph knows, it receives that file's
pack (the functions other files call, the dependent files, the tests to run) once per session. It never blocks an edit.
Or skip the install and `devkb init` and use the plugin, which brings the server, its instructions, that hook and a hook
that builds the graph in the background (needs [uv](https://docs.astral.sh/uv/)):

```
/plugin install devkb --marketplace namiq-ai/devkb
```

**Cursor**: add `.cursor/mcp.json` to the repository, then enable `devkb` under Settings → MCP:

```json
{"mcpServers": {"devkb": {"command": "devkb", "args": ["mcp", "--project", ".", "--toolset", "lean-pack"]}}}
```

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

```toml
[mcp_servers.devkb]
command = "devkb"
args = ["mcp", "--project", ".", "--toolset", "lean-pack"]
```

Codex and Cursor read the instructions in `AGENTS.md`; Claude Code reads them through `CLAUDE.md`.

What agents get by default (`--toolset lean-pack`): a `pack` tool that returns a whole answer in one call, and the
seven single-question tools. The instructions tell them to ask for a pack when a question follows a chain (a file
before editing, a change, an error) and to search as usual for a one-hop lookup, which is where the benchmark found
the saving and where it did not. Measured with agents asking for the pack themselves (lnbits and Dispatch, 400 runs):
53% cheaper than plain search with the highest quality of any arm, against 42% for the seven tools alone
([`bench/results/2026-11-15-lean-pack`](bench/results/2026-11-15-lean-pack/)).

Tried it on your repository? Tell us what happened, good or bad, in
[issue #25](https://github.com/namiq-ai/devkb/issues/25).

## 4. Licence and citation

Code: [Apache-2.0](LICENSE). The study in [`study/`](study/) (paper, figures, pre-registration, data):
[CC BY 4.0](study/LICENSE). Benchmark results quote third-party code under its own licences
([`bench/results/NOTICE`](bench/results/NOTICE)). Releases: [`docs/RELEASING.md`](docs/RELEASING.md).

> Hung T. Le. *Precomputed Context, Not More Tools: A Pre-Registered Study of Process Graphs for Coding Agents.* 2026.
