# Grum setup

Read this guide before running anything. Retrieve it at https://app.grum.so/agent with a command or network tool, not browser automation.

Use the CLI in your command tool for Grum's operational steps: inspecting the repository, linking or creating a workspace, scanning, and writing agent configuration. Retrieve this guide and perform those setup operations through command or network tools. Use the browser for sign-in, device-code approvals, GitHub authorization, editor trust, and connecting Grum's browser extension. You may also open a page in the agent's visible browser when you want the person to see the page you are referring to or asking them about, including local app previews. Use available browser control yourself; ask the person to open a page and confirm it renders only when browser control is unavailable or cannot access that page. If browser control is unavailable, give the person the exact URL and the next step, and continue independent checks.

Grum needs Node.js 22 or newer. Check `node --version`. When Node is missing or older, send the person to https://nodejs.org/en/download and ask them to install it with the graphical installer, then restart the editor so the new version is visible. Check the version again. Do not ask them to type a shell command. Do not write a Node path into the repository.

Choose the adapter from the host you are running in: cursor, codex, claude (Claude Code), or generic when none of them applies. A generic agent can set up, check and request review, and must tell the person that automatic enforcement is unavailable. Do not enable an agent only because its folder exists.

Run `npx --yes --prefer-online @grum-os/cli@latest setup --agent <cursor|codex|claude|generic> --json` with stdin closed. Add `--root <dir>` for a monorepo package. A command run inside a package folder sends that folder when it creates a workspace, and a workspace that already has a folder uses it when `--root` and local config omit one. Read the JSON on stdout. Exit 0 is ready, exit 2 means take actions[0] and run the command again, exit 1 is a fault. Do not treat an unknown or offline check as ready. A source-read check means listing local files was slow or hit 15 seconds: tell the person. Grum skips videos and large images by name; do not invent a GitHub download or a different scan.

The result schema is 1. Fields are schema, state, open, server, repository, project, checks, actions and exit. Each action has a kind, an explanation, and input with a browser URL, a code, exact choice ids, or the next command. Never include a sign-in secret in chat.

States: needs-sign-in, needs-github, needs-project-choice, needs-workspace-create, needs-starter, scan-running, needs-local-app, needs-host-action, needs-site, needs-extension, ready, blocked. open lists every state that still applies.

scan-running: the call returns at once. wait-for-scan's input carries scanId, label, percent, step of steps, elapsedSeconds, heartbeatAgeSeconds, progressAgeSeconds, liveness (working, or quiet when Grum has not heard from the scan for 30 seconds) and retryAfterSeconds. Tell the person the label in one line, then run the command again after retryAfterSeconds. A recent heartbeat with unchanged progress means a slow step, not a stall. Never wait inside the call and never start another scan. A scan that stopped or failed comes back as blocked.

Design-kit project: a workspace can start from a design kit, with its contract and no code. The person's prompt gives its project id. Pass it as --project; setup connects this repository to it (action link-workspace, which the request already authorizes), then walks the repository to the starter. needs-starter has three actions. run-commands: run input.commands in order from the repository root with stdin closed; they ask nothing, and when one refuses because the folder has files in it, tell the person and stop. setup writes the contract's tokens and DESIGN.md itself. commit-and-push: Grum scans the default branch on GitHub, so the work must be there first. Run `npx --yes --prefer-online @grum-os/cli@latest check` (it should find no drift), tell the person what you will commit and where, and push only when they say yes. Then run setup again: it starts the first scan.

Live site: when the result asks for one, ask the person in chat. Offer the URLs the result lists, plus any production URL you find in the repository, and accept one they type. Pass --site <url>, or --site none when there is no live site. Never save a site they did not confirm.

Local app: Ask the person where the app runs locally before saving a URL. Repository hints and existing unconfirmed URLs are suggestions, never permission to choose index.html. Prefer the running dev server; a repo HTML file is an explicit static-page choice only. HTTP must return 200; report refused connections, timeouts, redirects and all other statuses without calling them ready. After a successful probe, open the chosen page visibly for the person, inspect its rendering, and report any error page or broken rendering. Only then acknowledge that exact URL with localPreviewed (MCP) or --local-previewed <url> (CLI). If browser access is unavailable, give the exact URL, ask the person to open it and confirm it renders, and acknowledge only after their reply. HTTP 200 alone does not prove the app renders. Pass --local-url <url or ./file.html> after the person chooses, or --local-url none only when they explicitly skip. Follow preview-local-app before declaring setup ready. Codex uses its visible browser panel; Cursor uses its visible browser; Claude Code uses an available visible browser or the person's confirmation. When setup is ready, tell the person the live site and local app that are saved.

Sign-in: show the code and the URL, ask the person to approve them in the browser, then run the same command again. It resumes. Do not wait in one call for the code to expire. When the browser cannot open, the URL in the result is enough.

