devenv

Devenv Command

Initialize and manage Nix flake development environments. Provides a devbox-like experience with auto-detection of project dependencies and security tooling using native Nix solutions.

Execution Flow

Step 1: Check Current State

First, determine if this is a new setup or managing an existing environment:

1. Check if flake.nix exists in the current directory
2. If flake.nix exists, check if git-hooks input is present (indicates pre-commit is configured)
3. Read .claude/devenv.local.md if it exists for:
   • channel preference (default: nixos-unstable)
   • shell welcome style (default: box)
   • custom welcome text (if shell_welcome: custom)

Step 2: Branch Based on State

If flake.nix does NOT exist (Initialize Flow)

2a. Auto-detect project stack:

Scan for language indicator files and suggest packages:

File	Stack	Suggested Packages
package.json	Node.js	nodejs, check lockfile for pnpm/yarn/npm
pnpm-lock.yaml	Node.js + pnpm	nodejs, pnpm
yarn.lock	Node.js + yarn	nodejs, yarn
package-lock.json	Node.js + npm	nodejs
Cargo.toml	Rust	rustc, cargo, rust-analyzer
go.mod	Go	go, gopls
pyproject.toml	Python	python3, uv
requirements.txt	Python	python3, pip
Gemfile	Ruby	ruby, bundler
pom.xml	Java	jdk, maven
build.gradle	Java/Kotlin	jdk, gradle
*.csproj	.NET	dotnet-sdk
Makefile	C/C++	gnumake, gcc
CMakeLists.txt	C/C++	cmake, gcc
Dockerfile	Docker	docker

Also read CLAUDE.md if it exists to understand the project context and tech stack.

2b. Present detected packages:

Use AskUserQuestion with multiSelect to show detected packages:

Based on your repository, I detected these packages:
[x] nodejs_22
[x] pnpm
[x] typescript

Let user confirm, deselect, or add more via "Other" option.

2c. Ask for additional packages:

Ask: "Any additional packages you need? (e.g., redis, postgresql, jq)"

For each package mentioned:

1. Check .claude/devenv.local.md for use_mcp_search setting (default: true)
2. If MCP search is enabled, try MCP tools in priority order: a. 1mcp (preferred — already running, no extra process):

   mcp__1mcp__nixos_1mcp_nixos_search(
     query="<package>",
     search_type="packages",
     channel="unstable",
     limit=10
   )
   

   b. Global/project level MCP (if user has mcp-nixos configured):

   mcp__nixos__nix(
     action="search",
     query="<package>",
     source="nixos",
     type="packages",
     channel="unstable",
     limit=10
   )
   

   c. Plugin's bundled MCP:

   mcp__plugin_devenv_nixos__nix(
     action="search",
     query="<package>",
     source="nixos",
     type="packages",
     channel="unstable",
     limit=10
   )
   

3. Fallback: If no MCP tool available or use_mcp_search: false, use bash: nix-shell -p nix --run "nix search nixpkgs <package> --json"
4. If version specified (e.g., nodejs@20), handle version resolution: a. Try mcp__1mcp__nixos_1mcp_nixhub_find_version(package_name="nodejs", version="20") b. If 1mcp unavailable, try mcp__plugin_devenv_nixos__nix_versions(package="nodejs", version="20") c. Also search for nixpkgs variants like nodejs_20 d. Prefer the nixpkgs variant if it exists; offer pinned commit hash as alternative
5. Present search results and confirm selection

2d. Offer security tools:

Use AskUserQuestion with multiSelect:

Security tools (recommended):
[ ] pre-commit - Git hooks with SAST tools for your stack (using git-hooks.nix)

If pre-commit selected, determine which git-hooks.nix hooks to enable based on detected stack:

Stack	Hooks to Enable
JavaScript/TypeScript	eslint.enable = true; prettier.enable = true;
Python	ruff.enable = true; ruff-format.enable = true;
Go	golangci-lint.enable = true;
Rust	clippy.enable = true; rustfmt.enable = true;
Nix (always)	nixfmt-rfc-style.enable = true; statix.enable = true; deadnix.enable = true;
Shell scripts	shellcheck.enable = true;
Docker	hadolint.enable = true;
General (always)	check-yaml.enable = true; trim-trailing-whitespace.enable = true;

