Idea HQ

One backlog for all your projects. Capture an idea, tag it to a project, and the AI estimates its effort/value and writes a ready-to-paste build prompt — grounded in that project's real architecture, not a generic guess.

Lifted from the Snapmeal ideas board and made multi-project: each Project carries its own context (its ARCHITECTURE.md / stack / models / deploy flow), which is the exact text handed to Claude when it estimates or plans an idea for that project.

Stack

Next.js 15 (App Router) · React 19 · Prisma 7 → Neon Postgres · NextAuth (credentials + optional Google) · Anthropic Claude · Tailwind · deployed on Vercel. AI changes run in the owner's own GitHub through a GitHub App and an Actions workflow.

Getting started

Use Node 20 (.nvmrc; CI uses the same file, so nvm use matches it).

1. npm install
2. Copy .env.example to .env and fill in DATABASE_URL, NEXTAUTH_SECRET, ANTHROPIC_API_KEY, OWNER_EMAIL.
3. npx prisma db push to create the schema in your Neon database.
4. npm run dev, open http://localhost:3000, register (the first account becomes the owner).
5. Go to Projects, add each project and paste its context (its ARCHITECTURE.md).
6. Go to Ideas, capture an idea under a project — the estimate fills in automatically.

Try it locally, with nothing to set up

npm install
npm run dev:local

Open http://localhost:3100 and sign in as [email protected] with dev-password-local-only. This runs the whole app on an in-memory Postgres (PGlite, src/lib/db-pglite.ts) filled with sample data (src/lib/dev-seed.ts): a project with an idea in every stage of the journey (needs a plan, ready to build, the AI working, failed checks, ready to merge, shipped, a revert waiting), an Epic, and another person's idea that must never show. No Neon, no GitHub, no AI key: the AI key is blanked, so nothing can spend money (set IDEAHQ_ALLOW_AI=1 to allow it), and GitHub calls simply find nothing. Everything resets when the server stops. It only exists when IDEAHQ_DB=pglite is set (scripts/local.mjs does that); a normal build never contains it, and it refuses to start on Vercel.

Tests

• npm test runs the unit and database tests (Vitest, with the real SQL on PGlite).
• npm run test:e2e builds the local version above and runs the smoke tests in a real browser (Playwright, e2e/): sign-in, the Ideas list with each idea's stage and next step, the Needs you filter, every stage of the idea card, light and dark, and a phone width. The first time, run npx playwright install chromium. npm run test:e2e:fast reuses the last build. The same tests run in CI as the smoke job. When the sample data changes, change the expectations in e2e/ with it.

Deploy

Set the same env vars in Vercel, then git push origin main. The build runs prisma db push (additive schema changes only). The build (scripts/build.mjs) runs it only on a production deploy, without --accept-data-loss: a change that would drop data fails the build and the live site stays as it was. To drop something on purpose, set ALLOW_DATA_LOSS=1 for that one deploy and remove it afterwards. Preview and local builds never change the schema.

Layout

• src/app/(app)/ideas — the board (list + kanban), detail page, shared helpers
• src/app/(app)/projects — project admin (the per-project context lives here)
• src/app/api/ideas/[id]/estimate — AI effort/value/tags/scope
• src/app/api/ideas/[id]/plan — AI build prompt for a coding agent
• src/lib/project-context.ts — turns a project's context into the AI grounding block

Implement with AI (GitHub App + Actions)

The Implement button on an idea runs Claude Code in the project's own GitHub repo (in that repo's GitHub Actions, with that repo's ANTHROPIC_API_KEY secret), then opens a pull request. Idea HQ only dispatches the run and listens to GitHub webhooks. See the eng review in ~/.gstack/projects/vitoc82-se-Idea-hq/ for the design.

One-time server setup: create the GitHub App

GitHub, Settings, Developer settings, GitHub Apps, New GitHub App:

• Homepage URL / Webhook URL: https://ideahq.cloud/api/github/webhook
• Webhook secret: a long random string (GITHUB_WEBHOOK_SECRET)
• Setup URL: https://ideahq.cloud/api/github/callback, and tick Request user authorization (OAuth) during installation
• Repository permissions: Contents: Read and write. Pull requests: Read and write. Workflows: Read and write. Actions: Read and write. Commit statuses: Read. Checks: Read. Secrets: Read and write (the "add my key to my repos" relay writes the API key as an Actions secret; it also reads whether the secret exists). Metadata: Read. This is the whole list and nothing more is needed (reviewed against every GitHub call in src/lib/github/client.ts, 2026-10-21); do not add Administration, Issues or Members.
• Subscribe to events: Workflow run, Pull request, Check suite, Check run, Status (Push is not used; leave it off)
• Where can this app be installed: Any account (or only you, for a private start)

Then generate a private key and a client secret, and set these in Vercel:

Variable	Value
GITHUB_APP_ID	numeric App ID
GITHUB_APP_SLUG	the app's URL slug (also used as allowed_bots in the workflow)
GITHUB_APP_PRIVATE_KEY	the PEM, with newlines as \n
GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET	from the app page (install-ownership check)
GITHUB_WEBHOOK_SECRET	same string as in the app
AI_DAILY_LIMIT	optional, per-user daily estimate/plan/breakdown calls (default 20)

This is the beginning of the README. Read the rest at the original. Read the full README ↗