Johnny Decimal — Claude Code Integration

How the JD filing system connects to Claude Code through plugins, hooks, skills, and the jd CLI.

Last updated: 2026-03-31

Architecture

Two components give Claude Code full JD awareness:

Component	What it is	Source	Role
jd-cli	Python CLI + MCP server	`~/repos/jd-cli`	Core tool — all filesystem ops, indexing, context collection
jd plugin	Claude Code plugin	`~/repos/jd-cli/plugin/claude-code/`	Skills, hooks, and MCP server config

 Claude Code session
┌──────────────────────────────────────────────┐
│                                              │
│            jd plugin                         │
│  ┌────────────────────────────────────────┐  │
│  │                                        │  │
│  │  Hooks:              Skills:           │  │
│  │   SessionStart         /jd-suggest     │  │
│  │    → POLICY.md         /jd-file        │  │
│  │   SessionEnd           /jd-triage      │  │
│  │    → ACTIVITY.md                        │  │
│  │                      MCP: jd mcp       │  │
│  │                       (45+ tools)      │  │
│  └──────────────────────────┬─────────────┘  │
│                             │                │
│                             ▼                │
│                      ┌──────────────┐        │
│                      │   jd CLI     │        │
│                      │ Python/Click │        │
│                      └──────┬───────┘        │
│                             │                │
│                             ▼                │
│                      ┌──────────────┐        │
│                      │ ~/Documents  │        │
│                      │  (JD tree)   │        │
│                      └──────────────┘        │
└──────────────────────────────────────────────┘

Everything lives in one repo (jd-cli) and one plugin. The plugin provides skills for interactive filing, hooks for session lifecycle, and MCP tools for direct filesystem access.

jd-cli

The core tool. Everything else delegates to it.

Version: 0.3.0 (beta) Stack: Python 3.10+, Click, PyYAML, FastMCP Install: pipx install -e ~/repos/jd-cli

Commands

Navigation

Command	What it does
`jd which <ID>`	Resolve ID to filesystem path
`jd index [CAT]`	Print the JD index
`jd search <QUERY>`	Case-insensitive name search
`jd ls [TARGET]`	Tree listing (wraps `tree`)
`jd open <TARGET>`	Open in Finder
`jd cd <TARGET>`	Change directory (shell wrapper)
`jd json`	Full index as JSON
`jd root`	Print JD root path

Creation

Command	What it does
`jd new id <CAT> <NAME>`	Create new ID (auto-numbered)
`jd new category <AREA> <NAME>`	Create new category
`jd new sub <ID> <CODE> "Name"`	Create sub-ID (e.g. `26.05+JEM`)
`jd new subfolder <ID> "Name"`	Create date-prefixed subfolder
`jd init <CAT>`	Bootstrap category with `.00` and `.01`
`jd init-all`	Initialize all standard zeros

Moving and archiving

Command	What it does
`jd mv <SRC> <DEST>`	Smart move — renumber, refile, or rename
`jd mv -a <TARGET>`	Archive to `.99`
`jd mv -s <TARGET>`	Move to someday (`.08`)
`jd restore <TARGET>`	Restore from archive
`jd add <PATH> <ID>`	Add file from outside the tree

JDex (index management)

Command	What it does
`jd jdex show <ID>`	Show entry details
`jd jdex search <QUERY>`	Search by title/keywords
`jd jdex list [CAT]`	List indexed entries
`jd jdex adopt`	Create entries for unindexed filesystem IDs
`jd reconcile`	Detect drift between JDex and filesystem

Validation and diagnostics

Command	What it does
`jd validate [--fix]`	Check conventions, duplicates, symlinks
`jd triage`	Show busiest inbox dirs, empty categories
`jd stats`	System-wide statistics
`jd generate-index`	Export index (md/org/json)

App integrations

Command group	What it does
`jd notes scan/validate/create/open/sync`	Mirror JD folders in Apple Notes
`jd omnifocus scan/validate/open/tag/task/create`	JD-tagged projects and tasks in OmniFocus
`jd contacts scan/link/open`	Link macOS Contacts to JD IDs

Configuration

Command	What it does
`jd config show/get/set/unset`	Manage tiered config
`jd config where [PATH]`	Show which tier each key comes from
`jd systems list/add`	Manage multiple JD systems
`jd template list/show/create`	Manage structure templates
`jd volume list/scan/link/index`	Manage external volumes
`jd symlinks [--check] [--fix]`	Audit and repair symlinks
`jd ln <SOURCE> <ID>`	Create inbound symlink

