Install
You need: Python 3.10+, Claude Code on a Claude plan that includes it, and Linux or macOS (Windows through WSL2). Codex and OpenCode if you want them: with a binary on your PATH, install sets it up as another CLI for the same agents, and each agent runs on any of them, your choice per task.
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
-
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 the CLI you chose (claude by default, or codex) 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
-
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
-
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. The save rituals (
/prep, /memo, /compass) are skills under .agents/skills/, one source read by Claude Code, Codex and OpenCode alike.
- Mail and dispatch. Agents send each other tasks and results, and wake whoever they are waiting on, on Claude Code, on Codex (
--provider codex) or on OpenCode (--provider opencode).
- 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. Provider settings (
~/.claude/settings.json, ~/.codex/) change only with the owner's yes.
- 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 the CLI you run (Claude Code, or Codex or OpenCode when a seat runs on it) sends to its own provider, 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:
~/.claude/settings.json — hook wiring, plus env.AIPASS_HOME, env.CLAUDE_CODE_DISABLE_AUTO_MEMORY, env.CLAUDE_CODE_DISABLE_AGENT_VIEW, includeGitInstructions: false, the AIPass deny rules (git write verbs, ~/.secrets reads) and one ask rule (edits under ~/.claude/). Nothing of AIPass changes this file unseen: every write first drops a dated copy under ~/.claude/.backup/settings/ and a line in the receipts.jsonl beside it naming which door wrote; aipass doctor --fix lists the changes with a diff and asks once before writing (--yes for scripts), and the installer's own preflight writes once, with a receipt. Also ~/.claude/commands/memo.md.~/.claude/.backup/settings/ — those dated copies and the receipts ledger.aipass/drone symlinks in /usr/local/bin or ~/.local/bin.- Your shell rc (
.bashrc, .zshrc or .bash_profile) and, on Linux, ~/.profile: an AIPASS_HOME export, a PATH line where the commands went to ~/.local/bin, and the claude() boot-shim function between the AIPass boot shim markers in .bashrc and .zshrc.
~/.aipass/ — cross-project state: the trust registry, commons database, admin key, skills, the BAUD phone face and baud-cli under baud/, the logs of the aipass CLI installed from PyPI under system_logs/ (a clone logs under its own system_logs/ instead), and any Telegram bot state an earlier version left (the Telegram skill is out of the tree).- Your login keyring: one entry per secret under the service
aipass (API keys, Google credentials, the host API's token, pairings and config), in SecretService on Linux, the Keychain on macOS, the Credential Locker on Windows. drone @api secrets migrate imports the files an earlier version kept under ~/.secrets/aipass/ and shreds them; that directory keeps only the host API's write lock and pairing receipts.
git config --global pull.rebase true, set only if install also set your identity.- Only if a
codex binary was on PATH at install: the AIPass Codex hooks are merged into ~/.codex/hooks.json ($CODEX_HOME/hooks.json when set) from , your own rows kept, and four pins (, , , , all ) are set in one line each, every other line kept, after a backup and with a receipt. Run once and choose 'Trust all and continue', or a headless run skips the hooks.
No cloud accounts, no external services — everything to clean up is on your machine.
The reference fleet
[!TIP]
Two of these agents work for you directly.
devpulse is the admin seat. Run claude in src/aipass/devpulse in your AIPass folder (~/AIPass by default) to talk a project through before you create it, solve a problem, or get help with setup. It can dispatch any agent on your machine, your project managers included, and edit files and run git across projects.
aipass is the concierge for the machine itself: setup, updates and installs, and machine problems like a wifi connection that keeps dropping or a fan that never stops. Run claude in src/aipass/aipass.
The other sixteen maintain AIPass, and your agents call their services (mail, plans, memory, gates) without you running them.
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: setup, updates, machine problems (init, doctor)
├── 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
- Python 3.10+
- Claude Code on a Claude plan that includes it (Pro, Max, Team or Enterprise)
- Codex optional: with its binary on PATH, install wires it as a second CLI for the same agents (
/codex and $claude switch a seat between the two)
- OpenCode optional: with its binary on PATH, install adds the AIPass plugin so the same agents run on it (
/opencode from Claude Code, $opencode from Codex, /claude and /codex back); signed out, it runs on OpenCode's free models
- Linux or macOS (both tested in CI). On Windows, use WSL2 and install inside it: AIPass then runs as the Linux program CI tests. Native Windows and Git Bash are not tested in CI; the code keeps its Windows paths but nothing proves them.
sudo access optional (Linux uses it for /usr/local/bin symlinks — falls back to ~/.local/bin without it; macOS never asks)- Node.js + npm optional (on Linux, install uses them to add the
@anthropic-ai/sandbox-runtime kernel sandbox; without them the sandbox is reported as optional and not set up, AIPass runs without it, and aipass doctor says how to add it later; macOS skips the sandbox)
- API keys / OAuth optional (OpenRouter, Google — only for optional add-on integrations)
Documentation
Each agent keeps its own docs under src/aipass/<agent>/docs/. Start with these:
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 from a project
AIPass keeps agent state inside your project directory. To remove it:
# Remove AIPass files from your project.
# Warning: in a brought-your-own project, src/, README.md, AGENTS.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/ .agents/ src/<project>/<agent>/ # the agent dir holds its own mailbox, memory, logs
rm -f 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
.venv in a project is a symlink to the AIPass runtime, not a copy.
Remove AIPass from the machine
The installer also writes a layer outside the project. Remove all of it to erase AIPass completely: every item is listed under What install changes.
Remove a single agent
Use spawn's delete command to cleanly archive and deregister:
drone @spawn delete @agent_name --retire # asks for confirmation; --yes skips it
This copies the agent's directory to .archive/deleted_branches/ (minus .venv, .git, caches), removes it from the registry, then deletes the original. The fleet's own core agents (spawn, drone, devpulse, the registry owner) refuse deletion. Every agent you create is registered, and a plain delete refuses it too: --retire is the door, and the archived copy of its passport records that it was retired.
Subscriptions and compliance
Use your existing subscription
AIPass runs on your existing Claude subscription, any plan that includes Claude Code. No API keys required for core functionality. No extra costs beyond your existing subscription.
This works because AIPass runs Claude Code as an official subprocess — the same binary you'd run yourself in a terminal (a seat on Codex or OpenCode runs the official codex or opencode binary the same way). It doesn't extract credentials, proxy API calls, or intercept tokens. Your subscription stays within the provider's infrastructure at all times.
What AIPass does NOT do
- Extract or redirect subscription OAuth tokens
- Intercept CLI-to-provider communication
- Bypass rate limits or prompt caching
- Impersonate official CLI clients
Claude Code is proprietary but officially supports hooks and subprocess usage.
API keys are only needed for the optional OpenRouter integration (the OpenAI SDK is its transport; nothing calls OpenAI itself). For server/automated deployments, API key authentication is recommended per Anthropic's guidance.
License
MIT. See LICENSE.
