atoma

<div align="center">

# <img src="src/viz/public/favicon.svg" width="40" height="40" alt="" align="top"> atoma

### Turn business ideas into working software.

Describe the tool your team needs. atoma coordinates AI agents to build it,
checks the result against what you asked for, and lets you inspect every step.

**[Open atoma.run →](https://atoma.run)**

[Demo](#watch-the-demo) · [Use cases](#what-could-your-team-build) · [A run, step by step](#a-run-step-by-step) · [Features](#features) · [How it works](#how-it-works) · [Self-host](#install-and-evaluate-it-locally) · [Documentation](#documentation)

[![CI](https://github.com/mgtf/atoma/actions/workflows/ci.yml/badge.svg)](https://github.com/mgtf/atoma/actions/workflows/ci.yml)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)

</div>

> [!WARNING]
> **atoma is under active development.** Organisations are designed to be
> isolated from one another (projects, workspaces, traces and previews), but
> the platform has not been independently audited and we cannot yet guarantee
> that isolation, or the absence of other security defects, under every
> condition. **Do not include confidential, personal or otherwise sensitive
> data in your goals, uploaded files or generated applications**, whether on
> [atoma.run](https://atoma.run) or on a self-hosted instance exposed to others.
> Use the hosted service to evaluate the product, not to process data you could
> not afford to see leak. See [SECURITY.md](SECURITY.md) to report a vulnerability.

## Watch the demo

https://github.com/user-attachments/assets/9572ddb9-0767-45c8-aaf2-5435619c1cbd

## From a business need to a tool you can use

An operations team needs a dashboard. An agency needs a client demo. A product
team needs an API prototype. atoma turns those requests into software: web
applications, HTTP APIs, command-line tools and their technical documentation.

Start at **[atoma.run](https://atoma.run)**. The web console brings projects,
AI execution, acceptance criteria, result previews, model choice and run history
into one place. This repository contains the open-source engine and console for
teams that want to inspect, extend or self-host them.

## What could your team build?

These are example project briefs, not prebuilt industry integrations or
customer deployment claims.

| Team or industry | Example project | What it helps you do |
| --- | --- | --- |
| Agencies & consulting | An interactive client demo or project estimator | Turn a proposal into something a client can try |
| Retail & e-commerce | A sales dashboard from exported CSV files | Explore product performance and share a clear view with the team |
| Logistics & operations | An inventory viewer or shipment-status prototype using sample data | Test a workflow before connecting operational systems |
| SaaS & product teams | A web app prototype or HTTP JSON API | Explore a feature and hand working code to engineering |
| Data & engineering teams | A CSV-to-JSON CLI, validation utility or technical documentation | Package a repetitive task into a reusable tool |

For example:

> Build a sales dashboard that lets me upload a CSV with date, product, region
> and revenue columns. Add filters, monthly totals and a chart by region.
> Include sample data and instructions to run it locally.

## A run, step by step

1. **Create a project**, from scratch or by importing an existing GitHub
   repository, and describe the outcome you want.
2. **Say what "done" means**, if you want to: list the behaviours the result
   must show. Otherwise the run drafts its own checklist from your goal.
3. **Follow the run** as agents plan, write files, start servers and check their
   work, with the model, tokens and cost behind every step.
4. **Preview web results** in a temporary, isolated environment, including a
   snapshot while the run is still building.
5. **Keep the deliverable**, with its verification record, and publish it to a
   connected GitHub repository. The project's next run continues from it; a
   project imported from GitHub starts each run from its default branch.

Previews are review environments; deploying the generated application is a
separate step. Project runs use the configured model accounts and consume model
quota or incur API charges.

<p align="center">
  <img src="docs/atoma-run-audit.png" alt="atoma console showing a build run, its timeline, validation results and model cost estimates">
</p>

<p align="center"><em>See what ran, what was checked, and where model usage went.</em></p>

<p align="center">
  <img src="docs/atoma-run-llm-filter.png" width="640" alt="The same run timeline narrowed to LLM calls, each step showing its agent, model, tokens, cache use, duration and cost">
</p>

<p align="center"><em>Filter the timeline to LLM calls: the model, tokens and cost behind each step.</em></p>

## Features

### Acceptance criteria you approve before launch

A project run can carry up to twelve criteria, written one per line in the
console, the CLI (`--criteria <file>`) or over MCP. A line such as
`GET /api/items` is an HTTP check; any other line is judged by review. The host
stores the list before planning starts and nothing can change it afterwards.
The planner is told the user wrote it, and the final check is told which HTTP
checks were actually observed on servers the run itself started.

Without a list, the run drafts one from the goal with a single call to the
cheapest model. A drafted list can only add to what the final check looks for;
it can never make a run pass.

### Finished work is never thrown away

A run that exhausts its budget after completing at least one phase, or whose
result the final check refuses after one remediation attempt, is kept as
**incomplete** rather than discarded — including when the deadline falls while
its finished work is still being checked. Its finished phases stay in the
workspace, and the console explains in plain language why it stopped and what
to do next, with the technical reasons one click away. In a project created in
atoma, the next run starts from that workspace and is told why the previous one
stopped; a project imported from GitHub starts each run from its default
branch, so unpublished changes are not carried over.

### Choose the models, then compare them

Each tier (workers, supervisors, planners) takes its own model selector, of the
form `<api|sub|own>:<vendor>:<model>`, across Anthropic, OpenAI, Google
DeepMind, xAI, Meta, Mistral, Alibaba Qwen, DeepSeek, Moonshot, Z.ai and a
self-hosted Ollama: `api:` bills a key, `sub:` the host's Claude or ChatGPT subscription,
and `own:` the member's own ChatGPT account, whose available models Settings
lists. The operator can delegate the host subscription to named members without
making them administrators. The offered models and their per-token prices are
one versioned file, `src/core/modelCatalog.json`, kept current with
`npm run models -- refresh`: prices are a dated history, so a vendor's change
applies from its day without re-pricing what came before.

Every run records the models it was pinned to and the models the provider
actually served. A delivered or incomplete run of a project created in atoma can
be **rerun on other models** through the API or MCP: same goal, same acceptance
criteria, same starting workspace. The
rerun sits beside the project's history, so you can compare cost, time and
result; it never publishes and never seeds a later run.

### Start from your repository, publish back to it

Install the GitHub App to import a repository into a project or create a new
one, then publish delivered results to it. A project's earlier deliverables,
including Markdown, CSV, PDF and Office documents, are indexed so later runs
can search them and cite exact passages. See [GitHub App setup](docs/github-app-setup.md).

### Verification you can read

Supervisors check results with evidence the run produced: files, command
exit codes, HTTP probes, and browser checks laid out at the viewport widths the
goal asks for. They never replay shell commands a model wrote. Every verdict,
retry and refusal is in the timeline, and the console is available in thirteen
languages, on desktop and mobile.

### Connect an existing agent through MCP

The console serves an HTTP MCP endpoint at `https://<your-instance>/mcp`.
Compatible clients such as Claude Code or Codex can start runs, pass acceptance
criteria, request reruns and read traces, costs and diagnostics, with the same
organisation permissions as the web console.

**Forty-one tools.** The visible subset depends on the caller's role.
See the [MCP connection and authorization guide](docs/mcp-oauth.md).

### A platform that reviews its own runs

Three background services watch the platform itself. The **sentinel** watches
runs in flight for cost overruns and drifting trajectories. The **analyst**
writes a cited post-mortem verdict for each finished run. The **mender** turns a
verdict that names a code defect into a pull request, which a person reviews and
merges. Read the [supervisor design](docs/supervisor-design.md).

## How it works

atoma assigns planning, supervision and execution to different AI agents and
model tiers. Ordinary build runs start with a supervisor and workers; a deeper
planning tier takes over if supervision exhausts its retries, and a seeded run
keeps its starting workspace when it does.

- **Workers build.** They read and write files, run commands and use tools.
  Project runs do so in a container with no network unless egress is
  explicitly allowed; a local `npm run run:build` uses the host unless it is
  given `--container`.
- **Supervisors check.** They review results against artifact evidence and fixed
  probes. Before delivery, a separate check reviews the final result against
  the goal and its acceptance criteria.
- **Trust is earned.** Components that keep succeeding can skip some model
  reviews while retaining mechanical checks. A failure re