3  Agent Guide

3.1 What This Page Helps You Do

This guide is for users who want to connect IOBRpy to Codex or Claude Code. It focuses on three practical goals:

  1. How to install /iobrpy for workflow assistance and /iobrpy-result for result interpretation and visualization.
  2. How to verify that the installation worked.
  3. When to use /iobrpy versus /iobrpy-result.

3.2 Tutorial 1: How to Install the Plugin

3.2.1 Step 0: Activate the IOBRpy Environment

This page assumes that IOBRpy is already installed. If not, please read installation guide first. Here, the only environment preparation you need is:

conda activate iobrpy

3.2.2 Step 1: Run the Installation Command

Choose the one command that matches your actual client:

# Claude Code only
iobrpy-cli agent install --client claude-code

# Codex only
iobrpy-cli agent install --client codex

# Both Codex and Claude Code
iobrpy-cli agent install --client all

What this installs:

  • codex: the /iobrpy and /iobrpy-result skills, both Codex plugins, and MCP integration.
  • claude-code: the Claude Code memories, /iobrpy and /iobrpy-result commands, and MCP integration.
  • all: both of the above.

Reference standard:

  • The command finishes successfully instead of exiting with an error.
  • If a component was already present, an already_installed-style result is still acceptable.
  • You should not need to manually copy plugin, skill, or MCP files.

3.2.3 Step 2: Verify the Installation

Use the status command that matches what you installed:

# Check Codex only
iobrpy-cli agent status --client codex

# Check Claude Code only
iobrpy-cli agent status --client claude-code

# Check everything
iobrpy-cli agent status

Reference standard:

  • Ideally, the output should include Agent status: healthy.
  • You should no longer see states such as not_installed, not_configured, or invalid_config.
  • After installation, the relevant client should be able to use /iobrpy and /iobrpy-result.

3.2.4 Step 3: Call the Plugin Inside the Agent

After installation, open your agent client and call the IOBRpy entrypoint directly in the chat input.

IOBRpy provides two agent entrypoints:

  • /iobrpy is for analysis setup and execution. Use it to inspect input data, choose the right IOBRpy workflow, and prepare or run commands.
  • /iobrpy-result is for finished outputs. Use it to summarize, audit, interpret, compare, or visualize IOBRpy result directories and result tables.

If you are using Codex and specifically want the plugin-scoped namespace, you can also use:

/iobrpy:iobrpy

Reference standard:

  • Typing /iobrpy in the agent should show or trigger the IOBRpy entrypoint.
  • Typing /iobrpy-result should trigger IOBRpy-specific result visualization and interpretation.
  • After you send a message with /iobrpy, the agent should respond as an IOBRpy workflow assistant rather than a generic chat assistant.
  • After you send a message with /iobrpy-result, the agent should focus on existing result files rather than planning a new run by default.
  • In Codex, /iobrpy:iobrpy should also work when you want the plugin namespace explicitly.
  • The best first test is to give a real path or a concrete analysis goal, not just /iobrpy or /iobrpy-result alone.

3.3 Common Problems and Fixes

Symptom Common cause Suggested fix
iobrpy-cli is not recognized The current shell is not in the right environment, or IOBRpy is not installed yet Activate the environment with conda activate iobrpy, and if needed follow the installation guide first
agent status shows needs attention One client is missing part of the skill, plugin, or MCP setup Check iobrpy-cli --json agent status first, then rerun the relevant agent install --client ... command
Codex does not show /iobrpy or /iobrpy-result The skill or plugin did not take effect Rerun iobrpy-cli agent install --client codex --force
Claude Code installation fails The claude CLI is missing, or the config path is not writable Install or fix the Claude Code CLI setup, then retry iobrpy-cli agent install --client claude-code
You suspect the setup is outdated Older local agent files may still be present Rerun the matching iobrpy-cli agent install --client ... command and check status again

3.4 Tutorial 2: Prompt Examples

3.4.1 1. /iobrpy: Workflow Assistance

Use /iobrpy before or during analysis, especially when you are not yet sure what the directory contains or which workflow command is the right one.

/iobrpy Please scan path/to/your/target/directory
Show me the full checklist first, then tell me the current stage and the best next step.

After the scan, the agent will usually tell you which workflow best matches your directory and your current stage.

Typical examples:

  • If the directory contains raw FASTQ data, the agent will usually suggest runall.
  • If the directory already contains a TPM matrix, the agent will usually suggest tme_profile.
  • If the directory contains BAM files for HLA analysis, the agent will usually suggest hla_typing.
  • If the goal is TCR/BCR repertoire analysis, the agent will usually suggest trust4.

This means you do not need to decide the command first. Start with the scan, then choose the command that matches the agent’s recommendation and your real analysis goal.

Reference standard:

  • Your first prompt includes a real path.
  • The agent returns a checklist and a current-stage summary.
  • You choose the next command based on the scan result instead of guessing before the scan.

3.4.2 2. /iobrpy-result: Result Interpretation and Visualization

Use /iobrpy-result after IOBRpy has already generated result files.

/iobrpy-result Please summarize, interpret, and visualize path/to/iobrpy/result/directory

Typical examples:

  • If you want to understand what has already been generated, ask /iobrpy-result to summarize the result directory.
  • If you want biological interpretation, point /iobrpy-result to the output table or workflow output directory.
  • If you want a figure, explicitly ask /iobrpy-result to visualize the result and say whether you prefer Python or R.
  • If you ask for visualization without naming a backend, /iobrpy-result will ask you to choose Python or R before creating figures.

Reference standard:

  • Use /iobrpy-result for result reading, interpretation, comparison, and visualization.
  • Use /iobrpy when you still need to choose, configure, or run an IOBRpy workflow.