mvpfy by feature1

Website · Download · MIT

The IDE for PMs, by feature1. Describe any change to your product in plain language — see it running locally, then ship it as a pull request. Like Lovable or Replit, but on your existing codebase, on your own machine, with your team's PR review as the exit. Live preview of the running app and a full VS Code editor built in. And you can plan any feature: mvpfy writes a minimal PRD in the Feature1 style for you to review and agree, then breaks it into user stories on the feature's own board and executes them one by one — each story lands as a pull request you test before calling it done. Plan as many features as you like, each with its own board, even while another feature is still being built.

mvpfy is a minimal Electron desktop app for non-technical product managers. It is a thin wrapper over Claude Code and Codex CLI — it does not reimplement any agent logic. It handles setup checks, workspace management, curated prompts, and invoking the external CLI; the agents do the actual engineering work.

Bring your own agent. mvpfy shells out to claude and codex. You must have your own API keys / subscriptions for those tools, installed and authenticated on your machine.

How is this different from Cursor / Windsurf / Antigravity?

Those are code-first tools: they open on a codebase and make engineers faster, one reviewed diff at a time. mvpfy is product-first:

• The unit of work is a change to the product — a plain-language request or a user story, never a file. The loop is describe → running app → pull request; the PM never reads a diff — the PR is the engineers' review artifact.
• AI IDEs assume a working dev environment. mvpfy manufactures one: it dockerizes the repo, finds a free port, fills in missing services with open-source stand-ins, and hands the PM a URL and demo login so they can see the product.
• The system of record is the plan: a minimal PRD and user stories on a board (To do → Coding → Testing → Done). Each story carries acceptance criteria, exits Coding as a pull request, and only a human who has tested it can move it to Done.
• mvpfy doesn't compete on the agent or the editor — it orchestrates the same engines (Claude Code, Codex) and embeds VS Code for when someone technical leans in.

In short: Cursor makes engineers faster; mvpfy makes PMs shippers.

And how is it different from Lovable / Replit?

Same magic loop — describe, see it live, ship — but pointed at a different problem. Those tools excel at building new apps in their cloud. mvpfy runs that loop on the product your company already has: your real repos, cloned locally, running in Docker on your machine (nothing leaves it), with changes exiting through a branch and a pull request your engineers review — not a deploy button. It's Lovable for the other 95% of software work: the product that already exists.

Requirements

The app checks for these CLIs on first launch (Settings → Required tools). On macOS mvpfy can install them for you — each missing tool gets an Install button that runs the command below and streams the output. Anything needing your password (Homebrew) or opening Apple's own installer (xcode-select) is handed to Terminal.app instead, because an app shouldn't pretend it can answer a sudo prompt from a pipe. The command is always shown before it runs.

