Claude Code Athenaeum

Optimized Claude Code project hub with persistent memory, self-correcting agent pipeline, pre-write security, compounding knowledge, and institutional learning across sessions.

npx claude-athenaeum my-project

No Obsidian required. The vault is just a folder of markdown files. Obsidian is great for browsing them (graph view, wikilinks, backlinks) but any markdown editor works — or just raw folders. Your call.

Full documentation in GUIDE.md

What Makes This Different

Most Claude Code setups are a CLAUDE.md and maybe some hooks. Athenaeum is a complete development operating system:

• Agents that learn — 8 specialized agents with persistent memory that carries across sessions. Mistakes logged once are never repeated.
• Security that blocks, not warns — Pre-write secret scanning that prevents API keys from ever hitting disk. Prompt injection defense that flags manipulated content before Claude acts on it.
• Knowledge that compounds — Wiki layer (inspired by Karpathy's LLM Wiki) files research back as permanent, cross-referenced pages instead of letting it vanish into chat history.
• Self-maintaining — Deduplication, staleness detection, wiki linting, and consolidation runs keep the knowledge base clean without manual curation.
• Crash-proof sessions — Every file write is checkpointed. Context compression is snapshotted. Crashed sessions are auto-detected and recovered on next startup.
• Right-sized pipeline — 5 cascade levels auto-select how many agents to involve. A typo fix doesn't spin up 8 agents. A major feature does.

What You Get

8 Specialized AI Agents

A 5-level cascade pipeline that auto-scales based on task complexity:

| Level | When | Agents | |-------|------|--------| | 0 | Quick fixes, typos | Direct action (no agents) | | 1 | Standard features | Architect -> Builder -> Reviewer | | 2 | Multi-file features | Architect -> Builder -> Tester -> Reviewer | | 3 | Major features, security | + Critic | | 4 | Milestones, UI-heavy | + Designer, Compliance, Data-Integrity |

| Agent | Role | |-------|------| | Architect | Plans implementation, researches context, assesses feasibility | | Builder | Implements plans, self-corrects with quality checks | | Tester | Runs code and tests, reports issues | | Critic | Security audit, code quality, edge cases (0-5 scoring rubric) | | Reviewer | Final gate: APPROVED or NEEDS WORK | | Designer | UI/UX, accessibility, visual consistency, responsive design | | Compliance | Legal, platform, regulatory audits (auto-triggers every 5th run) | | Data Integrity | Data accuracy, schema compliance, link health |

13 Skills (Commands)

| Command | What It Does | |---------|-------------| | /pipeline [task] | Run the agent cascade (auto-selects complexity level) | | /startup | Daily briefing: crash recovery check, status, priorities | | /closeout | Full session end: handoff doc, dedup check, logs, git commit, backup | | /research [topic] | Deep research with automatic wiki filing | | /ingest [source] | Process a source into the wiki layer (file, URL, or topic) | | /wiki-lint | Wiki health check: orphans, stale pages, contradictions | | /experiment | Structured sandbox in .lab/ with THINK-TEST-REFLECT cycle | | /quality-gate | Typecheck + lint + test in one command | | /context | Show current session state | | /briefing | Generate plain-language status summary | | /backup | Backup workspace to local or cloud storage | | /dashboard-update | Update project dashboard with metrics | | /retrospective | Self-evaluation after pipeline run |

Security Features

| Feature | How It Works | |---------|-------------| | Secret Blocking | PreToolUse hook scans Write/Edit content before it hits disk. Blocks API keys, passwords, tokens, private keys. | | Prompt Injection Defense | PostToolUse hook scans Read/WebFetch/Bash/Grep outputs for injection patterns. Warns Claude to treat suspicious content with skepticism. | | Permissions Whitelist | Only approved Bash commands are allowed (no rm, sudo, etc.) | | Auto-Commit | Safety checkpoint commits every 10 file operations | | Compliance Agent | Automated legal/platform/regulatory audits | | Critic Agent | OWASP Top 10 security review built into pipeline |

19 Hooks

12 active by default, 7 optional (enable when needed):

• Always on: secret-guard (pre-write blocking), prompt-injection-defender, session lifecycle, checkpoint, reindex, auto-commit, claudemd-watchdog, learning-size-guard, context-monitor, auto-ingest-suggest
• Opt-in: dependency-audit (npm/pip/cargo), codebase-map-refresh, html-to-md, backup-vault. Code quality checks via /quality-gate skill.
• Git-level: pre-commit-secrets (blocks commits containing secrets — installed automatically)

Also Included

• Wiki layer — LLM-maintained knowledge base with ingest/query/lint cycle (inspired by Karpathy's LLM Wiki)
• MCP filesystem server for cross-directory vault access
• 10 Python scripts (semantic search, cross-project vault health, codebase mapping, token estimation, ...)
• Learning system (patterns, mistakes, decisions, improvements, metrics)
• Yggdrasil persistent semantic memory (install separately: npm install -g @chrisdudek/yg)
• Session management with crash recovery
• Comprehensive docs structure (specs, plans, guides, reference, research)

Quick Start

# 1. Create your project
npx claude-athenaeum my-project
cd my-project

# 2. Install Python dependencies
pip3 install sentence-transformers numpy

# 3. Customize CLAUDE.md (most important step!)
# Edit it to describe YOUR project

# 4. Build search index
python3 vault-search.py --reindex

# 5. Run health check
python3 health-check.py

# 6. Start Claude Code
claude
# Then type: /startup

Documentation

• GUIDE.md — Complete guide: setup, agents, pipeline, hooks, security, wiki layer, customization, performance tuning, troubleshooting
• CONTRIBUTING.md — How to contribute

FAQ

Does this require Obsidian? No. The project is just a folder of markdown files. Obsidian is excellent for browsing them (graph view, wikilinks, search) but completely optional. VS Code, Typora, or raw ls + cat all work fine.

Does this work with models other than Claude? The agents and pipeline are designed for Claude Code, but the vault structure, learning system, wiki layer, and scripts work with any AI coding tool that reads markdown.

Can I use this with an existing project? Yes. Run npx claude-athenaeum . in your existing project directory.

How do I update? Re-run npx claude-athenaeum@latest . — it updates scripts and adds new hooks without overwriting your customizations.

License

Apache 2.0 — see LICENSE for details.

Built with Claude Code by Maya Tobi.