AIPass – Persistent agent workspace with identity, memory, and email

Notifications You must be signed in to change notification settings

Fork 20

Star 136

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

970 Commits

970 Commits

.aipass

.aipass

.claude

.claude

.codex

.codex

.github

.github

assets

assets

src/aipass

src/aipass

tests

tests

.AIPASS_REGISTRY.lock

.AIPASS_REGISTRY.lock

.editorconfig

.editorconfig

.env.example

.env.example

.gitattributes

.gitattributes

.gitignore

.gitignore

.gitleaks.toml

.gitleaks.toml

.pre-commit-config.yaml

.pre-commit-config.yaml

AGENTS.md

AGENTS.md

CHANGELOG.md

CHANGELOG.md

CLAUDE.md

CLAUDE.md

CONTRIBUTING.md

CONTRIBUTING.md

Dockerfile.test

Dockerfile.test

LICENSE

LICENSE

README.md

README.md

SECURITY.md

SECURITY.md

codecov.yml

codecov.yml

pyproject.toml

pyproject.toml

pyrightconfig.json

pyrightconfig.json

setup.sh

setup.sh

uv.lock

uv.lock

Repository files navigation

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.

Multi-agent frameworks tried to fix this. But they isolate every agent in its own sandbox. Separate filesystems. Separate context. One agent can't see what another just built. Nobody picks up where a teammate left off.

That's not a team. That's a room full of people wearing headphones.

What AIPass Does

AIPass is a CLI-native scaffold that adds persistent memory, identity, and coordination to your AI agents. You bring your project — AIPass adds the agent layer on top. No UI, no dashboard. You work in your terminal.

pip install aipass mkdir my-project && cd my-project aipass init run

A guided setup creates your project, your first agent, and opens a terminal where that agent is already running. Say "hi" — it knows who it is. Come back tomorrow — it remembers.

This is the base framework. It gives your agents the infrastructure to persist, communicate, and organize — everything else you build on top.

Here's what lands in your project:

my-project/ ├── .aipass/ # Project config + prompts ├── .claude/ # Hooks (injected automatically) ├── src/my_project/ │ └── my-agent/ │ ├── .trinity/ # Identity + memory (3 JSON files) │ ├── .ai_mail.local/ # Local mailbox │ ├── apps/ # Your agent's code │ └── README.md # Domain knowledge ├── CLAUDE.md # Project instructions └── MY-PROJECT_REGISTRY.json

Everything is plain files. No daemon, no hidden state. Delete the directory and it's gone.

Start with one agent. Add more when you need them:

aipass init agent my-agent # Full agent: apps, mail, memory, identity

What makes this different:

Agents are persistent. They remember across sessions. Expertise develops over time. Nobody starts from zero.

Bring your own project. AIPass adds agent infrastructure to whatever you're building. It's a scaffold, not a product — you shape it.

Everything is local. Memory is JSON files. Communication is local mailbox files. No cloud, no external APIs.

Shared workspace. All agents work on the same filesystem, same project, same time. No sandboxes.

One command for everything. AIPass ships with drone, a CLI router — drone @agent command reaches any agent. Learn it once, use it everywhere.

Runs on your existing CLI subscription. Claude Pro/Max or Codex — AIPass uses the same CLI binary you already run. No extra API keys, no extra costs for core functionality.

Quick Start

Your own project

pip install aipass

mkdir my-project && cd my-project aipass init run # Guided setup — project, first agent, terminal handoff

That's it. Your agent has identity, memory, a mailbox, and access to every AIPass service — planning, quality audits, dispatch, real-time monitoring. All through drone @branch command.

aipass init # Just the scaffold (no guided setup) aipass init agent my-agent # Add another agent aipass doctor # Check system health

Need help? Ask in Discussions or file feedback — both take 30 seconds.

Explore the full framework

Clone the repo to see all 13 agents working together — the reference implementation:

git clone https://github.com/AIOSAI/AIPass.git cd AIPass ./setup.sh # Creates venv, installs, bootstraps 13 agents

cd src/aipass/devpulse claude # Talk to the orchestrator

Things you can do:

aipass doctor # Check system health (15+ checks) drone @seedgo audit aipass # Run 36 quality checks across all agents drone @flow create . "Add user auth" # Create a work plan drone @ai_mail dispatch @agent "Sub" "Body" # Send task + wake an agent

How It Works

One agent: Run aipass init run and in 5 minutes you have a project with an agent that reads .trinity/ on startup and picks up where it left off. Memory starts as plain JSON files — no setup required. When they fill up, older entries automatically archive into ChromaDB for long-term search. Nothing is lost.

A team: When one agent isn't enough, every agent shares the same structure:

src/my-project// ├── .trinity/ # Identity + memory (persists across sessions) ├── .ai_mail.local/ # Mailbox (receives tasks, sends results) ├── apps/ # Entry point → modules → handlers └── README.md # Domain knowledge (the agent reads this on startup)

