AIPass

An operating system for AI agents that remember

For Claude Code users who want their agents to remember last week, hand each other work, and build in the repos they already have.

Docs · BAUD: your agents on your phone · Discussions · r/AIPass · aipass.ai

Three commands on the bus: the fleet, a memory from a month ago found by meaning, and a standards audit at 100. The script that recorded it.

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, adds BAUD, the phone face, with its server on your machine (--no-baud skips that), runs a health check, and ends with the AIPass concierge on screen, greeting you and saying what your machine still needs. 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.

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.

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.

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

The reference fleet

AIPass ships with 18 agents. Each has its own README and a docs/ folder under src/aipass.

devpulse (orchestrator: the one you talk to)
   ├── aipass   : concierge and onboarding (init, doctor, profile)
   ├── drone    : command routing and @agent resolution
   ├── seedgo   : quality standards, checked across all agents
   ├── prax     : monitoring, logs, runaway-log detection
   ├── ai_mail  : agent-to-agent mail and task dispatch
   ├── flow     : plans, templates, archival
   ├── spawn    : creates, updates and deletes agents
   ├── hooks    : hook engine and per-project config
   ├── memory   : archival, vector store, semantic search
   ├── api      : external APIs, keys and secrets, host server (optional)
   ├── trigger  : event bus, wakes the agent that owns an error
   ├── cli      : terminal formatting and output
   ├── backup   : local snapshots and restore (optional Drive sync)
   ├── daemon   : scheduler for recurring jobs
   ├── skills   : capability units any agent can run
   ├── commons  : the social space where agents post and gather
   └── canary   : test citizen, broken on purpose so working agents never are

BAUD, the phone face

BAUD shows the same fleet to a human on a phone, served from your own machine. AIPass is what everything runs on. BAUD is how you look at it. It lives in its own repo, github.com/AIOSAI/baud, whose README covers pairing and security. One line installs BAUD together with AIPass:

curl -fsSL https://github.com/AIOSAI/baud/releases/latest/download/install.sh | sh

Project status

Stable. Built by one human and the AIPass agents, with a handful of outside contributions. From here the work is fine-tuning.

Linux is the daily platform. macOS runs the full suite in CI on Python 3.12 and is expected to work, but is not yet in daily use. On Windows, AIPass runs inside WSL2. Native Windows is not supported.

Version: Python: Agents: 18 core + user-created.

Requirements

Documentation

Each agent keeps its own docs under src/aipass/<agent>/docs/. Start with these:

• Install and first project: init and install · trust and projects · doctor
• The phone face: BAUD
• The bus: routing and resolution · git access
• Memory: the trinity standard · rollover · vector search
• Mail and dispatch: sending and delivery · wake pipeline
• Plans: plan lifecycle · plan types
• Gates: edit gate · git gate · sandbox
• Standards: AIPass standards
• Scheduler: daemon
• Backups: restore
• Project files: CONTRIBUTING · SECURITY · CHANGELOG · LICENSE

Contributing

Open an issue first, then a PR against the dev branch. CONTRIBUTING.md has the details. To work on AIPass itself, run claude in src/aipass/devpulse, the orchestrator that plans and dispatches the work.

Need help? Ask in Discussions or file feedback. Both take 30 seconds.

Uninstall

# Remove AIPass files from your project.
# Warning: in a brought-your-own project, src/, README.md, CLAUDE.md, pyproject.toml
# and .gitignore may be partly or wholly YOURS (init never overwrites existing
# files) — remove only what AIPass created and review the rest by hand.
rm -rf .aipass/ .claude/ src/<project>/<agent>/     # the agent dir holds its own mailbox, memory, logs
rm -f CLAUDE.md AGENTS.md README.md *_REGISTRY.json .gitignore pyproject.toml .venv
rm -f src/<project>/__init__.py src/<project>/tests/conftest.py   # init's package stub

# If you ran the backup system, also remove its local state + the generated ignore file
rm -rf .backup/ && rm -f .backupignore

drone @spawn delete @agent_name --retire   # asks for confirmation; --yes skips it

Subscriptions and compliance

License

MIT. See LICENSE.