noggin

A working-memory tree for in-flight work — your second brain for the stuff you can't fit in your head.

Items form a tree. There's at most one active item; the path from a root to the active item is your current spine. Other open items are paused. Done items stay in the tree under their parent so you can see what got finished. Lives in ~/.noggin.yaml by default; the YAML file is the source of truth.

📖 Full docs

This README is intentionally short. Everything else lives on the noggin docs site:

• Install — VS Code extension, agent plugin (Codex / Claude Code / GitHub Copilot CLI), bare CLI
• CLI reference — every verb, every flag, generated from the binary
• Verb demo — side-by-side human vs JSON output, real CLI runs
• MCP server — tools the agent sees over stdio
• Document schema — the NogginDocument shape and invariants
• Response envelope — JSON wrapper around every CLI / MCP / LM-tool response
• Playground — try noggin in your browser, no install

Agent-facing instructions live in SKILL.md. The TypeScript declarations for the in-process API are in noggin-api.d.mts.

Quick start

# Install the CLI (and the MCP server bin) globally
npm install -g noggin-cli

# Or run ad-hoc via npx
npx -y noggin-cli noggin push "ship v1"
npx -y noggin-cli noggin show

The package ships two bins:

• noggin — the working-memory tree CLI
• noggin-mcp — a stdio MCP server exposing the same verbs to agent hosts (Codex, Claude Code, GitHub Copilot CLI, VS Code MCP)

For MCP wire-up examples and host-specific config paths, see the MCP page and the plugin distribution README.

License

MIT.