[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) # AIPass A multi-agent operating system where AI agents live as citizens in a shared filesystem. Persistent memory, inter-agent messaging, standards enforcement, and CLI routing — no cloud required. --- ## Table of Contents - [What is AIPass](#what-is-aipass) - [Quick Start](#quick-start) - [Branches](#branches) - [Orchestration](#orchestration) - [Core Infrastructure](#core-infrastructure) - [Intelligence & Planning](#intelligence--planning) - [Communication & Events](#communication--events) - [Services](#services) - [How It Works](#how-it-works) - [Memory](#memory) - [Standards](#standards) - [Communication](#communication) - [Structure](#structure) - [Compliance & Safety](#compliance--safety) - [Project Status](#project-status) - [Requirements](#requirements) - [License](#license) --- ## What is AIPass AIPass (**AI Passport**) is a multi-agent framework built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Each agent is a **citizen** — it has an identity (passport), persistent memory, a mailbox, and the ability to communicate with other agents. Citizens live in **branches** (directories), each specializing in a domain. One orchestrator coordinates them all. You talk to one agent. It dispatches work to specialists and brings results back. Memory persists across sessions — you never re-explain context. ``` You <-> devpulse (orchestrator) <-> 14 specialist branches ```

Back to contents

--- ## Quick Start ```bash git clone https://github.com/AIOSAI/AIPass.git cd AIPass ./setup.sh ``` `setup.sh` creates a `.venv`, installs the package, generates the branch registry, bootstraps identity files for all 15 branches, copies an `.env` template, installs Claude Code hooks, and creates a global `drone` symlink. Idempotent — safe to re-run. ### Verify ```bash drone systems # Lists 15 branches + internal modules ``` ### Start working ```bash cd src/aipass/devpulse claude --permission-mode bypassPermissions ``` Talk to devpulse. It dispatches to specialists and brings results back. ### Core commands ```bash drone @branch --help # Any branch's capabilities drone systems # List all branches drone @ai_mail dispatch @memory "subject" "body" # Send mail + wake target drone @seedgo audit aipass # Full standards audit drone @flow create . "task name" dplan # Create a planning doc drone @git pr "description" # Atomic PR workflow ``` Pattern: `drone @branch command [args]` — single-line, non-interactive.
Docker setup ```bash docker build -t aipass . docker run -d -p 8080:8080 aipass ``` Opens a [code-server](https://github.com/coder/code-server) IDE with Python, Node.js, and Claude Code pre-installed. Check `docker logs ` for the generated password. Inside the container: ```bash bash setup-workspace.sh # Clones repo into workspace and installs ``` > `setup-workspace.sh` clones from a fork by default. Edit the `FORK` variable to point to your own.
Manual dev setup ```bash git clone https://github.com/AIOSAI/AIPass.git cd AIPass pip install -e ".[dev]" ./setup.sh ```
API keys (optional) ```bash nano ~/.secrets/aipass/.env ``` Only needed for the `api` branch (OpenRouter/OpenAI). Everything else works without API keys.

Back to contents

--- ## Branches 15 citizen branches, each autonomous with persistent memory. Click any branch name to read its full documentation. ### Orchestration | Branch | Purpose | Docs | |--------|---------|------| | [**devpulse**](src/aipass/devpulse/) | Orchestration hub — start here. Coordinates all other branches. | [README](src/aipass/devpulse/README.md) | ### Core Infrastructure | Branch | Purpose | Docs | |--------|---------|------| | [**drone**](src/aipass/drone/) | CLI router — `@name` resolution, command dispatch to all branches | [README](src/aipass/drone/README.md) | | [**spawn**](src/aipass/spawn/) | Branch lifecycle — create, update, delete, template management | [README](src/aipass/spawn/README.md) | | [**cli**](src/aipass/cli/) | Terminal display, formatting, and output services | [README](src/aipass/cli/README.md) | | [**daemon**](src/aipass/daemon/) | Background scheduler with cron and plugin system | [README](src/aipass/daemon/README.md) | ### Intelligence & Planning | Branch | Purpose | Docs | |--------|---------|------| | [**memory**](src/aipass/memory/) | Vector memory bank (ChromaDB) — search, archival, rollover | [README](src/aipass/memory/README.md) | | [**flow**](src/aipass/flow/) | Workflow management — FPLANs (execution) and DPLANs (planning) | [README](src/aipass/flow/README.md) | | [**prax**](src/aipass/prax/) | Logging infrastructure, stack introspection, real-time monitoring | [README](src/aipass/prax/README.md) | | [**seedgo**](src/aipass/seedgo/) | Standards enforcement — 33 automated checks, bypass system | [README](src/aipass/seedgo/README.md) | ### Communication & Events | Branch | Purpose | Docs | |--------|---------|------| | [**ai_mail**](src/aipass/ai_mail/) | Inter-agent messaging, dispatch, and wake system | [README](src/aipass/ai_mail/README.md) | | [**trigger**](src/aipass/trigger/) | Event-driven automation — 14 event types, watchers | [README](src/aipass/trigger/README.md) | | [**commons**](src/commons/) | Community space — posts, reactions, shared utilities | [README](src/commons/README.md) | ### Services | Branch | Purpose | Docs | |--------|---------|------| | [**api**](src/aipass/api/) | LLM access via OpenRouter (requires API key) | [README](src/aipass/api/README.md) | | [**backup**](src/aipass/backup/) | Multi-mode backup — snapshot, versioned, Google Drive sync | [README](src/aipass/backup/README.md) | | [**skills**](src/skills/) | Capability framework for branch skills | [README](src/skills/README.md) |

Back to contents

--- ## How It Works ### Memory Every branch has `.trinity/` files that persist across sessions: ``` .trinity/passport.json # Identity — role, purpose, principles .trinity/local.json # Session history — tasks, learnings, key insights .trinity/observations.json # Collaboration patterns observed over time ``` New session starts, branch reads its memories, picks up where it left off. When local files reach capacity, they roll over into `@memory` (ChromaDB vectors). Nothing is lost. ### Standards Every branch is held to 33 automated standards via `seedgo`: ```bash drone @seedgo audit aipass # Full system audit drone @seedgo audit aipass @api # Single branch ``` Standards cover: architecture, CLI patterns, error handling, imports, logging, naming, test quality, documentation, and more. Branches add justified bypasses in `.seedgo/bypass.json`. ### Communication Branches communicate via `ai_mail` — an internal messaging system: ```bash drone @ai_mail dispatch @target "Subject" "Body" # Send + wake target drone @ai_mail email @target "Subject" "Body" # Send without waking drone @ai_mail inbox # Check your inbox ``` Dispatch sends a message AND wakes the target branch (starts a Claude Code session in their directory). This is how devpulse coordinates work across the system. ### Structure ``` src/aipass// ├── .trinity/ # Identity & memory (persists across sessions) ├── .aipass/ # Branch-specific system prompt ├── .ai_mail.local/ # Mailbox (inbox.json, sent/) ├── apps/ │ ├── .py # Entry point │ ├── modules/ # Business logic │ └── handlers/ # Implementation details ├── tests/ # Branch test suite └── README.md ``` All 15 branches share the same filesystem and git repo. Each owns its directory. A PR lockfile prevents concurrent git operations. Standards enforcement keeps things consistent.

Back to contents

--- ## Compliance & Safety AIPass is built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and operates fully within Anthropic's usage policies. ### How AIPass uses Claude Code - Every agent session runs the **official `claude` CLI binary** (`claude -p`) as a genuine subprocess - Context is injected via [Claude Code hooks](https://code.claude.com/docs/en/hooks) (`settings.json`) and `CLAUDE.md` files — both officially supported, documented features - Each branch agent runs as an **independent Claude Code process** with its own working directory - No OAuth tokens are extracted, intercepted, or routed through third-party clients - No API calls are made to Anthropic outside the official CLI - Claude Code's built-in prompt caching and rate limiting are fully preserved ### What AIPass does NOT do - **No credential wrapping** — we don't extract or redirect subscription OAuth tokens - **No API proxying** — we don't intercept communication between Claude Code and Anthropic's servers - **No harness impersonation** — we don't spoof the Claude Code client identity - **No rate limit bypass** — each session respects Anthropic's built-in limits ### Why this matters As of April 2026, Anthropic [enforces restrictions](https://venturebeat.com/technology/anthropic-cracks-down-on-unauthorized-claude-usage-by-third-party-harnesses) on third-party tools that extract subscription credentials to route automated workloads outside the official CLI. Tools like OpenClaw bypass Claude Code's prompt caching optimizations, creating unsustainable compute costs. AIPass is architecturally different: it enhances Claude Code through its own extension points (hooks, CLAUDE.md, settings.json) rather than replacing or bypassing it. Your subscription credentials stay within Anthropic's infrastructure at all times. > **Using AIPass with your Claude Pro, Max, Team, or Enterprise subscription is compliant with Anthropic's terms.** For server/automated deployments, API key authentication is recommended per [Anthropic's guidance](https://code.claude.com/docs/en/legal-and-compliance).

Back to contents

--- ## Project Status **Beta.** Actively developed. 15 branches, 180+ PRs merged, 4,800+ tests, 100% standards compliance. | Metric | Value | |--------|-------| | Branches | 15 | | Standards | 33 | | Tests | 4,800+ | | PRs merged | 180+ | | Compliance | 100% | | Sessions | 73 | For detailed progress and session history, see [HERALD.md](HERALD.md). For per-branch status, see [STATUS.md](STATUS.md).

Back to contents

--- ## Requirements - Python 3.10+ - `sudo` access (for global CLI symlinks during setup) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (hooks provide branch identity, email notifications, auto-diagnostics) - API keys optional (only needed for `api` branch — OpenRouter/OpenAI)

Back to contents

--- ## License MIT ---

Back to top