Aries
An issue tracker, shared memory and coordination layer for AI coding agents. Agents claim work, hand it off and see who else is working, across sessions, machines and models. They reach Aries through MCP (Model Context Protocol), the standard way coding agents call tools; people use the same tracker from the command line. One small Go server keeps the data in Postgres.
Aries is for teams, and single developers, who run several agents on one codebase and need them to agree on who does what, what is ready, what was learned and what has really landed.
Status: v0.8.0 is the current release; stage 5 of 7 done. Not ready for production use yet: v1.0.0, the production release, is held as long as possible, and until then releases are minor versions (decision 93).
- Works today: issues, claims, handoffs, the inbox, the live board, memory, token cost, people's hours, gates, locks, agent setup, and import from bd (beads).
- Built and passing its gates in the test stack: many projects on one server, observability, work while the server cannot be reached, and a project's workflow, where closed means landed. None of the offline work has run on Windows.
- v0.8.0 brings protocol 11 and briefs stored on the issue they start (notes), after v0.7.0's prices by prompt length, the guard, and the dispatcher and outcome record, experimental.
- HTTPS is the default transport; SSH is off until an operator turns it on. Releases authenticate people and services by keys (decision 91). Sign-in at a company's identity provider and CI sign-in by workload token are built, off unless configured, and not yet security-reviewed.
The roadmap has the detail.
Quick start
Join a project that has a server:
-
Send your public SSH key, such as
~/.ssh/id_ed25519.pub, to the server's admin.ariesuses the keysshwould: a default file in~/.ssh, or a key in ssh-agent; setARIES_KEY_FILEto use another (Your key is your identity). Where the server signs people in at the company's identity provider, runaries logininstead (Sign in). -
In the repository, which has a committed
.aries.yaml, check the connection:aries ready -
If nobody has set your agent up in this repository yet, do it and commit what setup writes. For Claude Code:
aries setup claude-code --writeThe files tell agents to call
primewhen a session starts, thenstartandfinishfor each issue. Agents lists every agent and the one step each person still takes on their own machine.
Run your own server: start with the Local
example, or follow Running a server on any Linux
machine. On Ubuntu 24.04 LTS or 26.04 LTS, one script,
install-server.sh, does the setup
(With the installer).
Install
On Linux or macOS:
curl -fsSL https://raw.githubusercontent.com/ariesworx/aries/main/install.sh | sh
The script checks the release's checksum, and its signature when
OpenSSL 3 is installed, then installs aries into ~/.local/bin. It
never uses sudo. On Windows, download the zip from the
releases page.
Installing Aries covers the options, the server
binary, building from source and verifying a download by hand.
Why Aries
- Claims can't go stale. An agent claims an issue with a lease. If the agent dies, the lease lapses within 15 minutes and the issue is ready again. An agent that lost its claim cannot close work someone else has since taken.
- One authority. All changes go through one server, which puts them in order and records each as an event. There are no database merges. An edit made offline that meets another is parked for a person to resolve, never merged silently.
- Closed means landed. A project's workflow adds the acceptance
items every issue must meet, and can hold an issue open until CI, or
aries land, reports that its change merged. - Identity comes from keys the server knows. Over HTTPS,
ariesdchecks a proof by your key; over SSH, sshd checks it. A client cannot claim to be someone else. - Built for context windows. A write returns only the issue's id and
new revision (
{id, rev}), and no result passes about 2,000 tokens. - Failures say what to do. Every error comes with a
fix:line naming the next step, and each exit code and error code has one documented meaning.
What you can do with it
Plan and track work
Work together
Measure time and cost
Set up and run
Using aries lists every command.
How it works
agent ──MCP──┐ the server
├─▶ aries ══ HTTPS (WebSocket) ═══════▶ ariesd serve ─▶ Postgres
person ─CLI──┘ ╚═══ SSH, when turned on ══▶ sshd ─▶ ariesd stdio ─┘
(unix socket, 0700)
Either way the key, not the client, decides who you are. Messages are newline-delimited JSON, and each connection opens with a version handshake. Design has the architecture, and Security model what each part trusts.
Deployment examples
Costs are Google Cloud list prices for us-central1, read in October 2026. Deployment examples compares the three, and the Docker test server runs one locally for development.
Documentation
Using Aries
Running a server
Building Aries
Roadmap
Beside the stages, a project's workflow
(§21):
default acceptance items (W0), close means landed (W1), aries land
(W2), review and approval (W3) and the close-out checklist (W4) are
built, in v0.5.0; a server-wide default (W5) is not.
Releases. Releases are minor versions, v0.5.0, v0.6.0 and on, until v1.0.0, which is held as long as possible (decision 93). From v0.5.0 on, a release that changes the protocol keeps accepting the one before it, and the names a dashboard or an alert relies on are kept.
Sextant, cost and flow of the agents' work as series a dashboard draws and an alert watches, starts before v1.0.0 (decision 100). Built: its exporter (X0); cost by account, tokens, hours and unpriced tokens (X1, without amortized cost); and alert rules and a dashboard (X3, without the rules that wait on flow). Planned in sextant.md: flow (X2) and a release of its own (X5).
Bearings, an orchestrator that runs and supervises many agents on top of Aries, is a design only; its stages B0 to B5 are planned in the Bearings plan.
Names
Aries takes its name from the first point of Aries, the point on the celestial sphere from which celestial navigation measures the sky. With the almanac's figures for it, a clock and a sextant, a navigator fixes their position with no signal from anyone else. Aries gives AI coding agents the same: one shared reference, on any machine and with any model, to fix where their work stands and chart the next step. The mark on that theme (Celestial Fix — Airy) lives in assets/icon.
- Aries is the coordination server and its client,
ariesdandaries. - Bearings is the orchestrator planned on top of it, a design only.
- Sextant is observability of the agents' work: metrics,
monitoring, tracing, and cost and usage reporting, a binary of its own
in this repository (decision 98).
Its exporter of each project's cost, tokens and hours beside one
ariesdis built, with alert rules and a dashboard (Running Sextant); the rest is a design (sextant.md).
Further reading
Background reading behind the dark-factory idea, context engineering and multi-agent coordination. The full annotated list is in References.
- Robots, the maker of robots, in FANUC's dark factory: where the lights-out idea comes from.
- The Five Levels: from Spicy Autocomplete to the Dark Factory: a vocabulary for how autonomous a software team is.
- The State of Context Engineering: a current overview of context engineering.
- Effective context engineering for AI agents: the practical method; context as a finite attention budget.
- Welcome to Gas Town: what running 20 or more agents at once looks like, and why coordination becomes the bottleneck.
Contributing
CONTRIBUTING.md gets you from a clone to a passing
gate (scripts/gate.sh runs what CI runs) and to a pull request.
AGENTS.md holds the rules every contributor follows,
person or agent.
Relationship to beads
Aries is an independent project, inspired by and able to import from
beads (bd). It is not part of,
or endorsed by, the beads or Dolt projects.
License
AGPL-3.0-only. See LICENSE. Copyright (C) 2026 Ariesworx LLC.
Contributions are accepted under a contributor license agreement, as CONTRIBUTING.md says.