ForeVibe

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

ForeVibe gives every AI coding assistant a living memory of your project. It stores your plan, stories, security rules, architecture, and delivery schedule in a local .forevibe/ directory — then surfaces all of it through an MCP server and editor rule files 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 dashboard)
npx forevibe fetch

# 3. Set up your IDE — detects Cursor, Windsurf, Claude Code, etc. automatically
npx forevibe dev

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

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. Plan files are server-authoritative — forevibe sync only moves story completion status, not plan edits.

Full Workflow

# One-time setup
npx forevibe auth              ← authenticate with forevibe.com

# Get your plan
→ Go to forevibe.com, start a project, complete discovery session
npx forevibe fetch             ← download plan into .forevibe/

# Set up development
npx forevibe dev               ← detect IDE, compile rules, configure MCP, get kickoff prompt
npx forevibe start             ← start MCP server (keep running)

── daily loop ───────────────────────────────────────────────────────
npx forevibe next              ← what's my current story + acceptance criteria?
  → paste kickoff prompt into AI agent → code
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 compile           ← regenerate rule files after fetching a new plan
npx forevibe fetch             ← re-fetch if plan changes on forevibe.com
npx forevibe sync --pull       ← pull updated story statuses from server

CLI Commands

Get a Plan

| Command | Description | |---------|-------------| | npx forevibe fetch | Download your plan from forevibe.com (interactive project + plan picker) | | npx forevibe fetch <project> <plan> | Download a specific plan directly | | npx forevibe init --empty | Scaffold empty plan files to fill in manually |

Develop

| Command | Description | |---------|-------------| | npx forevibe dev | Detect IDE, compile rules, configure MCP, print AI kickoff prompt | | npx forevibe dev --ide cursor | Force Cursor setup | | npx forevibe dev --ide claude | Force Claude Code setup | | npx forevibe dev --ide windsurf | Force Windsurf setup | | npx forevibe dev --ide copilot | Force VS Code / Copilot setup | | npx forevibe dev --ide gemini | Force Gemini CLI setup | | 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) |

Compile Rule Files

