axsmak/aim

Purpose and Entry Point

AIM Loadout is a local-first, Git-backed Go CLI (aiman) that manages reusable AI-agent skills and MCP server definitions, then installs them into Claude Code, Cursor, and Codex CLI. Process startup is cmd/aim/main.go; command registration and shared CLI wiring are in internal/cli/root.go.

CLI Workflow Orchestration

The CLI separates offline local application from Git-backed distribution:

• apply reads the active inventory and updates AI-tool environments without Git mutation: internal/cli/apply.go.

• push validates inventory/loadouts, protects local secrets, commits, and pushes: internal/cli/push.go.

• sync fetches the configured repository, applies it, then updates local sync state: internal/cli/sync.go.

• Repository connection and selection are handled by internal/cli/init.go and internal/cli/switch.go.

Inventory Domain Model

Inventory is filesystem-based: Markdown skills, YAML MCP definitions, optional YAML loadouts, and repository metadata. Domain parsing and validation are split by type:

• Skills: internal/skill/skill.go, internal/skill/parse.go

• MCP definitions and environment requirements: internal/mcp/mcp.go, internal/mcp/validate.go

• Loadout parsing, resolution, and reference integrity: internal/loadout/parse.go, internal/loadout/resolve.go, internal/loadout/refcheck.go

Loadouts select an exact managed subset for reconciliation; normal apply/sync remain additive.

Adapter Boundary and Environment Reconciliation

internal/adapter/adapter.go defines the abstraction translating one inventory model into tool-specific filesystem/configuration surfaces. internal/adapter/registry.go discovers supported targets, while internal/adapter/scanner.go inspects installed state. Concrete adapters are internal/adapter/claude_code.go, internal/adapter/cursor.go, and internal/adapter/codex.go.

Adapters own external-format details: skill installation paths plus JSON/TOML MCP config changes. Core inventory logic should not depend on any individual AI tool format.

Apply, Add, and Import Operations

The application layer coordinates parsed inventory and adapters, including managed-item removals during loadout reconciliation:

• internal/adder/adder.go and internal/adder/skill.go install skills.

• internal/adder/mcp.go applies MCP definitions.

• internal/importer/skill.go and internal/importer/mcp.go ingest existing tool configuration into inventory-oriented forms.

This boundary preserves unmanaged environment content where adapters support it, while AIM controls inventory-known names.

Configuration, Secrets, and Git Transport

Repository-shared configuration is represented in internal/repoconfig/repoconfig.go; machine-local repository path, sync markers, and MCP environment values reside in internal/localconfig/localconfig.go. Global active-inventory selection is handled by internal/globalconfig/globalconfig.go.

Required MCP values are resolved locally through internal/mcp/envresolver.go; secrets stay in aim.local.yaml rather than the Git inventory. Git clone/fetch/status/commit/push behavior is isolated in internal/gitops/gitops.go, making Git the only inventory transport and external network dependency.

Runtime and Distribution

The runtime is a Go command-line binary with local filesystem and Git executable integration; it has no hosted service or web runtime. Release automation uses GoReleaser and GitHub Actions: .goreleaser.yaml, .github/workflows/release.yaml. Current packaging also includes Arch Linux metadata at packaging/arch/PKGBUILD.