Start

Give flip to your agent

Install the plugin in the harness where research already happens, then direct the work the way you already do. The agent handles the CLI and maintains the notebook; you steer the investigation.

Orientation

Give the agent the map

The guide explains flip's capabilities, contracts, and place alongside the repository's existing research systems.

Copy a prompt for your agent

Install

Add flip to the harness

In Claude Code or Codex, the easy path is two commands, a new session, and a research assignment. When the first notebook begins, the creation skill checks for the standalone CLI and guides that one-time installation if needed.

  1. Add flip to your harness

    Claude Code

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

    Codex

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

    Both receive the same seven notebook skills. Start a new session after installation. The harness guide explains the custody-hook difference between them.

  2. Or install the CLI directly

    The PyPI package is flip-notebook; the command it installs is flip. Python 3.12 or newer is required.

    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, updates, and removal.

Your first research question

Give it the assignment

Use flip for this investigation: <question>. Leave a notebook another agent can inspect and continue.

The plugin is loaded at session start. The agent chooses the notebook kind, handles the CLI, and keeps using the repository's existing source, retrieval, and publishing systems.

Keep going

Talk about the research, not the bookkeeping

You ask the substantive questions: “Did this result replicate?”, “What would falsify that?”, “Does this answer the question as asked?”, “What should we watch next?”, or “Can another agent pick this up?” The agent translates those requests into source captures, grades, claims, tests, question notes, reopen triggers, commissions, and session handoffs.

When you want to inspect the work, ask for flip show, the claims needing support, open questions, source grades, or the latest handoff. The same pages remain readable in GitHub, Obsidian, or any Markdown editor.

Other harnesses

The plugin is packaging, not a lock-in

Give another runtime the runtime-neutral contract and the plain SKILL.md procedures, or load the spindle package named flip; spindle distributes the same skill package across agent runtimes. The CLI and notebook format underneath are the same.

Read AGENTS.md completely before working in this notebook. Set FLIP_ACTOR explicitly, preserve append-only history and unknown frontmatter keys, capture before cite, and run flip doctor before handoff.

When you want to look underneath

What the agent is doing for you

You normally will not type these commands. The real output is shown so the enforcement layer stays inspectable.

  1. Choose an outcome and open the notebook

    A pursuit runs one question to ground; a scout screens an angle; a research-review, lit-review, data-investigation, decision-packet, or forward-set carries a more specific completion contract.

    export FLIP_ACTOR="agent:codex" flip new okf-origins --kind research-review --title "Where OKF came from and where it may go" --visibility public

  2. Capture what the work relies on

    flip preserves the bytes, hashes them, appends provenance, and opens a source page at grade ?. URL capture uses the configured web lane; local files always copy directly.

    flip add-source ../okf-launch.md --note "dated public-source packet; full capture in flip-examples"

  3. Read, then judge

    Capture is custody, not authority. The source counts toward nothing until a named actor records its independence, evidentiary basis, and whether the measurement base is defined.

    flip grade F1 --independence derivative --basis synthesis --method "compact packet from the held launch post" flip grade F1 --explain

  4. Assert a claim—and meet the gate

    A load-bearing claim enters as asserted. If the profile's corroboration bar is unmet, verified status is refused. The refusal names every legitimate path forward instead of accepting insistence as evidence.

    flip claim add "Visible proposals cluster around identity, routing, relationships, retrieval, and composition" --source F6 --load-bearing flip claim status C6 verified

  5. Expose the frontier and hand it off

    show computes the hot view; doctor checks the format, lineage, required files, and verification gates. Sessions and handoffs record enough state for a cold agent to continue at the open edge.

    flip show --claims flip doctor

Go deeper

The outputs above are generated by running the real CLI against a scratch notebook when this site is built. Ids and timestamps will differ in yours.