Tool	Install	Runs
git	xcode-select --install	in Terminal (Apple's installer window)
Homebrew	install.sh	in Terminal (asks for your Mac password)
gh	brew install gh (then Sign in)	in mvpfy
docker	brew install --cask docker-desktop	in mvpfy
claude	curl -fsSL https://claude.ai/install.sh | bash	in mvpfy (no Homebrew or Node)
codex	npm install -g @openai/codex	in mvpfy

Every command is the tool's own official install line. On Linux and Windows the commands are shown but not run for you.

Connecting Feature1 (optional) lives in the same place: paste your workspace address — acme.feature1.ai, the full URL, or the MCP endpoint — and mvpfy works the tenant out of it, opens the browser sign-in, and stores the token in your OS keychain. Once connected it pulls your user stories into the board and pushes pull requests back.

Signing in is handled the same way. gh and codex sign in inside mvpfy; Claude Code's login is interactive, so its button opens Terminal.app running claude auth login. Git has no login of its own — pushes and private clones use the credentials gh auth login writes into git's credential helper, so mvpfy runs gh auth setup-git as part of the GitHub sign-in and the Git row says so while GitHub is not connected.

Setup

Feature1 MCP registration follows Settings → Default agent. Choose Codex CLI, then connect Feature1 (or click Reconnect if already connected) to register the workspace in Codex. Claude Code uses its existing user-scope registration flow. Registration must finish successfully before the Feature1 browser sign-in starts.

npm install

Run in development

npm run dev

Starts the Vite dev server and launches Electron against it.

The walkthrough GIF

The GIF in this README is built from captures of the running app, so it can be remade whenever the UI moves:

# screenshots in docs/media/frames/ (01-…, 02-…), or a recording at docs/media/source.mov
npm run media:gif

It scales and palettises through ffmpeg — --width 960 for a smaller file, --hold 1.6 for a quicker cut between stills — and writes docs/media/mvpfy.gif.

Build & package

To check the Codex backend with a real model run, sign in with codex login, then run:

npm run test:codex

This opt-in smoke test uses your Codex allowance and configured model through mvpfy's actual agent runner. It asks Codex to fix a tiny temporary project, checks the JSON event stream, and independently runs the fixture's tests. It keeps the fixture and diagnostic log at the printed temporary path. It does not test Docker bootstrap, Feature1 MCP, the Electron UI, or PR creation. Set MVPFY_CODEX_TEST_MODEL to test a specific model. The regular npm test command never starts this live smoke test.

npm run build      # typecheck + build renderer and main/preload
npm run package    # package the macOS app into release/

How it works

1. Add project — paste one or more GitHub/GitLab repo URLs (one per line for multi-repo stacks), or add a local repository by path / the Browse… button. Everything is cloned into ~/.mvpfy/projects/<slug>; local repos keep their original origin remote so the PR flow still targets the real remote. A local folder can instead be used in place (no copy): check Use this folder in place and mvpfy works directly in your working copy, keeping everything it generates inside a .mvpfy/ subfolder — removing the project later removes only that subfolder and the containers, never your code.

2. Bootstrap environment — this starts automatically the moment you add the project (adding it is the consent); if it can't start — your agent CLI isn't signed in, say — the project falls back to a manual Bootstrap environment button. It runs in two phases. First, in ~30 seconds, the agent reads your repos and writes a task list in plain language — "your app expects a payments service that isn't in this code, so I'll serve realistic fake responses" — which shows on the Overview as cards you can follow while the work happens. Who may close a card matters: the agent can only ever say working; mvpfy marks a task done when it can see the files that task promised, and a claim it can't confirm shows as unconfirmed rather than green. The last card — your app actually up, with a working demo login — is yours: mvpfy moves it to ready to test and only you mark it done, exactly like a user story. The goal of this step is that you can see the app running locally. mvpfy finds a free port and asks your default agent to make the repo fully runnable: it generates mvpfy.yml, a Dockerfile (if missing), docker-compose.mvpfy.yml, and .env.mvpfy.example, and fills any gaps with open-source stand-ins — official images for missing infrastructure (postgres, redis, minio, mailhog, …) and generated mock services under mvpfy/ in the repo when a backend or third-party API isn't available. If the agent is genuinely blocked (e.g. it needs the real backend repo URL), it writes its questions to mvpfy-questions.md; the app shows them, you type answers, and bootstrap re-runs with your answers. When the work finishes mvpfy starts the app itself (docker compose -f docker-compose.mvpfy.yml up -d) — unless the agent left you questions, in which case it stops and shows them instead of running a half-configured stack. The app then polls the port and the last card turns once the app actually responds. Everything the agent generated stays on the Overview for you to read, and you can stop or restart the environment at any time.

Architecture

MVC-style separation across Electron's two processes:

electron/                     — MAIN PROCESS
  main.ts                     — bootstrap: window lifecycle, service wiring
  ipc.ts                      — controller: routes typed IPC calls to services
  paths.ts                    — managed-directory layout + path guards
  services/
    shell.ts                  — platform shell layer (zsh/bash/cmd), PATH resolution
    store.ts                  — persistent state model (~/.mvpfy/state.json)
    secrets.ts                — safeStorage-encrypted token store
    cli.ts                    — CLI presence + sign-in detection
    runs.ts                   — streaming command runner (event sink injected)
    docker.ts                 — local-context pinning, daemon checks, command builders
    agents.ts                 — Claude Code / Codex invocation
    projects.ts               — workspace create/clone/read/write/delete
    net.ts                    — free ports, health probes, MCP fetch proxy
shared/                       — types + pure helpers used by both processes
src/                          — RENDERER
  lib/                        — model/domain logic (MCP client, prompts, parsers) + tests
  hooks/                      — controllers (useProjectController, useRuns)
  components/                 — presentational views (project/* cards, PreviewPane, …)

Security boundaries: the renderer is sandboxed (contextIsolation, no nodeIntegration) and reaches the system only through the typed MvpfyApi bridge; every spawned command is confined to ~/.mvpfy/projects; docker is pinned to the local engine; tokens are encrypted via the OS keychain; the MCP proxy is https-only and local probes are localhost-only.

How this repo is built: mvpfy is built the way mvpfy works — a product owner directing coding agents (mostly Claude Code). This repo is itself the demo of that workflow.

Local state

• ~/.mvpfy/state.json — tenant config, projects, settings.
• ~/.mvpfy/secrets.json — safeStorage-encrypted tokens (never plaintext).
• ~/.mvpfy/projects/<slug> — cloned repos (agents run sandboxed to these directories).
• Linked (in-place) projects live at the folder you chose; mvpfy confines itself to that folder's .mvpfy/ subfolder for everything it generates, and agents/docker are allowed only in explicitly linked folders.

Prompt templates

The curated prompts live in src/prompts/:

• bootstrap-plan.txt — read-only first pass: write the setup task list the PM watches.
• launch-readiness.txt — read-only audit: what stands between this and real users.
• bootstrap-runtime.txt — generate the Docker runtime files for a repo.
• plan-spec.txt — write the minimal PRD (Feature1-style) and the user-story plan.
• plan-implement.txt — implement one planned story end-to-end and open its PR.
• instruct.txt / ship-change.txt — apply a plain-language change / ship the workspace's changes as pull request(s).
• triage.txt — read a failed run's log, explain it in plain English, and fix the workspace.

Platform support

• macOS — primary platform, fully supported (can auto-start Docker Desktop).
• Linux — supported; start the Docker daemon yourself.
• Windows — experimental beta: commands run through cmd.exe; Docker Desktop must be running. Feedback welcome.

Beta binaries are unsigned. On macOS, right-click → Open on first launch (or xattr -dr com.apple.quarantine "/Applications/mvpfy by feature1.app").

Installing

Windows and Linux update themselves in the background. macOS cannot install an update it cannot verify, and these builds are unsigned — so on a Mac, Homebrew is the way to stay current:

brew install --cask --no-quarantine feature1-ai/mvpfy/mvpfy
brew upgrade --cask mvpfy

--no-quarantine is what lets an unsigned app open without the right-click → Open dance. It is on the command line rather than inside the cask on purpose: turning off Gatekeeper should be something you chose, not something an install did to you. Leave it off and the app installs just the same — you clear the flag yourself on first launch.

The tap is our own (feature1-ai/homebrew-mvpfy), because Homebrew's cask repository takes neither pre-release versions nor projects this small. Every release updates it automatically. Windows and Linux are downloads for now — they already update in place, and a package manager there would only disagree with the app about which version is installed.

Notes

• First version is intentionally minimal; AO integration is planned for later.
• Default Codex model is gpt-5.3-codex (override in Settings).

License

MIT

Troubleshooting

macOS says Electron is malware / the binary disappears. Apple has revoked the code hash of some older stock Electron dev binaries (malware campaigns bundled the unmodified runtime, and the revocation hits every identical copy). This project pins Electron ≥ 43, which is not affected. If you ever hit it again: don't bypass the warning — upgrade electron in package.json instead, and verify the download against the official SHASUMS256.txt from the matching GitHub release.

spawn …/Electron ENOENT when starting. The Electron binary didn't get downloaded by npm install (postinstall was skipped). Run node node_modules/electron/install.js once.

Database changes when testing a feature or pulling merged code

Test this feature checks out the feature, applies pending migrations in a one-off app container, then restarts the local Compose stack. A failed or stopped migration blocks the preview from being marked ready; its output remains available in the Plan log panel. Retry Test this feature after fixing the error. Existing database volumes are preserved.

After a PR is merged, pull/sync its code into the local workspace, then use Overview → Local database → Update database. This applies pending migrations for the currently checked out code and restarts the app without changing branches. Merging a PR remotely alone does not update the local checkout or database. Migration output is available through View logs.

New environment setups record the migration steps in mvpfy.yml (under .mvpfy/ for linked projects). Existing Rails, Django, Laravel and standard Prisma projects are detected when exactly one Compose service builds or mounts each repository. For multiple app/worker services, monorepos, custom commands or other frameworks, configure each step explicitly:

migrations:
  - service: app
    command: [bundle, exec, rails, db:migrate]

service is the name in docker-compose.mvpfy.yml. command is an argument list executed inside that service, using its environment and volumes; it is not a host shell command. Use incremental commands only, never a database reset or schema reload. Set migrations: [] for a project with no migrations. Commands run sequentially and stop on the first failure.

The app service must expose its database connection through DATABASE_URL, DB_HOST, or another supported database URL/host environment variable pointing to a local Compose Postgres/MySQL/MariaDB service. External or unverifiable targets are rejected. SQLite requires DB_DATABASE to be an absolute path inside a shared volume and DB_CONNECTION=sqlite (or a SQLite database URL). Configuration files with hidden connection settings may need those explicit environment variables before the migration step can run.

Switching back to the default branch does not undo migrations. The preview shares one persistent database across feature branches, so schema changes must remain compatible with code you switch back to. This does not apply migrations to a deployed/production database.