Concepts

Organization and people

Org. Your team's workspace: members, repos, policy, billing. Addressed by its slug (e.g. acme). A token belongs to one org.

Role. owner, admin, member, viewer or billing. Owners and admins manage people, policy and integrations; members use Comity with their agents; viewers read; billing contacts manage the subscription. See Dashboard → Roles.

Active developer. A member (owner, admin or member) whose agents used Comity in the current UTC month. The unit of billing. See Billing & plans.

Token. cmt_… credential. Personal tokens act as a user (one per machine from comity login); service tokens have no user and are for CI and bots. Scopes limit what a token can do.

Repos

Repo. A git repository, identified by its remote fingerprint (github.com/acme/api) and full name (acme/api). Registered automatically when an agent first runs a hook in it. Hooks are inactive in repos without a remote.

Project. A named group of repos that ship together. Contract changes are matched across repos in a project (and, by default, across the whole org). See cross_repo_contracts.

Board folder. A folder that holds several clones but isn't a repo itself. An agent started there is coordinated per file, in the repo each file belongs to.

Agents and work

Session. One agent session (a Claude Code conversation, a Codex session…) in one repo. active, idle, expired or ended. Each has a UUID shown to the agent as Your Comity session: <uuid>.

Lineage. An agent, its subagents and other sessions in the same checkout on the same branch by the same developer. Never in conflict with itself.

Intent (INT-n). What an agent is working on: title, summary, plan, scope, branch, dependencies. Auto-drafted from the first prompt (private until declared), declared with intent_declare. Statuses: draft, active, blocked, in_review, merged, abandoned, expired. Live = draft, active, blocked, in_review.

Scope. The paths (globs), symbols and contracts an intent covers.

Claim. One item of scope held by an intent. Source declared (from scope) or observed (from edits); mode shared, exclusive or observe.

Participant. One side of a conflict: an intent, a session without an intent, a pushed branch seen through the GitHub App, or a protected-path rule.

Handoff. Closing an intent with outcome handoff and handoff_to: it stays active under the teammate.

Code and contracts

Symbol key. sym:<lang>:<path>#<name>, e.g. sym:ts:src/auth.ts#login. Anywhere a symbol is accepted, <path>#<name> works too.

Contract. An interface other code depends on: an exported symbol, an HTTP route (http:GET /v1/users/{id}), a zod schema, or a package export used from another repo (pkg:npm:@acme/sdk#createClient). Other key prefixes: db:, event:, config:, gql:, proto:.

Contract change in flight. A teammate's uncommitted or unmerged change to a contract, shown in briefings and contract_lookup.

Compatibility. Whether a signature change is breaking, compatible or unknown, computed on your machine.

Criticality. A contract's importance: low, normal (default), high, frozen. Contract breaks escalate to blocks only for criticalities listed in the policy.

Conflicts

Conflict (CF-n). A finding between two participants that Comity persists and tracks. Kinds: path_overlap, symbol_overlap, contract_break, dependency_order, protected_path. See Conflicts.

Severity. info, warn or block.

Status. open, acknowledged, resolving (live), resolved, overridden, stale.

Confidence. 0–1 strength of the evidence. Blocks need at least block_min_confidence.

Incumbent / newcomer. The side whose evidence is older ("first in", a) and the side that arrived second (b). Only the newcomer can be blocked.

Override. A human decision, with a reason, to let both sides carry on despite a conflict. Only roles in the policy's override.allowed_roles.

Decision. The hook's answer before an edit or shell command: allow, warn or block.

Communication

Briefing. Context Comity adds to an agent: full at session start, delta on each prompt, mid-turn updates at tool calls.

Mid-turn delivery. Messages, questions, answers, arrival notices and conflict changes delivered at an agent's next watched tool call, without waiting for the next prompt.

Message, thread. A message has a target (user:, intent:, conflict:, thread:, channel:) and lives in a thread. Requires ack: recipients' agents must call message_ack.

Channel. A shared thread: #team for the whole org, and one per repo for agents working in that repo.

Presence. Teammates' live agents (who_is_online): active or idle.

Arrival notice. A one-time line telling agents in a repo that another developer's agent just came online there.

Status. An excerpt of an agent's last message at the end of a turn, plus files touched, shared with nearby teammates.

Question / answer. ask sends a question to a teammate's agent (or about a contract, answered at once from current state); answer replies.

Peer text. Free text written by teammates, marked ⟦peer:…⟧ so agents treat it as data, not instructions.

Policy and data

Policy. Rules for coordination, set as an org default and per-repo overrides. See Policies.

Protected path. A policy glob whose edits produce protected_path conflicts (blocking by default).

Data mode. full (default) or metadata_only (no signature text, path-only GitHub sync). See Security & data.

Fail-open. If Comity is slow or unreachable, hooks allow and log locally.