Click

English | 한국어 | 简体中文

Keep work inside the approved boundary, and keep valid verification reusable.

Click provides incremental verification for coding agents. It helps constrain unrequested scope expansion through a reviewed Guarded contract, while revision-aware evidence lets valid checks survive a new task. Reuse requires matching execution bindings and, after changes, a complete dependency observation or an explicit policy committed before the baseline. Missing authority means a real rerun, not automatic dependency inference.

Release note: v0.90.0 adds continuous, cost-gated unittest/pytest shard setup, bounded inspection-result caching, and fail-closed native observer profiles.

Click does not prove that the code is correct or that the selected tests are sufficient. It tracks whether existing verification evidence still applies to the current code.

You keep working normally. Click remembers:

• what the agent was asked to do;
• when the workspace changed;
• which checks really ran;
• whether an old result is still safe to reuse.

It does not tell the model how to think or which files to read.

The problem in one example

revision 12  auth code changed   → auth tests run and pass
revision 13  README changed      → auth inputs unchanged, reuse the result
revision 14  auth code changed   → old result is stale, run the tests again

Without a revision-aware record, an agent may trust an old test after the code changed or rerun a large suite after an unrelated edit. Click keeps the result only while the inputs that made it valid still match.

That is the core of Click.

How it feels to use

Click has three modes:

Evidence: the normal default

Evidence mode uses the permissions already provided by Codex or the host. Click does not pretend it approved the work.

The final receipt says:

approval_bound: false
execution_authority: host

Guarded: one approval when the boundary matters

Use Guarded for payments, authentication, deletion, migrations, public API changes, or any task where changing the wrong thing would matter.

The approval view starts with one plain-language contract, not a list of developer fields. For example:

Revision 12 changed src/auth/token.py.
The authentication tests that used this file are affected.
The previous result is now stale, so those tests must run again.
Click will record the changed revision, the affected check, why the old result became stale, and the completion checks.
It only displays this information; the contract excludes test-skipping authority, UI work, and external transmission.
In short: this builds the safe data layer that a future Evidence Map can read.

The original canonical JSON stays hidden unless the user requests the original contract. Viewing it keeps the same contract id and does not approve, change, or restage anything. The approval prompt is equivalent to:

The contract above is explained in plain language. Do you approve it as written, or would you like to see the original contract first?

Approve, request changes, cancel, and view original are all available. Approval happens in a later user turn, and work inside the approved boundary continues without repeated approval prompts.

After A completes, B receives a new contract id and separate approval. A's successful checks are candidates only: B must request and requalify them. Unrelated code can permit partial reuse under an unchanged precommitted policy; related inputs, changed environment, and new checks run. Approval, runner tokens, unfinished work, and completion do not transfer. The Hook does not semantically prove that every implementation stayed in scope.

Install

codex plugin marketplace add grapefruit0205/click
codex plugin add click@click

Restart Codex so its Hooks reload, then start a new task.

New installations use Evidence mode. You can change the default:

click-gate default evidence
click-gate default guarded
click-gate default off

Then ask for work normally:

Refactor the authentication parser and keep its public behavior unchanged.

Or explicitly choose Guarded:

@Click Add order cancellation and prevent duplicate refunds.

Update

Current release: v0.90.0

codex plugin marketplace upgrade click
codex plugin add click@click

Start a fresh task after updating.

See release notes for version history.

What makes evidence reusable?

A result is reused only when its important bindings still match, such as:

• the exact check;
• the relevant files and their contents;
• the workspace state;
• the environment and executable;
• the known host Hook coverage.

If Click cannot establish that match, it runs the check again.

Cross-revision reuse is intentionally conservative. A repository can commit a dependency map:

.click/evidence-dependencies.json

The map declares candidate inputs for a specific check, and concrete paths
remain hard dependencies. It does not authorize reuse by itself. In an approved
Guarded contract, an explicitly enabled authoritative run may refine expanding
patterns such as *, **, and directory prefixes to the inputs that the check
actually consumed. Click hashes every resulting input into the receipt.
Working-tree edits cannot narrow the committed policy. If observation is
unavailable or incomplete, Click runs the check again after a mutation. The map
remains optional; leaving it out also means that the check reruns.