Then ask about secret scanning:

Use AskUserQuestion:

Secret scanner preference:
○ trufflehog (Recommended) - Built-in hook, works out of the box
○ gitleaks - Popular choice, requires custom hook configuration
○ None - Skip secret scanning

If trufflehog selected:

• Add trufflehog.enable = true; to the hooks configuration (built-in, no extra config needed)

If gitleaks selected:

• Add gitleaks as a custom hook (it's NOT built-in to git-hooks.nix):

gitleaks = {
  enable = true;
  name = "gitleaks";
  entry = "${pkgs.gitleaks}/bin/gitleaks git --pre-commit --redact --staged --verbose";
  language = "system";
  pass_filenames = false;
};

• Also add gitleaks to the packages list
• If pre-commit not selected, still add gitleaks to packages for manual use

2e. Choose direnv mode:

Use AskUserQuestion:

direnv mode:
○ direnv-instant (Recommended) - Async loading, instant shell prompt
○ Standard direnv - Traditional sync direnv (shell waits for Nix)
○ None - Use nix develop manually

Based on selection:

• direnv-instant: Add direnv-instant as a flake input (it's NOT a nixpkgs package):

  inputs.direnv-instant.url = "github:Mic92/direnv-instant";
  

  Then reference the package in devShell:

  direnv-instant.packages.${system}.default
  

• Standard direnv: Add direnv to packages list in flake.nix (from nixpkgs)
• None: Don't add direnv package, skip .envrc handling

Save the selection to .claude/devenv.local.md as direnv_mode: instant|standard|none

2f. Choose shell welcome style:

Use AskUserQuestion to let the user choose their shell welcome message style:

Shell welcome message style:
○ Box style (Default) - Unicode box with devenv branding
○ Minimal - Single line "▸ devenv ready"
○ Project name - Shows current project directory name
○ Tech style - Terminal-inspired "[devenv] :: environment initialized"
○ Custom - Enter your own message
○ None - No welcome message

If "Custom" is selected:

1. Use AskUserQuestion to ask: "Enter your custom welcome message (use \n for multiple lines):"
2. Store the custom text for shellHook generation

Save the selection to .claude/devenv.local.md as:

• shell_welcome: box|minimal|project|tech|custom|none
• shell_welcome_custom: "user's custom message" (only if custom selected)

2g. Generate files:

1. Generate flake.nix using the appropriate template:

Basic Template (without pre-commit):

{
  description = "Development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    # DIRENV_INSTANT_INPUT_HERE (if selected)
  };

  outputs = {
    self,
    nixpkgs,
    flake-utils,
    # DIRENV_INSTANT_PARAM_HERE (if selected)
  }:
    flake-utils.lib.eachDefaultSystem (
      system: let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = with pkgs; [
            # PACKAGES_HERE
          ]
          # DIRENV_INSTANT_PACKAGE_HERE (if selected)
          ;

          shellHook = ''
            # SHELL_WELCOME_HERE
          '';
        };
      }
    );
}

To add direnv-instant to the template:

• Replace # DIRENV_INSTANT_INPUT_HERE with: direnv-instant.url = "github:Mic92/direnv-instant";
• Replace # DIRENV_INSTANT_PARAM_HERE with: direnv-instant,
• Replace # DIRENV_INSTANT_PACKAGE_HERE with: ++ [ direnv-instant.packages.${system}.default ]

