Niklas Luhmann for your repo. A Claude Code agent that reads your codebase like a scholar, reorganizes your docs like an archivist, and finds the connections you missed.
Most codebases have documentation the way most people have notes: scattered, stale, and full of buried insight. Luhmannbot brings Zettelkasten discipline to your repo — extracting ideas, linking concepts across files, cleaning up inconsistencies, and building the kind of second brain your project deserves.
A role repo — a specialization pattern for Claude Code. It contains no application code. Instead, it configures Claude Code as a dedicated documentarian: an agent whose only job is knowledge extraction, organization, and maintenance.
The repo provides:
- 10 skills for knowledge work (extract, connect, verify, synthesize)
- A Rust CLI (
luhmann) for deterministic vault operations (graph analysis, schema validation, stats) - Hooks for auto-commit and schema validation
- CLAUDE.md that keeps the agent focused on documentarian work
You start Claude from this directory, point it at your project, and every skill it sees is relevant to documentation and knowledge work.
- Claude Code CLI installed and authenticated
- Rust toolchain (for building the
luhmannCLI)
git clone https://github.com/YOUR_USERNAME/luhmannbot.git
cd luhmannbot
# Build the Rust CLI
cd tools/luhmann && cargo build --release && cd ../..Start Claude Code from the luhmannbot directory and set your target:
cd luhmannbot
claudeThen tell it where to work:
Work on ~/myproject/docs
This runs luhmann target ~/myproject/docs and all skills operate there from now on — even across sessions.
/luhmann:reduce ~/myproject/docs/architecture-decisions.md
Extracts atomic notes with proper frontmatter, duplicate detection, and categorization. Presents a numbered list for approval before writing.
/luhmann:capture distributed systems need backpressure mechanisms to prevent cascading failures
Creates a single atomic note with semantic duplicate checking.
/luhmann:reflect notes/distributed-systems-need-backpressure.md
Finds forward and backward connections, updates MOCs, weaves wiki-links into prose.
/luhmann:dream sparks
Picks random notes from different clusters and proposes surprising connections.
/luhmann:health full
Runs diagnostics and writes a report to ops/health/ with ranked repair actions.
| Skill | Description |
|---|---|
/luhmann:capture |
Create an atomic note with duplicate detection |
/luhmann:reduce |
Extract atomic notes from a long document |
/luhmann:reflect |
Find and add connections between notes |
/luhmann:reweave |
Revisit older notes — sharpen claims, split, challenge |
/luhmann:verify |
Quality gate: recite, validate, review |
/luhmann:graph |
Structural graph analysis (hubs, bridges, clusters) |
/luhmann:dream |
Creative synthesis: find gaps, propose bridge notes |
/luhmann:health |
Vault diagnostics with ranked repair actions |
/luhmann:stats |
Quick vault metrics overview |
/luhmann:pipeline |
Batch: source → reduce → reflect → reweave → verify |
The Rust binary handles all mechanical vault operations. Skills invoke it and interpret the JSON output. This separates correctness (deterministic code) from judgment (LLM).
luhmann target ~/myproject # Set target directory
luhmann init # Create vault directories
luhmann graph # Graph metrics (JSON)
luhmann lint --all # Schema validation (JSON)
luhmann stats # Vault metrics (JSON)
luhmann frontmatter <file> # Extract YAML only, no body
luhmann sample --clusters 3 # Random notes for /dreamNotes are markdown with YAML frontmatter and wiki-links:
---
description: "~150 chars adding mechanism/scope beyond title"
topics:
- "[[Topic MOC]]"
type: claim
---
Body with [[wiki-links]] woven into prose because connections
drive understanding, not "see also" link dumps.
## Relevant Notes
- [[related note]] — explains the mechanism behind this claimThe title IS the claim. Filenames use hyphens: context-windows-limit-llm-attention.md.
Luhmannbot demonstrates role repos: small repos that each configure Claude Code for a specific role. Each has a CLAUDE.md that sets focus, skills that provide capabilities, and no application code.
MIT