ORP — Open Research Protocol

Maintained by SproutSeeds. Research stewardship: Fractal Research Group (frg.earth).

Agent-first CLI for workspace ledgers, operating agendas, local governance, secrets, scheduling, packets, reports, and research workflows.

Links: GitHub · npm · frg.earth

ORP is a unified CLI for research and research-like engineering. It helps humans and agents:

• keep a durable workspace ledger
• keep a durable operating agenda
• keep a durable connections registry
• keep a durable opportunities ledger
• resolve the right secret
• schedule the next loop
• checkpoint and protect progress
• emit packets and reports
• keep hosted and local state aligned

Boundary (non-negotiable): ORP files are process-only. They are not evidence and must not be cited as proof. Evidence lives in canonical project artifacts such as code, data, papers, proofs, and logs.

ORP also supports optional modular Instruments for shaping inquiry upstream of claims. Instruments are process-only and do not change the verification boundary. See modules/instruments/README.md and docs/WHY_INSTRUMENTS.md.

ORP also watches always-on personal-agent runtimes such as Hermes Agent and OpenClaw from a borrowing-ideas perspective. Those systems can inspire better gateways, skills, background notifications, model routing, and dashboards, but ORP remains the durable workspace ledger, agenda, routing, governance, and checkpoint layer. See Agent Runtime Borrowing Notes.

Watch It Run

A short ORP command-family walkthrough:

The current animation intentionally uses the same human-facing command surfaces ORP prints in the terminal. It is not a fabricated UI layer. It currently shows ORP from multiple angles:

• home for discovery and next actions
• hosted for ideas, workspaces, runners, and the control plane
• secrets for create-or-reuse plus local Keychain sync
• workspace for the hosted + local saved workspace ledger and recovery commands
• agenda for Codex-ranked actions and suggestions across current work
• connections for service accounts, data sources, deploy targets, and research destinations
• opportunities for contests, programs, grants, and other tracked openings
• schedule for recurring Codex jobs
• governance for local checkpoints and repo safety
• planning for frontier, compute, packet, and report surfaces
• synthesis for discover, exchange, collaborate, and YouTube ingestion
• mode for optional perspective-shift nudges

Maintainer asset generation:

npm run render:terminal-demo

Install CLI (npm)

Global install:

npm i -g open-research-protocol
orp
orp -h

Prerequisites:

• Python 3 available on PATH
• PyYAML in that Python environment (python3 -m pip install pyyaml)

Local repo usage still works:

./scripts/orp -h

Start Here

If you are new to ORP, use one canonical onboarding path:

• docs/START_HERE.md

That guide now follows the same clearer rhythm we liked in erdos-problems:

• a fast Start In 60 Seconds path
• a zero-assumption Beginner Flow
• a practical Daily Loop
• a compact Minimum Working Loop for agents and operators
• the checkpoint governance loop in plain English

It walks through:

• orp init
• umbrella and project-level AGENTS.md / CLAUDE.md guidance
• local-first workspace ledgers
• local-first opportunity boards
• saved Codex and Claude resume commands
• secrets setup
• the checkpoint and governance loop
• optional hosted sync later

Daily ORP Operating System

If you want the shortest honest map of day-to-day ORP, start here:

orp
orp home
orp agents audit
orp workspace tabs main
orp agenda refresh --json
orp agenda refresh-status --json
orp agenda focus
orp opportunities list
orp secrets ensure --alias openai-primary --provider openai --current-project
orp checkpoint create -m "capture loop state"
orp packet emit --profile default
orp report summary
orp frontier state
orp schedule list
orp mode nudge sleek-minimal-progressive
orp mode breakdown granular-breakdown
orp mode nudge granular-breakdown

That sequence covers discovery, agent-guide alignment, workspace recovery, agenda refresh, secret resolution, governance, artifacts, planning, automation, perspective-shift support, and intentional breakdown when the work needs more granular comprehension. Use mode breakdown for the full broad-to-atomic ladder; use mode nudge when you only need a short reminder card.

