ProtoForge

AI-Powered Prototype Builder for Hardware, Software, and Hybrid Projects

ProtoForge is an open-source CLI tool that uses AI to generate complete prototype packages from natural language descriptions. It creates everything you need to build your project: code, schematics, BOMs, build guides, and documentation.

Anti-AI-Design Philosophy

ProtoForge rejects the typical AI interface clichés:

┌─────────────────────────────────────────────────────────────────┐
│ NO CHAT BUBBLES        │ NO GRADIENTS         │ NO ROUNDED     │
│ NO FLOATING BUTTONS    │ NO GLOW EFFECTS      │ NO ANIMATIONS  │
│ NO MINIMALIST SPARSE   │ NO "COPILOT" STYLE   │ TERMINAL FIRST │
└─────────────────────────────────────────────────────────────────┘

Our interfaces are built for efficiency and productivity, not engagement metrics:

• Split-panel layout inspired by terminal multiplexers (tmux, screen)
• Visible borders and grid lines - no hidden boundaries
• High contrast terminal colors - no subtle gradients
• Monospace typography everywhere - including the web interface
• Angular brutalist aesthetics - 0px border-radius
• Dense information display - efficiency over white space
• ASCII art banners - real terminal culture, not AI marketing

Installation

Prerequisites

• Node.js 18+
• npm
• Optional: Ollama for local AI generation

Global Install (Recommended)

npm install -g protoforge
protoforge --version

After a global install, the protoforge command should work immediately (no npm link required).

Method 2: Using the Install Command

# Run the built-in install command
protoforge install

# This will show you the exact commands for your system

Method 3: From Source

# Clone and install locally
git clone https://github.com/protoforge/protoforge.git
cd protoforge
npm install
npm link

# Run locally without global install
npm start

Platform-Specific Notes

Linux/macOS:

# May require sudo for global install
sudo npm install -g protoforge

# Or use nvm to avoid sudo
nvm use --lts
npm install -g protoforge

Windows:

# Ensure Node.js is in your PATH
npm install -g protoforge

Docker:

# Run without installation
docker run --rm -it protoforge/cli

Setup (API keys + preferences)

Run:

protoforge setup

The setup wizard prompts in this order:

1. AI provider (default: Ollama — local & free)
2. Ollama URL (default: http://localhost:11434) and model (default: llama3.1)
3. Optional cloud AI key (OpenAI or Groq)
4. 3D preview (HTML) (no Meshy; generated locally as an HTML preview)
5. Web/output settings

Keys are stored locally via the conf module in ~/.protoforge/config.json.

Usage

Interactive TUI Mode

protoforge start

(You can also run protoforge with no args to start the TUI.)

Navigate with arrow keys:

• New Prototype: Enter a description and generate
• Recent Projects: View previously generated projects
• Settings: Configure AI providers and preferences
• Web Interface: Launch the local web dashboard

Command-Line Generation

Generate a prototype directly from the command line:

# Basic usage
protoforge build "A smart plant monitor with moisture sensor"

# With options
protoforge build "IoT weather station" \
  --type hardware \
  --provider ollama \
  --output ./my-projects \
  --zip

# Hybrid project
protoforge build "Smart doorbell with camera and mobile app" \
  --type hybrid

Web Interface (Main Editing Place)

protoforge web
# or
protoforge --web

Opens http://localhost:3000 with a split-panel layout:

• Left: command input + generation log
• Right tabs: Scripts (file browser + editor), Diagrams (Mermaid), 3D Preview (HTML), BOM, Guide
• ZIP export

Anti-AI-design enforced: no chat bubbles, no gradients, angular borders, monospace, dense info.

Configuration Commands

View and edit configuration:

# View all settings
protoforge config

# Get specific setting
protoforge config --get chatbot.provider

# Set a value
protoforge config --set chatbot.provider ollama

# Reset all configuration
protoforge config --reset

Output Structure

Generated prototypes are saved to ./protoforge-output/ (or custom directory):

project-name-timestamp/
├── code/
│   ├── main.ino          # Arduino/firmware code
│   ├── app.js            # Backend application
│   └── index.html        # Frontend interface
├── schematics/
│   ├── diagram.mmmd      # Mermaid diagram
│   └── 3d-description.md # 3D model specs
├── docs/
│   ├── overview.md       # Project overview
│   ├── tech-stack.md     # Technology recommendations
│   ├── build-guide.md    # Step-by-step guide
│   └── issues-and-fixes.md
├── bom.csv               # Bill of materials
├── report.md             # Complete project report
└── prototype.json        # Raw prototype data

AI Providers

Ollama (Recommended - Local)

Most private and cost-effective. Requires Ollama installed:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull recommended model
ollama pull llama3.1

Configure in ProtoForge:

Chatbot Provider: Ollama (Local)
URL: http://localhost:11434
Model: llama3.1

Cloud Providers

All require API keys:

| Provider | Setup | Recommended Model | |----------|-------|-------------------| | OpenAI | Get key from platform.openai.com | gpt-4-turbo | | Groq | Get key from groq.com | llama-3.1-70b-versatile | | Anthropic | Get key from anthropic.com | claude-sonnet-4 | | Gemini | Get key from aistudio.google.com | gemini-2.0-flash |

Example Prototypes

IoT Weather Station

protoforge build "A weather station that measures temperature, humidity, and pressure using ESP32, displays on OLED, and sends data to MQTT"

Smart Home Controller

protoforge build "Home automation controller with voice control, supporting Zigbee devices, with a React dashboard"

Robotic Arm

protoforge build "4-DOF robotic arm with Arduino Uno, SG90 servos, and inverse kinematics code"

Configuration File

ProtoForge stores configuration in ~/.protoforge/config.json:

{
  "chatbot": {
    "provider": "ollama"
  },
  "providers": {
    "ollama": {
      "url": "http://localhost:11434",
      "model": "llama3.1"
    }
  },
  "imageGen": {
    "provider": "none"
  },
  "meshy3d": {
    "enabled": false
  },
  "settings": {
    "outputDir": "./protoforge-output",
    "autoOpenBrowser": true
  }
}

Development

Tests

npm test

Debugging generation failures

When generation fails, ProtoForge preserves the output directory and writes:

• prototype.raw.txt (raw model output)
• prototype.parse-error.txt (parse/validation error, if any)
• .protoforge-error.txt (stack trace / error context)

This makes it much easier to reproduce and file issues.

Project Structure

protoforge/
├── bin/
│   └── protoforge.js      # CLI entry point
├── lib/
│   ├── ai/
│   │   └── adapter.js     # AI provider adapters
│   ├── core/
│   │   ├── config.js      # Configuration management
│   │   ├── generator.js   # Core generation logic
│   │   └── output.js      # File output handling
│   ├── prompts/
│   │   └── system.js      # LLM system prompts
│   ├── ui/
│   │   ├── App.jsx        # Ink TUI components
│   │   └── setup.js       # Setup wizard
│   ├── utils/
│   │   └── helpers.js     # Utility functions
│   └── web/
│       └── server.js      # Express web server
├── public/                # Static web assets
├── package.json
└── README.md

Running from Source

# Development mode with hot reload
npm run dev

# Link for testing
npm link

# Run CLI
protoforge

Adding New AI Providers

To add a new AI provider, extend lib/ai/adapter.js:

// Add provider type
case 'newprovider':
  return this._initNewProviderClient();

// Implement initialization
_initNewProviderClient() {
  return {
    type: 'newprovider',
    async complete(prompt, options) {
      // Your API integration
    }
  };
}

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Ideas for Contributions

• Additional AI provider integrations
• Project templates and presets
• Export formats (PDF, Markdown variants)
• Enhanced TUI components
• Web dashboard improvements
• Documentation translations

Roadmap

• [ ] Project templates (Arduino, Raspberry Pi, ESP32, etc.)
• [ ] Multi-file code generation with dependencies
• [ ] Interactive schematic editor
• [ ] 3D model viewer integration
• [ ] Collaborative features
• [ ] Cloud sync (optional)

License

MIT License - see LICENSE for details.

Acknowledgments

• Ollama - Local LLM infrastructure
• Ink - React for CLI
• Mermaid - Diagram generation
• OpenAI - Cloud AI APIs
• (3D preview is rendered locally as HTML; no Meshy dependency)

Built with ❤️ by the ProtoForge Team