• Choose your path
  • Coding agents
  • Claude Cowork / ChatGPT Work
  • Research
• Installation and first use
• CLI and plugin quick reference
• What you can do with kpopper
• Keep the conversation moving
• Keep your existing knowledge system
• What “deterministically checkable” means
• Go deeper
  • How it works
  • Followups and background checks
  • Optional experimental applications
  • Availability and limits
  • Karl Popper and falsifiability
• Try it, get help and contribute

Claude Code · Codex · Cursor · and more
Explore workflows and examples

Private data exposure

Two agents start from a search service whose results are all public. PR A adds private projects and filters results for each user. PR B adds a shared cache keyed only by the query, relying on those results being public and identical for everyone.

Phone layout

The files merge cleanly. The reason for sharing the cache no longer holds.

The same record retains the surrounding design: query matching, cache behavior, test coverage, operational limits and open questions.

Phone layout · Full design record

A selected excerpt from PR B:

known:
  search.results_public:
    v: true
    from: s.search
    at: INCLUDE_PRIVATE_PROJECTS is false
    measure: search_results_public
  cache.key_fields:
    v: query
    from: s.cache
    at: 'lookup: query not in _CACHE; _CACHE[query]'
  cache.hit_reuses_result:
    v: true
    from: s.cache
    at: 'lookup: return _CACHE[query]'
  cache.test_data:
    v: One mocked public project; no private-result fixture in that test.
    from: s.cache_tests
    at: test_public_query_is_served_once_across_users
judgments:
  search.shared_cache:
    rests_on:
    - search.results_public
    - cache.key_fields
    - cache.goal
    verdict: Search responses can share a cache keyed only by query because all results are public.
    wrong_if: search.results_public == false
    seen:
      search.results_public: true
      cache.key_fields: query
      cache.goal: Avoid a second search for the same public query across users.
  cache.hit_authorization:
    rests_on:
    - search.shared_cache
    - cache.hit_reuses_result
    - cache.miss_delegate
    verdict: Treat cross-user cache hits as depending on the public-results decision, not as a fresh
      authorization check.
    reopened_by: The hit path, key scope or public-results decision changes; review the combined
      path.

known holds values taken from a source or derived from other entries; judgments holds the decisions that rest on them. rests_on names the premise. seen keeps its value at the last review. When the measured value becomes false, wrong_if fires and identifies the cache decision. Source locators and the complete record are in the example.

The opening overview uses a download promise and a retention policy. The complete merge example shows the same 7-versus-30-day conflict across two branches, with executable code, measurement recipes and a separate integration probe.

These are executable examples. Checks cover the assumptions the record declares and the inputs deliberately measured or recorded. The examples on this page retain their compact legacy records, which the native runtime continues to read without migration. New records also preserve immutable history.

Two working modes

The difference is whether sessions share one project context or work against different versions of the code. Both modes support several sessions and competing hypotheses.

GROUNDING.yaml is the readable project record shown below: one shared context in Simple, and a version kept with each branch, including main, in Advanced. New history-backed records also keep their supporting history in .kpopper/; carry that directory with the YAML when sharing or versioning the record.

Phone layout

View the full-size illustration · View the vertical version

Simple — one shared context. Sessions read and contribute to the same project graph. Competing ideas are named hypotheses beside it: several sessions can examine the same proposal, and one session can work on several. For a research project, for example, sessions can read different papers and compare explanations against the same sourced record. Consolidation is how those proposals become part of the shared record: compare them with what it already holds, check the combined dependencies and resolve conflicting claims. A proposal can be folded in, refuted with its reason retained, or left pending.

Advanced (experimental) — branch contexts and shared findings. Each branch's record describes its version of the code. A cache decision on one branch may depend on results being public, while another branch introduces private results. Keeping those premises with their branches lets review check whether the reasoning still holds when the changes are combined. Consolidation reconciles those records: it identifies overlapping subjects and conflicting claims, and checks which decisions need another look under the combined premises. Resolve what needs judgment before folding a proposal in; unresolved hypotheses remain explicit.

