diff --git a/AGENTS.md b/AGENTS.md index f3a005c0..d174a40b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,11 @@ Your identity and branch context are also injected via hooks on session start an You are a citizen of AIPass. Your `.trinity/passport.json` defines who you are. Read it first — before writing anything, before making decisions. Your role, purpose, and principles are in that file. +## Security + +- NEVER read, access, or reference files in `~/.secrets/` or `/home/patrick/.secrets/`. This directory contains API keys, tokens, and recovery codes. No agent needs to see this. Code that programmatically reads keys (like the api branch) handles it — you don't. +- NEVER output credentials, tokens, or API keys in responses. + ## Key Principles - Code is truth. Running code beats architecture. diff --git a/CLAUDE.md b/CLAUDE.md index 173f95fc..af8ba18c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,21 +1,23 @@ # AIPass -A multi-agent framework where autonomous citizens live in branches and deploy disposable agents to do work. +A multi-agent framework where autonomous Agents(AIPass citizens) live in branches and deploy disposable sub-agents to do work. **User:** Name -# AIPass — Project Prompt - -Project-level instructions. Persists in context for the entire conversation. - -## Startup +# AIPass — Startup protocol On any greeting, silently read these files from CWD and run the commands — no narration, no announcing steps. Just do it and respond with the status. **Read:** `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`, `STATUS.local.md` -**Check:** If `.ai_mail.local/inbox.json` exists, read it. Process any mail — don't ask. +**Check:** If `.ai_mail.local/inbox.json` exists, read it. Process any mail — don't ask, +**list:** `dropbox` files. Ignore README.md **Run:** `git status` +## Security + +- NEVER read, access, or reference files in `~/.secrets/` or `/home/patrick/.secrets/`. This directory contains API keys, tokens, and recovery codes. No agent needs to see this. Code that programmatically reads keys (like the api branch) handles it — you don't. +- NEVER output credentials, tokens, or API keys in responses. + ## Memories -Update `.trinity/` at natural breakpoints, after milestones, and on `/memo`. If compaction hits before you save, it's gone. \ No newline at end of file +Update `.trinity/` at natural breakpoints, after milestones, and on `/memo`. \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md index f3a005c0..d174a40b 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -42,6 +42,11 @@ Your identity and branch context are also injected via hooks on session start an You are a citizen of AIPass. Your `.trinity/passport.json` defines who you are. Read it first — before writing anything, before making decisions. Your role, purpose, and principles are in that file. +## Security + +- NEVER read, access, or reference files in `~/.secrets/` or `/home/patrick/.secrets/`. This directory contains API keys, tokens, and recovery codes. No agent needs to see this. Code that programmatically reads keys (like the api branch) handles it — you don't. +- NEVER output credentials, tokens, or API keys in responses. + ## Key Principles - Code is truth. Running code beats architecture. diff --git a/README.md b/README.md index 9fb382e3..d9006193 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ [![Status](https://img.shields.io/badge/status-beta-yellow)](HERALD.md) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) +[![PyPI](https://img.shields.io/pypi/v/aipass)](https://pypi.org/project/aipass/) [![CLIs](https://img.shields.io/badge/CLIs-Claude%20%7C%20Codex%20%7C%20Gemini-purple)](#cli-support) [![Give Feedback](https://img.shields.io/badge/Give-Feedback-brightgreen)](https://github.com/AIOSAI/AIPass/issues/new?template=feedback.yml) - - - # AIPass **Your AI agents remember yesterday.** @@ -20,11 +18,9 @@ A local multi-agent framework where your AI assistants keep their memory between - [The Problem](#the-problem) - [What AIPass Does](#what-aipass-does) - [Quick Start](#quick-start) -- [What You Can Do](#what-you-can-do) - [How It Works](#how-it-works) - [The 15 Agents](#the-15-agents) - [CLI Support](#cli-support) -- [Platform Support](#platform-support) - [Project Status](#project-status) - [Requirements](#requirements) - [Subscriptions & Compliance](#subscriptions--compliance) @@ -45,14 +41,14 @@ What's missing isn't more agents — it's *presence*. Agents that have identity, ## What AIPass Does -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. +AIPass is a local CLI framework that gives your AI agents **identity, memory, and teamwork**. Verified with Claude Code, Codex, and Gemini CLI. Designed for terminal-native coding agents that support instruction files, hooks, and subprocess invocation. **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 +aipass init ~/Projects/my-saas-app ``` 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. @@ -67,56 +63,26 @@ When one agent isn't enough, use `spawn` to create specialists with the same inf | 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. 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) - ├── drone — command routing + @agent resolution - ├── seedgo — 33 automated quality standards - ├── prax — real-time monitoring across all agents - ├── ai_mail — agent-to-agent communication + task dispatch - ├── flow — plans, workflows, phased coordination - ├── spawn — creates new agents anywhere on your filesystem - ├── memory — vector search across archived context - ├── backup — versioned backups + Google Drive sync - └── ...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. - -**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 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. -- **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. +- **One pattern for everything.** Every agent follows the same structure. One command (`drone @branch command`) reaches any agent. Learn it once, use it everywhere. +- **Projects are isolated by design.** Each project gets its own registry. Agents communicate within their project, not across projects. +- **The system protects itself.** Agent locks prevent double-dispatch. PR locks prevent merge conflicts. Branches don't touch each other's files. Quality standards are embedded in every workflow. Errors trigger self-healing. **Say "hi" tomorrow and pick up exactly where you left off.** One agent or fifteen — the memory persists. -

Back to contents

