{"id":50718992,"url":"https://github.com/starsinc1708/hephaestus","last_synced_at":"2026-06-16T04:01:00.318Z","repository":{"id":363646807,"uuid":"1264271673","full_name":"starsinc1708/HEPHAESTUS","owner":"starsinc1708","description":"Self-hosted autonomous development loop — give it a goal, AI agents decompose, execute, verify, and merge it. FastAPI + Vue 3 dashboard (en/ru).","archived":false,"fork":false,"pushed_at":"2026-06-12T19:47:53.000Z","size":788,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T01:21:30.039Z","etag":null,"topics":["ai-agents","ai-coding","autonomous-agents","code-generation","developer-tools","devtools","fastapi","llm","self-hosted","vue"],"latest_commit_sha":null,"homepage":"https://github.com/starsinc1708/HEPHAESTUS","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/starsinc1708.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-06-09T18:19:23.000Z","updated_at":"2026-06-12T19:47:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"8e75e42c-bd2d-42fa-8552-02cdf0ecc148","html_url":"https://github.com/starsinc1708/HEPHAESTUS","commit_stats":null,"previous_names":["starsinc1708/hephaestus"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/starsinc1708/HEPHAESTUS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starsinc1708%2FHEPHAESTUS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starsinc1708%2FHEPHAESTUS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starsinc1708%2FHEPHAESTUS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starsinc1708%2FHEPHAESTUS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starsinc1708","download_url":"https://codeload.github.com/starsinc1708/HEPHAESTUS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starsinc1708%2FHEPHAESTUS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34306772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","ai-coding","autonomous-agents","code-generation","developer-tools","devtools","fastapi","llm","self-hosted","vue"],"created_at":"2026-06-09T22:00:24.548Z","updated_at":"2026-06-14T02:01:14.708Z","avatar_url":"https://github.com/starsinc1708.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HEPHAESTUS — Autonomous Development Loop\n\n[![CI](https://github.com/starsinc1708/HEPHAESTUS/actions/workflows/hephaestus-loop-ci.yml/badge.svg)](https://github.com/starsinc1708/HEPHAESTUS/actions/workflows/hephaestus-loop-ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)\n![Vue 3](https://img.shields.io/badge/Vue-3-42b883.svg)\n\n\u003e Self-hosted, open-source tool that turns development goals into shipped code.\n\u003e Define a goal → HEPHAESTUS decomposes it, executes tasks via AI agents, verifies results, and merges clean commits.\n\n![HEPHAESTUS dashboard — the board view](docs/screenshots/dashboard.png)\n\n\u003e The dashboard UI ships in English and Russian (toggle in the top bar).\n\n## What It Does\n\nHEPHAESTUS is an autonomous development loop: you give it a goal (e.g. \"implement user auth\"),\nand it:\n\n1. **Decomposes** the goal into discrete tasks\n2. **Executes** each task using an AI agent (opencode, Claude, Codex)\n3. **Verifies** results (typecheck, lint, tests)\n4. **Commits** to an isolated feature branch\n\nA web dashboard shows live progress of every task, iteration, and agent run.\n\n## Architecture\n\n```\n┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐\n│  Vue 3 SPA   │────▶│  FastAPI Backend  │────▶│  AI Agent CLI   │\n│  (dashboard)  │◀────│  (orchestrator)   │◀────│  (opencode/etc) │\n└──────────────┘     └──────────────────┘     └─────────────────┘\n       │                     │\n       │              ┌──────┴──────┐\n       │              │   state/    │\n       │              │  (JSON FS)  │\n       └──────────────┴─────────────┘\n```\n\n| Layer | Stack | Key files |\n|-------|-------|-----------|\n| **Backend** | FastAPI + Python 3.11+, `mypy --strict`, `ruff` | `backend/app/` |\n| **Frontend** | Vue 3 + TypeScript + Pinia + Tailwind CSS | `frontend/src/` |\n| **Orchestrator** | 9-phase FSM (finite state machine) | `backend/app/orchestrator/fsm.py` |\n| **State** | File-based JSON (no database) | `state/` |\n| **Agents** | opencode, Claude CLI, Codex CLI | via `backend/app/services/opencode_runner.py` |\n\n### FSM Pipeline\n\nEach task goes through these phases:\n\n```\npreflight → prompt → execute → verify → commit → idle\n                         ↑         │\n                         └── retry ┘\n```\n\n- **Verify funnel**: typecheck → lint → tests must all pass before commit\n- **Tier review**: multi-agent review with configurable approval thresholds\n- **Branch isolation**: every iteration works on `auto/\u003ctask-id\u003e-\u003csha\u003e` — never touches `main`\n\n## Quick Start\n\n### Option A — Docker\n\nThere are **two images**:\n\n- **`ghcr.io/starsinc1708/hephaestus:latest`** — the **dashboard + API** only. Great to try\n  the UI. It does **not** include the agent CLIs, so it can't *run* the loop.\n  ```bash\n  docker run -p 8765:8765 ghcr.io/starsinc1708/hephaestus:latest   # open http://localhost:8765\n  ```\n- **Agent image** (built from `Dockerfile.agent`) — the dashboard **plus** `git`, Node, and the\n  agent CLIs (`claude` / `opencode` / `codex`), so the autonomous loop actually runs. Use this\n  to use the app for real:\n  ```bash\n  git clone https://github.com/starsinc1708/HEPHAESTUS.git \u0026\u0026 cd HEPHAESTUS\n  docker compose up --build          # builds the agent image; open http://localhost:8765\n  ```\n\n**👉 Full walkthrough — running, mounting repos, and connecting providers (API key *or*\nsubscription login) in Docker: [docs/DOCKER.md](docs/DOCKER.md).**\n\n**Read [SECURITY.md](SECURITY.md) before pointing HEPHAESTUS at a repository** — agents execute\ncode with the container user's privileges.\n\n### Option B — from source (~15 minutes to first run)\n\n```bash\n# 1. Clone\ngit clone https://github.com/starsinc1708/HEPHAESTUS.git\ncd HEPHAESTUS\n\n# 2. Backend\ncd backend\ncp .env.example .env          # edit paths in .env\nuv sync                       # install Python deps\nuvicorn app.main:app          # starts on http://localhost:8766\n\n# 3. Frontend (new terminal)\ncd frontend\npnpm install\npnpm dev                      # starts on http://localhost:5173 (proxies API to :8766)\n\n# 4. Open http://localhost:5173 — the onboarding wizard will guide you\n```\n\nFor detailed setup, troubleshooting, and platform-specific instructions, see **[GETTING_STARTED.md](GETTING_STARTED.md)**.\n\n## Configuration\n\nConfiguration is via environment variables. Copy and edit the example:\n\n```bash\ncp backend/.env.example backend/.env\n```\n\nKey variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `HEPHAESTUS_LOOP_HOME` | (auto-detected) | Path to this repo |\n| `HEPHAESTUS_REPO` | `\"\"` | Target git repository path |\n| `HEPHAESTUS_DASHBOARD_PORT` | `8766` | Backend API port |\n| `HEPHAESTUS_DASHBOARD_HOST` | `127.0.0.1` | Backend bind address |\n| `HEPHAESTUS_DASHBOARD_PASSWORD` | (none) | Set to enable auth |\n| `HEPHAESTUS_PRIMARY_AGENT` | `sisyphus` | Primary AI agent |\n| `HEPHAESTUS_FALLBACK_AGENT` | `atlas` | Fallback agent on failure |\n| `HEPHAESTUS_MAX_ITER` | `50` | Max iterations per run |\n| `HEPHAESTUS_MAX_PARALLEL` | `1` | Parallel task limit |\n| `HEPHAESTUS_AUTOPUSH` | `off` | Auto-push feature branches |\n| `HEPHAESTUS_TIER_REVIEW` | `on` | Multi-agent review system |\n\nFull list in `backend/.env.example`. Can also be overridden via the dashboard Settings page\nor `state/config.json`.\n\n## Guardrails\n\n| Guardrail | Default |\n|-----------|---------|\n| Branch isolation: every iter creates `auto/\u003ctask-id\u003e-\u003csha\u003e` | always on |\n| **Never** pushes to `main` | always on |\n| Per-iteration hard timeout | `2400s` (40 min) |\n| Max iterations per run | `50` |\n| Stop after N consecutive failures | `4` |\n| Verify (typecheck + lint + tests) must pass to commit | always on |\n| Working tree reset on verify failure | always on |\n| Primary → fallback agent on failure | always on |\n| Kill switch: `state/stop` file | always on |\n\n## Supported AI Engines\n\nHEPHAESTUS works with multiple AI agent CLIs:\n\n| Engine | CLI | Notes |\n|--------|-----|-------|\n| **opencode** | `opencode` | Primary engine, supports multiple providers |\n| **Claude** | `claude` | Anthropic's Claude Code |\n| **Codex** | `codex` | OpenAI's Codex CLI |\n\nThe onboarding wizard auto-detects installed CLIs.\n\n### Provider Catalog\n\nThe backend supports 7 providers out of the box: Anthropic, OpenAI, DeepSeek, Google, Mistral, xAI, and custom endpoints.\n\n## Project Structure\n\n```\nhephaestus-autonomous-loop/\n├── backend/                   # FastAPI backend\n│   ├── app/\n│   │   ├── main.py            # App factory, auth, CORS, lifespan\n│   │   ├── config.py          # Configuration \u0026 env vars\n│   │   ├── api/v1/            # 79 HTTP endpoints, 3 WebSocket routes\n│   │   ├── orchestrator/\n│   │   │   └── fsm.py         # 9-phase FSM orchestrator\n│   │   ├── core/              # State, git, events, queue, iterations\n│   │   ├── models/            # Pydantic models\n│   │   ├── services/          # Connections, agent runner, WebSocket\n│   │   └── integrations/      # GitHub/GitLab integrations\n│   ├── tests/                 # 100+ test files\n│   ├── pyproject.toml         # Python deps \u0026 tool config\n│   └── .env.example           # Environment variable template\n├── frontend/                  # Vue 3 SPA\n│   ├── src/\n│   │   ├── views/             # Board, Agents, Tools, Settings, Worktrees\n│   │   ├── components/        # 36 components including OnboardWizard\n│   │   ├── stores/            # 7 Pinia stores\n│   │   ├── api/client.ts      # API client\n│   │   └── router.ts          # Routes\n│   ├── vite.config.ts         # Dev proxy → backend :8766\n│   └── package.json           # Node deps\n├── prompts/                   # 19 prompt templates\n├── state/                     # Runtime state (JSON, git-ignored)\n└── docs/                      # Screenshots \u0026 assets\n```\n\n## API Documentation\n\nOnce the backend is running, interactive API docs are available:\n\n- **Swagger UI**: http://localhost:8766/docs\n- **ReDoc**: http://localhost:8766/redoc\n- **OpenAPI JSON**: http://localhost:8766/openapi.json\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [GETTING_STARTED.md](GETTING_STARTED.md) | Detailed setup guide with troubleshooting |\n| [docs/DOCKER.md](docs/DOCKER.md) | Run + use HEPHAESTUS in Docker (repos, provider auth, subscription login) |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, code style, PR process |\n| [SECURITY.md](SECURITY.md) | Security policy + threat model (read before running) |\n| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community guidelines |\n| [CHANGELOG.md](CHANGELOG.md) | Release notes |\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarsinc1708%2Fhephaestus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarsinc1708%2Fhephaestus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarsinc1708%2Fhephaestus/lists"}