### Run Examples

Source: https://github.com/whit3rabbit/agent-config/blob/main/CLAUDE.md

Commands to execute the example programs located in the `examples/` directory. Each example runs in a temporary directory.

```bash
cargo run --example hooks_install_uninstall
cargo run --example mcp_install
cargo run --example dry_run_plan
cargo run --example gen_schema      # regenerates schema/agents.json
```

--------------------------------

### Run TUI Example for Dry-Run Plans

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Executes a terminal UI example that visualizes dry-run installation plans across different agent harnesses and capabilities. No code modification is needed; it's run directly from the command line.

```bash
cargo run --example tui_dry_run
```

--------------------------------

### Instruction Install with File References

Source: https://github.com/whit3rabbit/agent-config/blob/main/examples/README.md

Demonstrates installing an instruction using `ReferencedFile`, `InlineBlock`, and `StandaloneFile`.

```rust
use agent_config::instructions::Instruction;
use agent_config::Scope;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    let tmp = tempdir()?;
    let scope = Scope::Local(tmp.path().to_path_buf());

    // Assume instruction definition with various file types is prepared.
    // Instruction::install(&scope, "instruction_id", "instruction_version", "path/to/instruction.toml")?;
    println!("Instruction install with ReferencedFile, InlineBlock, and StandaloneFile (example placeholder).");

    Ok(())
}

```

--------------------------------

### Skill Install with Executable Asset

Source: https://github.com/whit3rabbit/agent-config/blob/main/examples/README.md

Shows how to install a skill that includes frontmatter and an executable asset.

```rust
use agent_config::skills::Skill;
use agent_config::Scope;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    let tmp = tempdir()?;
    let scope = Scope::Local(tmp.path().to_path_buf());

    // Assume skill definition and executable asset are prepared.
    // Skill::install(&scope, "skill_id", "skill_version", "path/to/skill.toml")?;
    println!("Skill install with frontmatter and executable asset (example placeholder).");

    Ok(())
}

```

--------------------------------

### Install and Uninstall Hooks

Source: https://github.com/whit3rabbit/agent-config/blob/main/examples/README.md

Demonstrates the installation, idempotent reinstallation, and uninstallation of hooks.

```rust
use agent_config::hooks::Hooks;
use agent_config::Scope;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    let tmp = tempdir()?;
    let scope = Scope::Local(tmp.path().to_path_buf());

    // Install hooks
    Hooks::install(&scope)?;
    println!("Installed hooks.");

    // Idempotent reinstall hooks
    Hooks::install(&scope)?;
    println!("Reinstalled hooks (idempotent).");

    // Uninstall hooks
    Hooks::uninstall(&scope)?;
    println!("Uninstalled hooks.");

    Ok(())
}

```

--------------------------------

### MCP Install with Secret Handling

Source: https://github.com/whit3rabbit/agent-config/blob/main/examples/README.md

Demonstrates installing an MCP with `env_from_host` secret handling.

```rust
use agent_config::mcp::Mcp;
use agent_config::Scope;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    let tmp = tempdir()?;
    let scope = Scope::Local(tmp.path().to_path_buf());

    // Assume MCP definition and necessary environment variables are set up
    // This is a placeholder for a more complex MCP installation scenario.
    // Mcp::install(&scope, "mcp_id", "mcp_version", "path/to/mcp/definition.toml")?;
    println!("MCP install with env_from_host secret handling (example placeholder).");

    Ok(())
}

```

--------------------------------

### Skill Frontmatter Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/agent.md

Example frontmatter for a SKILL.md file. It includes the skill's name and a description of when to activate it, followed by the skill's goal.

```markdown
---
name: my-skill
description: When to activate this skill.
---

## Goal
...
```

--------------------------------

### Install an MCP Server

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Installs an MCP server with specified configuration. Use `env_from_host` for secrets or `allow_local_inline_secrets` for trusted configurations.

```rust
use agent_config::{mcp_by_id, McpSpec, Scope};

fn main() -> agent_config::Result<()> {
    let spec = McpSpec::builder("github")
        .owner("myapp")
        .stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
        .env_from_host("GITHUB_TOKEN")
        .try_build()?;

    let codex = mcp_by_id("codex").expect("codex supports MCP");
    codex.install_mcp(&Scope::Global, &spec)?;
    Ok(())
}
```