[!WARNING] Advanced mode is experimental. Parallel branches can add different entries to the same part of GROUNDING.yaml, leaving an already-checked PR with a merge conflict after another PR lands. Resolving it can trigger another CI run. Automatic conflict-free integration is not implemented. We are keeping the readable file while this remains an open design question: the problem, alternatives and their tradeoffs.

For a supported local record conflict, preview a resolution with kpop consolidate --resolve --dry-run. Competing claims still need a decision.

Knowledge then follows two paths:

• Feature knowledge travels with its branch. Its assumptions, measurements and hypotheses stay attached to the code they describe. Consolidation tests their combination with the target record as part of reviewing the change.
• Shared findings have a continuing path of their own. Shareable findings that apply independently of the feature enter pending_grounding, with their sources and scope. They remain available even if the originating session closes or its worktree is removed.

Suppose a session building an integration discovers a documented change to the vendor's API limit. The feature may be abandoned; the finding can still help the project. Other local worktrees can read it immediately, marked as pending, without waiting for the feature to merge. It appears alongside their branch record; reading it does not adopt it or replace their recorded premises. Their consolidation dry run tests it against that record too, and turns red when accepting it would break a recorded decision, until a person decides the finding.

kpopper Board is this continuing shared-findings area. At the start of meaningful work in an unconfigured Git project, kpopper offers Simple (recommended) with a chosen external shared record, or Advanced (experimental) with branch-specific knowledge. The illustration above explains both. Advanced can keep Board findings local or publish them to a named repository and target through one continuing knowledge PR. A publication choice enables branch and PR updates, not merging; it is remembered across local worktrees. kpop board shows the current mode, selection and publication state.

With the project's publication permission, Board findings accumulate in one knowledge PR. Consolidation reconciles the proposed knowledge with the target record before acceptance; conflicts and changed premises need resolution. Accepted contributions are then verified in the target branch, shown as main above. The same publication branch is reused for the next batch, while the local contribution history persists across review cycles. Local capture and reading also work without publication.

A measurement of an unmerged commit can be a fact about that commit. A proposed conclusion remains a hypothesis. Merging means the team accepted the contribution; it does not prove the claim, increase confidence or refresh its last review. Private material and information whose sharing permission is unclear stay in a structured private draft.

Projects without Git start in Simple; new Git projects currently start in experimental Advanced mode, including those with only one checkout. Simple can also be configured for a Git project with one external shared record. Existing registered shared records keep their current location and behavior; changing mode requires explicit reconciliation.

See project modes and publication for routing, reproducible reads and the publication lifecycle, and consolidation for the dry run, folding and refutation commands.

These project modes also apply to document and research work.

Keep plans current when the brief changes.
Explore workflows and examples

Outdated planning assumptions

A cooking workshop is planned around the venue's shared kitchen, equipment and ingredients. A later client brief moves it entirely online. For ChatGPT Work, see the runtime requirements and current limits.

Phone layout

Once the agent records the new format, kpopper flags the saved plan for review. It does not decide whether the activities can work remotely. The next session can recover the old reason, read the updated brief, and work out what participants need. Try the Cowork example.

The planning record connects 13 readings to five saved plans and four open questions. The format change reaches the agenda, equipment, ingredients, group arrangement and supervision; the earlier review snapshots remain visible.

Phone layout · Full planning record

Selected entries from the after record:

known:
  workshop.format:
    v: remote
    from: s.updated_brief
    at: Participants join online from home
  workshop.participants:
    v: 18
    from: s.session_plan
    at: Client constraints
  workshop.duration_minutes:
    v: 90
    from: s.session_plan
    at: Client constraints
  venue.workstations:
    v: 6
    from: s.logistics_plan
    at: Venue provision
