Grainulator

Evidence and verification for the model you already use.

Keep the evidence. Challenge the answer. Know what to do next.
A shared workflow for research, engineering, and model-assisted work.

Quick start · Installation · Upgrading · Tools · Agent setup · Changelog

What it adds

Good models still need a way to keep track of evidence, revisit assumptions, and verify their work. Grainulator gives them that process, with a local ledger that stays with the task as it moves between models and sessions.

One package, one MCP server. Use the CLI, connect an MCP-compatible agent, or load the bundled Claude Code or Codex plugin. The consolidated components are included; separate ecosystem installations are not required.

Quick start

Requires Node.js 24+. Node 25 is the development default.

Upgrading from 1.x? Follow the migration checklist to update the correct plugin scope, reconnect the single MCP server, and review retired Farmer instructions without changing your research data.

git clone --branch v2.0.2 https://github.com/grainulation/grainulator.git
cd grainulator
npm ci --ignore-scripts
node bin/grainulator.js doctor
node bin/grainulator.js preview

Open localhost:4517/playground/ to choose your model, configure the workflow, and run research with your provider key.

Want to look around first? The public playground lets you explore the controls and export a setup. Model execution happens in your local installation.

Distribution: v2.0.2 is a GitHub release, not an npm registry release. For a separate local installation, follow the archive installation guide.

Connect your agent

From the project you want Grainulator to access:

node /path/to/grainulator/bin/grainulator.js connect --dir "$PWD"

Register the printed MCP configuration in your host, then restart its connection. The command prints configuration; it does not change your host settings.

For bundled skills, agents, and hooks, use the native plugin setup guide. Native Codex needs an explicit workspace: run node /path/to/grainulator/bin/grainulator.js setup --dir /absolute/project once, then restart Codex. A per-launch GRAINULATOR_WORKSPACE overrides that saved default. CLI and direct MCP access remain available to other hosts.

Put it to work

With Grainulator connected, give your agent the outcome you need:

Use Grainulator to investigate whether we should migrate this service. Record the evidence, challenge the assumptions, implement the agreed changes, and verify them. Keep the remaining next steps split into Auto and Manual.

The work follows a simple cycle:

1. Record findings with their sources and evidence tiers.
2. Check for conflicts, weak support, and missing perspectives.
3. Act on the gaps that matter, then verify the requested result.
4. Continue from the saved ledger or export the session to another workflow.

There are no fixed claim-count or research-pass quotas. Auto lists work the agent can continue within your authorization. Manual lists decisions, access, or actions that need you. When you ask only for next steps, those two lists are the entire response.

node bin/grainulator.js init --dir ./sprints/migration \
  --question 'Should we migrate this service?' \
  --audience engineers --constraints 'Preserve existing user data' \
  --done 'A verified plan with remaining risks documented'

node bin/grainulator.js add --dir ./sprints/migration \
  --id r001 --type constraint --topic migration \
  --content 'Existing user data must remain readable.' --evidence stated

node bin/grainulator.js compile --dir ./sprints/migration

Explore the docs

Verification and limits

CI checks Node 24 and 25, isolated package installation, plugin contracts, Rust runtime conformance, lint, and the static playground in a browser. Native host and live-provider acceptance have separate verification guides.

The compiler checks the structure and support recorded in the ledger; it does not establish that a source is true. Evaluations do not establish a general accuracy or efficiency gain, and per-pass limits are not a whole-session spending cap. Keep those distinctions when interpreting results.

npm test
npm run test:install
npm run lint

Built by Grainulation · MIT licensed · Issues & ideas