Security and Limits

Local model

AIM Loadout runs locally. It does not require a cloud account and does not send your inventory to external servers.

The transport between machines is your Git repository. AIM reads and writes inventory files and performs Git operations for publishing and syncing.

What goes into Git

Git stores:

• skills/*.md;
• mcp/*.yaml;
• loadouts/*.yaml;
• aim.yaml;
• .gitignore;
• any future public inventory files, if they are added to the format.

What must not go into Git

Local data is stored in aim.local.yaml and must be excluded via .gitignore.

This may include:

• paths to AI environments on the specific machine;
• published_hash;
• synced_hash;
• MCP server environment variable values.

In the current MVP, MCP env values are stored in aim.local.yaml as plain text. This is safe only under one condition: the file must not be committed to Git.

What AIM writes to AI environments

AIM may:

• create or update skill files in AI environment directories;
• add or update an MCP server entry in an AI environment's configuration file;
• create required directories if they do not exist;
• with apply --loadout, remove skills and MCP entries that exist in the inventory but are not part of the applied loadout. Files that do not exist in the inventory are never removed.

Before a bulk apply, use dry-run first:

aiman apply --dry-run
aiman sync --dry-run
aiman apply --loadout <name> --dry-run

Current MVP limitations

• Supported environments: Claude Code, Cursor, and Codex CLI.
• MCP supports the stdio launch model: a server with an HTTP/SSE transport ("type": "http", "type": "sse", or a bare "url") is neither imported from an environment nor installed into one.
• File permissions are not preserved: skills and their resource files are written as 0644 both when added to the inventory and when installed into an environment — the executable bit on scripts is lost.
• MCP secrets are not stored in a system keychain.
• The primary remote/branch is origin/main.
• AIM does not perform automatic Git conflict resolution.
• aiman list is not considered a full public command until a complete inventory view is implemented.

Limitations of declarative loadout apply

aiman apply --loadout removes inventory items outside the applied loadout from your environments. Two limitations of this model are deliberate; the mitigation for both is aiman apply --loadout <name> --dry-run, which shows the D lines before anything is removed.

Name collision. A skill you created in an environment by hand, but whose name matches an inventory item outside the loadout, will be removed by apply --loadout: AIM decides what is "its own" by the name in the inventory and cannot tell its own materialized file from a manually created one with the same name. Check the plan with --dry-run if you keep manual skills in environments under the same names as inventory items.

Orphans. A skill deleted from the inventory entirely stays in your environments: AIM no longer considers it its own and does not remove it during apply --loadout. This is not a regression — earlier versions removed nothing from environments at all. Delete such a file manually; automatic cleanup will arrive together with a manifest of the applied state (project scope).

What exactly gets removed. A skill is removed together with its entire directory in the AI environment (skills/<name>/, including reference files). From an MCP configuration, only the entry for that server is removed — other entries and the config file itself are preserved.

If something goes wrong

Start with:

aiman status
aiman doctor

For issues on first run, see Troubleshooting.