Agent interfaces

Command	What it does
`jd claude [TARGET] [--show]`	Launch Claude Code with cascading context
`jd context [TARGET]`	Print cascading context (no launch)
`jd mcp`	Start MCP server
`jd schema [COMMAND]`	Show JSON schema for command output

All commands support --json for structured output and --dry-run for write previews.

Source layout

~/repos/jd-cli/johnnydecimal/
├── core/           # Domain model (no I/O)
│   ├── models.py       # JDSystem, JDArea, JDCategory, JDID
│   ├── jdex.py         # JDex index engine
│   ├── ports.py        # Abstract protocols for adapters
│   ├── systems.py      # Multi-system support
│   ├── templates.py    # Template handling
│   └── exceptions.py   # Domain exceptions
├── adapters/       # I/O implementations
│   ├── filesystem.py    # Filesystem scanning
│   ├── config.py        # Config loading/merging (tiered)
│   ├── jdex_*.py        # JDex backends (YAML, Markdown)
│   ├── apple_notes.py   # Notes.app bridge
│   ├── staging.py       # Desktop staging + Finder tags
│   └── scope.py         # Agent scope enforcement
└── interfaces/     # User-facing
    ├── cli.py           # Click entry point
    ├── mcp_server.py    # FastMCP server (45+ tools)
    └── completion.py    # Shell completion

`jd claude` — context injection

When you run jd claude <target> from the terminal:

Resolves the target to a JD level (walks up: ID → category → area → root)
Builds a cascade from root down to the target
Scans for documentation at each level's .00 meta dir:
- Stems: README, TODO, CLAUDE, AUDIT, TIMELINE, PLAN
- Extensions: .md, .org, .txt (first match wins per stem)
Gathers proposals — lists .md filenames from sibling .02 dirs at area levels
Concatenates with markdown section headers showing relative paths
Launches Claude Code with --append-system-prompt "<context>", working directory set to target

jd claude --show prints the collected context without launching.

Per-level customization via .jd.yaml:

claude:
  include:
    stems: [README, NOTES]    # Add to default stems
    extensions: [.md]          # Restrict extensions
    extra: ["*.json"]          # Local-only file patterns
    exclude: [DRAFT.md]        # Local-only excludes

MCP server

jd mcp starts a FastMCP server exposing 45+ tools across all command groups (navigation, creation, JDex, templates, validation, app integrations, config, staging) plus two resources: jd://tree and jd://config.

The jd Claude Code plugin configures this as an MCP server so Claude has direct tool access without shell commands.

jd plugin

Source: ~/repos/jd-cli/plugin/claude-code/ Marketplace: claude-code-plugins-mac Scope: user (global)

Plugin structure

plugin/claude-code/
├── .claude-plugin/
│   └── plugin.json          # Metadata (name: jd, version: 0.1.0)
├── .mcp.json                # Configures `jd mcp` as MCP server
├── CLAUDE.md                # JD primer for Claude Code sessions
├── bin/
│   └── run                  # CLI launcher with fallback chain
├── hooks/
│   ├── hooks.json           # SessionStart + SessionEnd definitions
│   ├── session-start.sh     # POLICY.md injection
│   └── session-end.sh       # Activity logging to ACTIVITY.md
└── skills/
    ├── jd-suggest/SKILL.md
    ├── jd-file/SKILL.md
    └── jd-triage/SKILL.md

Skills

`/jd-suggest` — Propose a JD taxonomy

Trigger: "suggest a structure", "organize this", "create a taxonomy", jd init --suggest

Scans a directory tree (samples up to 200 paths), analyzes content by domain, and proposes a complete Johnny Decimal taxonomy. Iterates with user feedback before creating anything. Always gets approval before writing to disk.

`/jd-file` — File items into the JD tree

Trigger: "file this", "sort xx.01", "move this to the right place"

Two-tier filing:

Tier 1: Capture (01.xx) → Category inbox (xx.01) — quick domain sort
Tier 2: Category inbox (xx.01) → Final ID (xx.yy) — precise filing

Rules: use jd CLI for all ops, mv semantics (never copy), file to inbox when unsure, search before creating new IDs, ask before jd new.

`/jd-triage` — Triage capture and inbox folders

Trigger: "triage", "sort capture", "process inbox"

Scans target location, inspects contents
Proposes destinations in a table with confidence levels
Waits for user approval
Checks for duplicates before moving
Moves approved items via jd mv
Reports: moved, skipped, remaining

