{"id":49955390,"url":"https://github.com/aaroncx/forge","last_synced_at":"2026-05-17T23:04:41.981Z","repository":{"id":343560123,"uuid":"1178035884","full_name":"AaronCx/Forge","owner":"AaronCx","description":"Forge — agentic AI orchestration platform with workspace IDE, visual blueprints, computer use, and multi-model support","archived":false,"fork":false,"pushed_at":"2026-04-27T22:14:25.000Z","size":2201,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T22:17:03.528Z","etag":null,"topics":["agentic-ai","agents","ai","blueprint","cli","computer-use","fastapi","gui-automation","langchain","llm","multi-agent","nextjs","openai","orchestration","python","supabase","typescript","workflow-automation"],"latest_commit_sha":null,"homepage":"https://forge-theta-teal.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AaronCx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T16:12:16.000Z","updated_at":"2026-04-27T22:14:28.000Z","dependencies_parsed_at":"2026-03-25T00:05:28.484Z","dependency_job_id":null,"html_url":"https://github.com/AaronCx/Forge","commit_stats":null,"previous_names":["aaroncx/agentforge","aaroncx/forge"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/AaronCx/Forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronCx%2FForge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronCx%2FForge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronCx%2FForge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronCx%2FForge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AaronCx","download_url":"https://codeload.github.com/AaronCx/Forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AaronCx%2FForge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33158772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"ssl_error","status_checked_at":"2026-05-17T22:39:10.741Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","ai","blueprint","cli","computer-use","fastapi","gui-automation","langchain","llm","multi-agent","nextjs","openai","orchestration","python","supabase","typescript","workflow-automation"],"created_at":"2026-05-17T23:04:41.003Z","updated_at":"2026-05-17T23:04:41.976Z","avatar_url":"https://github.com/AaronCx.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Forge\n\n**Agentic AI orchestration platform — design workflows visually, automate GUIs and terminals, and coordinate agents across machines.**\n\nBuild AI-powered workflows that chain LLM reasoning with deterministic logic, automate any desktop or terminal, and orchestrate multiple agents in parallel. Visual DAG editor with 44 node types, cross-platform computer use, multi-model provider support, and real-time execution streaming. Runs fully local with SQLite (zero external accounts) or scales to cloud with Supabase.\n\n![Version](https://img.shields.io/badge/version-2.1.0-blue)\n![Tests](https://img.shields.io/badge/tests-641_passing-brightgreen)\n![Next.js](https://img.shields.io/badge/Next.js-14-black)\n![FastAPI](https://img.shields.io/badge/FastAPI-0.115-teal)\n![Python](https://img.shields.io/badge/Python-3.12-blue)\n![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n---\n\n## Features\n\n### Visual Blueprint System\nDrag-and-drop DAG workflow builder with 44 node types across 9 categories. Topological execution engine with concurrent layer resolution, context assembly with token budgets, retry policies, and SSE-streamed execution traces.\n\n### Computer Use (GUI + Terminal)\nAgents operate machines through GUI automation and terminal orchestration across macOS, Linux, and Windows:\n\n| Capability | Nodes | What It Does |\n|-----------|-------|-------------|\n| **GUI (Steer)** | 12 | Screenshot, OCR, click, type, hotkey, scroll, drag, focus, find, wait, clipboard, app listing |\n| **Terminal (Drive)** | 6 | Session management, command execution, key sending, log capture, polling, parallel fanout |\n| **CU Agents** | 4 | LLM-powered Planner, Analyzer, Verifier, Error Handler |\n| **Screen Recording** | 1 | Record sessions via CoreGraphics + ffmpeg (works over SSH) |\n| **Safety** | — | App/command blocklist, rate limiting, approval gates, audit logging |\n\n### Cross-Platform Support\n\n| Platform | GUI Automation | Terminal | Method |\n|----------|---------------|----------|--------|\n| macOS | Native Steer CLI (CoreGraphics, cliclick, Vision OCR) | Drive CLI / tmux | Works over SSH |\n| Linux | xdotool, scrot, tesseract, wmctrl, xclip | tmux | Xvfb for headless |\n| Windows | pyautogui, pytesseract, pygetwindow | PowerShell + WSL/tmux | Python packages |\n\n### Agent-on-Agent Orchestration\nSpawn and control external coding agents (Claude Code, Codex CLI, Gemini CLI, Aider) as workers in tmux sessions. Full lifecycle management with 6 agent control blueprint nodes.\n\n### Multi-Machine Dispatch\nRoute blueprint nodes to different execution targets. Dispatch routing: explicit target → blueprint default → capability-based → local fallback.\n\n### Multi-Model Providers\nProvider registry supporting OpenAI, Anthropic, and Google. Per-node model selection, health monitoring, and comparison tools.\n\n### Knowledge Base + RAG\nDocument collections with chunked upload, semantic search, and a `knowledge_retrieval` blueprint node for RAG-augmented workflows.\n\n### Eval Framework\nTest agent outputs with grading methods: exact_match, contains, json_schema, screenshot_match, ocr_contains. Multi-model comparison and per-prompt-version evaluation.\n\n### Human-in-the-Loop\n`approval_gate` blueprint node pauses execution for human review. Approve/reject with inbox UI and CLI.\n\n### MCP Integration\nModel Context Protocol connection management. Agents dynamically discover and use tools from connected MCP servers.\n\n### Observability + Prompt Versioning\nDistributed trace recording for all executions. Version prompts like code — diff, rollback, and measure how changes affect output quality.\n\n### Workflow Marketplace\nPublish, browse, fork, and rate blueprints. Organization support with member RBAC.\n\n### Workspace IDE\nIntegrated development environment with CodeMirror 6 web editor, file tree, editor tabs, integrated terminal (xterm.js), and agent activity panel. Real-time file sync via WebSocket — when an agent modifies a file, you see it instantly. Workspace blueprint nodes (workspace_read, workspace_write, workspace_list, workspace_search) let agents operate directly on your files.\n\n### Live Dashboard + CLI\nReal-time monitoring with heartbeat tracking, SSE-powered updates, cost analytics. CLI-first experience with 35+ command groups covering the full platform — no browser required.\n\n---\n\n## Node Types (48)\n\n| Category | Count | Nodes |\n|----------|-------|-------|\n| Context | 3 | fetch_url, fetch_document, knowledge_retrieval |\n| Transform | 2 | text_splitter, template_renderer |\n| Validate | 3 | json_validator, run_linter, approval_gate |\n| Output | 2 | output_formatter, chunker |\n| Agent (LLM) | 5 | llm_summarize, llm_extract, llm_generate, llm_review, llm_classify |\n| GUI (Steer) | 13 | steer_see, steer_ocr, steer_click, steer_type, steer_hotkey, steer_scroll, steer_drag, steer_focus, steer_find, steer_wait, steer_clipboard, steer_apps, recording_control |\n| Terminal (Drive) | 6 | drive_session, drive_run, drive_send, drive_logs, drive_poll, drive_fanout |\n| CU Agent | 4 | cu_planner, cu_analyzer, cu_verifier, cu_error_handler |\n| Agent Control | 6 | agent_spawn, agent_prompt, agent_monitor, agent_wait, agent_stop, agent_result |\n| Workspace | 4 | workspace_read, workspace_write, workspace_list, workspace_search |\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph Frontend[\"Frontend (Next.js 14)\"]\n        UI[React UI + shadcn/ui]\n        Auth[Supabase Auth]\n        SSE[SSE Client]\n        Editor[Blueprint Editor]\n    end\n\n    subgraph Backend[\"Backend (FastAPI)\"]\n        API[REST API]\n        Engine[Blueprint Engine]\n        Orchestrator[Orchestrator]\n        Messaging[Messaging Service]\n        Providers[Provider Registry]\n        CU[Computer Use]\n        Dispatch[Multi-Machine Dispatch]\n        Agents[Agent-on-Agent]\n        Stream[SSE Streaming]\n    end\n\n    subgraph ComputerUse[\"Computer Use Layer\"]\n        Steer[GUI - Steer/xdotool/pyautogui]\n        Drive[Terminal - Drive/tmux/PowerShell]\n        Recorder[Screen Recorder]\n        Safety[Safety + Audit]\n    end\n\n    subgraph External[\"External Services\"]\n        OpenAI[OpenAI API]\n        Anthropic[Anthropic API]\n        Google[Google AI]\n        Supabase[(Supabase DB)]\n        MCP[MCP Servers]\n    end\n\n    UI --\u003e API\n    UI --\u003e Auth\n    SSE --\u003e Stream\n    Editor --\u003e Engine\n    API --\u003e Engine\n    API --\u003e Orchestrator\n    Engine --\u003e Providers\n    Engine --\u003e CU\n    CU --\u003e Steer\n    CU --\u003e Drive\n    CU --\u003e Recorder\n    CU --\u003e Safety\n    Dispatch --\u003e CU\n    Agents --\u003e Drive\n    Orchestrator --\u003e Messaging\n    Providers --\u003e OpenAI\n    Providers --\u003e Anthropic\n    Providers --\u003e Google\n    API --\u003e Supabase\n    API --\u003e MCP\n```\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | Next.js 14, TypeScript, Tailwind CSS, shadcn/ui, React Flow, Bun |\n| Backend | Python 3.12, FastAPI, LangChain, OpenAI/Anthropic/Google APIs |\n| Computer Use | CoreGraphics, cliclick, Vision OCR, ffmpeg, tmux, xdotool, pyautogui |\n| CLI | Typer, Rich, httpx |\n| Database | SQLite (default, zero config) or PostgreSQL via Supabase |\n| Auth | Local JWT (default) or Supabase Auth (email + GitHub OAuth) |\n| Testing | pytest (620 tests), vitest + testing-library (21 tests) |\n| Deployment | Vercel (frontend), Render (backend) |\n| CI/CD | GitHub Actions (Ruff, mypy, pytest, ESLint, tsc, vitest) |\n\n---\n\n## Quick Start\n\n```bash\n# Clone and setup\ngit clone https://github.com/AaronCx/Forge.git\ncd Forge\n./setup.sh\n\n# Add an LLM provider key\nedit backend/.env              # Add OpenAI, Anthropic, or use Ollama for local models\n\n# Start everything\nforge up\n\n# Open the dashboard\nforge dashboard           # Terminal TUI\n# or visit http://localhost:3000  # Web GUI\n```\n\nThree steps. No database accounts. No migration steps. SQLite is created automatically.\n\n### Prerequisites\n\n- Python 3.11+ (backend + CLI)\n- [Bun](https://bun.sh) or Node.js (frontend)\n- At least one LLM provider: OpenAI, Anthropic, Google, or a local model via [Ollama](https://ollama.com)\n\nNo Supabase account needed for local use — the database (SQLite) and auth (local JWT) are built-in.\n\n### Computer Use (macOS)\n\n```bash\n./scripts/bootstrap-macos.sh      # Installs deps, builds native CLIs, checks permissions\n./scripts/bootstrap-verify.sh     # Smoke tests all 20 Steer + Drive commands\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux / Windows setup\u003c/summary\u003e\n\n```bash\n# Linux\nsudo apt install xdotool scrot tesseract-ocr wmctrl xclip tmux xvfb\n\n# Windows\npip install pyautogui pytesseract pygetwindow pyperclip\n```\n\n\u003c/details\u003e\n\n### Docker\n\n```bash\ncp backend/.env.example .env\ndocker-compose up --build\n```\n\n### Stack Management\n\n```bash\nforge up          # Start backend + frontend\nforge down        # Stop everything\nforge restart     # Restart all services\nforge status      # Quick health check\nforge dashboard   # Live TUI monitor\n```\n\n---\n\n## Deployment Options\n\n### Local (recommended for personal use)\n- **Database:** SQLite (zero config, auto-created)\n- **Auth:** Local JWT (auto-configured)\n- **Setup:** `./setup.sh \u0026\u0026 forge up`\n- **External accounts:** None required\n\n### Docker (self-hosted)\n- **Database:** SQLite in mounted volume\n- **Auth:** Local JWT\n- **Setup:** `docker-compose up`\n\n### Cloud (team deployment)\n- **Database:** Supabase PostgreSQL\n- **Auth:** Supabase Auth (email + GitHub OAuth)\n- **Setup:** Create Supabase project, configure keys, deploy to Vercel + Render\n\n### Showcase (forge-theta-teal.vercel.app)\n- Demo mode with simulated data\n- Optional BYOK for live LLM calls\n- No account required\n\n---\n\n## Environment Variables\n\n### Backend (`backend/.env`)\n\n| Variable | Description |\n|----------|-------------|\n| `OPENAI_API_KEY` | OpenAI API key (optional — use any provider) |\n| `ANTHROPIC_API_KEY` | Anthropic API key (optional) |\n| `GOOGLE_API_KEY` | Google AI API key (optional) |\n| `OLLAMA_BASE_URL` | Ollama endpoint for local models (optional) |\n| `SERPAPI_KEY` | SerpAPI key for web search tool (optional) |\n| `FRONTEND_URL` | Frontend URL for CORS |\n| `CU_DRY_RUN` | `true` for computer use dry-run mode |\n| `SUPABASE_URL` | Supabase project URL (only for cloud mode) |\n| `SUPABASE_SERVICE_KEY` | Supabase service role key (only for cloud mode) |\n\nFor local mode: only LLM provider keys needed. Database and auth are automatic.\n\n### Frontend (`frontend/.env.local`)\n\n| Variable | Description |\n|----------|-------------|\n| `NEXT_PUBLIC_API_URL` | Backend API URL (required) |\n| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL (cloud mode only) |\n| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anonymous key (cloud mode only) |\n\n---\n\n## API\n\n### Authentication\n\n```\nAuthorization: Bearer \u003csupabase-access-token\u003e\n```\n\n### Core\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/agents` | List agents |\n| `POST` | `/api/agents` | Create agent |\n| `POST` | `/api/agents/:id/run` | Run agent (SSE) |\n| `GET` | `/api/blueprints` | List blueprints |\n| `POST` | `/api/blueprints` | Create blueprint |\n| `POST` | `/api/blueprints/:id/run` | Run blueprint (SSE) |\n| `GET` | `/api/blueprints/node-types` | List all 44 node types |\n| `POST` | `/api/orchestrate` | Start orchestration (SSE) |\n\n### Computer Use\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/computer-use/status` | Capability report |\n| `GET` | `/api/computer-use/config` | Configuration |\n| `POST` | `/api/computer-use/refresh` | Refresh capabilities |\n| `GET` | `/api/computer-use/audit-log` | Audit log |\n\n### Additional APIs\n\nRuns, Costs, Dashboard, Messages, Orchestration, Providers, Evals, Approvals, Traces, Prompts, Knowledge, Marketplace, Organizations, MCP, Triggers, Targets, API Keys\n\n---\n\n## CLI\n\nThe CLI covers every action available in the web UI. A user who never opens a browser can set up, configure, create agents, build blueprints, run workflows, check costs, manage knowledge bases, run evals, and monitor everything from the terminal.\n\n```bash\n# Setup \u0026 lifecycle\nforge init                             # Create ~/.forge/config.toml\nforge up                               # Start backend + frontend\nforge down                             # Stop everything\nforge restart                          # Restart all services\nforge status                           # Quick health check\nforge health                           # Detailed system health\nforge dashboard                        # Live TUI dashboard\n\n# Auth\nforge auth signup --email e --password p   # Create account from CLI\nforge auth login --email e --password p    # Login, store token\nforge auth logout                          # Clear session\nforge auth whoami                          # Current user info\n\n# Configuration\nforge config show                      # Display config (keys masked)\nforge config set api-key \u003ckey\u003e         # Set a config value\nforge config set-provider openai \u003ckey\u003e # Configure provider (updates .env too)\nforge config set-default-model gpt-4o  # Set default model\n\n# Agents\nforge agents list                      # List agents\nforge agents create --name \"X\" --prompt \"...\" --tools web_search\nforge agents run \u003cid\u003e --input \"...\"    # Run with streaming output\nforge agents history \u003cid\u003e              # Run history for an agent\nforge agents templates                 # List available templates\n\n# Blueprints\nforge blueprints list                  # List blueprints\nforge blueprints create --from-template research\nforge blueprints run \u003cid\u003e --input \"...\"# Run with node-by-node streaming\nforge blueprints export \u003cid\u003e -o bp.json# Export as JSON for version control\nforge blueprints import bp.json        # Import from JSON\n\n# Multi-agent orchestration\nforge orchestrate \"objective text\"     # Submit and stream\n\n# Cost tracking\nforge costs                            # Summary (today/week/month)\nforge costs --breakdown agent          # By agent, model, or provider\nforge costs --period month             # Monthly view\n\n# Models \u0026 providers\nforge models list                      # All models across providers\nforge models test anthropic            # Test provider connection\nforge models compare --prompt \"...\" --models \"gpt-4o,claude-sonnet-4-20250514\"\n\n# Evals\nforge evals create --name \"Quality\" --target agent:\u003cid\u003e\nforge evals add-case \u003csuite\u003e --input \"X\" --expected \"Y\"\nforge evals run \u003csuite-id\u003e             # Run eval suite\nforge evals results \u003crun-id\u003e           # Detailed results\n\n# Knowledge base\nforge knowledge create --name \"Docs\"\nforge knowledge upload \u003ckb-id\u003e ./docs/ # Upload directory\nforge knowledge search \u003ckb-id\u003e --query \"text\"\n\n# Computer use\nforge cu status                        # Capability report\nforge cu see                           # Take screenshot\nforge cu ocr                           # OCR screen text\nforge cu click 500 300                 # Click at coordinates\nforge cu type \"hello\"                  # Type text\nforge cu focus Safari                  # Focus app\nforge cu find \"Button Label\"           # Find element by text\n\n# Additional command groups\nforge runs list                        # View agent runs\nforge triggers list                    # Manage event triggers\nforge approvals list                   # Human-in-the-loop inbox\nforge traces list                      # Execution traces\nforge prompts list \u003cagent-id\u003e          # Prompt versioning\nforge marketplace browse               # Browse blueprints\nforge mcp list                         # MCP connections\nforge targets list                     # Execution targets\nforge recordings list                  # Screen recordings\nforge keys list                        # API key management\n```\n\n---\n\n## Testing\n\n```bash\n# Backend (620 tests)\ncd backend \u0026\u0026 source .venv/bin/activate\npytest tests/ -v --cov=app\n\n# Frontend (21 tests)\ncd frontend \u0026\u0026 npx vitest run\n\n# Or use the Makefile\nmake test\n```\n\n---\n\n## Project Structure\n\n```\nForge/\n├── frontend/                    # Next.js 14 + TypeScript + Tailwind + shadcn/ui\n│   ├── app/dashboard/           # 15+ dashboard routes\n│   ├── components/              # Blueprint editor, dashboard, UI primitives\n│   └── lib/                     # API client, auth client, demo data\n├── backend/                     # FastAPI + LangChain\n│   ├── app/\n│   │   ├── db/                  # Pluggable database layer (SQLite + Supabase)\n│   │   ├── routers/             # 22 API route modules (incl. auth API)\n│   │   ├── providers/           # Multi-model provider registry\n│   │   └── services/\n│   │       ├── blueprint_nodes/ # 44 node type executors\n│   │       └── computer_use/    # Steer, Drive, agents, dispatch, recorder\n│   │           ├── steer/       # macOS GUI automation\n│   │           ├── drive/       # Terminal automation\n│   │           ├── linux/       # xdotool/tesseract fallback\n│   │           └── windows/     # pyautogui/PowerShell fallback\n│   └── tests/                   # 620 tests\n├── cli/                         # Typer + Rich CLI (35+ command groups)\n├── scripts/                     # Bootstrap, Steer/Drive CLIs, OCR helper\n├── supabase/migrations/         # 17 SQL migrations (cloud mode only)\n├── setup.sh                     # One-command project setup\n├── Makefile                     # setup, up, down, test, lint targets\n├── docs/                        # Test \u0026 security reports\n└── .github/workflows/           # CI + deployment\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaroncx%2Fforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaroncx%2Fforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaroncx%2Fforge/lists"}