Claude Code OS

A complete operating system for Claude Code. 9 specialist agents, 21 workflow commands, 9 automated checks, persistent memory, and 1,727 skills across 31 categories — installed in one command.

What You Get

9 Agents (.claude/agents/)

| Agent | What It Does | |-------|-------------| | Auditor | Self-improving quality gate. Reviews work, catches regressions, promotes learnings to knowledge base. Runs automatically via Stop hook. | | Unsticker | Root-cause analyst. When you're stuck, it classifies your block and prescribes the fastest path forward. | | Error Whisperer | Translates cryptic errors into plain English + copy-paste fixes. Stack traces, build errors, dependency conflicts. | | Rubber Duck | Thinking partner. Asks questions, not answers. Surfaces hidden assumptions and stress-tests plans before execution. | | PR Ghostwriter | Writes PR descriptions, commit messages, and changelogs from diffs. Reads actual code changes, never generic. | | Yak Shave Detector | Catches scope drift. "Is this actually necessary, or are you yak shaving?" Blunt, fast, unapologetic. | | Debt Collector | Scans for TODOs, hacks, deprecated patterns. Maintains a ranked debt inventory with effort estimates and impact scores. | | Onboarding Sherpa | Codebase tour guide. Maps architecture, identifies patterns, creates a working mental model in 5 minutes. | | Archaeologist | Code history investigator. Answers "why was this written this way?" by digging through git blame and commit history. |

8 Commands (.claude/commands/)

| Command | When | What It Does | |---------|------|-------------| | /start | Morning | Load memory, create daily note, review task board | | /sync | Mid-day | Refresh memory, process scratchpad, reorient | | /wrap-up | End of day | Daily audit, externalize knowledge, prep tomorrow | | /clear | Context pressure | Distill state, flush context, auto-resume seamlessly | | /audit | After completing work | Quality review via auditor agent | | /system-audit | Monthly | Deep infrastructure audit (agents, hooks, memory, config) | | /unstick | Stuck 10+ min | Deploy unsticker agent for root-cause analysis | | /retro | End of sprint | Sprint retrospective — patterns, improvements, action items |

9 Automated Checks (.claude/hooks/)

| Hook | Lifecycle | What It Does | |------|-----------|-------------| | guard-bash.sh | PreToolUse (Bash) | Three-tier command safety: hard block, soft block, log warning | | completeness-gate.sh | PreToolUse (Write/Edit) | Blocks incomplete writes to critical files (no TBD, no secrets) | | backup-before-write.sh | PreToolUse (Write/Edit) | Atomic backups with 7-day retention before any file modification | | log-changes.sh | PostToolUse (Write/Edit) | Audit trail of every file change | | log-failures.sh | PostToolUseFailure | Categorized failure logging with severity levels | | pre-compact-handoff.sh | PreCompact | Saves state marker before auto-compaction | | post-compact-resume.sh | SessionStart (compact) | Restores context after compaction | | session-reset.sh | SessionStart (user) | Cleans stale files, validates hooks, checks agent health | | log-stop-verdict.sh | Stop | Quality tracking via Haiku review + JSONL verdicts |

Persistent Memory (6 layers)

1. memory.md — Active working context (what you're doing now)
2. agent-memory/ — Per-agent persistent knowledge (survives across sessions)
3. knowledge-base.md — System-wide learned rules (auditor-gated, mandatory)
4. knowledge-nominations.md — Candidate learnings pipeline (any agent can nominate)
5. Daily Notes/ — Chronological history and session handoffs
6. Task Board — Structured task tracking

Install

npx claude-code-os init

That's it. Works in any project directory. Doesn't overwrite existing files.

What Happens

1. Copies the full Claude Code OS scaffold into your project
2. Sets up .claude/ with agents, commands, hooks, and memory files
3. Creates CLAUDE.md with system instructions
4. Makes all hook scripts executable
5. You're ready to go

Force Reinstall

npx claude-code-os init --force

Overwrites existing files. Use when upgrading to a new version.

Getting Started

After install:

1. Open your project with Claude Code
2. Run /start to begin your first session
3. Claude will load its memory, create a daily note, and ask what you're working on
4. Work normally — the system learns from your patterns automatically

Key Concepts

• Knowledge flows upward: You work > agents observe patterns > auditor validates > knowledge base stores. The system gets smarter over time.
• Commands are proactive: Claude will suggest /clear when context is heavy, /unstick when you're blocked, /audit when a task completes.
• Hooks are deterministic: Safety checks run on every tool call. No exceptions, no skipping.
• Memory is layered: Active context in memory.md, learned rules in knowledge-base.md, history in daily notes.

Customization

Add Your Own Agents

Create a new .md file in .claude/agents/ with this frontmatter:

---
name: my-agent
description: What this agent does
tools:
  - Read
  - Grep
model: sonnet
memory: project  # or 'none'
maxTurns: 8
---

Add Your Own Commands

Create a new .md file in .claude/commands/ with this frontmatter:

---
description: What this command does
argument-hint: "[optional args]"
allowed-tools:
  - Read
  - Write
---

Then add it to .claude/command-index.md.

Modify Hooks

Edit .claude/settings.json to add, remove, or modify lifecycle hooks. Hook scripts live in .claude/hooks/ — they're standard shell scripts.

How It Works

The Learning Loop

You work
  -> Hooks log everything (audit trail, failures, quality verdicts)
  -> Agents observe patterns (nominations to knowledge pipeline)
  -> Auditor reviews nominations (promotes confirmed learnings)
  -> Knowledge base grows (all agents read it)
  -> Better decisions next time

Context Management

Claude Code sessions have finite context. Claude Code OS handles this:

• Automatic: PreCompact hook saves state before auto-compaction
• Manual: /clear distills session into daily note + memory, then auto-resumes
• Proactive: Claude suggests /clear after 30+ tool calls or when quality degrades

Completeness Checks

The completeness gate blocks writes to critical files that are:

• Missing provenance tags (knowledge-base entries need [Source:])
• Containing incomplete markers (TBD, TODO, FIXME, PLACEHOLDER)
• Exposing secrets (API key patterns in any file)
• Invalid format (settings.json must be valid JSON)

Requirements

• Claude Code (CLI)
• Node.js 16+ (for the installer)
• Any project directory

License

MIT