Rules: never delete, never overwrite (flag duplicates), batch by category, ask before creating new IDs.

Hooks

SessionStart — Policy injection

Reads ~/repos/dotfiles/docs/POLICY.md and injects it as session context via hookSpecificOutput.additionalContext. Every Claude Code session starts with the full JD System Policy (structure, reserved IDs, capture system, documentation stems, naming conventions).

If POLICY.md doesn't exist, exits silently.

SessionEnd — Activity logging

Spawns a background claude --print --model sonnet call that reads the session transcript, decides if anything notable was done (files modified, features built, configs changed), and if so appends an org-mode entry to the activity log:

Log file: ~/Documents/00-09 System-management area/00 System-management category/00.00 JDex for the system/ACTIVITY.md

** 2026-03-31 — Short description
   - What was done
   - Files created or modified (with paths)
   - Any follow-up needed

Rules: one line per bullet, include paths, append only, skip Q&A-only sessions, never create the file if it doesn't exist.

Timeout: 10 seconds for the hook; the background Claude call runs independently.

MCP server config

.mcp.json registers jd mcp as a Claude Code MCP server, giving Claude direct tool access to the full JD system without shell commands.

Launcher

bin/run ensures the jd CLI is available:

jd on PATH (pipx install — normal case)
uvx --from johnnydecimal jd (fallback)
Plugin-local venv with auto-install (last resort)

Context chain

When Claude Code starts a session, it receives JD context from multiple layers:

Layer	Source	Always active?	What it provides
1	`~/.claude/CLAUDE.md`	Yes	Area table, key IDs, behavioral rules, tool ecosystem
2	`~/.claude/projects/*/memory/`	Yes	Per-directory auto-memory from prior sessions
3	`POLICY.md` via jd plugin hook	Yes	JD structure, filing rules, naming conventions, documentation stems
4	`jd mcp` via jd plugin	Yes	45+ tools for filesystem ops, JDex, app integrations
5	`jd claude --append-system-prompt`	Only via `jd claude`	Cascading docs from `xx.00` meta dirs (README, TODO, CLAUDE, AUDIT, TIMELINE, PLAN)

Layers 1–4 are present in every session regardless of how it was launched. Layer 5 adds deep, location-specific context but requires launching via jd claude <target>.

File locations

What	Path
jd-cli source	`~/repos/jd-cli/`
jd-cli entry point	`~/repos/jd-cli/johnnydecimal/cli/__init__.py`
`jd claude` implementation	`~/repos/jd-cli/johnnydecimal/claude.py`
MCP server implementation	`~/repos/jd-cli/johnnydecimal/interfaces/mcp_server.py`
Plugin source	`~/repos/jd-cli/plugin/claude-code/`
Plugin (installed cache)	`~/.claude/plugins/cache/claude-code-plugins-mac/jd/0.1.0/`
JD System Policy	`~/repos/dotfiles/docs/POLICY.md`
Activity log	`~/Documents/.../00.00 JDex for the system/ACTIVITY.md`
JD tree root	`~/Documents/`

Navigation Menu

Johnny Decimal — Claude Code Integration

Architecture

jd-cli

Commands

Navigation

Creation

Moving and archiving

JDex (index management)

Validation and diagnostics

App integrations

Configuration

Agent interfaces

Source layout

`jd claude` — context injection

MCP server

jd plugin

Plugin structure

Skills

`/jd-suggest` — Propose a JD taxonomy

`/jd-file` — File items into the JD tree

`/jd-triage` — Triage capture and inbox folders

Hooks

SessionStart — Policy injection

SessionEnd — Activity logging

MCP server config

Launcher

Context chain

File locations

Related documentation

FilesExpand file tree

claude-code-integration.md

Latest commit

History

claude-code-integration.md

File metadata and controls

Johnny Decimal — Claude Code Integration

Architecture

jd-cli

Commands

Navigation

Creation

Moving and archiving

JDex (index management)

Validation and diagnostics

App integrations

Configuration

Agent interfaces

Source layout

jd claude — context injection

MCP server

jd plugin

Plugin structure

Skills

/jd-suggest — Propose a JD taxonomy

/jd-file — File items into the JD tree

/jd-triage — Triage capture and inbox folders

Hooks

SessionStart — Policy injection

SessionEnd — Activity logging

MCP server config

Launcher

Context chain

File locations

Related documentation

`jd claude` — context injection

`/jd-suggest` — Propose a JD taxonomy

`/jd-file` — File items into the JD tree

`/jd-triage` — Triage capture and inbox folders