Learn from the work you're already doing

Hephaestus is an open-source AI mentor for software teams. It reads the work developers already do — issues, pull requests, reviews and the discussion around them — against the engineering practices their project cares about, then says what went well, what could be better, and a way to get there. Every piece of feedback names the practice it came from and points back to the work it saw, and developers can ask why, push back, or talk through the next step.

Feedback on how you work is a mentor's job — a coach on a university capstone, an experienced maintainer on an open-source project — and there is never enough of that attention to go round. Hephaestus carries the routine part so that everyone gets some. The harder judgement and the relationships stay with people.

_{An illustration of the feedback Hephaestus writes. See the user guide for the real interface.}

Important

Hephaestus is pre-1.0. It is released continuously and only the latest release is supported — no maintenance branches, no backports. Until 1.0, a minor release can change configuration or the API in ways that need you to act, so read the release notes before every upgrade. Version 1.0 is what makes upgrades, configuration, Compose and the REST API predictable: compatibility policy · 1.0 milestone.

What Hephaestus does

• Reviews contributions against engineering practices. A curated set of practices ships with it, covering how work is scoped and described, how issues are written, how reviews are given and answered, testing, failure handling, security, maintainability, recorded decisions, version control, planning and communicating in the open. A workspace adopts the groups it cares about and can rewrite any practice inside them.
• Gets the feedback to the developer. It can land on the work itself, on the developer's own practice pages, or in their next conversation with Hephaestus. Every piece names the practice it came from and points at the evidence behind it.
• Answers follow-up questions. Developers can ask why a suggestion matters or supply the context it did not have. In chat Hephaestus goes by Heph, in the web app and, when Slack is connected, in a direct message.
• Uses only the project context you connect. GitHub and GitLab repositories, plus optional selected Slack channels and Outline collections.
• Puts admins in control. They configure repositories, practices, members, integrations, the AI model through any OpenAI-compatible endpoint, and a monthly spending cap.
• Ships optional recognition features. Achievements, leagues, a weekly leaderboard, and a Slack digest of review activity, all separate from practice feedback.

How feedback works

1. A workspace connects its GitHub or GitLab repositories and adopts the practices it cares about.
2. Hephaestus gathers a contribution together with the work around it: the issue, the change, the review thread, the conversation.
3. It records what it observed against those practices, and writes feedback from those observations.
4. The feedback goes where the developer will actually see it — on the work, on their own practice pages, or in conversation.
5. They act on it, push back with a reason, or let it pass. Their next contribution is read the same way.

The feedback is advisory: it does not approve a change for merge or grade anyone.

Get started

• Try the hosted app: open the TUM deployment.

• Learn how it works: read the user guide.

• Run your own deployment. One 64-bit Linux host, 4 vCPUs / 8 GB RAM / 40 GB SSD recommended:

  VERSION=0.75.2   # the release you are installing, without the leading "v"
  sudo git clone --depth 1 --branch "v$VERSION" https://github.com/ls1intum/Hephaestus.git /opt/hephaestus
  sudo chown -R "$USER" /opt/hephaestus
  cd /opt/hephaestus/docker/self-host
  cp .env.example .env

  The stack refuses to start until .env is complete, so finish the installation guide before the first docker compose up -d — it covers the sign-in OAuth app, TLS, and the first admin account. Before upgrading, read the release notes and the migration guide, then test the upgrade in staging.

• Contribute: start with the local development guide; the web app's components are browsable in Storybook.

Get help

• Ask questions and share ideas in GitHub Discussions.
• Report reproducible bugs in GitHub Issues.
• Report security vulnerabilities privately as described in SECURITY.md.

Contributing

Contributions are welcome. Hephaestus is a research project and @FelixTJDietrich is its core maintainer, so issues and pull requests are triaged on a best-effort basis; security reports get priority. CONTRIBUTING.md explains how to set up the project, propose a change, run the quality checks, and open a pull request. Participation in the project is governed by the Code of Conduct.

Project origins

Hephaestus is an MIT-licensed open-source project developed by Applied Education Technologies at the Technical University of Munich. It is named after the Greek god of the forge, whose craft — in the myth Plato tells — was stolen from his workshop and given to people so they could make things for themselves.

Developed by


_{Research Group for Applied Education Technologies · Technical University of Munich}