Vibe-Claude
Don't fight the tool. Sharpen the edge.
A minimal enhancement layer for Claude Code — distilled from 4 major iterations down to what actually matters.
What This Is
5 files. 2 hooks. 5 rules. That's it.
Vibe-Claude adds two things Claude Code doesn't enforce natively:
- Stop Guard — Blocks the agent from stopping without showing execution evidence
- Post-Edit Check — Validates syntax after every file edit
Everything else is Claude Code doing what it already does best.
Install
git clone https://github.com/kks0488/vibe-claude.git ~/.claude-vibe
cp ~/.claude-vibe/CLAUDE.md ~/.claude/CLAUDE.md
cp -r ~/.claude-vibe/hooks/* ~/.claude/hooks/
cp ~/.claude-vibe/settings.json ~/.claude/settings.json
Structure
~/.claude/
├── CLAUDE.md # 5 rules
├── settings.json # minimal config
└── hooks/
├── hooks.json # hook registry
├── stop-guard.sh # no proof → no stop
└── post-edit.sh # auto syntax check
The Rules
From CLAUDE.md:
- Prove it, don't claim it — Show execution output before claiming done. "Should work" is banned.
- Delegate exploration — Use subagents for searching/reading. Keep main context for decisions.
- Two-Strike Rule — Same error twice → change the approach entirely.
- Ask before building big — 3+ files affected → confirm scope first.
- Minimal changes — Only change what was asked. No drive-by refactors.
The Hooks
| Hook | Trigger | What it does |
|---|
| stop-guard | Agent tries to stop | Blocks unless execution evidence (output, test results, file:line refs) is present |
| post-edit | After Write/Edit | Runs syntax validation (Python, JS, JSON, YAML, Bash) |
The Story: Why v5 Exists
What we built (v1 — v4)
Over 4 major versions, Vibe-Claude grew into a full orchestration system:
- 13 specialized agents — analyst, planner, critic, worker, designer, conductor, tester, researcher, advisor, finder, vision, api-tester, writer
- 8 skills — vibe, v-turbo, v-git, v-style, v-evolve, v-continue, v-memory, v-compress
- 5-Phase pipeline — Routing → Interview → Recon → Planning → Execution → Verification → Polish
- 8 hook events — Setup, SessionStart, UserPromptSubmit, SubagentStart, TeammateIdle, TaskCompleted, Stop, PostToolUse
- Self-evolution system — automatic agent creation when capability gaps were detected
- Memory system — lessons, patterns, decisions, context with grep-based recall
- Context management — compression, checkpointing, session handoff
689 lines of markdown prompts orchestrating Claude Code like a puppet theater.
What happened
Claude Code's updates outpaced our development.
Every few weeks, Anthropic shipped features that made our layers redundant:
| What we built | What Claude Code shipped |
|---|
| v-memory (file + grep) | Auto Memory (built-in, semantic) |
| v-compress (context compression) | Compaction API (server-side, automatic) |
| v-continue (session restore) | Session auto-restore (built-in) |
| v-conductor (orchestrator agent) | Agent tool + subagents (built-in) |
| v-turbo (parallel execution) | Parallel tool calls (built-in) |
| v-finder (file search) | Glob, Grep, Explore agent (built-in) |
| 13 persona agents | Claude already plays every role |
| 5-Phase system | Plan mode (built-in) |
We were writing prompt instructions for things Claude already knew how to do. The 13 agents were personality wrappers. The 5-Phase system was a rigid pipeline over Claude's natural reasoning. The skills were markdown files restating built-in capabilities.
The system wasn't enhancing Claude Code. It was constraining it.
All that markdown was consuming context window — the most precious resource — to tell Claude things it already knew.
What we kept
We asked: "What does Claude Code still not do well?"
Two things:
-
It sometimes claims "done" without actually running the code. The stop-guard hook fixes this at the process level — not a prompt suggestion, an actual gate.
-
It sometimes breaks syntax after edits. The post-edit hook catches this immediately — automatic validation, zero context cost.
Everything else was deleted. 93% reduction.
The result
| v4 | v5 |
|---|
| Files | 70+ | 5 |
| Agents | 13 | 0 |
| Skills | 8 | 0 |
| Hooks | 8 | 2 |
| Lines of prompts | ~689 | ~20 |
| Context overhead | High | Near zero |
Lessons Learned
For anyone building systems on top of AI coding tools — we learned these the hard way.
1. The platform will eat your features.