How Idea HQ works

A plain-language guide. No technical background needed. Keep this page handy: it is the answer to most "what do I do now?" moments.

What Idea HQ is

Idea HQ is a notebook for the ideas behind your projects, with an AI helper that can turn an idea into a real change in your project. You write what you want. The AI works out how big it is, writes a plan, builds it, and tests it. Then you look at the result and decide if it goes live.

It is not a website builder and it does not run your app. Your project stays where it already lives, on GitHub. Idea HQ just helps you plan and build changes to it, safely.

The big picture

1. You write an idea. Plain words are fine.
2. The AI estimates it. A rough size: small, medium, large or extra large.
3. The AI writes a plan (called the build prompt). You can read and approve it.
4. The AI builds it in a safe copy of your project, and runs your checks.
5. You review the result as a "pull request" (a proposed change you can read).
6. You approve it and it joins your real project, or you ask for changes, or you close it.

Words used here

Project

One product or codebase of yours, like "My webshop". Ideas belong to a project.

Idea

Something you want to change or add, written in plain words.

Build prompt

The plan the AI follows for an idea. It is written for you to read.

GitHub

The website where your project's code is stored. Think of it as cloud storage for code that remembers every change.

Repo (repository)

Your project's folder on GitHub.

Branch

A separate copy of your project to try changes in, so the real one stays untouched. "main" is usually the real one.

Pull request (PR)

A proposed change. It shows exactly what was added and removed, and waits for your yes or no.

Merge

Saying yes: the proposed change joins the real project.

Checks

Automatic tests that run on a change, like a spell-check for code. Green means passed, red means a problem.

API key

A long secret password that lets the AI work and bills the usage to your Anthropic account. Keep it private.

Workflow

A small file in your project that lets GitHub run the AI for you. Idea HQ adds it through a pull request you approve once.

Before you start

• A GitHub account. Free. Your project's code needs to be on GitHub already.
• An Anthropic account and an API key. Make one at console.anthropic.com. Set a small monthly spending limit while you learn.
• An approved Idea HQ account. After you sign up, the owner approves you. You do not have to do anything while you wait.

Setup, step by step

The app walks you through this and ticks each step off by itself. This is what you will see and why.

1. 1

   Create your first project

   Give it a name. It is only a label for you.
2. 2

   Connect GitHub

   Click Connect GitHub. GitHub asks you to sign in and allow the app. You choose which repos it may see. Pick only the ones you want to use with Idea HQ. You can change this later in GitHub, under Settings, Applications.
3. 3

   Choose the repo and the branch

   Pick your project's repo. For the branch, enter the one that holds your real project, usually main. The AI's changes will be proposed against it.
4. 4

   Set the checks

   These are the commands that test a change. The app suggests them from your project, so just click Use them. If you do not know, leaving them empty works, but then nothing tests the AI's work.
5. 5

   Install the workflow

   Click the button. Idea HQ opens a pull request in your repo that adds one small file. Open it on GitHub and click Merge. You only do this once per project. It is the file that lets GitHub run the AI for you, with a time limit.
6. 6

   Add your API key to the repo

   Open the page the app links to. It must be a Secret (the Secrets tab), never a Variable: variables are shown in plain text. Name it ANTHROPIC_API_KEY, paste your key, and save. The key stays in GitHub. Idea HQ never sees it.
7. 7

   Teach the AI about your project

   Click Read my repo and describe it. The AI looks through your project and writes down what it is, how it is built and how to run it. Read it, then click This looks right, or fix what is wrong. A good description makes every later estimate and plan better. The next section explains how to improve it further.

How the AI learns your project

The AI can only do good work if it understands your project. Idea HQ keeps a page for that: open Projects and click Knows 60% (or the percentage you see) on any project. It shows what the AI knows, in six plain topics: what it is, the technology, how it is organised, how to run and ship it, rules, and known quirks. Each topic says whether it is Missing, Needs review or Confirmed, and where it came from.

• Quick draft from my repo: reads the key files in seconds and fills in what it can see. Safe to repeat. It never overwrites what you wrote or confirmed.
• Learn deeply in my GitHub: the AI explores your whole project inside your own GitHub, like a new teammate reading the code. It takes a few minutes, uses your Anthropic key (usually under a dollar), and what it writes appears on the page marked Needs review.
• Answer a few questions: optional. The AI asks plain questions about the gaps, like what must never change, and adds your answers.
• This is right / Edit: check each topic. Anything you edit or confirm is protected, so the AI will not overwrite it later.
• Save a copy in my repo: opens a pull request that adds the knowledge to your project as a text file, so other AI tools you use start with the same understanding. Idea HQ always keeps its own copy too.
• What it learns over time: after each change, Idea HQ notes what shipped, what you asked to be fixed, and what failed. You can pin the ones that matter, add your own rules, or delete any.

Your first AI change

Start tiny, so you learn the loop cheaply. The practice idea (add one line to the README) is perfect.

1. Add the idea, then click Generate build prompt. Read the plan it writes.
2. Click Implement. You will see which AI model and effort it picked, and why. Leave it as it is for now.
3. Click Approve and run. It takes a few minutes. The status moves from "Starting" to "AI is working" to "PR ready for review".
4. When it says Build and tests passed, open the pull request link and look at what changed.
5. Click Approve and merge. The idea is marked done.

Everyday use

• Big ideas: click Break into stories. The AI splits it into small steps that build on each other. You build them one at a time, in order, and merge each before the next.
• Not quite right? Use Request changes on the pull request and say what to adjust, in plain words. The AI updates the same proposal.
• Changed your mind after merging? Use Revert this change. It creates a new proposal that undoes it, which you approve like any other.
• AI model: chosen automatically from the size of the idea. Small ideas use a cheap, fast model, big ones a stronger one. You can change it before each run, and set a project to lean cheaper or stronger.
• Many ideas at once: one run per project at a time, so changes do not collide. Queue the rest.

Writing good ideas

• One thing per idea. "Add a search box to the ideas page" is better than "improve the ideas page".
• Say what done looks like. "When I type in the box, the list shows only matching ideas."
• Mention what to leave alone if it matters. "Do not change the sign-in page."
• Too big? If the estimate says large or extra large, break it into stories first. Smaller steps are cheaper and fail less.

Staying in control

• You approve the plan before anything runs.
• Every change is a pull request you can read. Nothing joins your project until you say yes.
• The build and tests must pass before the merge button works.
• The AI runs in your own GitHub, with a time limit and a cap on how many steps it may take. It only touches the repo you connected.
• Your API key lives in GitHub, not in Idea HQ.
• Auto-merge is off by default. If you turn it on for a project, it only merges when every check is green and the main branch is protected on GitHub.
• You can undo any merged change with one button.

What it costs

Idea HQ does not charge you. The AI work is billed by Anthropic to the API key you add to your repo. Small changes typically cost cents. A medium change is usually a few tens of cents. Bigger ones cost more, and stronger models cost more per step.

• Set a monthly spending limit in your Anthropic account. It is the best safety net.
• Each run has a time limit and a step cap, so a stuck run cannot run up a bill forever.
• After each run, Idea HQ shows what it cost.
• The quick helper steps (estimates, plans, project description) are paid by the Idea HQ owner and limited per person each day.

If you get stuck