AI Multi-agent Sessions — git-native session management for AI coding agents, across many machines and many agents.

AIMS turns each unit of AI work into a git branch in an isolated worktree. Sessions can be handed off between machines and adopted by any agent — because the source of truth is a git remote (origin), never a machine-to-machine link. No agent needs access to another's computer.

You never learn AIMS commands. Your agent does. You talk to it normally — "save and close the session", "hand this off to the other machine" — and it runs AIMS for you.

v1.0.0 is the stable AIMS 1.0 command-line contract, verified through CI and an independent Ubuntu installation. See the CLI compatibility policy and the acceptance test.

The demo shows the verified lifecycle: start → save → handoff → adopt → save → publish. Run the same workflow safely with disposable local repositories using the under-3-minute acceptance test.

Install AIMS from its official public repository: https://github.com/visaroy/aims

1. Review it first. Read README.md, SECURITY.md, and LICENSE, and skim bootstrap.sh,
   install.sh, and lib/. Confirm for me that it: makes no network calls except `git` to
   repositories I configure, ships no secrets or telemetry, needs no elevated privileges,
   and backs up any file it modifies. Summarize the security posture before installing.

2. Install it (this accepts the MIT license and its "AS IS", no-warranty terms on my behalf):
     curl -fsSL https://raw.githubusercontent.com/visaroy/aims/main/bootstrap.sh | AIMS_ACCEPT=1 bash
   The installer links the `aims` command, creates my private data repo at ~/.aims, and adds an
   AIMS rules block to the config of each AI agent it detects — backing up each original first.

