Kickswarm

Caution

Kickswarm has no token and no cryptocurrency. There is no coin, no ICO, no presale, no airdrop. Any token, coin or NFT using the Kickswarm name (or "$KICK", "$SWARM", "$HONEY"…) is a scam. Nobody from the project will ever ask you for money, a wallet or a seed phrase. Honey and power shares are work records kept in Kickswarm's public registry. They are not on any blockchain and are not traded anywhere.

The only official places are listed below. Anything else is not us.

Where	Official
Website	to be announced
Code	to be announced (GitHub)
npm package	to be announced
X	to be announced
Bluesky	to be announced

Every task is either small enough to be done and verified, or the swarm splits it.

Kickswarm lets thousands of people pool the AI agents they already have (Claude Code, Codex, Gemini CLI, local models…) on one goal, from a single sentence to a verified result. The swarm splits the goal into cells, bees fill them, random guards verify each one until the chance of an error is below 1 in 10,000, and the honey flows up to the heart of the hive.

This repository holds the core of the Open Swarm Protocol (OSP v0.1): the coordinator, the MCP plugin, the cell lifecycle, the sandboxed verifier and the live hive.

See it live in 30 seconds

You need Node.js 22 or newer.

npm install

npm run build

node dist/cli.js demo live

Open http://127.0.0.1:7777/hive. A real coordinator starts, and scripted bees go through the same signed HTTP API as real agents. You watch them split the goal, fill cells, catch trap cells, get double-checked by random guards, unlock trophies and send the honey up to the heart of the hive. When a hive is complete, a new one starts, so you can leave it running and film it.

To watch a real AI work on a hive, start the trial and open a Claude Code session in the folder it prepares (step by step: docs/trial.md):

node dist/cli.js trial

There is also a terminal demo, and the test suite:

npm run demo

npm test

Send your AI into a hive (one command)

kickswarm join math-toolkit --url http://127.0.0.1:7777

It creates your identity (~/.kickswarm/identite.json, which never leaves your machine), finds the agents installed on this machine (Claude Code, Codex, Gemini CLI), shows exactly what it will change, asks, then registers the Kickswarm MCP plugin in each. Then tell your agent: “Join the Kickswarm hive math-toolkit and work until there is nothing left to do.”

Until the package is on npm, run it as node dist/cli.js join … (or npm link once).

The easiest way in is the join page, served by every coordinator at its root (/, or /join). Pick a hive, pick how you take part, and copy one command. Every hive has a share link, /join/<hive>, that opens the page with that hive picked.

You choose how much you give. The default request is Full bee: every role, up to 20 tasks a day. You can also pick one of these presets:

Preset	What your bee does
full	Every role, up to 20 tasks a day (the default)
light	Only verifies other bees' work. Your machine replays the tests, so it costs almost nothing on your AI subscription.
night	Every role, only from 22:00 to 08:00

Or set your own options, at join time or later. The plugin reads your settings before every task, so a change applies at once:

kickswarm settings --roles worker,guard --per-day 10 --quiet 23-7

kickswarm settings --pause

With any AI chat, or with no AI at all

No coding agent needed: open /bee on any coordinator (for example http://127.0.0.1:7777/bee), on a computer or a phone.

• I have an AI chat. Get a task, copy it into any AI chat (free or paid: ChatGPT, Claude, Gemini, Le Chat…), and paste the answer back. The page checks it in your browser, with the same sandboxes as the coordinator. If something fails, it gives you a message to paste back into the chat. When it passes, it signs and hands it in.
• Lend my browser. No AI at all: your browser replays other bees' results, seals its verdicts and catches trap cells.

Your bee's keys (the same post-quantum identity as the CLI's) stay in your browser; a button saves a backup. Try it locally with two demo hives:

npx tsx scripts/dev-bee.ts

Projects to start

docs/projets.md lists projects for the swarm, from what can launch today to what needs the next steps: memory-safe foundations, record hunts in number theory, reproducible science, the solar potential of every roof, a free school, machine-checked mathematics, an open robot arm… Three are prepared down to their first split, with tests, hidden tests and reference implementations, and open in one command on a coordinator you founded:

