# Builderthread — Full Knowledge Base & System Specifications > Complete context bundle for LLMs, autonomous coding agents, and technical evaluation systems. Builderthread helps founders ship software customers pay for, in record time. It turns raw app ideas and competitor gaps into verified market demand, production starter repositories, and living blueprints ready to take payments. Website: https://builderthread.dev Canonical Pricing: https://builderthread.dev/pricing.md Compact Context: https://builderthread.dev/llms.txt ================================================================================ SECTION 1: SYSTEM OVERVIEW & ARCHITECTURE ================================================================================ Builderthread is designed for solo founders, engineering teams, and product builders using AI coding tools (Claude Code, Cursor, Codex, Windsurf, Copilot). Instead of pasting multi-thousand-line prompts into chat interfaces, Builderthread runs an automated architectural pipeline: 1. Research & Gap Analysis: Users enter a product concept or a live competitor URL. The platform crawls target product pages, analyzes search results, identifies market differentiators, and compiles a cited market brief in three minutes. 2. Living PRD (Product Requirements Document): A living PRD links feature specifications directly to the file tree and data schemas of the generated codebase. When founders adjust product scope or refine features, the PRD updates downstream task packets automatically. 3. Verified Starter Repositories: Builderthread provisions a private GitHub repository under the user's account with working boilerplate tailored to the product: - TypeScript Web App: Next.js 15, React 19, Tailwind CSS, Postgres, Drizzle ORM, Better Auth, Stripe / Polar billing. - Mobile App: React Native with Expo SDK 52, Expo Router, Tamagui / NativeWind, Hono API. - Desktop App: Tauri v2, Rust core, React / Vite frontend, SQLite storage. - Chrome Extension: Manifest V3, WXT framework, Plasmo background messaging. - Serverless Backend: Cloudflare Workers / Hono, Fastify, Trigger.dev background task runner. 4. Model Context Protocol (MCP) Gateway: Every generated repository includes MCP configuration. Coding agents query the MCP server to read current task requirements, inspect living PRD sections, retrieve stack-specific coding skills, and mark completed tasks on the Kanban board. 5. Momentum & Goal Tracking: Tracks commit history, milestones, and release readiness. Includes an automated Discord bot integration that posts daily check-in summaries and milestone progress. ================================================================================ SECTION 2: MACHINE-READABLE PRICING MATRIX ================================================================================ - Plan: Research Pass Price: $9 USD (one-time payment) Billing Model: One-time fee, credited 100% ($9) toward first month of Builder plan Active Projects: 1 Research Sources: 3 initial sources per project Research Refreshes: 0 PRD Version History: 7 days Build Packets: Unlimited for the project Agent Connections (MCP): 0 (Manual copy/paste prompt mode) GitHub Installations: 1 GitHub Repositories: 1 private repository Discord Bot: Disabled Team Members: 1 - Plan: Builder (Most Popular) Price: $39 USD/month (or $374 USD/year billed annually, 20% discount) Billing Model: Subscription Active Projects: 3 concurrent projects Research Sources: 8 initial sources per project Research Refreshes: 3 refreshes per month PRD Version History: 365 days Build Packets: Unlimited Agent Connections (MCP): 1 live agent connection per project Agent Task Completion: Automatic via MCP Build Momentum Goals: 3 active goals GitHub Installations: 1 GitHub Repositories: Up to 3 private repositories Discord Bot Updates: Enabled Team Members: 1 Deployment Guidance: Enabled (Postgres, Vercel, Supabase, Cloudflare) - Plan: Pro Price: $89 USD/month (or $854 USD/year billed annually, 20% discount) Billing Model: Subscription Active Projects: 10 concurrent projects Research Sources: 15 initial sources per project Research Refreshes: 10 refreshes per month PRD Version History: 730 days (2 years) Build Packets: Unlimited Agent Connections (MCP): 3 live agent connections per project Agent Task Completion: Automatic via MCP Build Momentum Goals: 10 active goals GitHub Installations: 3 GitHub Repositories: Up to 10 private repositories Discord Bot Updates: Enabled Team Members: 3 team seats included Deployment Guidance: Enabled with advanced cloud options - Plan: Studio Price: $179 USD/month (or $1,718 USD/year billed annually, 20% discount) Billing Model: Subscription Active Projects: 30 concurrent projects Research Sources: 30 initial sources per project Research Refreshes: 30 refreshes per month PRD Version History: 1095 days (3 years) Build Packets: Unlimited Agent Connections (MCP): 10 live agent connections per project Agent Task Completion: Automatic via MCP Build Momentum Goals: 30 active goals GitHub Installations: 10 GitHub Repositories: Up to 30 private repositories Discord Bot Updates: Enabled Team Members: 5 team seats included Deployment Guidance: Priority architectural and cloud setup support ================================================================================ SECTION 3: TECHNICAL GUIDES & DOCUMENTATION ================================================================================ --- # Guide: Skills Source URL: https://builderthread.dev/guides/features/agent-skills > The skills included in your repo and how your agent uses them. # Skills Skills are short guides your coding agent reads for a specific job. They are listed in `PRD/SKILLS.md` and `PRD/SKILL_COVERAGE.md`. ## In every repo | Skill | Used for | | --- | --- | | `copywriting` and `cro` | Any text users read: landing pages, onboarding, pricing, store listings. | | `frontend-ui-engineering` | Building accessible, consistent screens (web and extensions). | | `security-audit` (Cloudflare) | A security review at the end of every phase and before deploys. | | `ui-ux-pro-max` | Choosing a visual style. Too large to bundle, so the agent offers to install it. | ## For your stack Official skills from the tools you use (for example Stripe, Neon, Supabase, Expo, Prisma) are included when their publisher's repository and license check out. Others are offered as one install command. ## Safety - Every skill is scanned before it is included. Official publisher skills are included after Builderthread confirms they come from that publisher's own GitHub organization with an open-source license. - Your agent asks you before installing any skill, explaining what it does. - Skills never override your instructions, and downloaded skill files are never committed. --- # Guide: What is in your repo Source URL: https://builderthread.dev/guides/features/boilerplate-mapping > The working starter code, living PRDs, skills, and setup guides Builderthread puts in your private GitHub repository. # What is in your repo When you approve your product brief, Builderthread creates a private GitHub repository built for your product. Instead of handing your AI coding tool an empty folder or a generic template, Builderthread prepares working starter code, verifies that it installs and builds, and writes your PRDs and task list directly against that codebase. ## How Builderthread prepares your repository ### 1. Stack matched to your product Builderthread reads your approved brief and selects the right foundation for what you are building, whether that is a web SaaS app, an iOS and Android mobile app, a desktop app, a Chrome extension, or an API and AI backend. If you have specific preferences, you can also switch your managed Postgres provider (**Neon** or **Supabase**), your deployment host, or your preferred AI coding tool (**Cursor**, **Claude Code**, **Codex**, **Windsurf**, **VS Code with GitHub Copilot**, **Gemini CLI**, **Kiro**, or **OpenCode**) before building. ### 2. Built and checked before you clone When you click **Prepare my build**, Builderthread assembles and checks your repository in the background: 1. **Generates your starter foundation**: sets up the project structure, authentication, database wiring, and billing for your stack. 2. **Writes PRDs for your actual code**: maps every folder and script in `PRD/CODEBASE_MAP.md` and writes your modular PRDs in `PRD/` referencing the real file paths in your repository. 3. **Adds your product data model and roles**: drafts the initial database tables and user permission rules from your PRDs and documents them in `PRD/GROUNDWORK.md`. 4. **Bundles skills and agent instructions**: adds curated guides for UI design, copywriting, security reviews, and the tools in your stack, placed in the folder your coding tool reads. 5. **Pushes to your private GitHub repo**: creates the private repository on your GitHub account and emails you when it is ready to clone. ## Supported stacks Builderthread supports modern stacks across TypeScript, Python, React Native, Rust, and browser extensions: | Product | Ecosystem | Stack included | Ships to | | --- | --- | --- | --- | | **Web app (SaaS)** | TypeScript | Next.js, Hono, tRPC, Drizzle, Postgres (Neon or Supabase), Better Auth, Stripe, Trigger.dev, Vercel AI SDK, Resend | Vercel and Railway | | **API, bot, or automation** | TypeScript | Hono, OpenAPI, Drizzle, Postgres (Neon or Supabase), Better Auth, Trigger.dev, Apify, Docker | Railway | | **AI or data backend** | Python | FastAPI, Postgres, SQLAlchemy, Pydantic, OpenAI SDK, Ruff, Pytest, `uv`, Docker | Railway | | **Mobile app** | React Native | Expo, Expo Router, Uniwind, Hono API, tRPC, Drizzle, Postgres (Neon or Supabase), Better Auth, Stripe | App Store and Google Play via Expo EAS | | **Desktop app** | Desktop (TypeScript + Rust) | Tauri, React, TanStack Router, shadcn/ui | GitHub Releases (macOS, Windows, Linux installers) | | **Chrome extension** | Browser extension | WXT (Manifest V3 for Chrome and Firefox), React, TanStack Router, shadcn/ui, `chrome.storage` | Chrome Web Store | ## Files your coding agent reads first When you paste your start prompt into your AI coding tool, it reads these files first so it understands your product and codebase from the first task: - `AGENTS.md` and `CLAUDE.md`: the rulebook covering how the agent works with you, how it picks up tasks through MCP, Git branching rules, which skills to use, and when to pause for your approval. - `PRD/CODEBASE_MAP.md`: a complete map of where each part of your app lives and which scripts to run. - `PRD/product-requirements.md` and `PRD/*.md`: your living PRD documents written against the files and packages in your repository. - `PRD/GROUNDWORK.md`: the initial database tables, roles, and permission rules prepared from your PRDs. - `PRD/SKILLS.md` and `PRD/SKILL_COVERAGE.md`: the list of official tool skills and design, copy, and security guides included in your repository. - `.agents/product-marketing.md`: your product positioning, target customer, and value proposition so your agent writes clear, consistent copy across every screen. ## Setup guides and Git workflow - `docs/database.md`: step by step database setup. Web and mobile apps default to **Neon** (free cloud Postgres with a separate database branch for each feature, so you do not need Docker). Your agent asks before installing any CLI and pauses for browser login. - `docs/deployment.md` and `docs/environment-variables.md`: where your app deploys, which API keys it needs, and how to get each one. - `.github/workflows/ci.yml` (and `.builderthread/ci/github-actions.yml`): an automated GitHub Actions check that runs type checks, tests, and security checks on every push. - **Safe Git branches**: your agent works on a separate branch for each task, commits after each working step, and opens a pull request or merges into `main` once checks pass. --- # Guide: Build Momentum and Discord Source URL: https://builderthread.dev/guides/features/build-momentum > Your shipping goal, what counts as shipped, achievements, and updates in Discord. # Build Momentum and Discord Momentum watches your repo on GitHub and shows how close you are to shipping. ## Your goal When your repo is created, Builderthread sets a 30-day goal from your plan (on plans that include goals): 1. run the starter locally and finish setup, 2. ship the top MVP features, each with "done when" criteria, 3. the platform's ship step: a deployed preview, a build on a real phone, a published desktop release, or a Chrome Web Store submission. You can edit the goal, its date and milestones on the **Momentum** page. Your agent marks milestones done with `complete_milestone`. ## What counts as shipped Only things GitHub (or your agent) can prove: | Choice | Measured as | | --- | --- | | Code on main + checks pass | Commits reach your main branch (merged pull request or push) and CI checks pass. | | + a working deployment | The above, plus a successful deployment from your host's GitHub integration or one your agent records. | | + a published GitHub release | The above, plus a published release. | Your repo includes a CI workflow template; the agent installs it on its first task so checks run on every push. ## Health - **Active:** recent commits and progress. - **Quiet:** no commits for a few days. - **At risk:** three days or less left and evidence is missing. - **Blocked:** you or your agent reported a blocker. - **Shipped:** every piece of evidence is in. ## Commits and achievements The Momentum page shows a commit graph for the last 20 weeks, your streak, and achievements such as **First push**, **10 commits**, **Green checks**, **First merge**, **3-day streak**, **First milestone**, **First deploy** and **Shipped**. Achievements raise your level: Starter, Builder, Maker, Shipper, Launcher. ## Discord On the **Momentum** page, select **Add to Discord**, pick one of your servers on Discord's page, and approve. That's it: the bot posts in the server's main channel (or the first channel it can write in) and says hello. You then get achievements and level-ups, milestones completed, a message when the goal ships, goes quiet or is at risk, a note when your coding agent needs you, and a summary every Monday. Use **Move to another server** to switch. There are no commands to learn. Every message has an **Open Momentum** button, where you record a blocker, take a quiet day or check your achievements. The Monday summary includes your health, level, streak, commits and next milestone. Discord is included in Builder and above. --- # Guide: The build board Source URL: https://builderthread.dev/guides/features/kanban-export > How tasks move from Todo to Done while your coding agent works. # The build board The PRDs come with an ordered task list. Each task has acceptance criteria ("done when ..."). ## How cards move | Column | When | | --- | --- | | Todo | Ready to start. | | In Progress | The agent called `start_build_session` and is working on it. | | Done | The agent attached evidence (checks it ran, the commit) and called `complete_task`. | Completion needs evidence: a task without checks or a commit stays in progress. Tasks finish automatically once the evidence is in; if your project requires approval, they wait in **Review**. ## Build packets When the agent starts a task it receives a build packet: the acceptance criteria, the PRD sections that matter, files to change, the branch name and the checks to run. Packets count toward your monthly allowance. You can also open a task on the board to read its packet or move it yourself. --- # Guide: MCP tools Source URL: https://builderthread.dev/guides/features/mcp-agent-gateway > The tools your coding agent uses to pick up tasks, report progress and track the goal. # MCP tools These are the tools your agent sees after you [connect your coding tool](/guides/features/mcp-client-setup). The repo's `AGENTS.md` tells the agent to use them in this order. ## The routine 1. **Start a session:** `list_goals` (what "shipped" means and the next milestone), then `start_build_session`. It picks the next ready task, moves its card to **In Progress**, and returns the build packet: acceptance criteria, files to touch, branch name and checks. 2. **While working:** after each commit, `record_build_progress` with a one-line summary. 3. **Before committing:** `validate_code_diff` checks the change against the accepted PRD and decisions. 4. **Task done:** `submit_build_evidence` (checks run, commit) and `complete_task`. The card moves to **Done**. Then `start_build_session` again. 5. **Milestone done:** `complete_milestone`. **Deployed:** `record_deployment`, so the goal counts it. 6. **Stuck:** `report_blocker` posts the question to Discord and your project page. Press **Answer** in Discord (or answer on the page); the agent receives it with its next Builderthread call, so you don't need to be at the computer it runs on. When it needs keys, `request_env_values` tells you which file and how to get each one: add them, then press **I've added them** in Discord. ## All tools | Tool | Scope | What it does | | --- | --- | --- | | `list_projects` | `projects:read` | Lists the project this connection can use. | | `get_agent_context` | `prd:read`, `build:read` | Accepted PRD, decisions and open tasks. | | `get_next_actions` | `build:read` | Ready tasks in order, with what blocks the others. | | `start_build_session` | `build:read`, `progress:write` | Starts or resumes the next task and returns its build packet. | | `get_build_packet` | `build:read` | The packet for a specific task. | | `record_build_progress` | `progress:write` | Records progress on the current task. | | `submit_build_evidence` | `progress:write` | Attaches checks, test output or a commit to the task. | | `complete_task` | `tasks:complete` | Finishes the task and moves it to Done once a pushed commit is attached, the task's acceptance tests are written and CI is green on that commit. | | `list_goals` | `projects:read` | Goals, what counts as shipped, and milestone status. | | `complete_milestone` | `tasks:complete` | Marks a goal milestone done with evidence. | | `report_blocker` | `progress:write` | Asks the user for something the agent cannot do itself. | | `request_env_values` | `progress:write` | Asks you to put keys the agent cannot get itself into a local env file. You get what each is for and how to get it in Builderthread and Discord, and type the values into the file yourself. | | `pause_task` | `progress:write` | Puts a task back as not done while it waits on your answer, so the agent moves on. It comes back when you answer. | | `get_user_answers` | `projects:read` | Reads the user's answers to its questions. Answers also arrive appended to the agent's next call. | | `record_deployment` | `progress:write` | Records a working deployment (URL and commit). Never secrets. | | `validate_code_diff` | `prd:read`, `build:read` | Reviews a diff against the PRD and decisions before commit. | | `propose_prd_change` | `changes:propose` | Proposes a product change for you to approve. | | `record_decision` | `changes:propose` | Records a lasting technical decision. | The connection's scopes are `projects:read`, `prd:read`, `research:read`, `build:read`, `skills:read`, `changes:propose`, `progress:write` and `tasks:complete`. ## Plan limits - Reading works for anyone on an active plan with MCP agent connections (Builder, Pro, and Studio). - Starting tasks, recording progress, and calling `complete_task` or `complete_milestone` require Builder or above. - Every paid plan includes all build packets for your project with no monthly cap. When a call is not part of the plan, the agent gets a clear "ask the user to upgrade" message and keeps coding locally. --- # Guide: Connect your coding tool Source URL: https://builderthread.dev/guides/features/mcp-client-setup > Connect Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI, Kiro or OpenCode so the agent can pick up tasks and report progress. # Connect your coding tool Your repo already contains the Builderthread MCP configuration for your project. MCP is how your coding agent reads tasks, gets build packets and moves cards on the board. You only approve a browser sign-in once. You need a plan that includes a coding-agent connection (Builder and above). ## Easiest: paste the start prompt Open your project, go to the **Build** tab and copy the **Start building** prompt into your coding tool. It clones the repo, connects MCP and starts the first task. The steps below are what the agent does, if you want to do it yourself. ### Claude Code 1. Clone the repo and open a terminal in it, then run `claude`. 2. Claude Code finds `.mcp.json` and asks whether to use the `builderthread` server. Approve it. 3. Type `/mcp`, select `builderthread` and choose **Authenticate**. Your browser opens; sign in to Builderthread and approve the project. Without the repo, you can add it by hand: `claude mcp add --transport http builderthread `. ### Cursor 1. Open the cloned repo in Cursor. It reads `.cursor/mcp.json`. 2. Open **Settings → MCP**. Next to `builderthread`, select **Login** (or **Connect**) and approve the project in the browser. 3. The tools appear in Agent mode. ### Codex 1. Open the cloned repo with Codex and trust the project when asked. Codex reads `.codex/config.toml` for trusted projects. 2. Run `codex mcp login builderthread` and approve the project in the browser. ### Windsurf Windsurf keeps MCP servers in its own settings rather than in the repo. 1. Open **Windsurf Settings → MCP servers → View raw config**. 2. Copy the `builderthread` entry from `.builderthread/mcp/windsurf.json` in your repo into that file and save. 3. Refresh the server list and approve the browser sign-in. ### VS Code (GitHub Copilot) 1. Open the cloned repo in VS Code. It reads `.vscode/mcp.json`. 2. Open that file and select **Start** above the `builderthread` server (or use **MCP: List Servers**). Approve the browser sign-in. 3. Use Copilot in Agent mode; it also reads `AGENTS.md`. ### Gemini CLI 1. Run `gemini` in the cloned repo. It reads `.gemini/settings.json` and `GEMINI.md`. 2. Type `/mcp auth builderthread` and approve the project in the browser. ### Kiro 1. Open the cloned repo in Kiro. It reads `.kiro/settings/mcp.json` and the steering file in `.kiro/steering/`. 2. In the MCP servers panel, connect `builderthread` and approve the browser sign-in. ### OpenCode 1. Open the cloned repo. OpenCode reads `opencode.json` and `AGENTS.md`. 2. Run `opencode mcp auth builderthread` and approve the project in the browser. ## Your project's MCP URL The configs point to a URL like `https:///api/mcp/`. It is tied to one project. The repo contains no tokens or passwords: sign-in happens in your browser. ## If something does not work - **No tools show up:** restart the MCP server in your tool, then sign in again. - **Asked to sign in again:** your session expired or was revoked. Sign in again from the tool's MCP settings. - **"This action needs an active plan" (402):** the action is not part of your plan. Upgrade in **Settings → Billing**; your agent can keep coding locally meanwhile. - **The repo says MCP setup is pending:** the agent works from the PRD and task list in the repo until your workspace has a public address. Next: [the MCP tools your agent uses](/guides/features/mcp-agent-gateway). --- # Guide: Research and the brief Source URL: https://builderthread.dev/guides/features/smart-research > How Builderthread researches your idea or competitor URL and turns live market evidence into a product brief. # Research and the brief Before writing a single line of code, Builderthread researches the live web so your product plan is based on real market gaps, competitor pricing, and customer complaints rather than guesswork. ## How Builderthread researches your market When you submit an idea or paste a product URL, Builderthread investigates the market in two ways at the same time: - **Visits live product pages**: Builderthread opens the product's website (or competing products in your space), reading the homepage, pricing page, features page, and about page to capture how existing tools work and what they charge. - **Runs Google searches across multiple angles**: Builderthread searches Google for competitor plans, upgrade limits, alternatives, recent launches, and real user reviews and complaints on Reddit, Hacker News, G2, and app stores. Research runs in the background and finishes in about three minutes. Every finding links directly to the web pages Builderthread visited so you can verify any claim in one click. ## Starting from an idea vs a competitor URL You can start a project from a rough idea in your head or from an existing product you want to beat: - **Start from an idea**: describe what you want to build and who it is for. Builderthread searches Google and visits existing tools in that category to uncover how people solve the problem today, what current options cost, and where they fall short. - **Start from a product URL**: paste the link to a product you want to improve on. Builderthread visits the product's key pages, researches its reviews and alternatives on Google, and maps out its features, pricing tiers, and weak spots. In both cases, Builderthread handles the research without asking you to fill out questionnaires. Any assumptions it makes are listed clearly in the brief so you can review or adjust them. ## What is inside your brief Your research brief gives you and your coding agent a complete picture of what to build and why: ### 1. Problem, buyer, and positioning - **Problem and target customer**: who buys in this category, the job they are trying to get done, and the workarounds they rely on today. - **Differentiating wedge**: the specific angle that makes your product sharper, faster, or easier to adopt than existing options. ### 2. Competitor breakdown - **Existing alternatives**: the main products in the space and where each one falls short. - **Feature inventory**: capabilities existing products offer, grouped by area, so you can decide what to match, skip, or improve. - **Pricing tiers and limits**: real plan names, prices, billing units, and the usage caps that push users to upgrade. - **Repeated pain points**: frustrations and unmet needs in users' own words, with direct links to the reviews and forum threads where they were found. ### 3. Your MVP blueprint - **Core MVP features**: five to ten high impact features for your first release, each tied to a real user pain point and written with clear "done when" criteria. - **Personas and key user flows**: the step by step journeys users take through your product. - **Data records and integrations**: the core records your app will store in its database and any external services it needs. - **Assumptions and scope boundaries**: risky assumptions to keep in mind and features intentionally left out of version one so you ship faster. ## Reviewing and approving Once your brief is ready, you can read through the cited sources, edit any section, and click **Approve** to generate your starter repository and living PRDs. The number of web sources included in each research run depends on your plan (shown on the pricing page). --- # Guide: How it works Source URL: https://builderthread.dev/guides/getting-started/overview > Every step from submitting an idea or URL to a private GitHub repo your coding agent builds from. # How it works ## 1. Create a project On **Projects**, type your app idea (who it is for and what it should do) or paste the URL of an existing product you want to beat. Builderthread immediately starts researching the market: it visits live product pages and searches Google for competitor features, pricing plans, user complaints, and alternatives. You do not have to answer any questionnaires. Research takes about three minutes, and you can leave the page while it runs. ## 2. Review the brief When research finishes, Builderthread presents a cited brief covering: - the problem, target customer, and positioning angle, - the features existing products offer and what they charge, - where current users are unhappy, with links to the sources, - the five to ten MVP features to build first, user flows, and data records. Review the brief (and edit anything you want to refine), then approve it to continue. ## 3. Build your repository From your approved brief, Builderthread automatically selects and recommends the right stack for your product, whether it is a web SaaS app, an Expo mobile app, a Tauri desktop app, a Chrome extension, or an API and AI backend. You can keep the recommended setup or change your database provider, hosting target, or coding tool if you prefer. Connect your GitHub account and select **Prepare my build**. In the background, Builderthread: 1. generates and verifies the working starter code for your stack, 2. writes your living PRDs and initial data model against that exact codebase (real file paths, packages, and scripts), 3. adds stack skills, a GitHub Actions check workflow, and instructions for your coding agent, 4. creates the private repository on your GitHub account. This takes about 30 minutes in the background. You get a notification and an email as soon as your repository is ready. ## 4. Copy the start prompt Open your project. The **Build** tab gives you a **Start building** prompt. Paste that prompt into your AI coding tool (Claude Code, Cursor, Codex, Windsurf, or another supported editor). Your agent clones the repository, walks you through setup (asking before it installs anything or creates accounts), and starts building the first task. ## 5. Track progress - The **build board** moves each task from Todo to In Progress to Done as your agent completes and verifies each feature. - **Momentum** tracks your shipping goal, commits, milestones, and achievements, and can post progress updates to your Discord server. ## Plans Research Pass ($9 one time) covers one full project: market research, the cited brief, a private GitHub starter repository, living PRDs, and every build packet for that project, with your $9 credited toward your first Builder payment. Live coding agent connections (MCP), Build Momentum goals, Discord updates, and automatic agent task completion are included in Builder and above. See **Settings → Billing**. --- # Guide: Builderthread guides Source URL: https://builderthread.dev/guides > Go from an app idea or a product URL to a private GitHub repo your AI coding tool builds from. # Builderthread Builderthread turns an app idea, or the URL of a product you want to beat, into a ready-to-build private GitHub repository. Your AI coding tool (Claude Code, Cursor, Codex, Windsurf, or another supported editor) then builds the product task by task while Builderthread tracks your progress. ## How it works in four steps 1. **Describe it or paste a URL.** Type your idea or paste a competitor URL. Builderthread visits live product pages and searches Google to write a cited market brief in about three minutes. 2. **Prepare your build.** Approve the brief, connect GitHub, and click **Prepare my build**. Builderthread selects the right stack for your product (web, mobile, desktop, Chrome extension, or backend) and creates your private GitHub repo with working starter code, living PRDs written for that code, skills, and agent instructions. This runs in the background for about 30 minutes, and you get an email when it is ready. 3. **Start building.** Copy the start prompt into your AI coding tool. It clones the repo and works through the tasks one by one, asking you before installing anything or creating accounts. 4. **Watch it ship.** Tasks move across your build board as the agent finishes them, and your Momentum page tracks commits, milestones, and achievements. ## Guides - [How it works, step by step](/guides/getting-started/overview) - [Research and the brief](/guides/features/smart-research) - [What is in your repo](/guides/features/boilerplate-mapping) - [Connect your coding tool](/guides/features/mcp-client-setup) - [MCP tools your agent uses](/guides/features/mcp-agent-gateway) - [The build board](/guides/features/kanban-export) - [Build Momentum and Discord](/guides/features/build-momentum) - [Skills](/guides/features/agent-skills) ================================================================================ SECTION 4: TECHNICAL PLAYBOOKS & ENGINEERING ARTICLES ================================================================================ --- # Article: Comparing AI Coding Tools for Full-Stack SaaS: Claude Code, Cursor, Codex, and Windsurf Source URL: https://builderthread.dev/blog/claude-code-vs-cursor-codex-windsurf Date: 2026-10-31 Author: Builderthread Engineering > A direct speed and cost comparison of Claude Code, Cursor, OpenAI Codex, and Windsurf on full-stack application builds, covering task completion time, multi-file edits, and token spend. Developers building full-stack applications with artificial intelligence now choose between terminal agents, specialized editors, and autonomous cloud runners. This benchmark evaluates Claude Code, Cursor, OpenAI Codex, and Windsurf across full-stack repository setup, task packet execution, and long-session stability. ## Benchmark Summary | Feature | Claude Code | Cursor | OpenAI Codex | Windsurf | | :--- | :--- | :--- | :--- | :--- | | **Interface** | Terminal CLI | VS Code Fork | CLI / Cloud Runner | VS Code Fork | | **Primary Model** | Claude 3.7 / 3.5 Sonnet | Sonnet / GPT-4o / Claude | GPT-4o / o1 / o3-mini | Cascade / Sonnet | | **MCP Support** | Native stdio and SSE | Native (.cursor/mcp.json) | Custom API adapters | Partial / Custom | | **Multi-File Edits** | High (patch-based) | High (multi-file diff) | High (git branch output) | High (Cascade agent) | | **Terminal Autonomy** | Yes (runs bash in terminal) | Optional (agent terminal) | Yes (sandboxed runner) | Optional (Cascade terminal) | | **Context Window** | 200,000 tokens | 200,000 tokens | 128,000 - 200,000 tokens | 200,000 tokens | | **Average Task Cost** | $0.08 - $0.25 per task | Included in subscription / usage | $0.10 - $0.35 per task | Included in subscription | | **Best Use Case** | Fast terminal execution | Visual review & UI refinement | Batch task pipelines | Hybrid tab-and-prompt coding | ## What Defines an Effective AI Coding Tool? An effective AI coding tool executes discrete task packets without losing architectural context. It reads existing database schemas, adheres to authentication boundaries, runs test suites, and requests human confirmation before deploying or installing external packages. Tools fail when developers feed them monolithic 5,000-line requirement documents in a single chat turn. High-performing workflows split product specifications into living PRDs, connect tools through the Model Context Protocol (MCP), and verify code after every commit. ## 1. Claude Code (Anthropic Terminal Agent) Claude Code runs in your terminal. It inspects your file tree, searches codebases using grep and glob utilities, executes shell commands, runs test suites, and creates git commits without manual guidance. ### Strengths - Fast terminal iteration: Claude Code runs tests, catches compile errors, and fixes syntax mistakes in a single loop. - Native MCP support: Configures via standard configuration files. Connects to project management boards and PRD endpoints without UI plugins. - Prompt caching: Anthropic prompt caching cuts token costs by up to 90 percent on recurring repository contexts. ### Limitations - No visual diff interface: Developers inspect diffs via git diff or terminal pagers rather than inline editor highlights. - Requires local CLI authorization: Developers must authenticate in a terminal environment with shell access. ### Recommended Workflow Use Claude Code for foundational setup, database migrations, backend endpoint wiring, and test-driven bug fixes. ```bash # Start Claude Code on a Builderthread repository claude-code "Read task 1 from the MCP server, verify the schema, and run tests" ``` ## 2. Cursor (AI-First Code Editor) Cursor forks Visual Studio Code and integrates LLM reasoning into file editing, composer workflows, and code review gutters. ### Strengths - Visual multi-file diffing: Shows green and red additions inside your editor tabs before saving changes to disk. - Symbol indexing: Indexes your workspace into local vector embeddings for fast semantic code retrieval. - Flexible model selection: Switch between Claude 3.7 Sonnet, OpenAI o3-mini, and Gemini models within the same session. ### Limitations - Context window fatigue: Long composer threads accumulate token weight, slowing response times and increasing hallucination rates unless developers start fresh composer sessions. - Higher memory footprint: Runs full Electron VS Code runtime alongside language server processes. ### Recommended Workflow Use Cursor for component design, Tailwind styling, page layout assembly, and visual code reviews. ## 3. OpenAI Codex & Autonomous Cloud Runners OpenAI Codex interfaces power autonomous runners that take GitHub issues, run inside isolated Docker containers, and submit ready-to-merge pull requests. ### Strengths - Asynchronous task processing: Runs tasks in background containers without tying up your local laptop. - Strict sandbox isolation: Protects local machines from experimental scripts or dependency issues. - Strong reasoning models: Access to OpenAI o1 and o3-mini reasoning engines for intricate data structure algorithms. ### Limitations - Slow feedback loops: Reviewing changes requires waiting for a full git push and PR generation cycle. - Higher setup requirements: Requires container configuration and remote environment variable provisioning. ## 4. Windsurf (Codeium Cascade) Windsurf combines an editor fork with Cascade, a collaborative agent that tracks developer intent across multiple files. ### Strengths - Supercomplete autocomplete: Predicts multi-line edits and cursor movements ahead of keystrokes. - Clear file tracking: Displays active working files in a compact side panel. - Balanced pricing: Competitive monthly subscription with predictable usage limits. ### Limitations - Smaller third-party plugin ecosystem compared to mainline VS Code extensions. - MCP client support is newer and less standardized than Claude Code and Cursor. ## How to Structure Projects for Any Coding Tool Regardless of which tool you select, four rules determine whether your build succeeds: 1. Never dump raw unformatted idea text into a prompt. Convert the idea into a verified specification with explicit database models and route lists. 2. Limit tasks to single pull requests. Each task should touch no more than 3 to 8 files. 3. Keep specifications external to chat memory. Use living PRD documents and MCP servers so new agent sessions load fresh context on demand. 4. Run static type checking after every turn. Execute TypeScript or compiler checks before marking a task complete. Builderthread generates starter repositories configured for Claude Code, Cursor, Codex, and Windsurf, pre-loaded with Model Context Protocol configurations and task packets. --- # Article: Living PRD Architecture: Why Structured Specs Beat Raw Prompts for AI Coding Agents Source URL: https://builderthread.dev/blog/living-prd-architecture-for-coding-agents Date: 2026-10-31 Author: Builderthread Engineering > How structured living specifications eliminate context window drift, define strict data boundaries, and turn chaotic AI chat sessions into rapid, deterministic software launches. Developers building software with artificial intelligence often encounter a common failure mode: after five or six conversational prompts, the coding agent forgets earlier architectural choices, introduces duplicate database columns, and breaks existing API contracts. This breakdown occurs because chat transcripts make terrible source-of-truth documents. Chat logs intermingle code snippets, reasoning attempts, and debugging corrections into an unstructured token stream. A living Product Requirements Document (PRD) fixes this problem by decoupling product specifications from conversational history. ## What is a Living PRD? A living PRD is an editable, version-controlled specification file mapped to an application codebase. Unlike static design documents that sit untouched after kickoff, a living PRD updates alongside project tasks. When a founder refines a data model or adjusts billing tiers, the specification updates downstream prompt packets so coding agents never build from obsolete requirements. ## The Five Structural Sections of an Agent-Ready PRD To guide an autonomous coding agent, a specification document must answer five questions with zero ambiguity: ### 1. Data Schema and Entity Relationships Agents write cleaner code when database tables, types, and foreign keys are defined in advance. The PRD must define table names, column types, default values, and index requirements. ```typescript // Example: Strict schema contract in living PRD export interface ProjectEntity { id: string; // Primary key (cuid2) organizationId: string; // Foreign key -> Organization.id name: string; // Project display title (max 64 chars) status: 'draft' | 'building' | 'complete' | 'archived'; createdAt: Date; // Timestamp with timezone } ``` ### 2. Authentication and Authorization Boundaries Specify who can perform each action. Never let the model infer access controls: - Public endpoints: Landing pages, public marketing content, webhooks. - Authenticated user endpoints: Account settings, personal project lists. - Organization admin endpoints: Billing configuration, team invitations, API key management. ### 3. Concrete API Request and Response Shapes Define exact JSON payloads for every route. Coding agents match these shapes against frontend client components and database query procedures without guessing parameter names. ### 4. Ordered Build Packets Break broad features into small, atomic tasks. Each packet contains: - Target files to create or modify. - Acceptance criteria written as test assertions. - Explicit prohibitions (for example: "Do not install external modal libraries; use existing Radix dialog components"). ### 5. Verification Commands Provide explicit verification scripts the agent must run before concluding work: - Type check: `pnpm type-check` - Linter: `pnpm lint` - Test suite: `pnpm test` ## Why Traditional PRDs Fail with AI Agents Traditional product requirement documents contain paragraphs of marketing rationale, user personas, and aspirational roadmaps. Human engineers scan past this copy to find the technical constraints. AI agents, by contrast, treat all input tokens with the same baseline weight. When 60 percent of a prompt consists of high-level marketing narrative, the model allocates precious attention heads to brand voice rather than schema types and error handling. | Traditional PRD | Living PRD for AI Agents | | :--- | :--- | | **Format** | Google Doc or Notion page | Markdown repository files | | **Location** | External document silo | Inside repository (`docs/` and MCP endpoint) | | **Updates** | Manual; abandoned after week two | Automated sync linked to Kanban boards | | **Audience** | Human stakeholders and managers | Coding agents and human reviewers | | **Content** | Personas, user stories, business cases | Typed schemas, API routes, task packets | | **Validation** | Subjective review meetings | Automated compiler checks and unit tests | ## How Builderthread Implements Living PRDs Builderthread generates living PRD packets from initial product research. When you approve a market brief, the platform provisions your private GitHub repository and structures living specifications into organized files: 1. `00_OVERVIEW.md`: System mission, target personas, and core tech stack decisions. 2. `01_DATABASE_SCHEMA.md`: Prisma or Drizzle schema definitions and migration sequence. 3. `02_API_ARCHITECTURE.md`: Server procedures, input schemas, and authentication guards. 4. `03_FEATURE_SPECIFICATIONS.md`: Task packets ordered by dependency. Your coding tool connects to these specifications through the Model Context Protocol (MCP). Instead of stuffing the entire specification into your prompt, your agent requests the exact file it needs for the current task. When you modify a feature in the Builderthread dashboard, the platform updates the living PRD and notifies your agent on its next check-in. --- # Article: Model Context Protocol for AI Coding Agents: Building and Connecting Custom MCP Tools Source URL: https://builderthread.dev/blog/mcp-gateway-model-context-protocol-guide Date: 2026-10-31 Author: Builderthread Engineering > A practical guide to Model Context Protocol (MCP) servers for coding tools, explaining how tools and resources eliminate manual prompt pasting to ship features in record time. The Model Context Protocol (MCP) is an open standard created by Anthropic that connects artificial intelligence applications to external tools, databases, and development servers. Before MCP, developers copied API keys, database schemas, and requirement files into chat prompts by hand. With MCP, your coding tool queries your project workspace, calls remote tools, and reports build progress without manual steps. ## What is the Model Context Protocol? The Model Context Protocol (MCP) is a client-server protocol that enables AI models to discover tools, inspect structured data resources, and execute functions through JSON-RPC 2.0 messages. MCP clients (including Claude Code, Cursor, and Windsurf) communicate with local processes over standard input and output (stdio) or remote servers over Server-Sent Events (SSE). ## The Three Core Primitives of MCP MCP defines three primary capabilities: 1. **Tools**: Executable functions that models invoke to take actions in the real world (for example: running a test, fetching a task, updating a ticket status). 2. **Resources**: Read-only data payloads that provide file contents, database snapshots, or living specifications. 3. **Prompts**: Pre-configured prompt templates that standardize workflows across developers. ## Why MCP Matters for AI Coding When an AI coding agent works on a software project, it needs real-time context: - Which task should I build next? - What database tables exist? - What are the acceptance criteria for this feature? - Did my code pass verification? Without MCP, the developer acts as a manual copy-paste router between their project management tool, terminal, and AI editor. With MCP, the coding tool runs an autonomous feedback loop: ``` +---------------------------------------------------------+ | AI Coding Agent | | (Claude Code, Cursor, Codex) | +---------------------------------------------------------+ | ^ | 1. get_next_task() | 2. Task packet v | +---------------------------------------------------------+ | MCP Server | | (Builderthread Gateway) | +---------------------------------------------------------+ | ^ | 3. mark_task_done(taskId) | 4. Next task v | +---------------------------------------------------------+ | Project Kanban & Living PRD | +---------------------------------------------------------+ ``` ## How to Configure MCP in Coding Tools ### 1. Claude Code Configuration Add your MCP server definition to your project `.claude/mcp.json` or your global configuration file: ```json { "mcpServers": { "builderthread": { "command": "npx", "args": ["-y", "@builderthread/mcp-server"], "env": { "BUILDERTHREAD_PROJECT_ID": "your_project_id", "BUILDERTHREAD_API_KEY": "your_api_key" } } } } ``` ### 2. Cursor Configuration In Cursor, create `.cursor/mcp.json` in your repository root: ```json { "mcpServers": { "builderthread": { "url": "https://builderthread.dev/api/mcp/your_project_id", "headers": { "Authorization": "Bearer your_token" } } } } ``` ## Essential MCP Tools for Coding Agents A complete project management MCP server exposes four primary tools: ### `get_next_task` Returns the highest-priority pending task from your build board. The tool returns the task title, description, target files, acceptance criteria, and schema requirements. ### `get_prd_section` Accepts a section identifier (for example: `authentication` or `database`) and returns the exact markdown requirements from your living PRD. This ensures the model reads the latest spec without blowing its token budget on unrelated sections. ### `update_task_status` Moves a task from `todo` to `in_progress` or `done`. When your agent finishes writing code and passes test suites, it calls this tool to update your board without manual intervention. ### `get_stack_skills` Fetches verified coding guidelines for your chosen stack. For example, in a Next.js 15 repository, this tool returns best practices for Server Components, caching tags, and route handlers. ## Performance and Security Considerations 1. **Keep tool responses compact**: AI models pay token costs for every byte returned by MCP tools. Strip redundant metadata and return concise markdown or JSON. 2. **Never expose raw secrets**: MCP servers should never return production database passwords or private signing keys. Return endpoint descriptions and instruct agents to read environment variables from local `.env` files. 3. **Require human confirmation for destructive actions**: Tools that execute database drops or live deployments must request explicit human consent before execution. Builderthread repositories include pre-configured MCP integration out of the box, connecting your coding agent to your project brief, living PRDs, and task boards.