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.7.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.7.0 brings protocol 10, prices by prompt length, the guard, and the dispatcher and outcome record, experimental (notes).
• 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:

1. Install aries.

2. Send your public SSH key, such as ~/.ssh/id_ed25519.pub, to the server's admin. aries uses the key ssh would: a default file in ~/.ssh, or a key in ssh-agent; set ARIES_KEY_FILE to use another (Your key is your identity). Where the server signs people in at the company's identity provider, run aries login instead (Sign in).

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.

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, ariesd checks 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

| You can | With | Read more | |---|---|---| | Track issues with types, priorities, labels, parents, dependencies and dates, and see what is ready or blocked | create, ready, blocked, dep | Issues, Ready and blocked, Dates | | Claim an issue, then close it with a handoff note, filing what you found on the way | start, finish | Claims, Start and finish | | Check work against its acceptance items | accept, finish --tick | Acceptance criteria | | Set the acceptance items and required checks each issue type gets | workflow, workflow check | The workflow | | Hold work until a person approves or CI reports a check | gate | Gates, CI gates | | Report what merged, from a machine or a scheduled job, for a server CI cannot reach | land, setup pull-job | A server CI cannot reach | | Hold a lock or a semaphore around a command | lock run | Locks |

Work together

| You can | With | Read more | |---|---|---| | Hand work between people and agents | handoff --to | Handoffs | | Get mentions, handoffs, assignments and lost claims in an inbox the server pushes | inbox, watch | The inbox | | See every session at work and what it holds | who | Who is at work | | Watch ready, held and blocked work change live in a terminal | tui | The live board | | Summarize a day or a week for a standup | digest | The digest | | Keep what the next session needs to know, for the project, the team or yourself | remember, recall, memories, pin | Memory | | Keep working while the server cannot be reached: writes queue and are sent once, later | outbox, cache, resolve, away | When the server cannot be reached |

Measure time and cost

| You can | With | Read more | |---|---|---| | See the time and tokens each issue took, by account (tokens from Claude Code so far) | show, digest, usage --hook | Accounts, time and tokens | | Report token cost at list price, and amortized over subscription plans, by account, issue, epic, person, model or outcome | cost, admin price, admin plan | Cost, Prices, Plans | | Log the hours people spend on an issue | hours | Human hours | | Export each project's cost by model and account, tokens, hours and unpriced tokens to Prometheus or an OTLP backend, with alert rules and a dashboard | sextant | Running Sextant |

Set up and run

| You can | With | Read more | |---|---|---| | Set up Claude Code, Codex, Gemini CLI, Cursor, VS Code, Junie, JetBrains AI Assistant or Claude Desktop | setup | Agents | | Check each command and edit a Claude Code agent makes against one policy file | guard | The guard | | Keep agents at work on ready issues without a person starting each session (experimental; macOS and Linux) | dispatch | The dispatcher | | Serve many projects from one server, and manage projects, people, keys and memberships from any machine | admin project, admin principal, admin key, admin member | Serving many projects | | Watch the server: metrics, traces, logs, health and a status report | admin status, ariesd status | Observability | | Send Claude Code's own metrics, without content, to the same Collector | settings, ARIES_AGENT_OTLP_ENDPOINT | Agent metrics | | Reach a server that has no public address, through Google Cloud IAP | iap: in .aries.yaml | Servers without a public IP | | Move a bd (beads) backlog over, keeping its IDs | ariesd import-bd | Moving from bd | | Upgrade clients and the server from signed releases | upgrade | Upgrade and roll back |

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)

| Part | What it does | Runs on | |---|---|---| | aries | The client: a command line for people, and an MCP server for agents | Linux, macOS, Windows | | ariesd serve | Owns the data: applies every change in order, records each as an event in the same transaction, and stores it in Postgres | Linux | | HTTPS (default) | aries proves it holds a key the server knows; the server takes that key's principal, the name it knows you by | | | SSH (when turned 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 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

| Example | For | Server | Cost a month | |---|---|---|---| | Local | One developer and their agents | Your own Linux machine, WSL2 or a Linux VM | $0 | | Team | A team with agents on laptops, in cloud sandboxes and in CI | A small cloud VM, reached over SSH | About $19 | | Enterprise | A company that keeps the tracker off the internet | A private VM behind Google Cloud IAP, with backups nothing on it can delete | About $65 to $114 |

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

| Guide | Covers | |---|---| | How Aries works | Identity, issues, dependencies, gates, locks, claims and leases, the workflow, handoffs, the inbox, memory, time and cost | | Using aries | Connecting a reposito