What eben does

eben scans your repository once — deterministically, with no AI, no internet — and builds a Canonical Engineering Model (CEM): a structured representation of everything that matters about your codebase.

From that model it generates:

• 📊 Engineering Dashboard — dark-mode web UI with 7 sections, AI chat built in
• 🤖 AI Context Files — CLAUDE.md, AGENTS.md, CURSOR.md, GEMINI.md, COPILOT.md
• 🕸️ Knowledge Graph — interactive Cytoscape.js graph + DOT + Mermaid exports
• 📈 AI Readiness Score — letter grade across 9 engineering dimensions
• 🔬 Benchmark Engine — measures AI performance with vs without eben context
• 🗂️ Canonical JSON — report.json as the single source of truth for everything

Quickstart

pip install eben
cd your-project
eben init .
open .eben/index.html

That's it. Eben scans the repo, builds the model, and opens a full engineering dashboard in your browser.

Every scan ends with an impact summary:

  ✓  Dashboard ready → .eben/index.html

  ──────────────────────────────────────────────

  Your AI just got 31 facts about this repo.
  Before eben: your AI knew nothing about my-service.
  After  eben: stack, architecture, conventions, dependencies — all loaded.

  →  Write CLAUDE.md, AGENTS.md and more:
     eben scan . --markdown

The fact count is real — every detected convention, dependency, layer, entry point, technology, and module counted from your actual repo.

Install

Recommended — install globally with pipx:

pipx install eben

That's it. eben is now available everywhere on your machine. No venv, no activation, no python3 eben.py.

# Then just run from any repo:
cd your-project
eben scan .

Don't have pipx? brew install pipx on Mac or pip install pipx on Linux/Windows.

Optional extras:

pipx install eben[benchmark]   # + benchmark engine
pipx install eben[all]         # + all LLM providers

Or clone and run locally (for development):

git clone https://github.com/ebenhq/eben
cd eben
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip setuptools
pip install -e .
eben scan .              # works like a global command while venv is active

Commands

Scan flags

eben scan . --markdown           # also generate AI context files
eben scan . --format json        # JSON terminal output
eben scan . --no-color           # no ANSI colours
eben scan . --max-depth 12       # deeper traversal
eben scan . --max-files 100000   # raise file limit

What gets generated

eben scan .

Everything goes into .eben/ — never the repo root:

.eben/
├── index.html               ← Engineering Dashboard  ← open this
├── report.json              ← canonical report model
├── model.json               ← Canonical Engineering Model (CEM)
├── technologies.json
├── architecture.json
├── conventions.json
├── dependencies.json
├── metadata.json
├── checksum.json
├── engineering-report.md
├── ai-readiness.json
├── graph.json
├── graph.mermaid
└── graph.dot

eben scan . --markdown or eben generate .

Also writes AI context files to the repo root (agents find them there automatically):

CLAUDE.md
AGENTS.md
CURSOR.md
GEMINI.md
COPILOT.md

Engineering Dashboard

One HTML file. No server needed. Works offline. Open it anywhere.

Seven sections:

Built-in AI Chat

The Chat tab turns the dashboard into an interactive assistant that already knows your repo before you type a word.

• Reads context from the embedded report.json
• Supports 6 providers: Anthropic · OpenAI · Gemini · Mistral · Groq · Custom
• Custom provider accepts any OpenAI-compatible endpoint (Ollama, LM Studio, Azure, Together, Anyscale…)
• API key stays in browser memory only — gone when the tab closes
• Works on GitHub Pages (no backend)

What eben detects

35+ languages — Java, Python, TypeScript, Go, Rust, Kotlin, Swift, Dart, C#, C++, Ruby, PHP, Scala, Elixir, and more

60+ frameworks — Spring Boot, Django, FastAPI, React, Next.js, NestJS, Vue, Angular, Gin, Rails, Laravel, Axum, Flutter, PyTorch, LangChain, and more

