Developer Tool / CLI

Stop context collapse. Ship one thing at a time.
A Focus Guardian CLI that keeps your AI coding sessions on track.

$ npm install -g vibe-focus
GitHub → npm Package How It Works

⚠️ Context Collapse

  • → You start on user auth. 20 minutes later you're refactoring error handling.
  • → AI agents happily follow every tangent - they don't push back on scope creep.
  • → Context window fills up with 4 different concerns, agent starts hallucinating.
  • → You've touched 15 files but shipped nothing. Session wasted.
  • → No clear definition of "done" - so you keep adding "one more thing".

✓ Vibe Focus

  • → Define your task with acceptance criteria before you start coding.
  • → Focus Guardian pushes back when you try to switch context.
  • → Claude Code hooks enforce focus on every single prompt.
  • → Project scope blocks out-of-scope work, even if you ask for it.
  • → Clear "done" = all criteria met. Then move to the next task.
// capabilities

Built for focused vibe coding

🛡️

Focus Guardian

Pushes back when you try to switch tasks. Escalates from gentle warning to hard block based on how much progress you'd lose.

🎯

Project Scope

Define what's in and out of scope. The guardian blocks tasks that don't fit your project's purpose. No more scope creep.

✅

Acceptance Criteria

Every task has a clear definition of done. Check criteria off as you go. "Done" means all criteria met, not "I think it works".

🔗

Claude Code Hooks

Native integration via UserPromptSubmit hooks. Claude Code checks every prompt against your active task and refuses to deviate.

📊

Interactive Dashboard

Full TUI dashboard with keyboard navigation. Start tasks, check criteria, and track progress without leaving the terminal.

📈

Focus Score

Daily score from 0-100. Rewards completing tasks, penalizes switching. Build a habit of deep focus over time.

// demo

The Guardian in Action

vf status
██╗ ██╗██╗██████╗ ███████╗ ███████╗ ██████╗ ██████╗██╗ ██╗███████╗ ██║ ██║██║██╔══██╗██╔════╝ ██╔════╝██╔═══██╗██╔════╝██║ ██║██╔════╝ ██║ ██║██║██████╔╝█████╗ █████╗ ██║ ██║██║ ██║ ██║███████╗ ╚██╗ ██╔╝██║██╔══██╗██╔══╝ ██╔══╝ ██║ ██║██║ ██║ ██║╚════██║ ╚████╔╝ ██║██████╔╝███████╗ ██║ ╚██████╔╝╚██████╗╚██████╔╝███████║ ╚═══╝ ╚═╝╚═════╝ ╚══════╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝ ╔════════════════════════════════════════════════════════════╗ ║ SYS://my-project SCORE [▓▓▓▓▓▓▓▓▓░░░░░░] 85 ║ ╠── ACTIVE TASK ─────────────────────────────────────────╣ ║ >> T1 :: Implement user auth ║ ║ ELAPSED 23m SWITCHES 0 [████████████░░░░] 67% ║ ║ [PASS] Login endpoint returns JWT ║ ║ [PASS] Password hashing with bcrypt ║ ║ [ ] Tests pass with >80% coverage ║ ╠── TASK PIPELINE ───────────────────────────────────────╣ ║ ▶ t1 Implement user auth 2/3 ▓▓▓░░ ║ ║ ○ t2 Add rate limiting 0/2 ░░░░░ ║ ║ ○ t3 Write API docs 0/4 ░░░░░ ║ ╚════════════════════════════════════════════════════════════╝
vf switch t2
╭──────────────────────────────────────────────────────────╮ │ │ │ FOCUS GUARDIAN - BLOCKED │ │ │ │ Du bist 67% fertig mit "Implement user auth". │ │ Nur noch 1 Kriterium offen! │ │ │ │ Mach die restlichen Kriterien fertig. Du bist fast da. │ │ │ │ Override: --force │ │ │ ╰──────────────────────────────────────────────────────────╯
// workflow

How It Works

01

Define Your Scope

Set the project purpose and boundaries. What's allowed, what's forbidden.

$ vf init
$ vf scope --purpose "REST API for e-commerce" \
    --in "endpoints" "auth" --out "frontend"
02

Create Focused Tasks

Break work into small tasks with clear acceptance criteria.

$ vf add "User registration" \
    -c "POST /register" "Email validation" "Returns JWT"
$ vf start t1
03

Activate the Guardian

Install the Claude Code hook. From now on, Claude enforces your focus.

$ vf guard --install
$ claude   # Claude now checks every prompt against your task
04

Ship & Repeat

Check criteria, complete the task, pick the next one. Stay in the flow.

$ vf check t1-c1 t1-c2 t1-c3
$ vf done
✓ Task t1 completed | Focus score: 90 (Deep Focus)
$ vf start t2

"Context switching is the enemy of vibe coding. Without explicit scope, AI agents will happily refactor your entire codebase when you asked for a button."

— The Vibe Focus Philosophy

// reference

All Commands

Command Description
vf initInitialize vibe-focus in your project
vf scopeDefine or view project scope (purpose, in/out boundaries)
vf add "task" -c "..."Add a task with acceptance criteria
vf start <id>Start working on a task
vf check <criterion>Mark acceptance criteria as met
vf doneComplete the current task
vf statusShow the nerdy focus dashboard
vf listList all tasks with status
vf switch <id>Switch task (guardian pushback!)
vf abandonAbandon or shelve current task
vf promptGenerate focused prompt for Claude Code
vf guard --installInstall Claude Code enforcement hooks
vf dashInteractive TUI dashboard
// stack

Technology

Node.js TypeScript Commander.js chalk boxen tsup Claude Code Hooks API TUI / Raw TTY

Stop switching.
Start shipping.

One command to install. One task at a time. Zero context collapse.

$ npm install -g vibe-focus


View on GitHub →