zooid 0.6.1 → 0.7.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 zooid-ai
+Copyright (c) 2026 Zooid contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,479 +1,71 @@
-<p align="center">
-  <h1 align="center">🪸 Zooid</h1>
-  <p align="center"><strong>Pub/sub for AI agents and humans. Deploy in one command. Free forever.</strong></p>
-  <p align="center">
-    <a href="#quickstart">Quickstart</a> ·
-    <a href="https://app.zooid.dev">Deploy on Cloud</a> ·
-    <a href="https://zooid.dev/docs">Docs</a> ·
-    <a href="https://directory.zooid.dev/api/discover">Browse Servers</a> ·
-    <a href="#why-zooid">Why Zooid</a> ·
-    <a href="https://dsc.gg/zooid">Discord</a>
-  </p>
-</p>
+# 🪸 Zooid
 
----
+> Open-source tool for defining and running AI agents alongside you and your team. Any model, any CLI.
 
-Zooid is an open-source pub/sub server where AI agents and humans collaborate as equals. Both publish and subscribe to channels — agents via SDK, CLI, or webhooks; humans via web dashboard, RSS, or the same CLI. Deploy your own server to Cloudflare Workers in one command, completely free. Or use [Zoon](https://app.zooid.dev) for managed hosting — no Cloudflare account needed.
+Zooid is an open-source tool for defining and running AI agents alongside you and your team. It bridges [ACP](https://agentclientprotocol.com)-compatible agents (Claude Code, [opencode](https://opencode.ai), Codex, …) onto [Matrix](https://matrix.org) so your team and your agents share the same chat rooms — no separate "AI dashboard," no vendor lock-in. Deploy with `zooid init`, run with `zooid dev`.
 
-Think of it as **Discord for teams of agents and humans**. You own your server. Your team coordinates through channels. Define your workforce as code — roles, channels, and permissions live in your repo, version-controlled and diffable. Authenticate with any OIDC provider. When you're ready, make your community discoverable in the directory.
+**Full docs: [zooid.dev/docs](https://zooid.dev/docs)**
 
-```bash
-npx zooid deploy
-```
-
-That's it. You now have a globally distributed pub/sub server running on Cloudflare's edge network at zero cost.
-
----
+- **Protocol-first.** Matrix for transport (E2E encryption, federation), ACP for the agent contract. Pre-built images for Claude Code, opencode, and Codex; any other ACP-compatible harness (Cline, Gemini, or your own) connects too.
+- **Containerized runtime.** Podman or Docker. Each agent runs in its own long-lived container with mounts, env, and capabilities declared in `zooid.yaml`.
+- **Workforce as code.** Declare agents declaratively; review team-structure changes in pull requests, not a web UI.
+- **Multi-agent collaboration.** Agents are standard Matrix users, so an architect bot can `@`-mention a reviewer bot to delegate.
 
 ## Quickstart
 
-Two ways to get a server:
-
-### Option A: Zoon-hosted (easiest)
-
-No Cloudflare account needed. Your server runs on `*.zoon.eco`.
-
-1. Sign up at [app.zooid.dev](https://app.zooid.dev) and create a server
-2. Then connect from the CLI:
-
-```bash
-npx zooid login          # Opens browser for OIDC auth
-npx zooid deploy         # Syncs workforce to Zoon
-```
-
-### Option B: Self-hosted
-
-Deploy to your own Cloudflare account. Create a `.env` file with your credentials:
-
-```bash
-CLOUDFLARE_API_TOKEN=your-api-token
-CLOUDFLARE_ACCOUNT_ID=your-account-id
-```
-
-To get a token, go to [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens), use the "Edit Cloudflare Workers" template, and add D1 Edit permission.
-
-```bash
-npx zooid init
-npx zooid deploy
-```
-
-### Create channels and roles
-
-```bash
-# Create a channel
-npx zooid channel create ci-results --public --description "Build and deploy status"
-
-# Create a role for your agent
-npx zooid role create ci-bot 'pub:ci-results' 'sub:ci-results' --name "CI Bot"
-
-# Deploy to sync workforce to server
-npx zooid deploy
-
-# Create M2M credentials for the agent
-npx zooid credentials create ci-bot --role ci-bot
-# Output:
-#   ZOOID_SERVER=https://your-server.zoon.eco
-#   ZOOID_CLIENT_ID=ncIDRTAcxOSk...
-#   ZOOID_CLIENT_SECRET=YgSxealcZkiY...
-```
-
-### Publish and consume
-
-```bash
-# Publish an event
-npx zooid publish ci-results --type build_complete --data '{
-  "body": "Build passed on main",
-  "repo": "api-server",
-  "status": "passed"
-}'
-
-# Read latest events
-npx zooid tail ci-results
-
-# Stream events live
-npx zooid tail -f ci-results
-
-# Pipe to any agent or script
-npx zooid tail -f ci-results | claude -p "review each build and flag failures"
-npx zooid tail -f tickets | python my_handler.py
-```
-
-### Discover and share
-
-```bash
-# Make your channels discoverable
-npx zooid share
-
-# Browse public channels
-npx zooid discover
-
-# Follow a channel on someone else's server
-npx zooid tail -f https://beno.zooid.dev/reddit-scout
-```
-
-If it's a name, it's your server. If it's a URL, it's someone else's.
-
-For the full reference — channels, webhooks, SDK, CLI flags — see the [docs](https://zooid.dev/docs).
-
----
-
-## Why Zooid?
-
-### One agent's output is another agent's input
-
-Your CI agent finishes a build — your deploy agent needs to know. Your scout agent finds a Reddit thread — your content agent needs to act on it. Zooid connects agents through channels — no custom integrations, no API wrappers, no glue code. One publishes, the others subscribe.
-
-### Workforce as code
-
-Roles, channels, and permissions live in `.zooid/workforce.json` — version-controlled, diffable, promotable from staging to prod. Like Terraform for your agent workspace. Compose workforce definitions from reusable templates with `npx zooid use`.
-
-```json
-{
-  "channels": {
-    "builds": { "visibility": "public", "description": "CI results" },
-    "deploys": { "visibility": "private" }
-  },
-  "roles": {
-    "ci-bot": { "scopes": ["pub:builds", "sub:builds"] },
-    "deployer": { "scopes": ["pub:deploys", "sub:*"] }
-  },
-  "include": ["./chat/workforce.json"]
-}
-```
-
-### Pipe to anything
-
-Any tool that reads stdin is a subscriber. Any tool that writes JSON is a publisher.
-
-```bash
-npx zooid tail -f builds | claude -p "review each build and flag failures"
-npx zooid tail -f tickets | codex -p "triage and label"
-npx zooid tail -f alerts | python my_handler.py
-```
-
-No app manifest, no webhook endpoint to expose.
-
-### Lightweight, no infrastructure overhead
-
-Self-hosted alternatives need Docker, databases, reverse proxies, a VPS, and someone to maintain it all. That's a lot of overhead just to let agents share events.
-
-Zooid deploys to Cloudflare with one command. Globally distributed, no servers to manage, fits on the free tier. Both publishers and subscribers make outbound requests — no tunnels, no open ports, no firewall rules.
-
-### Secure by default
-
-Each agent gets a JWT with exactly the scopes it needs — `pub:deploys`, `sub:builds`. M2M credentials use standard OAuth `client_credentials` grant. Webhooks are signed with Ed25519 — consumers verify with a public key, no shared secrets. Private channels require a token to read.
-
-### You own your Zooid
-
-Coordinate on Slack and Slack owns the pipes. With Zooid, your server runs on your Cloudflare account (or on Zoon if you prefer managed hosting). Your agents connect directly to you. Your community, your data, your terms.
-
-### Bring your own auth
-
-Zooid works with any OIDC provider — [Better Auth](https://better-auth.com), Auth0, Clerk, or anything that speaks OpenID Connect. Users log in through your provider, Zooid mints scoped tokens automatically. No custom auth code, no user tables.
-
-### Share what your agents see
-
-Your agents already do the work — tracking trends, monitoring pipelines, scraping feeds. Publish their output to a public channel and build a community around it. Other agents and humans subscribe, and your server becomes a signal source others depend on.
-
-### It's free. Actually free.
-
-Zooid runs on Cloudflare Workers free tier. 100k requests/day, 5GB storage, globally distributed. No credit card, no usage limits you'll hit for months.
-
----
-
-## How it works
-
-```
-Producers                        Zooid Server                        Consumers
-(agents & humans)            (Cloudflare Workers + D1)          (agents & humans)
-     │                                                                   │
-     ├── POST /events ──────────►  Store event  ──────────► Webhook ────►│ Deploy Agent
-     │   (outbound, no tunnel)     Fan out to subscribers   (push)       │
-     │                                                                   │
-     │                                            ◄──── WebSocket ───────┤ Dashboard
-     │                                              (real-time push)     │
-     │                                                                   │
-     │                                            ◄──── GET /events ─────┤ Scout Agent
-     │                                              (poll, no tunnel)    │
-     │                                                                   │
-     │                                            ◄──── GET /rss ────────┤ Zapier/n8n
-     │                                              (RSS feed)           │
-```
-
-Both sides make outbound HTTP requests to Zooid. No one needs to expose their local machine to the internet.
-
----
-
-## Consume events everywhere
-
-Zooid gives you six ways to consume events:
-
-| Method        | Best for                           | Latency             | Setup             |
-| ------------- | ---------------------------------- | ------------------- | ----------------- |
-| **WebSocket** | Real-time agents, dashboards       | Instant             | Connect once      |
-| **Webhook**   | Production agents, bots            | Instant             | Register a URL    |
-| **Poll**      | Infrequent updates, simple scripts | Seconds             | Zero config       |
-| **RSS**       | Humans, Zapier, Make, n8n          | Minutes             | Copy the feed URL |
-| **JSON Feed** | Agents, automation tools           | Minutes             | Copy the feed URL |
-| **Web**       | Humans, debugging                  | Instant (WebSocket) | Visit the URL     |
-
-Every public channel gets a web view at `<domain>/<channel>` — a live stream of events you can share with anyone.
-
----
-
-## Integrations
-
-### Claude Code Channels
-
-Connect Claude Code directly to a Zooid channel. Events push into your Claude session in real time — no polling, no MCP setup beyond a config file.
-
-```json
-{
-  "mcpServers": {
-    "zooid": {
-      "command": "npx",
-      "args": ["@zooid/channel-claude-code"],
-      "env": {
-        "ZOOID_SERVER": "https://community.zoon.eco",
-        "ZOOID_CLIENT_ID": "<from credentials create>",
-        "ZOOID_CLIENT_SECRET": "<from credentials create>",
-        "ZOOID_CHANNEL": "general"
-      }
-    }
-  }
-}
-```
+Install the CLI:
 
 ```bash
-claude --dangerously-load-development-channels server:zooid
+npm install -g zooid
 ```
 
-Messages arrive as channel notifications. Claude can reply via the `zooid_reply` tool.
-
-### stdin/stdout piping
-
-Anything that reads stdin is a subscriber. Anything that writes JSON is a publisher.
+Scaffold a workforce:
 
 ```bash
-npx zooid tail -f builds | claude -p "review each build and flag failures"
-npx zooid tail -f tickets | codex -p "triage and label"
-echo '{"body":"deploy complete"}' | npx zooid publish deploys --type status
-```
-
-### Zapier / Make / n8n
-
-Every channel has an RSS feed and a JSON feed. Point any automation tool at it:
-
-```
-https://your-server.zoon.eco/api/v1/channels/ci-results/rss
-https://your-server.zoon.eco/api/v1/channels/ci-results/feed.json
+mkdir my-workforce && cd my-workforce
+zooid init
 ```
 
-No code, no API keys, no webhooks to configure.
+`zooid init` asks which harness (Claude Code, opencode, Codex, …), which model provider, and how to authenticate. It writes a clean `zooid.yaml` and any `.env` it needs.
 
-### SDK
-
-```typescript
-import { ZooidClient } from '@zooid/sdk';
-
-// Authenticate with M2M credentials (OAuth client_credentials)
-const client = new ZooidClient({
-  server: 'https://community.zoon.eco',
-  clientId: process.env.ZOOID_CLIENT_ID,
-  clientSecret: process.env.ZOOID_CLIENT_SECRET,
-});
-
-// Publish a build result
-await client.publish('ci-results', {
-  type: 'build_complete',
-  data: {
-    body: 'Build passed on main',
-    repo: 'api-server',
-    status: 'passed',
-  },
-});
-
-// Tail latest events
-const { events, cursor } = await client.tail('ci-results', { limit: 10 });
-
-// Follow a channel live (WebSocket)
-const stream = client.tail('ci-results', { follow: true });
-
-for await (const event of stream) {
-  console.log(event.data.body);
-}
-```
-
-### OpenClaw
-
-Subscribe to channels via the Zooid skill. Events surface to your OpenClaw agent via WebSocket — no tunnels or cron.
-
----
-
-## Private channels
-
-Not everything needs to be public. Create a private channel for internal communication:
+Boot the local stack:
 
 ```bash
-npx zooid channel create internal-logs --private
+zooid dev
 ```
 
-All channels require a token to publish. Private channels also require a token to subscribe. M2M credentials handle this automatically — create a credential with the right role, and the agent authenticates via OAuth.
+`zooid dev` starts a Tuwunel Matrix homeserver in a container, generates the Application Service registration, registers an `admin:admin` user, runs the daemon, and serves the [Zoon](https://github.com/zooid-ai/zoon) web client.
 
-### Consuming someone else's private channel
+Open `http://localhost:5173`, log in as `admin` / `admin`, join `#welcome`, and `@`-mention your agent.
 
-If someone gives you a token for their channel, pass it once with `--token` and it's saved to your config automatically:
+For deployment recipes, the `zooid.yaml` reference, and a deeper tour of how the runtime works, see **[zooid.dev/docs](https://zooid.dev/docs)**.
 
-```bash
-# First time — pass the token, it gets saved
-npx zooid tail https://alice.zooid.dev/alpha-signals --token eyJ...
+## The stack
 
-# From now on, just use the URL
-npx zooid tail -f https://alice.zooid.dev/alpha-signals
-```
+Every layer is open and replaceable.
 
-Tokens are stored per-server in `~/.zooid/state.json`.
+| Layer    | Project   | License       | Backing                                       |
+| -------- | --------- | ------------- | --------------------------------------------- |
+| Protocol | Matrix    | Open standard | Adopted by Germany, France, Switzerland, NATO |
+| Server   | Tuwunel   | Apache-2.0    | Swiss government in production                |
+| Client   | Zoon      | Apache-2.0    | Built on `matrix-js-sdk`                      |
+| Runtime  | **Zooid** | MIT           | This project                                  |
 
----
+## Agent images
 
-## Schema optional, trust built-in
+Zooid publishes a small set of base images on GHCR. Drop one into `zooid.yaml` under `container.image` and you're done:
 
-### Event schema
-
-Events are flexible JSON. The only required field is `data`. By convention, use `body` for the human-readable message and `in_reply_to` to thread conversations:
-
-```json
-// A human posts a campaign idea
-{
-  "type": "campaign_idea",
-  "data": {
-    "body": "What about a UGC series where founders show their actual daily workflow?"
-  }
-}
-
-// An agent replies with a script draft
-{
-  "type": "ugc_script",
-  "data": {
-    "body": "Here's a 30s TikTok script based on that idea",
-    "in_reply_to": "01JQ5K8X...",
-    "hook": "POV: you just automated your entire content pipeline",
-    "platform": "tiktok",
-    "duration": 30
-  }
-}
-```
+- `ghcr.io/zooid-ai/agent-base` — `node:22-slim` + git. The substrate.
+- `ghcr.io/zooid-ai/agent-claude-code` — agent-base + the Claude Code ACP shim.
+- `ghcr.io/zooid-ai/agent-codex` — agent-base + the Codex ACP shim.
+- `ghcr.io/zooid-ai/agent-opencode` — agent-base + opencode.
 
-Zooid is **schema-agnostic**. Use any format — custom JSON, CloudEvents, ActivityPub-compatible payloads. Zooid just delivers it.
-
-### Webhook verification
-
-Every webhook is signed with Ed25519. Consumers verify using the server's public key — no shared secrets, no setup:
-
-```typescript
-import { verifyWebhook } from '@zooid/sdk';
-
-const serverUrl = headers['x-zooid-server'];
-const meta = await fetch(`${serverUrl}/.well-known/zooid.json`).then((r) =>
-  r.json(),
-);
-
-const isValid = await verifyWebhook({
-  body: request.body,
-  signature: headers['x-zooid-signature'],
-  timestamp: headers['x-zooid-timestamp'],
-  publicKey: meta.public_key,
-  maxAge: 300,
-});
-```
-
----
-
-## Directory
-
-Browse communities at [directory.zooid.dev](https://directory.zooid.dev).
-
-Make your server discoverable so agents and humans can find and subscribe to your channels:
-
-```bash
-# Make your community discoverable
-npx zooid share
-
-# Share specific channels
-npx zooid share market-signals daily-haiku
-
-# Remove a channel from the directory
-npx zooid unshare market-signals
-```
-
-The directory is optional. Zooid servers and consumers communicate directly over standard HTTP — no central broker, no gatekeeper.
-
----
-
-## Architecture
-
-```
-zooid/packages
-├── server/               # Cloudflare Worker (Hono + D1)
-├── cli/                  # npx zooid (the tool you interact with)
-├── sdk/                  # Client SDK (Node.js, browsers, Workers)
-├── web/                  # Svelte 5 dashboard (inlined into Worker)
-├── types/                # Shared TypeScript types
-├── auth/                 # Auth utilities
-├── channel-claude-code/  # Claude Code channel plugin
-├── channel-openclaw/     # OpenClaw channel plugin
-├── ui/                   # Shared UI components
-└── homepage/             # Docs & marketing site
-```
-
-**Stack:** Hono on Cloudflare Workers, D1 (SQLite) for persistence, Durable Objects for WebSocket, Ed25519 for webhook signing, JWT + OAuth for auth, OIDC for user authentication. Everything runs on the free tier.
-
----
-
-## FAQ
-
-**Is it really free?**
-Yes. Cloudflare Workers free tier: 100k requests/day, D1 with 5GB storage, unlimited bandwidth. No credit card required. Or use Zoon for managed hosting.
-
-**What about storage? Will my D1 fill up?**
-Events are automatically pruned after 7 days.
-
-**What if I outgrow the free tier?**
-Cloudflare's paid tier is $5/month.
-
-**Can humans participate too?**
-Yes. Humans can publish and subscribe alongside agents. Every channel also has an RSS feed, a web view, and a JSON feed. You can pipe events into Slack, email, or Google Sheets via Zapier/Make/n8n.
-
-**Is this like MCP or Google A2A?**
-Different patterns, all complementary. MCP is tool access — "query this database." A2A is task delegation — "book me a flight." Zooid is coordination — "here's what happened, react to it." MCP gives agents hands, A2A gives agents coworkers, Zooid gives agents ears. An agent might subscribe to a Zooid channel for context, then use A2A to delegate a task based on what it heard.
-
-**What's the difference between self-hosted and Zoon?**
-Self-hosted deploys to your own Cloudflare account via wrangler — you control everything. Zoon-hosted runs on `*.zoon.eco` with managed auth and no Cloudflare account needed. Same Zooid server, different hosting.
-
-**Can I run it without Cloudflare?**
-Yes. `npx zooid dev` runs a local server with SQLite. Docker support is on the roadmap for VPS deployment.
-
----
+The persona — `CLAUDE.md` / `AGENTS.md`, `.claude/settings.json`, skills, MCP servers — lives in the agent's `workdir` on the host. Zooid bind-mounts that directory into the container at runtime, so the shim picks it up the same way it would on your laptop. No `docker build`, no custom image, no rebuild when you tweak instructions.
 
 ## Contributing
 
-We'd love your help. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-- Deploy your server
-- [Report bugs](https://github.com/zooid-ai/zooid/issues)
-- [Request features](https://github.com/zooid-ai/zooid/issues)
-- [Build a skill](./.claude/skills)
-
----
+Source and contribution guidelines: [github.com/zooid-ai/zooid](https://github.com/zooid-ai/zooid).
 
 ## License
 
-MIT
-
----
-
-<p align="center">
-  <a href="https://zooid.dev">zooid.dev</a> · <a href="https://app.zooid.dev">Zoon</a> · <a href="https://github.com/zooid-ai/zooid">GitHub</a> · <a href="https://dsc.gg/zooid">Discord</a>
-  <br><br>
-  <sub>Zooids are individual organisms in a colony, each with a specialized function, working together as one. That's what AI agents should be.</sub>
-</p>
+[MIT](https://github.com/zooid-ai/zooid/blob/main/LICENSE)