Claude Code for Mise — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Mise (formerly rtx) to manage development tool versions — Node.js, Python, Ruby, Go, and hundreds of other tools — with a single config file. Mise replaces nvm, pyenv, rbenv, and asdf with one tool that is faster and supports environment variables and task running. Claude Code can configure Mise, but it defaults to individual version managers or Docker for tool isolation.

What Claude Code Gets Wrong By Default

  1. Installs nvm, pyenv, and rbenv separately. Claude sets up individual version managers for each language. Mise manages all of them with mise install node@20, mise install [email protected] — one tool for everything.

  2. Creates .nvmrc and .python-version files. Claude generates tool-specific version files. Mise uses .mise.toml (or mise.toml) as a single source of truth for all tool versions. It can read legacy files but prefers its own format.

  3. Uses Docker for tool version isolation. Claude writes Dockerfiles to pin tool versions. Mise provides the same version pinning without containerization overhead — mise install downloads the exact binary version.

  4. Ignores Mise’s task runner and env features. Claude treats Mise as only a version manager. Mise also runs tasks (like Just or Make) and manages environment variables (like direnv), all from the same config file.

The CLAUDE.md Configuration

# Mise Dev Tool Manager

## Tooling
- Tool manager: Mise (replaces nvm, pyenv, rbenv, asdf)
- Config: .mise.toml at project root (committed to git)
- Tasks: defined in .mise.toml [tasks] section
- Env vars: defined in .mise.toml [env] section

## Mise Rules
- Install tools: mise install (reads .mise.toml)
- Pin versions: mise use [email protected] (updates .mise.toml)
- All tool versions in .mise.toml, not .nvmrc/.python-version
- Tasks: mise run <task-name>
- Env vars: [env] section auto-loads when entering directory
- Plugins: mise plugins install <name> for non-core tools
- Activate: eval "$(mise activate zsh)" in .zshrc

## Conventions
- .mise.toml committed to version control
- Node.js, Python versions pinned to minor version
- Tasks for common operations: dev, test, build, lint
- Environment variables for dev in [env] section
- Secrets in .mise.local.toml (gitignored)
- Use mise trust to approve new .mise.toml files

Workflow Example

You want to set up a project with pinned Node.js and Python versions plus dev tasks. Prompt Claude Code:

“Create a .mise.toml that pins Node.js 20 and Python 3.12, sets DATABASE_URL and API_KEY environment variables for development, and defines tasks for dev server startup, testing, and linting.”

Claude Code should create .mise.toml with [tools] section listing node = "20" and python = "3.12", an [env] section with dev variables, and a [tasks] section with named tasks including their commands, descriptions, and dependencies.

Common Pitfalls

  1. Forgetting mise trust on new projects. Claude checks out a project with .mise.toml but tools are not activated. Mise requires explicit trust for new config files as a security measure. Run mise trust in the project directory after reviewing the file.

  2. Mise activation order in shell config. Claude adds eval "$(mise activate zsh)" before other shell initializations. Mise activation should be near the end of .zshrc after PATH modifications, or it may not intercept the correct tool binaries.

  3. Local overrides leaking to git. Claude puts secrets in .mise.toml which gets committed. Sensitive env vars should go in .mise.local.toml which is gitignored by default. The project .mise.toml should only contain non-sensitive defaults.