- --- ## Quick Start +```bash +pip install aipass # Install the package +``` + +Or clone the full framework with all 15 agents: + ```bash git clone https://github.com/AIOSAI/AIPass.git cd AIPass @@ -131,74 +97,30 @@ cd src/aipass/devpulse claude # devpulse reads its memory, knows who it is, picks up where it left off ``` -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. +Say "hi." Here's what that looks like: + +``` +You: hi +devpulse: Hey. Picking up where we left off. + + Status: + - Branch: main, up to date + - Inbox: 1 email from drone — routing fix applied + - Git: 3 files modified, not committed + - Dropbox: 1 item from @api + + Ready when you are. +``` + +Come back tomorrow — it remembers. ```bash -# See the system in action: +# More things you can do: 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 ``` -
-Linux (fully tested) - -Works out of the box. This is the primary development platform. - -```bash -./setup.sh -``` - -
- -
-macOS (untested, should work) - -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 -``` - -
- -
-Windows - -**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. - -
- -
-Docker - -```bash -docker build -t aipass . -docker run -d -p 8080:8080 aipass -``` - -Opens a code-server IDE with Python, Node.js, and Claude Code pre-installed. - -
- ---- - -## What You Can Do - -- **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. -- **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. -- **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. - -

Back to contents

- --- ## How It Works @@ -215,7 +137,11 @@ src/aipass// └── README.md # Domain knowledge (the agent reads this on startup) ``` -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: +Identical layout everywhere. If you know one agent, you know all of them. One command reaches anyone: + +```bash +drone @branch command [args] # Every agent, every task. Drone handles routing. +``` ```bash drone @seedgo audit aipass # Run quality checks on everything @@ -228,7 +154,22 @@ drone @ai_mail dispatch @memory "Archive old sessions" "Find sessions older than - **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. -

Back to contents

+**AIPass ships with 15 specialist agents** that maintain and develop the framework — the reference implementation proving the architecture works at scale: + +``` +devpulse (orchestrator) + ├── drone — command routing + @agent resolution + ├── seedgo — 33 automated quality standards + ├── prax — real-time monitoring across all agents + ├── ai_mail — agent-to-agent communication + task dispatch + ├── flow — plans, workflows, phased coordination + ├── spawn — creates new agents anywhere on your filesystem + ├── memory — vector search across archived context + ├── backup — versioned backups + Google Drive sync + └── ...and 6 more specialists +``` + +These agents work on the **same filesystem, same project, same time** — no sandboxes, no worktrees. This is the pattern your projects inherit. --- @@ -247,6 +188,9 @@ You don't need to memorize this list. Start with `devpulse`, use `drone` to reac | [**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 | +
+See all 15 agents + **Quality and operations** — how the system stays healthy: | Agent | Role | @@ -267,6 +211,8 @@ You don't need to memorize this list. Start with `devpulse`, use `drone` to reac | [**commons**](src/commons/README.md) | Community space for agent updates and discussion | | [**skills**](src/skills/README.md) | Reusable capabilities agents can invoke | +
+ --- ## CLI Support @@ -281,19 +227,6 @@ AIPass works with three AI coding CLIs. Claude Code is the most tested. setup.sh auto-detects which CLIs are installed and configures hooks for each. -

Back to contents

- ---- - -## Platform Support - -| Platform | Status | -|----------|--------| -| Linux | Fully tested | -| Windows (WSL2) | Expected to work, zero changes needed | -| Windows (native) | Partial testing on Windows 10 | -| macOS | Untested, should work | - --- ## Project Status @@ -310,19 +243,15 @@ setup.sh auto-detects which CLIs are installed and configures hooks for each. For detailed session history, see [HERALD.md](HERALD.md). -

Back to contents

- --- ## Requirements - Python 3.10+ -- 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) +- At least one AI CLI: Claude Code (recommended), Codex, or Gemini CLI - `sudo` access (for global CLI symlinks) -- API keys optional (only for the `api` branch — OpenRouter/OpenAI) - -

Back to contents

+- API keys optional (only for the `api` agent — OpenRouter/OpenAI) +- **Platforms:** Linux (fully tested), macOS (untested, should work), Windows via WSL2 --- @@ -331,12 +260,10 @@ For detailed session history, see [HERALD.md](HERALD.md). ### 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. +AIPass runs on your **existing CLI subscription** — Claude Pro/Max, Codex, or Gemini. 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. -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 @@ -344,12 +271,8 @@ This is different from tools like OpenClaw that were [restricted by Anthropic](h - 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. +Claude Code is proprietary but officially supports hooks and subprocess usage. Codex and Gemini CLI are open source (Apache 2.0). > 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). - ---- - -

Back to top

diff --git a/pyproject.toml b/pyproject.toml index 8e05d91d..0fa8f51d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "aipass" version = "2.0.0" -description = "Orchestration framework for autonomous AI agent ecosystems" +description = "A local multi-agent framework where your AI agents keep their memory, work together, and never ask you to re-explain context" readme = "README.md" license = "MIT" requires-python = ">=3.10" @@ -29,7 +29,6 @@ dependencies = [ "rich>=13.0", "watchdog>=3.0", "requests>=2.28", - "openai>=1.0", ] [project.urls] @@ -38,6 +37,9 @@ Repository = "https://github.com/AIOSAI/AIPass" "Bug Tracker" = "https://github.com/AIOSAI/AIPass/issues" [project.optional-dependencies] +llm = [ + "openai>=1.0", +] trinity = [ "trinity-pattern>=1.0.0", ]