Develop, test, debug, and deploy KurrentDB projections.

KurrentDB projections are server-side JavaScript that derive new streams and state from existing events. Gaffer runs them locally against the same JavaScript engine KurrentDB uses, so a projection that passes here passes in production.

Install

npm install -g @kurrent/gaffer

Requires Node.js 22 or later. Platform binaries are pulled in as optional dependencies; no separate runtime install is needed.

Quick start

Try the bundled demo:

git clone https://github.com/kurrent-io/gaffer
cd gaffer/demo
gaffer dev order-count --fixture happy

The CLI replays the events declared as fixtures.happy in demo/gaffer.toml through the order-count projection and prints the resulting state. No running KurrentDB instance is needed.

Or start a new project from scratch:

gaffer init                  # create gaffer.toml and .gaffer/
gaffer scaffold order-count  # add projections/order-count.js

See the getting started guide for a full walkthrough including fixtures, editor setup, and the dev loop.

Commands

| Command | What it does | | -------------------------- | --------------------------------------------------------------------------- | | gaffer init | Create gaffer.toml, .gitignore, and .gaffer/ in the current directory | | gaffer scaffold <name> | Add a new projection to the project | | gaffer dev <projection> | Run a projection against fixtures, an events file, or a live KurrentDB | | gaffer info <projection> | Show projection details | | gaffer mcp | Start an MCP server for AI agent integration | | gaffer lsp | Run the Language Server Protocol server over stdio | | gaffer config | Manage user-level configuration (telemetry, identity) | | gaffer version | Print the gaffer version |

Run gaffer <command> --help for flags and options, or see the full command reference.

Configuration

Project settings live in gaffer.toml at the project root:

connection = "kurrentdb+discover://localhost:2113"
engine_version = 2

[[projection]]
name = "order-count"
entry = "projections/order-count.js"
fixtures.happy = "fixtures/orders.json"

User-level settings (telemetry opt-out, identity) live in ~/.config/gaffer/config.toml and are managed with gaffer config. See the configuration reference for every option.

Editor integration

Gaffer ships with Language Server Protocol and Debug Adapter Protocol servers, plus a VS Code extension that wires them up automatically.

• VS Code - install the KurrentDB Projections extension for inline diagnostics, run/debug codelens above gaffer.toml projections, and breakpoint debugging.
• Other editors - run gaffer lsp over stdio for LSP integration. See the editor setup guide for examples.

AI agent integration

gaffer mcp exposes scaffolding, validation, debugging, and the projection API as Model Context Protocol tools and resources. Compatible with Claude Code, Cursor, Continue, GitHub Copilot, and any other MCP client.

See the MCP integration guide for client setup.

Related packages

| Package | What it is | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | @kurrent/projections-testing | Library for testing projections from your existing test runner (vitest, jest, mocha) | | KurrentDB Projections for VS Code | Editor integration with debugger, codelens, and MCP server |

Telemetry

Gaffer collects anonymous usage telemetry by default. See TELEMETRY.md for the full list of what is collected and how to opt out (gaffer config telemetry off).

Documentation

Full documentation at https://docs.kurrent.io/gaffer/.

Bugs go to GitHub Issues. Questions and feature requests to Discussions.

License

Kurrent License v1