CHAP_PARTICIPANT — The participant every call is made as. Defaults to agent:assistant, the agent a create-chap-app mcp-gate project joins. A call naming anyone else is refused, and so is a human: URI here, since a person decides in a desk.
CHAP_DB_PATH — Path to a SQLite file; a leading ~ is the home directory. Without it, and without --url, the coordinator runs in memory and workspaces are lost when the client restarts.
CHAP_PROFILES — Comma-separated CHAP profiles enabled on new workspaces. Defaults to Core plus review, whisper, deliberation, handoff, control, routing, modes and audit-scitt.
O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
Work is moving towards teams in which hundreds of agents and hundreds of people take part. Agents draft, triage and recommend; people approve, correct, overrule and escalate. Those human decisions make the work accountable, yet they are usually recorded only in chat threads, ticket comments and memory.
CHAP, the Collaborative Human Agent Protocol, is a MCP/A2A-compatible runtime for auditable human-agent work: approvals, overrides, handoffs, escalation and verifiable evidence logs.
Apache-2.0
Chave de API
CHAP_PARTICIPANT, CHAP_DB_PATH, CHAP_PROFILES
Última verificação
2026-10-27
Estrelas
121
Ferramentas
—
Disponibilidade
—
CHAP gives those decisions a defined structure and an auditable record: what the agent produced, what the person decided and why, in one log that can be queried and verified.
Structured overrides. When a person edits an agent's work, the edit is recorded with a diff, a rationale and tags your team defines, so corrections can be analysed later.
A tamper-evident log. Every change is recorded in order. With the hash chain on, an altered entry is detected on verification, provided a recent chain head is kept out of the operator's reach (SECURITY.md §5). The history survives key rotation, expired vendor logs and staff changes.
Signatures and identity. Optional extensions, called profiles, require every call to be signed, bind signing keys to verified identities, and submit entries to a transparency log.
Alongside MCP and A2A. MCP connects agents to tools and A2A connects agents to each other; CHAP records the work agents share with people.
Concepts
CHAP is a protocol: a set of calls that agents, people and their tools send to a coordinator, the service that mediates a workspace. The coordinator checks each call against the workspace's rules, answers it, and records each accepted change in the workspace's audit log. The TypeScript and Python packages below are coordinators, to embed in your own process or run as a server.
Term
What it is
Workspace
A named context for one body of work: its members, its tasks, and the profiles it uses
Participant
A member, named by a URI such as human:[email protected] or agent:triage; group: names a set of members
Task
A unit of work, assigned to a participant
Artefact
What a participant produces in a task: a draft, a decision, an override
Envelope
One call, as a JSON-RPC 2.0 message; its method is the verb, such as task.create or decide.approve
Audit log
The ordered record of every change to the workspace; with the hash chain on, each entry carries the hash of the one before it
The verbs read as their names. A task is created, completed and sent for review (task.create, task.complete, review.request). A reviewer approves, rejects or overrides it (decide.approve, decide.reject, decide.override). Work is handed off or escalated (handoff.propose, escalate.raise), and audit.read returns the record.
Core and profiles. Every coordinator implements Core (core/1.0): workspaces, participants, tasks and the audit log. Everything else is an optional profile, named with its version. review/1.0 adds review requests and decisions. Others add quick questions to a person (whisper/1.0), group votes (deliberation/1.0), handoffs (handoff/1.0), pausing and rollback (control/1.0), routing (routing/1.0), shadow and trial modes (modes/1.0), signed calls (security-signed/1.0), verified identities (identity-oidc/1.0, identity-vc/1.0) and a transparency log (audit-scitt/1.0). A workspace advertises the profiles it uses, and the coordinator refuses calls that belong to any other profile. core/SPEC.md fits Core on one page, profiles/PROFILES.md lists the profiles, and GLOSSARY.md defines every term.
Install
Libraries. Each package implements Core and every profile; a new workspace advertises core/1.0 and review/1.0 unless you name others.
npm install @brightbeamai/chap-coordinator
pip install chap-coordinator
A new project.create-chap-app generates one with a review desk, one profile setting and a diff-profiles command:
npx create-chap-app my-gate
cd my-gate && npm install && npm run demo
The default template is the code gate: each change a coding agent makes in a git repository is reviewed as a diff, approved with the reviewer's signature, and committed with the evidence beside it for CI to verify. The other templates are an MCP gate for Claude Desktop, Cursor and Claude Code, a support desk, an outbound approval gate and a production set. docs/profile-explorer.md shows what each profile changes.
From a clone of this repository.START_HERE.md runs a local review desk on the Python coordinator, with Python 3.10 or later and nothing else to install:
git clone https://github.com/BrightbeamAI/chap.git && cd chap
python3 start-here/start.py
A solo developer reviews pull requests with Cursor, and the bot flags a warning the developer disagrees with. The clip shows the exchange in six steps, in about 23 seconds.
The code for each step follows, in TypeScript and Python.
// The review Cursor returned.
const cursorReview = {
comments: [{ severity: "warning",
body: "Unused parameter." }],
};
// The bot's review is the output of a task.
const { task_id } = coord.api.task.create({
workspace: "wsp_pr_reviews",
from: "agent:cursor#v1",
assignee: "agent:cursor#v1",
kind: "code_review",
input: { pr_id: "PR-482" },
});
coord.api.task.complete({
workspace: "wsp_pr_reviews",
from: "agent:cursor#v1",
task_id,
output: cursorReview,
});
coord.api.review.request({
workspace: "wsp_pr_reviews",
from: "agent:cursor#v1",
task_id,
artefact: cursorReview,
to: "human:me@local",
});
// You disagree with one comment. Override it.
coord.api.decide.override({
workspace: "wsp_pr_reviews",
from: "human:me@local",
task_id,
intent_preserved: true,
diff: [{ op: "replace",
path: "/comments/0/severity",
value: "info" }],
rationale: "False positive. Framework " +
"convention, not a bug.",
tags: ["false-positive",
"framework-pattern-misread"],
});
# The review Cursor returned.
cursor_review = {
"comments": [{"severity": "warning",
"body": "Unused parameter."}],
}
# The bot's review is the output of a task.
r = send("task.create", {
"workspace": "wsp_pr_reviews",
"from": "agent:cursor#v1",
"assignee": "agent:cursor#v1",
"kind": "code_review",
"input": {"pr_id": "PR-482"},
})
task_id = r["result"]["task_id"]
send("task.complete", {
"workspace": "wsp_pr_reviews",
"from": "agent:cursor#v1",
"task_id": task_id,
"output": cursor_review,
})
send("review.request", {
"workspace": "wsp_pr_reviews",
"from": "agent:cursor#v1",
"task_id": task_id,
"artefact": cursor_review,
"to": "human:me@local",
})
# You disagree with one comment. Override it.
send("decide.override", {
"workspace": "wsp_pr_reviews",
"from": "human:me@local",
"task_id": task_id,
"intent_preserved": True,
"diff": [{"op": "replace",
"path": "/comments/0/severity",
"value": "info"}],
"rationale": "False positive. Framework "
"convention, not a bug.",
"tags": ["false-positive",
"framework-pattern-misread"],
})
The two surfaces. TypeScript ships a typed facade, coord.api.*, so every method has autocomplete and compile-time checks. Python keeps the JSON-RPC envelope on the surface, coord.dispatch({...}), wrapped here in a send() helper, the idiom the Python tests use. Both send the same parameters in the same envelope, so the audit chain reads the same whichever client made the call.
The repository ships the script in both languages. It reads the audit chain over HTTP or straight from your SQLite file:
# TypeScript reference, against the SqliteStore from step 1:
$ npx tsx reference/core-plus-review/analyze-overrides.ts --db ./chap.db wsp_pr_reviews
# Python reference, same idea:
$ python3 reference/python/analyze_overrides.py --db ./chap.db wsp_pr_reviews
Override Learning Report
========================================
Workspace: wsp_pr_reviews
Total overrides: 47
By tag:
false-positive ████████████████████ 31 (66%)
framework-pattern-misread ██████████████ 22 (47%)
cosmetic-pref █████ 8 (17%)
Intent breakdown:
refining (same decision, better wording) 41
substituting (different decision) 6
Top reviewers:
human:me@local 47
Hint: the most common tags are your next prompt revision targets.
The most common tags name what the next prompt revision for Cursor should fix.
chap-analytics (pip install chap-analytics) loads the whole chain into documented pandas tables, from a SQLite file, a JSON export, a live coordinator or an audit.read: overrides, decisions, reviewers, whispers and handoffs. A notebook works through a week of review data, and ANALYTICS_ROADMAP.md describes the planned work.
The override envelope
The override envelope records a reviewer's change to an agent's output. Each field is annotated below:
Two fields matter most for analysis:
intent_preserved tells a refining override, where the person kept the agent's decision and rewrote its wording, from a substituting one, where the person decided differently. Each points at a different fix: many refining overrides around one policy clause point at the agent's retrieval; many substituting ones point at an ambiguous policy, or at the agent's task context.
tags are the small, controlled vocabulary your team agrees on. They are what you will count by three months from now, to answer which prompts need work? and which paths does the bot keep getting wrong?
Status
CHAP 0.3 is a public draft: a small Core and optional profiles (SPECIFICATION.md).
Two reference coordinators, in TypeScript and Python, implement the same methods, and a differential fuzzer checks that they answer and log alike.
The conformance harness covers Core and review/1.0, and runs against the Python coordinator and a standalone TypeScript server.
A coordinator can present itself as an MCP server or an A2A agent.
Framework bridges put LangGraph, Pydantic AI, AG2, LlamaIndex Workflows and Google ADK human-in-the-loop decisions on the audit log.
Before 1.0, a minor release may break things, and its changelog lists each break with a migration; from 1.0 the specification follows Semantic Versioning. For strict stability, wait for 1.0: ROADMAP.md sets out what it will promise and the milestones on the way.
The architecture, profile semantics and threat model, with the scenarios as JSON traces
Cite
If you reference CHAP in academic or technical work, please cite the technical report.
@techreport{chap2026,
author = {Shahid, Arsalan and Suttie, Gordon and Black, Philip},
title = {Collaborative Human-Agent Protocol (CHAP): An open protocol for auditable, structured multi-human and multi-agent collaboration},
institution = {Brightbeam AI},
year = {2026},
type = {Technical Report},
number = {arXiv:2606.09751},
url = {https://arxiv.org/abs/2606.09751}
}
CC BY 4.0 (specification text, see LICENSE-SPEC.md) · Apache 2.0 (everything else) · Any language, any deployment.
C
Chap
BrightbeamAI·121 estrelas·
CHAP, the Collaborative Human Agent Protocol, is a MCP/A2A-compatible runtime for auditable human-agent work: approvals, overrides, handoffs, escalation and verifiable evidence logs.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Chap?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Chap precisa de uma chave de API?
O publicador lista estas variáveis de ambiente: CHAP_PARTICIPANT, CHAP_DB_PATH, CHAP_PROFILES.
Qual transporte Chap usa?
Chap roda localmente via stdio.
Quando Chap foi verificado pela última vez?
Última verificação: 2026-10-27. CHAP, the Collaborative Human Agent Protocol, is a MCP/A2A-compatible runtime for auditable human-agent work: approvals, overrides, handoffs, escalation and verifiable evidence logs.