█▀▀ █▀█ █▀█ █▀▀ █ █ █ █▀▄ █▀▀
█▀▀ █ █ █▀▄ █▀▀ ▀▄▀ █ █▀▄ █▀▀
▀   ▀▀▀ ▀ ▀ ▀▀▀  ▀  ▀ ▀▀▀ ▀▀▀

Your project's AI navigator — plan, enforce, and ship with confidence.

ForeVibe gives every AI coding assistant a Brain with living memory & source of truth of your project. Your plan is created on forevibe.com, then downloaded into your repo — surfaced through an MCP server so your AI always knows what you're building, what's next, and what to watch out for.

Works with Cursor, Windsurf, Claude Code, GitHub Copilot, Gemini CLI, Firebase Studio, Zed, JetBrains, and any editor supporting the Model Context Protocol.

Quick Start

# 1. Authenticate
npx forevibe auth

# 2. Download your plan (created on forevibe.com)
npx forevibe fetch

# 3. Start the MCP server (keep it running while you code)
npx forevibe start

# 4. Tell your AI agent to start building
implement

Where does the plan come from? Plans are created on the forevibe.com dashboard via a discovery chat session. forevibe fetch downloads the generated plan into your local .forevibe/ directory.

Daily Workflow

npx forevibe auth              ← authenticate with forevibe.com
npx forevibe fetch             ← download plan into .forevibe/
npx forevibe start             ← start MCP server (keep running)

── daily loop ───────────────────────────────────────────────────────
npx forevibe next              ← what's my current story + acceptance criteria?
  → tell your AI agent: implement
npx forevibe check             ← scan for drift violations
  → git commit (hook auto-checks staged files)
npx forevibe sync --push       ← push story completion status to forevibe.com
─────────────────────────────────────────────────────────────────────

npx forevibe fetch             ← re-fetch if plan changes on forevibe.com
npx forevibe sync --pull       ← pull updated story statuses from server

CLI Commands

Plan

| Command | Description | |---------|-------------| | npx forevibe init | Initialize a ForeVibe project (AI-guided planning) | | npx forevibe init --empty | Scaffold empty plan files (no LLM) | | npx forevibe init --import <file> | Import plan from a PRD / spec / README file | | npx forevibe fetch | Download your plan from forevibe.com (interactive picker) | | npx forevibe fetch <project> <plan> | Download a specific plan directly |

Develop

| Command | Description | |---------|-------------| | npx forevibe next | Show current story + acceptance criteria + what's queued | | npx forevibe check | Scan project for drift violations | | npx forevibe check --staged | Check only git-staged files (for CI/pre-commit) | | npx forevibe check --fix | Show fix suggestions for each violation | | npx forevibe check --format sarif | SARIF output for GitHub Code Scanning | | npx forevibe check --format json | JSON output for any CI pipeline | | npx forevibe check --format markdown | Markdown output for PR comments | | npx forevibe chat | Interactive AI assistant with full project context | | npx forevibe chat -m "..." | Single question (non-interactive) |

Sync Story Progress

| Command | Description | |---------|-------------| | npx forevibe sync --push | Push story completion status to forevibe.com | | npx forevibe sync --pull | Pull story statuses from server → merge into local state.json | | npx forevibe sync | Show sync status |

Sync scope: Only story completion status is synced. Plan files are server-authoritative — run forevibe fetch to update them.

Configure

| Command | Description | |---------|-------------| | npx forevibe auth | Authenticate with forevibe.com | | npx forevibe status | Show project health — stories, drift rules, completion % | | npx forevibe hooks install | Install git pre-commit drift check | | npx forevibe hooks install --claude-code | Also hook into Claude Code tool calls | | npx forevibe hooks remove | Remove the pre-commit hook | | npx forevibe config set <key> <value> | Set a config value | | npx forevibe start | Start the MCP server (stdio transport) |

Auth Requirements

| Command group | Auth needed? | |---------------|-------------| | fetch, sync | Yes — run npx forevibe auth first | | check, next, status, hooks | No — 100% local | | chat | No — uses your own LLM key (config set deepseek_api_key) | | start (MCP server) | Optional — server runs without auth, tools are local-only |

forevibe next — What To Work On

npx forevibe next

Shows:

• In-progress story — title, acceptance criteria, dependencies, AI prompt
• Next queued story — first unblocked todo (respects dependency order)
• Remaining queue — everything waiting after that

forevibe status — Project Health

