What causes "Agent '{}' already exists at {}" in nikivdev/code?

Pick a different, unused agent name

Agent '{}' already exists at {}

Error message

Agent '{}' already exists at {}

What it means

`create_agent` scaffolds a new agent markdown file under `.flow/agents/<name>.md` (or a caller-supplied path). To avoid silently clobbering user-authored agents, it bails with this error if the target file already exists, echoing the agent name and full path.

Source

Thrown at src/hive.rs:375

    Ok(())
}

/// Create a new agent spec file
pub fn create_agent(name: &str, global: bool) -> Result<PathBuf> {
    let path = if global {
        let home = dirs::home_dir().context("Could not find home directory")?;
        let dir = home.join(".hive/agents").join(name);
        fs::create_dir_all(&dir)?;
        dir.join("spec.md")
    } else {
        let dir = PathBuf::from(".flow/agents");
        fs::create_dir_all(&dir)?;
        dir.join(format!("{}.md", name))
    };

    if path.exists() {
        anyhow::bail!("Agent '{}' already exists at {}", name, path.display());
    }

    let template = format!(
        r#"# Agent: {}
# Purpose: <describe what this agent does>
#
# Rules:
# - <rule 1>
# - <rule 2>
#
# Tools:
# - bash
"#,
        name
    );

    fs::write(&path, template)?;
    Ok(path)

View on GitHub (pinned to a747e741ae)

Solutions

Pick a different, unused agent name
Delete or rename the existing file first: `mv .flow/agents/<name>.md .flow/agents/<name>.bak`
If intentional, remove the existing file before recreating: `rm .flow/agents/<name>.md`
Edit the existing agent file in place instead of re-scaffolding

Example fix

// before
create_agent("reviewer")?; // .flow/agents/reviewer.md exists
// after
let path = PathBuf::from(".flow/agents/reviewer.md");
if !path.exists() {
    create_agent("reviewer")?;
} else {
    eprintln!("reusing existing agent at {}", path.display());
}

Defensive patterns

Strategy: validation

Validate before calling

let path = PathBuf::from(format!(".flow/agents/{}.md", name));
if path.exists() {
    eprintln!("agent '{}' already exists at {}", name, path.display());
    std::process::exit(1);
}

Type guard

fn agent_file_exists(name: &str) -> bool {
    PathBuf::from(format!(".flow/agents/{}.md", name)).exists()
}

Try / catch

match create_agent(name) {
    Err(e) if e.to_string().contains("already exists") => {
        eprintln!("{e}");
        eprintln!("choose a new name, or edit the existing file");
    }
    r => r?,
}

Prevention

Check for the target file before scaffolding; prompt to overwrite if intended
Use unique, descriptive agent names (prefix by team/feature) to avoid collisions
Don't commit agent re-scaffolding scripts that run unconditionally
Keep `.flow/agents/` reviewed in version control so collisions are visible in PRs

When it happens

Trigger: Running `create_agent` with a name whose `<name>.md` file already exists in `.flow/agents/` (or at the resolved path); re-running a scaffold script that already ran once.

Common situations: Re-running an init/scaffold command after a previous successful creation; name collision with an agent created by a teammate or checked into the repo; expecting the command to overwrite/regenerate an existing agent template.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/15c8d6ca0850fe8d. Report an issue: GitHub.