Building Lucifer: an open-source AI company you can watch · ⭐ GitHub
🚀 Start here: 1. Meet Lucifer · 2. Why I built it · 3. Architecture
📖 Use it: 4. Getting started · 5. Connect an LLM · 6. Office tour
🛠 Build the engine: 7. Org chart in YAML · 8. Real delegation · 9. Sandboxed tools · 10. Simulation brain
🎨 Build the office: 11. 3D office with R3F · 12. WebSocket + zustand · 13. Visualizing workflow
🧭 What's next: 14. Roadmap · 15. Contributing
I have run a lot of multi-agent demos. They tend to look the same: a terminal scrolls past thousands of lines of Thought:, Action: and Observation:, something called manager_agent says it has delegated a task, and a few minutes later a final answer appears. Whether that answer is good, which agent did what, where the time went and what got silently skipped are all buried in the scroll.
That is fine for a one-off script. It is not fine when you want to hand an AI team real work and trust what comes back. Lucifer is my attempt to fix that, and this post explains the reasoning behind it.
The problem: agents are a black box
Three things kept bothering me about the usual multi-agent setups.
1. You can't see the work. Delegation happens inside one long run. The "subtasks" exist only as text in a prompt, so there is nothing to open, nothing to cancel and nothing to point at when something goes wrong.
2. The structure is flat. Most frameworks give you a manager and some workers. Real organizations have layers: a CEO talks to a CTO, the CTO talks to engineers. Without layers, one manager prompt has to understand everything, and that is exactly where quality drops.
3. Failure is hidden. An agent that cannot do something usually produces something anyway. A confident but empty answer is worse than an honest "I couldn't do this, here's why", because it hides the problem and wastes your time later.
The idea: a company you can watch
People already have a mental model for "many workers splitting up a goal": a company. Everybody understands an org chart, a manager handing out work, a team reporting back, and a board with columns for to-do, in progress and done. So instead of inventing a new UI for agents, Lucifer borrows the company:
| Company concept | In Lucifer |
|---|---|
| Org chart | A YAML file: departments, managers (reportsTo), personas |
| An employee | One agent with its own persona, model and effort level |
| Assigning work | POST /api/tasks, or typing into the assign bar |
| Delegating | A delegate_task tool call that creates a real subtask |
| Waiting on the team | The parent task's waiting status |
| Deliverables | Files in a shared, sandboxed workspace |
| Owning a mistake | fail_task, with a specific reason |
| The office | A 3D yacht where every employee is an angel at a desk |
The office matters more than it looks. When you can see Michael the CTO hand three tasks to his engineers, see two of them working while one waits, and see a green comet fly back when one finishes, you understand the system in a way a log never gives you. And when something stalls, you notice: one angel sits there with a waiting hourglass while everyone else is idle.
Design choices
A few decisions shaped everything else.
Every subtask is a first-class task
The most important one. When an agent delegates, the engine creates a task with its own id, status, assignee, result and files. The parent moves to waiting. When all its children are finished, the parent goes back to todo, and its owner picks it up again with the results in the brief. That is what makes the work inspectable and cancellable, and it is why Lucifer doesn't use CrewAI's hierarchical process. I explain that in Real delegation with CrewAI.
Work flows down the org chart
Each agent is shown only its direct reports and told to delegate to them, and the engine refuses any delegate_task aimed at someone outside the agent's own branch of the chart. The CEO hands work to the CTO, the CTO to the engineers, and a content writer cannot hand work to the CEO. The rule keeps every manager's context small and makes the delegation tree mirror the org chart, so it is easy to read.
Honest failure is a feature
Agents get a fail_task tool and are told to use it with "the specific reason, and what would be needed to finish it". A failed subtask still wakes its parent, so the manager can decide what to do, for example delegating again or reporting the gap upward. It also fits the story: the company was founded by a fallen angel making amends through honest work.
Free by default
With no API key the engine runs a simulation brain that goes through the same actions without calling an LLM. You can try the whole product, develop the UI and run every test without spending a token. More on that in the simulation brain post.
Built for watching, not just for running
The office has missions, work links, a follow camera and break time. Lucifer is not trying to be a framework you import into your app. It is a product you run and watch, and a codebase you can learn from.
Why open source, and why MIT
Two reasons.
First, multi-agent systems are still young, and the interesting questions are open. How should agents ask for help? When should a manager review work? How do you keep costs predictable? Those answers will come from many people trying things, not from one repository. A permissive license makes it easy to fork Lucifer, change the org chart, add a tool or swap the world.
Second, I learn by building in public. Every design decision in this series is in the code, with comments that explain the why. If you are building agents yourself, you are welcome to take whatever is useful.
How Lucifer compares
Lucifer stands on CrewAI and does not compete with it. CrewAI runs each agent's loop, its tools and its LLM calls, and Lucifer adds the company around it.
| Typical agent framework | Lucifer | |
|---|---|---|
| Unit of work | A run | A task tree that persists across runs and restarts |
| Hierarchy | One manager layer | Any depth, following the org chart |
| Visibility | Logs, traces | Board, delegation tree, live 3D office |
| Control | Stop the process | Cancel any task and its open subtasks |
| Cost to try | API key required | Free simulation brain |
If you need agents embedded inside your own product, a framework is the right tool. If you want to give a team of agents a goal and watch them deliver, Lucifer is built for that.
What's next
The roadmap points at one goal: a company that can take a real client brief, ship a real product and market it. The next big step is ask instead of guess. When an agent isn't confident, it pauses and asks its manager or you, with concrete options to pick from. See the roadmap post for the rest.
In the meantime, clone the repo, give the company a goal and watch it work. Next up: the architecture at a glance.
Lucifer is open source under the MIT license. Clone it, run it for free with the simulation brain, and ⭐ star it if you'd like to follow along: github.com/siri2moon/lucifer.
Next in the series: Lucifer Architecture at a Glance: Engine, Office and the Protocol Between Them.