Realm

Decision capture & knowledge pipeline for Claude Code, Cursor, Codex, and Gemini. Persists the WHY behind your code — decisions made, alternatives rejected, constraints imposed — as interlinked ADR nodes in an Obsidian vault.

Realm keeps one host-neutral Markdown skill source. Invoke skills with /realm-* in Claude Code and Gemini, or $realm-* in Codex. Host-native agent files contain only model, sandbox, and delegation adapters; workflow procedures stay in skills/.

Table of Contents

• What is Realm?
• Why Realm?
• How It Works
• Skills
• Installation
• Claude Plugin Publication
• Uninstallation
• Quick Start
• Querying the Vault
• Token Economics
• Vault Structure
• Dependencies

What is Realm?

Realm is an AI-coding-host skill/plugin system that captures architectural decisions as you make them — the choices, the alternatives you rejected, and the constraints those decisions impose — and stores them as compressed, interlinked ADR nodes in an Obsidian vault.

Every new AI session starts cold. Code tells AI what exists. Realm tells AI why it exists that way, what was tried and discarded, and what must not change.

Why Realm?

Code captures the surviving solution. It does not capture the graveyard of rejected alternatives, the constraint that forced an unusual pattern, or the incident that made you write "DO NOT change this order."

Without a decision record, AI assistants re-derive or re-propose settled questions every session. You answer the same "why not Redis pub/sub?" question repeatedly. A rejected approach gets proposed again in session 12.

How It Works

/realm-forge     ← Bootstrap vault directory structure and project state (once per repo)
/realm-fathom    ← Investigate code + vault rationale in parallel before changing code
/realm-recall    ← Instant decision queries (~20 tokens/node)
/realm-planning  ← Two-phase planning (P1: High-level + ADR direction; P2: Impl blueprint)
/realm-concise   ← God-file concierge triage queue (scripts/concise.py + committed ledger)
/realm-status    ← Read-only vault & pipeline health check

1. Bootstrap — realm-forge

Run /realm-forge once per project to link an Obsidian vault, create directory conventions, and seed pipeline state.

2. Investigate — realm-fathom

Before touching unfamiliar code:

/realm-fathom function:validateUser   # live code (ground truth) + vault WHY
/realm-fathom "how does auth flow"    # end-to-end + ADR context

Live code is always ground truth. Vault adds the architectural intent. Conflicts flagged as VAULT DRIFT.

3. Query — realm-recall

/realm-recall "why JWT"               # ~20 tokens
/realm-recall "what was rejected for auth"   # surfaces rejected_alternatives
/realm-recall "constraint on payments"       # consequences field
/realm-recall decisions               # all ADR nodes, compressed

4. Planning — realm-planning

Two-phase planning skill operating inside native plan mode:

• Phase 1: High-level architectural analysis and ADR direction.
• Phase 2: Code-level implementation blueprint for coding agents.

/realm-planning "refactor auth to JWT"
/realm-planning "distributed caching" --phase2

5. God-File Triage — realm-concise

Deterministic crawler (scripts/concise.py) finds oversized files, scores blast radius, maintains persistent queue in .realm/concise-state.json, and updates committed docs/GOD_FILES.md ledger.

/realm-concise                        # scan & print top god files
/realm-concise recommend <file>       # single-file refactor recommendation
/realm-concise plan <file>            # delegate approved candidate to /realm-planning

Skills

Team-Wide Facts (Organization)

Central GitLab realm-facts repo for organization knowledge. GitLab MR review + Microsoft Teams notifications.

One routed skill, /realm-facts, with 8 subcommands:

See docs/realm-facts-workflow.md for full team workflow.

Installation

See REQUIREMENTS.md for prerequisites.

Cursor (plugin)

Install from the repository URL via Settings → Plugins:

https://github.com/blackmo18/realm

Cursor reads .cursor-plugin/plugin.json and registers Realm's skills plus the Cursor-native agent adapters. Reload Cursor afterwards, then run /realm-forge.

Codex, Cursor, and Gemini

# Recommended installer
curl -fsSL https://raw.githubusercontent.com/blackmo18/realm/main/install.sh | bash -s -- --agent codex
curl -fsSL https://raw.githubusercontent.com/blackmo18/realm/main/install.sh | bash -s -- --agent cursor
curl -fsSL https://raw.githubusercontent.com/blackmo18/realm/main/install.sh | bash -s -- --agent gemini