For common changes that are known not to affect a check, such as documentation,
the repository may instead commit an observer-free safe-change policy:

{
  "version": 1,
  "entries": [
    {
      "checks": [["python3", "-m", "pytest", "tests/unit"]],
      "reuse_if_only_changed": ["README.md", "docs/**"]
    }
  ]
}

Save it as .click/evidence-reuse.json. After a successful baseline, Click
records the Git commit plus compact fingerprints for effective uncommitted
files. Before the same exact check runs again, it reports the net changed paths.
It reuses the result only when every path matches the unchanged committed policy;
any unlisted path, policy edit, Git ambiguity, environment or executable change,
or later workspace drift runs the real check. Policy files cannot declare
themselves safe. This path uses only Git and the plugin's Python runtime, so it
does not require a platform-specific observer or another installation on Linux,
macOS, or Windows. The declaration is repository-owner policy, not an inferred
claim that Click discovered every dependency.
A committed Evidence Shards map can split one exact broad suite into independent children, retaining a passed sibling after another fails. The map alone never permits reuse after a mutation; the rules above still decide each child, and an invalid map runs the original suite.

For a supported project, click-gate sharding init, sharding status, and
sharding refresh provide a JSON-free path from command selection to a reviewed
proposal, Evidence application or separately approved Guarded application,
user-owned commit, parent/child bootstrap, and baseline evidence. A measured
cost rule keeps short suites on the parent command. Later test discovery or test
structure changes produce a bounded diff and update only policy that still
matches Click's prior committed digest lineage. User-owned or modified policy is
never overwritten, and Click does not run git add, commit, or push. A
successful bootstrap is setup cost; it reports sharding-ready / reuse-unavailable until every child has a complete authoritative observation. See
automatic sharding setup.
The automatic collector supports bounded unittest discovery and a conservative
pytest collect-only profile on CPython 3.10 through 3.14. Its common process and
locking adapters are implemented for Linux, macOS, and Windows; platform-native
validation status is tracked separately from implementation status.

The two-project setting-free E2E record shows an
actual Guarded A→B module change, partial child reuse, same-final-code audit,
and the retained negative whole-request result for short fixtures.

Observer collection is off by default and independent from the dashboard. Use
click-gate observer off, click-gate observer shadow,
click-gate observer authoritative, or click-gate observer status. Explicit
shadow mode attaches non-authoritative telemetry on its supported Linux,
macOS, and Windows backends; Shadow predictions never authorize a skipped
check. Explicit authoritative mode is available only inside a separately
approved Guarded contract for direct CPython 3.12.3 python -m unittest
checks. The Linux strace 6.8, macOS privileged fs_usage, and Windows inbox
ETW profiles have passed native-host authoritative contract and cross-contract
reuse validation on CPython 3.12.3. The setting-free automatic-sharding E2E
remains Linux-scoped. Each profile
prepares an identity-bound native companion from already installed build
inputs, runs the original check once, and authorizes reuse only for a complete
signed input snapshot. Click installs nothing or elevates no privilege. See the
Authoritative Observer v2 contract.

Use click-gate status for a compact read-only JSON view of verification
progress. It distinguishes checks that ran in the current batch, checks reused
after current-condition requalification, checks that did not run, and checks
that have not been requested. It also reports which registered checks remain,
which are valid for the current mutation revision, and which a mutation
invalidated. This view cannot create reuse authority or complete a task.

During Evidence, approved Guarded work, or read-only review, Click can reuse a
complete result for one explicit local cat, bounded sed -n, or supported
rg request. The cache binds the request, cwd, trusted executable, relevant
environment, file contents, and a conservative directory inventory. Directory
searches also bind applicable project ignore files, so additions, deletions,
renames, and ignore changes miss the old entry and run normally. Cached output
lives only in the owner-readable plugin data directory, expires after 24 hours,
and never becomes verification evidence. Unsupported commands, ambiguous
targets, failures, output over 48 KB, missing entries, and corrupt entries use
the normal read-only runner. For an intentional same-request rerun, use
click-gate inspect with "fresh":true in its version 1 request.

