Lachesis

Lachesis reads your code and builds a map of it. Then you can ask the map questions, like who calls this function, where does this value go, and can bad input reach a dangerous spot.

It works on C, Python, and TypeScript/JavaScript, all in one map.

What is this?

Search tools like grep tell you where a word shows up in your code. Lachesis is different. It follows the actual data. It can tell you where a value came from, where it goes next, and whether a request from the outside can reach something dangerous, like a database call with no login check in front of it.

To do this it reads your code the same way a compiler does, not by guessing with text patterns. So it doesn't miss a call just because a name was renamed or imported in a weird way.

You can use it three ways: as a command in your terminal, as a Python library, or as an MCP server that an AI agent can talk to.

Quick start

Install it, then point it at a folder:

python -m pip install lachesis-cpg
lachesis ./my-project

It builds the map, saves it, and prints the leads. A lead is a spot where outside input can reach something sensitive with no check in the way. Each lead is a question to look into, not a final answer.

  ✓ compiling (0.7s)
  2,677 nodes, 4,539 edges from typescript-compiler-api
  ✓ finding entrypoints that reach sensitive effects (0.1s)

2 leads (lens=all)
  1. [0.810] handleWebhook (http/webhook.ts:10, route) -> findById(documentId) [database]
     a caller that passes no recognized guard can read or write data
     through findById(documentId) starting from handleWebhook
  2. [0.810] handleWebhook (http/webhook.ts:10, route) -> findById(invoiceId) [database]
     this function branches on something, but no login-style check is seen here

You can also give it a git URL instead of a folder: lachesis https://github.com/owner/repo. It downloads the code to a temp folder, scans it, and cleans up after.

The first scan of a project is slow. After that the map is cached under ~/.lachesis/cache, so every run after is fast.

The three ways to use it

Terminal. One lachesis command. lachesis ./repo is the easy front door. If you want more control, the steps map to three passes:

lachesis build   ./my-project graph.kuzu     # step 1: read the code, build the map
lachesis enrich  graph.kuzu                   # step 2: work out the data flow
lachesis analyze graph.kuzu --summary         # step 3: print the leads
lachesis explain graph.kuzu tree.c:1487       # show all the evidence for one spot

Python library. Open the map once, then ask it as many questions as you want.

import lachesis

a = lachesis.Analysis.build("./my-project", "graph.kuzu", enrich=True)
leads = a.scan()
print(leads.summary())

print(a.explain_sink("tree.c", 1487))   # all the evidence for one spot

Runnable example scripts are in examples/.

MCP (for AI agents). Start the server and an agent can build and query the map on its own:

lachesis mcp ./my-project

See MCP below for setup in Cursor, VS Code, Claude, and Docker.

What you can ask

Once the map is built, these are the moves. They work from the terminal, the Python library, or as MCP tools an agent uses:

Every answer comes with how sure it is. Some links are exact. Some are a safe guess, and Lachesis tells you when it's guessing instead of hiding it. Read the answers as evidence, not as a verdict.

MCP

Run lachesis mcp from the same place you built the map. You can hand it a graph.kuzu path, but you don't have to. Start it with no argument and the agent builds its own map when you point it at a repo.

One click (uses uvx, no install step):

Or set it up by hand. If the package is already installed:

{
  "mcpServers": {
    "lachesis": { "command": "lachesis", "args": ["mcp"] }
  }
}

Or let uvx fetch it on first run, no install:

{
  "mcpServers": {
    "lachesis": { "command": "uvx", "args": ["--from", "lachesis-cpg", "lachesis", "mcp"] }
  }
}

Or run it in Docker, with all three languages already in the image:

{
  "mcpServers": {
    "lachesis": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/your/project:/src",
               "ghcr.io/unboundcompute/lachesis:edge"]
    }
  }
}

More client notes are in docs/queries.md.

Languages

Each language is read by a real compiler or its own parser, never a text guess.

A mixed project is one map, not three. A Python function and a TypeScript function it calls sit in the same map, and the same tools work across both.

Two limits worth knowing. Python has no type checker, so it matches attribute calls by name. C reads one file at a time, so it won't follow a call through a function-pointer table it never sees. Each language says what it can and can't do.

How it works

Lachesis works in three steps, and each one is a command.

1. build: read the code with real compilers into a plain map of symbols and calls. This is the fast part, and it's all most navigation needs.
2. enrich: work out how data flows through the map. This isn't done at build time. A question only computes the part of the flow it needs, then caches it.
3. analyze: run over the map and print the leads. These are sensitive spots, scored and matched to known bug shapes. It has a time limit, so a big project can't hang.

There's also a C lifetime pass. Some bugs, like freeing the same object twice or using it after it's freed, aren't about one spot. They're about the whole life of an object. A separate pass tracks each C object being allocated, freed, and used, and reports double-free and use-after-free with a path showing how it happens.

The map is saved as a folder (graph.kuzu). It holds an embedded database plus a small index file. That folder is the map. Every tool reads it directly.

More detail is in docs/graph-model.md (what's in the map) and docs/scaling.md (big repos, memory, and speed).

Install

python -m pip install lachesis-cpg

Works on Python 3.10–3.12. Python analysis needs nothing extra. Scanning TypeScript/JavaScript needs node on your PATH, and C needs clang. If one is missing you get a clear message, not a crash.

To work from a clone (for contributors):

git clone https://github.com/UnboundCompute/lachesis && cd lachesis
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
npm ci
cargo build --release --manifest-path native/clang_frontend/Cargo.toml

Where to go next

• examples/: a five-minute walkthrough plus a runnable script per feature.
• docs/graph-model.md: what's in the map.
• docs/queries.md: every way to ask a question.
• docs/scaling.md: big repos, memory, and CI.

Roadmap

Done recently: