abacus

Abacus

A CLI tool and MCP server that builds a living application graph from source code using pluggable scanners. Abacus discovers routes, entities, pages, actions, and their relationships, stores them in SQLite with FTS5 full-text search, and exposes them via CLI commands and MCP tools for AI agents.

AI agents (like Claude Code) can query the graph to understand an application's structure -- what API routes exist, what database entities are defined, what pages are rendered, and how they connect.

How It Works

.abacus/config.yaml
        |
        v
  Scanner Runner         Scanners are standalone executables.
        |                 Abacus sends ScanInput JSON on stdin,
        +---> express     reads ScanOutput JSON from stdout.
        +---> prisma
        +---> react-router
        +---> orpc
        |
        v
  SQLite Graph DB         Nodes + edges + FTS5 full-text index
   (.abacus/abacus.db)
        |
        +---> CLI commands (abacus routes, entities, pages, ...)
        +---> MCP server   (11 tools for AI agent integration)

The architecture is BYOASTP (Bring Your Own AST Parser): Abacus core is 100% Go with no language-specific parsing. Scanners are standalone executables that output JSON conforming to Scanner Protocol V1. Community can write scanners for any language or framework.

Quick Start

# Install
make install
# or
go install github.com/mjn/abacus/cmd/abacus@latest

# Initialize in your project
cd your-project
abacus init

# Run scanners
abacus scan

# Query the graph
abacus routes
abacus entities
abacus pages
abacus stats

CLI Commands

All commands support --json for machine-readable output, --db to override the database path (default: .abacus/abacus.db), and --quiet/--verbose flags.

abacus init

Initialize Abacus for the current project. Creates .abacus/ directory, auto-detects scanners from package.json and go.mod, generates config.yaml, and initializes the SQLite database.

Flag	Description
--dir	Project directory to initialize (default: .)
--force	Re-detect scanners and overwrite config

abacus init
abacus init --dir /path/to/project --force

abacus scan [type]

Run all configured scanners (or a specific one by ID) and ingest discovered nodes and edges into the graph database.

abacus scan           # Run all scanners
abacus scan express   # Run only the express scanner
abacus scan --json    # JSON output

abacus routes

List or search route nodes.

Flag	Description
-m, --match	FTS5 search query
-l, --limit	Maximum results (default: 1000)

abacus routes
abacus routes -m "users" -l 10

abacus entities

List or search entity nodes. Same flags as routes.

abacus entities
abacus entities -m "User"

abacus pages

List or search page nodes. Same flags as routes.

abacus pages
abacus pages -m "dashboard"

abacus actions

List or search action nodes.

Flag	Description
-m, --match	FTS5 search query
-l, --limit	Maximum results (default: 50)

abacus actions
abacus actions -m "login"

abacus actions create <name>

Create a new action node with optional Gherkin patterns and references.

Flag	Description
--label	Human-readable description
--gherkin	Cucumber expression patterns (repeatable)
--route-ref	Route node IDs to link (repeatable)
--entity-ref	Entity node IDs to link (repeatable)
--page-ref	Page node IDs to link (repeatable)

abacus actions create "login-user" \
  --label "User logs in" \
  --gherkin "the user logs in with {string}" \
  --route-ref "route:POST-/api/auth/login" \
  --entity-ref "entity:User"

abacus graph <node-id>

Show the connected subgraph around a node.

Flag	Description
-d, --depth	Maximum traversal depth (default: 2)

abacus graph "route:GET-/api/users"
abacus graph "entity:User" -d 3 --json

abacus match [step-text]

Match a Gherkin step text against the action graph using 3-tier matching (exact, fuzzy, suggest).

Flag	Description
-f, --file	Feature file to match all steps
-k, --keyword	Step keyword (Given/When/Then)
--create	Auto-create action from suggestion
--threshold	Fuzzy match threshold

abacus match "the user logs in with \"admin\""
abacus match -f features/login.feature --create

abacus coverage [glob]

Show Gherkin step coverage report. Default glob: **/*.feature.

abacus coverage
abacus coverage "features/**/*.feature" --json

abacus stats

Show graph statistics (node counts per kind).

abacus stats
abacus stats --json

abacus mcp-server

Start the MCP server on stdio.