{"id":"a2fc15f2-8718-4813-bc52-ba1f4bd45d8b","slug":"ai-collab-framework","kind":"skill","name":"ai-collab-framework","summary":"Multiple AIs collaborate through shared filesystem files. Zero dependencies, any AI that can read/write files can join.","owner":"IronHanhann","repoUrl":"https://github.com/IronHanhann/ai-collab-framework","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-16T13:11:30.000Z","addedAt":"2026-10-21T13:46:01.257Z","logoUrl":"https://avatars.githubusercontent.com/u/79067797?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents"],"tags":["ai-agents","collaboration","markdown","multi-agent","powershell"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T08:46:29.608Z","sample":false,"url":"https://conduits.dev/tools/ai-collab-framework","language":"PowerShell","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ✨ AI Collab Framework\n\n> Multiple AI agents collaborating through a shared folder. No API, no server, no network — just files.\n\n<div align=\"center\">\n\n⭐ **If this is useful, a Star helps others find it** ⭐\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![Version](https://img.shields.io/badge/version-v1.9.7-blue.svg)\n[![Protocol](https://img.shields.io/badge/protocol-file--based-green.svg)](SKILL.md)\n[![Zero Deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()\n\n[中文文档](README.zh-CN.md) · [协议本体](SKILL.md) · [用户手册](docs/USER-GUIDE.md) · [样例](examples/README.md)\n\n</div>\n\n---\n\n## 🎯 What is this\n\nMultiple AIs on your disk, talking to each other through a folder. **No API. No server. No network. No middleware. No code.** A shared directory is the entire infrastructure.\n\nIt's not software — it's a *convention*. Which means it can never break from a platform upgrade or a model change.\n\n---\n\n## 💡 Why pick this\n\nMost multi-agent options ask you to install an SDK, register an API key, or trust someone's hosted service. This one asks for a folder.\n\n| | Other options typically | This framework |\n|---|---|---|\n| Setup | Install a plugin / register an API key | Copy a folder |\n| Who can join | AIs on that vendor's platform | **Any AI that can read and write files** |\n| What breaks on upgrade | SDK version, platform API changes | Nothing — it's a convention, not a dependency |\n| Cost to run | Per-call API billing | Zero (you already pay for the AIs) |\n| Where your data lives | Someone's server | Your disk |\n| Can you read every message? | Only through their tooling | **Open the folder. It's all plain markdown.** |\n| Can you hand-edit a \"config\"? | Their settings UI | **Edit one file. That's the whole config.** |\n\nNo competitor is named here — the point isn't that others are bad, it's that the *category* has a certain shape and this one doesn't fit it.\n\n---\n\n## ⚡ Seven things it gives you\n\n1. **Any AI joins in one line** — if it can read and write files, it's in. DeepSeek, Doubao, Claude, GPT, Kimi, your own agent.\n2. **Crash recovery is a file read** — no session to resume, no token to refresh. AI died, quota ran out, model swapped? Start a new one, it reads `STATE.md` and continues from where the last one stopped.\n3. **A crashed AI can't corrupt anyone's mailbox** — every write is `.tmp` first, then rename. Readers skip `.tmp`. Half-written messages don't exist.\n4. **No two AIs do the same job** — a task is claimed with a time-limited lease *before* it's worked. Leases expire, so a crashed holder doesn't deadlock anyone.\n5. **You can see everything, always** — every message is plain markdown in a folder. Open it in any editor. No dashboard, no query language, no log ingestion.\n6. **You can change the rules by hand** — flip the switch, appoint a controller, change the polling interval: each is editing one file. **You're not operating software; you're editing config.**\n7. **You're never the message bus** — the framework does the relaying. You supervise, decide, and flip switches.\n\n---\n\n## 🏗 Architecture\n\n```\nAI-A writes file → shared folder → AI-B reads file → writes reply → AI-A reads reply\n```\n\nEach AI gets its own inbox. Others drop files in. It wakes up on a timer (or when you poke it), reads new messages, processes them, writes back. **Email for AIs — except the mailbox is a folder, and delivery is free.**\n\n**Why files?** Not every AI platform gives you an API. But essentially every AI can read and write files.\n\n### Three roles\n\n| Role | Does what | Analogy |\n|---|---|---|\n| **Controller** | Coordinates globally, owns the protocol, assigns message-ID ranges | Foreman |\n| **Worker AI** | Does the actual work (code, translation, docs, review) | Crew |\n| **You** | Supervise, decide, flip the switches | Client |\n\n**The controller is a *position*, not an identity.** You appoint one AI as controller; it reads `CONTROLLER.md` and knows its job. Want a different one? Edit that file — one line. If the controller dies, nothing critical breaks: the workers keep going, you just appoint a new foreman.\n\n---\n\n## 🚀 Quick start (one line to onboard)\n\n> **First rule of every session:** before touching anything, read `projects/{name}/ROLE.md` — it tells you which project you belong to, which inbox is yours, and what you must not touch. No `ROLE.md`? Read `SWITCH.md`. Never read another project's files. (FRAMEWORK.md §18.3 rule 5)\n\n### 1. Create a project\n\n```powershell\n# Copy the template\nxcopy /E /I \"template\" \"projects\\my-project\"\n\n# One inbox per AI\nmkdir \"projects\\my-project\\inbox-ai-a\"\nmkdir \"projects\\my-project\\inbox-ai-b\"\n```\n\n### 2. Tell the AI to connect\n\nSend this to any AI — copy-paste ready:\n\n```\nYou are now connected to the AI Collab Framework.\nRead SKILL.md first and follow the protocol.\nYour inbox is projects\\my-project\\inbox-ai-a\\\nWake up on a timer (default 15 minutes, adjustable), follow the flow in SKILL.md.\n```\n\nThat's the whole install. **No plugin, no API call, no code.**\n\n### 3. Start it up\n\nEdit `projects\\my-project\\SWITCH.md`, set `enabled: true`.\n\n> New projects start with `enabled: false` **on purpose** — flipping it before everyone has arrived just burns tokens on idle cycles.\n\n---\n\n## ⚠️ Human oversight is required\n\nThis framework runs on **AI self-discipline**, not enforced validation. The rules are conventions the AI follows voluntarily — there is no hard check that stops an AI from breaking them.\n\n- **AI is single-threaded and has limited attention.** It can forget: it edits one spot and neglects to sync the other, or skips a checklist item.\n- **Don't leave it fully unattended.** Periodically look at `cron-log.md`, `STATE.md`, and the check results yourself. Don't expect the AI to catch all its own mistakes.\n- **`check.ps1` only does mechanical checks.** It catches what can be checked automatically (missing files, stale `.alive`, drift between the three copies). Semantic and logical errors still need a human eye.\n\n> The AI won't police itself. Your periodic glance is the safety net.\n\n## 🔄 How a message flows\n\nEvery time an AI wakes up (on a timer, or when you poke it):\n\n```\n1. Read the master switch   →  disabled? Stop. Don't reschedule.\n2. Read the project switch  →  disabled? Skip this project, keep the timer.\n2.5 Read ROLE.md           →  which role slot are you? Do only your own work.\n3. Touch your .alive file   →  your own timestamp, nobody else's\n3.5 Read back .alive mtime  →  mismatch? Write failed, retry next round\n4. Scan for used message IDs→  your inbox + archive + tombstones\n5. Read STATE.md + inbox    →  see what's new\n6. Process messages         →  write replies, claim leases first\n7. Append a line to cron-log.md\n```\n\nEvery message is one file named `{id}-{sender}-{type}.md` with a standard `META` header. A full round-trip — task, result, ack — is in [examples/messages.md](examples/messages.md).\n\n---\n\n## 🧑‍💻 The hidden one: several sessions of the *same* AI\n\nYou don't need different vendors. Run one Doubao session as the developer and another as the reviewer; a DeepSeek session for research and one for code. They never collide — each is its own inbox, its own `.alive`, its own identity.\n\nThis is the capability most frameworks don't have. It's also the one that makes the framework usable when you have exactly one good AI and want a second opinion from it.\n\n**Why they don't collide:** identity is the inbox folder, not the model name. Two sessions of the same model are two folders. Slot names are session-scoped — the same software in two projects must use `{software}-{project}` names so a session can never read the other project's mail.\n\n---\n\n## 🔧 What's built in\n\n| Mechanism | What it does |\n|---|---|\n| 📦 **Zero dependencies** | If the AI can read and write files, it can join. No SDK, no API keys, nothing to install. |\n| 🌐 **Cross-platform** | DeepSeek, Doubao, Claude, GPT, Kimi, any custom AI — all work. |\n| 💥 **Crash recovery** | All state lives on disk. AI died, quota ran out, session reset? Start a new one, read the files, continue from where it stopped. |\n| 🔄 **Multi-project** | Run several independent collaborations at once, fully isolated. |\n| 👑 **Controller role** | One AI coordinates globally. Controller dies → workers keep running, no auto-takeover fights. |\n| 🔢 **Numbered messages** | Every message gets an ID from a shared pool. Nothing lost, nothing duplicated. |\n| 📝 **ACK receipts** | Received a message? Write an ack. The sender knows you saw it. |\n| 🔒 **Lease system** | Claim a task *before* working on it. No two AIs start the same job. Leases expire — no deadlocks. |\n| 🔘 **Two-layer switches** | Master switch stops everything; project switch stops just one project. One file = full control. |\n| 💚 **`.alive` heartbeats** | Private per-participant liveness file — only its owner writes it. That's why a shared heartbeat log can't prove who's alive. |\n| 🪦 **Exit tombstones** | An AI leaving writes `EXITED.md` with its unfinished work handed over. No vanishing acts. |\n| ⚛️ **Atomic writes** | Write to `.tmp`, then rename. Nobody ever reads a half-written message. |\n| 🧑‍💻 **Same AI, multiple roles** | Run several sessions of the *same* AI as different team members. They never collide. |\n\n---\n\n## 🖥 Daily operations\n\n| What you want | What you do |\n|---|---|\n| Stop everything | Edit root `SWITCH.md`, set `enabled: false` |\n| Stop one project | Edit `projects/{name}/SWITCH.md`, set `enabled: false` |\n| See who's working | Read `projects/{name}/STATE.md` |\n| Check if AI is alive | Read `projects/{name}/inbox-{ai}/.alive` mtime — 30+ min unchanged means dead. **Not** `HEARTBEAT.md`'s mtime: it's a shared file, anyone's write refreshes it |\n| Start a new project | Copy `template/` → `projects/{new-name}/`, then onboard AIs |\n| Add a new AI to a project | Register it in `PARTICIPANTS.md` + `IDENTITY.md`, create `inbox-{new-ai}/`, add a block in `STATE.md`, log it in `HEARTBEAT.md`, then broadcast. Let an existing AI do it — it has the checklist |\n| Appoint a new controller | Edit `CONTROLLER.md`, one line |\n| Controller went dark | Its `.alive` is frozen and it won't take over your project. Business projects keep running; fix emergency bugs yourself and broadcast. A new controller is appointed by **you**, not auto-promoted |\n| Stop two AIs doing the same work | Check `projects/{name}/LEASES.md` — one task, one owner, one lease |\n| Resume a long task after a crash | Read `projects/{name}/PROGRESS.md` — it holds the checkpoint |\n| Know who is who before touching anything | Read `projects/{name}/ROLE.md` — role slots, what you own, what you must not touch |\n| Never silently rewrite a sent message | Sent = sent. Fix it with a correction message under a new ID |\n\n**Everything is just editing files.** You're not operating software — you're changing configs.\n\n---\n\n## 🧪 How it works, and what it can't do\n\n**How it works.** State lives on disk, so nothing is ever held in a conversation. When an AI dies, the next one reads the files and picks up the thread. When a model is swapped, the new executor reads `IDENTITY.md` and knows who it is. When a task is long, its checkpoint is in `PROGRESS.md` so a crash costs minutes, not the whole job.\n\n**What it can't do.** It isn't real-time — participants poll, or you poke them. Everyone must reach the same directory. Message IDs are project-scoped, so cross-project collisions are prevented by slot naming, not by a global registry. Files are plain text, so no secrets in them; need privacy, put the folder on an encrypted drive.\n\nIt's a convention, not a sandbox. An AI *could* misbehave — which is why the protocol requires timestamps to come from a system command rather than the model's own clock, and why every claim is meant to be verified against the disk.\n\n---\n\n## 💸 Cost\n\nRunning the framework itself costs about **one cent per round** (≈¥0.1) — measured during off-peak hours — most of your bill is the actual work the AIs do, not the plumbing.\n\nTip: turn it off when idle (one file flip, zero cost) and keep messages short.\n\n---\n\n## 📖 It has actually been run\n\nThis isn't a design exercise. The protocol was built while two AIs used it to collaborate, and every rule in it exists because something happened:\n\n- **58 numbered messages** across **119 archived files**, in one day of work\n- **2 of the 3 participants were on different platforms** — one of them switched executor **three times** mid-project (twice from running out of quota). Neither side noticed; identity is the folder, not the model.\n- **Two message-ID collisions happened**, and the numbering rule was changed to close the hole — the rule exists because of the incident, not in spite of it\n- **One participant left mid-project** and the exit procedure ran end to end: tombstone, handover of unfinished work, broadcast to everyone\n- **The liveness check silently failed for 76 minutes** — a heartbeat file stopped updating because a script matched an example line in the documentation. It was found, fixed, and turned into a write-back verification step in the protocol.\n- The `.alive` mechanism itself was adopted *from the other side's* suggestion, after the shared heartbeat log was shown to be unreliable\n\nThose numbers are counted from the framework's own working logs, not estimated.\n\n---\n\n## 📂 Directory structure\n\nThe repo (this package):\n\n```\nai-collab-framework/\n├── SKILL.md              # Protocol spec (the AI reads this)\n├── SKILL.zh-CN.md        # 协议本体中文版\n├── FRAMEWORK.md          # Full framework protocol (generalized)\n├── DISCIPLINE.md         # Full discipline rules (17 sections)\n├── CONTROLLER.md         # Controller registry (a role, not an identity)\n├── SCRIPT-SPEC.md        # poll/check contract (generate your own if no PowerShell)\n├── README.md             # This file\n├── README.zh-CN.md       # 中文版\n├── LICENSE               # MIT\n├── docs/\n│   ├── USER-GUIDE.md     # User manual\n│   └── USER-GUIDE.zh-CN.md\n├── screenshot-*.png      # Screenshots\n├── examples/             # Sanitized sample projects (all data fictional)\n└── template/             # Blank project template — copy this to start a project\n    ├── SWITCH.md         # Project switch (starts disabled)\n    ├── ROLE.md           # Who you are in THIS project — read it first, every session\n    ├── STATE.md          # Shared state ← recovery entry point\n    ├── PARTICIPANTS.md   # Participant registry\n    ├── IDENTITY.md       # Who each participant is (identity = slot name, not model)\n    ├── DISCIPLINE.md     # Starter subset (full 17 sections: DISCIPLINE.md at package root)\n    ├── DECISIONS.md      # Decision log (with rationale)\n    ├── HEARTBEAT.md      # Heartbeat log (facts only)\n    ├── LOG.md            # Message log\n    ├── LEASES.md         # Lease table (prevent duplicate work)\n    ├── PROGRESS.md       # Long-task checkpoint (resume after crash)\n    ├── poll.ps1          # Polling script (Windows; other OSes: follow SCRIPT-SPEC.md)\n    ├── check.ps1         # Consistency checker\n    ├── CRON-TEMPLATE.md  # Timer prompt template\n    ├── inbox-controller/ # Controller inbox (all issues go here)\n    ├── inbox-{name}/     # One inbox per participant (+ .alive)\n    └── archive/          # Processed messages, by ID\n```\n\nYour live projects go in `projects/` (gitignored, so your data never lands in the repo). Each project is a copy of `template/`, plus a `cron-log.md`.\n\nPer the protocol the framework root only ever has one switch — `SWITCH.md`, the master switch — plus `CONTROLLER.md` when a controller is appointed, and `FRAMEWORK.md` / `USER-GUIDE.md` as the protocol and manual. Everything else lives *inside* each project, so a second project can never touch the first one's state.\n\n```\n{your-collab-root}\\\n├── SWITCH.md              # Master switch — read it first, every wake-up\n├── projects\\\n│   ├── my-project\\        # A copy of template/ + cron-log.md\n│   └── my-other-project\\\n├── FRAMEWORK.md           # The protocol itself\n├── USER-GUIDE.md          # Human-facing manual\n└── template\\              # Blank project template — copy this to start a project\n```\n\n**Every project-level file lives under `projects/{project}/`** — `SWITCH.md`, `STATE.md`, `DECISIONS.md`, `HEARTBEAT.md`, `LEASES.md`, `PROGRESS.md`, `DISCIPLINE.md`, `IDENTITY.md`, `PARTICIPANTS.md`, `cron-log.md`, `LOG.md`, `CONTROLLER.md`, `inbox-*`, and `archive/`. See the tree in [examples/structure-two-ai.md](examples/structure-two-ai.md) for the full layout, and [examples/root-files.md](examples/root-files.md) for what goes in each of those six state files.\n\n**Want to see one running?** [examples/](examples/README.md) has sanitized sample projects, a full message round-trip, and skeletons of the state files — all fictional data.\n\n---\n\n## 🩹 FAQ\n\n| Question | Answer |\n|---|---|\n| **AI died / ran out of quota** | Check its `.alive` file. No update for 30+ min = it's dead. Start a new session; it reads `IDENTITY.md` + `STATE.md` and continues. |\n| **Two AIs used the same message ID** | The later one renumbers and logs it in `HEARTBEAT.md`. Always scan for used IDs before sending. |\n| **Want to add a new AI** | Tell any *existing* participant \"add {new-name}\". It handles onboarding. |\n| **Controller died** | No `.alive` for 30+ min = offline. Workers keep running. No auto-takeover — you appoint a new controller. |\n| **Can two AIs edit the same file at once?** | Yes, but don't. That's what leases are for — claim a task before starting it. |\n| **Is this secure?** | Files are plain text. Don't put secrets in them. Need privacy? Put the folder on an encrypted drive. |\n| **Does switching models break anything?** | No. Identity is the inbox folder, not the model name. We switched executors three times mid-project and the other side never noticed. |\n| **What if an AI won't follow the rules?** | It's a convention, not a sandbox — an AI *could* misbehave. Timestamps must come from a system command, not from the model. That's why the protocol says so. |\n\n---\n\n## 🧪 Example use cases\n\n- **Code review**: AI-A writes code, AI-B reviews it and leaves comments in the inbox, AI-A reads the review and fixes issues.\n- **Translation project**: AI-A translates a document, AI-B proofreads, AI-A revises. All through files.\n- **Swap models without losing context**: DeepSeek ran out of quota? Start Doubao — it reads the state files and continues.\n- **Multiple sessions, same AI**: One Doubao session as \"developer\", another as \"reviewer\". They collaborate through files, never collide.\n- **Review each other's homework**: Send a `task` asking another AI to audit your protocol. It will find bugs you can't see.\n\n---\n\n## 🛠 Development\n\nThis is a protocol package, not a code framework. To modify it:\n\n1. Edit `SKILL.md` (the protocol spec)\n2. If you changed the structure, sync `template/`\n3. Bump the version in `SKILL.md` / `README.md` / `README.zh-CN.md`\n4. The controller AI keeps live deployments and this open-source package in sync\n\n> **Sync three copies**: a protocol change must land in the framework root, every live project, *and* `template/`. Letting them drift is how a project ends up following rules nobody has anymore.\n\n---\n\n## 📦 Version\n\nCurrent: **v1.9.7** — per-round lease check + immutable messages + two-role ROLE.md\n\nVersion history: see the repo's `git log`.\n\n## 📄 License\n\n[MIT](LICENSE)\n"}