// docs·01

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.

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

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 Reinstall Grafema (npm install -g grafema) and ensure the install directory is on your PATH.

← Back to docs