RELAI

README

Relai

Pass the baton between people and their AI agents, across all their projects — without losing context, and without rebuilding what already exists.

Relai is an open, agent-agnostic layer of files in git plus one CLI. No server, no portal:

• a repo contract (AGENTS.md, relai.yaml, a generated handoff of a few hundred tokens, specs and tasks) so whoever pulls the repo — and their agent — knows the next steps immediately;
• check before you build: a project index (a plain git repo of relai.yaml files) to find what the other projects already provide before writing a duplicate;
• shared conventions that every repo points to, so every agent reads the same rules;
• links between projects: what each repo provides and consumes, with upstream changes shown in the handoff;
• an optional golden path: a project template born with all of the above.

It composes existing standards (AGENTS.md, Agent Skills, OpenSpec, Beads) instead of replacing them.

Status: early development (v0.x, everything may change). Read the design document; the handoff is being evaluated with real agents in eval/.

Made to be easy: one binary, no server, nothing but git. Useful on day one for a single person or a small team; the multi-project features (index, conventions) are optional layers.

How it fits together

flowchart TB
  subgraph repo["Repo contract (every repo)"]
    agents["AGENTS.md (L0, ≤100 lines)"]
    manifest["relai.yaml (provides / consumes)"]
    notes[".relai/notes.md (decisions, pitfalls)"]
    specs["openspec/ + .beads/ (adapters, optional)"]
  end
  handoff["relai handoff (L1, ≤2k tokens, generated;<br/>degraded mode if none of the above exists)"]
  repo --> handoff
  conv["Shared conventions repo (versioned, planned)"] -. "referenced by relai.yaml" .-> repo
  index["index.json (relai.yaml of every known project)"]
  repo -- "relai index build" --> index
  person(["Person B + their agent"]) -- "git pull, read L0 + L1, then bd ready" --> repo
  person -- "relai find: check before you build" --> index
  tpl["Golden path template (planned)"] -. "new repo, pre-wired" .-> repo

Solid arrows are shipped; dashed ones are planned (shared conventions, golden path — see docs/DESIGN.md). Everything shipped runs from a single static binary against local git repos — no server, no Docker, no account, including the cross-repo index above.

Same diagram, as an editable draw.io file

Quick start

Install the binary — no Go toolchain needed:

curl -fsSL https://raw.githubusercontent.com/ECG-Rudy-Glt/RELAI/main/scripts/install.sh | sh

Or download a binary directly from the releases page (Linux/macOS/Windows, amd64/arm64). From source:

go install github.com/ECG-Rudy-Glt/RELAI/cmd/relai@latest   # Go ≥ 1.23

Then:

cd your-repo
relai init        # adds AGENTS.md (or links it to CLAUDE.md), relai.yaml, .relai/notes.md
relai discover    # lists what the project already gives agents: skills, hooks, specs, tracker, docs
relai handoff     # prints where the work stands, in ≤ 2,000 tokens

Adopting Relai in the middle of a project. Nothing is moved or rewritten: relai discover finds the existing harness (AGENTS.md/CLAUDE.md, skills, commands, hooks, MCP servers, Beads or GitHub Issues, OpenSpec or Spec Kit, ADRs, handoff and journal docs, CI) and the handoff points to it. relai discover --prompt prints instructions for your own agent to draft .relai/notes.md (decisions, pitfalls, next step) from those docs; you review the draft and commit it.

The handoff format is specified in spec/handoff.md.

Point your agent at it: AGENTS.md tells any agent to run relai handoff first. With Claude Code you can also run it from a SessionStart hook. relai handoff reads Beads tasks and OpenSpec changes when they are present, and works without them.

Check before you build

Before writing a new capability, check whether one of your other projects already provides it, using nothing but each project's own relai.yaml — no server, no account.

# repos.txt: one local path or clone URL per line, blank lines and #comments ignored
cat > repos.txt <<'EOF'
../other-project
https://github.com/you/another-project.git
EOF

relai index build -o .relai/index.json repos.txt   # reads each repo's relai.yaml, skips what it can't
relai find --index .relai/index.json auth.oidc      # or just `relai find auth.oidc` (default path above)

relai index build reads the list, clones any clone-URL entry to a temp dir (shallow, read-only, cleaned up after), and collects every repo's relai.yaml into a single index.json: an array of {"source": "<path-or-url>", "relai_yaml": {...}}. A listed repo that is missing, not a git repo, or has no relai.yaml is skipped and reported on stderr; the rest of the index is still built.

relai find <capability> prints every indexed repo whose relai.yaml lists that capability under provides: (its id, source, and summary:), or states plainly that nothing provides it yet. If no index has been built yet, it says so and names the relai index build command instead of failing with a file-not-found error.

This only builds and reads a flat index.json you keep in git or share however you like; see docs/multi-repo.md for the larger (not yet built) multi-repo design this is a first slice of.

Golden path: scaffold from your own template

Relai ships no template of its own — a group's CI and deployment choices are its own. relai new scaffolds a new repo from a template you already have (a local directory or a clone URL), the same way relai index build sources a repo list:

relai new ./my-org-template ./my-new-tool          # local template
relai new https://github.com/you/template.git ./my-new-tool   # or a clone URL

A template is just a directory of files. Any text file may use the placeholder token {{.RepoName}} (Go's text/template syntax); relai new substitutes it with the new repo's name (the target directory's base name) as it copies the template in. A file that isn't valid template syntax — including any binary file — is copied byte for byte, unchanged. Anything the template doesn't already provide (AGENTS.md, relai.yaml, .relai/notes.md) is filled in the same way relai init fills it, without overwriting what the template did provide. The target directory must not already exist and contain files — relai new never merges into one.

Worked example: a template with an AGENTS.md containing # {{.RepoName}} — instructions for AI agents and a relai.yaml with id: {{.RepoName}} produces, for relai new ./tpl ./widgets, an AGENTS.md titled "widgets" and a relai.yaml with id: widgets — and still gets .relai/notes.md from relai init's own template, since the example template didn't provide one.

On success, relai new prints the relai index build command to add the new repo to your group's index — it does not run it for you.

Licence

Apache-2.0.