Take your setup.
Keep going.

01 / Before you start

Run Grainulator 2.0.2.

Use Node.js 24 or later; Node 25 is the dogfood default. Get the tagged source from the v2.0.2 GitHub release. This GitHub release is not published to npm; installing the currently released npm package does not select it.

Upgrading from 1.x? Follow the migration checklist for plugin scopes, the single MCP server, and existing data.

The public playground configures and exports sessions. Model execution happens through your local server or CLI. There is no public research backend to sign into.

02 / Source checkout

Open the local playground.

Clone the release tag. Tagged builds include a release identity and file checksums that doctor verifies:

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 http://127.0.0.1:4517/playground/ and choose Open session. Select your exported JSON file and enter your provider key locally, or configure OPENAI_API_KEY or OPENROUTER_API_KEY in the server environment.

03 / Local archive

Install the exact build.

From the full source checkout, create an identified archive:

npm run pack:local

The command prints the archive path and a unique local version such as 2.0.2-local.<hash>. It also saves the report to .dogfood/builds/latest.json. The checkout's public version stays unchanged; nothing is published.

In a new, empty folder, replace <archive> below with the full archive path printed by that command. Use its unique filename, not an older tarball.

npm init -y
npm install --offline --ignore-scripts "<archive>"
node node_modules/@grainulation/grainulator/bin/grainulator.js doctor --json

Check that build.id and build.version match the report and build.verified is true. Doctor verifies packaged file checksums from build-info.json. Then start the installed preview:

node node_modules/@grainulation/grainulator/bin/grainulator.js preview

The archive includes its runtime modules and needs no sibling repositories. This installs locally and does not change your global tools.

04 / Activate updates

Update the copy you actually run.

Your source checkout, npm installation, and host plugin cache are separate copies. Source fixes do not update an installed app or a running session.

Stop your installed preview, install the newly printed archive from its consumer folder, verify the build ID with doctor, and restart. For a plugin, reinstall the intended local build, reload it in the host, and use a fresh test session.

The bundled Claude marketplace entry does not pin your local artifact. Use the tagged checkout or identified archive, and verify the loaded build. Follow docs/PLUGIN-TESTING.md in the checkout or installed archive for local plugin setup and full acceptance checks, including skills, agents, hooks, and the actual loaded cache.

Using the native Codex plugin? Save an existing project folder with the installed build, then restart Codex:

node /absolute/path/to/grainulator/bin/grainulator.js setup --dir /absolute/path/to/project

This saves ~/.config/grainulator/workspace.json without changing host settings and works for Codex Desktop after restart. It is the shared default for your native sessions. For one launch, GRAINULATOR_WORKSPACE=/absolute/path/to/project codex overrides it. Missing or invalid configuration leaves tools available for discovery but prevents workspace access.

For direct MCP access instead, run node /absolute/path/to/grainulator/bin/grainulator.js connect --dir /absolute/path/to/project and register the printed connection in your host. That connection uses the explicit folder and needs no Codex workspace variable; it does not load or verify bundled plugin skills or hooks. Claude's plugin registration does not require this Codex-specific variable.

05 / Continue

Resume the work you already have.

From a source checkout, run:

node bin/grainulator.js research --session /path/to/session.json --dir ./continued-session

For a local archive installation, replace bin/grainulator.js with node_modules/@grainulation/grainulator/bin/grainulator.js. Use a new output directory. Completed passes are reused; the API key field is excluded from exported files. Provider charges apply when you run models.

For an authenticated compatible endpoint, configure a local environment variable such as MODEL_API_KEY, then add --api-key-env MODEL_API_KEY to the research command. Pass the variable name, never the key itself. Compatible endpoints do not inherit your OpenAI or OpenRouter environment keys, and exported sessions do not contain credentials.