# axsmak/aim architecture

> Architecture diagram of the GitHub repository axsmak/aim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/axsmak/aim
- Repository: https://github.com/axsmak/aim

## Overview

#### 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`.

Main entry points: [`internal/cli/apply.go`](https://github.com/axsmak/aim/blob/main/internal/cli/apply.go) (Apply, push, sync), [`internal/adder/adder.go`](https://github.com/axsmak/aim/blob/main/internal/adder/adder.go) (Apply operations), [`internal/cli/root.go`](https://github.com/axsmak/aim/blob/main/internal/cli/root.go) (Command wiring), [`.goreleaser.yaml`](https://github.com/axsmak/aim/blob/main/.goreleaser.yaml) (Release automation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main{{"aiman binary<br/>Go entry point<br/>[main.go]"}}
  node_root["Command wiring<br/>CLI root<br/>[root.go]"]
  node_commands["Apply, push, sync<br/>CLI workflows<br/>[apply.go]"]
  node_repo_selection["Repository selection<br/>CLI setup<br/>[init.go]"]
end

subgraph group_domain["Inventory domain"]
  node_inventory["Filesystem inventory<br/>domain model"]
  node_skills["Skills parser<br/>domain parser<br/>[parse.go]"]
  node_mcp["MCP validation<br/>domain validator<br/>[validate.go]"]
  node_loadouts["Loadout resolution<br/>domain resolver<br/>[resolve.go]"]
end

subgraph group_reconcile["Reconciliation"]
  node_application["Apply operations<br/>application layer<br/>[adder.go]"]
  node_adapters["Adapter boundary<br/>target abstraction<br/>[adapter.go]"]
  node_scanner["Installed-state scanner<br/>adapter service<br/>[scanner.go]"]
  node_importer["Environment importer<br/>application service<br/>[skill.go]"]
end

subgraph group_state["State and transport"]
  node_configs["Configuration layers<br/>local and shared state<br/>[repoconfig.go]"]
  node_envresolver["MCP env resolver<br/>secret resolver<br/>[envresolver.go]"]
  node_gitops["Git transport<br/>Git integration<br/>[gitops.go]"]
end

subgraph group_targets["AI tool targets"]
  node_tool_envs["Claude, Cursor, Codex<br/>local tool environments<br/>[claude_code.go]"]
end

subgraph group_release["Distribution"]
  node_release["Release automation<br/>GoReleaser and Actions<br/>[.goreleaser.yaml]"]
  node_arch["Arch package<br/>package metadata"]
end

node_main -->|"starts"| node_root
node_root -->|"registers"| node_commands
node_root -->|"registers"| node_repo_selection
node_repo_selection -->|"stores selection"| node_configs
node_commands -->|"reads and validates"| node_inventory
node_inventory -->|"skill files"| node_skills
node_inventory -->|"MCP definitions"| node_mcp
node_inventory -->|"optional subset"| node_loadouts
node_commands -->|"apply or sync"| node_application
node_loadouts -->|"managed selection"| node_application
node_application -->|"reconciles through"| node_adapters
node_scanner -->|"installed state"| node_application
node_adapters -->|"writes target formats"| node_tool_envs
node_tool_envs -.->|"existing configuration"| node_importer
node_importer -->|"inventory-oriented forms"| node_inventory
node_mcp -->|"required values"| node_envresolver
node_envresolver -->|"local secrets"| node_configs
node_commands -->|"push and sync"| node_gitops
node_gitops -->|"clone, fetch, commit"| node_inventory
node_release -->|"builds binary"| node_main
node_release -->|"packages"| node_arch

click node_main "https://github.com/axsmak/aim/blob/main/cmd/aim/main.go"
click node_root "https://github.com/axsmak/aim/blob/main/internal/cli/root.go"
click node_commands "https://github.com/axsmak/aim/blob/main/internal/cli/apply.go"
click node_repo_selection "https://github.com/axsmak/aim/blob/main/internal/cli/init.go"
click node_skills "https://github.com/axsmak/aim/blob/main/internal/skill/parse.go"
click node_mcp "https://github.com/axsmak/aim/blob/main/internal/mcp/validate.go"
click node_loadouts "https://github.com/axsmak/aim/blob/main/internal/loadout/resolve.go"
click node_application "https://github.com/axsmak/aim/blob/main/internal/adder/adder.go"
click node_adapters "https://github.com/axsmak/aim/blob/main/internal/adapter/adapter.go"
click node_scanner "https://github.com/axsmak/aim/blob/main/internal/adapter/scanner.go"
click node_importer "https://github.com/axsmak/aim/blob/main/internal/importer/skill.go"
click node_configs "https://github.com/axsmak/aim/blob/main/internal/repoconfig/repoconfig.go"
click node_envresolver "https://github.com/axsmak/aim/blob/main/internal/mcp/envresolver.go"
click node_gitops "https://github.com/axsmak/aim/blob/main/internal/gitops/gitops.go"
click node_tool_envs "https://github.com/axsmak/aim/blob/main/internal/adapter/claude_code.go"
click node_release "https://github.com/axsmak/aim/blob/main/.goreleaser.yaml"
click node_arch "https://github.com/axsmak/aim/blob/main/packaging/arch/PKGBUILD"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_root,node_commands,node_repo_selection toneBlue
class node_inventory,node_skills,node_mcp,node_loadouts toneAmber
class node_application,node_adapters,node_scanner,node_importer toneMint
class node_configs,node_envresolver,node_gitops toneRose
class node_tool_envs toneIndigo
class node_release,node_arch toneTeal
```

## Components

### CLI

- [aiman binary](https://github.com/axsmak/aim/blob/main/cmd/aim/main.go): Go entry point · `cmd/aim/main.go`
- [Command wiring](https://github.com/axsmak/aim/blob/main/internal/cli/root.go): CLI root · `internal/cli/root.go`
- [Apply, push, sync](https://github.com/axsmak/aim/blob/main/internal/cli/apply.go): CLI workflows · Apply is local; push and sync use Git. · `internal/cli/apply.go`
- [Repository selection](https://github.com/axsmak/aim/blob/main/internal/cli/init.go): CLI setup · `internal/cli/init.go`

### Inventory domain

- **Filesystem inventory**: domain model · Markdown skills, YAML MCP definitions, loadouts, and metadata.
- [Skills parser](https://github.com/axsmak/aim/blob/main/internal/skill/parse.go): domain parser · `internal/skill/parse.go`
- [MCP validation](https://github.com/axsmak/aim/blob/main/internal/mcp/validate.go): domain validator · Validates definitions and required environment values. · `internal/mcp/validate.go`
- [Loadout resolution](https://github.com/axsmak/aim/blob/main/internal/loadout/resolve.go): domain resolver · Resolves selected items and checks references. · `internal/loadout/resolve.go`

### Reconciliation

- [Apply operations](https://github.com/axsmak/aim/blob/main/internal/adder/adder.go): application layer · Installs known items and removes managed items outside a loadout. · `internal/adder/adder.go`
- [Adapter boundary](https://github.com/axsmak/aim/blob/main/internal/adapter/adapter.go): target abstraction · Converts inventory into target-specific files and configuration. · `internal/adapter/adapter.go`
- [Installed-state scanner](https://github.com/axsmak/aim/blob/main/internal/adapter/scanner.go): adapter service · `internal/adapter/scanner.go`
- [Environment importer](https://github.com/axsmak/aim/blob/main/internal/importer/skill.go): application service · Ingests existing skills and MCP configuration into inventory forms. · `internal/importer/skill.go`

### State and transport

- [Configuration layers](https://github.com/axsmak/aim/blob/main/internal/repoconfig/repoconfig.go): local and shared state · Shared repo config; local paths, sync markers, secrets, and active selection. · `internal/repoconfig/repoconfig.go`
- [MCP env resolver](https://github.com/axsmak/aim/blob/main/internal/mcp/envresolver.go): secret resolver · Resolves required MCP values from local configuration. · `internal/mcp/envresolver.go`
- [Git transport](https://github.com/axsmak/aim/blob/main/internal/gitops/gitops.go): Git integration · Clone, fetch, status, commit, and push are the only network dependency. · `internal/gitops/gitops.go`

### AI tool targets

- [Claude, Cursor, Codex](https://github.com/axsmak/aim/blob/main/internal/adapter/claude_code.go): local tool environments · Skills plus JSON/TOML MCP configuration surfaces. · `internal/adapter/claude_code.go`

### Distribution

- [Release automation](https://github.com/axsmak/aim/blob/main/.goreleaser.yaml): GoReleaser and Actions · `.goreleaser.yaml`
- [Arch package](https://github.com/axsmak/aim/blob/main/packaging/arch/PKGBUILD): package metadata · `packaging/arch/PKGBUILD`

## Connections

- aiman binary → Command wiring: starts
- Command wiring → Apply, push, sync: registers
- Command wiring → Repository selection: registers
- Repository selection → Configuration layers: stores selection
- Apply, push, sync → Filesystem inventory: reads and validates
- Filesystem inventory → Skills parser: skill files
- Filesystem inventory → MCP validation: MCP definitions
- Filesystem inventory → Loadout resolution: optional subset
- Apply, push, sync → Apply operations: apply or sync
- Loadout resolution → Apply operations: managed selection
- Apply operations → Adapter boundary: reconciles through
- Installed-state scanner → Apply operations: installed state
- Adapter boundary → Claude, Cursor, Codex: writes target formats
- Claude, Cursor, Codex → Environment importer: existing configuration
- Environment importer → Filesystem inventory: inventory-oriented forms
- MCP validation → MCP env resolver: required values
- MCP env resolver → Configuration layers: local secrets
- Apply, push, sync → Git transport: push and sync
- Git transport → Filesystem inventory: clone, fetch, commit
- Release automation → aiman binary: builds binary
- Release automation → Arch package: packages