Claude Code for Nushell (2026)

The Setup

You are using Nushell, the shell that treats everything as structured data — tables, records, and lists instead of plain text streams. Running Claude Code inside Nushell lets you pipe its output through Nushell’s powerful data manipulation commands. But Claude Code generates bash/zsh commands that do not work in Nushell’s different syntax.

What Claude Code Gets Wrong By Default

  1. Generates bash syntax for shell commands. Claude writes export VAR=value, if [ -f file ], and command1 && command2. Nushell uses $env.VAR = value, if ("file" | path exists), and command1; command2.

  2. Uses text-parsing pipes (grep, awk, sed). Claude pipes output through grep pattern | awk '{print $2}'. Nushell returns structured tables — use where column =~ pattern | get column instead of text munging.

  3. Writes .bashrc or .zshrc configurations. Claude adds environment setup to bash config files. Nushell uses config.nu for configuration and env.nu for environment variables.

  4. Assumes command output is plain text. Claude parses JSON output with jq. Nushell natively understands JSON, YAML, CSV, and TOML — open file.json returns a structured record, and from json converts piped text to data.

The CLAUDE.md Configuration

# Nushell Development Environment
## Shell
- Shell: Nushell (nu)
- Config: ~/.config/nushell/config.nu
- Env: ~/.config/nushell/env.nu
- Data-oriented: tables, records, lists — not text streams
## Nushell Rules
- Variables: let name = value (immutable), mut name = value (mutable)
- Environment: $env.VAR_NAME = "value"
- Conditions: if condition { } else { } (no square brackets)
- Pipes return structured data, not text
- Use 'where' instead of grep: ls | where name =~ ".ts"
- Use 'get' instead of awk: ps | get name
- JSON handled natively: open data.json | get users
- String interpolation: $"Hello ($name)"
## Conventions
- Claude Code commands should output plain text (default works)
- Process Claude output with Nushell data commands
- Custom commands in ~/.config/nushell/scripts/
- Use 'complete' for capturing stdout + stderr + exit code
- Path operations: "file.ts" | path parse | get stem
- Never use bash-specific syntax (&&, ||, $(), backticks)

Workflow Example

You want to analyze Claude Code’s git output with Nushell’s data tools. Prompt Claude Code:

“Show me all TypeScript files changed in the last 5 commits, grouped by directory, with the change count per directory. Use Nushell-compatible commands.”

Claude Code should run git log --oneline -5 --name-only --diff-filter=M and pipe through Nushell commands: lines | where $it ends-with ".ts" | each { path parse } | group-by parent | transpose dir files | each { {dir: $in.dir, count: ($in.files | length)} }.

Common Pitfalls

  1. Subshell syntax differences. Claude uses $(command) for command substitution. Nushell uses parentheses: (command). The bash $(...) syntax causes parse errors in Nushell.

  2. Boolean operator differences. Claude writes command1 && command2 for sequential execution. Nushell does not have && — use ; for sequential commands or wrap in a block: do { command1; command2 }.

  3. Environment variable persistence. Claude sets env vars with $env.VAR = value in a script expecting them in later commands. Nushell scopes environment changes to the current block. Use load-env or set variables in env.nu for persistence across shell sessions.

Configure permissions → Build your settings with our Permission Configurator.

Frequently Asked Questions

What is the minimum setup required?

You need Claude Code installed (Node.js 18+), a project with a CLAUDE.md file, and the relevant toolchain for your project type (e.g., npm for JavaScript, pip for Python). The CLAUDE.md file should describe your project structure, conventions, and common commands so Claude Code can work effectively.

How long does the initial setup take?

For a typical project, initial setup takes 10-20 minutes. This includes creating the CLAUDE.md file, configuring .claude/settings.json for permissions, and running a test task to verify everything works. Subsequent sessions start immediately because the configuration persists.

Can I use this with a team?

Yes. Commit your .claude/ directory and CLAUDE.md to version control so the entire team uses the same configuration. Each developer can add personal preferences in ~/.claude/settings.json (user-level) without affecting the project configuration. Review CLAUDE.md changes in pull requests like any other configuration file.

What if Claude Code produces incorrect output?

First check that your CLAUDE.md accurately describes your project conventions. Incorrect or outdated context is the most common cause of wrong output. If the output is still wrong, provide feedback in the same session — Claude Code learns from corrections within a conversation. For persistent issues, add explicit rules to CLAUDE.md (e.g., “Always use single quotes” or “Never modify files in the config/ directory”).