parler-protocol

Imported from tamdogood/parler-protocol (AGENTS.md). Install upstream with npx skills add tamdogood/parler-protocol. Copyright stays with the author.

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)

Where to read next (docs/)

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