{ Docs }
How to use Nogra.
Nogra is pull-first. Ordinary chat, direct edits, debugging, and implementation stay direct unless you ask for Nogra. Use it when the work needs a plan, approval, evidence, and a local record of what happened.
Install.
Then open Claude Code inside a project and run /nogra:status to confirm the plugin is visible. Full walkthrough on the install page.
Pure local.
The plugin is a local Node runtime plus hooks — nothing else phones home. No bundled MCP server, no cloud calls, no telemetry. The brief, run, and verification contracts run on your machine, and auth stays first-party: Nogra never sees your credentials.
No prerequisites beyond Claude Code: Node ships with it, and the runtime installs nothing of its own. The hosted layer — MCP tools, sync across devices — arrives with Sync, opt-in and later. The free plugin stays entirely on your machine.
Nothing leaves your machine.
The memory layer.
Durable memory is Claude Code's own native Auto Memory — a MEMORY.md index plus typed topic files under ~/.claude/projects/<slug>/memory/. Claude writes it and loads it itself, every session. Nogra keeps no copy and never loads it for you.
What Nogra owns is the bound. It reads the memory read-only at session start, and once it has grown past the load window — the first 200 lines of the index, or 16,000 characters across the folder — it nudges you to consolidate: merge duplicates, prune the stale, keep the theory of you sharp. Never a hard cap, never a truncation — a consolidation, on purpose.
Hoarding is not memory.
The brain/ vault.
Alongside memory, your workspace ships a brain/ vault — a knowledge base for deep work. raw/ source drops compile into wiki/ pages, catalogued in index.md. Where memory is the bounded theory of you that rides along always, the brain is deep knowledge you pull in only when a session needs it.
It's pull-first by design: never auto-loaded, so the heavy material lives in the vault instead of your context. Remove it and /nogra:brain-init scaffolds it back.
Memory rides along. The vault waits to be opened.
Choose the right flow.
Stay direct for ordinary questions, small edits, routine debug help, and normal implementation where you do not need a durable approval trail.
Pull Nogra in when the work is scoped, risky, or needs a record that another session can inspect. For complex work, shape the orchestration first — then write the brief.
First Nogra run.
- 01
Set up the workspace.
Creates .nogra/ in your project root. This is local markdown and JSON state: briefs, receipts, evidence, checkpoints, decisions, and current tasks.
- 02
Ask for a brief.
Nogra turns the request into a scoped contract: what is in, what is out, what evidence is required, and when the run should stop.
- 03
Review before GO.
Read the brief. If scope, evidence, or risk boundaries are wrong, fix the brief before dispatch. A demo request, preview, or idea selection is not GO.
- 04
Dispatch only after approval.
After you approve the brief, dispatch runs a fresh executor role against that approved scope and writes a run receipt.
- 05
Verify the result.
The verification pass checks output and files against the brief. The executor's own claim is never enough by itself.
- 06
Checkpoint what changed.
Use status to inspect local ledger and checkpoint freshness before continuing in the next session.
Commands.
/nogra:setupInitialize local .nogra/ state in the current workspace./nogra:brain-initScaffold or restore the brain/ deep-work vault (raw → wiki) — re-creates it if you've removed it./nogra:statusShow installed plugin version, workspace id, recent records, and checkpoint freshness./nogra:briefShape a scoped work contract before dispatch./nogra:dispatchRun an approved brief after you have reviewed it and said GO./nogra:authorizeGrant a risk boundary class a standing GO so the gate stops asking within it./nogra:verifyCheck returned work against the brief and evidence instead of accepting a self-report./nogra:adaptMap an existing project into Nogra's local workspace records./nogra:createCreate a project-local Nogra workspace under a hub./nogra:settingsInspect or adjust language and runtime preferences./nogra:updateRefresh installed Nogra guidance without starting work./nogra:watchInspect recent local hook events when you need to see what Nogra observed./nogra:helpChoose the right Nogra route when you are unsure.
What gets written.
Nogra writes local workspace records under .nogra/ — plain markdown and JSON: briefs, transport records, evidence, checkpoints, decisions, and current tasks. You can read them, delete them, or commit them with your project.
brief · brief-014
scope: a local task tracker
evidence: tests pass · work committed
dispatch · fresh executor
receipt returned — no parent context to defend
verify · separate pass
OK — output matches the approved brief
The work leaves a record, not a memory.
What Nogra never auto-approves.
Auto-approval is off by default. When you opt in, it runs on provenance — a deterministic match against a receipt you approved — and every auto-approval names its source: "approved rm — in scope of your GO, receipt #id." Some doors never open automatically, no matter what:
- Changing the gate's own rules. Writes to
.nogra/config.jsonalways reach a human. No receipt, no active intent, and no automation can approve the gate arming itself. - Executing code. Running a script always asks — even one that lives inside the run's own sandbox. An exec's effects are not bounded by where its arguments point.
- The gray zone. Anything not deterministically covered by your GO asks. There is no model judgment in the gate — no classifier deciding what you probably meant.
Provenance decides. Humans decide the rest.
Troubleshooting.
- If a command is missing, run
/reload-pluginsin Claude Code and check/nogra:status. - If the wrong workspace appears, run status from the project root and inspect the local
.nogra/folder. - If a run returns partial or blocked, keep the reason. Do not mark the work done until verification has evidence against the brief.
- If the completion-claim nudge is noise in a workspace that already runs the full verify loop, set
verifyNudge: "off"at the top level of.nogra/config.json. Default stays on.