# jdx/mise architecture

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

- Interactive diagram: https://gitdiagram.com/jdx/mise
- Repository: https://github.com/jdx/mise

## Overview

#### Overview

mise is a Rust CLI for managing development tools, environment variables, project tasks, and machine bootstrap configuration. A project declares these in `mise.toml`; mise can install or select tools, expose environment variables, and run tasks in the configured environment.

#### Public entry points

- `src/main.rs` is the primary CLI binary entry point.

- `src/cli` contains the public command surface, including `exec`, `run`, `install`, `use`, `activate`, task commands, configuration commands, and bootstrap commands.

- `crates/mise-shim/src/main.rs` provides a separate shim executable for tool command dispatch.

- Shell integration is exposed through commands such as `mise activate bash`, `zsh`, or `fish`. Editors and CI can instead invoke the CLI directly.

#### Core components

- **Command orchestration — `src/cli`:** Maps user-facing commands to tool, environment, task, shell, bootstrap, plugin, and system-management capabilities.

- **Configuration and environment — `src/config`:** Implements project/global configuration, settings, TOML files, version-file discovery, environment directives, trust, and provenance areas.

- **Tool selection and installation state — `src/toolset`:** Represents tool requests, versions, installation options, tool environments, paths, dependencies, and install state.

- **Backend integrations — `src/backend`:** Organizes alternative acquisition and version-resolution backends such as GitHub, HTTP, npm, Cargo, Go, Python, Aqua, UBI, S3, and vfox. The `registry` directory supplies declarative tool definitions.

- **Task execution — `src/task`:** Loads task files, templates, dependencies, workspace relationships, source freshness, scheduling, output handling, and task caching before running external commands.

- **Shell environment and command dispatch — `src/shell`:** Produces shell-specific activation/deactivation behavior and environment updates. `src/shims.rs` and the shim crate support command lookup through managed tool installations.

- **Plugin boundary — `src/plugins`:** Hosts core, asdf-style, mise, PackSlip, and vfox plugin integrations. The optional vfox runtime and Lua plugin ecosystem are separately organized under `crates/vfox/src` and `crates/vfox/embedded-plugins`.

- **Bootstrap and system management — `src/system`:** Covers machine packages, services, files, repositories, accounts, shell setup, secrets, and system-history operations exposed by bootstrap commands.

- **Reproducibility and persistence — `src/lockfile`:** Handles lockfile generation and graph data; related runtime caching is organized in `src/cache.rs`.

#### Relationships

Project or global configuration is interpreted by `src/config` and supplies tool, environment, and task inputs to the CLI. Tool requests are represented by `src/toolset`, resolved through a selected `src/backend` or plugin, and persisted through lockfile/cache facilities. Tasks consume the resulting tools and environment, then execute application-supplied commands. Shell activation and shims expose those resolved tools to interactive shells.

The main path is repository code; task scripts, external tools, remote registries, package hosts, shells, editors, and CI are external actors. Plugin implementations may be repository-embedded, installed separately, or supplied by users; the plugin directories define the extension boundary rather than making those implementations part of the CLI core.

