|
|
|
@@ -1,50 +1,59 @@
|
|
|
|
|
[](HERALD.md)
|
|
|
|
|
[](pyproject.toml)
|
|
|
|
|
[](LICENSE)
|
|
|
|
|
[](#cli-support)
|
|
|
|
|
[](https://github.com/AIOSAI/AIPass/issues/new?template=feedback.yml)
|
|
|
|
|
|
|
|
|
|
<!-- TODO: Terminal GIF here — show a dispatch + mail + memory session -->
|
|
|
|
|
|
|
|
|
|
<!-- TODO: Replace with actual AIPass logo when ready -->
|
|
|
|
|
<!-- <p align="center"><img src="docs/logo.png" width="400" alt="AIPass"></p> -->
|
|
|
|
|
|
|
|
|
|
# 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.
|
|
|
|
|
**Your AI agents remember yesterday.**
|
|
|
|
|
|
|
|
|
|
A local multi-agent framework where your AI assistants keep their memory between sessions, work together on the same codebase, and never ask you to re-explain context.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
## Contents
|
|
|
|
|
|
|
|
|
|
- [What is AIPass](#what-is-aipass)
|
|
|
|
|
- [The Problem](#the-problem)
|
|
|
|
|
- [What AIPass Does](#what-aipass-does)
|
|
|
|
|
- [Quick Start](#quick-start)
|
|
|
|
|
- [Branches](#branches)
|
|
|
|
|
- [Orchestration](#orchestration)
|
|
|
|
|
- [Core Infrastructure](#core-infrastructure)
|
|
|
|
|
- [Intelligence & Planning](#intelligence--planning)
|
|
|
|
|
- [Communication & Events](#communication--events)
|
|
|
|
|
- [Services](#services)
|
|
|
|
|
- [What You Can Do](#what-you-can-do)
|
|
|
|
|
- [How It Works](#how-it-works)
|
|
|
|
|
- [Memory](#memory)
|
|
|
|
|
- [Standards](#standards)
|
|
|
|
|
- [Communication](#communication)
|
|
|
|
|
- [Structure](#structure)
|
|
|
|
|
- [Compliance & Safety](#compliance--safety)
|
|
|
|
|
- [Project Status](#project-status)
|
|
|
|
|
- [The 15 Branches](#the-15-branches)
|
|
|
|
|
- [CLI Support](#cli-support)
|
|
|
|
|
- [Platform Support](#platform-support)
|
|
|
|
|
- [CLI Support](#cli-support)
|
|
|
|
|
- [Project Status](#project-status)
|
|
|
|
|
- [Requirements](#requirements)
|
|
|
|
|
- [License](#license)
|
|
|
|
|
- [Subscriptions & Compliance](#subscriptions--compliance)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## What is AIPass
|
|
|
|
|
## The Problem
|
|
|
|
|
|
|
|
|
|
AIPass (**AI Passport**) is a multi-agent framework built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code), with support for [OpenAI Codex](https://github.com/openai/codex) and [Google Gemini CLI](https://github.com/google-gemini/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 supports all three CLIs with shared hooks, identity, and commands — though Claude Code is the most tested and Codex/Gemini integration is newer (S76).
|
|
|
|
|
Your AI has memory now. It remembers your name, your preferences, your last conversation. That used to be the hard part. It isn't anymore.
|
|
|
|
|
|
|
|
|
|
You talk to one agent. It dispatches work to specialists and brings results back. Memory persists across sessions — you never re-explain context.
|
|
|
|
|
The hard part is everything that comes after. You're still one person talking to one agent in one conversation doing one thing at a time. When the task gets complex, *you* become the coordinator — copying context between tools, dispatching work manually, keeping track of who's doing what. You are the glue holding your AI workflow together, and you shouldn't have to be.
|
|
|
|
|
|
|
|
|
|
Multi-agent frameworks tried to solve this. They run agents in parallel, spin up specialists, orchestrate pipelines. But they isolate every agent in its own sandbox. Separate filesystems. Separate worktrees. Separate context. One agent can't see what another just built. Nobody picks up where a teammate left off. Nobody works on the same project at the same time. The agents don't know each other exist.
|
|
|
|
|
|
|
|
|
|
That's not a team. That's a room full of people wearing headphones.
|
|
|
|
|
|
|
|
|
|
What's missing isn't more agents — it's *presence*. Agents that have identity, memory, and expertise. Agents that share a workspace, communicate through their own channels, and collaborate on the same files without stepping on each other. Not isolated workers running in parallel. A persistent society with operational rules — where the system gets smarter over time because every agent remembers, every interaction builds on the last, and nobody starts from zero.
|
|
|
|
|
|
|
|
|
|
## What AIPass Does
|
|
|
|
|
|
|
|
|
|
AIPass gives your AI agents **persistent identity and memory**. Each agent lives in your filesystem, remembers its history, and communicates with other agents through a shared mailbox system. You talk to one orchestrator. It dispatches specialists. Results come back. Context survives.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
You <-> devpulse (orchestrator) <-> 14 specialist branches
|
|
|
|
|
You <-> devpulse (orchestrator) <-> 14 specialist agents
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
**Say "hi" tomorrow and pick up exactly where you left off.**
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -53,290 +62,207 @@ You <-> devpulse (orchestrator) <-> 14 specialist branches
|
|
|
|
|
```bash
|
|
|
|
|
git clone https://github.com/AIOSAI/AIPass.git
|
|
|
|
|
cd AIPass
|
|
|
|
|
./setup.sh
|
|
|
|
|
./setup.sh # Creates venv, installs, bootstraps 15 agents
|
|
|
|
|
drone systems # See all agents
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
> **Note:** setup.sh is tested on Linux. macOS should work but is untested (see [Platform Support](#platform-support)). Windows users should use WSL2.
|
|
|
|
|
|
|
|
|
|
`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 (plus Codex/Gemini hooks if those CLIs are detected), and creates a global `drone` symlink. Idempotent — safe to re-run.
|
|
|
|
|
|
|
|
|
|
### Verify
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
drone systems # Lists 15 branches + internal modules
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Start working
|
|
|
|
|
Then start working:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd src/aipass/devpulse
|
|
|
|
|
claude --permission-mode bypassPermissions
|
|
|
|
|
claude
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
Talk to devpulse. Ask what's happening. Dispatch work. Come back later.
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>Docker setup</summary>
|
|
|
|
|
<summary>Linux (fully tested)</summary>
|
|
|
|
|
|
|
|
|
|
Works out of the box. This is the primary development platform.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
./setup.sh
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>macOS (untested, should work)</summary>
|
|
|
|
|
|
|
|
|
|
setup.sh should work on macOS. Known issue: Apple Silicon Macs may need Homebrew path adjustment for symlinks.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
brew install python@3.10
|
|
|
|
|
./setup.sh
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>Windows</summary>
|
|
|
|
|
|
|
|
|
|
**WSL2 (recommended):** setup.sh runs with zero changes inside WSL2.
|
|
|
|
|
|
|
|
|
|
**Native Windows:** Has been tested on Windows 10 with most functionality working. No setup.ps1 yet — manual setup required.
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>Docker</summary>
|
|
|
|
|
|
|
|
|
|
```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 <container>` 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.
|
|
|
|
|
Opens a code-server IDE with Python, Node.js, and Claude Code pre-installed.
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>Manual dev setup</summary>
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git clone https://github.com/AIOSAI/AIPass.git
|
|
|
|
|
cd AIPass
|
|
|
|
|
pip install -e ".[dev]"
|
|
|
|
|
./setup.sh
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>API keys (optional)</summary>
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
nano ~/.secrets/aipass/.env
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Only needed for the `api` branch (OpenRouter/OpenAI). Everything else works without API keys.
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Branches
|
|
|
|
|
## What You Can Do
|
|
|
|
|
|
|
|
|
|
15 citizen branches, each autonomous with persistent memory. Click any branch name to read its full documentation.
|
|
|
|
|
- **Never re-explain context.** Your agents remember across sessions, days, weeks. Memory persists in `.trinity/` files and rolls over to vector search when full.
|
|
|
|
|
- **Dispatch work to specialists.** Send a task to the right agent. It investigates, builds, tests, and reports back. You don't wait — start something else.
|
|
|
|
|
- **Work in teams on the same files.** 15 agents share one filesystem. No git worktrees isolating them. A planning system prevents conflicts.
|
|
|
|
|
- **Enforce quality automatically.** 33 automated standards checks run across every agent. Code stays consistent at scale.
|
|
|
|
|
- **Use any AI CLI.** Claude Code, Codex, or Gemini CLI. Same hooks, same identity, same commands.
|
|
|
|
|
- **Switch context freely.** Building something complex? Pause it. "Hey, investigate this other thing." Come back when ready.
|
|
|
|
|
- **Scale it your way.** Add agents. Add capabilities. The framework grows with you.
|
|
|
|
|
|
|
|
|
|
### 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) |
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## How It Works
|
|
|
|
|
|
|
|
|
|
### Memory
|
|
|
|
|
|
|
|
|
|
Every branch has `.trinity/` files that persist across sessions:
|
|
|
|
|
Every agent has three things: an **identity** (who it is), **memory** (what it knows), and a **mailbox** (how it communicates).
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
.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/<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
|
|
|
|
|
src/aipass/<agent>/
|
|
|
|
|
├── .trinity/ # Identity + memory (persists across sessions)
|
|
|
|
|
├── .ai_mail.local/ # Mailbox (receives tasks, sends results)
|
|
|
|
|
├── apps/ # What this agent can do
|
|
|
|
|
└── 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.
|
|
|
|
|
You talk to **devpulse** (the orchestrator). It knows every agent's specialty and dispatches work:
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
```bash
|
|
|
|
|
drone @ai_mail dispatch @memory "Archive old sessions" "Find sessions older than 30 days and archive them"
|
|
|
|
|
drone @seedgo audit aipass # Run quality checks on everything
|
|
|
|
|
drone @flow create . "Refactor auth module" # Create a work plan
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Pattern: `drone @branch command [args]` — one line, non-interactive.
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Compliance & Safety
|
|
|
|
|
## The 15 Agents
|
|
|
|
|
|
|
|
|
|
AIPass is built primarily on [Claude Code](https://docs.anthropic.com/en/docs/claude-code), with additional support for [Codex](https://github.com/openai/codex) and [Gemini CLI](https://github.com/google-gemini/gemini-cli). The compliance details below apply specifically to Claude Code usage. Codex and Gemini compliance has not been independently audited.
|
|
|
|
|
|
|
|
|
|
### 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).
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
| Branch | What It Does |
|
|
|
|
|
|--------|-------------|
|
|
|
|
|
| [**devpulse**](src/aipass/devpulse/README.md) | Orchestrator — you talk to this one. It coordinates everyone else. |
|
|
|
|
|
| [**drone**](src/aipass/drone/README.md) | Routes commands to the right branch. The postal service. |
|
|
|
|
|
| [**memory**](src/aipass/memory/README.md) | Long-term storage. Vector search over everything branches have learned. |
|
|
|
|
|
| [**ai_mail**](src/aipass/ai_mail/README.md) | Messaging between branches. Dispatch tasks, get replies. |
|
|
|
|
|
| [**flow**](src/aipass/flow/README.md) | Work plans — tracks what's being built and what's being designed. |
|
|
|
|
|
| [**seedgo**](src/aipass/seedgo/README.md) | Quality enforcement — 33 automated checks across all branches. |
|
|
|
|
|
| [**prax**](src/aipass/prax/README.md) | Monitoring — logs, dashboards, real-time session tracking. |
|
|
|
|
|
| [**trigger**](src/aipass/trigger/README.md) | Event system — things that happen automatically when conditions are met. |
|
|
|
|
|
| [**spawn**](src/aipass/spawn/README.md) | Creates new branches from templates. |
|
|
|
|
|
| [**cli**](src/aipass/cli/README.md) | Terminal formatting and rich output. |
|
|
|
|
|
| [**daemon**](src/aipass/daemon/README.md) | Background scheduler with cron jobs. |
|
|
|
|
|
| [**backup**](src/aipass/backup/README.md) | Snapshots, versioned backups, Google Drive sync. |
|
|
|
|
|
| [**api**](src/aipass/api/README.md) | LLM access via OpenRouter (optional). |
|
|
|
|
|
| [**commons**](src/commons/README.md) | Community space where branches share updates and discuss. |
|
|
|
|
|
| [**skills**](src/skills/README.md) | Reusable capabilities that branches can invoke. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Project Status
|
|
|
|
|
## CLI Support
|
|
|
|
|
|
|
|
|
|
**Beta.** Actively developed. 15 branches, 192+ PRs merged, 4,900+ tests, 100% standards compliance.
|
|
|
|
|
AIPass works with three AI coding CLIs. Claude Code is the most tested.
|
|
|
|
|
|
|
|
|
|
| Metric | Value |
|
|
|
|
|
|--------|-------|
|
|
|
|
|
| Branches | 15 |
|
|
|
|
|
| Standards | 33 |
|
|
|
|
|
| Tests | 4,900+ |
|
|
|
|
|
| PRs merged | 192+ |
|
|
|
|
|
| Compliance | 100% |
|
|
|
|
|
| Sessions | 76 |
|
|
|
|
|
| CLIs supported | 3 (Claude Code, Codex, Gemini) |
|
|
|
|
|
| CLI | Autonomous Mode | Status |
|
|
|
|
|
|-----|----------------|--------|
|
|
|
|
|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude -p "prompt" --permission-mode bypassPermissions` | Fully tested |
|
|
|
|
|
| [Codex](https://github.com/openai/codex) | `codex exec "prompt" --approval-mode never` | Integrated, less tested |
|
|
|
|
|
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini -p "prompt" --approval-mode=yolo` | Integrated, less tested |
|
|
|
|
|
|
|
|
|
|
For detailed progress and session history, see [HERALD.md](HERALD.md).
|
|
|
|
|
setup.sh auto-detects which CLIs are installed and configures hooks for each.
|
|
|
|
|
|
|
|
|
|
For per-branch status, see [STATUS.md](STATUS.md).
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Platform Support
|
|
|
|
|
|
|
|
|
|
| Platform | Status | Notes |
|
|
|
|
|
|----------|--------|-------|
|
|
|
|
|
| **Linux** | Fully tested | Primary development platform. Docker tested. setup.sh, all 15 branches, all 3 CLIs verified. |
|
|
|
|
|
| **Windows (WSL2)** | Expected to work | setup.sh runs in WSL2 with zero changes. Untested but no known blockers. |
|
|
|
|
|
| **Windows (native)** | Partial testing | Tested on Windows 10 — most functionality working. No setup.ps1 yet; manual setup required. |
|
|
|
|
|
| **macOS** | Untested | Should work (bash, Python, Claude Code are native). setup.sh needs minor fix for Apple Silicon Homebrew paths. |
|
|
|
|
|
| Platform | Status |
|
|
|
|
|
|----------|--------|
|
|
|
|
|
| Linux | Fully tested |
|
|
|
|
|
| Windows (WSL2) | Expected to work, zero changes needed |
|
|
|
|
|
| Windows (native) | Partial testing on Windows 10 |
|
|
|
|
|
| macOS | Untested, should work |
|
|
|
|
|
|
|
|
|
|
### CLI Support
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
AIPass supports three AI coding CLIs. Claude Code is the primary and most tested. Codex and Gemini have hooks, skills, and identity integration but less testing.
|
|
|
|
|
## Project Status
|
|
|
|
|
|
|
|
|
|
| CLI | Autonomous Mode | Tested | Notes |
|
|
|
|
|
|-----|----------------|--------|-------|
|
|
|
|
|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude -p "prompt" --permission-mode bypassPermissions` | Fully tested | Primary CLI. Hooks, dispatch, background agents all proven. |
|
|
|
|
|
| [Codex](https://github.com/openai/codex) | `codex exec "prompt" --approval-mode never` | Docker-tested (S75) | Hooks + skills integrated (S76). Background dispatch untested. |
|
|
|
|
|
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini -p "prompt" --approval-mode=yolo` | Docker-tested (S75) | Hooks + skills integrated (S76). Background dispatch untested. |
|
|
|
|
|
**Beta.** Actively developed by a solo developer + AI team.
|
|
|
|
|
|
|
|
|
|
> **Autonomous agent dispatch** (running background agents that do work and report back) is proven with Claude Code. Codex and Gemini have the equivalent flags but this workflow hasn't been tested end-to-end yet.
|
|
|
|
|
| Metric | Value |
|
|
|
|
|
|--------|-------|
|
|
|
|
|
| Agents | 15 |
|
|
|
|
|
| Quality standards | 33 |
|
|
|
|
|
| Tests | 4,900+ |
|
|
|
|
|
| PRs merged | 192+ |
|
|
|
|
|
| Development sessions | 76 |
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
For detailed session history, see [HERALD.md](HERALD.md).
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Requirements
|
|
|
|
|
|
|
|
|
|
- Python 3.10+
|
|
|
|
|
- Linux recommended (macOS should work; Windows via WSL2 or native with manual setup)
|
|
|
|
|
- `sudo` access (for global CLI symlinks during setup)
|
|
|
|
|
- At least one AI coding CLI:
|
|
|
|
|
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (recommended — most tested, hooks provide branch identity, email notifications, auto-diagnostics)
|
|
|
|
|
- [Codex](https://github.com/openai/codex) (alternative — hooks and skills supported, less tested)
|
|
|
|
|
- [Gemini CLI](https://github.com/google-gemini/gemini-cli) (alternative — hooks and skills supported, less tested)
|
|
|
|
|
- API keys optional (only needed for `api` branch — OpenRouter/OpenAI)
|
|
|
|
|
- Linux recommended (macOS should work; Windows via WSL2)
|
|
|
|
|
- At least one AI CLI: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (recommended), [Codex](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
|
|
|
|
|
- `sudo` access (for global CLI symlinks)
|
|
|
|
|
- API keys optional (only for the `api` branch — OpenRouter/OpenAI)
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#table-of-contents">Back to contents</a></p>
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
<details>
|
|
|
|
|
<summary>Subscriptions & Compliance</summary>
|
|
|
|
|
|
|
|
|
|
MIT
|
|
|
|
|
### Use your existing subscription
|
|
|
|
|
|
|
|
|
|
AIPass runs on your **existing CLI subscription** — Claude Pro/Max, Codex, or Gemini. No API keys required for core functionality. No extra costs. Your subscription covers everything.
|
|
|
|
|
|
|
|
|
|
This works because AIPass runs each CLI as an **official subprocess** — the same binary you'd run yourself in a terminal. It doesn't extract credentials, proxy API calls, or intercept tokens. Your subscription stays within the provider's infrastructure at all times.
|
|
|
|
|
|
|
|
|
|
This is different from tools like OpenClaw that were [restricted by Anthropic](https://venturebeat.com/technology/anthropic-cracks-down-on-unauthorized-claude-usage-by-third-party-harnesses) for extracting subscription OAuth tokens and routing workloads outside the official CLI. AIPass doesn't do that — it enhances the CLI through officially supported extension points (hooks, CLAUDE.md, AGENTS.md, GEMINI.md).
|
|
|
|
|
|
|
|
|
|
### 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. Codex and Gemini CLI are open source (Apache 2.0). No provider forbids this usage pattern.
|
|
|
|
|
|
|
|
|
|
> API keys are only needed for the optional `api` agent (OpenRouter/OpenAI). For server/automated deployments, API key authentication is recommended per [Anthropic's guidance](https://code.claude.com/docs/en/legal-and-compliance).
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
AIPass