# asdf-vm/asdf architecture

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

- Interactive diagram: https://gitdiagram.com/asdf-vm/asdf
- Repository: https://github.com/asdf-vm/asdf

## Overview

asdf is a per-project runtime-version manager exposed through one CLI and extended by language plugins. The main flow is command invocation, configuration and version selection, then plugin-driven install or executable dispatch through generated shims. The graph also preserves plugin discovery, shell completion, legacy-version support, and execution helpers documented or referenced by the source index. Edges reflect visible imports/calls or README capabilities; unsampled implementation details are omitted rather than inferred.

Main entry points: [`internal/cli/cli.go`](https://github.com/asdf-vm/asdf/blob/master/internal/cli/cli.go) (Command router), [`internal/plugins/plugins.go`](https://github.com/asdf-vm/asdf/blob/master/internal/plugins/plugins.go) (Plugin manager), [`internal/versions/versions.go`](https://github.com/asdf-vm/asdf/blob/master/internal/versions/versions.go) (Version lifecycle), [`internal/shims/shims.go`](https://github.com/asdf-vm/asdf/blob/master/internal/shims/shims.go) (Executable shims)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI experience"]
  node_cli["Command router<br/>[cli.go]"]
  node_completions["Shell completion<br/>[completions.go]"]
end

subgraph group_selection["Version selection"]
  node_config["Configuration<br/>[config.go]"]
  node_toolversions["Version files<br/>[toolversions.go]"]
  node_resolve["Version resolver<br/>[resolve.go]"]
  node_legacy["Legacy version files<br/>[plugins.go]"]
end

subgraph group_plugin["Plugin management"]
  node_plugins["Plugin manager<br/>[plugins.go]"]
  node_pluginindex[("Plugin index<br/>[pluginindex.go]")]
  node_git["Git operations<br/>[git.go]"]
end

subgraph group_runtime["Runtime operations"]
  node_versions["Version lifecycle<br/>[versions.go]"]
  node_installs[("Install registry<br/>[installs.go]")]
  node_shims["Executable shims<br/>[shims.go]"]
end

subgraph group_support["Execution support"]
  node_execenv["Runtime environment<br/>[execenv.go]"]
  node_execute["Process execution<br/>[execute.go]"]
  node_hook["Lifecycle hooks<br/>[hook.go]"]
  node_data["Data paths<br/>[data.go]"]
end

node_user(("Shell user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"offers completion"| node_completions
node_cli -->|"manages plugins"| node_plugins
node_cli -->|"lists plugins"| node_pluginindex
node_cli -->|"resolves versions"| node_resolve
node_cli -->|"runs lifecycle"| node_versions
node_cli -->|"dispatches tools"| node_shims
node_cli -->|"runs hooks"| node_hook
node_cli -->|"prepares environment"| node_execenv
node_resolve -->|"reads version files"| node_toolversions
node_resolve -->|"parses legacy files"| node_plugins
node_cli -.->|"supports migration"| node_legacy
node_plugins -->|"clones and updates"| node_git
node_pluginindex -->|"refreshes index"| node_git
node_versions -->|"runs callbacks"| node_plugins
node_versions -->|"checks installations"| node_installs
node_versions -->|"runs lifecycle hooks"| node_hook
node_shims -->|"selects versions"| node_resolve
node_shims -->|"finds executables"| node_installs
node_shims -->|"runs shim callbacks"| node_plugins
node_shims -->|"runs reshim hooks"| node_hook
node_execenv -->|"queries plugin"| node_plugins
node_execenv -->|"executes command"| node_execute
node_git -->|"runs Git commands"| node_execute
node_plugins -->|"locates plugin data"| node_data
node_installs -->|"maps install paths"| node_data
node_versions -->|"parses version values"| node_toolversions

click node_cli "https://github.com/asdf-vm/asdf/blob/master/internal/cli/cli.go"
click node_completions "https://github.com/asdf-vm/asdf/blob/master/internal/completions/completions.go"
click node_config "https://github.com/asdf-vm/asdf/blob/master/internal/config/config.go"
click node_toolversions "https://github.com/asdf-vm/asdf/blob/master/internal/toolversions/toolversions.go"
click node_resolve "https://github.com/asdf-vm/asdf/blob/master/internal/resolve/resolve.go"
click node_plugins "https://github.com/asdf-vm/asdf/blob/master/internal/plugins/plugins.go"
click node_pluginindex "https://github.com/asdf-vm/asdf/blob/master/internal/pluginindex/pluginindex.go"
click node_git "https://github.com/asdf-vm/asdf/blob/master/internal/git/git.go"
click node_versions "https://github.com/asdf-vm/asdf/blob/master/internal/versions/versions.go"
click node_installs "https://github.com/asdf-vm/asdf/blob/master/internal/installs/installs.go"
click node_shims "https://github.com/asdf-vm/asdf/blob/master/internal/shims/shims.go"
click node_execenv "https://github.com/asdf-vm/asdf/blob/master/internal/execenv/execenv.go"
click node_execute "https://github.com/asdf-vm/asdf/blob/master/internal/execute/execute.go"
click node_hook "https://github.com/asdf-vm/asdf/blob/master/internal/hook/hook.go"
click node_data "https://github.com/asdf-vm/asdf/blob/master/internal/data/data.go"
click node_legacy "https://github.com/asdf-vm/asdf/blob/master/internal/plugins/plugins.go"

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_cli,node_completions,node_user toneBlue
class node_config,node_toolversions,node_resolve,node_legacy toneAmber
class node_plugins,node_pluginindex,node_git toneMint
class node_versions,node_installs,node_shims toneRose
class node_execenv,node_execute,node_hook,node_data toneIndigo
```

## Components

### CLI experience

- [Command router](https://github.com/asdf-vm/asdf/blob/master/internal/cli/cli.go): `internal/cli/cli.go`
- [Shell completion](https://github.com/asdf-vm/asdf/blob/master/internal/completions/completions.go): `internal/completions/completions.go`

### Version selection

- [Configuration](https://github.com/asdf-vm/asdf/blob/master/internal/config/config.go): `internal/config/config.go`
- [Version files](https://github.com/asdf-vm/asdf/blob/master/internal/toolversions/toolversions.go): `internal/toolversions/toolversions.go`
- [Version resolver](https://github.com/asdf-vm/asdf/blob/master/internal/resolve/resolve.go): `internal/resolve/resolve.go`
- [Legacy version files](https://github.com/asdf-vm/asdf/blob/master/internal/plugins/plugins.go): `internal/plugins/plugins.go`

### Plugin management

- [Plugin manager](https://github.com/asdf-vm/asdf/blob/master/internal/plugins/plugins.go): `internal/plugins/plugins.go`
- [Plugin index](https://github.com/asdf-vm/asdf/blob/master/internal/pluginindex/pluginindex.go): `internal/pluginindex/pluginindex.go`
- [Git operations](https://github.com/asdf-vm/asdf/blob/master/internal/git/git.go): `internal/git/git.go`

### Runtime operations

- [Version lifecycle](https://github.com/asdf-vm/asdf/blob/master/internal/versions/versions.go): `internal/versions/versions.go`
- [Install registry](https://github.com/asdf-vm/asdf/blob/master/internal/installs/installs.go): `internal/installs/installs.go`
- [Executable shims](https://github.com/asdf-vm/asdf/blob/master/internal/shims/shims.go): `internal/shims/shims.go`

### Execution support

- [Runtime environment](https://github.com/asdf-vm/asdf/blob/master/internal/execenv/execenv.go): `internal/execenv/execenv.go`
- [Process execution](https://github.com/asdf-vm/asdf/blob/master/internal/execute/execute.go): `internal/execute/execute.go`
- [Lifecycle hooks](https://github.com/asdf-vm/asdf/blob/master/internal/hook/hook.go): `internal/hook/hook.go`
- [Data paths](https://github.com/asdf-vm/asdf/blob/master/internal/data/data.go): `internal/data/data.go`

### Other components

- **Shell user**

## Connections

- Shell user → Command router: runs commands (evidence: `README.md`)
- Command router → Configuration: loads settings (evidence: `internal/cli/cli.go`)
- Command router → Shell completion: offers completion (evidence: `internal/cli/cli.go`)
- Command router → Plugin manager: manages plugins (evidence: `internal/cli/cli.go`)
- Command router → Plugin index: lists plugins (evidence: `internal/cli/cli.go`)
- Command router → Version resolver: resolves versions (evidence: `internal/cli/cli.go`)
- Command router → Version lifecycle: runs lifecycle (evidence: `internal/cli/cli.go`)
- Command router → Executable shims: dispatches tools (evidence: `internal/cli/cli.go`)
- Command router → Lifecycle hooks: runs hooks (evidence: `internal/cli/cli.go`)
- Command router → Runtime environment: prepares environment (evidence: `internal/cli/cli.go`)
- Version resolver → Version files: reads version files (evidence: `internal/resolve/resolve.go`)
- Version resolver → Plugin manager: parses legacy files (evidence: `internal/resolve/resolve.go`)
- Command router → Legacy version files: supports migration (evidence: `README.md`)
- Plugin manager → Git operations: clones and updates (evidence: `internal/plugins/plugins.go`)
- Plugin index → Git operations: refreshes index (evidence: `internal/pluginindex/pluginindex.go`)
- Version lifecycle → Plugin manager: runs callbacks (evidence: `internal/versions/versions.go`)
- Version lifecycle → Install registry: checks installations (evidence: `internal/versions/versions.go`)
- Version lifecycle → Lifecycle hooks: runs lifecycle hooks (evidence: `internal/versions/versions.go`)
- Executable shims → Version resolver: selects versions (evidence: `internal/shims/shims.go`)
- Executable shims → Install registry: finds executables (evidence: `internal/shims/shims.go`)
- Executable shims → Plugin manager: runs shim callbacks (evidence: `internal/shims/shims.go`)
- Executable shims → Lifecycle hooks: runs reshim hooks (evidence: `internal/shims/shims.go`)
- Runtime environment → Plugin manager: queries plugin (evidence: `internal/execenv/execenv.go`)
- Runtime environment → Process execution: executes command (evidence: `internal/execenv/execenv.go`)
- Git operations → Process execution: runs Git commands (evidence: `internal/git/git.go`)
- Plugin manager → Data paths: locates plugin data (evidence: `internal/plugins/plugins.go`)
- Install registry → Data paths: maps install paths (evidence: `internal/installs/installs.go`)
- Version lifecycle → Version files: parses version values (evidence: `internal/versions/versions.go`)
