Stop context collapse. Ship one thing at a time.
Focus Guardian CLI for vibe coding sessions with AI agents
npm install -g vibe-focus
Fresh features that just shipped.
vibe-focus-team — share focus state across your team.
See who's working on what, sync tasks, and inject coworker context
into your guard hooks. Solo focus, team awareness.
Sparkline visualization of your focus score over time.
See streaks, trends, and weekly averages.
vf history shows it all in one glance.
Run parallel tasks in separate terminal tabs.
Each worker tracks its own task independently.
vf start t2 --worker api and go.
import { loadState } from 'vibe-focus' —
build plugins and extensions on top of vibe-focus.
Powers the upcoming vibe-focus-team package.
You're vibe coding with Claude Code. You start on user authentication. Twenty minutes in, you notice the API error handling could be better. You "quickly" refactor that. Then you spot a CSS issue. Before you know it, you've touched 15 files across 4 different concerns, your context window is bloated, and Claude starts hallucinating because it lost track of what you're actually building.
This is context collapse. And it kills vibe coding sessions.
vibe-focus is a Focus Guardian CLI that sits next to your AI coding agent and enforces single-task discipline. Define your scope. Break work into focused tasks with acceptance criteria. Get pushed back when you try to context-switch before finishing. Track your focus score to build better habits.
Everything you need to stay in the zone and stop your AI agent from going rogue.
The heart of vibe-focus. What makes it work.
Pushes back when you try to switch tasks before finishing.
Blocks context-switching with friction, not force.
Override with --force or --yolo -- but you'll see the score hit.
vf guard --install hooks directly into Claude Code.
Every prompt gets checked against your active task.
Focus rules are injected as system context automatically.
Every task gets clear, checkable criteria. No more "I think it's done?" -- you know exactly when to stop. Claude uses these as its definition of done.
Define what's in and what's out before you start. Try to add a task outside scope? Blocked. Keeps both you and your AI agent on the rails.
Stay in the flow. Ship without friction.
You close the terminal. Claude forgets everything.
vf context saves what matters — decisions, state, stack —
and auto-injects it when you come back.
Claude asks permission for every file edit. Every. Single. One.
vf flow auto-approves until your task is done.
No interruptions, just shipping.
Full TUI dashboard with keyboard navigation. Navigate tasks, check criteria, copy focused prompts, and force switches -- all from the terminal.
Great idea. Wrong moment. vf note parks it without
breaking your focus. Promote it to a real task later — or let it rot.
See your patterns. Build better habits.
Daily score from 0-100 tracking your focus habits. +20 for completing a task, -10 for switching, -5 for overriding. Build better habits over time.
Sparkline visualization of your focus over time.
Streaks, trends, and weekly averages — all in the terminal.
vf history to see where you've been.
Team workflows, parallel tabs, and extensibility.
vibe-focus-team — share focus state with your team.
See who's working on what via vf-team who.
Coworker context auto-injects into guard hooks.
Run parallel tasks in separate terminal tabs.
vf start t2 --worker api assigns the tab.
Each worker tracks independently, merges on done.
import { loadState } from 'vibe-focus' —
build plugins on top of the core.
Powers vibe-focus-team for shared team workflows.
Initialize, scope, task, ship, remember. Repeat.
Tell vibe-focus what you're building and what's off-limits.
$ vf init Initialized vibe-focus in ~/my-project/.vibe-focus/ $ vf scope --purpose "E-commerce checkout flow" \ --in "Cart" "Payment" "Order confirmation" \ --out "Product catalog" "User profiles" "Admin panel" Scope defined. 3 in-scope areas, 3 out-of-scope areas.
Break your work into focused chunks with clear acceptance criteria.
$ vf add "Implement cart total calculation" \ -c "Sum line items" \ -c "Apply discounts" \ -c "Tax calculation" Added task t1 with 3 criteria. $ vf start t1 Started task t1: Implement cart total calculation
The guardian keeps you honest. Try to deviate and it will block you.
$ vf switch t2 FOCUS GUARDIAN -- BLOCKED You're 67% done with "Cart total calculation". Only 1 criterion left! Finish it. You're almost there. Override: --force # Complete your criteria instead: $ vf check t1-c3 Checked: Tax calculation [3/3 complete] $ vf done Task t1 completed! Focus score: +20
The killer feature. Claude Code will enforce your focus automatically on every prompt.
$ vf guard --install Focus guardian hooks installed for Claude Code. Claude will now enforce your active task on every prompt. $ vf guard --status Guard: ACTIVE Mode: strict Task: t2 - Payment integration # What Claude sees on every prompt: VIBE FOCUS ACTIVE - STRICT MODE CURRENT TASK: t2 - Payment integration REMAINING CRITERIA: - Stripe API integration - Error handling for failed charges ENFORCEMENT: If request does NOT relate to this task -> STOP, REMIND, REDIRECT
Terminal closed. Machine rebooted. Doesn't matter. Save your session context and the guard hook injects it next time automatically.
# End of session — save what matters $ vf context "auth flow done, switched to JWT, need refresh tokens" Session context saved (ctx-3) # Next day, new terminal — context auto-loads $ claude PREVIOUS SESSION CONTEXT (saved 14h ago): auth flow done, switched to JWT, need refresh tokens
Interactive TUI dashboard. Navigate tasks, check criteria, and stay on track.
=========================================================== VIBE FOCUS DASHBOARD Focus Score: 85/100 Good Focus =========================================================== PROJECT: E-commerce checkout flow SCOPE: Cart | Payment | Order confirmation ----------------------------------------------------------- TASKS STATUS PROGRESS ----------------------------------------------------------- t1 Cart total calculation DONE [###] 3/3 > t2 Payment integration ACTIVE [##-] 2/3 t3 Order confirmation page PENDING [---] 0/2 t4 Email receipt PENDING [---] 0/2 ----------------------------------------------------------- CRITERIA for t2: Payment integration ----------------------------------------------------------- [x] t2-c1 Stripe API integration [x] t2-c2 Payment form UI > [ ] t2-c3 Error handling for failed charges ----------------------------------------------------------- TODAY: 2 tasks completed | 0 switches | Score: 85 ----------------------------------------------------------- [Enter] Start [Space] Check [d] Done [p] Prompt [q] Quit
Install globally, initialize in your project, and start focusing.
# Install globally $ npm install -g vibe-focus # Initialize in your project $ cd your-project $ vf init # Define scope $ vf scope --purpose "Build a REST API" \ --in "endpoints" "auth" \ --out "frontend" "deploy"
# Add a task $ vf add "User registration" \ -c "POST /register" \ -c "Email validation" \ -c "Password hashing" # Start, work, check, done $ vf start t1 $ vf check t1-c1 $ vf check t1-c2 $ vf check t1-c3 $ vf done # Activate Claude Code enforcement $ vf guard --install
| Command | Description |
|---|---|
| Core Workflow | |
vf init | Initialize vibe-focus in your project |
vf scope | Define or view project scope |
vf add "task" -c "criteria" | Add a task with acceptance criteria |
vf start <id> | Start working on a task |
vf check <criterion-id> | Mark a criterion as met |
vf done | Complete the current task |
vf list | List all tasks |
vf status | Show focus dashboard |
| Focus Protection | |
vf guard --install | Install Claude Code enforcement hooks |
vf guard --status | Check if guard is active |
vf guard --remove | Remove Claude Code hooks |
vf switch <id> | Switch task (guardian pushback!) |
vf scope --rules | Write focus rules to .claude/rules/ |
vf note "idea" | Park an idea without losing focus |
vf note --list | Show parked notes (parking lot) |
vf note --promote <id> | Promote a note to a backlog task |
vf abandon | Abandon current task (score penalty) |
| Workflow & Productivity | |
vf dash | Interactive TUI dashboard |
vf flow --on | Auto-approve tools until current task is done |
vf superflow --on | Auto-approve tools until ALL tasks done |
vf context "summary" | Save session context — survives terminal death |
vf context -i | Interactive mode — walks you through what to save |
vf context --show | Show last saved session context |
vf context --list | List all saved session contexts |
vf context --clear | Clear all saved contexts |
vf prompt | Generate focused prompt for Claude Code |
vf history | Focus history sparkline visualization |
vf history -n 30 | Show last 30 days of focus history |
vf history --json | Export focus history as JSON |
| Advanced | |
vf start <id> --worker <name> | Start task in a named worker tab |
vf done --worker <name> | Complete task for a specific worker |