To add standard direnv: Simply add direnv to the packages list (it's a nixpkgs package).

Template with git-hooks.nix (pre-commit enabled):

{
  description = "Development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    git-hooks.url = "github:cachix/git-hooks.nix";
    # DIRENV_INSTANT_INPUT_HERE (if selected)
  };

  outputs = {
    self,
    nixpkgs,
    flake-utils,
    git-hooks,
    # DIRENV_INSTANT_PARAM_HERE (if selected)
  }:
    flake-utils.lib.eachDefaultSystem (
      system: let
        pkgs = nixpkgs.legacyPackages.${system};

        # Pre-commit hooks configuration
        pre-commit-check = git-hooks.lib.${system}.run {
          src = ./.;
          hooks = {
            # Nix
            nixfmt-rfc-style.enable = true;
            statix.enable = true;
            deadnix = {
              enable = true;
              settings.edit = true;
              settings.noLambdaPatternNames = true; # Preserve 'self' in flake outputs
            };

            # General
            check-yaml.enable = true;
            trim-trailing-whitespace.enable = true;

            # LANGUAGE_HOOKS_HERE

            # SECRET_SCANNER_HERE
            # For trufflehog (built-in): trufflehog.enable = true;
            # For gitleaks (custom hook):
            # gitleaks = {
            #   enable = true;
            #   name = "gitleaks";
            #   entry = "${pkgs.gitleaks}/bin/gitleaks git --pre-commit --redact --staged --verbose";
            #   language = "system";
            #   pass_filenames = false;
            # };
          };
        };
      in {
        # Run hooks in CI with: nix flake check
        checks.pre-commit-check = pre-commit-check;

        devShells.default = pkgs.mkShell {
          packages = with pkgs; [
            # PACKAGES_HERE
          ]
          ++ pre-commit-check.enabledPackages
          # DIRENV_INSTANT_PACKAGE_HERE (if selected)
          ;

          shellHook = ''
            ${pre-commit-check.shellHook}
            # SHELL_WELCOME_HERE
          '';
        };
      }
    );
}

direnv-instant integration: Same as basic template - add input, parameter, and package reference.

Shell welcome replacement: Replace # SHELL_WELCOME_HERE based on user's shell_welcome preference:

Style	Replacement Content
box	echo "╔══════════════════════════════════════╗" echo "║ 🔧 devenv ║" echo "║ Development environment loaded ║" echo "╚══════════════════════════════════════╝"
minimal	echo "" echo " ▸ devenv ready" echo ""
project	echo "" echo " ╭───────────────────────────────────╮" echo " │ 📁 $(basename $PWD)" echo " │ Development environment loaded" echo " ╰───────────────────────────────────╯" echo ""
tech	echo "" echo " [devenv] :: environment initialized" echo " └── packages loaded, hooks active" echo ""
custom	Parse shell_welcome_custom from settings, split by \n, wrap each line in echo "..."
none	# No welcome message (empty comment, no output)

For custom messages:

1. Read shell_welcome_custom from .claude/devenv.local.md

2. Split by \n for multi-line support

3. Wrap each line in echo "..." statements

4. Escape special characters: $ becomes \$, " becomes \", \ becomes \\

5. If empty, fall back to box style

6. Handle .envrc (if direnv mode is not "none"):

   IMPORTANT: Never read .envrc files - they may contain secrets.

   • Check if .envrc exists: test -f .envrc
   • If .envrc does NOT exist:
     • Create it with content: use flake
   • If .envrc EXISTS:
     • Do NOT read the file
     • Tell the user: ".envrc already exists. Ensure it contains use flake for direnv integration."

7. Update .gitignore to exclude generated/sensitive files:

   • Check if .gitignore exists
   • Append entries that are not already present:

# Nix/direnv
.direnv/
.pre-commit-config.yaml

# Environment files (sensitive)
.env
.env.*
.envrc

