Connect and Explore AI Agents

Exploration tells Rook what an agent is supposed to do before you tell it how to invoke the agent. Rook reads local material such as source code, prompts, skills, manifests, tool declarations, tests, README files, and product requirements.

The target can be a complete application, one agent directory, or a documentation-only workspace. Rook works with any agent framework.

Explore the Current Workspace

Start Rook from the repository root and run:

/explore .

The headless equivalent is:

rook explore .

Use a narrower path when a monorepo contains a specific agent package:

/explore packages/travel-agent

Rook scans deterministically first, then gives its discovery subagent read tools scoped to the authorized workspace. The result depends on how many candidates it finds:

• One candidate: Rook asks whether to register it.
• Several candidates: Choose the candidates you want.

What Rook Looks For

Rook can identify agents from evidence including:

• System and developer prompts.
• Model calls and agent loops.
• Tool or function registries.
• MCP server declarations.
• Framework files such as .claude/agents/*.md.
• Skills, subagents, routing rules, and policies.
• HTTP handlers and command entrypoints.
• Tests, fixtures, examples, and user-facing documentation.
• PRDs and other text describing intended behavior.

Discovery does not invent missing facts. If a tool's write behavior cannot be established, Rook records it as unknown rather than guessing from its name.

Give Exploration Extra Context

Put free-form guidance after --:

/explore . -- focus on the refund approval threshold and identity checks

In headless mode:

rook explore . \
  --instruction "focus on the refund approval threshold and identity checks"

The instruction guides the discovery model, but it does not widen the filesystem scope.

Use --force after a substantial change or when you want to ignore the incremental freshness check:

/explore --force

Normally Rook hashes the relevant files and re-reads only what changed.

Explore a PRD Without Source Code

Create a clean directory containing the material you are authorized to share:

travel-agent-spec/
  PRD.md
  policies.md
  api-examples.md
  fixtures/

Start Rook inside that directory:

cd travel-agent-spec
rook

Then run:

/explore . -- the deployed agent is a multi-turn travel planner

If no structural agent signal is found, Rook can ask whether to register the directory anyway. A documentation-only exploration generates requirement-grounded scenarios, but it has less evidence about implementation details, tool behavior, and side effects than a source-backed exploration.

You still need an invocation profile that reaches the deployed agent. See Configure Rook Profiles.

Explore a GitHub Repository

Rook does not read a GitHub URL directly. Clone the repository, enter the checkout, and run Rook locally:

git clone https://github.com/<owner>/<repository>.git
cd <repository>
rook

Then:

/explore .

If you paste a GitHub URL into /explore, Rook refuses it before spending credits and prints the corresponding clone workflow.

For a pull request, check out the exact head you want to test:

gh repo clone <owner>/<repository>
cd <repository>
gh pr checkout <number>
rook

This keeps the source state, scenario evidence, and tested revision reproducible.

warning

Never clone or check out untrusted code and then run its setup scripts without reviewing them first.

Explore an External Local Directory

You can explicitly point interactive Rook at a directory outside the current workspace:

/explore ../another-agent

The path must be typed by a human. A model suggestion or stored record cannot grant a new external read scope.

Current external-workspace limitation

Rook can read and report an external directory, but the current pre-alpha release does not persist an external agent record. To keep discovery state and generate scenarios, cd into that checkout and start Rook there.

Rook also refuses two paths to keep read scope tight:

• A parent directory that contains the current workspace: This would mix evaluator files with target files.
• A single external file: Granting its entire parent directory would be broader than the path you selected.

Manage Multiple Agents

The browser inventory shows all registered agents and their scenario and run history.

Interactive commands:

/agent
/agent use <id>
/agent rm <id>

Headless commands:

rook agent list
rook agent list --json
rook agent use <id>

/agent rm forgets the agent and everything stored below its project record. Review the target ID carefully before using it.

Explore All Discovered Agents in Headless Mode

The interactive flow asks which candidates to register. For automation, use --all:

rook explore . --all --json

Use --allow only for a narrowly reviewed tool call:

rook explore . --allow 'bash(npm test)'

--allow is additive authorization. It does not create a sandbox, and it does not restrict any other already approved grant.

Re-Explore After Changes

Run /explore again when prompts, tools, policies, skills, or agent source change. Rook compares the current files with the stored index and updates the existing record, so it keeps your scenario and run history.

After exploration, run /generate to refresh scenarios. Rook shows a plan and names the stale prerequisite before it spends credits.