Ribbit

Generate an AI-readable knowledge graph of your codebase.

Ribbit scans your project, parses every file with tree-sitter, and outputs a structured JSON graph of all files, symbols, and relationships — plus a handoff file summarising recent activity. Together they give any agent complete context: what the code is, and what just happened to it.

Features

• ⚡️ Blazing Fast Incremental Builds: Uses xxhash-wasm to fingerprint files. On re-runs, only modified files are parsed, completing most updates in under 500ms.
• 🧵 Multi-Core Parallel Parsing: Leverages Node.js worker_threads to parse your codebase concurrently across all available CPU cores.
• 🌳 Deep Semantic Understanding: Powered by tree-sitter for flawless AST-based parsing of TypeScript, JavaScript, and Python.
• 🧠 AI-Optimized Output: Automatically calculates "centrality" metrics so LLMs and coding agents know which files are the most critical in your architecture.
• 📋 Handoff File: Auto-generates a human & agent readable summary of recent git activity, function-level diffs, and dependency impact analysis.
• 📦 Smart Auto-Chunking: Small projects get a single index.json. Large projects (>200 files) are automatically split into a chunked module directory structure to prevent context window overflows.
• ⚙️ Highly Customizable: Easily exclude directories, toggle test files, or focus on specific languages via ribbit.config.js.

Quick Start

# Install
npm install @aryaneelshivam/ribbit
npx @aryaneelshivam/ribbit

# Add the script to your package.json
# "scripts": { "ribbit": "ribbit" }

# Run
npm run ribbit

Or run directly:

npx @aryaneelshivam/ribbit

What Gets Generated

Running ribbit produces two outputs inside a ribbit/ folder:

npm run ribbit
→ updates ribbit/index.json       (the structural graph)
→ updates ribbit/handoff.md       (what changed recently)

Here's how it sits in your project:

my-project/
├── src/
│   ├── auth/
│   │   └── middleware.ts
│   ├── db/
│   │   └── client.ts
│   ├── routes/
│   │   └── api.ts
│   └── utils/
│       └── logger.ts
├── package.json
├── ribbit.config.js
└── ribbit/                      ← Generated by Ribbit
    ├── index.json               ← full structural graph
    └── handoff.md               ← recent activity summary

Small codebases (< 200 files) → single file + handoff:

ribbit/
  index.json          ← full graph: files, symbols, relationships
  handoff.md          ← git activity, diffs, impact analysis

Large codebases (≥ 200 files) → chunked + handoff:

ribbit/
  index.json          ← meta + file map (always small)
  handoff.md          ← git activity, diffs, impact analysis
  modules/
    auth.json         ← one file per top-level directory
    payments.json
    utils.json
  relationships.json  ← cross-module edges

Handoff File

Every time you run ribbit, alongside the graph it generates a handoff.md — a human and agent readable summary of recent activity in the codebase. It bridges the gap between the structural graph (what the code is) and the activity log (what changed recently).

What it captures

| Section | Description | |---------|-------------| | Recent activity | Which files changed in the last N commits, who changed them, when, and commit messages | | What changed | Function-level diff — which functions were added, removed, or modified; import & export changes | | Impact analysis | Which files depend on changed files, high-centrality risk flags, broken edge detection | | Agent context | Plain-English summary an agent can read instantly to understand what happened since the last session |

Sample output

# Ribbit Handoff — 2026-05-09T10:00:00Z

## Recent activity (last 5 commits)

| File | Changed by | When | Commit |
|---|---|---|---|
| src/auth/middleware.ts | @dan | 2h ago | refactor: JWT validation |
| src/db/client.ts | @sara | 5h ago | feat: connection pooling |
| src/routes/api.ts | @dan | 1d ago | feat: add /payments route |

## What changed

### src/auth/middleware.ts
- Modified: `authMiddleware` (logic changed)
- Added: `refreshToken`
- Removed: `legacyAuth` ← still called by src/admin/panel.ts ⚠️

### src/db/client.ts
- Modified: `db.query` (now async pool)
- Added: `db.pool`, `db.disconnect`