--------------------------------

### Install Hook with Rules

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Installs a hook and injects prompt rules simultaneously. Rules are added as a string to the HookSpec.

```rust
let spec = HookSpec::builder("myapp")
    .command_program("myapp", ["hook", "claude"])
    .matcher(Matcher::Bash)
    .event(Event::PreToolUse)
    .rules("Run `myapp lint` before committing.")
    .build();

```

--------------------------------

### Antigravity CLI Command Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/antigravity.md

Illustrates how to reference the Antigravity CLI, which is separate from the desktop app/IDE integration.

```text
antigravitycli
```

--------------------------------

### MCP Servers Configuration Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/agent.md

An example JSON object for configuring MCP servers. This map defines servers by name, specifying their command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": { "API_KEY": "secret" }
    }
  }
}
```

--------------------------------

### Preview Install Changes with Dry-Run Plan

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Generates an installation plan for an agent without making any filesystem changes. This allows inspection of planned changes, status (WillChange, NoOp, Refused), and potential file modifications before execution.

```rust
use agent_config::{by_id, PlanStatus};

let plan = by_id("claude").unwrap().plan_install(&scope, &spec)?;
match plan.status {
    PlanStatus::WillChange => println!("{}" change(s) planned", plan.changes.len()),
    PlanStatus::NoOp => println!("nothing to do"),
    PlanStatus::Refused => println!("refused: {:?}", plan.changes),
}
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/claude.md

Illustrates the frontmatter structure for a SKILL.md file, showcasing various configuration options for a skill.

```markdown
---
name: my-skill
description: Clear, specific trigger phrase for skill activation
when_to_use: Use for repository-specific review workflows
argument-hint: issue-id
arguments:
  - issue
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Read
  - Bash
disallowed-tools:
  - Write
model: inherit
effort: high
context: fork
agent: reviewer
paths:
  - src/**
shell: bash
---

## Goal
Describe what the skill does.

## Instructions
Step-by-step guidance.

## Examples
Usage examples.

## Constraints
Limitations or edge cases.
```

--------------------------------

### Install a Hook with HookSpec

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Installs a hook for a specific consumer tag, command, matcher, and event. Use `.try_build()?` for production code.

```rust
use agent_config::{by_id, Event, HookSpec, Matcher, Scope};

fn main() -> agent_config::Result<()> {
    let spec = HookSpec::builder("myapp")              // your consumer tag
        .command_program("myapp", ["hook", "claude"])  // what the harness runs
        .matcher(Matcher::Bash)                        // filter to shell calls
        .event(Event::PreToolUse)                      // before each tool call
        .try_build()?;

    let claude = by_id("claude").expect("claude is registered");
    let report = claude.install(&Scope::Global, &spec)?;

    println!("created: {:?}", report.created);
    println!("patched: {:?}", report.patched);
    println!("backed up: {:?}", report.backed_up);
    Ok(())
}

```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/claude.md

An example of how to configure MCP servers in Claude Code. This JSON structure defines server details, including command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Install an Instruction

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Installs a new instruction with a specified owner, placement, and body. The instruction is tracked in a ledger for co-existence of multiple consumers. Use this when you need to add project-specific guidance loaded into the agent every session.

```rust
use agent_config::{instruction_by_id, InstructionPlacement, InstructionSpec, Scope};

fn main() -> agent_config::Result<()> {
    let spec = InstructionSpec::builder("MYAPP")
        .owner("myapp")
        .placement(InstructionPlacement::ReferencedFile)
        .body("# MyApp\n\nProject-specific guidance loaded into the agent every session.\n")
        .try_build()?;

    let claude = instruction_by_id("claude").expect("claude instruction-capable");
    let report = claude.install_instruction(&Scope::Global, &spec)?;
    println!("created: {:?}", report.created);
    println!("patched: {:?}", report.patched);
    Ok(())
}
```

--------------------------------

### CodeBuddy Hooks Configuration Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/codebuddy.md

Example JSON structure for configuring CodeBuddy hooks, specifying event types, matchers, and commands.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "myapp hook codebuddy" }],
        "_agent_config_tag": "myapp"
      }
    ]
  }
}
```

--------------------------------

### Install MCP Servers from JSON Object Map

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/README.md

Use this function when your harness reads MCP servers from a JSON object map keyed by name. It delegates to `mcp_json_object` for installation.

```rust
fn install_mcp(&self, scope: &Scope, spec: &McpSpec) -> Result<InstallReport, AgentConfigError> {
    spec.validate()?;
    let cfg    = Self::mcp_path(scope)?;
    let ledger = ownership::mcp_ledger_for(&cfg);
    mcp_json_object::install(&cfg, &ledger, spec)
}
```

--------------------------------

### Install a Skill

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Installs a skill with a specified configuration. Skills can be configured to disable model invocation and include custom body content.

```rust
use agent_config::{skill_by_id, Scope, SkillSpec};