The shorter rule is:

• recover the workspace
• keep the agent guides aligned
• refresh the agenda
• inspect the active opportunities
• inspect repo safety
• resolve the right secret
• inspect the current frontier
• do the next honest move
• checkpoint at honest boundaries

Agenda Quick Start

Use agenda when you want ORP to keep two ranked lists for the current operating moment:

• actions for the things most likely to need attention now
• suggestions for the next best expansions toward the current north star

Run one refresh:

orp agenda refresh --json

Check whether recurring refreshes are enabled on this machine:

orp agenda refresh-status --json

If you want scheduled Codex refreshes, you must opt in explicitly. Nothing auto-runs until you do. The starter preset uses local morning, afternoon, and evening times:

orp agenda enable-refreshes --json

If you want your own times instead of the default 09:00, 14:00, and 19:00, set them directly:

orp agenda enable-refreshes --morning 08:30 --afternoon 13:00 --evening 18:30 --json

Turn them back off any time:

orp agenda disable-refreshes --json

Inspect the resulting lists:

orp agenda actions
orp agenda suggestions
orp agenda focus

If you want to pin an explicit north star instead of relying on inferred context:

orp agenda set-north-star "Advance the ocular controller and ORP ecosystems"

The practical model is:

• agenda refresh is a real Codex reasoning pass
• it reads current main-workspace context, GitHub pressure, connections, and opportunities
• it writes two saved ranked lists locally
• recurring agenda refreshes stay disabled until the user explicitly enables them
• the default scheduled windows are morning, afternoon, and evening, but the user can set custom times
• focus is the fastest operator and agent recall surface

Opportunities Quick Start

Use opportunities when you want a separate editable list of contests, programs, grants, or other openings without mixing that into workspace.

Create one board:

orp opportunities create main-opportunities --label "Main Opportunities"

Add one tracked item:

orp opportunities add main-opportunities --title "vision-prize" --kind contest --section ocular-longevity --priority high --url https://example.com/vision-prize

Inspect the current board:

orp opportunities show main-opportunities
orp opportunities focus main-opportunities --limit 5
orp opportunities list

Update or remove one item:

orp opportunities update main-opportunities vision-prize --status submitted
orp opportunities remove main-opportunities vision-prize

Mirror or restore the same board across machines once you authenticate:

orp auth login
orp opportunities sync main-opportunities --json
orp opportunities pull main-opportunities --json

The practical model is:

• local board first, always usable without an account
• hosted mirror optional, for the same user across multiple rigs
• sync pushes the current local board to hosted ORP
• pull restores the hosted copy onto this machine

Connections Quick Start

Use connections when you want one place to remember service accounts, data sources, deployment targets, and research destinations without storing raw credentials inline.

Inspect the built-in provider templates when they help:

orp connections providers

Add one saved connection that references an ORP secret alias:

orp connections add github-main --provider github --label "GitHub Main" --account cody --organization sproutseeds --auth-secret-alias github-main

If one service needs several tokens, keep them together under named secret bindings:

orp connections add huggingface-main --provider huggingface --label "Hugging Face" --account cody --secret-binding primary=hf-main --secret-binding publish=hf-publish --secret-binding inference=hf-inference

If ORP has never seen the service before, custom is still a normal first-class path:

orp connections add my-science-portal --provider custom --label "My Science Portal" --url https://example.org --secret-binding primary=my-science-token

Inspect or update the registry:

orp connections show github-main
orp connections list
orp connections update github-main --status paused
orp connections remove github-main

Mirror the same registry across machines once you authenticate:

orp auth login
orp connections sync --json
orp connections pull --json

The practical model is:

• secrets holds the actual sensitive value
• connections holds the provider/account/capability record and which secret alias or named secret bindings power it
• built-in providers help you start faster, but custom works for anything new or niche
• hosted sync is optional and mirrors the whole registry for the same user

