Research Copilot

Research Copilot is a terminal-first local research loop.

It gives you:

• a read-only TUI for observing runs, experiments, research context, and runtime state
• workflow commands as the primary action surface for triage, experiments, review, and next-step planning
• workflow autonomous-start / workflow autonomous-continue as the canonical managed autonomy path
• runtime codex-* as advanced supervision / recovery for a managed Codex brain

State lives in .research-copilot/ inside the workspace.

Quick Start

Prerequisites:

• Python 3.11+
• tmux on PATH
• codex on PATH if you want a live Codex brain

Install:

pipx install research-copilot

For local development from a checkout:

pip install -e .

Initialize a workspace:

research-copilot init

Open the TUI:

research-copilot

Experimental Rust TUI scaffold:

cargo run --manifest-path rust-tui/Cargo.toml -- --workspace .

If you are operating from another shell against an already-initialized workspace, set the workspace explicitly:

research-copilot --workspace "G:\Projects\my-research" status

Run JSON-safe workflow commands:

research-copilot workflow triage --json
research-copilot workflow run-experiment --command "<local command>" --json
research-copilot workflow review-results <experiment-id> --json
research-copilot workflow next-step <experiment-id> --json

Recommended next action after onboarding:

research-copilot workflow triage --json

Canonical Managed Autonomy

Start the persistent managed autonomy loop:

research-copilot workflow autonomous-start --json

Continue/reconcile or inspect that managed runtime:

research-copilot workflow autonomous-continue --json
research-copilot workflow autonomous-status --json
research-copilot workflow autonomous-stop --owner-token <token> --json
research-copilot workflow autonomous-resume --owner-token <token> --json

Advanced Codex Runtime Supervision

Use runtime codex-* when you already have a managed Codex brain and need expert supervision or recovery:

Attach a Codex pane:

research-copilot runtime codex-attach \
  --session-id my-live-session \
  --pane-id %42 \
  --workspace-path "G:\Projects\my-research" \
  --json

Report a bounded turn:

research-copilot runtime codex-report \
  --session-id my-live-session \
  --turn-number 1 \
  --summary "Finished the first bounded turn." \
  --action review-results \
  --experiment-id exp-1 \
  --json

Start the detached supervisor so the Codex pane keeps going without manual prompting:

research-copilot runtime codex-run \
  --session-id my-live-session \
  --pane-id %42 \
  --workspace-path "G:\Projects\my-research" \
  --json

Inspect live Codex runtime state:

research-copilot runtime codex-status \
  --session-id my-live-session \
  --include-nudges \
  --json

Steering

Queue a steering request:

research-copilot runtime codex-nudge \
  --session-id my-live-session \
  --kind request_summary \
  --message "Need a tighter recap for the next turn." \
  --json

Apply queued nudges into the live tmux pane:

research-copilot runtime codex-apply-nudges \
  --session-id my-live-session \
  --json

Pause or resume:

research-copilot runtime codex-pause --session-id my-live-session --json
research-copilot runtime codex-resume --session-id my-live-session --json

Stop the supervisor:

research-copilot runtime codex-stop --session-id my-live-session --json

TUI Notes

The TUI is read-only.

It shows:

• live runtime state
• brain driver and runtime health
• freshness
• last action
• latest summary
• goal
• operator mode
• pending nudges
• a recommended next action handoff back to the workflow CLI

For overflow content:

• j / k move selection
• Ctrl+U / Ctrl+D scroll oversized detail panels and modals
• Tab changes panes

Core Workflow Commands

research-copilot workflow onboard --json
research-copilot workflow triage --json
research-copilot workflow autonomous-start --json
research-copilot workflow autonomous-continue --json
research-copilot workflow research-context "<query>" --json
research-copilot workflow run-experiment --command "<local command>" --json
research-copilot workflow review-results <experiment-id> --json
research-copilot workflow next-step <experiment-id> --json

See docs/cli-workflows.md for the wording contract and docs/demo-runbook.md for the demo path.

Verify

pytest
ruff check .
research-copilot --help
research-copilot workflow --help
research-copilot runtime --help

MVP Limitations

• The TUI is read-only. Mutating actions still go through CLI workflow/runtime commands.
• The live Codex runtime can continue autonomously, but it still depends on the Codex pane accepting and following the injected bounded-turn prompt.
• Managed Codex autonomy now depends on one active runtime generation, explicit turn reporting, and may degrade to watchdog-supported mode when reports stop arriving.
• The supervisor currently targets tmux panes only.
• Steering is applied as text injected into the registered Codex pane; it is not a model-native control channel.
• The runtime/dashboard path is local and single-user. It is not a multi-user remote control plane.
• Very long content now pages in the main detail/modals, but this is still a terminal UI, not a full rich-scroll application.