Users should be able to choose which existing Claude and Codex customization they want in a coop VM without reconstructing their setup manually or understanding each agent's directory layout.
Investigating #457 exposed a broader design question: host agent directories mix reusable instructions, skills, extensions, preferences, credentials, and runtime state. Expanding path allowlists alone increasingly requires implicit migration and lifecycle decisions. This proposal tracks a guided setup workflow separately so it does not delay the original reporter's bounded import fix.
Desired experience
A command such as coop agent setup --claude or --codex (names illustrative) discovers supported customization and presents a concrete selection:
- Personal instructions, including effective override precedence.
- Skills and complete extension bundles.
- Custom agents.
- Agent-specific rules and supported preferences.
- Hooks and other executable automation, identified as such.
- Installed plugins and their available source/version information.
Start with categories and allow individual selections. Offer a clean setup, an additional source file/directory, and an unattended way to apply an existing selection. Explain unsupported items and missing dependencies specifically. Do not require a prompt per file or per VM restart.
Save a reusable agent profile and apply it automatically to new VMs. Selection should default to the items discovered now, rather than silently enrolling future host additions. An explicit refresh should show additions, changes, and removals.
Cross-agent requirements
Provide equivalent outcomes and a common profile lifecycle, with agent-specific discovery and installation logic. Do not force native formats into identical semantics.
Claude needs complete skills-directory plugin bundles and relevant enable/disable choices; copying a host-disabled bundle without its preferences can activate it in the guest. Standalone hook support requires registrations and supporting files together.
Codex needs discovery across its personal skill and config roots, effective AGENTS.override.md precedence, path-based disabled-skill relocation, and its own custom-agent, execution-rule, hook, and plugin semantics. Repository content already transported with the workspace, bundled/system skills, and personal content must remain distinguishable.
Keep authentication under coop's existing mechanisms. Account access and remote capabilities are not transferable merely by copying plugin metadata. Preserve coop-managed routing/permissions and guest-owned configuration outside the imported selection.
Discovery should use supported manifests, configuration, and native discovery interfaces where suitable. It should not execute host customization or infer arbitrary installation commands from instruction text. Prefer native bundle discovery or documented installers; avoid converting all content into a synthetic plugin, copying whole agent homes, or importing arbitrary caches.
Decisions to resolve before implementation
- Snapshot local assets at setup time versus reference live host paths. A saved selection should have explicit reproducibility and refresh semantics.
- Ownership and precedence when host imports and guest edits overlap; safe repeated application and explicit removal behavior.
- Applying profiles to existing VMs, including failures, retries, and partial installation. Initial support may target new VMs.
- Plugin source/version pinning and architecture-specific dependencies; define what can and cannot be reproduced.
- Cross-platform host paths, symlinked dotfiles, and external dependencies. Do not rewrite arbitrary shell commands speculatively.
- Migration from existing
claude.config_dir / codex.config_dir behavior without surprising existing users.
- Integration with initial onboarding, noninteractive operation, and the existing
coop agent update command.
- How to keep profile application consistent across Lima and Firecracker without exposing user customization in shared images unintentionally.
Acceptance direction
A user with supported local instructions and skills can discover them, select them once, and create a working VM without manually copying files or reinstalling self-contained bundles. Relevant disabled state is preserved. Restart does not prompt or silently enroll new host content. A saved profile can be reapplied predictably, while unrelated guest configuration and existing authentication boundaries remain intact.
Test discovery and selections independently of the UI, and exercise actual agent loading on both VM backends. Clearly report unsupported configurations rather than claiming a full host clone.
Codex already documents skill discovery and selective external-agent migration interfaces, which are useful precedent for the interaction. They are not a general host-to-VM export API; its app-server plugin APIs are currently marked under development and should not be assumed production-ready.
References: Claude skills-directory plugins, Codex skills, Codex app-server.
This issue does not replace or block #457 or the focused Codex companion #461.
Users should be able to choose which existing Claude and Codex customization they want in a coop VM without reconstructing their setup manually or understanding each agent's directory layout.
Investigating #457 exposed a broader design question: host agent directories mix reusable instructions, skills, extensions, preferences, credentials, and runtime state. Expanding path allowlists alone increasingly requires implicit migration and lifecycle decisions. This proposal tracks a guided setup workflow separately so it does not delay the original reporter's bounded import fix.
Desired experience
A command such as
coop agent setup --claudeor--codex(names illustrative) discovers supported customization and presents a concrete selection:Start with categories and allow individual selections. Offer a clean setup, an additional source file/directory, and an unattended way to apply an existing selection. Explain unsupported items and missing dependencies specifically. Do not require a prompt per file or per VM restart.
Save a reusable agent profile and apply it automatically to new VMs. Selection should default to the items discovered now, rather than silently enrolling future host additions. An explicit refresh should show additions, changes, and removals.
Cross-agent requirements
Provide equivalent outcomes and a common profile lifecycle, with agent-specific discovery and installation logic. Do not force native formats into identical semantics.
Claude needs complete skills-directory plugin bundles and relevant enable/disable choices; copying a host-disabled bundle without its preferences can activate it in the guest. Standalone hook support requires registrations and supporting files together.
Codex needs discovery across its personal skill and config roots, effective
AGENTS.override.mdprecedence, path-based disabled-skill relocation, and its own custom-agent, execution-rule, hook, and plugin semantics. Repository content already transported with the workspace, bundled/system skills, and personal content must remain distinguishable.Keep authentication under coop's existing mechanisms. Account access and remote capabilities are not transferable merely by copying plugin metadata. Preserve coop-managed routing/permissions and guest-owned configuration outside the imported selection.
Discovery should use supported manifests, configuration, and native discovery interfaces where suitable. It should not execute host customization or infer arbitrary installation commands from instruction text. Prefer native bundle discovery or documented installers; avoid converting all content into a synthetic plugin, copying whole agent homes, or importing arbitrary caches.
Decisions to resolve before implementation
claude.config_dir/codex.config_dirbehavior without surprising existing users.coop agent updatecommand.Acceptance direction
A user with supported local instructions and skills can discover them, select them once, and create a working VM without manually copying files or reinstalling self-contained bundles. Relevant disabled state is preserved. Restart does not prompt or silently enroll new host content. A saved profile can be reapplied predictably, while unrelated guest configuration and existing authentication boundaries remain intact.
Test discovery and selections independently of the UI, and exercise actual agent loading on both VM backends. Clearly report unsupported configurations rather than claiming a full host clone.
Codex already documents skill discovery and selective external-agent migration interfaces, which are useful precedent for the interaction. They are not a general host-to-VM export API; its app-server plugin APIs are currently marked under development and should not be assumed production-ready.
References: Claude skills-directory plugins, Codex skills, Codex app-server.
This issue does not replace or block #457 or the focused Codex companion #461.