|
|
|
@@ -22,7 +22,7 @@ A local multi-agent framework where your AI assistants keep their memory between
|
|
|
|
|
- [Quick Start](#quick-start)
|
|
|
|
|
- [What You Can Do](#what-you-can-do)
|
|
|
|
|
- [How It Works](#how-it-works)
|
|
|
|
|
- [The 15 Branches](#the-15-branches)
|
|
|
|
|
- [The 15 Agents](#the-15-agents)
|
|
|
|
|
- [CLI Support](#cli-support)
|
|
|
|
|
- [Platform Support](#platform-support)
|
|
|
|
|
- [Project Status](#project-status)
|
|
|
|
@@ -47,27 +47,35 @@ What's missing isn't more agents — it's *presence*. Agents that have identity,
|
|
|
|
|
|
|
|
|
|
AIPass is a local CLI framework that gives your AI agents **identity, memory, and teamwork**. Tested with Claude Code, Codex, and Gemini — built to work with any AI that can read a file and follow a prompt.
|
|
|
|
|
|
|
|
|
|
**Start a project in one command:**
|
|
|
|
|
**Start with one agent that remembers:**
|
|
|
|
|
|
|
|
|
|
Your AI reads `.trinity/` on startup and writes back what it learned before the session ends. That's the whole memory model — JSON files your AI can read and write. Next session, it picks up where it left off. No database, no API, no setup beyond one command.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
aipass init ~/Projects/my-saas-app # coming soon — currently requires dev setup
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Your project gets its own registry, its own identity, and persistent memory. Your AI reads its context on startup, remembers across sessions, and saves what it learns. Each project is isolated — its own agents, its own mail, its own rules. No cross-contamination between projects.
|
|
|
|
|
Your project gets its own registry, its own identity, and persistent memory. Each project is isolated — its own agents, its own rules. No cross-contamination between projects.
|
|
|
|
|
|
|
|
|
|
**Need more than memory? Build a team:**
|
|
|
|
|
**Add teammates when you need them:**
|
|
|
|
|
|
|
|
|
|
Use `spawn` to create full agents with the same infrastructure AIPass itself runs on — communication, monitoring, standards, the whole scaffold. Or keep it lightweight with just memory and identity. Your choice:
|
|
|
|
|
When one agent isn't enough, use `spawn` to create specialists with the same infrastructure AIPass runs on — communication, monitoring, standards, the whole scaffold.
|
|
|
|
|
|
|
|
|
|
| What you need | What to use | What you get |
|
|
|
|
|
|---------------|-------------|-------------|
|
|
|
|
|
| Memory + identity | `aipass init` | Registry, passport, memory files, local prompt |
|
|
|
|
|
| A full agent | `spawn create` | All of the above + apps scaffold, mail, dashboard, tests |
|
|
|
|
|
| A lightweight agent | `spawn passport` | Identity + rich memory (no apps scaffold) |
|
|
|
|
|
| Start here | What to use | What you get |
|
|
|
|
|
|------------|-------------|-------------|
|
|
|
|
|
| One persistent agent | `aipass init` | Registry, passport, memory files, local prompt |
|
|
|
|
|
| A lightweight specialist | `spawn passport` | Identity + rich memory (no apps scaffold) |
|
|
|
|
|
| A full specialist | `spawn create` | All of the above + apps scaffold, mail, dashboard, tests |
|
|
|
|
|
|
|
|
|
|
**How AIPass itself is built:**
|
|
|
|
|
|
|
|
|
|
AIPass ships with 15 specialist agents that maintain and develop the framework. They're the reference implementation — proof that the architecture works at scale:
|
|
|
|
|
AIPass ships with 15 specialist agents that maintain and develop the framework. It looks like a lot — but every agent follows one pattern and needs one command:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
drone @branch command [args] # Every agent, every task. Drone handles routing.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Drone resolves who you're talking to, routes the work, and handles errors. You never need to know where anything lives. Each agent has the same directory layout — learn the pattern once and you know every agent.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
devpulse (orchestrator)
|
|
|
|
@@ -82,16 +90,26 @@ devpulse (orchestrator)
|
|
|
|
|
└── ...and 6 more specialists
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
These 15 agents work on the **same filesystem, same project, same time**. No sandboxes. No worktrees. No isolation. They see each other's work, coordinate through mail, and share a planning system that prevents conflicts. This is the pattern your projects inherit.
|
|
|
|
|
These 15 agents work on the **same filesystem, same project, same time**. No sandboxes. No worktrees. No isolation. They see each other's work, coordinate through mail, and share a planning system that prevents conflicts.
|
|
|
|
|
|
|
|
|
|
**How they stay out of each other's way:**
|
|
|
|
|
|
|
|
|
|
- **Agent locks** — an agent can't run twice simultaneously. Dispatch checks for active locks before waking anyone.
|
|
|
|
|
- **PR locks** — only one agent creates a PR at a time. No merge conflicts from parallel commits.
|
|
|
|
|
- **File isolation** — branches don't touch each other's files. Hard rule, enforced every session.
|
|
|
|
|
- **Standards baked in** — quality checks are embedded in every workflow template. Agents follow them without being told.
|
|
|
|
|
- **Self-healing** — the monitoring system detects errors and can dispatch the offending agent to fix itself.
|
|
|
|
|
|
|
|
|
|
This is the pattern your projects inherit.
|
|
|
|
|
|
|
|
|
|
**What makes this different:**
|
|
|
|
|
|
|
|
|
|
- **Agents are persistent.** They have passports, memories, and expertise that develop over time. They're not disposable workers — they're specialists who remember.
|
|
|
|
|
- **Agents are persistent.** They have memories and expertise that develop over time. They're not disposable workers — they're specialists who remember.
|
|
|
|
|
- **Everything is local.** Your data stays on your machine. Memory is JSON files. Communication is local mailbox files. No cloud dependencies, no external APIs for core operations.
|
|
|
|
|
- **Projects are isolated by design.** Each project gets its own registry. Agents communicate within their project, not across projects. No external agent can accidentally break your system.
|
|
|
|
|
- **You build within the framework, and the framework gives you everything.** Follow the structure and you get memory, monitoring, communication, quality enforcement, backup, and dispatch for free.
|
|
|
|
|
- **Standards are baked into the workflow.** Quality isn't an afterthought — workflow templates inject standards directly into every plan, ensuring agents follow best practices automatically.
|
|
|
|
|
|
|
|
|
|
**Say "hi" tomorrow and pick up exactly where you left off.**
|
|
|
|
|
**Say "hi" tomorrow and pick up exactly where you left off.** One agent or fifteen — the memory persists.
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
@@ -110,10 +128,17 @@ Then start working:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd src/aipass/devpulse
|
|
|
|
|
claude
|
|
|
|
|
claude # devpulse reads its memory, knows who it is, picks up where it left off
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Talk to devpulse. Ask what's happening. Dispatch work. Come back later.
|
|
|
|
|
Say "hi." devpulse reads its identity and memory files, tells you what's been happening, and is ready to dispatch work. Come back tomorrow — it remembers.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# See the system in action:
|
|
|
|
|
drone @seedgo audit aipass # Run 33 quality checks across all agents
|
|
|
|
|
drone @flow create . "Add user auth" # Create a work plan
|
|
|
|
|
drone systems # List every agent and what it does
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>Linux (fully tested)</summary>
|
|
|
|
@@ -165,11 +190,11 @@ Opens a code-server IDE with Python, Node.js, and Claude Code pre-installed.
|
|
|
|
|
|
|
|
|
|
- **Start any project with memory.** `aipass init` gives your AI persistent context — it picks up where you left off, every session, no re-explaining.
|
|
|
|
|
- **Build your own agents.** Use `spawn` to create agents with the same infrastructure AIPass runs on. Full scaffold or lightweight — your call.
|
|
|
|
|
- **Agents work as a team.** Agents within a project share one filesystem, communicate through mail, and coordinate through plans. No sandboxes isolating them.
|
|
|
|
|
- **Dispatch work, don't do it yourself.** Send a task to the right agent — it investigates, builds, tests, and reports back. You keep working on something else.
|
|
|
|
|
- **Enforce quality automatically.** Define standards, run audits across every agent. Code stays consistent at scale.
|
|
|
|
|
- **Use any AI CLI.** Tested with Claude Code, Codex, and Gemini. Same hooks, same identity, same commands. The framework is model-agnostic.
|
|
|
|
|
- **Projects stay isolated.** Each project gets its own registry. Your agents talk to each other, not to other projects' agents. No cross-contamination.
|
|
|
|
|
- **Or work with an agent directly.** `cd src/aipass/memory && claude` — sit down with a specialist one-on-one for complex problems. Direct access is a first-class workflow, not a fallback. The agent has its own memory, its own expertise, and picks up where you left off.
|
|
|
|
|
- **Agents work as a team.** Agents within a project share one filesystem, communicate through mail, and coordinate through plans. No sandboxes isolating them.
|
|
|
|
|
- **Enforce quality automatically.** Standards are embedded in every workflow template. Agents follow them without being told. Code stays consistent at scale.
|
|
|
|
|
- **Use any AI CLI.** Tested with Claude Code, Codex, and Gemini. Same hooks, same identity, same commands.
|
|
|
|
|
- **Scale your way.** One agent with memory, or fifty agents with full infrastructure. The framework grows with your project.
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
@@ -178,25 +203,30 @@ Opens a code-server IDE with Python, Node.js, and Claude Code pre-installed.
|
|
|
|
|
|
|
|
|
|
## How It Works
|
|
|
|
|
|
|
|
|
|
Every agent has three things: an **identity** (who it is), **memory** (what it knows), and a **mailbox** (how it communicates).
|
|
|
|
|
**One agent:** Your AI reads `.trinity/` on startup and writes back what it learned. That's the whole memory model — JSON files on disk. Next session, it picks up where it left off.
|
|
|
|
|
|
|
|
|
|
**A team:** When one agent isn't enough, every agent shares the same structure:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
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
|
|
|
|
|
├── apps/ # Entry point → modules → handlers
|
|
|
|
|
└── README.md # Domain knowledge (the agent reads this on startup)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You talk to **devpulse** (the orchestrator). It knows every agent's specialty and dispatches work:
|
|
|
|
|
Identical layout everywhere. If you know one agent, you know all of them. Communication happens through mail, coordination through plans, and routing through one command:
|
|
|
|
|
|
|
|
|
|
```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
|
|
|
|
|
drone @ai_mail dispatch @memory "Archive old sessions" "Find sessions older than 30 days"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Pattern: `drone @branch command [args]` — one line, non-interactive.
|
|
|
|
|
**Two ways to work:**
|
|
|
|
|
|
|
|
|
|
- **Team mode (most of the time):** Talk to `devpulse`, dispatch work across the team. Agents work in parallel and report back.
|
|
|
|
|
- **Direct mode (for deeper work):** `cd src/aipass/memory && claude` — work one-on-one with a specialist when the problem needs focused domain expertise.
|
|
|
|
|
|
|
|
|
|
<p align="right"><a href="#contents">Back to contents</a></p>
|
|
|
|
|
|
|
|
|
@@ -204,23 +234,38 @@ Pattern: `drone @branch command [args]` — one line, non-interactive.
|
|
|
|
|
|
|
|
|
|
## The 15 Agents
|
|
|
|
|
|
|
|
|
|
| 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. |
|
|
|
|
|
You don't need to memorize this list. Start with `devpulse`, use `drone` to reach any agent, and learn the rest as your workflow expands.
|
|
|
|
|
|
|
|
|
|
**You interact with one:** [**devpulse**](src/aipass/devpulse/README.md) — the orchestrator. You talk to it, it coordinates everyone else.
|
|
|
|
|
|
|
|
|
|
**Core infrastructure** — how agents connect:
|
|
|
|
|
|
|
|
|
|
| Agent | Role |
|
|
|
|
|
|-------|------|
|
|
|
|
|
| [**drone**](src/aipass/drone/README.md) | Routes `drone @branch command` to the right agent |
|
|
|
|
|
| [**ai_mail**](src/aipass/ai_mail/README.md) | Agent-to-agent messaging and task dispatch |
|
|
|
|
|
| [**memory**](src/aipass/memory/README.md) | Long-term vector search across all agent knowledge |
|
|
|
|
|
| [**spawn**](src/aipass/spawn/README.md) | Creates new agents from templates |
|
|
|
|
|
|
|
|
|
|
**Quality and operations** — how the system stays healthy:
|
|
|
|
|
|
|
|
|
|
| Agent | Role |
|
|
|
|
|
|-------|------|
|
|
|
|
|
| [**seedgo**](src/aipass/seedgo/README.md) | 33 automated quality standards, enforced across all agents |
|
|
|
|
|
| [**prax**](src/aipass/prax/README.md) | Real-time monitoring, logs, dashboards |
|
|
|
|
|
| [**flow**](src/aipass/flow/README.md) | Work plans, phased coordination |
|
|
|
|
|
| [**trigger**](src/aipass/trigger/README.md) | Event-driven automation + self-healing |
|
|
|
|
|
|
|
|
|
|
**Support** — everything else:
|
|
|
|
|
|
|
|
|
|
| Agent | Role |
|
|
|
|
|
|-------|------|
|
|
|
|
|
| [**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 for agent updates and discussion |
|
|
|
|
|
| [**skills**](src/skills/README.md) | Reusable capabilities agents can invoke |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -231,7 +276,7 @@ AIPass works with three AI coding CLIs. Claude Code is the most tested.
|
|
|
|
|
| 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 |
|
|
|
|
|
| [Codex](https://github.com/openai/codex) | `codex exec "prompt" --dangerously-bypass-approvals-and-sandbox` | Integrated, less tested |
|
|
|
|
|
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini -p "prompt" --approval-mode=yolo` | Integrated, less tested |
|
|
|
|
|
|
|
|
|
|
setup.sh auto-detects which CLIs are installed and configures hooks for each.
|
|
|
|
@@ -253,15 +298,15 @@ setup.sh auto-detects which CLIs are installed and configures hooks for each.
|
|
|
|
|
|
|
|
|
|
## Project Status
|
|
|
|
|
|
|
|
|
|
**Beta.** Actively developed by a solo developer + AI team.
|
|
|
|
|
**Beta.** Actively developed by a solo developer working with the AI agents themselves — every PR, every test, every fix is human-AI collaboration.
|
|
|
|
|
|
|
|
|
|
| Metric | Value |
|
|
|
|
|
|--------|-------|
|
|
|
|
|
| Agents | 15 |
|
|
|
|
|
| Quality standards | 33 |
|
|
|
|
|
| Tests | 4,900+ |
|
|
|
|
|
| PRs merged | 192+ |
|
|
|
|
|
| Development sessions | 76 |
|
|
|
|
|
| Quality standards | 33 automated checks |
|
|
|
|
|
| Tests | 4,900+ (across all agents) |
|
|
|
|
|
| PRs merged | 192+ (created by agents, reviewed by human) |
|
|
|
|
|
| Development sessions | 78 |
|
|
|
|
|
|
|
|
|
|
For detailed session history, see [HERALD.md](HERALD.md).
|
|
|
|
|
|
|
|
|
|
AIPass