GitHub access: when the result is needs-github (no GitHub login, or the repository is not found or access is denied), give the person the URL in the result. That one Grum page reconnects GitHub, links to Grum's Manage Access page on GitHub for connecting the repository, and says when Grum can read the repository. Then run the same command again.

No workspace yet: an explicit request to set up Grum authorizes creation. State that you are creating one for this repository, then re-run with --create without asking again. Several workspaces: ask which id to use and pass --project. Never pick the first. --site and --local-url accept a URL or none. Keep a saved site. Keep a local app that setup has already confirmed and previewed; an older saved URL must be confirmed with the person once. A local URL is saved only after a successful probe.

A server mismatch is a blocked result. Switch only when the person agrees, with --switch-server.

Daily work, once tools are loaded: grum_contract, grum_check, grum_request_review, grum_add_to_contract, grum_snooze_review, grum_review_status. When those tools are not in the chat, run `npx --yes --prefer-online @grum-os/cli@latest contract`, `npx --yes --prefer-online @grum-os/cli@latest check --json`, `npx --yes --prefer-online @grum-os/cli@latest request <key> --reason "..." --context "..." --url "<page>"`, `npx --yes --prefer-online @grum-os/cli@latest add-token <name> --category <c> --value <v> --key <key> --url "<page>"` or `npx --yes --prefer-online @grum-os/cli@latest add-button "<name>" --key <buttonDriftKey> --url "<page>"` when the signed-in person is an owner, and `npx --yes --prefer-online @grum-os/cli@latest snooze <key>`. Review status is the grum_review_status tool, or `npx --yes --prefer-online @grum-os/cli@latest doctor --agent <cursor|codex|claude|generic> --json` for readiness. A check with nothing cached has not run. Offline output is the saved contract, not a current server result. Pending and allowed reviews cover drift. A failed review request is not approval: report it and do not retry it unless the person asks. A rejected style is not approval: change the code to use the contract. A snooze pauses the question only: it is not approval, check still lists the drift, and it does not unblock a commit or push. Never edit .grum files to make a check pass.

Readiness: `npx --yes --prefer-online @grum-os/cli@latest doctor --agent <cursor|codex|claude|generic> --json`. A Grum MCP tool responding in this chat confirms the tools are available here. A shell doctor cannot inspect this chat's MCP connection; do not repeat its unconfirmed-tools warning after an MCP tool has responded. Finish setup verification with grum_doctor through MCP, discovering the tool by name first if needed. Ask the user to enable tools only when discovery or the connection actually fails, and report that failure. For published installs, use the explicit `@latest` package spec and `--prefer-online` in every operational CLI command: a bare `npx @grum-os/cli` can reuse a local or cached copy and does not prove it is current. To update an existing setup, run `npx --yes --prefer-online @grum-os/cli@latest setup --agent <cursor|codex|claude|generic> --json` again so the MCP server, hooks and agent guidance refresh. Hooks prefer the local/cache copy and can install on a cache miss. Unchanged hook definitions keep their trust; changed commands require review in Codex. Repair: take only the first action, then check again. Do not loop scans or review requests.

Sign out this computer: `npx --yes --prefer-online @grum-os/cli@latest logout`. Remove Grum from the editor you set up: `npx --yes --prefer-online @grum-os/cli@latest setup --agent <cursor|codex|claude> --remove --json`. That deletes Grum's files for that agent and leaves the other agent, the pre-commit check, the sign-in and the workspace. Add --no-pre-commit only when the person asked to drop the pre-commit check. Clear saved capture sign-ins: `npx --yes --prefer-online @grum-os/cli@latest capture reset`. Remove Grum completely, from this repository and this computer, only when the person asks for that: `npx --yes --prefer-online @grum-os/cli@latest uninstall --yes`. Deleting a workspace, an account or the contract is done in Grum, not by setup.

Configuration written, tools loaded, and hooks active are separate checks. After writing config, tell the person the editor step in the result immediately. Do not wait for the scan to finish first. Codex: Grum will not appear in Settings > MCP servers or Settings > Hooks until they trust this folder when Codex asks. Grum will not appear in Settings > MCP servers or Settings > Hooks until you do. Then in Settings > MCP servers, turn on the server named grum. If Codex labels it with this folder's name, pick the one whose command runs grum.mjs. Then if any of Grum's 3 commands (they say "need review" and run grum.mjs hook ...) are off, open Settings > Hooks for this project and allow them; this is separate from MCP servers. In the Codex terminal, run /hooks to review the list. Cursor: switch on "grum" in Cursor Settings > Tools & MCP (Cursor keeps a project's new tools off until then). Then start a new chat. Claude Code: trust this folder in Claude Code, approve the "grum" MCP server if it asks (/mcp shows whether it is connected), then start a new session.. The extension page is https://app.grum.so/extension. Connecting there is for pages behind a sign-in. The server saying the extension is connected is not proof it is installed in the browser that is open.