Main entry points: [`src/toolset`](https://github.com/jdx/mise/tree/main/src/toolset) (Toolset), [`src/cli`](https://github.com/jdx/mise/tree/main/src/cli) (Command surface), [`src/task`](https://github.com/jdx/mise/tree/main/src/task) (Task execution), [`src/shell`](https://github.com/jdx/mise/tree/main/src/shell) (Shell integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["mise core"]
  node_main(("CLI binary<br/>entry point<br/>[main.rs]"))
  node_cli{{"Command surface<br/>orchestrator"}}
  node_config["Configuration"]
  node_toolset["Toolset<br/>tool state"]
  node_backend["Backends<br/>integration layer"]
  node_plugins["Plugin boundary<br/>extension point"]
  node_task["Task execution<br/>scheduler"]
  node_shell["Shell integration<br/>environment adapter"]
  node_shims["Command shims<br/>command dispatch<br/>[shims.rs]"]
  node_shim_bin(("Shim executable<br/>entry point<br/>[main.rs]"))
  node_system["System management<br/>bootstrap subsystem"]
  node_lockfile[("Lockfile<br/>persistence")]
  node_cache[("Runtime cache<br/>persistence<br/>[cache.rs]")]
end

subgraph group_external["External actors"]
  node_shells(("Interactive shells<br/>external consumer"))
  node_task_commands(("Application commands<br/>external process"))
  node_tool_sources[("Tool sources<br/>external system")]
  node_consumers(("Editors and CI<br/>external consumer"))
end

node_main -->|"starts"| node_cli
node_config -->|"supplies inputs"| node_cli
node_cli -->|"orchestrates"| node_toolset
node_cli -->|"orchestrates"| node_task
node_cli -->|"manages"| node_system
node_config -->|"supplies task inputs"| node_task
node_toolset -->|"resolves through"| node_backend
node_toolset -.->|"resolves through"| node_plugins
node_backend -->|"acquires from"| node_tool_sources
node_toolset -->|"persists state"| node_lockfile
node_toolset -->|"uses cache"| node_cache
node_task -->|"consumes tools"| node_toolset
node_task -->|"uses environment"| node_shell
node_task -->|"executes"| node_task_commands
node_toolset -->|"exposes resolved tools"| node_shell
node_shims -->|"looks up installations"| node_toolset
node_shim_bin -->|"dispatches through"| node_shims
node_shell -->|"generates activation for"| node_shells
node_consumers -->|"invokes"| node_cli

click node_main "https://github.com/jdx/mise/blob/main/src/main.rs"
click node_cli "https://github.com/jdx/mise/tree/main/src/cli"
click node_config "https://github.com/jdx/mise/tree/main/src/config"
click node_toolset "https://github.com/jdx/mise/tree/main/src/toolset"
click node_backend "https://github.com/jdx/mise/tree/main/src/backend"
click node_plugins "https://github.com/jdx/mise/tree/main/src/plugins"
click node_task "https://github.com/jdx/mise/tree/main/src/task"
click node_shell "https://github.com/jdx/mise/tree/main/src/shell"
click node_shims "https://github.com/jdx/mise/blob/main/src/shims.rs"
click node_shim_bin "https://github.com/jdx/mise/blob/main/crates/mise-shim/src/main.rs"
click node_system "https://github.com/jdx/mise/tree/main/src/system"
click node_lockfile "https://github.com/jdx/mise/tree/main/src/lockfile"
click node_cache "https://github.com/jdx/mise/blob/main/src/cache.rs"

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_cli,node_config,node_toolset,node_backend,node_plugins,node_task,node_shell,node_shims,node_shim_bin,node_system,node_lockfile,node_cache toneBlue
class node_shells,node_task_commands,node_tool_sources,node_consumers toneAmber
```

## Components

### mise core

Repository runtime components

- [CLI binary](https://github.com/jdx/mise/blob/main/src/main.rs): entry point · `src/main.rs`
- [Command surface](https://github.com/jdx/mise/tree/main/src/cli): orchestrator · Maps user commands to mise capabilities. · `src/cli`
- [Configuration](https://github.com/jdx/mise/tree/main/src/config): configuration · Interprets project and global configuration and environment directives. · `src/config`
- [Toolset](https://github.com/jdx/mise/tree/main/src/toolset): tool state · Represents tool requests, environments, paths, dependencies, and installation state. · `src/toolset`
- [Backends](https://github.com/jdx/mise/tree/main/src/backend): integration layer · Provides alternative acquisition and version-resolution backends. · `src/backend`
- [Plugin boundary](https://github.com/jdx/mise/tree/main/src/plugins): extension point · Hosts core, asdf-style, mise, PackSlip, and vfox integrations. · `src/plugins`
- [Task execution](https://github.com/jdx/mise/tree/main/src/task): scheduler · Loads, schedules, caches, and runs configured tasks. · `src/task`
- [Shell integration](https://github.com/jdx/mise/tree/main/src/shell): environment adapter · Produces shell-specific activation and environment updates. · `src/shell`
- [Command shims](https://github.com/jdx/mise/blob/main/src/shims.rs): command dispatch · Looks up commands through managed tool installations. · `src/shims.rs`
- [Shim executable](https://github.com/jdx/mise/blob/main/crates/mise-shim/src/main.rs): entry point · Separate executable for tool command dispatch. · `crates/mise-shim/src/main.rs`
- [System management](https://github.com/jdx/mise/tree/main/src/system): bootstrap subsystem · Manages machine packages, services, files, repositories, accounts, and shell setup. · `src/system`
- [Lockfile](https://github.com/jdx/mise/tree/main/src/lockfile): persistence · Generates lockfiles and stores dependency graph data. · `src/lockfile`
- [Runtime cache](https://github.com/jdx/mise/blob/main/src/cache.rs): persistence · `src/cache.rs`

### External actors

Consumer-supplied code and external systems

- **Interactive shells**: external consumer
- **Application commands**: external process · Commands supplied by projects and run by tasks.
- **Tool sources**: external system · Remote registries, package hosts, and tool providers.
- **Editors and CI**: external consumer

## Connections

- CLI binary → Command surface: starts
- Configuration → Command surface: supplies inputs
- Command surface → Toolset: orchestrates
- Command surface → Task execution: orchestrates
- Command surface → System management: manages
- Configuration → Task execution: supplies task inputs
- Toolset → Backends: resolves through
- Toolset → Plugin boundary: resolves through
- Backends → Tool sources: acquires from
- Toolset → Lockfile: persists state
- Toolset → Runtime cache: uses cache
- Task execution → Toolset: consumes tools
- Task execution → Shell integration: uses environment
- Task execution → Application commands: executes
- Toolset → Shell integration: exposes resolved tools
- Command shims → Toolset: looks up installations
- Shim executable → Command shims: dispatches through
- Shell integration → Interactive shells: generates activation for
- Editors and CI → Command surface: invokes