# Skills-only direct installs (native agents require the recommended installer)
npx --yes skills add blackmo18/realm -a cursor --global --yes
npx skills add blackmo18/realm -a gemini

From a local clone:

# Global install
node bin/install.mjs --agent codex
node bin/install.mjs --agent gemini

# Local project-only install (does not touch ~)
./install.sh --agent gemini --local
./install.sh --agent codex --local

Claude Code

# 1. Install caveman plugin (required dependency)
/plugin marketplace add ~/.claude/plugins/marketplaces/caveman

# 2. Copy Realm into the Claude plugin marketplace path from a local clone
node bin/install.mjs --agent claude --force

# 3. Install realm inside Claude Code
/plugin marketplace add ~/.claude/plugins/marketplaces/realm

Full step-by-step guide: INSTALL.md

Claude Plugin Publication

To publish or update Realm on the Claude Code marketplace:

1. Verify Plugin Manifests:

   • .claude-plugin/plugin.json — contains plugin name, version, description, and author.
   • .claude-plugin/marketplace.json — contains plugin entry, category, and source repository pointer (https://github.com/blackmo18/realm.git).

2. Update Release Version & Git Commit SHA:

   • Bump version in .claude-plugin/plugin.json (e.g., "version": "0.1.6").
   • Get current git commit SHA: git rev-parse HEAD.
   • Update sha in .claude-plugin/marketplace.json.

3. Commit & Push to GitHub:

   git add .claude-plugin/plugin.json .claude-plugin/marketplace.json
   git commit -m "chore(release): update plugin manifest and commit SHA"
   git push origin main

4. Add or Refresh in Claude Code:

   # Add plugin from local marketplace path or git endpoint:
   /plugin marketplace add ~/.claude/plugins/marketplaces/realm
   # Or from public/remote git URL:
   /plugin marketplace add blackmo18/realm

Uninstallation

# Skills CLI installs (Cursor and Gemini)
npx skills remove realm

Codex native removal commands are listed in UNINSTALL.md.

For Claude Code installs:

./uninstall.sh

Full uninstall guide: UNINSTALL.md

Quick Start

Codex:

$realm-forge
$realm-fathom function:validateUser
$realm-recall "why JWT"
$realm-planning "refactor payment module"
$realm-concise

Claude Code and Gemini:

# 1. Bootstrap the vault for your project
/realm-forge

# 2. Investigate before changing code
/realm-fathom function:validateUser

# 3. Query existing ADRs
/realm-recall "why JWT"

# 4. Plan complex architectural changes
/realm-planning "refactor payment module"

# 5. Check god-file tech debt queue
/realm-concise

Querying the Vault

Decision queries (primary use case)

/realm-recall "why did we choose X"       # rationale field
/realm-recall "what was rejected for Y"   # rejected_alternatives field
/realm-recall "constraint on Z"           # consequences field
/realm-recall decisions                   # all ADR nodes, compressed

Before touching unfamiliar code

/realm-fathom function:validateUser       # signature, flow, callers + vault why + drift check
/realm-fathom class:AuthService           # class responsibility + vault ADR context
/realm-fathom "how does auth flow work"   # freeform → relevant code mapped + vault decisions

Token Economics

What realm-recall saves

Vault Structure

<vault>/projects/<slug>/
├── overview.md          # status, stack, milestone tracker, key file links
├── architecture.md      # service map, event shapes, data flow, schema groups
├── decisions/
│   ├── ADR-000-index.md # table of all ADRs
│   └── <id>.md          # one file per decision
├── discoveries/
│   └── YYYY-MM-DD-<topic>.md  # perf notes, bug discoveries
└── sessions/
    └── YYYY-MM-DD-<topic>.md  # per-session logs

Dependencies

Diagrams: VISUALS.md — pipeline flows & architecture diagrams.

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "realm",
  "description": "Obsidian project-knowledge & decision memory pipeline for continuous learning, ADRs, architecture planning, and god-file triage.",
  "owner": {
    "name": "blackmo",
    "url": "https://github.com/blackmo18"
  },
  "plugins": [
    {
      "name": "realm",
      "description": "Living Obsidian vault for project decisions & architecture memory. Core: forge, fathom, recall, status, planning, concise.",
      "source": {
        "source": "url",
        "url": "https://github.com/blackmo18/realm.git",
        "sha": "05d150799138b3274d670132aa9b1d3c888edff1"
      },
      "category": "productivity",
      "homepage": "https://github.com/blackmo18/realm"
    }
  ]
}