fn main() -> agent_config::Result<()> {
    let spec = SkillSpec::builder("my-skill")
        .owner("myapp")
        .description("Use when my app needs custom repository context.")
        .disable_model_invocation(true)
        .body("# My Skill\n\nFollow the local project conventions.")
        .try_build()?;

    let claude = skill_by_id("claude").expect("claude supports skills");
    claude.install_skill(&Scope::Global, &spec)?;
    Ok(())
}
```

--------------------------------

### Tabnine Hooks Configuration

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/tabnine.md

Example of configuring Tabnine hooks for the 'BeforeTool' event, specifying a 'Bash' matcher and a 'command' hook.

```json
{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "myapp hook tabnine" }],
        "_agent_config_tag": "myapp"
      }
    ]
  }
}
```

--------------------------------

### Codex MCP Server Configuration

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/codex.md

Example TOML configuration for setting up MCP servers in Codex. Supports stdio and http transports.

```toml
[mcp_servers.my_server]
command = "node"
args = ["/path/to/server.js"]

[mcp_servers.my_server.env]
API_KEY = "${API_KEY}"
```

--------------------------------

### Cursor MCP Server Configuration

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/cursor.md

Example JSON configuration for setting up an MCP server within Cursor. This allows for custom server integrations. Changes require restarting Cursor.

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}
```

--------------------------------

### OpenCode MCP Server Configuration

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/opencode.md

Example JSON configuration for setting up a local MCP server for OpenCode. This configuration specifies the server type, command to execute, and can be placed in either user or project scope configuration files.

```json
{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["node", "/path/to/server.js"]
    }
  }
}
```

--------------------------------

### JSON Structure for MCP Servers

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/README.md

Example JSON structure for configuring MCP servers, where the 'mcpServers' key holds an object map of server configurations.

```json
{ "mcpServers": { "my-server": { "command": "node", "args": [...] } } }
```

--------------------------------

### Example Path Helper Function

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/README.md

Illustrates how to define a path helper function that resolves paths based on the provided scope (Global or Local). This is crucial for managing agent configurations across different environments.

```rust
fn settings_path(scope: &Scope) -> Result<PathBuf, AgentConfigError> {
    Ok(match scope {
        Scope::Global    => paths::claude_home()?.join("settings.json"),
        Scope::Local(p)  => p.join(".claude").join("settings.json"),
    })
}
```

--------------------------------

### Kilo Code MCP Server Configuration Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/kilocode.md

This JSONC snippet shows how to configure an MCP server for Kilo Code. It includes server type, command to run, and environment variables.

```jsonc
{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["node", "/path/to/server.js"],
      "environment": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Antigravity CLI MCP Server Configuration (Local)

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/antigravitycli.md

Configure local MCP servers for the Antigravity CLI. This example shows a Node.js server for SQLite exploration.

```json
{
  "mcpServers": {
    "sqlite-explorer": {
      "command": "node",
      "args": ["/usr/local/bin/sqlite-mcp-server.js"],
      "env": {
        "SQLITE_DB_PATH": "/var/data/app.db"
      }
    }
  }
}
```

--------------------------------

### MCP Servers Configuration

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/amp.md

Example JSON configuration for MCP servers. This defines how Amp connects to and manages MCP servers, including the command and arguments to execute.

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@example/server"]
    }
  }
}
```

--------------------------------

### iFlow Hooks Configuration Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/iflow.md