# Claude local settings (user preferences)
.claude/*.local.md

4. Run nix flake lock to generate flake.lock

2h. Validate the flake:

After generating files, ALWAYS validate the flake works correctly:

nix flake check --no-build 2>&1

If validation fails:

1. Read the error message carefully
2. Common issues to check:
   • Missing self parameter in outputs (required by flake system even if unused)
   • Syntax errors in Nix expressions
   • Invalid package names
   • Missing inputs referenced in outputs
3. Fix the issue in flake.nix
4. Re-run validation until it passes
5. Only proceed to output instructions after validation succeeds

Important: Never finish the task if validation fails. The user should have a working environment.

2i. Output instructions:

If direnv-instant was selected:

Development environment created!

To enter the environment:
  nix develop

Or with direnv-instant (async, instant prompt):
  direnv allow

direnv-instant shell setup (one-time):
  # bash (~/.bashrc) or zsh (~/.zshrc):
  eval "$(direnv-instant hook bash)"  # or zsh

  # fish (~/.config/fish/config.fish):
  direnv-instant hook fish | source

Note: Remove any existing `eval "$(direnv hook ...)"` first.

Your environment includes:
- [list packages]

If standard direnv was selected:

Development environment created!

To enter the environment:
  nix develop

Or with direnv:
  direnv allow

Your environment includes:
- [list packages]

If direnv mode is "none":

Development environment created!

To enter the environment:
  nix develop

Your environment includes:
- [list packages]

[If pre-commit was selected, append:]

Pre-commit hooks are configured via git-hooks.nix.
They will auto-install when you run `nix develop`.

Available hooks:
- [list enabled hooks]

To run hooks manually: pre-commit run --all-files
To validate in CI: nix flake check

---

If flake.nix EXISTS (Manage Flow)

2a. Parse current state:

1. Read flake.nix and extract current packages from packages = with pkgs; [ ... ]
2. Check if git-hooks input exists in flake.nix (indicates pre-commit is configured)

2b. Ask what to do:

Use AskUserQuestion:

What would you like to do?
○ Add packages - Add new packages to your environment
○ Upgrade packages - Update flake.lock to get latest versions
○ Remove packages - Remove packages from your environment
○ Setup security tools - Add pre-commit and gitleaks (only if not configured)
○ Switch direnv mode - Change between direnv-instant, standard direnv, or none
○ Change welcome style - Customize shell welcome message

Only show "Setup security tools" option if git-hooks input is NOT present in flake.nix. Show "Switch direnv mode" and "Change welcome style" options always (user may want to change their preference).

2c. Handle selected action:

Add packages:

1. Ask: "What packages would you like to add?"
2. Search nixpkgs for each package:
   • Check .claude/devenv.local.md for use_mcp_search setting (default: true)
   • If MCP search is enabled, try MCP tools in priority order: a. 1mcp (preferred): mcp__1mcp__nixos_1mcp_nixos_search(query="<pkg>", search_type="packages", channel="unstable", limit=10) b. Global/project MCP: mcp__nixos__nix(action="search", query="<pkg>", ...) c. Plugin's bundled MCP: mcp__plugin_devenv_nixos__nix(action="search", query="<pkg>", ...)
   • Fallback: If no MCP tool available or use_mcp_search: false, use bash: nix-shell -p nix --run "nix search nixpkgs <package> --json"
   • For versioned packages (e.g., nodejs@20): a. Try mcp__1mcp__nixos_1mcp_nixhub_find_version(package_name="nodejs", version="20") b. If 1mcp unavailable, try mcp__plugin_devenv_nixos__nix_versions(package="nodejs", version="20") c. Also search for nixpkgs variants like nodejs_20
3. Confirm package names
4. Edit flake.nix to add packages to the list
5. Run nix flake lock --update-input nixpkgs to update lock

Upgrade packages:

1. Run nix flake update to update all inputs
2. Show what was updated from the output

Remove packages:

1. Show current packages list with checkboxes (multiSelect)
2. Let user select which to remove
3. Edit flake.nix to remove selected packages

Setup security tools:

1. Follow the same flow as step 2d from Initialize Flow
2. Add git-hooks input to flake.nix
3. Add the pre-commit-check configuration
4. Update the devShell to include pre-commit-check.enabledPackages and shellHook
5. Add the checks.pre-commit-check output

Switch direnv mode:

1. Check current direnv configuration in flake.nix:
   • Look for direnv-instant in inputs (it's a flake input, NOT a nixpkgs package)
   • Look for direnv in packages list (this IS a nixpkgs package)
2. Use AskUserQuestion:

   direnv mode:
   ○ direnv-instant (Recommended) - Async loading, instant shell prompt
   ○ Standard direnv - Traditional sync direnv (shell waits for Nix)
   ○ None - Use nix develop manually
   

3. Based on selection:
   • direnv-instant:
     • Add direnv-instant.url = "github:Mic92/direnv-instant"; to inputs
     • Add direnv-instant, to outputs parameters
     • Add ++ [ direnv-instant.packages.${system}.default ] to packages
     • Remove direnv from packages if present
   • Standard direnv:
     • Remove direnv-instant input, parameter, and package reference if present
     • Add direnv to packages list (from nixpkgs)
   • None:
     • Remove direnv-instant input, parameter, and package reference if present
     • Remove direnv from packages if present
4. Update .claude/devenv.local.md with new direnv_mode setting
5. Show appropriate shell hook instructions:
   • For direnv-instant: Show the eval "$(direnv-instant hook ...)" instructions
   • For standard direnv: Remind to use eval "$(direnv hook ...)"
   • For none: Note that user should use nix develop manually

Change welcome style:

1. Read current shell_welcome setting from .claude/devenv.local.md (default: box)
2. Use AskUserQuestion:

   Shell welcome message style:
   ○ Box style (Default) - Unicode box with devenv branding
   ○ Minimal - Single line "▸ devenv ready"
   ○ Project name - Shows current project directory name
   ○ Tech style - Terminal-inspired "[devenv] :: environment initialized"
   ○ Custom - Enter your own message
   ○ None - No welcome message
   

3. If "Custom" selected, ask for custom message text
4. Update .claude/devenv.local.md with new shell_welcome (and shell_welcome_custom if applicable)
5. Update the shellHook section in flake.nix:
   • Read the current flake.nix
   • Locate the shellHook block in devShells.default
   • Replace the welcome message echo statements using the replacement table from Step 2g
   • Preserve any ${pre-commit-check.shellHook} if present at the start of shellHook
   • Keep any other shellHook content intact
6. Show the user a preview of their new welcome message

After any modification, validate the flake:

nix flake check --no-build 2>&1

If validation fails, fix the issue before completing the task.

---

Important Notes

• Always use nix-shell -p <tool> --run "<command>" for nix tools - do NOT assume they are installed system-wide
• The PostToolUse hooks will automatically format and lint flake.nix after any Write/Edit operations
• Use the nixpkgs channel from .claude/devenv.local.md if it exists, otherwise default to nixos-unstable
• When searching for packages, use 1mcp NixOS tools first, then mcp-nixos MCP, with bash fallback
• git-hooks.nix auto-generates .pre-commit-config.yaml via shellHook - no manual YAML needed!
• All hook tools are provided by Nix, ensuring reproducibility
• Critical: The self parameter in flake outputs is REQUIRED by the Nix flake system, even if not explicitly used in the function body. The plugin's deadnix hook is configured with --no-lambda-pattern-names to preserve it
• Always validate with nix flake check --no-build before completing any flake creation/modification task
• direnv-instant is a flake input, NOT a nixpkgs package: It must be added via inputs.direnv-instant.url = "github:Mic92/direnv-instant" and referenced as direnv-instant.packages.${system}.default. Standard direnv IS in nixpkgs and can be added directly to the packages list.

MCP Tools: NixOS Package Search

This plugin uses NixOS MCP tools for package search, providing access to 130K+ NixOS packages with accurate, up-to-date information.

Tool Priority Order

The command tries MCP tools in this order:

1. 1mcp (preferred): mcp__1mcp__nixos_1mcp_nixos_search — already running via 1mcp proxy, no extra process
2. Global/Project level: mcp__nixos__nix — if user has mcp-nixos configured globally or in project
3. Plugin's bundled: mcp__plugin_devenv_nixos__nix — plugin's own MCP server (fallback for non-1mcp environments)
4. Bash fallback: nix search command

This ensures the fastest available tool is used first, with graceful degradation.

Package Search

1mcp (separate tools per action):

mcp__1mcp__nixos_1mcp_nixos_search(
  query="<search_term>",
  search_type="packages",
  channel="unstable",
  limit=10
)

Global/Plugin MCP (combined action parameter):

mcp__nixos__nix(  # or mcp__plugin_devenv_nixos__nix
  action="search",
  query="<search_term>",
  source="nixos",
  type="packages",
  channel="unstable",
  limit=10
)

Version Search

For versioned package requests (e.g., nodejs@20):

1mcp — find specific version:

mcp__1mcp__nixos_1mcp_nixhub_find_version(
  package_name="nodejs",
  version="20"
)

1mcp — list all available versions:

mcp__1mcp__nixos_1mcp_nixhub_package_versions(
  package_name="nodejs",
  limit=20
)

Plugin bundled MCP — version lookup:

mcp__plugin_devenv_nixos__nix_versions(
  package="nodejs",
  version="20"
)

Version resolution workflow:

1. Try nixhub_find_version (or nix_versions) to find the exact version
2. Also search nixpkgs for variants like nodejs_20
3. Prefer the nixpkgs variant if it exists (simpler, no pinning needed)
4. Offer pinned commit hash from nixhub as alternative if no nixpkgs variant found

Parameter Reference

Tool	Parameter	Value	Description
1mcp_nixos_search	query	string	Package name or search term
1mcp_nixos_search	search_type	"packages"	Search packages (not options)
1mcp_nixos_search	channel	"unstable"	Nixpkgs channel
1mcp_nixos_search	limit	number	Max results to return
1mcp_nixhub_find_version	package_name	string	Package to find version for
1mcp_nixhub_find_version	version	string	Desired version (e.g., "20")
1mcp_nixhub_package_versions	package_name	string	Package to list versions for
1mcp_nixhub_package_versions	limit	number	Max versions to return
nixos__nix / plugin_devenv_nixos__nix	action	"search"	Search for packages
nixos__nix / plugin_devenv_nixos__nix	query	string	Package name or search term
nixos__nix / plugin_devenv_nixos__nix	source	"nixos"	Use NixOS packages source
nixos__nix / plugin_devenv_nixos__nix	type	"packages"	Search packages (not options)
nixos__nix / plugin_devenv_nixos__nix	channel	"unstable"	Use nixos-unstable channel
nixos__nix / plugin_devenv_nixos__nix	limit	number	Max results to return
plugin_devenv_nixos__nix_versions	package	string	Package to find version for
plugin_devenv_nixos__nix_versions	version	string	Desired version (optional)
plugin_devenv_nixos__nix_versions	limit	number	Max versions to return (optional)

Fallback Behavior

If no MCP tool is available, the command falls back to:

nix-shell -p nix --run "nix search nixpkgs <package> --json"

Settings File

Users can customize behavior via .claude/devenv.local.md:

---
nixpkgs_channel: nixos-unstable
use_mcp_search: true
direnv_mode: instant
shell_welcome: box
shell_welcome_custom: ""
---

Available Settings

Setting	Default	Description
nixpkgs_channel	nixos-unstable	Nixpkgs channel to use
use_mcp_search	true	Use mcp-nixos for package search. Set to false to always use bash fallback
direnv_mode	instant	direnv integration: instant (async, recommended), standard (sync), or none
shell_welcome	box	Welcome message style: box, minimal, project, tech, custom, or none
shell_welcome_custom	""	Custom welcome message text (only used when shell_welcome: custom). Use \n for multi-line

git-hooks.nix Hook Reference

Available Hooks by Language

Language	Hook Names
JavaScript/TypeScript	eslint, prettier
Python	ruff, ruff-format, black, mypy
Go	golangci-lint, gofmt
Rust	clippy, rustfmt, cargo-check
Nix	nixfmt-rfc-style, statix, deadnix
Shell	shellcheck, shfmt
Docker	hadolint
YAML	check-yaml, yamllint
Secrets	trufflehog, ripsecrets (built-in); gitleaks requires custom config
General	trim-trailing-whitespace, check-added-large-files, check-merge-conflicts

Example Hook Configuration

hooks = {
  # Enable a built-in hook
  eslint.enable = true;

  # Built-in secret scanner
  trufflehog.enable = true;

  # Enable with custom settings
  ruff = {
    enable = true;
    settings.args = ["--fix"];
  };

  # Custom hook example: gitleaks (not built-in)
  gitleaks = {
    enable = true;
    name = "gitleaks";
    entry = "${pkgs.gitleaks}/bin/gitleaks git --pre-commit --redact --staged --verbose";
    language = "system";
    pass_filenames = false;
  };
};

For full list of available hooks, see: https://github.com/cachix/git-hooks.nix