Struct AgentsRoot 

pub struct AgentsRoot { /* private fields */ }

Root directory of Claude Code’s user-level agent definitions. Defaults to ~/.claude/agents; override with AgentsRoot::at for tests or non-default installs.

Implementations

impl AgentsRoot

pub fn home() -> Result<Self>

Resolve the default ~/.claude/agents. Errors if $HOME (or the platform-specific user home) cannot be determined.

pub fn at(path: impl Into<PathBuf>) -> Self

Use a specific path as the agents root. Useful for tests (point at a tempdir) and for non-default installs.

pub fn path(&self) -> &Path

The configured root directory.

pub fn list(&self) -> Result<Vec<AgentSummary>>

List every *.md agent at the root, sorted by file stem.

Returns an empty vec if the root directory doesn’t exist (a fresh Claude Code install with no user agents). Files that fail to parse contribute a tracing warning and are skipped rather than failing the whole listing.

pub fn get(&self, file_stem: &str) -> Result<Agent>

Read one agent by file stem (i.e. the basename of <stem>.md under the root). Errors if no such file exists or it fails to parse.

pub fn write(&self, file_stem: &str, input: AgentWriteInput) -> Result<()>

Write (create or overwrite) an agent at <file_stem>.md.

Atomic: writes to a temp file in the same directory and renames into place, so a crash mid-write can’t leave a partially-written file. Creates the agents root directory if it doesn’t exist.

file_stem is validated for path traversal and reserved names (empty, ., .., embedded slashes / NUL bytes). To fail when the agent already exists instead of overwriting, use Self::write_new.

pub fn write_new(&self, file_stem: &str, input: AgentWriteInput) -> Result<()>

Like Self::write but errors if the agent already exists. Useful for “create only” flows where overwriting an existing agent would be a bug.

pub fn delete(&self, file_stem: &str) -> Result<()>

Remove the <file_stem>.md agent. Errors if no such file exists.

Trait Implementations

impl Clone for AgentsRoot

fn clone(&self) -> AgentsRoot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentsRoot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.