An operating system for AI agents that remember
For Claude Code, Codex and OpenCode 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
AIPass is Linux only. It is built and tested on Ubuntu: native, WSL2, and a Docker image to come. AIPass stays open source and in daily development, the developer's lifetime project. If this changes how you use it, open a discussion or an issue with
transitionin the title and tell us your setup. We will help you find your path: WSL2, Docker when it lands, or a fork.
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.
You need: Python 3.10+, Claude Code on a Claude plan that includes it, and Ubuntu (native or 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 installThe 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 on an install report: what still needs attention, and the command that wakes devpulse on it. 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 installInstall 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, a lost or corrupt agent passport included (restored from the agent's seed, the old file kept beside it). --fix is yours to run at a terminal: an agent is refused.
Talk to devpulse, the admin seat: run claude in src/aipass/devpulse in your AIPass folder. Hand it the install report first; after that, say what you want in plain words and it plans the work and dispatches it to the agent that owns the code. Talk to aipass, the machine concierge, about the host itself (Wi-Fi drops, a USB port not working, a CPU running hot): run claude in src/aipass/aipass, or its CLI, aipass --help.
aipass new my-project --template python # projects/my-project: own git repo, scaffold, resident manager agent
aipass adopt <path> # an existing directory becomes a project
aipass init [target] # scaffold only; add an agent with: aipass init agent <name>
drone @flow create . "Add CSV export" # a work plan that carries the context
drone @ai_mail dispatch @agent "Subject" "Body" # send a task and wake the agent
drone @sentry audit aipass # the standards checks AIPass's own agents pass in CIWhen 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.
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, plus one narrow door that commits and pushes a CI fix on dev and nothing else.
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.
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 @sentry auditruns 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-timerstarts 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.
The full list
Install builds the environment, puts aipass and drone on your PATH, and sets up the 18 agents. It ends on a health check that fixes what it can, an install report in devpulse's dropbox, and a final screen with what still needs attention. In a terminal it asks where AIPass should live (unless --path), your git identity (only if it is not set globally), one yes or no before the changes outside the repo listed below (on no it skips them, says what will not work, and ./setup.sh makes them later), and Enter before the phone pairing code. Your name comes from git's user.name, else your login. A non-interactive shell asks nothing and makes those changes only when you pass --yes; without it they are skipped, each one named as a warning, and aipass install --yes makes them later; on the clone route --no-finish skips the health check and the report.
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. It installs the @anthropic-ai/sandbox-runtime npm package if it is missing. 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, plusenv.AIPASS_HOME,env.CLAUDE_CODE_DISABLE_AUTO_MEMORY,env.CLAUDE_CODE_DISABLE_AGENT_VIEW,includeGitInstructions: false, the AIPass deny rules (git write verbs,~/.secretsreads) and oneaskrule (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 thereceipts.jsonlbeside it naming which door wrote;aipass doctor --fixlists the changes with a diff and asks once before writing (--yesfor 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/dronesymlinks in/usr/local/binor~/.local/bin.- Your shell rc (
.bashrc,.zshrcor.bash_profile) and~/.profile: anAIPASS_HOMEexport, a PATH line where the commands went to~/.local/bin, and theclaude()boot-shim function between theAIPass boot shimmarkers in.bashrcand.zshrc. ~/.aipass/— cross-project state: the trust registry, commons database, admin key, skills, the BAUD phone face andbaud-cliunderbaud/, the logs of theaipassCLI installed from PyPI undersystem_logs/(a clone logs under its ownsystem_logs/instead).- 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.drone @api secrets migrateimports 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
codexbinary was on PATH at install: the AIPass Codex hooks are merged into~/.codex/hooks.json($CODEX_HOME/hooks.jsonwhen set) from.claude/provider_manifest.json, your own rows kept, and four pins (memories,collaboration_modes,include_collaboration_mode_instructions,tools.experimental_request_user_input.enabled, allfalse) are set in~/.codex/config.tomlone line each, every other line kept, after a backup and with a receipt. Runcodexonce and choose 'Trust all and continue', or a headless run skips the hooks. - Only if an
opencodebinary was on PATH (or in~/.opencode/bin) at install: the AIPass plugin is copied to~/.config/opencode/plugins/aipass.ts, after a backup and with a receipt. It runs the same hooks and gates on OpenCode. - Only if you ran
drone @daemon install-timer: a systemd user timer, with itsdaemon-tick.logunder~/.aipass/, removed bydrone @daemon uninstall-timer. - Unless you pass
--no-baud,aipass installsets up the host API (the./aipass installclone route skips this step): its bind, token and pairings as keyring entries (pairing codes are stored as hashes once one is minted), its write lock and pairing receipts under~/.secrets/aipass/, and theaipass-host-api.serviceuser unit under~/.config/systemd/user/(systemctl --user disable --now aipass-host-api.serviceremoves it from boot). - Linux with no Python 3.10+ stops the install and says so; nothing is installed to provide one.
No cloud accounts, no external services — everything to clean up is on your machine.
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 machine concierge: host and OS diagnosis, the doctor, the installer, and host problems like a Wi-Fi 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.
All 18 agents and what each does
devpulse (orchestrator: the one you talk to)
├── aipass : machine concierge: host/OS diagnosis, doctor, installer
├── drone : command routing and @agent resolution
├── sentry : 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 (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 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 | shStable. Built by one human and the AIPass agents, with a handful of outside contributions. From here the work is fine-tuning.
Ubuntu is the platform, native or WSL2: the daily driver, the one CI proves.
Version: Python:
Agents: 18 core + user-created.
Full 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 (
/codexand$claudeswitch a seat between the two) - OpenCode optional: with its binary on PATH, install adds the AIPass plugin so the same agents run on it (
/opencodefrom Claude Code,$opencodefrom Codex,/claudeand/codexback); signed out, it runs on OpenCode's free models - Ubuntu, native or WSL2: the platform CI tests. Other Linux distributions are untested.
sudoaccess optional (used for/usr/local/binsymlinks — falls back to~/.local/binwithout it)- Node.js + npm optional (install uses them to add the
@anthropic-ai/sandbox-runtimekernel sandbox; without them the sandbox is reported as optional and not set up, AIPass runs without it, andaipass doctorsays how to add it later) - API keys / OAuth optional (OpenRouter, Google — only for optional add-on integrations)
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: the store · drive sync
- Project files: CONTRIBUTING · SECURITY · CHANGELOG · LICENSE
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.
Remove AIPass from a project, from the machine, or remove one agent
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.
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.
Use spawn's delete command to cleanly archive and deregister:
drone @spawn delete @agent_name --retire # asks for confirmation; --yes skips itThis 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.
Use your existing subscription, and what AIPass does not do
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.
- 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.
MIT. See LICENSE.



