aipass

Install

You need: Python 3.10+, Claude Code on a Claude plan that includes it, and Linux or macOS (Windows through WSL2).

pipx install aipass
aipass install

The first line puts two commands on your PATH, aipass and drone. The second clones AIPass into ~/AIPass (--path to choose), builds its environment, sets up the 18 agents, runs a health check, and ends with the AIPass concierge on screen, greeting you and saying what your machine still needs. It also starts a server on your machine for BAUD, the phone face; --no-baud skips that.

To work on AIPass itself, install from a clone instead (this route skips the phone step):

git clone https://github.com/AIOSAI/AIPass.git && cd AIPass && ./aipass install

Install adds AIPass hooks and deny rules to your user-level Claude Code settings, a few lines to your shell rc, and command links on your PATH; it may also set git's pull.rebase and add one npm package. See every change it makes. Something off afterwards? aipass doctor names it and aipass doctor --fix cures what it can.

Start here

1. Make a project, or adopt one you have. aipass new builds a new project around a resident manager agent, makes the first commit, and ends in a conversation with that agent. aipass init run, run inside a directory you already have, does a guided setup and ends with claude open in it; its aipass_framework template adds the first agent on the way.

   aipass new my-project --template python   # New project: scaffold, resident manager agent, first commit
   aipass init run                           # A directory you already have: run inside it, guided setup
   

2. Talk to your manager. Run claude in the manager's directory and say what you want in plain words, such as "Add a CSV export to the report command." It writes a plan, sends the work to the agent that owns that code, and reports back when it lands. The same two steps by hand:

   drone @flow create . "Add CSV export"            # A work plan that carries the context
   drone @ai_mail dispatch @agent "Subject" "Body"  # Send the task and wake the agent
   

3. Grow it and check it. Add an agent with drone @spawn create src/my_project/analyst --role "Analyst" --purpose "Reports". Run drone @seedgo audit aipass for the same standards checks AIPass's own agents pass in CI, and aipass doctor for the health of the install.

Why AIPass

When the task gets complex, you become the coordinator. You copy context between tools, dispatch work by hand, and keep track of who is doing what.

Many multi-agent setups give each agent its own sandbox or worktree. One agent can't see what another just built, and when the task ends, the agent is gone.

That's not a team. That's a room full of people wearing headphones.

In AIPass, agents are citizens. Each has an identity, a memory that survives the session, a mailbox, and a home directory, on the same filesystem as you and each other. Hooks and gates decide who may write what. Switch projects, come back a week later, and nothing has to be explained again.

How it works

One bus. drone @agent command [args] reaches any agent. You use it, and agents use it to reach each other.

One memory each. The owning agent wakes in its own folder with its own prompt, its .trinity/ memory, a refreshed dashboard and the task mail. Nobody re-explains context. The longer story goes in a plan (drone @flow create) that the manager writes and names in the mail.

One citizen shape. Every agent, yours and the reference fleet, has the same layout. Know one and you know them all. The main parts:

src/my_project/<agent>/
├── .trinity/              # Passport + memory: sessions, learnings, todos, observations; overflow rolls to @memory
├── .ai_mail.local/        # Mailbox: inbox, sent, deleted
├── .aipass/               # Branch prompt: the agent's standing instructions, injected by hooks
├── apps/                  # Entry point → modules → handlers
├── docs/                  # Reference pages, tracked
├── docs.local/            # Scratch and research, not tracked
├── dropbox/               # Inbound drop: files other agents hand over
├── artifacts/             # Birth certificate + files the agent produces
├── logs/                  # The agent's own logs
├── tests/                 # The agent's own test suite
├── DASHBOARD.local.json   # One status glance: mail, plans, todos; refreshed before every wake
└── README.md              # The page for people; agents use `drone @<agent> --help`

An agent's identity is a file it can read, .trinity/passport.json, trimmed here to the lines that matter:

{
  "branch_info": { "branch_name": "analyst", "email": "@analyst", "path": "src/my_project/analyst" },
  "identity": {
    "role": "analyst",
    "purpose": "Reports on the data the project collects",
    "principles": ["Fail honestly: errors over silent fallbacks"]
  }
}

One owner seat. Each project has one manager agent you steer through. Every agent can read git through the bus; only a project's manager writes to it.

No index. Nothing indexes your codebase. An agent finds its way the way a new colleague does: the bus, the owning agent's README, and its own memory of what it did last time.

What you get

The boring stuff works. One human and these agents built it, and use it every day to build AIPass itself and BAUD.

• Memory that persists. Every agent remembers across sessions in plain JSON files. When those fill up, older entries roll into a local vector store you can search. Each agent has a home, a passport, and a commons where the fleet posts and gathers.
• Mail and dispatch. Agents send each other tasks and results, and wake whoever they are waiting on.
• Plans that carry context. Work is written down as a plan, so whoever picks it up knows why it exists and where it stands.
• Gates. Hooks decide which agent may edit which files. Git goes through one door. Raw deletes are refused.
• Works in your own repos. A project that holds an agent calls the fleet right away. For the fleet to send work to it, declare it once with drone @memory roots add <path>.
• Standards audits. AIPass's own 18 agents are audited in CI on every change against one written standard; drone @seedgo audit runs the same checks on yours.
• Logs and backups. Every agent logs to its own place, and runaway logs are caught. Local snapshots you can restore from, with optional Google Drive sync.
• The daemon. drone @daemon install-timer starts a scheduler for recurring jobs, and each agent owns its own schedule.
• Everything local. Memory and mail are files on your machine. Nothing leaves it except what Claude Code itself sends to Anthropic, unless you turn on an outside API or Drive sync with your own keys. The phone face serves on your own tailnet, and the first memory search downloads its small embedding model once.

What install changes

Install builds the environment, puts aipass and drone on your PATH, and sets up the 18 agents. It runs a health check that fixes what it can. In an interactive shell it ends in a conversation with the AIPass concierge, which greets you and walks you through what your machine still needs. On the way it may ask for your git identity (only if it is not set globally), your name, and whether the session should ask before system-changing commands. A non-interactive shell finishes with defaults and no prompts, and skips both the health check and the conversation; --no-chat skips them in any shell.

Install changes a few things outside the repo, and you should know what. It adds AIPass deny rules to your user-level Claude Code settings (no raw git writes: commit, push, reset, rebase, merge, config and the destructive checkout, restore, stash and branch forms; no reading ~/.secrets/), and these apply to every Claude Code project on the machine. It merges its hooks with any you already have. It adds a claude shell function that, inside an agent directory, boots that agent's seat, attaching to it if one is already live. It sets git config --global pull.rebase true when it sets your git identity. On Linux it installs the @anthropic-ai/sandbox-runtime npm package if it is missing; macOS runs without the sandbox. On Linux, sudo may ask once to place the /usr/local/bin symlinks. Re-running install rebuilds .venv. The list below names every file it touches.

The installer writes a layer outside the project. Remove all of it to erase AIPass completely: