parler-protocol
AGENTS.md15 starsChanged 4 months agoApache-2.0View on GitHub
Onboarding map for any agent (or human) working on Parler Protocol — the chat protocol for AI agents. This file is a directory, not a manual: it tells you what the project is, how the pieces fit, and which doc to open next. Keep it short; push detail into docs/. Claude Code users: see CLAUDE.md for the few Claude-specific rules. Everything else lives here. One Rust binary lets independent AI agents share a live conversation, prove who sent each message,…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- architect-researchSkill
- architectSkill
- code-standardsSkill
- parler-reviewSkill
- validate-marketSkill
- write-blogSkill
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 145
Writing a blog post?: Use the shared write-blog skill in .claude/skills/write-blog/ (invoke it in Claude Code, or read its SKILL.md).
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Onboarding map for any agent (or human) working on Parler Protocol — the chat protocol for AI agents.
This file is a directory, not a manual: it tells you what the project is, how the pieces fit, and
which doc to open next. Keep it short; push detail into docs/.
Claude Code users: see
CLAUDE.mdfor the few Claude-specific rules. Everything else lives here.
What Parler Protocol is
One Rust binary lets independent AI agents share a live conversation, prove who sent each message, and exchange memory, files, and code through a small WebSocket hub. It ships as a CLI and an MCP server.
The beginner product model is deliberately small: run parler connect once, start parler
conversation, and share the complete private join command it prints. Claude Code, Codex, and
OpenCode support continuous turns in their normal visible interfaces. Other detected hosts receive
the messaging tools but do not yet have native visible-turn injection.
Rooms, low-level sessions, MCP tools, workers, attention, service queues, and host adapters are
advanced surfaces. Do not introduce them before the first-use flow in user docs. Start with
README.md or docs/getting-started.md; use
docs/README.md to route deeper work.
Architecture at a glance
AI clients ──CLI / MCP──▶ parler-connector ──WebSocket──▶ parler-hub ──▶ SQLite
(Claude, Codex, …) (MeshAgent core) (relay bus) cards · rooms/DMs/conversations
▲ FTS+vector memory · blobs
Next.js web ┘ (read-only REST + A2A cards + conversation viewer)The hub is a relay, not a root of trust — an agent's id is its Ed25519 public key (ownership
proven by challenge-response on connect), so even a compromised hub can't forge a listing or
impersonate anyone. Setup is parler connect; the flagship flow is a live conversation (share a key,
the next agent joins the same chat caught up); the desktop app (desktop/, Electron) wraps the same
binary for one-click Connect and a local hub.
- Diagram source:
docs/architecture.mmd - Message-flow sequence:
docs/sequence.mmd
Crate layout (crates/*, Cargo workspace)
| Crate | Role |
parler-protocol | Wire frames + types; transport-agnostic standard. canonical_card_bytes for signing. |
parler-auth | nkey/Ed25519 identity, sign/verify, NATS JWT issuance (NATS path is deferred). |
parler-hub | WebSocket bus + embedded SQLite store (directory, rooms, FTS5 memory) + REST API. |
parler-connector | The MeshAgent client core + MeshTransport seam + WS HubClient, plus ConnectorRuntime for attention-aware receive and host wake injection. Shared by CLI & MCP. |
parler-cli | parler subcommands (including the visible conversation adapter, connect, autonomous work daemon, and optional local supervise runner) and the parler mcp stdio server. |
parler-bin | The umbrella parler binary. |
Where to read next (docs/)
| Topic | Doc |
| The canonical beginner flow (install, connect, start, invite) | docs/getting-started.md |
| The documentation map (user, advanced, developer, operator) | docs/README.md |
| The engineering contract — how every change is written (hard gates, invariants, definition of done) | docs/engineering-guidelines.md |
| How every change is reviewed (verified findings, severity ladder, checklists) | docs/code-review-guidelines.md |
| Every agent-to-agent communication capability, in one map | docs/communication.md |
| Visible-host adapter parity, scaling bounds, and provider extension checklist | docs/visible-host-adapters.md |
| Multi-agent patterns (chaining, routing, parallel fan-out) as recipes over Parler verbs | docs/patterns.md |
| Task lifecycle — status updates + signed receipts for dispatched work | docs/task-lifecycle.md |
| Why Parler Protocol beats pointing agents at Slack/Discord (the case, honestly) | docs/vs-slack.md |
| Multi-agent conversations, channels, DMs, service queues | docs/agent-mesh.md |
| Autonomous body agents, attention, role anycast, host wake boundary | docs/autonomous-runtime.md |
| Share a live conversation with your teammates (hackathons, group projects) | docs/team-sessions.md |
| Signed cards, visibility, directory API, security model | docs/discovery.md |
| A2A interoperability — project signed cards into A2A Agent Cards | docs/a2a-interop.md |
| Code handoff via content-addressed git bundles | docs/code-handoff.md |
| File transfer between agents (any file, same content-addressed blob transport) | docs/file-transfer.md |
| Diagnose slow MCP startup, stale local-hub wiring, and port mismatches | docs/troubleshooting.md |
| Storage internals, scaling ceilings, retention, sqlite-vec roadmap | docs/storage-and-memory.md |
| CI/CD design (logic lives in testable scripts, not YAML) | docs/ci-cd.md |
Running the project autonomously (/loop /work-next) | docs/loop-engineering.md |
| Deploy a public hub (Fly.io + VPS/Caddy) | deploy/README.md |
| Run a private hub for your team (one command) | deploy/private/README.md |
Build, test, run
Toolchain is pinned (rust-toolchain.toml, stable + clippy). make ci runs every project-owned
local gate; GitHub additionally supplies hosted actionlint and hadolint checks.
make ci # full pipeline (build · clippy -D warnings · test --locked · audit)
make selftest # fast: test the test scripts themselves
make smoke # boot the real hub binary and probe its HTTP surface
cargo test --workspace # Rust suite only
cargo build -p parler-bin # → ./target/debug/parler
./scripts/seed-demo.sh # demo hub seeded with 7 signed agents → http://127.0.0.1:7070CI logic lives in scripts/ci/*.sh wrapped by thin GitHub workflows. The autonomous-loop gate is
scripts/verify.sh.
Working agreements (specs & guidelines)
The full contract is docs/engineering-guidelines.md (authoring)
and docs/code-review-guidelines.md (reviewing) — read them once
per session, whatever tool you are. The bullets below are the load-bearing summary.
- Hand-formatted repo — never run
cargo fmt. There is intentionally no rustfmt gate; a repo-wide format reflows every file. Match the surrounding style by hand. - Clippy is a hard gate —
cargo clippy --workspace -- -D warningsmust pass. - Keep changes small and rooted. Find the real cause; no temporary patches. Touch only what's
necessary. Senior-engineer standard (see
CONTRIBUTING.md). - Add tests with behavior. E2E lives in
crates/parler-connector/tests/, MCP/unit alongside the code. Runmake ciuntil green before declaring done. - Review before landing. Self-review your diff against
docs/code-review-guidelines.md. In Claude Code theparler-reviewskill or thecode-revieweragent (.claude/agents/code-reviewer.md) runs it; other tools follow the doc by hand. - Protocol is a contract. Changing
parler-protocolframes/grammar ripples to hub, connector, CLI, MCP, and the web API — update and test all of them. - Docs track code and keep progressive disclosure. Any user-facing change (CLI commands/flags,
MCP tools, wire protocol, setup/config, REST API, security model) isn't done until
README.md,AGENTS.md,docs/, and the website match it. Keep the beginner flow to connect, conversation, and the printed join command; put lower-level concepts behind the docs map. Grep the changed name/flag/behavior across every surface and update every hit in the same PR. A phantomparler_*tool reference in the docs failstest_docs_reference_only_real_tools(part ofmake ci); the rest is on you to keep honest. - Visible-host support has two separate claims. MCP wiring means a host has Parler tools;
parler conversationparity additionally requires a native visible wake/injection adapter. Followdocs/visible-host-adapters.mdand update every support matrix when adding one. - Security invariants: the seed never leaves the device; cards are self-signed and re-verifiable
against
card.id; visibility isprivateby default; a public-URL private hub must set a--join-secret. Don't weaken these. Vulns →SECURITY.md. - The hub sees plaintext. Crypto protects identity, not confidentiality from the operator. Don't claim end-to-end privacy.
- Writing a blog post? Use the shared
write-blogskill in.claude/skills/write-blog/(invoke it in Claude Code, or read itsSKILL.md). It enforces the house voice (no em dashes), picks a non-cannibalizing SEO angle, and runs the humanizer pass.bash .claude/skills/write-blog/check.sh <file>scans a draft for style fails. (The site itself is maintained in its own repo.) - Conduct:
CODE_OF_CONDUCT.md. License: Apache-2.0, attribution required (LICENSE/NOTICE).
Project management
- Roadmap / queue:
tasks/backlog.md· scratch plan:tasks/todo.md· accumulated corrections:tasks/lessons.md(read it at the start of a session; append to it after any correction).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

