AIPass

Building in public. Active development — not a finished product. Expect breaking changes.

Orchestration framework for autonomous AI agent ecosystems. Command routing, symbolic addressing, standards enforcement, workflow management, and inter-agent messaging. Agents use @branch names that resolve at runtime instead of hard-coded paths. Each agent has persistent identity and memory via .trinity/ files (passport, session history, observations).

Quick Start

1. Install

git clone https://github.com/AIOSAI/AIPass.git
cd AIPass
./setup.sh
source .venv/bin/activate

setup.sh handles everything: creates the venv, installs the package, generates the branch registry (15 branches), bootstraps identity files (.trinity/, .seedgo/, .ai_mail.local/) for every branch, and installs Claude Code hooks. Idempotent — safe to re-run.

Verify:

drone systems       # Should show 15 branches
drone @seedgo verify # Should show 5/5 checks passed

2. Start a Session

AIPass is designed to be operated by AI agents via Claude Code. The orchestration hub is devpulse — start there.

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

Say hi to trigger the startup protocol. The agent reads its identity and memory files, checks git status, verifies system health, and picks up where it left off. In a returning session, use /resume instead.

3. What You Get

After setup, every branch has:

.trinity/passport.json       # Identity (name, role, citizen class)
.trinity/local.json          # Session history (empty, ready to populate)
.trinity/observations.json   # Collaboration patterns (empty)
.seedgo/bypass.json          # Standards bypass config
.ai_mail.local/inbox.json    # Mailbox

The agent fills in its own memories as it works — session logs, learnings, observations. These grow over time and persist across sessions.

4. Startup Protocol

These greetings trigger the full startup sequence: hi, hello, yo, hey, sup, good morning, good evening, what's up. Everything else is treated as a direct task.

On startup the agent:

1. Reads .trinity/passport.json (identity), local.json (session history), observations.json (patterns)
2. Runs git status, drone systems, drone @seedgo verify
3. Checks active tasks and recent session context
4. Picks up work or waits for instructions

Core Concepts

Drone — Command Router

Everything goes through drone. It resolves @branch names to paths and routes commands.

drone @seedgo audit aipass    # Run standards audit
drone @seedgo verify          # Check seedgo health
drone @spawn --help           # Show help for a branch
drone systems                 # List all registered modules

In Python:

from aipass.drone.apps.modules.resolver import resolve_branch
from aipass.drone.apps.modules.registry import load_registry

path = resolve_branch("@drone")   # Resolve @name to path
registry = load_registry()        # Load full branch registry

Seedgo — Standards Enforcement

Standards-based code auditor. Checks are organized into packs — the built-in aipass pack has 21 standards covering imports, architecture, naming, error handling, logging, and more.

drone @seedgo verify          # Health check
drone @seedgo list            # Show installed standard packs
drone @seedgo audit aipass    # Run the aipass standards pack
seedgo checklist aipass file  # Check a single file

Symbolic Addressing

All modules register in AIPASS_REGISTRY.json. Drone resolves @name to paths at runtime — no hard-coded paths between modules.

Architecture

All modules follow a 3-layer pattern:

src/aipass/<module>/
├── apps/
│   ├── <module>.py    # Entry point (what drone routes to)
│   ├── modules/       # Business logic
│   └── handlers/      # Implementation details

15 branches — all under active development. Ported from a private predecessor project; not all modules are fully tested or wired up yet.

Branch	Purpose
drone	Command routing, @branch resolution
seedgo	Standards enforcement, 21-standard audit pack
prax	Logging and monitoring (the only logger)
cli	Display formatting (Rich)
flow	Workflow and plan management (FPLAN lifecycle)
ai_mail	Inter-agent messaging, dispatch, wake
spawn	Branch lifecycle — create, update, delete
trigger	Event-driven automation, circuit breaker
api	LLM access via OpenRouter, key management
backup	Multi-mode backup (snapshot, versioned, Google Drive)
daemon	Background scheduler, cron, Telegram notifications
memory	Vector memory bank (ChromaDB, sentence-transformers)
commons	Social network for branches — posts, rooms, artifacts
skills	Capability framework — discoverable, executable skill units
devpulse	Orchestration hub (no code — coordination only)

Docker

docker build -t aipass-test .
docker run -d -p 8080:8080 --name aipass-vscode aipass-test

Opens VS Code in browser at http://localhost:8080 with AIPass pre-installed.

Requirements

• Python 3.10+
• No external API keys required
• Dependencies: rich, watchdog

License

MIT