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
                ├── 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
                        ├── scenarios/
                        └── report.yaml

Why Runs Copy Their Inputs

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:

1. Review hook scripts for accidental literal secrets.
2. Confirm profile YAML contains only references such as ${API_KEY}.
3. Inspect run evidence for target data that should not leave the test environment.
4. 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.

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.

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 scroll to files. The local UI reads the directory tree above, including unsynchronized and test-mode evidence. Keep that tree intact when moving an approved evidence bundle.

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, scroll to files. The sample lists the request, response, hooks, snapshot, verdict, and additional judge evidence. Click a filename to inspect the corresponding on-disk record and use Back to return.

Hosted Web UI: Browse Uploaded Artifacts

Open run → scenario → Artefacts for additional uploaded files. Main records have separate Request, Response, and Verdict tabs, so this tab is not a mirror of the local file list. The sample lists judge-working.json here.

Related Documentation

• Concepts and data model
• Architecture
• Environment and secrets
• Verdicts and reports