ProtoForge Documentation

Introduction

ProtoForge is a native macOS app that prototypes real things from plain-English descriptions. Unlike chat tools that only write code, ProtoForge also produces the artifacts you need to physically build hardware: wiring diagrams, bills of materials, firmware, interactive 3D part viewers, and step-by-step assembly guides.

It runs entirely on your machine. You bring your own AI provider key (15+ supported), and nothing — keys, prompts, or projects — ever touches our servers. It's free and open source under the MIT license; an optional $6/mo ProtoForge Plan unlocks hardware mode, sub-agents and unlimited prompts.

Install

1. Download the DMG. Grab the latest ProtoForge-macOS-universal.dmg (universal — Apple Silicon & Intel).
2. Open it and drag ProtoForge.app into your Applications folder.
3. First launch. Right-click the app → Open (the build is unsigned, so Gatekeeper asks once). After that, launch normally.
4. Python check. ProtoForge bundles a Python backend; on first run it sets up a virtual environment automatically. Give it a few seconds.

Requirements

Quick Start

1. Open the model picker. Click the robot-face icon in the chat bar, choose a provider, paste your API key, pick a model, hit Apply.
2. Pick a mode. Software (free) or Hardware/Hybrid (Plan). The toggle is in the left sidebar.
3. Describe your project. e.g. "A line-following robot with obstacle avoidance" or "A REST API for tracking inventory".
4. Press Enter. ProtoForge may ask a couple of clarifying questions, then generates everything into the workbench tabs.
5. Iterate. Keep chatting — it remembers the conversation. Open the terminal to run the generated files.

The Interface

ProtoForge has two columns: the console (left) and the workbench (right).

• Left — Console: the Project Type toggle (Software / Hardware), the chat log, and the chat composer.
• Right — Workbench: a top bar (theme, terminal, download, account), the output tabs (3D Model, Diagram, BOM, Instructions, Code), and a status bar.
• Settings cog: bottom-right — plan status and sub-agent configuration.

Modes: Software / Hardware / Hybrid

Chat Composer

The rounded input bar at the bottom of the console. Left to right, the toolbar buttons are:

Model Picker

Click the robot-face icon to open the compact model popup. Set everything in one place:

• Provider — OpenRouter, Together, Anthropic, OpenAI, DeepSeek, Groq, and more.
• API Key — pasted here; stored locally on your device only.
• Model — the dropdown auto-fetches the provider's live model list once your key is entered (15-min cache). Custom endpoints get a free-type box.
• Mode — Text or Image-Gen. Image-Gen only lights up for providers that support it.

Image Upload & Vision

Click the camera icon to attach a reference image. The image appears in your chat message above your text, and ProtoForge sends it to the model's vision input — so the AI actually sees your inspiration and builds from it.

• Upload a photo of a device, a sketch, a UI screenshot, a product — anything.
• Works with vision-capable models. Image input is supported across OpenAI-compatible providers, Anthropic, Ollama, and others.
• An image with little/no text is treated as "recognize this" — ProtoForge describes what it sees and how to prototype it.

Deep Thinking (brain toggle)

Click the brain icon to enable reasoning mode. When on, ProtoForge applies each model's native thinking parameters and captures the reasoning tokens:

• OpenAI / Gemini → reasoning_effort. Qwen / SiliconFlow → enable_thinking. DeepSeek → reasoner model. Anthropic → extended thinking. Groq, Together, Kimi, GLM, MiniMax, OpenRouter, Volc — each wired to its real API.
• Models with no native mode fall back to an explicit step-by-step directive.
• While thinking, a "thinking" chip shows in the bar. Click it to open the live reasoning log.

The toggle is remembered between sessions.

Sub-Agents PLAN

Configure a team of specialized AI agents that discuss, build and review your project together. Roles include Planner, Coder, Reviewer, and Tester.

• Set the max number of agents (1–10), nicknames, and an optional per-agent API key in Settings → Sub-Agents.
• The discussion streams live into a collapsible panel as each agent contributes.
• When agents are configured, generation uses the real multi-agent flow end-to-end.

Planning Loop

Before building, ProtoForge can run a short planning loop with three tools:

• question_tool — asks 1–3 clarifying questions as tidy option chips. Pick answers, then hit Submit answers; the form collapses into a clean summary.
• research_tool — pulls in relevant context for the build.
• deep_thinking — reasons through the approach before generating.

Answer the questions and ProtoForge folds them into an enriched prompt, so the output matches what you actually want.

Workbench Tabs

Output lands in tabs across the top of the workbench. Hardware/hybrid surfaces all of them; software mode hides the hardware-only ones.

Code & Firmware

The Code tab shows a file tree plus a viewer. For software projects it holds the full source. For hardware projects it now generates real firmware — not just a diagram:

• ProtoForge picks the right platform from the BOM — Arduino/ESP32 → .ino C++, Raspberry Pi → .py, STM32 → .c.
• The firmware uses the exact pins from the wiring diagram, includes every library, and has working logic for every module — no stubs or TODOs.

