NixOS Command Not Found Handler

Automatically handles "command not found" errors in NixOS environments by searching for packages and retrying with nix shell.

When to Use

Activate this skill when:

• Command fails with "command not found" or "No such file or directory"
• User is in NixOS environment (detected by /etc/nixos existence or NIX_STORE env var)
• Command appears to be a standard Unix tool or known package

Workflow

1. Detect NixOS environment: Check for /etc/nixos or NIX_STORE env var
2. Extract command name: Get the missing command from error output
3. Delegate everything to nixos agent: Agent finds package AND runs command
4. Return command output: Agent provides the actual command result

Implementation Steps

1. Environment Detection

Check if we're in NixOS:

test -d /etc/nixos || test -n "$NIX_STORE"

2. Delegate Complete Task

Use Task tool with nixos agent to handle everything:

Task(
  description="Run missing command with nix shell",
  prompt="The command '<original-command>' failed with 'command not found'. Please:
1. Search for the NixOS package that provides this command
2. Run the command using 'nix shell nixpkgs#<package> -c <original-command>'
3. Return the actual command output/result",
  subagent_type="nixos"
)

3. Return Results

The nixos agent returns the actual command execution result, not just package info.

Examples

Missing tree command

1. User runs: tree /some/path
2. Error: zsh: command not found: tree
3. Detect NixOS environment ✓
4. Delegate to nixos agent: "Run 'tree /some/path' with nix shell"
5. Agent finds tree package, runs nix shell nixpkgs#tree -c tree /some/path
6. Agent returns: actual directory tree output

Missing jq command

1. User runs: cat data.json | jq '.name'
2. Error: command not found: jq
3. Delegate to nixos agent: "Run 'jq '.name'' with nix shell"
4. Agent finds jq package, runs with stdin preserved
5. Agent returns: actual JSON parsing result

Missing cargo command

1. User runs: cargo build
2. Error: command not found: cargo
3. Delegate to nixos agent: "Run 'cargo build' with nix shell"
4. Agent finds cargo package, runs nix shell nixpkgs#cargo -c cargo build
5. Agent returns: actual build output or errors

Edge Cases

Multiple Package Options

Nixos agent handles all selection logic internally:

• Uses nixos MCP tools to find best match
• Considers exact name matches, package descriptions, etc.
• Picks most appropriate option or asks user if truly ambiguous

Complex Commands

Nixos agent handles command complexity:

• Preserves pipes, redirects, and shell syntax
• Uses appropriate shell escaping when needed
• Maintains stdin/stdout/stderr as expected

Already in Nix Shell

Nixos agent handles this case:

• Detects if already in nix shell
• Still proceeds (might need different package)
• Can inform user about current nix shell context

Error Handling

Package Not Found

Nixos agent handles all error scenarios:

• Tries broader search terms and fallbacks
• Searches programs, options, or suggests alternatives
• Returns helpful error message if no package found

Command Failures

Nixos agent returns actual command results:

• Shows real command output if successful
• Returns actual error messages if command fails
• Distinguishes between "package not found" vs "command failed"

Integration Notes

Detection Triggers

Monitor for these error patterns:

• command not found: <cmd>
• <cmd>: No such file or directory
• zsh: command not found: <cmd>
• bash: <cmd>: command not found

Agent Responsibilities

Nixos agent handles all technical details:

• Maintains current working directory
• Preserves environment variables
• Keeps stdin/stdout/stderr intact
• Shows what package was used
• Provides appropriate feedback

Main Agent Role

Main agent just:

• Detects NixOS environment
• Delegates to nixos agent
• Returns agent's command results to user

Configuration

Excluded Commands

Don't handle these (likely typos or not packages):

• Single letters: a, b, x
• Common typos: sl, gerp
• Shell builtins that failed: cd, export

Channel Preference

• Default to nixpkgs# (follows system channel)
• Could use nixpkgs/unstable# for newest versions
• Respect user's flake configuration if detected