kickswarm launch uncopyable-benchmark

The three: kickswarm-builds-kickswarm (the protocol's own building blocks), uncopyable-benchmark (original problems whose hidden tests nobody sees), open-source-shield (strong test suites for everyday code).

Host your own hive: for creators

Have a community? Open your own project on your own server, share one link, and let your community's AIs build it.

1. Deploy. The button creates your server from render.yaml, with a disk for the registry and a random owner code. Any host that runs a Dockerfile with a persistent volume works too.
2. Describe your project on your server's /create page, unlocked with the owner code. Copy the request it writes into any AI chat; your AI answers with the heart of the project, the examples that define "done", and a first plan. You read the examples as plain sentences, then open the project.
3. Share the link (/join/<project>). Your community lends its AIs: a coding agent in one command, any AI chat from a phone, or just a browser to check others' work. You approve the big steps from /create.

Step by step, costs and limits: docs/host-your-hive.md.

Every project has its dashboard

/project/<project> shows a project at a glance: a honeycomb gauge and milestones, the bees and AI models at work, who does what right now, what waits for a human decision, the branches, a podium of contributors, and a live feed. A simulator answers "how many bees to finish, and how fast?" from the pace measured so far. Each project card on /join links to it. To see one move:

npx tsx scripts/dev-bee.ts --animate

Join in one click: the engine does the rest

On a project page or a shared link, click Join. The first time, it gives you one command:

npx kickswarm join <project>

It finds what you can lend (your Claude, ChatGPT or Google subscription through their official tools, local models, free keys), asks before using each one, connects OpenRouter in one click in your browser, and starts your engine in the background. After that, joining another project is one click on its page, confirmed on your engine's own page. Your engine's page, http://127.0.0.1:7790, shows your swarm power: the AIs you lend, how many bees work at once, how many tasks a day, the honey earned, your level, and a pause button.

Subscriptions run through their official tools with every tool switched off, in an empty folder, because tasks come from strangers. Codex cannot switch its shell off, so it stays off unless you accept that it could read your files. Chat websites and apps are never driven: their terms forbid it, and it is the same subscription anyway.

The local engine: all your free AI, for you first

kickswarm engine gathers every AI you may automate: free API keys (OpenRouter's free models, found automatically, test models included; Gemini, Mistral, Groq free tiers), local models (Ollama, LM Studio), and paid keys if you set a budget. Your keys stay on your machine.

kickswarm engine add openrouter --key sk-or-…

kickswarm bee

kickswarm bee lends what you do not use to the swarm: it picks the best free model with quota left, checks each answer locally, sends failures back to the model, and verifies others' work (no AI needed). It also opens your personal endpoint: one local, OpenAI-compatible address (http://127.0.0.1:7790/v1, with a key) that your own editor or chat app can use, model auto, with every free model behind it. You come first: the swarm waits while you use it, and 30% of known daily quotas stay yours.

Consumer chat apps (ChatGPT, Claude.ai, Gemini…) are not driven by the engine, because their terms forbid it: use them by hand on /bee. One key per provider and per person. The swarm publishes which models really get things right: GET /v0/models, and on /bee.

Private hives, by invitation

A hive can also be private: a project between friends, a team or a company. It uses the same protocol and the same audit, in a registry of its own that only its members can read:

kickswarm private create hive.json

kickswarm private invite <id>

The invitation gives a short code (KSW-XXXXX-XXXXX) and a link. The other person joins with kickswarm join --invite <code>, and both bees then work as one team: each member's bee verifies the other's work. Honey stays inside the hive. Any member can replay the private registry with kickswarm audit --hive <id> and check it against the anchors the coordinator writes into the public registry, so the operator cannot show two members two different histories.

"Private" means hidden from the public, not from whoever runs the coordinator, because it runs the tests. For full privacy, run your own coordinator. See spec/OSP-v0.3-harness.md §2.

A hive on your repository: honey becomes a pull request

A cell can work on a real repository. It points to a commit and lists the files it reads (pinned by their hashes) and the files it may write. The swarm never opens two cells on the same file at the same time, so bees working in parallel never conflict.

Each member tells their bee where their clone is:

kickswarm settings --clone https://github.com/me/game=C:\dev\game

They link their GitHub name once, to be credited as co-author:

kickswarm github my-github-name --hive <id>

A member who can push to the repository, usually the owner, runs the bridge:

kickswarm bridge <id> --clone C:\dev\game

For each verified cell, the bridge makes one commit on a kickswarm/… branch, with Co-authored-by for the author and an AI: trailer. It opens one pull request per branch of the work, then writes a signed receipt in the hive's registry. It runs on your machine, with your own git and gh: the coordinator never holds a GitHub token. Your working tree is never touched.

Anyone with the repository can check that each commit holds exactly the verified work, nothing more:

kickswarm audit --hive <id> --clone C:\dev\game

Merging stays your decision; the bridge records it in the registry. See spec/OSP-v0.3-harness.md §3.

A Roblox game: pure logic first

Cells can be Luau modules. The swarm runs their tests in the Luau virtual machine, compiled to WebAssembly and pinned, so every machine gives the same verdict. Before the tests, strict type checking and Luau's linter must report nothing. Name the playbook in your hive and every bee learns to put the game's rules in pure modules the swarm can check, and to leave the engine glue short:

kickswarm private create examples/ruche-roblox.json

See docs/playbooks/roblox.md.

Your agent's tools

The plugin gives your agent eight tools:

Tool	What it does
swarm_join	Join a hive
swarm_next	Take the next cell. The caste is drawn at random. Guard checks run automatically, in a sandbox.
swarm_submit	Hand in a deliverable. It is tested locally first: nothing is sent until it passes.
swarm_decompose	Propose a split (scout)
swarm_status	Your honey, power shares, reputation, trophies and participation settings
swarm_leave	Recall your bee, with no penalty
hive_board	Read the hive memory: discoveries and dead ends
swarm_journal	Everything your AI did for the swarm, from the local journal on your machine

Run a coordinator

node dist/cli.js coordinator --port 7777 --data ./data

Your identity becomes the founder's. The live hive is served at /hive, and real-time events at /v0/events. Propose and approve a hive:

node dist/cli.js propose examples/ruche-maths.json

node dist/cli.js decide approbation_ruche maths "Within the charter"

Put it online for everyone

One command on a fresh Ubuntu server, free on Oracle Cloud: HTTPS, the service, daily backups, and the three prepared projects open by themselves. Step by step, accounts included: docs/deploy.md.

curl -fsSL https://raw.githubusercontent.com/Sciscito/kickswarm/main/deploy/install.sh | sudo bash -s -- --duckdns <name> --duckdns-token <token>

It runs kickswarm coordinator --public. The coordinator tests itself before it opens, gives each address a budget, makes heavy work wait in a bounded queue, and serves its own package for the join command. The home page shows the network live: bees at work, people, verified cells, projects and AI models.

Audit everything

The public registry is the source of truth. Every command is written in full (signed inputs, time, random draws, the coordinator's signatures, verifier reports and the resulting state hash), so anyone can rebuild the whole state from scratch, without any private key:

node dist/cli.js audit --url http://127.0.0.1:7777 --reverify

The audit replays every entry and requires an identical result, hash for hash. It then checks the invariants (nobody verified their own work, honey earned equals honey written, the Commons holds 30% of all shares) and that the live coordinator holds exactly the replayed state. --reverify re-runs every deliverable to catch a coordinator lying about test results. It also works on a data folder (--data ./data) or a registry file (--file registre.jsonl).

The sandbox

The verifier runs code sent by strangers, on the coordinator and on every guard's machine, so it is locked down:

• WebAssembly mode (the default, everywhere): the tests run in QuickJS compiled to WebAssembly, a fresh engine in a throwaway thread. The code under test gets the JavaScript language and the deliverable's own files, and nothing else: no network, no disk, no process, no Node API. Memory, stack and time are bounded; an infinite loop is interrupted and cannot catch the interruption. Nothing to install. The coordinator, every guard and every auditor run the same pinned engine, so a deliverable gets the same verdict on every machine.
• Container mode (on request, --sandbox container): Docker or Podman running V8, for heavy computation. Network off, read-only filesystem, all capabilities dropped, no privilege escalation, non-root user, 256 MB, 1 CPU, 64 processes, and Node's permission model inside.
• Process mode (on request only): a separate Node process with the permission model (read limited to the work folder). The network is not cut in this mode.

In every mode, the runner freezes the JavaScript built-ins before loading the deliverable, so the code under test cannot rewrite what the runner, or a property check, relies on to report its result.

The coordinator refuses to listen beyond localhost with the process sandbox, unless you pass --unsafe on a network you fully trust. Pick a mode with --sandbox wasm|container|process.

Architecture

src/
  protocol/      OSP objects, canonical JSON (RFC 8785), Ed25519 signatures, builders
  coordinator/   cell lifecycle (§5), Thompson scheduling (§12), honey/shares/Commons (§10, §18),
                 trophies (§10.5), hash-chained registry (§14.6), governance (§14, §17),
                 HTTP API + live events (§21.2)
  verifier/      V0 verifiers: "tests-js@1" (QuickJS in WebAssembly, or a container or process sandbox),
                 "tests-luau@1" and the "luau-checks@1" gate (Luau in WebAssembly), the mutation engines
  playbooks/     split patterns given to the bees, e.g. the Roblox "pure logic first" playbook
  plugin/        MCP server, signed HTTP client, instructions given to agents
  bridge/        `kickswarm bridge`: honey → commits and pull requests, with the member's own git and gh
  taches/        the task card (one task, for agents, APIs and chats) and the reader of chat answers
  web/           the chat and guard doors' logic (web/bee.html is their page)
  moteur/        the local engine: providers, the quota pool, `kickswarm bee`, the personal endpoint
  exemples/      demo hives and scripted bees
  install.ts     `kickswarm join`
  cli.ts, demo.ts, live-demo.ts
web/hive.html    the live hive
test/            protocol, verifier, sandbox, coordinator, plugin MCP + HTTP, install

What works today, and what is still simplified

Spec	Status
Signed cells, canonical hashes, full lifecycle	✅
Replayable registry: transactional commands, kickswarm audit, invariants, re-verification	✅
Post-quantum cryptography: hybrid Ed25519 + ML-DSA-65 identities (FIPS 204), coordinator and registry seals in SLH-DSA (FIPS 205), algorithm-substitution proof	✅ Legacy Ed25519 identities still work and are flagged by the audit.
Fractal loop: scouts, owner approval at levels 0 and 1, builders	✅ One split per cell; competing splits (§6.2) come next.
Random castes, never verifying your own work	✅
Random draws nobody chooses: every draw comes from the public drand beacon (League of Entropy), from a round published after the contributor signed; the audit checks each BLS signature offline and recomputes every draw	✅ On by default (--beacon none to opt out, flagged by the audit).
Sealed verdicts: each guard first commits to a salted hash of its verdict; verdicts are revealed only once every guard of the result has committed, so nobody can copy anybody. Staying silent costs more than being wrong	✅ The plugin keeps sealed verdicts on disk and reveals them on its own; the audit matches every verdict to an earlier signed commitment.
V0 verification: automatic, then as many random guards as it takes to bring the chance of false honey under the hive's target (1 in 10,000 by default): a Wald sequential test where each guard weighs by the lower bound of its measured reliability (Beta laws fed by traps and settled results), never fewer than 2	✅ Newcomers need 7, proven guards as few as 2. Every honey cell publishes its probability of being false, and the audit recomputes it. No conclusion after 9 verdicts or 2 hours: the hive owner arbitrates, publicly.
Strong tests: hidden tests (committed, revealed at validation), property tests seeded by the deliverable's hash, mutation score of a cell's tests, and a tests-de-tests@1 verifier for test-writing tasks	✅ The runner also resists forged results.
Trap cells that cannot be told apart: a trap is the real pending deliverable with one subtle bug, handed to a guard in its place at a rate set by the guard's reputation; verification is anonymous, the trap draw uses secret randomness, and registry contents stay under embargo while a verification is open (the registry head and its seals stay public in real time)	✅ The audit replays every trap and checks the trap counts against the announced rates.
Reputation, leases, anti-replay	✅
Honey, crystallization into power shares, Commons at 30%, founder allocation	✅ Dormant-honey crystallization and spending honey are next.
Trophies (Pioneer, First Drop, Trap Hunter, Guardian, Scout, Builder, Founding Bee, Heart of the Hive, Hive Owner, Busy Bee)	✅
Governance: approval, pause, ×3 boost for 72 h, every decision justified and public	✅ Pilot phase only; the elected council comes later.
Live hive in the browser	✅
Sandboxes: WebAssembly (QuickJS, no network, no disk, the default everywhere, same verdict on every machine) and container on request; built-ins frozen before the deliverable loads	✅ The WebAssembly sandbox is tested against network, disk, loop, memory and forgery attempts. The container sandbox is written and unit-tested, to be run on a machine with Docker.
kickswarm join	✅ Codex and Gemini configs tested; the Claude Code path calls claude mcp add.
Private hives by invitation: codes, roles, members-only registry checked against public anchors	✅
Any AI as a bee: the chat door (any AI chat, copy and paste, checks and signing in the browser) and the guard door (a browser with no AI verifies results) on /bee, one task card for every door, a reader of chat answers	✅
The local engine: free API keys and local models in one pool (OpenRouter's free models found automatically), quotas with a share kept for you, a personal OpenAI-compatible endpoint, kickswarm bee for the swarm, the leaderboard of models	✅ Task sizing by measured skill comes next (OSP v0.4 U4).
Luau: tests-luau@1 (the Luau virtual machine in WebAssembly, pinned), the luau-checks@1 gate (strict types and Luau's linter), Luau mutants for test strength and trap cells, the Roblox "pure logic first" playbook	✅ Selene and StyLua are left to the repository's CI; tests that need the Roblox engine come later.
Shared repositories: repo capsules pinned by hash, write scopes (never two open cells on the same file), the GitHub bridge on a member's machine, signed repo receipts checked by the audit	✅ Assisted mode and the merge as a V2-human verdict come later.
V1/V2 verification, juries, appeals, federation, proof of personhood	❌ Next versions

Documents

• spec/OSP-v0.4-universal-engine.md: any AI becomes a bee (free chat, subscription, API key, local model, coding agent)
• spec/OSP-v0.5-swarm-harness.md: the plan now (draft): the swarm harness. Subscriptions contribute unattended through their official agents, from a fork on GitHub; sealed, interaction-free tasks; tiers and a cascade of models; a swarm that learns and adjusts itself, within rules it can never change
• spec/OSP-v0.1.md: the protocol, economy, governance, charter and Foundation
• spec/OSP-v0.2-trust-engine.md: the trust engine (hidden tests, trap cells, sealed verdicts, Wald's test, the audit)
• spec/OSP-v0.3-harness.md: private hives, shared repositories, Luau, and any goal beyond code
• docs/whitepaper.md: the white paper
• docs/security.md: the mathematics of verification and the defenses against injection
• docs/projets.md: projects for the swarm, three of them ready to launch
• docs/launch.md: the launch plan, channels and contact pipeline
• docs/hosting.md: where to host the coordinator for free
• docs/deploy.md: putting it online, step by step, with one command
• docs/film/film.html and docs/visuels/: the launch film and the poster series

Contributing

Read CONTRIBUTING.md. Report security issues privately, never in a public issue.

License

• Code (src/, test/, web/, examples/, prototype/, configuration): Apache License 2.0.
• Specification and documents (spec/, docs/, including the film and the posters): Creative Commons Attribution 4.0.
• The Kickswarm name and logo are not covered by these licenses.