3. Give my data repo a remote so sessions sync across machines, then verify. Ask me for the URL
   of a private git repo I control (create one if I don't have it), then run:
     git -C ~/.aims remote add origin <MY_PRIVATE_DATA_REPO_URL>
     git -C ~/.aims push -u origin main
     aims doctor
   Also add `export AIMS_HOME=$HOME/.aims` to my shell profile.

4. Report what you reviewed, the security summary, which agent config files were changed (and
   where the backups are), and the final `aims doctor` output.

To restore/update AIMS later, run `cd ~/aims && bash install.sh`: it prints `🔄 Restoring a fresh, official AIMS version from the official GitHub repository…`, fetches `origin/main`, then runs `git reset --hard origin/main` and `git clean -ffdx` before refreshing the command link. It deliberately deletes every local tracked, untracked, and ignored engine file (including nested worktrees such as `.slim/`) so `~/aims` is an exact official checkout; it still refuses a non-`main` branch.

Running this on more than one machine, each pointed at the same private data repo, is the whole multi-machine setup — the machines meet only on that remote, never on each other.

Running AI agents (Claude, Codex, opencode, Gemini) across a laptop and a workstation creates the same problems every time: work stranded on one machine, two agents clobbering each other, "done" that never reached the shared repo, and no clean way to pick up someone else's half-finished task.

AIMS solves this the boring, durable way: plain git. Branches, worktrees, and a small set of scripts with guards that make the failure modes loud instead of silent.

Two layers, deliberately separated:

You continue a session from artifacts (worklog + commits), never from the previous agent's head. That is what makes it agent-agnostic and machine-agnostic.

Every AI CLI has a native resume (claude --resume, codex resume, gemini --resume, opencode's session continue). They all move the conversation within one tool on one machine. AIMS moves the work across machines and across tools:

Full breakdown across all tools: docs/COMPARISON.md. A focused comparison with Softaworks Agent Toolkit's session-handoff skill: docs/SESSION-HANDOFF-COMPARISON.md.

Setup has two sides: the agent environment (the CLIs you talk to) and, optionally, a hardware / storage environment (a shared network store for large files). After setup you interact only with your agent in natural language — AIMS runs underneath.

Install whichever agent CLIs you use — any mix works: Claude Code, OpenAI Codex CLI, opencode, Gemini CLI. Also need git, bash, python3 (macOS or Linux).

curl -fsSL https://raw.githubusercontent.com/visaroy/aims/main/bootstrap.sh | bash

This: installs the engine to ~/aims, links the aims command, creates your private data repo (~/.aims), and teaches every installed agent to understand AIMS by writing an AIMS rules block into their config files (~/AGENTS.md, ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md). For a later engine restore/update, run cd ~/aims && bash install.sh: it announces the official-repository restore, fetches origin/main, then uses git reset --hard origin/main plus git clean -ffdx before refreshing the link. This deliberately removes local tracked, untracked, and ignored files — including nested worktrees such as .slim/ — so ~/aims is exactly the official engine; it refuses only a non-main branch.

Then point AIMS at your data repo and give it a remote so sessions sync across machines:

echo 'export AIMS_HOME=$HOME/.aims' >> ~/.bashrc   # or ~/.zshenv
git -C ~/.aims remote add origin <your-private-data-repo-url>
git -C ~/.aims push -u origin main
aims doctor

Git holds session pointers; a shared network store holds the bytes (build outputs, dumps, datasets). Point AIMS_ARTIFACTS at a mounted store and pick any backend — NFS, SMB/Samba, GlusterFS, CephFS, MinIO, RustFS, Ceph RGW. Copy-paste recipes: docs/SHARED-STORE.md.

echo 'export AIMS_ARTIFACTS=$HOME/.aims-artifacts' >> ~/.bashrc   # mount point of the shared store

Run step 2 on every machine and point them at the same origin data repo. That is the whole multi-machine setup — no machine ever connects to another; they meet on origin.

You do not memorize aims start / aims save / etc. Say what you want; the agent maps it:

"start on the login bug" · "save the session" · "hand this off to the laptop" · "continue session 2026…-login-fix" · "save and close the session"

The commands below are what your agent runs after interpreting your intent. You never type them. They are documented so agents — and the curious — know exactly what happens.

aims start myproject "fix login bug" claude    # new branch + worktree
cd ~/.aims/.worktrees/<session-id>             # agent works here
aims save                                       # checkpoint: commit whole worktree + push
aims rebase <session-id>                         # safe rebase after a publish merge conflict
aims handoff "waiting on CI"                     # hand to another machine (pushes everything)
# Or, from ~/.aims/.worktrees: aims handoff <session-id>
aims adopt <session-id>                          # (elsewhere) take it over from origin
aims publish <session-id>                        # merge to main, register, done

See docs/COMMANDS.md, docs/ARCHITECTURE.md, docs/AIMS.md, docs/AGENTS-MEMORY.md, and the agent integration strategy. Also see the acceptance test, CLI compatibility policy, and the session handoff roadmap. Documentation language: English is official; translations under docs/i18n/.

• No silent data loss: aims save stages the whole worktree and always pushes when ahead; aims publish refuses a dirty or unpushed worktree and warns on an empty merge.
• Safe rewritten checkpoints: only aims rebase creates the private exact-OID rewrite marker; aims save uses --force-with-lease only when the remote still has that exact captured OID.
• Concurrent writers are preserved: a remote advance, deleted branch, stale marker, or unmarked divergence is refused rather than force-pushed.
• Publication state is centralized: start, save, rebase, handoff, and adopt maintain the local refs/aims/published/<id> sentinel; adoption push failures are fatal and retain the worktree.
• Every branch update is leased: existing branches use the exact fetched OID, while initial branch creation requires remote absence and a zero-OID lease.
• Pre-existing divergence is refused: handoff and adopt require the fetched remote tip to be an ancestor of local HEAD before checkpointing or applying an exact lease.
• Adoption targets are exact: adopt edits and pushes only a worktree on ai/<session-id> and checks the observed remote OID against that exact local branch/HEAD, including stale-branch recovery.
• Force-policy recovery is supported: save rebased HEAD at refs/aims/recovery/<id>, reset to refs/aims/rewrite/<id>, merge origin/main without committing, restore the recovery tree, commit, then save; delete the recovery ref only after success so actual conflict work is preserved.
• No two-writer conflict: aims adopt warns if a branch moved recently; aims handoff marks a session released so adoption elsewhere is known-safe.
• main is protected: a pre-push hook blocks direct pushes; integration only via aims publish.
• No secrets, no external calls: the engine talks only to your origin. See SECURITY.md.

git, bash, python3. macOS and Linux.

MIT — see LICENSE.