usegrain

Grain — memory layer for design engineers. One command.

Get started

npx usegrain

Walks you through the whole setup: sign in with GitHub, pick a repo target (new repos or attach to one you already own), invite teammates by GitHub username, and launches the TUI. No env vars, no client IDs, no side trips to a separate auth tool.

Already inside a Grain instance? npx usegrain opens the TUI instead of re-running setup.

Authentication

Grain uses a three-tier auth chain so it works on any machine:

1. gh CLI — if you've already run gh auth login, Grain reuses that token. Zero friction.
2. Hosted Grain GitHub App — first-time users hit GitHub's Device Flow against the public Grain App. Click Authorize in the browser; that's it. No registration, no env vars.
3. Self-hosted override — set GRAIN_GITHUB_CLIENT_ID to point Grain at your own OAuth/GitHub App. See docs/github-app.md.

grain doctor reports which tier is currently active.

Common commands

npx usegrain                     # one-command setup wizard (or open TUI)
npx usegrain new my-project      # scripted scaffold (no prompts)
npx usegrain join <owner>/<slug> # accept an invitation, clone, welcome
npx usegrain start               # load shared context
npx usegrain save "fix hero"     # commit instance + memory
npx usegrain brief "<title>" --body "<intent>" --active
npx usegrain --where             # print resolved instance path

Or install once and drop the npx:

npm i -g usegrain
grain

Inviting teammates

Inside a Grain instance:

grain invite <github-username>

Grain adds the user as a collaborator on both the instance and memory repos, then prints a one-liner the teammate can run:

npx usegrain join <owner>/<slug>

The invitee gets a polished welcome: who invited them, the active brief title, the latest handoff, and an inline tour of capabilities. Their GitHub username is auto-added to memory/people/.

What it makes

npx usegrain (new-repo path) creates two sibling repos:

• my-project-instance/ — hooks, scripts, agent rules, bin/grain
• my-project-memory/ — your shared markdown memory (taste, brief, voice, references…)

The instance symlinks memory/ → ../my-project-memory. Both are git repos, committed independently with npx usegrain save "<msg>".

Attaching to an existing repo

The wizard's option 2 ("Attach to an existing repo I own") layers Grain onto a repo you already have. It clones the repo into <slug>-instance, adds Grain's hooks and slash commands, creates a sibling <slug>-memory repo on GitHub, and wires both. Use this when your codebase already lives somewhere and you just want Grain next to the code, not a fresh project.

You can also do this after the fact from inside an instance:

grain attach <owner>/<repo>

How it finds your instance

Resolution is strictly cwd-local. There is no global default — running npx usegrain in a folder that isn't part of any Grain instance will open the wizard to scaffold one for that project, never silently load a different project's instance.

1. $GRAIN_HOME env var (explicit per-shell override)
2. Nearest ancestor of cwd containing grain.md + bin/grain-tui
3. A unique sibling *-instance folder directly under cwd

If none of those resolve, usegrain runs the new-project wizard.