Secrets Quick Start

Today, ORP secrets use the hosted ORP secret inventory as the canonical store, with optional local macOS Keychain caching. That means the real first step for secrets is:

orp auth login

After that, there are two normal ways to save a secret.

For a human at the terminal, use the interactive path:

orp secrets add --alias openai-primary --label "OpenAI Primary" --provider openai

ORP then prompts:

Secret value:

That is where you paste the real key.

For an agent or script, use stdin:

printf '%s' 'sk-...' | orp secrets add --alias openai-primary --label "OpenAI Primary" --provider openai --value-stdin

If a service needs both a username and a secret, store the username with it:

orp secrets add --alias huggingface-login --label "Hugging Face Login" --provider huggingface --kind password --username cody

After that:

orp secrets list
orp secrets show openai-primary
orp secrets resolve openai-primary --reveal

If you want the convenience command, ensure means:

use this saved key if it already exists, otherwise prompt for it and save it

So this command:

orp secrets ensure --alias openai-primary --provider openai --current-project

does not contain the key itself. It means:

• look for a saved secret called openai-primary
• if it exists, reuse it
• if it does not exist, prompt for the key and save it
• attach it to the current project if needed

For secrets, the simplest plain-English rule is:

• orp secrets add ... = save a new key
• orp secrets add ... --username <name> = save a new login credential plus its username
• orp secrets list = see what is saved
• orp secrets show ... = inspect one saved key record
• orp secrets resolve ... = get the key value for use right now
• orp secrets ensure ... = use the saved key if it exists, otherwise create it
• orp secrets sync-keychain ... = keep a secure local Mac copy too

You can ignore --env-var-name at first. It is optional metadata like OPENAI_API_KEY, not the key itself.

Product Map

Think of ORP as one CLI with a few major lanes:

• home, about, mode, update, maintenance Discovery, status, creativity overlays, and ORP self-upkeep.
• auth, ideas, world, workspaces, checkpoint queue, runner, agent Hosted control-plane operations.
• workspace, secrets, schedule Workspace ledger recovery, API-key management, and recurring Codex jobs.
• init, status, branch, checkpoint create, backup, ready, doctor, cleanup Local repo governance and safe operator flow.
• packet, report, frontier, compute Structured artifacts, planning, and bounded compute control.
• discover, exchange, collaborate, youtube, erdos Scanning, synthesis, workflow scaffolding, external source ingestion, and domain-specific support.

The pack layer still exists, but it is now an advanced/internal surface rather than the main product story.

For agents and machine integrations, the --json variants remain the canonical structured interface. The public demo and launch materials use the human-facing command output on purpose so the walkthrough matches what a person actually sees.

Command Families

Landing and discovery:

orp
orp home --json
orp about --json
orp mode list --json
orp mode show sleek-minimal-progressive --json
orp mode nudge sleek-minimal-progressive --json
orp mode show granular-breakdown --json
orp mode breakdown granular-breakdown --json
orp mode nudge granular-breakdown --json
orp update --json
orp maintenance status --json

Hosted control plane:

orp auth login
orp whoami --json
orp ideas list --json
orp workspaces list --json
orp workspaces show <workspace-id> --json
orp checkpoint queue --idea-id <idea-id> --json
orp runner work --once --json
orp agent work --once --json

Local desk and automation:

orp workspace create mac-main --machine-label "Mac Studio"
orp workspace list
orp workspace tabs main
orp workspace add-tab main --path /absolute/path/to/project --remote-url git@github.com:org/project.git --bootstrap-command "npm install" --resume-command "codex resume <id>"
orp workspace add-tab main --path /absolute/path/to/project --title "second active thread" --resume-tool claude --resume-session-id <id> --append
orp workspace remove-tab main --path /absolute/path/to/project
orp workspace sync main
orp secrets list --json
orp secrets ensure --alias openai-primary --provider openai --current-project --json
orp secrets sync-keychain openai-primary --json
orp schedule add codex --name morning-summary --prompt "Summarize this repo" --json

