Crate agent_config

Expand description

agent-config installs hooks, prompt rules, MCP servers, and skills into AI coding harnesses.

The library knows where each harness keeps its configuration and what shape that configuration takes. Callers supply a HookSpec, McpSpec, or SkillSpec. The library handles atomic writes, backups, ownership ledgers, and idempotent edits.

§Production usage

In production code, prefer try_build() over the panicking build() so that invalid specs propagate as Result errors instead of panics:

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

fn install_my_hook() -> agent_config::Result<()> {
    let spec = HookSpec::builder("myapp")
        .command_program("myapp", ["hook", "claude"])
        .matcher(Matcher::Bash)
        .event(Event::PreToolUse)
        .try_build()?;

    let claude = by_id("claude").expect("claude integration registered");
    claude.install(&Scope::Global, &spec)?;
    Ok(())
}

build() is also available as a convenience for tests and examples where a panic on misconfiguration is acceptable.

§Quick start

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

let spec = HookSpec::builder("myapp")
    .command_program("myapp", ["hook", "claude"])
    .matcher(Matcher::Bash)
    .event(Event::PreToolUse)
    .build();

let claude = by_id("claude").expect("claude integration registered");
claude.install(&Scope::Global, &spec).unwrap();

§MCP servers

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

let spec = McpSpec::builder("github")
    .owner("myapp")
    .stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
    .build();

let codex = mcp_by_id("codex").expect("codex MCP support registered");
codex.install_mcp(&Scope::Global, &spec).unwrap();

§Skills

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

let spec = SkillSpec::builder("my-skill")
    .owner("myapp")
    .description("Use when my app needs custom repository context.")
    .body("# My Skill\n\nFollow the local project conventions.")
    .build();

let claude = skill_by_id("claude").expect("claude skill support registered");
claude.install_skill(&Scope::Global, &spec).unwrap();

§Discovery and uninstall

use agent_config::{all, by_id, Scope};

for integration in all() {
    if integration.supported_scopes().contains(&Scope::Global.kind())
        && integration.is_installed(&Scope::Global, "myapp").unwrap_or(false)
    {
        println!("{} has myapp installed", integration.display_name());
    }
}

let claude = by_id("claude").expect("claude integration registered");
claude.uninstall(&Scope::Global, "myapp").unwrap();

§Safety guarantees

Atomic writes (write-to-temp + rename).
First-touch .bak backups of any pre-existing file we modify.
Idempotent installs: repeating install with the same tag yields the same state.
Reversible: uninstall removes only the tagged content.

§Concrete agent types

When the target harness is known at compile time, construct the agent directly for type-safe, discoverable usage:

use agent_config::{ClaudeAgent, Integration, HookSpec, Matcher, Event, Scope};

fn main() -> agent_config::Result<()> {
    let claude = ClaudeAgent::new();
    let spec = HookSpec::builder("myapp")
        .command_program("myapp", ["hook", "claude"])
        .matcher(Matcher::Bash)
        .event(Event::PreToolUse)
        .try_build()?;

    claude.install(&Scope::Global, &spec)?;
    Ok(())
}

The registry API (by_id, mcp_by_id, skill_by_id) remains the recommended path for CLIs and tools that accept integration IDs from user input at runtime. Concrete types are stable convenience handles for compile-time usage.

Re-exports§

pub use error::AgentConfigError;
pub use integration::InstallReport;
pub use integration::InstructionSurface;
pub use integration::Integration;
pub use integration::McpSurface;
pub use integration::MigrationReport;
pub use integration::SkillSurface;
pub use integration::UninstallReport;
pub use plan::InstallPlan;
pub use plan::PlanStatus;
pub use plan::PlanTarget;
pub use plan::PlanWarning;
pub use plan::PlannedChange;
pub use plan::RefusalReason;
pub use plan::UninstallPlan;
pub use registry::all;
pub use registry::by_id;
pub use registry::instruction_by_id;
pub use registry::instruction_capable;
pub use registry::mcp_by_id;
pub use registry::mcp_capable;
pub use registry::skill_by_id;
pub use registry::skill_capable;
pub use scope::Scope;
pub use scope::ScopeKind;
pub use spec::Event;
pub use spec::HookCommand;
pub use spec::HookSpec;
pub use spec::HookSpecBuilder;
pub use spec::InstructionPlacement;
pub use spec::InstructionSpec;
pub use spec::InstructionSpecBuilder;
pub use spec::Matcher;
pub use spec::McpSpec;
pub use spec::McpSpecBuilder;
pub use spec::McpTransport;
pub use spec::RulesBlock;
pub use spec::ScriptTemplate;
pub use spec::SecretPolicy;
pub use spec::SkillAsset;
pub use spec::SkillContext;
pub use spec::SkillEffort;
pub use spec::SkillFrontmatter;
pub use spec::SkillShell;
pub use spec::SkillSpec;
pub use spec::SkillSpecBuilder;
pub use status::DriftIssue;
pub use status::InstallStatus;
pub use status::PathStatus;
pub use status::PlanTarget as StatusPlanTarget;
pub use status::StatusReport;
pub use status::StatusWarning;
pub use validation::SuggestedAction;
pub use validation::ValidationReport;

Modules§

error: Public error type for the crate.
integration: The contract every AI-harness integration implements.
paths: Cross-platform resolution of the per-user directories that AI harnesses use.
plan: Side-effect-free install and uninstall planning.
registry: Lookup of registered integrations.
schema: Live JSON manifest of every registered agent’s file layout, surface coverage, and marker conventions.
scope: Where a hook should be installed: globally for the user, or scoped to a single project directory.
spec: Caller-supplied description of a hook (or MCP server, or skill) to install.
status: Richer install-state reporting for hooks, MCP servers, and skills.
validation: Side-effect-free drift validation reports.

Structs§

AmpAgent: Amp CLI installer.
AntigravityAgent: Google Antigravity integration.
ClaudeAgent: Claude Code (Anthropic’s official CLI).
ClineAgent: Cline integration.
CodeBuddyAgent: Tencent CodeBuddy CLI installer.
CodexAgent: Codex CLI.
CopilotAgent: GitHub Copilot.
CursorAgent: Cursor (the AI editor and CLI).
ForgeAgent: Forge CLI installer.
GeminiAgent: Gemini CLI (Google’s official Gemini code agent).
HermesAgent: Hermes Agent file-backed installer.
IFlowAgent: iFlow CLI installer.
JunieAgent: JetBrains Junie installer.
KiloCodeAgent: Kilo Code integration.
OpenClawAgent: OpenClaw file-backed installer.
OpenCodeAgent: OpenCode plugin installer.
QoderCliAgent: Qoder CLI installer.
QwenAgent: Qwen Code installer.
RooAgent: Roo Code integration.
TabnineAgent: Tabnine CLI installer.
TraeAgent: Trae agent installer.
WindsurfAgent: Windsurf integration.

Type Aliases§

Result: Result alias used throughout the crate’s public API.