Getting Started with Grafema

Zero to insight in 5 minutes. Grafema builds a queryable graph of your codebase, answering questions like "who calls this function?" or "where does this data flow?" without reading thousands of lines of code.

Prerequisites

• Node.js 18+ (check with node --version)
• A JavaScript or TypeScript project with a package.json
• macOS (ARM or Intel) or Linux x64

Step 1: Install

npm install -g grafema

Step 2: Index (1-2 minutes)

In your project directory:

grafema analyze --quickstart

--quickstart auto-detects your project languages, generates .grafema/config.yaml, and builds the code graph in one step.

Expected output:

Analyzing project: /path/to/your-project
Analysis complete
  Nodes: 2,847
  Edges: 5,123

Two-step alternative — if you want to review the config before indexing:

grafema init        # generates .grafema/config.yaml
grafema analyze     # builds the graph

Step 3: Explore

What's in a file?

grafema tldr src/server.ts

Returns a compact DSL overview — 10-20x smaller than the source file:

server.ts {
  o- imports express, cors, helmet
  > calls app.listen, setupRoutes
  < reads config.port
  => writes app
}

Who calls a function?

grafema who handleRequest

Where does data come from?

grafema wtf req.user

Traces backward through assignments, function parameters, and imports to show where the value originates.

Project overview

grafema overview

Shows node/edge counts by type — modules, functions, classes, call sites.

Step 4: AI Integration (MCP)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "grafema": {
      "command": "npx",
      "args": ["grafema-mcp", "--project", "."]
    }
  }
}

Now Claude Code (or any MCP client) can query your codebase graph instead of reading files. Available tools include find_nodes, find_calls, trace_dataflow, get_file_overview, describe, and 30+ more.

Step 5: Health Check

grafema doctor

Checks binary availability, RFDB server status, and common issues.

Configuration

The generated .grafema/config.yaml uses minimal defaults:

version: "0.3.29"
root: ".."
include:
  - "src/**/*.{ts,tsx,js,jsx}"
exclude:
  - "**/*.test.*"
  - "**/__tests__/**"
  - "**/node_modules/**"
  - "**/dist/**"

Edit include/exclude patterns to match your project layout. Paths resolve relative to the .grafema/ directory, so root: ".." points to the project root.

See Configuration Reference for all options.

Next Steps

• Configuration Reference - Customize file patterns and services
• Datalog Cheat Sheet - Advanced graph queries
• Known Limitations - What works and what doesn't

Troubleshooting

"No graph database found" Run grafema analyze first to build the graph.

Analysis shows 0 files Check .grafema/config.yaml — make sure include patterns match your source files and root points to the project root (usually "..").

"package.json not found" Grafema currently requires a package.json. Run npm init -y to create one.

Binaries not found Run grafema doctor to check which binaries are available and where they're expected. Run grafema upgrade to clean stale artifacts and download fresh binaries.

"error while loading shared libraries: libyaml-0.so.2" (Linux slim containers)

On minimal Linux images (e.g. node:22-slim, Alpine-based containers), the libyaml C library may not be present, causing resolution to fail:

grafema-resolve: error while loading shared libraries: libyaml-0.so.2: cannot open shared object file
build-index request failed: Broken pipe

Workaround until a statically-linked binary is available:

apt-get install -y libyaml-0-2

On Alpine: apk add libyaml. On standard Ubuntu/Debian developer machines, libyaml-0-2 is installed by default — this affects slim/minimal images only.

Upgrading from an older version Run grafema upgrade to remove stale binaries from ~/.grafema/bin/ and download the current versions. Use grafema upgrade --lang js,python to install only specific language analyzers.