Hephaestus
A development framework where agents discover, create, and coordinate the work as they go.
- Source repo
- Ido-Levi/Hephaestus
- Stars
- ★ 1.2k
- Last updated
- 9mo ago
- License
- NOASSERTION
- Primary language
- Python
- FA score
- 31/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- You'll need
- Typical use
- A software team has a PRD and wants authentication, REST API, frontend, database, and background-work tasks to be split into parallel work.
- Main limitation
- The runtime footprint is substantial: Python, tmux, Git, Docker, Qdrant, Node.js, npm, and at least one agent CLI are required.
- Source review
- 31/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
Hephaestus is a semi-structured agentic framework for software development in which workflows expand from discoveries made during execution instead of requiring every branch in advance. It uses Phase definitions such as analysis, implementation, and validation, while agents dynamically create Kanban tickets with blocking relationships. The README describes a Guardian that monitors alignment with phase goals and a real-time observability UI for watching agents in isolated sessions. Agents can run Claude Code, OpenCode, Droid, or Codex CLIs inside tmux; Qdrant serves as the vector store and a Node.js frontend is required. Hephaestus Dev supplies five preconfigured workflows: PRD-to-software building, bug fixing, repository indexing, feature development, and documentation generation.
A user defines Phases and their done criteria, then an analysis agent reads the task or PRD and creates subsequent tickets. Implementation and validation agents can continue their current ticket while adding investigation, fix, implementation, or retest tickets in any Phase when they find failed tests, optimization opportunities, or other new work. Blocking relationships coordinate the resulting dependencies, while Guardian monitors whether work remains aligned with phase instructions. The Kanban board, dependency graph, and observability views expose the evolving workflow. Hephaestus runs the selected Claude Code, OpenCode, Droid, or Codex CLI in tmux and requires configured Hephaestus and Qdrant MCP servers. The documented Hephaestus Dev entry point is python run_hephaestus_dev.py --path /path/to/project.
- A software team has a PRD and wants authentication, REST API, frontend, database, and background-work tasks to be split into parallel work.
- A maintainer needs to analyze, fix, and verify a defect in an existing Git repository through traceable tickets.
- A developer inheriting an unfamiliar codebase wants to scan and index it into memory before starting feature work.
- A test engineer finds a performance opportunity or security issue during validation and wants investigation, implementation, and retest work created from that finding.
- A team needs comprehensive documentation for an existing codebase using a preconfigured development workflow.
How do you install or deploy this agent?
The README does not provide repository-cloning commands, dependency-install commands, or .env configuration syntax, so a complete installation procedure cannot be established from the supplied evidence. Its stated prerequisites are Python 3.10+, tmux, Git, Docker, Node.js, npm, and one of Claude Code, OpenCode, Droid, or Codex; the target project must be a Git repository. API keys are also required for OpenAI, OpenRouter, Anthropic, or one of the listed Azure OpenAI and Google AI Studio support paths, along with configured Hephaestus and Qdrant MCP servers. On macOS, run python check_setup_macos.py to check CLI tools, .env API keys, MCP configuration, Docker/Qdrant, and dependencies.
How do you use this agent?
After satisfying the prerequisites and configuring MCP and LLM settings, run this against the target Git project: python run_hephaestus_dev.py --path /path/to/project. This starts a preconfigured Hephaestus Dev development workflow. The README does not document command-line options for selecting one of the five workflows or supplying a PRD, so those details cannot be added from the available evidence.
What are this agent's strengths and limitations?
- Phase types constrain the kind of work while agents can create tasks from discoveries, avoiding the need to predefine every workflow branch.
- Kanban tickets and blocking relationships provide explicit coordination for parallel building, fixes, and validation.
- Guardian monitoring, real-time observability, and tmux-isolated sessions provide visible oversight of multi-agent execution.
- Hephaestus Dev lists five software-development workflows spanning PRD building, repository indexing, bug fixing, feature work, and documentation.
- The runtime footprint is substantial: Python, tmux, Git, Docker, Qdrant, Node.js, npm, and at least one agent CLI are required.
- It requires several API credentials and Hephaestus/Qdrant MCP configuration; the README does not provide full installation commands or configuration formats.
- The project is labeled Alpha, so adoption should budget for stability validation and workflow change.
- Repository metadata says License is NOASSERTION while the README claims AGPL-3.0; licensing should be independently verified before adoption.
How does this agent compare with similar options?
The README positions it between traditional predefined-branch workflows and unstructured agents: traditional frameworks require instructions for anticipated branches, while Hephaestus lets agents create tasks dynamically within Phase-based structure.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Hephaestus This agent | 31 · Major gaps | ★ 1.2k | 9mo ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| Whale | 51 · Major gaps | ★ 929 | 1mo ago | Go | — |
| Agent Deck | 76 · Good | ★ 943 | 2d ago | Go | Codex · Claude Code |
| Swiftide | 68 · Some gaps | ★ 785 | 5d ago | Rust | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: The repository does not provide explicit mechanisms for least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. README mentions API keys and MCP servers but does not explain how to protect or minimize permissions. Therefore all trust criteria score 0.
Evidence shows: README and test files describe a consistent architecture (phases, agents, kanban), but there are inconsistencies, e.g., README requires Python 3.10+ while pyproject.toml requires ^3.11. Dependency lists differ between pyproject.toml and requirements.txt (e.g., version differences). Test files exist but no documentation of failure messages. Thus self-consistency, dependency availability, and failure messages score 1.
Evidence shows: README describes multiple scenarios (PRD building, bug fix, indexing, etc.) but does not clearly define target audience. Capability boundaries are not explicitly stated, trigger mechanisms (phase definitions) are described but not precise. Environment fit requires multiple tools (tmux, Docker, Node.js, etc.) but no detailed configuration guide. Therefore audience and scenarios score 2, others 1.
Evidence shows: README provides quick start, documentation links, and examples, but lacks installation instructions (only mentions check_setup_macos.py). Naming stability is not explicit, version is 0.1.0 in pyproject.toml but no changelog. License is AGPL-3.0 but metadata is NOASSERTION. Maintenance responsibility is not clear. Thus information architecture, install notes, examples, and license score 2, others 1.
Evidence shows: README describes outputs (kanban board, dependency graph) but no actual output examples. Marginal value is described (adaptive workflows) but not quantified. Cost-benefit is not discussed. Therefore output usability scores 1, marginal value 2, cost-benefit 1.
Evidence shows: Claims in README (e.g., 'workflows build themselves') are not supported by verifiable evidence such as test results or demos. Test files exist but no coverage or execution results. Facts and inferences are not clearly separated. Therefore all criteria score 1.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- The repository lacks permission management or user confirmation mechanisms, potentially allowing agents to perform arbitrary actions.
- Dependency lists are inconsistent, which may cause installation issues.
- No explicit rollback or recovery mechanisms are provided, agent actions may be irreversible.
- Publisher identity is unverified, use with caution.