agentleFS
tamdogoodtamdogood/parler-protocol/AGENTS.md

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.

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
  1. Very specific:

    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).

    line 145

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.md for 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)

CrateRole
parler-protocolWire frames + types; transport-agnostic standard. canonical_card_bytes for signing.
parler-authnkey/Ed25519 identity, sign/verify, NATS JWT issuance (NATS path is deferred).
parler-hubWebSocket bus + embedded SQLite store (directory, rooms, FTS5 memory) + REST API.
parler-connectorThe MeshAgent client core + MeshTransport seam + WS HubClient, plus ConnectorRuntime for attention-aware receive and host wake injection. Shared by CLI & MCP.
parler-cliparler subcommands (including the visible conversation adapter, connect, autonomous work daemon, and optional local supervise runner) and the parler mcp stdio server.
parler-binThe umbrella parler binary.

Where to read next (docs/)

TopicDoc
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 mapdocs/communication.md
Visible-host adapter parity, scaling bounds, and provider extension checklistdocs/visible-host-adapters.md
Multi-agent patterns (chaining, routing, parallel fan-out) as recipes over Parler verbsdocs/patterns.md
Task lifecycle — status updates + signed receipts for dispatched workdocs/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 queuesdocs/agent-mesh.md
Autonomous body agents, attention, role anycast, host wake boundarydocs/autonomous-runtime.md
Share a live conversation with your teammates (hackathons, group projects)docs/team-sessions.md
Signed cards, visibility, directory API, security modeldocs/discovery.md
A2A interoperability — project signed cards into A2A Agent Cardsdocs/a2a-interop.md
Code handoff via content-addressed git bundlesdocs/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 mismatchesdocs/troubleshooting.md
Storage internals, scaling ceilings, retention, sqlite-vec roadmapdocs/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:7070

CI 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 warnings must 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. Run make ci until green before declaring done.
  • Review before landing. Self-review your diff against docs/code-review-guidelines.md. In Claude Code the parler-review skill or the code-reviewer agent (.claude/agents/code-reviewer.md) runs it; other tools follow the doc by hand.
  • Protocol is a contract. Changing parler-protocol frames/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 phantom parler_* tool reference in the docs fails test_docs_reference_only_real_tools (part of make 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 conversation parity additionally requires a native visible wake/injection adapter. Follow docs/visible-host-adapters.md and 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 is private by 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-blog skill in .claude/skills/write-blog/ (invoke it in Claude Code, or read its SKILL.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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.