nogra✓
Install free

{ 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.

$claude plugin marketplace add nograai/nogra-claude-marketplace
$claude plugin install nogra@nogra-claude

Then open Claude Code inside a project and run /nogra:status to confirm the plugin is visible. Full walkthrough on the install page.

The MCP layer.

The plugin bundles Nogra's own MCP server. On first start, Claude Code launches it with npx @nograai/mcp — standalone binaries fetched from npm, running locally, exposing the brief, run, and verification contracts as tools. Auth stays first-party; the server never sees your credentials.

No prerequisites: Node ships with Claude Code, so npx is always there. If you prefer the PyPI path, uvx nogra-mcp works as a fallback — the launcher tries npx, then uvx, then pipx, and never installs anything itself.

Install = get the brain.

The memory layer.

Nogra's memory is two plain markdown files you own: USER.md — who you are, bounded at 1,375 characters — and MEMORY.md — what matters, bounded at 2,200. They live under .nogra/memory/local/ in your repo, and both are loaded into every session at start, deterministically — memory that rides in context, not advice that gets deprioritized.

The bound is the point. Full doesn't mean forgetting by accident — it means consolidating deliberately: merge what survives into a sharper theory of you, drop the transcript noise. Claude does the remembering. Nogra owns the bound.

Hoarding is not memory.

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.

  1. 01

    Set up the workspace.

    /nogra:setup

    Creates .nogra/ in your project root. This is local markdown and JSON state: briefs, receipts, evidence, checkpoints, decisions, and current tasks.

  2. 02

    Ask for a brief.

    /nogra:brief Build a small local task tracker in this workspace.

    Nogra turns the request into a scoped contract: what is in, what is out, what evidence is required, and when the run should stop.

  3. 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.

  4. 04

    Dispatch only after approval.

    GO

    After you approve the brief, dispatch runs a fresh executor role against that approved scope and writes a run receipt.

  5. 05

    Verify the result.

    /nogra:verify

    The verification pass checks output and files against the brief. The executor's own claim is never enough by itself.

  6. 06

    Checkpoint what changed.

    /nogra:status

    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: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: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.

.nogra/runs/run-7c3everified

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.json always 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-plugins in 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.

{ Ready when you are }

Install the plugin, then pull Nogra in.

Install NograWhat Nogra is