Identical layout everywhere. If you know one agent, you know all of them. drone is the single command that routes to any agent:

drone @branch command [args] # Every agent, every task. Drone handles routing.

drone @seedgo audit my-project # Run quality checks on everything drone @flow create . "Refactor auth module" # Create a work plan drone @ai_mail dispatch @agent "Archive old sessions" "Find sessions older than 30 days"

Two ways to use AIPass:

Your own project: aipass init run sets up a new project with your first agent. Add more agents as you need them. Your first agent is the orchestrator — it coordinates the others.

The full framework: Clone the repo to work with all 13 core agents. Talk to devpulse (the orchestrator), dispatch work across specialists. Agents work in parallel and report back.

The Reference Implementation

AIPass ships with 13 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.

devpulse (orchestrator) ├── aipass — concierge + onboarding (aipass init, doctor, profile) ├── drone — command routing + @agent resolution ├── seedgo — 36 automated quality standards ├── prax — real-time monitoring across all agents ├── ai_mail — agent-to-agent communication + task dispatch ├── flow — plan lifecycle, templates, auto-archival ├── spawn — creates new agents anywhere on your filesystem ├── hooks — hook engine, sound control, per-project config ├── memory — automatic archival, ChromaDB, semantic search ├── api — LLM access layer (OpenRouter, multi-provider) ├── trigger — event-driven automation + self-healing └── cli — terminal formatting and rich output

These agents work on the same filesystem, same project, same time — no sandboxes, no worktrees. This is the pattern your projects inherit.

Agent details

You interact with one: devpulse — the orchestrator. You talk to it, it coordinates everyone else.

Core infrastructure — how agents connect:

Agent Role

aipass Concierge — aipass init, doctor, profile, onboarding

drone Routes drone @branch command to the right agent

ai_mail Agent-to-agent messaging and task dispatch

memory Memory lifecycle — automatic archival, ChromaDB vectors, semantic search

api LLM access layer — multi-provider routing (OpenRouter)

spawn Creates new agents from templates

Quality and operations — how the system stays healthy:

Agent Role

seedgo 36 automated quality standards, enforced across all agents

prax Real-time monitoring, logs, dashboards

flow Plan lifecycle — 6 template types, auto-archival, vector verification

hooks Hook engine — per-project config, sound control, event dispatch

trigger Event-driven automation + self-healing

cli Terminal formatting and rich output

CLI Support

AIPass is built and tested with Claude Code on Linux/WSL.

CLI Autonomous Mode Status

Claude Code claude -p "prompt" --permission-mode bypassPermissions Fully tested

Codex codex exec "prompt" --dangerously-bypass-approvals-and-sandbox Experimental

setup.sh auto-detects which CLIs are installed and configures hooks for each.

Project Status

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

Version 2.4.0

Agents 13 core + user-created

Quality standards 36 automated checks

Tests 8,400+ (across all agents)

PRs merged 600+ (human-AI collaboration)

Each agent documents its own operational status in its branch README — what works, what doesn't, and why.

Requirements

Python 3.10+

Claude Code

Linux, macOS, or WSL (all CI-tested)

sudo access optional (for /usr/local/bin symlinks — falls back to ~/.local/bin without sudo)

API keys optional (OpenRouter/OpenAI — for optional add-on agents)

Roadmap

These items have partial work done and are under ongoing testing:

macOS support — CI green, full test suite passing (#360)

Windows native — CI green, full test suite passing

Codex CLI — hooks and AGENTS.md wired, needs end-to-end testing

Fork contributor workflow — improved error handling for fork-based PRs (#329)

Uninstall

Remove AIPass from a project

AIPass stores everything locally in your project directory. To remove it:

Remove AIPass files from your project

rm -rf .aipass/ .claude/ .ai_mail.local/ hooks/ src/ rm -f CLAUDE.md AGENTS.md STATUS.local.md *_REGISTRY.json .gitignore

If you installed via pip

pip uninstall aipass

No cloud accounts, no external services, no cleanup beyond your local filesystem.

Remove a single agent

Use spawn's delete command to cleanly archive and deregister:

drone @spawn delete @agent_name

This archives the agent's directory and removes it from the registry.

Subscriptions & Compliance

Use your existing subscription

AIPass runs on your existing CLI subscription — Claude Pro/Max or Codex. No API keys required for core functionality. No extra costs beyond your existing subscription.

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.

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 CLI is open source (Apache 2.0).

API keys are only needed for optional add-on agents (OpenRouter/OpenAI). For server/automated deployments, API key authentication is recommended per Anthropic's guidance.

About

Persistent Agent Workspace — AI agents that remember, collaborate, and never start from zero.

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

136 stars

Watchers

1 watching

Forks

20 forks

Report repository

Releases

4 tags

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 99.5%

Shell 0.5%