For secrets, the simplest plain-English rule is:

• orp secrets ensure ... = use the saved key if it already exists, or ask for it and create it if it does not
• orp secrets resolve ... = return the actual key value for use right now
• you can ignore --env-var-name at first; it is optional metadata, not the key itself

Local governance:

orp agents root set /absolute/path/to/projects
orp init --projects-root /absolute/path/to/projects
orp agents audit
orp agents sync
orp status --json
orp branch start work/<topic> --json
orp checkpoint create -m "describe completed unit" --json
orp backup -m "backup current work" --json
orp ready --json
orp doctor --json
orp cleanup --json

Artifacts, planning, and compute:

orp packet emit --profile default --json
orp report summary --json
orp frontier state --json
orp frontier roadmap --json
orp frontier checklist --json
orp frontier continuation-status --json
orp frontier preflight-delegate --json
orp frontier additional list --json
orp frontier doctor --strict --json
orp compute decide --input orp.compute.json --json
orp compute run-local --input orp.compute.json --task orp.compute.task.json --json

Frontier continuation checks are the handoff guard for long-running delegated research. orp frontier preflight-delegate --json fails when the live milestone/phase is stale, an additional queue item is complete but still active, pending queue work has not been activated, or the frontier has no declared next step or terminal completion.

Scanning, synthesis, and collaboration:

orp discover github scan --profile orp.profile.default.json --json
orp exchange repo synthesize /path/to/source --json
orp collaborate workflows --json
orp collaborate run --workflow full_flow --json
orp youtube inspect https://www.youtube.com/watch?v=<video_id> --json
orp erdos sync --json

Life Ops Bridge

ORP and Life Ops are meant to connect, but they are not the same package.

• open-research-protocol stays the main ORP CLI/runtime surface.
• @lifeops/core is the Life Ops SDK for normalized agenda items, outreach, and structured share-email drafting.
• @lifeops/orp is the bridge package that turns ORP JSON surfaces into Life Ops-compatible items and share-ready project input.

The bridge package lives at packages/lifeops-orp/.

Key Docs

• docs/START_HERE.md for the canonical step-by-step starter path
• AGENT_INTEGRATION.md for integrating ORP into an agent's primary instructions
• INSTALL.md for adopting ORP in an existing repo or new project
• docs/AGENT_LOOP.md for the intended operator rhythm
• docs/AGENT_MODES.md for optional creativity and perspective overlays
• docs/EXCHANGE.md for repository/project synthesis
• docs/CANONICAL_CLI_BOUNDARY.md for CLI, Rust, and web responsibility boundaries
• docs/ORP_HOSTED_WORKSPACE_CONTRACT.md for the first-class hosted workspace model
• docs/LAUNCH_KIT.md for public positioning, demo flow, and launch copy
• docs/NPM_RELEASE_CHECKLIST.md and docs/ORP_PUBLIC_LAUNCH_CHECKLIST.md for release execution
• llms.txt for concise agent/LLM discovery

Stable artifact paths:

• orp/state.json
• orp/artifacts/<run_id>/RUN.json
• orp/artifacts/<run_id>/RUN_SUMMARY.md
• orp/packets/<packet_id>.json
• orp/packets/<packet_id>.md
• orp/discovery/github/<scan_id>/SCAN.json
• orp/discovery/github/<scan_id>/SCAN_SUMMARY.md

Quick start (existing repo)

