Start and follow atoma builds; read their runs, traces, agent registry and skill catalogue.
run.atoma/atoma (MCP Server)
The run.atoma/atoma MCP server starts and follows atoma builds. It provides access to build runs and traces, and it also exposes an agent registry and a skill catalogue for use in development and inspection workflows.
🛠️ Key Features
Start and follow atoma builds
Read build runs
Read traces
Access agent registry
Access skill catalogue
🚀 Use Cases
Inspect the execution of atoma builds over time
Debug behavior using trace data
Review available agents via an agent registry
Enumerate or reference skills from the skill catalogue
⚡ Developer Benefits
Centralizes build run and trace inspection in one MCP server
Provides structured access to agents and skills for tooling integration
Supports workflows that need both execution data and catalog metadata
⚠️ Limitations
The provided description does not specify supported actions beyond starting/following builds and reading runs, traces, agent registry, and skill catalogue
Ask for a drawing, a sound, a report, a data study, a proof or a piece of
software. atoma coordinates AI agents to produce it, checks the result against
what you asked for, and lets you inspect every step. The bounded decisions
along the way, such as which agent takes a task or whether a plan is approved,
are taken by Decision, TypeSafe's Jev model.
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 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 to report a vulnerability.
IMPORTANT
Where atoma stands, November 2026. atoma was built on a cost premise:
split a goal across three tiers of agents, give each tier the cheapest model
that can do its part, and finished work costs less than one frontier agent
doing all of it. On the evidence so far, that premise does not hold. Measured
on the current release, one agent was as correct or more correct, and atoma
cost 6.6 to 10.4 times as much. The three tiers remain what atoma runs,
because they leave something one agent does not: a run you can audit step by
step. Read the cost premise, measured.
Watch the demo
Explore a two-run business scenario, three-tier coordination, MCP integration
and the cost breakdown by tier and model in this four-minute walkthrough. The
film predates the measurements on the current release.
Where it says atoma helps minimise model costs, take the breakdown for what it
is: a way to see what a run spent, not a saving.
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. 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.
image
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
Open Projects → Talk to Atoma, or connect your existing agent through
MCP from Settings. Describe the project you want to create or the change
you want to make. The integrated assistant uses the saved project brief
and latest run to prepare a proposal.
Review the agent's proposal for a new or existing project, the run goal
and optional acceptance criteria. In the integrated assistant, creation and
run launch have separate confirmation buttons. Both use the existing MCP.
Without criteria, the run drafts its own
checklist from the goal.
Follow the run as agents plan, write files, start servers and check their
work, with the model, tokens and cost behind every step.
Preview web results in a temporary, isolated environment, including a
snapshot while the run is still building.
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.
Features
Acceptance criteria you approve before launch
A project run can carry up to twelve criteria, supplied through MCP or the
CLI (--criteria <file>). 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, or their own Claude Code token (beta). 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. TypeScript/JavaScript sources also expose symbols and resolved local imports through Haystack; clients use atoma_run_search to inspect saved versions (scope and evaluation). See GitHub App setup.
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.
For an existing static page, the host also replays browser checks recorded by
earlier runs before editing begins and again before delivery. Regressions go
to the final review, which distinguishes requested changes from lost behaviour.
Read-only phases restore the files they changed, and workers read existing
files before editing them. See inherited browser checks.
Decision handles bounded decisions
Decision, TypeSafe's Jev model, helps choose an agent or recipe, approve intermediate plans
and results when the evidence permits it, and avoid learning equivalent
recipes twice. It answers structured questions; the run's models still plan,
write code and explain refusals. Uncertain or unavailable answers go back to
those models, and final delivery acceptance stays independent of Decision.
The initial goal and starting repository guide the root tissue choice. Decision
selects a suitable registered L3; if the choice is uncertain or no tissue fits,
a bounded model call reuses one or requests a new capability. New tissue prompts
are authored by the platform's pinned L3 model using the platform's credentials.
The legacy run:build command also accepts analysis and explanation tasks.
Decision is enabled for every organisation when the host has TYPESAFE_API_KEY,
unless the operator sets ATOMA_JEV=0. Decision context, including task text
and evidence excerpts, is sent to TypeSafe as described in the
service terms.
The timeline records its decisions, latency and separate cost; a sample of
approvals is reviewed by the model for comparison. See the
architecture guide.
Adjust run limits without redeploying
Platform administrators can change run budgets, token and spend ceilings,
call timeouts and tool-iteration limits in Settings or with npm run settings.
Changes are recorded in the audit journal and apply to new runs. A token or
spend ceiling stops further model calls and preserves completed phases as an
incomplete run. See operating run limits.
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 create projects, draft run
goals from the conversation and repository context, start runs, pass acceptance
criteria, request reruns and read traces, costs and diagnostics. The Web console
also provides an integrated assistant for customers without an external agent,
and remains the place to review projects and results. Choose a personal subscription, organisation API key or configured platform API
connection; conversation usage is accounted separately from runs; see setup and limits.
Conversations can continue in either direction between Atoma and an MCP client.
Use Continue in Claude or another agent to copy the continuation prompt;
shared messages and proposals remain private to the same account and organisation.
One endpoint supports both MCP protocol revisions 2025-11-25 and 2026-07-28.
OAuth clients can connect through browser consent, including clients identified
by a metadata URL. Project run tasks survive a client reconnect, and results
link to run resources that compatible clients can open or follow.
Sixty-four tools. The visible subset depends on the caller's role. Compact
searchable menus, recorded progress and saved-file readers keep the workflow
inside the conversation. Versioned project briefs and client-confirmed decisions
are captured per run through atoma_project_context and atoma_project_context_update.
Model suggestions remain proposals until the client confirms them. Sequential
project runs can pause for a blocking client choice, receive an answer through
atoma_run_answer, and resume saved work through atoma_run_resume. atoma_run_review assembles bounded saved evidence before
client acceptance, without running tests or opening a preview. Clients can pause and resume validated work and compare
saved file inventories between runs. atoma_run_start accepts baseRunId to
iterate a specific saved version; status and readiness expose the accepted reference. Deliveries await client testing and explicit
acceptance before GitHub publication. Hosts supporting MCP Apps can also display an inline
run view; every client retains text results and file resource links.
See the MCP connection and authorization guide.
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.
How it works
atoma assigns planning, supervision and execution to different AI agents and
model tiers. Every run starts by default with a planner that breaks the goal
into phases, each handed to a supervisor and its workers. A run can instead
start at the supervisor level; a planner then takes over if supervision
exhausts its retries, and a seeded run keeps its starting workspace when it
does.
The split was designed to make finished work cheaper, and
it does not. It stays the default because every
hand-off between tiers is recorded, which is what makes a run auditable.
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 revokes that trust.
Skills carry forward. Verified work becomes reusable recipes. A recipe
that can be turned into a script is compiled as soon as it is learned, and
the script then runs without model calls until it fails.
The composition model is Element → Molecule → Cell → Tissue: tools, workers,
supervisors and planners. Read How atoma works for
the architecture, execution boundaries and verification design.
One catalogue, shared by every run. An instance keeps one agent registry,
one skill catalogue and one set of trust counters, and every run reads and
writes them, whichever organisation started it. What one team's run works out
is offered to the next team's run. Projects, workspaces, traces and searchable
documents stay scoped to their organisation. This is the design, and it has a
price: prompts and recipes a run writes, including wording derived from a
document it was given, are readable by other organisations' runs. An instance
therefore suits teams that accept pooling what their runs learn. The hosted
service states this in its shared-learning terms.
The cost premise, measured
atoma began from a premise about cost. A frontier model plans, a mid-tier
model supervises, and cheap models do the bulk of the work. Components that
keep succeeding earn the right to skip reviews, and verified work is distilled
into recipes and scripts that later runs reuse. The first runs would pay for
the supervision and later runs would recover it, until atoma cost less than
giving the same goal to one frontier agent.
Fifteen controlled rounds compared atoma with a single agent on build and
maintenance tasks. Rounds 1–12 (August 2026) predate the 2026-08-18 state
reset and are historical narrative. Rounds 13 to 15 and a control-only
calibration (2026-10-31 and 2026-11-01) measured the current release as it
ships, three tiers on gpt-5.6-luna, gpt-5.6-terra and gpt-5.6-sol,
against one gpt-5.6-terra agent and one gpt-5.6-sol agent.
Task
One agent
atoma, three tiers
Maintenance of a three-file CLI (rounds 13 and 14)
7 of 7 correct with either model
6 of 7 correct, at 7.7 to 10.4 times the cost
Four repairs in a real repository (calibration)
12 of 12 correct
not run: nothing was left to improve
An HTML detection function one agent gets wrong half the time (round 15)
3 of 6 correct
3 of 6 correct, at 6.6 times the cost
On the evidence so far, the premise does not hold. The supervision thesis
is refuted on the whole range tested on the current release: on every task
family measured, supervision buys no correctness, and it multiplied the cost.
The overhead is the supervision itself: in round 13, planning took half of
what the runs spent and the work itself a tenth. The mechanisms meant to
recover it did not: the cost per run rose across both atoma series, and in
round 13 no phase ran without a model call. The range tested runs from a
one-minute maintenance task to repairs in a real repository. Larger builds
have not been measured on the current release.
What the three tiers do leave behind is a record. Every hand-off between tiers
follows one protocol: a plan, a verdict on the plan, the work, a verdict on
the work. Each step is stored with the agent and model behind it, its tokens
and its cost. Verdicts rest on evidence the run produced (files, exit codes,
HTTP probes, browser checks), and the acceptance criteria are fixed before
planning starts. The timeline shows all of it in order, MCP clients read the
same record, a finished run can be rerun on other models against the same goal
and criteria, and the analyst writes a cited post-mortem of each finished run.
The single agent atoma was measured against is one tool loop that certifies
its own result.
That is what atoma is offered for today: auditing how agent work was
produced and checked, not producing it at the lowest cost. It suits
reviewing an agent workflow before relying on it, comparing model mixes on the
same goal, and keeping a verification record beside a deliverable. The rounds
measured cost and correctness. They did not measure what that record is worth.
On the tasks measured, if the cheapest correct result is the goal, one capable
agent is the better tool.
The consequence registered with round 15 was to make a single agent the
product's default. On 2026-11-10 the project owner decided against it. The
three-tier split stays the default, on atoma.run and in
this repository, and the single-agent default built for that consequence stays
unmerged on the
feat/direct-depth
branch. Read the decision,
the protocol, round 13,
round 14, round 15 and the
calibration.
Install and evaluate it locally
For the web experience, start at atoma.run.
For a source checkout, use the pinned Node version and follow the
development setup guide, including system
prerequisites. Runs and the full test suite require macOS or Linux; on Windows,
use WSL2 with its own checkout on ext4.
bash
git clone https://github.com/atoma-run/atoma.git
cd atoma
nvm install && nvm use
npm ci
npm run release:check
npm run doctor
npm run run:build -- "a Node CLI that converts CSV to JSON"
npm run viz:serve
The compiled commands read the process environment; they do not load .env.
The local console is open on loopback by default. Organisation-scoped project
runs additionally require Docker and a Haystack search runtime, described in
the development setup guide.
A fresh checkout contains no learned state.
For opt-in execution on a paired macOS or Windows computer with Docker Desktop,
see Atoma Compute. Its headless client runs the workspace, tools,
search and previews locally while Atoma retains orchestration and saved results.
To host an instance for others, follow the packaged stack,
deployment, GitHub App
and preview guides, and back the state up
off-machine with npm run backup -- --dest <mount>.
Status
atoma is an evolving open-source system. Its web console, project runs,
acceptance criteria, comparison reruns, GitHub import and publication, result
previews and MCP endpoint are in use on atoma.run.
Runs go through the three-tier split by default, and that is not changing.
Expect a run to cost several times what one agent would spend on the same
goal: the cost premise behind the split did not
hold when measured, and atoma is offered for auditing runs, not for saving on
them.
Local file-tool containment is not shell isolation; use the container backend
for isolated execution. A platform admin can read across organisations, and
mutually untrusted tenants are not a supported deployment shape. Verification
provides evidence for review, not a guarantee that a generated application is
ready for production. See the changelog for what changed.
Repository facts
Read out of this checkout
Version
0.5.1
Node
24.20+ (.nvmrc 24.20.0, engines >=24)
Subsystems under their own contract
19
MCP tools
64
Curated agent names
118 molecules · 40 cells · 20 tissues
Controlled benchmark rounds
15 (benchmark/RESULT.md + ROUND<n>.md)
Interface locales
13 catalogs — 1 source, 12 translated
Documentation
Browse the documentation index for current guides and the
archive for historical designs, reviews and release evidence.
atoma is free and open-source software under the
GNU Affero General Public License, version 3 (AGPL-3.0-only).
If you distribute a modified version, or run one that users interact with over
a network, you must offer those users its source under the same licence.
Unmodified use, including internal production use and hosting, carries no
obligation beyond keeping the notices. A commercial licence is available from
the author for organisations that cannot accept the AGPL; contributors grant
the rights that make this possible through the CLA, which also
commits the project to remaining under an OSI-approved licence.
Model providers are called with the credentials you supply, under each
provider's own terms. The @anthropic-ai/claude-agent-sdk dependency is
distributed by Anthropic under its own licence, and the 3D assets under
src/viz/public/ carry their CC0 and CC-BY-4.0 notices beside the files.