judgments:
  workshop.agenda:
    rests_on:
    - workshop.format
    - venue.shared_kitchen
    - workshop.duration_minutes
    - workshop.recipe
    verdict: Use the shared-kitchen agenda and provide ingredients at the venue.
    reopened_by: The format or access to the shared kitchen changes; review activities, equipment
      and preparation.
    seen:
      workshop.format: onsite
      venue.shared_kitchen: true
      workshop.duration_minutes: 90
      workshop.recipe: Fresh pasta with tomato sauce.
  workshop.equipment_plan:
    rests_on:
    - workshop.format
    - venue.equipment_supplied
    - venue.workstations
    verdict: Plan equipment around the six venue workstations.
    reopened_by: The format, supplied equipment or access to the workstations changes.
    seen:
      workshop.format: onsite
      venue.equipment_supplied: true
      venue.workstations: 6
  workshop.ingredient_plan:
    rests_on:
    - workshop.format
    - venue.ingredients_supplied
    - workshop.participants
    verdict: Prepare ingredient portions at the venue for the 18 participants.
    reopened_by: The format, ingredient provision or participant count changes; review purchasing,
      portions and distribution.
    seen:
      workshop.format: onsite
      venue.ingredients_supplied: true
      workshop.participants: 18

The current value is remote; the decision was reviewed against onsite. That is a MOVED notice. The prose in reopened_by tells the agent what deserves attention; it is not an executable predicate. Read the complete after record.

Before the first answer

The next session opens with the saved context: all five plans need review because workshop.format changed from onsite to remote. Then the user asks:

Prepare the ingredient portions for the 18 participants.

On a host with the prompt hook enabled, this matching prompt produces a focused pointer (actual hook output, shown here with Codex skill syntax):

kpopper: the record holds workshop.ingredient_plan on this - $ground workshop.ingredient_plan before answering from memory.

The agent follows that pointer with pull workshop.ingredient_plan. It retrieves remote, the old venue-based plan and its onsite review snapshot before answering. The next decision is how ingredients will reach participants at home. See the opening and retrieval output.

Keep your existing documents, notes and task tools. The record links back to relevant evidence; there is no need to migrate your knowledge system. For another example that needs judgment, explore a replacement offer with an uncertain deadline.

Connect evidence and revisit conclusions as findings change.
Explore workflows and examples

Dark matter across studies

The original three-paper view shows the shared-record idea:

Phone layout

A research record can connect observations across scales and retain the tensions between them. This worked example follows six papers: Rubin's galaxy rotation, SPARC's galaxy catalog, the radial acceleration relation, Bullet Cluster lensing, Planck's cosmological fit and the first LZ particle search.

Phone layout

The argument includes 36 source readings, two scope readings, one calculation, seven linked judgments and five open questions. Its depth comes from the links: SPARC and the acceleration paper share data; the Planck density ratio comes from one model fit; a null WIMP search constrains specific interactions without settling the identity of the astronomical mass component.

Phone layout · Complete research record · Sources and exact locations

A source-grounded excerpt:

known:
  sparc.sample_size:
    v: 175
    from: paper.sparc
    at: Abstract
    unit: galaxies
  rar.sample_size:
    v: 153
    from: paper.rar
    at: p. 1, Data / Galaxy Sample
    unit: galaxies
  rar.points:
    v: 2693
    from: paper.rar
    at: 'p. 1, Galaxy Sample: velocity-precision cut'
    unit: points
  cmb.omega_c_h2:
    v: 0.12
    from: paper.cmb
    at: Abstract, combined analysis
    uncertainty: 0.001
    confidence: 68%
  cmb.omega_b_h2:
    v: 0.0224
    from: paper.cmb
    at: Abstract, combined analysis
    uncertainty: 0.0001
    confidence: 68%
  lz.si_limit:
    v: 9.2e-48
    from: paper.lz
    at: 'Abstract, version 4: limit at 36 GeV/c^2'
    unit: cm^2
    confidence: 90%
  lz.mass_at_limit:
    v: 36
    from: paper.lz
    at: Abstract, version 4
    unit: GeV/c^2
  cmb.dark_to_baryon_density:
    rule:
      expr: cmb.omega_c_h2 / cmb.omega_b_h2
