Aries

Aries takes its name from the first point of Aries: the point on the celestial sphere where the Sun crosses the celestial equator northward at the March equinox. Celestial navigation measures the sky from it. A star’s sidereal hour angle is its angle westward from the first point of Aries, and the almanac gives that point’s hour angle for every second of the year. With those figures, a clock and a sextant sight of two or three stars, anyone anywhere on the globe can fix their position and chart a course, with no signal from anyone else. Aries does the same for AI coding agents: one shared reference that every agent, on any machine and with any model, measures its work against (who holds what, what is ready, what was learned), so that each can fix where it stands and chart its next step.

An issue tracker built for AI coding agents. Agents claim work, hand it off and see who else is working, across sessions and machines. They reach Aries through MCP (Model Context Protocol), the standard way coding agents call tools, and people use the same tracker from the command line. One small Go server keeps the data in Postgres.

Status: stage 5 of 7 done (stage 3 waits only on token capture for Codex and Gemini CLI, a follow-up; stage 3a, many projects on one server, is built and waits on checks on real machines; stage 5 has not run on Windows). Issues, claims, handoffs, the inbox, a live board, scoped memory, token cost (at list price and amortized over plans), people’s hours, agent setup and importing from bd (beads) work today. Stage 5, working without the server, is built and passes its gate in the test stack: the writes made while the server cannot be reached are kept on the machine and sent later, once each, for up to 7 days; a cache shows a session the work it holds while the server is away, saying so; a write that arrives after others changed the issue is parked as a conflict for a person, or kept as a comment; and aries away holds a person’s claims through a planned absence. None of it has run on Windows. The store, the server guide, the installer and the Docker test server run on Postgres (slices P1, P2 and P4 of decision 79), and the long soaks pass on it on Linux, on GitHub’s amd64 and arm64 runners (slice P5). HTTPS is the transport a fresh server serves, with SSH off until an operator turns it on (slice T1 of decision 86); a principal’s kind, identities and invitations are recorded (slice N1); people sign in at their company’s identity provider with aries login, the server issuing its own tokens, bound to the machine’s key (slice T2); and a CI job or a cloud workload signs in as a service principal with its platform’s token, by a trust rule, holding no stored key (slice N5). Both are off unless configured, not yet security-reviewed and not tested against a real provider; v0.5.0, the next release, authenticates by keys (decision 91). Releases are minor versions (v0.5.0, v0.6.0, …) until v1.0.0, which is held as long as possible (decision 93). Not ready for production use yet; see the roadmap.

Why Aries

When several agents work on one codebase, they have to agree on who does what. Aries makes that safe:

• 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. There are no database merges and no conflicts to resolve.
• Identity comes from keys the server knows. Over HTTPS, the default, ariesd checks a proof by your SSH key; over SSH, when an operator turns it on, sshd checks the key. A client cannot claim to be someone else.
• Built for context windows. Results are compact: 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. Errors come 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

Planned: an offline cache and conflict handling, and Bearings, an orchestrator that runs and supervises many agents on top of Aries (design).

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)

• aries is the client: a command line for people, and an MCP server for agents. It runs on Linux, macOS and Windows. The name is short for Aries.
• Over HTTPS, the default, aries proves it holds a key the server knows, and the server takes the key’s principal, the name it knows you by; nothing on the connection reaches the protocol before that. Over SSH, which an operator turns on, sshd checks the key, and each key’s line in authorized_keys runs one fixed command, ariesd stdio --principal NAME. Either way the key, not the client, decides your principal.
• ariesd serve owns the data. It applies every change in order, records each as an event in the same transaction, and stores it in Postgres. It runs on Linux.
• Messages are newline-delimited JSON. Each connection opens with a version handshake.

Deployment examples

Costs are Google Cloud list prices for us-central1, read in October 2026. Deployment examples compares the three.

Quick start

To join a project that has a server:

1. Install aries.

2. Send your public SSH key, such as ~/.ssh/id_ed25519.pub, to the server’s admin. aries signs in with the key ssh would use: a default file in ~/.ssh, or a key in ssh-agent. To use another, set ARIES_KEY_FILE to its path (Your key is your identity).

3. In the repository, which has a committed .aries.yaml, check the connection:

   aries ready
   

4. 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 --write
   

   The files tell agents to call prime when a session starts, then start and finish for each issue. Agents lists every agent, and the one step each person still takes on their own machine, such as approving the MCP server.

To run your own server, start with the Local example, or follow Running a server on any Linux machine.

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. A server on Ubuntu 24.04 LTS or 26.04 LTS is set up by one script, install-server.sh (With the installer).

Documentation

Roadmap

v0.5.0, and v1.0.0 held. The next release is v0.5.0, the release decisions 81, 90 and 91 called v1.0.0: the production release, v1.0.0, is held as long as possible, and until then releases are minor versions, v0.5.0, v0.6.0 and on, which aries upgrade installs (decision 93). From v0.5.0 on, a release that changes the protocol keeps accepting the one before it. The releases before 1.0 carry the features pulled forward: the project workflow setting and organization memory. The names a dashboard or an alert relies on are kept from v0.5.0, and v1.0.0 is when the settings are frozen for 1.x. v0.5.0 is cut back so that Aries can be used to build Aries sooner (decision 90), and cut back again to authenticate by keys alone (decision 91). It holds the rename to Aries; the move from Dolt to Postgres, slices P0 to P5 of decision 79; stage 6’s slices G0 to G2; HTTPS as the primary transport, with SSH off unless an operator turns it on, people and services authenticating by keys, over HTTPS by the key proof or over SSH; and a hardening pass: a review of every public name, flag, variable and setting, the protocol settled at one version (decision 78), and a security review of the HTTPS listener. Sign-in through your company’s identity provider (T2) and service principals by workload identity (N5) are on main but off unless configured, and neither is security-reviewed or tested against a real provider; those checks, the provider guides and N0 come in 1.x. Built: all of it, but the rest of P5 (ACME against a real CA) and the listener’s review. Of P5, the soaks pass on Linux, on GitHub’s amd64 and arm64 runners, and so do the installer and the AppArmor profiles enforced under systemd. A remote MCP endpoint, GitHub’s sign-in and the device grant, a Claude Desktop extension, and stage 6’s G3 to G5 come in 1.x releases, after v1.0.0, as compatible additions.

The Bearings stages (B0 to B5) start once Aries stage 3 lands; see the Bearings plan.

Names

Aries is the coordination server and its client, ariesd and aries. Bearings is the orchestrator planned on top of it, a design only. Sextant is reserved for future observability: metrics, monitoring, tracing, and cost and usage reporting. It is a name only; nothing moves under it now.

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 © 2026 Ariesworx LLC.

Contributions are accepted under a contributor license agreement, as CONTRIBUTING.md says.