npx forevibe status

Shows:

• Project name, phase, auth state
• Story completion progress bar (X/Y stories, %)
• Currently active story
• Drift rule count
• Which plan files are present / missing

Claude Code Integration

ForeVibe integrates deeply with Claude Code.

MCP Server Config

Add to .claude/settings.local.json:

{
  "mcpServers": {
    "forevibe": {
      "command": "npx",
      "args": ["forevibe", "start"]
    }
  }
}

Real-time Drift Checking (PostToolUse Hook)

npx forevibe hooks install --claude-code

Adds a PostToolUse hook that automatically runs forevibe check --staged --ci after every Write/Edit tool call — catching drift violations in real time as code is written.

MCP Server

Resources (read-only)

| URI | What it provides | |-----|------------------| | forevibe://contract | Full project plan, tech stack, goals | | forevibe://current-story | Active story with acceptance criteria | | forevibe://stories | All stories across all statuses | | forevibe://stories/{status} | Filtered: todo / in_progress / complete | | forevibe://plan/current-phase | Phase progress, gates, active stories | | forevibe://security/rules | All security rules with severity levels | | forevibe://context/blind-spots | Active and resolved blind spots | | forevibe://progress/shipment-readiness | Progress score, blockers, ready items | | forevibe://patterns/established | Established code patterns and conventions | | forevibe://files/tree | Project directory structure |

Tools (AI-callable actions)

| Tool | What it does | |------|--------------| | mark_story_complete | Mark a story done, advance to next, regenerate rules | | validate_against_plan | Check a code snippet against story AC and security rules | | get_story_details | Search stories by name, title, or acceptance criteria | | update_progress | Update phase progress and shipment readiness | | add_blindspot | Log a new risk or gap in the project | | diff_since_last_sync | Show what changed since last story completion | | regenerate_rules | Regenerate rule files |

Example AI Conversations

You: "What should I be working on right now?"
AI: → reads forevibe://current-story

You: "Does this code meet the acceptance criteria?"
AI: → calls validate_against_plan with your code

You: "Mark the auth story as done"
AI: → calls mark_story_complete("story-002", "Auth implemented with NextAuth v5")

You: "I noticed we don't have rate limiting"
AI: → calls add_blindspot("Rate Limiting", "No rate limiting on API routes", "high")

You: "What are the security rules I need to follow?"
AI: → reads forevibe://security/rules

Drift Detection

The check command scans your project for violations of your own rules — 100% local, no code leaves your machine.

# Full project scan
npx forevibe check

# Staged files only (fast, for pre-commit)
npx forevibe check --staged --ci

# Show fix suggestions
npx forevibe check --fix

# Output formats for CI pipelines
npx forevibe check --format sarif    # GitHub Code Scanning
npx forevibe check --format json     # Any CI pipeline
npx forevibe check --format markdown # PR comments

Install as a git pre-commit hook:

npx forevibe hooks install

CI example:

# .github/workflows/ci.yml
- name: ForeVibe Drift Check
  run: npx forevibe check --ci --format sarif

Authentication

npx forevibe auth

Opens your browser to authenticate with forevibe.com. Token saved to .forevibe/.auth.json, auto-added to .gitignore.

Required for: fetch (download plans) and sync (push/pull story status).

Everything else (check, next, status, hooks, start) is 100% local — no auth needed.

Development

npm run build     # Compile TypeScript → dist/
npm run dev       # Watch mode
npm start         # Run MCP server directly
npx tsc --noEmit  # Type-check only

What's New

v1.3.7

• forevibe init added to CLI Commands in README (with --empty and --import variants)
• Version consistency — all hardcoded version strings unified across CLI, fetch, sync, init, and UI
• Sync hardening — 422/403/429 error handling for push, story key validation

v1.3.5

• forevibe dev temporarily disabled — IDE setup is handled automatically via forevibe fetch
• Cleaner post-fetch output — shows only what matters: check, sync, and how to start building
• Animated tagline — reveals ForeVibe's core value props on init and fetch
• Source hardening — TypeScript source and source maps no longer published to npm

v1.3.3

• forevibe fetch — lists your available projects and plans as readable text before asking for a slug
• Re-fetch guard — warns you if a plan was already fetched and defaults to "No" on overwrite
• Auth retry loop — if browser sign-in fails, the CLI asks if you want to try again
• Update check on init — checks npm for a newer version and prompts you to update before continuing

License

MIT