pbakaus/impeccable · warning

Warning: user-level agents in {} shadow the project copies j

Error message

Warning: user-level agents in {} shadow the project copies just installed: {}.

What it means

After installing agents into a project, `report_provider_agents` checks whether user-level (home-directory) copies of the same agent names exist. Because user-level agents take precedence, the freshly installed project agents would be shadowed and never load, so this warning lists the offending files and where they live.

Source

Thrown at crates/skills/src/bundle.rs:773

        };
        results.push(AgentResult { provider, written: agent_files.len(), dest_dir, user_dir, shadowed });
    }
    Ok(results)
}

/// JS: reportProviderAgents(results)
pub fn report_provider_agents(sys: &Sys, io: &mut Io, results: &[AgentResult]) {
    for result in results {
        if result.written == 0 {
            continue;
        }
        io.out(&format!(
            "Installed {} agents into: {}\n",
            provider_display_name(result.provider),
            sys.format_path_for_display(&result.dest_dir)
        ));
        if !result.shadowed.is_empty() {
            io.err(&format!(
                "Warning: user-level agents in {} shadow the project copies just installed: {}.\n",
                sys.format_path_for_display(&result.user_dir),
                result.shadowed.join(", ")
            ));
            io.err("Run `npx impeccable update --user` to refresh them, or remove them so the project agents apply.\n");
        }
    }
}

pub struct LinkSource {
    pub checkout_root: String,
    pub bundle_root: String,
}

/// JS: resolveLinkSource(sourceValue, root)
pub fn resolve_link_source(source_value: Option<&str>, root: &str) -> Result<LinkSource, String> {
    let source_path = source_value.unwrap_or(".impeccable");
    let checkout_root = if jsp::is_absolute(source_path) {

View on GitHub (pinned to 2bc2879276)

Solutions

1. Run `npx impeccable update --user` to refresh the user-level agents to the current versions.
2. Delete the listed user-level agent files so the project copies take effect.
3. Compare versions: if the user-level copies are current and preferred, ignore the warning.
4. Re-run the project install after cleaning up to confirm the warning is gone.

Example fix

// before: shadowing user-level copy
rm ~/.claude/agents/impeccable-design.md
// after: project copy now applies; or refresh instead:
npx impeccable update --user

ls ~/.claude/agents 2>/dev/null | grep -l impeccable - >/dev/null && echo 'user-level impeccable agents present - run npx impeccable update --user first'

When it happens

Trigger: Running `impeccable skills install` (or provider install flow) when `result.shadowed` is non-empty — i.e. agent filenames installed into the project already exist under the user-level agents directory (e.g. ~/.claude/agents or equivalent).

Common situations: Previously ran `impeccable skills install --user` or `update --user` and now installing project-level; older user-level agent copies left from an earlier version; syncing dotfiles that place agents in the home config directory.

Related errors

• Run `npx impeccable update --user` to refresh them, or remov
• Skipped existing {provider}/skills/{skill}. Use --force to r

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/87ecb51d7e8cb34e. Report an issue: GitHub.