{"record":{"id":"87ecb51d7e8cb34e","repo":"pbakaus/impeccable","slug":"warning-user-level-agents-in-shadow-the-projec","errorCode":null,"errorMessage":"Warning: user-level agents in {} shadow the project copies just installed: {}.\n","messagePattern":"Warning: user-level agents in (.+?) shadow the project copies just installed: (.+?)\\.\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/skills/src/bundle.rs","lineNumber":773,"sourceCode":"        };\n        results.push(AgentResult { provider, written: agent_files.len(), dest_dir, user_dir, shadowed });\n    }\n    Ok(results)\n}\n\n/// JS: reportProviderAgents(results)\npub fn report_provider_agents(sys: &Sys, io: &mut Io, results: &[AgentResult]) {\n    for result in results {\n        if result.written == 0 {\n            continue;\n        }\n        io.out(&format!(\n            \"Installed {} agents into: {}\\n\",\n            provider_display_name(result.provider),\n            sys.format_path_for_display(&result.dest_dir)\n        ));\n        if !result.shadowed.is_empty() {\n            io.err(&format!(\n                \"Warning: user-level agents in {} shadow the project copies just installed: {}.\\n\",\n                sys.format_path_for_display(&result.user_dir),\n                result.shadowed.join(\", \")\n            ));\n            io.err(\"Run `npx impeccable update --user` to refresh them, or remove them so the project agents apply.\\n\");\n        }\n    }\n}\n\npub struct LinkSource {\n    pub checkout_root: String,\n    pub bundle_root: String,\n}\n\n/// JS: resolveLinkSource(sourceValue, root)\npub fn resolve_link_source(source_value: Option<&str>, root: &str) -> Result<LinkSource, String> {\n    let source_path = source_value.unwrap_or(\".impeccable\");\n    let checkout_root = if jsp::is_absolute(source_path) {","sourceCodeStart":755,"sourceCodeEnd":791,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/skills/src/bundle.rs#L755-L791","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Run `npx impeccable update --user` to refresh the user-level agents to the current versions.","Delete the listed user-level agent files so the project copies take effect.","Compare versions: if the user-level copies are current and preferred, ignore the warning.","Re-run the project install after cleaning up to confirm the warning is gone."],"exampleFix":"// before: shadowing user-level copy\nrm ~/.claude/agents/impeccable-design.md\n// after: project copy now applies; or refresh instead:\nnpx impeccable update --user\n","handlingStrategy":"validation","validationCode":"ls ~/.claude/agents 2>/dev/null | grep -l impeccable - >/dev/null && echo 'user-level impeccable agents present - run npx impeccable update --user first'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer one install scope (project or user) and stick to it.","Run `npx impeccable update --user` after project installs if you maintain user-level copies.","Audit the user-level agents directory periodically for stale files.","Exclude agent files from dotfiles syncs that shadow project installs."],"tags":["installation","agents","shadowing","path-conflict"],"backgroundTag":"agent-path-shadowing","analyzedSha":"2bc2879276c1f321a53c4ca99d3371e411329b52","analyzedAt":"2026-09-08T04:51:14.109Z","contentChangedAt":"2026-09-08T04:51:14.109Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}