This JSON structure defines how to configure hooks for the iFlow CLI. It specifies event types like 'PreToolUse' and maps them to specific commands or actions, with an optional agent configuration tag.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "myapp hook iflow" }],
        "_agent_config_tag": "myapp"
      }
    ]
  }
}
```

--------------------------------

### Install MCP Servers using TOML Patch

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/README.md

This pattern is for harnesses using TOML for MCP server configuration. It involves building a TOML table and using `toml_patch` functions for reading, checking ownership, and upserting.

```rust
toml_patch::read_or_empty(&cfg)
toml_patch::contains_named_table(&doc, &["mcp_servers"], &spec.name)
toml_patch::upsert_named_table(&mut doc, &["mcp_servers"], &spec.name,
  build_mcp_table(spec))
toml_patch::to_string(&doc)
ownership::record_install(&ledger, &spec.name, &spec.owner_tag, hash)
```

--------------------------------

### Markdown Block Upsert Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/templates/new-harness/README.md

This markdown snippet shows how an agent configuration block is inserted into a file. The 'BEGIN' and 'END' tags are used to identify and manage the block.

```markdown
<!-- BEGIN AGENT-CONFIG:myapp -->
Use myapp prefix.
<!-- END AGENT-CONFIG:myapp -->
```

--------------------------------

### Cline Hook Return Fields Example

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/cline.md

Hooks can return JSON to control task execution and provide context. This example shows the structure for returning cancellation status and additional context.

```json
{
  "cancel": false,
  "contextModification": "additional context for the task",
  "errorMessage": "optional error message"
}
```

--------------------------------

### Build and Test Rust Library

Source: https://github.com/whit3rabbit/agent-config/blob/main/CLAUDE.md

Standard commands for building the library, running unit and integration tests, and generating documentation. Use `cargo clippy` for linting.

```bash
cargo build                    # build the library
cargo test                     # run all tests (unit + integration)
cargo test --lib               # unit tests only
cargo test --test registry     # integration tests only
cargo test <test_name>         # run a single test by name
cargo doc --no-deps            # generate rustdoc
cargo clippy --all-targets     # lints lib + tests + examples
```

--------------------------------

### Dry Run Plan Install/Uninstall

Source: https://github.com/whit3rabbit/agent-config/blob/main/examples/README.md

Provides previews of `plan_install` and `plan_uninstall` operations without making any changes.

```rust
use agent_config::plan::{plan_install, plan_uninstall};
use agent_config::Scope;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    let tmp = tempdir()?;
    let scope = Scope::Local(tmp.path().to_path_buf());

    // Perform a dry run of installation
    let install_plan = plan_install(&scope, "agent_id", "agent_version")?;
    println!("Dry run install plan: {:?}", install_plan);

    // Perform a dry run of uninstallation
    let uninstall_plan = plan_uninstall(&scope, "agent_id", "agent_version")?;
    println!("Dry run uninstall plan: {:?}", uninstall_plan);

    Ok(())
}

```

--------------------------------

### Release Preparation Commands

Source: https://github.com/whit3rabbit/agent-config/blob/main/CLAUDE.md

Commands to run before creating or moving a release tag. Ensures the project is tested, linted, and a dry run of publishing is successful.

```bash
cargo test --locked --all-targets
cargo clippy --locked --all-targets -- -D warnings
cargo publish --locked --dry-run
```

--------------------------------

### Uninstall an Instruction

Source: https://github.com/whit3rabbit/agent-config/blob/main/README.md

Uninstalls a previously installed instruction. The uninstallation is keyed on the instruction's name and owner tag, mirroring MCP and skills.

```rust
let claude = agent_config::instruction_by_id("claude").unwrap();
claude.uninstall_instruction(&agent_config::Scope::Global, "MYAPP", "myapp")?;
```

--------------------------------

### Antigravity CLI MCP Server Configuration (Remote)

Source: https://github.com/whit3rabbit/agent-config/blob/main/docs/agents/antigravitycli.md

Configure remote MCP servers for the Antigravity CLI. This example specifies a server URL and authorization headers.

```json
{
  "mcpServers": {
    "remote-indexer": {
      "serverUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer TOKEN"
      }
    }
  }
}
```

--------------------------------

### Regenerate Schema Golden Fixture

Source: https://github.com/whit3rabbit/agent-config/blob/main/CLAUDE.md

Command to regenerate the `schema/agents.json` snapshot. Set `AGENT_SCHEMA_UPDATE` or use `cargo run --example gen_schema`. This test is platform-specific.

```bash
AGENT_SCHEMA_UPDATE=1 cargo test --test schema_golden
# or, equivalently
cargo run --example gen_schema
```