AIPassandClaude Opus 4.6
6f2333ec67
* docs: rewrite README with verified claims + add HERALD.md progress tracker README rewritten and verified against live system: - All commands tested and confirmed working - drone systems shows 23 (15 core + 8 test), documented correctly - seedgo at 33 standards (was incorrectly stated as 34) - Docker setup-workspace.sh fork URL noted - setup.sh sudo requirement documented - prax monitor marked as interactive - Added Standards, Communication, and Structure sections - Removed session tracking (moved to HERALD.md) - Branch table expanded with roles and descriptions HERALD.md: Living progress doc for Patrick to read between sessions. Contains session history, active DPLANs, milestones, known issues. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(install): registry format mismatch + seedgo CLI entry point Bugs found via fresh Docker install test: 1. setup.sh generated AIPASS_REGISTRY.json with branches as dict (keyed by name), but seedgo's discovery.py expected a list of dicts. Result: `drone @seedgo audit aipass` was completely broken on any fresh install. Fix: setup.sh now generates list format (matching existing registry). 2. setup.sh verified `seedgo --help` but seedgo has no CLI entry point — it's only accessible via `drone @seedgo`. Fix: check `drone @seedgo --help` instead, remove broken symlink attempt. 3. seedgo discovery.py now handles both list and dict registry formats defensively (in case old registries exist). 4. README updated to remove seedgo standalone CLI claims. Verified: full fresh install in Docker container — setup.sh completes successfully, drone systems shows 15 branches, seedgo audit runs clean. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
194 lines
7.8 KiB
Markdown
194 lines
7.8 KiB
Markdown
[](pyproject.toml)
|
|
[](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.
|
|
|
|
## Setup
|
|
|
|
### Quick (full setup)
|
|
|
|
```bash
|
|
git clone https://github.com/AIOSAI/AIPass.git
|
|
cd AIPass
|
|
./setup.sh
|
|
```
|
|
|
|
`setup.sh` creates a `.venv`, installs the package in editable mode, generates the branch registry (`AIPASS_REGISTRY.json`), bootstraps `.trinity/` identity files for all 15 branches, copies an `.env` template to `~/.secrets/aipass/.env`, installs Claude Code hooks, and creates a global symlink for `drone` (requires `sudo` — will prompt). Idempotent — safe to re-run.
|
|
|
|
After setup, `drone` is available globally via `/usr/local/bin` symlink. No venv activation needed for CLI use. `seedgo` is accessed via `drone @seedgo`. For development (running tests, importing modules), activate the venv:
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
### Manual (dev)
|
|
|
|
```bash
|
|
git clone https://github.com/AIOSAI/AIPass.git
|
|
cd AIPass
|
|
pip install -e ".[dev]" # Editable install + dev tools
|
|
./setup.sh # Bootstrap registry, identities, hooks
|
|
```
|
|
|
|
### Add your API keys
|
|
|
|
```bash
|
|
nano ~/.secrets/aipass/.env
|
|
```
|
|
|
|
Only needed if using the `api` branch (OpenRouter/OpenAI). Everything else works without API keys.
|
|
|
|
### Verify
|
|
|
|
```bash
|
|
drone systems # Should list 15 core branches + 3 internal modules
|
|
```
|
|
|
|
### Docker
|
|
|
|
```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. Auth is password-based — check `docker logs <container>` for the generated password.
|
|
|
|
Inside the container:
|
|
|
|
```bash
|
|
bash setup-workspace.sh # Clones repo into workspace and installs
|
|
```
|
|
|
|
> **Note:** `setup-workspace.sh` clones from a fork by default. Edit the `FORK` variable in the script to point to your own fork, or change it to the upstream `AIOSAI/AIPass` URL.
|
|
|
|
## Usage
|
|
|
|
Start with devpulse — the orchestration hub:
|
|
|
|
```bash
|
|
cd src/aipass/devpulse
|
|
claude --permission-mode bypassPermissions
|
|
```
|
|
|
|
Talk to it. It dispatches to specialist branches and brings results back. You work with one agent, it coordinates the rest.
|
|
|
|
### Core Commands
|
|
|
|
```bash
|
|
drone @branch --help # Any branch's capabilities
|
|
drone systems # List all branches + modules
|
|
drone @ai_mail dispatch @memory "subject" "body" # Send inter-agent mail + wake target
|
|
drone @seedgo audit aipass # Run standards audit (all branches)
|
|
drone @seedgo audit aipass @branch # Audit a single branch
|
|
drone @flow create . "task name" dplan # Create a planning doc
|
|
drone @flow create . "task name" # Create an execution plan
|
|
drone @git pr "description" # Create PR via drone (atomic workflow)
|
|
drone @git status # Git status scoped to your branch
|
|
drone @prax monitor # Real-time log monitoring (interactive — Ctrl+C to exit)
|
|
```
|
|
|
|
Pattern: `drone @branch command [args]` — single-line, non-interactive.
|
|
|
|
### Branches
|
|
|
|
15 citizen branches, each an autonomous agent with persistent memory:
|
|
|
|
| Branch | Role | What it does |
|
|
|--------|------|-------------|
|
|
| `devpulse` | Manager | Orchestration hub — start here. Coordinates all other branches. |
|
|
| `drone` | Builder | CLI router — resolves `@name` to paths, routes commands to branches |
|
|
| `seedgo` | Builder | Standards enforcement — 33 automated checks, bypass system |
|
|
| `prax` | Builder | Logging infrastructure and real-time monitoring |
|
|
| `cli` | Builder | Terminal display, formatting, and output services |
|
|
| `flow` | Builder | Workflow management — FPLANs (execution) and DPLANs (planning) |
|
|
| `ai_mail` | Builder | Inter-agent messaging, dispatch, and wake system |
|
|
| `spawn` | Builder | Branch lifecycle — create, update, template management |
|
|
| `trigger` | Builder | Event-driven automation — 12 event types |
|
|
| `api` | Builder | LLM access via OpenRouter (requires API key) |
|
|
| `backup` | Builder | Multi-mode backup — snapshot, versioned, Google Drive |
|
|
| `daemon` | Builder | Background scheduler with plugin system |
|
|
| `memory` | Builder | Vector memory bank (ChromaDB) — search, archival |
|
|
| `commons` | Builder | Social space — posts, reactions, community features |
|
|
| `skills` | Builder | Capability framework for branch skills |
|
|
|
|
## 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 the `@memory` branch (ChromaDB vectors). Nothing is lost.
|
|
|
|
### Standards
|
|
|
|
Every branch is held to 33 automated standards checks via `seedgo`:
|
|
|
|
```bash
|
|
drone @seedgo audit aipass # Full system audit
|
|
drone @seedgo audit aipass @api # Single branch
|
|
drone @seedgo checklist apps/module.py # Quick check on a file
|
|
```
|
|
|
|
Standards cover: architecture, CLI patterns, error handling, imports, logging, naming, test quality, documentation, and more. Branches can add justified bypasses in `.seedgo/bypass.json`.
|
|
|
|
### Structure
|
|
|
|
```
|
|
src/aipass/<branch>/
|
|
├── .trinity/ # Identity & memory (persists across sessions)
|
|
├── .aipass/ # Branch-specific system prompt
|
|
├── .ai_mail.local/ # Mailbox (inbox.json, sent/)
|
|
├── .seedgo/ # Standards bypass config
|
|
├── .claude/ # Claude Code settings (deny rules, permissions)
|
|
├── apps/
|
|
│ ├── <branch>.py # Entry point (handle_command, introspection)
|
|
│ ├── modules/ # Business logic / orchestration
|
|
│ └── handlers/ # Implementation details
|
|
├── tests/ # Branch test suite
|
|
├── logs/ # Prax log output
|
|
└── README.md
|
|
```
|
|
|
|
All branches follow this layout. `drone` resolves `@name` to filesystem paths via `AIPASS_REGISTRY.json`.
|
|
|
|
### Communication
|
|
|
|
Branches communicate via `ai_mail` — an internal messaging system:
|
|
|
|
```bash
|
|
drone @ai_mail dispatch @target "Subject" "Body" # Send + wake target branch
|
|
drone @ai_mail email @target "Subject" "Body" # Send without waking (FYI only)
|
|
drone @ai_mail inbox # Check your inbox
|
|
```
|
|
|
|
Dispatch sends a message AND wakes the target branch (starts a Claude session in their directory). This is how devpulse coordinates work across the system.
|
|
|
|
### No Isolation
|
|
|
|
All 15 branches share the same filesystem and git repo. Each owns its directory and doesn't touch others. A PR lockfile prevents concurrent git operations. Standards enforcement keeps things consistent.
|
|
|
|
Git workflow is atomic via `drone @git pr` — one command handles: lock acquisition, branch creation, scoped staging, commit, push, PR creation, return to main, and lock release.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.10+
|
|
- `sudo` access (for global CLI symlinks during setup)
|
|
- API keys optional (only needed for `api` branch — OpenRouter/OpenAI)
|
|
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) recommended (hooks provide branch identity, email notifications, auto-diagnostics)
|
|
|
|
## Status
|
|
|
|
Beta. 15 branches. 137 PRs merged. 2,000+ tests. 100% compliance across 33 standards. See [HERALD.md](HERALD.md) for detailed progress and session history.
|
|
|
|
## License
|
|
|
|
MIT
|