flip

Help your agent be a reporter, not a stenographer

Deep-research agents hand you a fluent report and a list of URLs. flip keeps the record underneath: every source captured and judged, every claim at an honest status, every open question named, in plain files that outlive the session.

flip's CLI tools and skills help agents assess the quality of the research they build on, track the provenance and validity of claims, formulate and refine research questions, and pursue complete answers. You steer the research; the agent maintains the record.

The spec defines a notebook format agent harnesses can operate: a conformant OKF bundle that also opens as an Obsidian vault.

In Claude Code, Codex, or another agent harness, the agent operates flip: it captures the material the work relies on, records how each source was judged, keeps claims and questions at honest states, and leaves an attributed trail in plain files. Humans rarely need to type the CLI commands.

See flip in action · Explore real notebooks · Give flip to your agent · Get started

Start with your agent

Put flip to work in your repository

Hand the orientation guide to your agent.

Install for your harness

Install the plugin in Claude Code:

/plugin marketplace add lyra-forge/marketplace
/plugin install flip@lyra-forge

Or in Codex:

codex plugin marketplace add lyra-forge/marketplace
codex plugin add flip@lyra-forge

Start a new agent session after installing. The plugin ships ten procedural skills covering notebook practice plus reusable workflow and plugin authoring. The harness guide explains the custody-hook difference between Claude Code and Codex.

To use the CLI directly, install the PyPI package as a standalone Python 3.12+ tool (the package is flip-notebook; the command is flip):

uv tool install --python 3.12 flip-notebook
flip --version

If the shell cannot find it, run uv tool update-shell and open a new shell. The getting-started guide also covers pipx, URL capture setup, upgrades, removal, and the first verification.

When the first flip-backed investigation starts, the creation skill checks whether the flip CLI is available and guides its one-time installation as a standalone tool if needed. The executable enforces the notebook contract; the human does not have to assemble the two layers up front.

Other harnesses can read AGENTS.md as the runtime-neutral contract and load the plain SKILL.md files directly or through the spindle package named flip.

Use it conversationally

You: People keep saying NJ school enrollment dipped in the pandemic. Did it? Did it come back? Use flip so someone else can audit and continue the work.

Agent: starts a notebook, captures four NJ DOE enrollment files, grades them, computes the totals two independent ways, records three verified claims, answers the question, and opens the logical follow-on: what is driving the more recent decline?

What remains is not a transcript or a final report. It is a browsable notebook with the captured workbooks, hashes, derivations, claims, question journey, session record, and named actor. Read the real notebook or browse its rendered form.

Useful directions include:

• “Start a pursuit notebook for this question.”
• “Capture that before relying on it, then tell me how strong it is.”
• “What did this evidence answer: the question as worded, a narrower one, or an adjacent one?”
• “Try to disprove the load-bearing claims and record the probes that fail too.”
• “Keep the unresolved branch open and say what would resolve it.”
• “Hand this off so a cold agent can continue without reconstructing the trail.”

The full harness guide is docs/claude-code.md.

What flip changes

Work the question, not just the first answer

A polished report is not the research record. In a 2026 benchmark of 100 deep-research tasks, the best evaluated system achieved 0.55 overall F1 and systems covered only about half of the necessary search queries (LiveDRBench). In DeepTRACE's dated August 2025 snapshot of 303 questions and 2,727 system-query samples, evaluated deep-research configurations were one-sided on 54.7%–94.8% of debate queries, while citation accuracy ranged from 31.4%–79.1% (DeepTRACE).

flip makes the route durable: follow-on questions, corroboration gaps, closer reads, recomputations, failed tests, narrower and adjacent answers, reopen conditions, and bounded continuation work remain available to the next session.

Keep useful signals without promoting them prematurely

Capture and judgment are separate acts. A source can be held but ungraded; a promising synthesis can remain a grade-C lead; a claim can be asserted, challenged, corroborated, superseded, or rejected; an audience's belief can be recorded without becoming the notebook's belief. Ungraded material counts toward nothing, but it is not thrown away merely because it needs more work.

Claims record more than truth status. Tests say which error they looked for and how it would have appeared. Stances say what someone is doing with a claim. Absence claims name the surfaces searched, because a null is only as strong as its coverage.

Let the research outlive the session, agent, or model

Every source, claim, decision, question, and session is a Markdown page with an immutable id. Every event names its actor. Raw captures and hashes establish custody; append-only JSONL preserves history; generated views provide a bounded cold-start surface. Different agents can continue the same notebook without silently replacing one another's reasoning or reconstructing the investigation from chat logs.

At rest, a notebook is a conformant Open Knowledge Format (OKF v0.2) knowledge bundle. It works in Git, opens as an Obsidian vault, and remains readable with less if flip disappears.

Real notebook outcomes