judgments:
  evidence.shared_catalog:
    rests_on:
    - sparc.sample_size
    - sparc.inputs
    - rar.catalog
    - rar.selection
    verdict: Treat SPARC and the RAR analysis as related evidence, not two independent observational
      votes.
    reopened_by: A different catalog, sample selection or independently calibrated replication changes
      the dependence between these findings.
  synthesis.dark_matter:
    rests_on:
    - galaxy.extended_mass
    - galaxy.baryon_coupling
    - cluster.mass_location
    - cosmology.cold_component
    - particle.search_scope
    - research.framework
    - research.selection
    verdict: Under the stated models, the selected evidence supports a dark-matter account across
      scales, while baryonic regularities and direct-search limits constrain its explanation.
    reopened_by: A source finding or shared assumption is revised, or a worked alternative jointly
      addresses the galaxy, cluster, cosmological and particle-search constraints. Reassess the
      affected paths and the synthesis.

The next session inherits the argument, including its unresolved questions.

Run the checker on that same record:

kpop check examples/dark-matter/GROUNDING.yaml

Its final summary (exit 0; the full response also lists the seven prose review conditions):

7 judgments, 58 entries, 0 problems, 7 declared

For a starting overview use open; to inspect a subject use pull; to trace a premise use affects. The ground skill guides that workflow for an agent.

kpop open examples/dark-matter/GROUNDING.yaml --chars 1000

Six-paper worked example; selected source readings and an authored synthesis, not a complete review or live research-agent evaluation.
holds: rar (8) · research (8) · cmb (7) · lz (6) · paper (6) · sparc (6) · lensing (5) · rotation (5)
58 entries, 7 judgments, 5 open questions, updated 2026-09-19

kpop pull cmb.dark_to_baryon_density examples/dark-matter/GROUNDING.yaml --budget 1100

cmb.dark_to_baryon_density: 75/14 = cmb.omega_c_h2 / cmb.omega_b_h2 (Ratio of the abstract central physical de ...
+ cosmology.cold_component: Within base Lambda-CDM, the fitted physical cold-dark-matter density exceeds the b ...
    holds
    because: The density ratio connects two central values from the same fit. The model assumptions and
             retained lensing-amplitude tension limit the interpretation.
    reopened by: The likelihood, data combination or cosmological model changes enough to alter the inferred c ...

affects <entry> shows what a change reaches

kpop affects research.framework examples/dark-matter/GROUNDING.yaml

cluster.mass_location
    via research.framework -> flagged only
cosmology.cold_component
    via research.framework -> flagged only
galaxy.extended_mass
    via research.framework -> flagged only
synthesis.dark_matter
    via research.framework -> flagged only

4 judgments reached

See all captured commands and responses, including pull synthesis.dark_matter. Here check reports record consistency; the scientific review conditions still require judgment.

The illustrations are schematics drawn from the record. The full example distinguishes source readings, authored interpretations, shared assumptions and the computed 75/14 density ratio. That arithmetic does not establish the scientific synthesis.

Run the shared-record example: three concurrent CLI writers retain the prepared six-paper contributions, and the writer records each judgment's review snapshot. A proposed change of framework then reopens several interpretations and the synthesis. No model call or claim of live independent research is part of that replay.

Inside Claude Code, enter these slash commands one at a time:

/plugin marketplace add ilanbm/kpopper
/plugin install kpopper@kpopper

Or, in a terminal, run the equivalent commands:

claude plugin marketplace add ilanbm/kpopper
claude plugin install kpopper@kpopper --scope user

Both routes install the plugin. The native runtime is a separate required step; ask Claude Code to finish it, or follow the manual runtime setup. That guide explains how to find the installed plugin directory and includes Windows instructions. Start a new session after setup is complete.

In a terminal:

codex plugin marketplace add ilanbm/kpopper
codex plugin add kpopper@kpopper

Install the native runtime in the plugin root printed by codex plugin add using the native runtime setup guide. Then start a new task and review and trust kpopper's hooks when Codex asks. You can also inspect the hook definitions inside Codex with:

/hooks

See Codex setup and behavior.

In a terminal, clone the repository where it can stay:

git clone https://github.com/ilanbm/kpopper.git

Follow the adapter linked above. Add to the agent's existing configuration rather than replacing it. What runs automatically differs by agent; see the capability matrix and verification status.

These commands can record decisions, update project state or configure work. The linked guides describe their arguments and review steps.

See the command reference, history commands, background capture and followups. review records your assessment; it does not make that assessment for you.