| Command | Description | |---------|-------------| | npx forevibe compile | Generate all editor rule files | | npx forevibe compile --claude | AGENTS.md + Claude Code slash commands | | npx forevibe compile --cursor | .cursorrules | | npx forevibe compile --copilot | .github/copilot-instructions.md | | npx forevibe compile --mdc | .cursor/rules/*.mdc (Cursor v2 drift rules) | | npx forevibe compile --windsurf | .windsurf/rules/core.md + preferences.md | | npx forevibe compile --gemini | .gemini/styleguide.md |

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 (contract.json, story_cards.json, etc.) are server-authoritative — run forevibe fetch to update them, not sync --push.

Configure

| 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 (e.g. deepseek_api_key) | | npx forevibe start | Start the MCP server (stdio transport) |

Auth Requirements

| Command group | Auth needed? | |---------------|-------------| | fetch, sync | Yes — run npx forevibe auth first | | check, compile, dev, 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 dev — IDE-Aware Setup

npx forevibe dev is the fastest way to go from a plan to coding. It detects your IDE from environment variables and does everything for you:

1. Detects your IDE — Cursor, Windsurf, Claude Code, VS Code, Gemini CLI, Firebase Studio, Zed, JetBrains
2. Compiles the right files for that IDE (rule files, instructions, slash commands)
3. Configures MCP in the IDE's config file (merges, never overwrites)
4. Prints a ready-to-paste kickoff prompt with your project name + current story

npx forevibe dev               # auto-detect
npx forevibe dev --ide cursor  # force Cursor
npx forevibe dev --ide claude  # force Claude Code

What gets written per IDE:

| IDE | Files generated | MCP config | |-----|----------------|-----------| | Claude Code | AGENTS.md, .claude/commands/*.md | .claude/settings.local.json | | Cursor | .cursorrules, .cursor/rules/*.mdc | .cursor/mcp.json | | Windsurf | .windsurf/rules/core.md, preferences.md | .windsurf/mcp.json | | VS Code / Copilot | .github/copilot-instructions.md | — | | Gemini CLI | .gemini/styleguide.md | — |

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.

1. Automatic Setup

npx forevibe dev --ide claude

This runs compile --claude, configures the MCP server in .claude/settings.local.json, and prints a kickoff prompt to paste directly into Claude Code.

2. AGENTS.md + Slash Commands

AGENTS.md is auto-loaded by Claude Code on every session — your full project context is always present without any manual steps.

Slash commands available after compile --claude:

/forevibe-check       ← scans for drift, explains what's wrong
/forevibe-plan        ← refines your plan with AI
/forevibe-compile     ← regenerates AGENTS.md, .cursorrules, etc.

3. Real-time Drift Checking (PostToolUse Hook)

npx forevibe hooks install --claude-code

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

4. MCP Server Config

forevibe dev writes this automatically, but you can also add it manually:

// .claude/settings.local.json
{
  "mcpServers": {
    "forevibe": {
      "command": "npx",
      "args": ["forevibe", "start"]
    }
  }
}

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 all .cursor/rules/*.mdc 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

Editor Rule Files

npx forevibe compile generates static rule files your editor reads automatically:

| File | Editor | Description | |------|--------|-------------| | AGENTS.md | Claude Code, Gemini CLI, others | Universal AI agent instructions | | .cursorrules | Cursor | Project plan + security rules as instructions | | .github/copilot-instructions.md | GitHub Copilot | Copilot workspace instructions | | .cursor/rules/*.mdc | Cursor v2 | Fine-grained drift rules, security, patterns | | .windsurf/rules/core.md | Windsurf | Architecture, stack, security rules | | .windsurf/rules/preferences.md | Windsurf | Living doc — patterns and conventions | | .gemini/styleguide.md | Gemini CLI | Style guide and invariants | | .claude/commands/*.md | Claude Code | /forevibe-* slash commands |

These files work even without an active MCP connection — a "hybrid mode" that gives you AI guardrails everywhere.

Project Files

After npx forevibe plan + npx forevibe dev, your project contains:

your-project/
├── .forevibe/
│   ├── contract.json          # Locked scope + tech decisions
│   ├── story_cards.json       # All stories with ACs + AI prompts
│   ├── feature_graph.json     # Feature/epic/story DAG
│   ├── delivery_packs.json    # Phased delivery schedule
│   ├── state.json             # Progress tracker
│   ├── checks.json            # Security guardrails + drift rules
│   ├── architecture.json      # Arch summary + components + DB tables
│   ├── cursor_rules.json      # Machine-readable coding invariants
│   ├── runbook.json           # Release + rollback steps
│   └── .auth.json             # Auth token (git-ignored, auto-created)
├── .claude/
│   ├── commands/              # Claude Code slash commands
│   │   ├── forevibe-check.md
│   │   ├── forevibe-plan.md
│   │   └── forevibe-compile.md
│   └── settings.local.json    # MCP config + PostToolUse hook
├── .cursor/
│   ├── mcp.json               # MCP server config
│   └── rules/                 # Cursor v2 static drift rules
│       ├── core.mdc
│       ├── security.mdc
│       ├── database.mdc
│       ├── preferences.mdc
│       └── stories/current.mdc
├── .windsurf/
│   └── rules/
│       ├── core.md
│       └── preferences.md
├── .gemini/
│   └── styleguide.md
├── .github/
│   ├── copilot-instructions.md
│   └── workflows/ci.yml
├── .cursorrules               # Cursor rules
├── AGENTS.md                  # Universal AI agent instructions
└── .env.example

Safe re-init: If any of these paths already exist when you run npx forevibe init, they are automatically renamed to {name}.bak.{timestamp} — nothing is silently overwritten.

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, compile, dev, next, status, hooks, start) is 100% local — no auth needed. chat uses your own LLM key set via config set deepseek_api_key.

Development

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

License

MIT