AIPass/README.md

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
• Quick Start
• Branches
  • Orchestration
  • Core Infrastructure
  • Intelligence & Planning
  • Communication & Events
  • Services
• How It Works
  • Memory
  • Standards
  • Communication
  • Structure
• Compliance & Safety
• Project Status
• Requirements
• License

---

What is AIPass

AIPass (AI Passport) is a multi-agent framework built on Claude Code, with support for OpenAI Codex and Google Gemini CLI. 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. The system is model-agnostic — hooks, identity, and commands work the same across all three CLIs.

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

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

drone systems          # Lists 15 branches + internal modules

Start working

cd src/aipass/devpulse
claude --permission-mode bypassPermissions

Talk to devpulse. It dispatches to specialists and brings results back.

Core commands

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

docker build -t aipass .
docker run -d -p 8080:8080 aipass

Opens a code-server IDE with Python, Node.js, and Claude Code pre-installed. Check docker logs <container> for the generated password.

Inside the container:

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

git clone https://github.com/AIOSAI/AIPass.git
cd AIPass
pip install -e ".[dev]"
./setup.sh

API keys (optional)

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	Orchestration hub — start here. Coordinates all other branches.	README

Core Infrastructure

Branch	Purpose	Docs
drone	CLI router — @name resolution, command dispatch to all branches	README
spawn	Branch lifecycle — create, update, delete, template management	README
cli	Terminal display, formatting, and output services	README
daemon	Background scheduler with cron and plugin system	README

Intelligence & Planning

Branch	Purpose	Docs
memory	Vector memory bank (ChromaDB) — search, archival, rollover	README
flow	Workflow management — FPLANs (execution) and DPLANs (planning)	README
prax	Logging infrastructure, stack introspection, real-time monitoring	README
seedgo	Standards enforcement — 33 automated checks, bypass system	README

Communication & Events

Branch	Purpose	Docs
ai_mail	Inter-agent messaging, dispatch, and wake system	README
trigger	Event-driven automation — 14 event types, watchers	README
commons	Community space — posts, reactions, shared utilities	README

Services

Branch	Purpose	Docs
api	LLM access via OpenRouter (requires API key)	README
backup	Multi-mode backup — snapshot, versioned, Google Drive sync	README
skills	Capability framework for branch skills	README

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:

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:

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/<branch>/
├── .trinity/           # Identity & memory (persists across sessions)
├── .aipass/            # Branch-specific system prompt
├── .ai_mail.local/     # Mailbox (inbox.json, sent/)
├── apps/
│   ├── <branch>.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 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 (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 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.

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.

For per-branch status, see STATUS.md.

Back to contents

---

Requirements

• Python 3.10+
• sudo access (for global CLI symlinks during setup)
• 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