USER GUIDE / Go further

07 / Go further

Research Station

Test a better way of working before adopting it across your projects.

What research does

The Research Station runs bounded experiments on agent resources, compares trial evidence, and produces a proposed resource patch. Open it with uppercase R on the galaxy or empire research. The standalone command does not start or upgrade the fleet daemon.

A useful first question is: “My agents miss layout problems when they finish UI work. Investigate a better verification workflow.” Choose a small representative task with clear acceptance criteria.

Set up the runtime

Press i in the station, or run:

empire research setup

Setup needs git, uv and network access. It installs the pinned Google Harness² runtime with Python 3.12 in a separate environment. Trials use the native Codex CLI and your existing codex login account.

Start a study

  1. Press n. Describe the problem and choose the project folder and Git revision, normally HEAD.
  2. Enter one to three representative tasks, one per line. Alt+Enter adds a task; pasted newlines work too. Tab moves between fields.
  3. Choose a time budget. Enter reviews the frozen commit, tasks and limits. Press it again to start, or Esc to edit.
  4. Follow snapshot → baseline → proposals → trials → composition → review. Leaving the screen keeps the study running.

One experiment runs at a time. Each task normally uses eight model sessions, with a ceiling of ten calls per task. The default study budget is 30 minutes, and each session has a ten-minute limit. These are real model calls; token counts are recorded, but billed cost is unavailable. Check your provider account for cost.

Read and adopt

Enter opens a study. v reads its evidence report, p shows the resource patch, and o returns to progress. Use arrows or Page Up/Down to scroll. To cancel, press x, then y; existing evidence is retained.

From the patch, a, then y, applies the resource proposal to the original project. Every original resource must still match the snapshot; a conflict refuses the entire application. Application-code changes from trials stay in the experiment copies. There is no automatic commit, push or rollout.

Boundaries and records

Trials copy the chosen commit, excluding uncommitted files, symlinks, .env files, .codex and .mcp.json. Task commands have workspace-write access with network disabled and escalation denied. Model requests still require network access. This is not a confidentiality sandbox: choose appropriate source and tasks.

Dependencies are not downloaded automatically for trials. Tasks needing a server or browser need usable tooling. Editable resources include AGENTS.md, skill SKILL.md files, Python skill helpers and scripts/*.py. Supporting documents remain intact.

Study records, workspaces, traces, REPORT.md and proposed patches live under $XDG_STATE_HOME/empire/research/RUN-ID. Runtime dependencies live under $XDG_DATA_HOME/empire/research. Set EMPIRE_RESEARCH_PYTHON to use an existing compatible environment.