Use click-gate dashboard start, status, or stop for actual verification-group outcomes, batch history and JSON/standalone HTML exports. Planned, started, reused and unstarted groups are distinct; partial processing measurements, full request wait (unknown when unmeasured), baseline-cost estimates and Shadow remain separate. Run python3 benchmarks/incremental_verification.py --iterations 3 --warmups 1 --output /tmp/click-comparison.json, then select that JSON in the viewer for a real hook/runner comparison. Short checks can be slower with runtime overhead. See measurement scope, mode boundaries and exports.

An opened dashboard remains attached to the same host session and workspace across successive Evidence tasks. Each verification group is persisted as soon as it finishes, so an already-passed group remains visible while the next group runs and after cancellation. Viewer connectivity does not carry Guarded approval, runner tokens, unfinished commands, or completion authority into the next task. A completed Evidence task may pass real successful results forward as candidates only; Click rechecks the exact source and check, workspace and mutation boundary, environment, executable, host coverage, and existing dependency or committed safe-change rules. Equal revision numbers, dashboard history, exports, timing, and Shadow predictions never authorize reuse.

Completion receipt

Click can export a receipt after current evidence is complete:

click-gate receipt export
click-gate receipt verify ./completion-receipt.json

The receipt binds request lineage, mutation revision, final workspace, checks, environment, executable identity, host coverage, and reuse lineage. Evidence successors use v4; an applied Guarded successor uses v5 with the origin contract, batch, revision, requalification mode and candidate digest. Merely retaining candidates does not select v5. Legacy v1–v4 remain readable; v5 retains complete shard provenance when present.

Reproduce a completed Guarded A → B workflow

python3 benchmarks/incremental_verification.py --guarded-workflow --iterations 3 --warmups 1 --workload-rounds 40000 --output /tmp/click-workflow.json --html-output /tmp/click-workflow.html

This uses independent real Hook/runner fixtures, not approval in your development session. It compares no Click, explicitly selected Guarded with default reuse settings, and Guarded with precommitted shards/sibling-code policy. Evidence remains the product default mode. The fixed flow includes first run, unrelated/related code, environment change, failure, repair and unchanged retry; every step is audited against the same-state full suite. Warmups, rotating execution order, setup/transition/audit costs and negative timing differences are retained. The offline HTML is the v3 three-configuration report; the existing dashboard importer accepts the older v2 paired report. Neither sample results nor unsigned exports prove universal safety or total development-time savings.

The result-first dashboard shows promises and approval, group outcomes, prior-contract provenance, estimated avoided rerun cost and whether a separate comparison exists. A bounded local display copy of contract summaries is retained; it is not an authority source or guaranteed secret redactor. Shared exports omit contract prose, raw commands, input paths and environment values. Request timing is partial (hook-entry-to-result-recording), not the full host wait. Detailed measurement and privacy boundaries.

Receipt verification currently reports unsigned-integrity-only. It detects accidental or uncoordinated changes to the receipt, but it does not yet prove the publisher's identity.

What Click enforces

Click keeps hard rules for things that need runtime integrity:

• approval and contract identity in Guarded mode;
• one-use execution claims and replay protection;
• mutation revisions and stale-evidence invalidation;
• exact verification receipts;
• managed local service cleanup;
• receipt integrity.

Suggestions about exploration, retries, planning, and verification depth remain advice. They do not block the model's search strategy.

Antigravity

The repository also ships an experimental Google Antigravity adapter:

agy plugin install ./dist/antigravity

The adapter supports the same Evidence and Guarded model through Antigravity's available Hook surface. Host coverage is reported honestly; unsupported paths are not described as independently observed.

See the Antigravity adapter guide.

Honest limits

Click is a workflow guardrail, not an operating-system sandbox.

It cannot prove hidden reasoning, semantic correctness, unmatched external tool activity, or the quality of a test chosen by the model. Hosted and manual evidence outside a matched Hook is recorded as an attestation rather than independent observation.

Use normal code review, CI, branch protection, deployment controls, and security boundaries where they belong.

Technical reference

The README stays short on purpose. Protocol and architecture details live here:

• Product Constitution
• Guard classification
• Operating modes
• Guarded contract format
• Verification profiles
• Capability protocol
• Authoritative Observer v2, Shadow Observer v1, Shadow Intelligence v1, and Evidence Shards v1
• Anti-loop policy

License

MIT