• Data investigation: the NJ schools notebook captured four state workbooks, found file oddities, recomputed totals two ways, corrected the popular pandemic framing, and opened a more consequential follow-on question.
• Literature review: the RAG/hallucination review froze criteria before searching and preserved its denominator—2,600+ records identified, 31 examined, seven advanced, four excluded, three included—including a canonical paper excluded on license alone.
• Honest non-answer: the EV-charger pursuit distinguished failed-visit data from measured uptime, answered the narrower question, left the national trend unresolved, and armed conditions that should reopen it.
• Long-running work: an unattended loop ran 43 sessions over nearly 67 hours, keeping 380 sources, 82 claims, 47 questions, corrections, bounded nulls, and two deliberately unconfirmed load-bearing claims coherent.

Browse every example and its receipts. They show the research states, corrections, and continuations flip preserved in real work. A controlled comparison of final research quality is a separate question.

Start from the outcome

Profiles define the notebook's rigor and operating contract. Outcome kinds add a collection contract for a particular deliverable.

A beat sits above notebooks when the mission recurs. It keeps coverage memory and computes the next bounded item—an unmet load-bearing claim, returned commission, due forecast, open question, or ungraduated thread—so each pass does not begin by rereading the whole corpus. A workspace binds many notebooks under stable handles so agents can resolve and audit them together.

What the agent maintains under the hood

The core loop is orient → select → open → work → check → close → continue or stop:

export FLIP_ACTOR="agent:codex" # set before `flip new`; pursuit seeds Q1 immediately
flip new nj-schools --kind pursuit --title "What changed in NJ enrollment?"
cd nj-schools
flip next --explain
flip session start enrollment-sweep --model <model> --tools <tools> \
  --workflow question-pursuit --phase orient --item Q1
flip add-source ./districts.csv --note "district enrollment table"
flip grade F1 --independence independent --basis official-record --base-defined
flip claim add "Enrollment fell 4.2% since 2021" --source F1 --load-bearing
flip question add "What is driving the decline?" --resolves-via "NJ DOE fall snapshot"
flip show
flip doctor
flip session end enrollment-sweep --summary "..." --output Q1 --check doctor
flip next

Humans generally direct those acts rather than typing them. flip cli prints an always-current command map. The CLI quickstart is a local, copy-and-run first notebook; the evidence workflow explains every legitimate path through the verification gates.

The portable artifact

A notebook is one directory:

index.md                 # OKF manifest + generated hot view
notebook.md              # prose working memory
references/              # one page per source
claims/                  # one page per assertion
questions/               # the question journey
decisions/               # forks resolved, with reasons
sessions/                # attributed working episodes
sources/raw/              # captured bytes, immutable
sources/_provenance.jsonl # append-only custody history
derived/                  # extraction and recomputation receipts
log/                      # append-only work and negative evidence

Human-slug filenames stay readable; immutable ids such as F1, C3, and Q2 keep citations stable through sanctioned renames. Unknown frontmatter keys and page bodies survive round trips, so humans, editors, and other tools can work in the same files.

Notebooks can be exported as BagIt, CSL JSON, render JSON, or a policy-filtered OKF copy. The public export can withhold raw custody and private event history; rights still have to be established by the workflow's source-selection and licensing policy. It is rights-aware publishing infrastructure, not an automatic legal-clearance system.

What flip works alongside

Retrieval systems, vector stores, schedulers, agent frameworks, databases, and publishing platforms keep serving their existing roles. flip connects their research outputs through a durable record. Integrations for capture, extraction, research, and local knowledge remain operator-configured. The core makes no LLM calls and requires no service; its two third-party libraries are Click and PyYAML.

The CLI enforces structural invariants and exposes missing work. Source grades and conclusions remain research judgments rather than claims the software can make. Generated views and scope-aware flip next support bounded re-grounding; the expected token-efficiency benefit has not yet been benchmarked.

Documentation

• Getting started — plugin and CLI installation, PATH fixes, URL setup, updates, removal, and first verification
• CLI quickstart — a network-free first notebook from capture through flip doctor
• Evidence workflow — grades, claims, tests, questions, transcripts, ids, and renames
• Integrations — capture, extraction, research, and local-knowledge lanes
• Agent orientation — capabilities, workflow map, and operating contract for agents
• Claude Code and Codex — plugin behavior, skills, updates, and custody-hook boundary
• AGENTS.md — concise runtime-neutral contract loaded in a repo
• Complete agent reference — command tour, lineage contract, and detailed task recipes
• Specification — OKF bundle, entities, profiles, beats, workspaces, exports, and integration contract
• Migration — recognize and upgrade older notebooks
• Obsidian — human editing and the companion plugin
• The core loop — orient through receipt and stop decision
• Workflows and extensions — registries, hooks, trust, and authoring
• Running a beat on a loop — standing policy and unattended passes
• llms.txt — compact documentation map for agents

Status: spec draft v0.22; package 0.22.0; Python 3.12+; MIT licensed. Built and maintained by Marc Lavallee. Changes are tracked in CHANGELOG.md; issues and contributions through CONTRIBUTING.md are welcome.