// firmware.ino — generated for an HC-SR04 + Arduino Uno
#define TRIG 9
#define ECHO 10
void setup() {
  Serial.begin(9600);
  pinMode(TRIG, OUTPUT); pinMode(ECHO, INPUT);
}
void loop() {
  digitalWrite(TRIG, LOW); delayMicroseconds(2);
  digitalWrite(TRIG, HIGH); delayMicroseconds(10); digitalWrite(TRIG, LOW);
  long d = pulseIn(ECHO, HIGH) * 0.034 / 2;
  Serial.println(d);
}

Diagram · BOM · 3D

• Diagram — a Mermaid circuit/system diagram that renders inline. Theme-aware.
• BOM — a table of name, quantity, reference designator and notes for every part.
• 3D Model — an interactive Three.js assembly of simplified parts, laid out sensibly so you can see how the build fits together.
• Instructions — pin-by-pin, build-along steps including wiring (with wire colors), flashing, power-on test and a troubleshooting tip.

Agent Terminal

Click the >_ button in the workbench top bar to open the terminal. It opens directly inside the agent workspace — the folder of files ProtoForge just generated — not your home directory.

• Edit, run, compile, or port the generated files right there.
• It's a full interactive shell, scoped to the current project.
• Switch projects and reopen — the terminal lands in the new project's workspace.

Live Preview & Export

• Preview — for software projects with an index.html, hit the in-app preview to see it run live.
• Download .zip — export the whole project from the workbench top bar.
• Share — generate an AI-written social post about what you built.

AI Providers

ProtoForge speaks the OpenAI-compatible API, so you can bring almost any provider. Built-in options:

Getting API Keys

1. Pick a provider from the list above. For a free start, try Groq, OpenRouter (free models), or Together.
2. Create an account on the provider's site and open their API-keys / console page.
3. Generate a key and copy it.
4. Paste it into the model picker (robot-face icon) in ProtoForge and hit Apply.

Models & the Dropdown

Once a key is entered, the model dropdown fetches the live list from the provider's /v1/models endpoint and shows exactly what your key can use, sorted alphabetically. Results are cached for 15 minutes; changing the key busts the cache and refetches.

Custom / unknown endpoints get a free-type box so you can enter any model id.

Image Generation

Switch the model picker to Image-Gen mode to use a provider's image models. Only providers that actually offer image generation enable this mode, including:

• OpenAI (gpt-image / DALL·E), Together & SiliconFlow (FLUX, SD), Zhipu (CogView), Qwen (Wan), Google (Imagen), MiniMax.
• Text-only providers (Anthropic, Kimi, etc.) keep image-gen disabled.

Free vs Plan

The free tier is fully functional for software projects. You still bring your own AI key on both tiers.

Unlock PRO

1. Open Settings (the cog, bottom-right) → Plan tab.
2. Click Pay with PayPal and complete the $6/mo subscription.
3. Back in the app, the plan flips to Active and Hardware / Hybrid / Sub-Agents unlock.

Cancel anytime from PayPal. The plan is tied to your purchase, not your AI usage — you still use your own provider key.

Chat & History

• Context — ProtoForge remembers the conversation. Ask "what did you just build?" and it answers from history instead of generating a random new project.
• New chat — the + icon in the chat header clears the session and resets the workbench.
• History — the clock icon opens past chats; click one to reopen it.

Settings

The settings cog (bottom-right) opens a card with two tabs:

• Plan — current tier, the $6/mo plan with its feature list, PayPal unlock, and your free-prompt status.
• Sub-Agents — max agents, roles, nicknames and per-agent keys (Plan only).

Privacy

ProtoForge is local-first. A native app with a Python backend runs entirely on your Mac:

• Your API keys are stored on-device and sent directly to your chosen provider.
• Prompts, generated files and projects stay on your machine.
• No accounts, no cloud, no telemetry of your work.

Troubleshooting

FAQ

Which provider should I use?

Free: Groq, OpenRouter (free models), Together. Best quality: Claude (Anthropic), DeepSeek, GPT. Any OpenAI-compatible endpoint works, including your own.

Is my data safe?

Yes — everything runs locally and keys go straight to your provider. See Privacy.

How accurate are hardware schematics?

ProtoForge generates pin-to-pin connections with real part numbers. Accuracy scales with model quality — verify before ordering parts or building circuits.

Who built this?

ProtoForge was built by a 13-year-old. Open source under MIT; contributions welcome.

Does it work on Windows / Linux?

The packaged app targets macOS. The backend is Python and the project is open source, so other platforms are possible from source.

Open Source

ProtoForge is MIT-licensed and developed in the open.

• Repo: github.com/snarsnat/protoforge-v2
• Issues & ideas: open an issue
• Stars welcome — they genuinely help.

Support

• Email: help@pforge.xyz
• X / Twitter: @happinezreal
• Buy me a coffee: buymeacoffee.com/nebsol