1. Copy this folder into your repo (recommended location: orp/).
2. Link to orp/PROTOCOL.md from your repo README.md.
3. Customize Canonical Paths inside orp/PROTOCOL.md to match your repo layout.
4. Run orp init in the repo root to establish ORP governance.
5. If you keep many repos under one umbrella directory, run orp agents root set /absolute/path/to/projects once and let orp init --projects-root /absolute/path/to/projects link each child repo back to that parent guidance.
6. Use orp agents audit whenever you want to confirm AGENTS.md and CLAUDE.md are still aligned without overwriting human notes.
7. Use orp status, orp branch start, orp checkpoint create, and orp backup as the default implementation loop.
8. Use the templates for all new claims and verifications.
9. Optional (agent users): integrate ORP into your agent’s primary instruction file (see orp/AGENT_INTEGRATION.md).

Quick start (new project)

1. Copy this folder into a new project directory.
2. If you keep projects under one umbrella directory, run orp agents root set /absolute/path/to/projects once from anywhere.
3. Run orp init immediately so the repo starts ORP-governed and scaffolds or updates AGENTS.md and CLAUDE.md.
4. Edit PROTOCOL.md to define your canonical paths and claim labels.
5. Run orp agents audit to confirm the repo-level agent files are aligned and still preserving human notes.
6. Start implementation on a work branch with orp branch start.
7. Create regular checkpoint commits with orp checkpoint create.
8. Use orp backup whenever you want ORP to capture current work to a dedicated remote backup ref.
9. Validate promotable task/decision/hypothesis artifacts with orp kernel validate <path> --json.
10. Start by adding one small claim + verification record using the templates.
11. Optional (agent users): integrate ORP into your agent’s primary instruction file (see AGENT_INTEGRATION.md).

Activation is procedural/social, not runtime: nothing “turns on” automatically. ORP works only if contributors follow it.

Optional Runtime Draft (v1)

ORP remains docs-first by default. For teams that want local gate execution and machine-readable packets, there is an optional v1 draft:

• Overview: docs/ORP_V1_ATOMIC_DISCOVERY_EVOLUTION.md
• Packet schema: spec/v1/packet.schema.json
• Config schema: spec/v1/orp.config.schema.json
• Kernel schema: spec/v1/kernel.schema.json
• Lifecycle mapping: spec/v1/LIFECYCLE_MAPPING.md
• Sunflower atomic profile example: examples/orp.sunflower-coda.atomic.yml
• Kernel starter example: examples/orp.reasoning-kernel.starter.yml

Minimal CLI skeleton:

orp auth login
orp youtube inspect https://www.youtube.com/watch?v=<video_id> --json
orp ideas list --json
orp world bind --idea-id <idea-id> --project-root /abs/path --codex-session-id <session-id> --json
orp checkpoint queue --idea-id <idea-id> --json
orp runner work --once --json
orp runner work --continuous --transport auto --json
orp agent work --once --json   # compatibility alias with legacy checkpoint fallback
orp init
orp status --json
orp branch start work/<topic> --json
orp checkpoint create -m "describe completed unit" --json
orp kernel validate analysis/orp.kernel.task.yml --json
orp backup -m "backup current work" --json
orp gate run --profile default
orp ready --json
orp packet emit --profile default
orp report summary --run-id <run_id>
orp erdos sync

Equivalent local-repo commands are available via ./scripts/orp ... when developing ORP itself.

Kernel helper surfaces:

orp kernel scaffold --artifact-class task --out analysis/trace-widget.kernel.yml --json
orp kernel validate analysis/trace-widget.kernel.yml --json

Run summaries are one-page markdown reports generated from RUN.json and intended for fast teammate review:

• what ran,
• what passed/failed,
• where evidence logs live,
• and how reproducible the run is.

Sample summaries:

• examples/reports/sunflower_live_compare_857.RUN_SUMMARY.md
• examples/reports/sunflower_live_compare_20.RUN_SUMMARY.md
• examples/reports/sunflower_live_compare_367.RUN_SUMMARY.md

Optional Profile Packs

ORP supports reusable domain profile packs so core runtime stays general.

The main public collaboration story is now the built-in orp collaborate ... surface. Treat packs as advanced/internal packaging structure unless you are working on ORP itself or installing domain-specific workflows like erdos.

