Rook Workspace Files

Rook uses plain files rather than a hidden workspace database. That makes agents, test definitions, profiles, and evidence packs available for normal review, diffing, editing, and version control.

Repository Tree

Verified

.testmuai/rook/
├── settings.json                         active project and permission rules
├── .gitignore                            machine-only and sensitive exclusions
├── cache/                                derived indexes; safe to rebuild
└── projects/
    └── <project-id>/
        ├── project.yaml
        ├── active                        selected agent
        ├── jobs/                         in-flight upstream writes
        └── agents/
            └── <agent-id>/
                ├── agent.yaml            derived agent definition
                ├── coverage-gaps.yaml    attack patterns with no scenario
                ├── state.json            machine-local server IDs
                ├── features/
                │   ├── F-001.yaml
                │   └── F-005.yaml
                ├── scenarios/
                │   ├── SC-001.yaml
                │   └── SC-011.yaml
                ├── profiles/
                │   ├── active
                │   └── staging.yaml
                ├── scripts/
                │   └── order-desk.mjs
                └── runs/
                    └── 01M0VPKFSDC07CWWF51FGAVCCR/
                        ├── run.yaml
                        ├── agent.yaml
                        ├── features.yaml
                        ├── profile.yaml
                        ├── scenario-inventory.yaml
                        ├── scenarios/
                        └── report.yaml

Why Runs Copy Their Inputs

Directory names can include a readable project slug and its ID, such as <project-name>--<project-id>. Use the evidence path printed by your run or /report; do not construct it from the hosted URL. Local run directory names can also differ from hosted run IDs.

Every run directory is self-contained. It snapshots:

the agent definition as it was;
the feature set as it was;
the selected profile as it was;
the scenarios as they were;
all per-scenario verdicts and evidence;
the final report.

This makes a verdict readable later even after the working agent, profile, features, and scenario definitions have all changed. It also lets reports distinguish a regression from a definition change.

Files Excluded From Git

On first use, Rook adds a .gitignore below .testmuai/rook/ for data that should not travel:

Verified

*.log
.env
cache/
projects/*/jobs/
projects/*/agents/*/state.json

These entries cover logs, credentials, derived caches, in-flight jobs, and machine-specific IDs. Rook appends missing defaults rather than rewriting the file, because a repository may have intentional local policy.

What Is Safe to Review and Commit

Project YAML, agent definitions, features, scenarios, profiles containing references, hook scripts without embedded credentials, and completed evidence packs are designed to be readable project artifacts.

Before committing:

Review hook scripts for accidental literal secrets.
Confirm profile YAML names variables under env (for example API_KEY) and holds no literal secret, including in hook_env.
Inspect run evidence for target data that should not leave the test environment.
Keep machine-only .gitignore entries intact.

Global State Lives Elsewhere

Credentials, actual environment values, history, logs, and installed versions are stored under ~/.testmuai/rook/ by default. Set ROOK_HOME to isolate that state for CI or another account.

Each session keeps a transcript at ~/.testmuai/rook/sessions/<project>/<session>/transcript.jsonl, readable only by your user. It records every prompt Rook sent, every tool result, and every answer, so treat it like a log that can contain target data and environment values.

Synchronization

rook sync copies a reviewed project tree upstream as one write. Run results are stored locally first; rook runs sync reconciles finished runs that still owe remote records. Neither operation changes the historical input snapshots inside an existing run.

Inside the interactive TUI, enter /sync after reviewing the files. This actual quickstart capture confirms that the triage agent was recorded upstream; it does not say that a test has run or passed:

Rook's interactive sync confirming that one local agent was recorded upstream

Review Files in Either UI

Use rook ui --local from this workspace to browse its agents and runs, then open a run's scenario and choose Request, Response, Verdict, or Artefacts in the Evidence panel. The local UI reads saved records, including unsynchronized and test-mode evidence, but does not list every file in the directory tree above. Keep that tree intact when moving an approved evidence bundle. See the earlier layout if your CLI has the old files list.

Use rook ui for the hosted Web UI's uploaded versions and run artifacts. Local edits are not visible there until synchronized, and --test runs stay local. Hosted IDs may differ from run-directory IDs; use the UI's links instead of constructing URLs. See the local and hosted walkthrough.

Local UI: Browse the Scenario's Files

On a run's scenario result, open Evidence → Artefacts. The CommerceCare sample lists collect.json and judge-working.json; select View to inspect a file and the drawer's return control to go back. Request, response, and verdict have their own drawer tabs. hooks.json, snapshot.yaml, and nested internal files remain on disk but are not listed here, so keep the original run directory for a complete investigation.

Local Artefacts drawer listing the CommerceCare collect.json and judge-working.json files

Hosted Web UI: Browse Uploaded Artifacts

Open run → scenario → Evidence → Artefacts for additional uploaded files. The evidence drawer also has Request, Response, and Verdict tabs. Neither viewer's Artefacts list mirrors the complete run directory. This separate hosted triage sample lists judge-working.json here.