Build tools — Maven, Gradle, Cargo, Go Modules, Make, Bazel, SBT, MSBuild

Package managers — npm, Yarn, pnpm, pip, Poetry, uv, Bundler, Composer, Pub

Databases — PostgreSQL, MySQL, MongoDB, Redis, Cassandra, Elasticsearch

Messaging — Kafka, RabbitMQ, NATS, ActiveMQ, Celery

Cloud — AWS, GCP, Azure, Vercel, Fly.io, Cloudflare, Render, Netlify

CI/CD — GitHub Actions, GitLab CI, Jenkins, CircleCI, Travis CI, Drone, Buildkite

Infrastructure — Terraform, Pulumi, Ansible, CloudFormation, AWS CDK, Serverless

Architecture patterns — Layered, hexagonal, MVC, microservices, monorepo, event-driven, serverless, library

AI Context Files

When you run eben generate ., eben writes five files to your repo root — one per major AI coding agent.

Each file uses a three-zone system:

<!-- eben:generated -->
## Stack
Languages: Java, Kotlin
Frameworks: Spring Boot
...
<!-- /eben:generated -->

<!-- eben:ai -->
AI agents write their notes here.
eben never touches this zone.
<!-- /eben:ai -->

<!-- eben:team -->
Humans write team context here.
eben never touches this zone.
<!-- /eben:team -->

⚠️ If a file already exists without zone markers, eben overwrites it entirely. Move your existing content into <!-- eben:team --> first.

Benchmark Engine

Measures the real impact of eben on AI performance. Runs every task twice:

1. Baseline — AI with no eben context
2. Eben-assisted — AI with .eben/report.json injected

Metrics captured:

• ✅ Task success rate
• 🎯 Accuracy improvement
• 💰 Token and cost reduction
• ⚡ Latency reduction
• 🧠 Hallucination reduction
• 📈 ROI estimate

Outputs go to .benchmark/:

.benchmark/
├── index.html          ← Benchmark Dashboard (7 sections)
├── benchmark.json      ← full run data
├── benchmark.md        ← markdown summary
└── results.json        ← per-task detail

The benchmark dashboard includes a live ROI calculator — adjust your team size and session frequency in the browser.

Supported benchmark providers

Architecture

eben/
├── core/           ← filesystem walker, detector base, CEM schema, zone system
├── detectors/      ← 8 detectors (one file each — add a detector = one new file)
├── writers/        ← CEM, markdown, terminal output
├── report/         ← Engineering Intelligence Report generator
├── readiness/      ← AI Readiness scoring engine + rules.yaml
├── graph/          ← knowledge graph builder
├── dashboard/      ← Engineering Dashboard (single HTML, no deps)
└── benchmark/      ← full benchmark system
    └── providers/  ← 6 provider implementations (one file each)

Architecture rules:

• FileSystem walks once — all detectors share the same fs instance
• Each detector returns a dict — merged by ModelBuilder.deep_merge()
• All outputs go to .eben/ — never the repo root
• Agent markdown files go in root only with --markdown flag
• report.json is the single source of truth — dashboard reads from it
• from __future__ import annotations first line in every .py (Python 3.8 compat)

Contributing

macOS / Linux note: never run pip install outside a virtual environment — your OS will block it. Always activate the venv first.

git clone https://github.com/ebenhq/eben
cd eben

# Create and activate a virtual environment (one time)
python3 -m venv .venv
source .venv/bin/activate       # Mac / Linux
# .venv\Scripts\activate       # Windows

# Install dependencies (venv must be active — you'll see (.venv) in your prompt)
pip install pyyaml              # core only
pip install pyyaml pydantic litellm rich typer   # full install

# Run eben
python3 eben.py scan .
open .eben/index.html

Adding a detector = one new file in eben/detectors/. Adding a benchmark provider = one new file in eben/benchmark/providers/. Nothing else changes.

Built by ebenhq