Built-in collaboration quickstart:

orp collaborate init
orp collaborate workflows --json
orp collaborate gates --workflow full_flow --json
orp collaborate run --workflow full_flow --json

• Pack docs: docs/PROFILE_PACKS.md
• Pack metadata schema: spec/v1/profile-pack.schema.json
• Included pack: packs/erdos-open-problems/ (857/20/367 + catalog sync + governance profiles)
• Included pack: packs/external-pr-governance/ (generic external OSS contribution workflow pack)
• Included pack: packs/issue-smashers/ (opinionated external contribution workspace pack built on the same governance ideas)

If you are using ORP normally, prefer:

• orp collaborate ... for collaboration
• orp erdos ... for Erdos work

Reach for orp pack ... when you are doing advanced installs, ORP maintenance, or direct domain-template work.

Pack installation is pack-owned: pack.yml can describe installable components, default includes, dependency checks, and report naming. That lets ORP consume repo-owned external packs through --pack-path without baking domain-specific install rules into ORP core.

Install pack configs into a target repo (recommended):

orp pack list

orp pack install \
  --pack-id erdos-open-problems

Fetch an external pack repo and install through CLI (no manual clone flow required):

orp pack fetch \
  --source https://github.com/example/orp-packs.git \
  --pack-id erdos-open-problems \
  --install-target .

This writes rendered configs and a dependency audit report at:

• ./orp.erdos-catalog-sync.yml
• ./orp.erdos-live-compare.yml
• ./orp.erdos-problem857.yml
• ./orp.erdos.pack-install-report.md

Advanced/internal direct install of the Issue Smashers workspace pack:

orp pack install \
  --pack-id issue-smashers

This writes:

• ./orp.issue-smashers.yml
• ./orp.issue-smashers-feedback-hardening.yml
• ./orp.issue-smashers.pack-install-report.md
• ./issue-smashers/ workspace scaffold

The pack is intentionally install-and-adapt:

• it creates the workspace layout and starter docs
• it does not auto-clone target repos
• it keeps governance commands as explicit placeholders until you wire in a repo adapter

By default, install includes starter scaffolding for Problems 857/20/367 so live_compare runs are install-and-go in a fresh repo.

If you want the Problem 857 lane to pull the real public sunflower-lean repo into an empty repo instead of writing starter-only 857 files, use:

orp pack install \
  --pack-id erdos-open-problems \
  --include problem857 \
  --var PROBLEM857_SOURCE_MODE=public_repo \
  --var PROBLEM857_PUBLIC_REPO_URL=https://github.com/SproutSeeds/sunflower-lean

This syncs the public Lean repo into sunflower_lean/ and generates the ORP-owned 857 bridge files (analysis/, docs/, scripts/, and orchestrator/) on top of it.

For public-only adoption (no private sunflower adapters yet):

orp pack install \
  --pack-id erdos-open-problems \
  --include catalog

Clean-room public pack cycle:

orp pack install \
  --pack-id erdos-open-problems \
  --include catalog

orp --config orp.erdos-catalog-sync.yml \
  gate run --profile erdos_catalog_sync_active

orp report summary

This is the simplest end-to-end pack workflow currently validated against the published npm package.

Manual render path (advanced):

python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --list
python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template sunflower_live_compare_suite \
  --var TARGET_REPO_ROOT=/path/to/repo --out /path/to/repo/orp.erdos-live-compare.yml
python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template sunflower_mathlib_pr_governance \
  --var TARGET_REPO_ROOT=/path/to/repo --out /path/to/repo/orp.erdos-mathlib-pr-governance.yml
python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template erdos_problems_catalog_sync \
  --var TARGET_REPO_ROOT=/path/to/repo --var ORP_REPO_ROOT=/path/to/orp --out /path/to/repo/orp.erdos-catalog-sync.yml