## Impact
- `authMiddleware` is depended on by 4 files — changes here are **high risk**
- `legacyAuth` was removed from `src/auth/middleware.ts` but `src/admin/panel.ts` still references it ⚠️

## Agent context
Auth was refactored 2h ago — JWT now handled differently.
DB client now uses connection pooling, all queries are async.
New /payments route added. Legacy auth removed but may cause
a broken import in admin panel — investigate before proceeding.

Output Format

{
  "meta": {
    "generated": "2026-05-08T10:00:00Z",
    "version": "1.0.0",
    "files": 847,
    "nodes": 12453,
    "edges": 34821,
    "parseTime": 1200,
    "incremental": true
  },
  "files": {
    "src/auth/middleware.ts": {
      "exports": ["authMiddleware", "validateToken"],
      "imports": ["src/db/client.ts", "src/utils/logger.ts"],
      "language": "typescript",
      "centrality": 0.87,
      "hash": "a1b2c3d4",
      "lastModified": 1715000000,
      "size": 4821
    }
  },
  "symbols": {
    "authMiddleware": {
      "file": "src/auth/middleware.ts",
      "type": "function",
      "calls": ["db.query", "logger.log"],
      "calledBy": ["src/routes/api.ts"]
    }
  },
  "relationships": {
    "src/auth/middleware.ts": {
      "dependsOn": ["src/db/client.ts"],
      "dependedOnBy": ["src/routes/api.ts"]
    }
  }
}

How to Reference in IDE Agents

Point your AI agent to both files for complete context:

@ribbit/index.json       ← full structural context
@ribbit/handoff.md       ← what changed since last session

[!IMPORTANT] Cursor & Copilot Workaround IDE AI agents will completely ignore files listed in your .gitignore. If you add ribbit/ to your .gitignore, you will not be able to tag it with @ribbit.

To fix this: Do not add ribbit/ to your .gitignore file. Instead, manually ensure you do not git commit the folder, or add it to .cursorignore (if your IDE supports divergent ignore files).

The centrality scores tell agents which files and symbols are most important — entry points, shared utilities, and core models will have high centrality. The handoff file tells them what's been actively changing so they can prioritise accordingly.

CLI Options

| Flag | Description | |------|-------------| | ribbit | Default: runs full or incremental build | | --full | Force complete re-parse, ignore previous graph | | --stats | Print graph stats to console, don't write files | | --config <path> | Path to custom ribbit.config.js | | --version | Print version | | --help | Show help |

Configuration

Create a ribbit.config.js in your project root (auto-created on first run):

module.exports = {
  // Glob patterns to ignore
  ignore: [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/__tests__/**",
    "**/dist/**",
  ],

  // Languages to parse
  languages: ["typescript", "javascript"],

  // Output directory
  output: "ribbit/",

  // File count threshold for chunked output
  chunkThreshold: 200,

  // Include test files in the graph
  includeTests: false,

  // Include dotfiles
  includeDotFiles: false,

  // Handoff file generation
  handoff: {
    enabled: true,       // generate the handoff file
    commits: 10,         // how many commits to look back
    includeDiffs: true,  // include function-level diff analysis
    includeImpact: true, // include dependency impact analysis
    format: "markdown",  // "markdown" or "json"
  },
}

Incremental Builds

Ribbit uses xxhash to fingerprint every file. On re-runs, only files whose content has changed are re-parsed — everything else is carried forward from the previous graph. This makes re-runs extremely fast even on large codebases.

Performance

| Scenario | Target | |----------|--------| | First run — 10k lines | < 0.5s | | First run — 100k lines | < 3s | | First run — 1M lines | < 20s | | Re-run — 10 changed files | < 500ms |

Supported Languages

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx, .mjs, .cjs)
• Python (.py)

Roadmap

• [x] Handoff File: Auto-generated activity summary with diff and impact analysis.
• [ ] Phase 2: --watch mode for automatic re-runs on file changes.
• [ ] Phase 3: MCP server for real-time graph queries.
• [ ] Phase 4: Additional language support (Go, Rust, Java).

Author

Aryaneel Shivam

License

This project is licensed under the MIT License - see the LICENSE file for details.