notric
v0.7.0
Published
notric CLI and MCP server — the source of truth for your project's domains, whiteboards and documents.
Maintainers
Readme
notric
CLI and MCP server for notric — the shared context of your system: business rules, flows, system views, changes, and the map from code paths to the knowledge that governs them.
notric is agent-first and human-supervised. Agents are the primary users: they read the context before changing code, work under a Change, and write back what the work discovered. Humans observe, review, approve, correct, investigate and decide what needs human authority, in the web app — the human control plane. A team can go days without opening it; that is the system working. Claude Code runs on your machine and uses this CLI as an MCP server (stdio) and through direct commands.
curl -fsSL https://app.usenotric.com/install.sh | NOTRIC_API_KEY=ntk_... sh
export PATH="$HOME/.notric/bin:$PATH"
notric projects create "acme-api"Run it inside the repository: it creates the project and connects this folder in the same step
(.notric/project.json and the notric MCP server in .mcp.json). Already have the project?
notric projects list inside the repository lists them numbered and asks which one this folder
is. Outside a terminal nothing is asked and nothing blocks; --no-init only creates the project.
Prefer a personal key (web app → Account → Personal API keys). It acts as you: the versions
you push carry your name and your permissions, and the history reads Ana S. via CLI. An agent
key is for automation with no person behind it, and its versions are attributed to the key's
agent user.
$ notric login
Logged in as Ana S. (personal key) — https://api.usenotric.com, organization Acme, key "laptop-ana", scope write.Linking the folder registers the MCP server (.mcp.json) and records the project in
.notric/project.json — every CLI command and MCP tool falls back to it, you never pass a
project id inside the repository. That is enough: the MCP server itself hands the agent its playbook and the session
brief through the initialize handshake, so there is no CLAUDE.md block or skill file to write
or keep in sync anymore.
notric hooks install (or --hooks on projects create) additionally installs a PreToolUse
hook that tells the agent which context governs a file before it is edited — a belt-and-suspenders
nudge for harnesses that support it, since the playbook already tells the agent to read the context
first. Linking again is idempotent; a hook installed on the older PostToolUse event is migrated
to PreToolUse, keeping its command and leaving your other hooks alone. notric hooks remove
takes the hook out, and notric clean removes what an older install left behind — the CLAUDE.md
block, the skill and the notric hooks — without touching anything else.
Configuration
~/.notric/config.json stores { apiUrl, apiKey }. NOTRIC_API_URL and NOTRIC_API_KEY
override it. The default apiUrl is https://api.usenotric.com (production); for local
development, point it at your own instance with notric login --url http://localhost:3000
or NOTRIC_API_URL=http://localhost:3000.
Commands
notric me
notric projects list | projects create <title> [-d]
notric domains list <project> | domains create <project> <name> [--parent <id>] [-d]
notric docs list <project> [--limit <n>]
notric doc get <ref|id> [--project <id>] [--graph] [--json]
notric doc create <project> --ref OS-03 --title "…" [--kind story] [--parent <ref>]
[--domain <id>] [--critical] [--code-path a.ts] [--body-file f.md]
notric doc update <ref|id> [--title "…"] [--status draft|active|superseded] [--critical yes|no]
notric doc set-ref <ref|id> --provider jira --key ABC-123 --url https://…
notric doc push <ref|id> --body-file f.md --bump minor -m "…"
notric doc search <project> <term>
notric wb list <project> | wb get <id> | wb set-context <id> <context|none>
notric context --path <file> [--intent bug_fix|new_behavior|unexplained_divergence|unknown]
notric context get <ref> [--depth summary|working|full] | context create <domain> <title>
notric guardrails [project] --path <file> [--intent <intent>] | --target <kind:id>
notric decisions list [project] [--status …] [--effective] [--active]
notric code-map [project] | code-map add|remove|set <target> <paths…>
notric attention [project]
notric tree <project> [--limit <n>]
notric blocked <project>
notric import <file.md...> --project <id|title> [--source v3] [--json]
notric projects create <title> [--no-init] [--hooks] [--hook-mode ask|inform]
notric projects list (in a repository with no link yet: pick one and connect it)
notric hooks install [--mode ask|inform] | hooks remove
notric clean (remove what an older install left in the repository)
notric sync [--project <id>]
notric mcpHuman-readable output by default; --json where it makes sense.
Bug or Change
Before changing governed code, classify the work and say so with --intent — this is the whole
point of the guardrail:
| --intent | When | What follows |
| --- | --- | --- |
| bug_fix | A Current Rule says what should happen and the code does not | Fix the code. No Change: you are restoring a truth that already exists. |
| new_behavior | The code matches the rule and the request wants something else | Open a Change — the truth itself is changing. |
| unexplained_divergence | Code and knowledge disagree with nothing explaining it | Investigate, then hand it to a human. |
| unknown (default) | Not classified yet | The answer is INTENT_REQUIRED plus the Current Rules to compare against. |
notric guardrails --path <file> without --intent refuses to guess for you.
Approving is a human act. notric decision status <ref> approved answers 403
(APPROVAL_REQUIRES_HUMAN) unless the organization issued the key with the approve scope. Leave
the Change proposed and say what is waiting.
Importing a specification
notric import sends whole Markdown files to the project: every section with a code
(OS-03, R-12, DEC-04) becomes a document, domains come from the headings and a body that
changed produces a new version. Files are imported in the given order, so the sequence
produces the history:
notric import spec-v2.md spec-v3.md --project elionOS --source v2/v3The output summarizes created, versioned, skipped (with the reason) and domains.
Blocks
A business rule blocks a story with @[label](blocks:<documentId>) in the rule's body. While the
rule is unsettled (draft, or the legacy open), the story shows up in notric blocked <project>
and in notric doc get <ref> --graph (the "Blocked by" section).
Versioning
Every document is versioned with semver. The bump is patch for a text change, minor for
additions and major for removals — the server rejects patch when it detects a removal and
returns the suggestion. A document marked as critical saves the version as proposed until an
owner approves it.
Mentions
The Markdown body wires the document into the graph:
@[Owner sees stores](node:<whiteboardId>/<nodeId>)— whiteboard node@[OS-01 · Work order opening](doc:<documentId>)— another document
notric doc get <ref> --graph shows the neighborhood: domain, parent/children, what the document
mentions and who mentions it.
MCP tools
notric_me, notric_tree, notric_projects_list, notric_domains_list,
notric_domains_create, notric_docs_list, notric_doc_get, notric_doc_create,
notric_doc_update, notric_doc_push, notric_doc_search, notric_blocked,
notric_wb_list, notric_wb_get, notric_wb_push, notric_wb_set_context,
notric_get_context, notric_check_guardrails, notric_context_create, notric_code_map,
notric_code_map_update, notric_get_context_drift, notric_get_decision_readiness,
notric_attention, and the rest of the Change lifecycle.
projectId is optional in all of them. Read tools answer with a compact text rendering and
return the full payload only with format: "json".
Importing a spec is a human operation: it stays CLI-only (notric import), with no MCP tool.
