Claude Code in the Terminal: Setup, tmux and Troubleshooting

Published 22-10-2026. Last verified against Anthropic's documentation on 22-10-2026. Reviewed monthly, because install paths and terminal behavior change with releases.

Quick answer

To run Claude Code in the terminal, use the native installer for your system, open a new terminal window and run claude --version. If your shell answers zsh: command not found: claude, the install folder is not on your PATH yet: add ~/.local/bin to it and open a new window. This page is for a developer or tech lead who sets Claude Code up on a team's laptops and needs the same result on macOS, Linux, WSL and Windows. Our advice: use the native installer, pick a terminal where Shift+Enter works without setup, and only touch tmux settings if you really run Claude Code inside tmux. We ran none of these commands ourselves, so every fix below is vendor-documented and marked as not tested by us.

How we checked the information in this article

Our method is to read the vendor documentation, write down what it says with the date and mark anything we did not run. On 22-10-2026 we read three pages from Anthropic in full: the advanced setup page, the installation troubleshooting page and the terminal configuration page. Our gate for this page was a reproduction test: every fix run on at least two shells, zsh and bash, with the OS named at each step. We ran no test, so the gate rejected what we could not support. We dropped sudo npm install -g, because Anthropic's setup page warns against it. We dropped turning off Windows PATH importing in WSL with appendWindowsPath = false, because Anthropic's troubleshooting page says it breaks calling Windows programs from WSL. And we dropped fixes from third-party blogs that we saw in search results but did not open. We name the OS and shell for every step, as Anthropic does. The setup page shows 2.1.211 as an example version; we tested no version on any OS.

How do you run Claude Code in the terminal?

Install it with the command for your system, then start claude from your project folder. Anthropic's setup page marks the native install as recommended. The commands below are from that page and we did not run them.

The installer shows no progress while it downloads. When it finishes, open a new terminal window and run claude --version; a working installation prints a version number. Then run claude in your project folder and follow the browser prompts to log in. Claude Code needs a Pro, Max, Team, Enterprise or Console account, and the free claude.ai plan does not include it. Anthropic lists macOS 13.0 or later, Windows 10 1809 or later, Ubuntu 20.04 or later, Debian 10 or later and Alpine Linux 3.19 or later, with 4 GB of RAM and Bash, Zsh, PowerShell or CMD as the shell. If you would rather not use a terminal at all, Anthropic also offers a Desktop app.

Two Windows mix-ups cost people the most time. If you see The token '&&' is not a valid statement separator, you are in PowerShell and ran the CMD command. If you see 'irm' is not recognized as an internal or external command, you are in CMD and ran the PowerShell command. Anthropic recommends Git for Windows on native Windows so Claude Code can use the Bash tool; without it, Claude Code uses PowerShell as the shell tool. Our guide to Claude Code skills on Windows covers what changes for skills there, and how to update Claude Code covers what happens after the first install.

How do you fix "zsh: command not found: claude"?

The installer put claude in a folder your shell does not search. Check that ~/.local/bin/claude exists, then add ~/.local/bin to your PATH. Anthropic says the installer reports this case under Setup notes: in its output and prints the fix, but does not change PATH itself.

Pick the block for your shell. On macOS with Zsh, the default:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Linux with Bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

In Windows PowerShell, add the folder to your User PATH, then restart the terminal:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

In Windows CMD, open System Settings, go to Environment Variables and add %USERPROFILE%\.local\bin to your User PATH variable. Then restart the terminal. This three-command block prints the version, every claude on your PATH and your shell, so you can paste its output into a support ticket:

claude --version
which -a claude
echo $0

On Windows, use claude --version, where.exe claude and Test-Path "$env:USERPROFILE\.local\bin\claude.exe" instead.

If claude is still not found, Anthropic lists three causes. The window predates the change, or it is a terminal inside an editor, which takes its PATH from the editor: open a new window or quit and reopen the editor. The line was not saved: run grep -n '.local/bin' ~/.zshrc, using your shell's file name. Or the line went to another shell's file: run echo $0 and repeat the two commands for that shell. If the echo command prints permission denied for ~/.zshrc, check the owner with ls -l ~/.zshrc. Anthropic's fix for a file owned by another user is sudo chown $(whoami) ~/.zshrc, and for a read-only file it is chmod u+w ~/.zshrc.

Two installs of Claude Code cause odd version behavior. Run which -a claude, ls -la ~/.claude/local/ and npm -g ls @anthropic-ai/claude-code, and keep only the native install. Anthropic removes extras with npm uninstall -g @anthropic-ai/claude-code, rm -rf ~/.claude/local and brew uninstall --cask claude-code. On Windows, an older Claude Desktop can register a Claude.exe in the WindowsApps directory that wins over the CLI; Anthropic's fix is updating Claude Desktop.

When the problem is a project that will not start rather than claude itself, we reach for env doctor. We sell skills that load into Claude, Cursor, Codex CLI and Copilot, and we name three skills from our marketplace on this page. No vendor paid to be listed. Per its listing, env doctor is free and diagnoses why a project will not start across runtimes, dependencies, env vars, ports and build artifacts. We have not run it. Our guide to diagnosing environment issues shows the thinking behind it, and the Claude DevOps and cloud collection has more skills for setup and deploy work.

What is the best terminal for Claude Code?

For most people we would pick Ghostty, then iTerm2, then Windows Terminal, and the reasons come from Anthropic's terminal configuration page. We put Ghostty first because Shift+Enter inserts a newline without setup and desktop notifications work by default, with no extra step to reach your OS notification center. iTerm2 is second because it has the same defaults, but notifications need forwarding switched on ("Send escape sequence-generated alerts"), the Option keys set to "Esc+" for Option shortcuts, and /terminal-setup run once so /copy can reach your clipboard. Windows Terminal is third because Shift+Enter works without setup, but Claude Code sends desktop notifications by default only in Ghostty, Kitty and iTerm2, so you set preferredNotifChannel to "terminal_bell". What would move Ghostty down is a team that lives in an editor's integrated terminal; our Claude Code IDE setup guide covers that route.

The rest, per Anthropic: Kitty, WezTerm, Warp, Apple Terminal and Windows Terminal need no setup for Shift+Enter. VS Code, Cursor, Devin Desktop, Alacritty before 0.16 and Zed need /terminal-setup once. gnome-terminal and JetBrains IDE terminals cannot do Shift+Enter, so use Ctrl+J, or type \ and press Enter, which works in every terminal. In Apple Terminal, tick "Use Option as Meta Key" under Settings, Profiles, Keyboard for the Option shortcuts. If characters render as boxes in an editor's terminal, /terminal-setup turns off terminal.integrated.gpuAcceleration. If the display flickers, /tui fullscreen switches the renderer.

To get an alert when Claude finishes, set the bell in ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

Anthropic also documents a Notification hook that plays a sound or runs any command. For hooks and other repeatable chores, browse the Claude workflow automation collection.

How do you run Claude Code in tmux?

Add three lines to ~/.tmux.conf and reload it. By default, inside tmux, Shift+Enter submits instead of inserting a newline, and desktop notifications and the progress bar never reach the outer terminal. Anthropic's fix:

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Then run tmux source-file ~/.tmux.conf to apply it to the running server. The allow-passthrough line lets notifications and progress updates through, and the two extended-keys lines let tmux tell Shift+Enter from plain Enter. Run /terminal-setup directly in the host terminal, not inside tmux or screen, because it writes to the host terminal's configuration. If your terminal shows session status through the OSC 7501 protocol, start the session outside tmux, since allow-passthrough has no effect on that. We have not run any of this.

Sessions survive more than people expect. Anthropic says restarting does not lose your conversation: run claude --resume in the same directory. If memory passes 2.5 GB, a warning appears, and the fix is to restart and run claude --continue. Press Ctrl+C if Claude Code hangs. Our view is one session per task. When one agent should hand work to others, see the Claude agents orchestration collection. For long sessions, context window tracker is free and, per its listing, monitors context window usage with token breakdowns, and task completor is free and gives copy-pasteable commands to commit, push and deploy. We ran neither. More in the Claude productivity collection.

How do you troubleshoot Claude Code in the terminal?

Start with claude doctor in your shell, or /doctor inside a session. Anthropic describes claude doctor as a read-only check that prints install health, settings errors and warnings with suggested fixes without starting a session. Then match your symptom to the fixes below, all from Anthropic's pages and none tested by us.

On WSL, install and launch claude inside the WSL terminal, not from PowerShell or CMD. If a npm install gives exec: node: not found, WSL is probably using Windows Node.js: which npm and which node paths starting with /mnt/c/ are Windows binaries, and the fix is installing Node with your distribution's package manager or nvm. Searches can return fewer matches when the project lives under /mnt/c/, so keep it under /home/. Anthropic's table also shows sandboxing as supported on WSL 2 and not on WSL 1 or native Windows. If sandboxing matters to your team, look at the Claude security collection and our Claude Code sandbox guide. On Alpine, the documented install command fails until you install bash and curl, and you then add libgcc, libstdc++ and ripgrep and set USE_BUILTIN_RIPGREP to 0.

Three smaller terminal symptoms have exact fixes. Stray >0q at startup or >4m after exit comes from a terminal built on a VTE library older than 0.53, and Anthropic says to update to v2.1.301 or later; echo $VTE_VERSION below 5300 confirms the cause. If every Backspace deletes a whole word on Windows, set CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0. If a download fails with curl: (22) and a 403, Anthropic points to a proxy, a network filter or an unsupported region, and checks it with curl -sI https://downloads.claude.ai/claude-code-releases/latest, which should return a 200. Behind a proxy, set HTTP_PROXY and HTTPS_PROXY before installing.

When skills stop loading after a fix, our guide to Claude Code skills not working walks through the usual causes, and the Claude testing and debugging collection has skills for the next step.

Where to go next

Keep the install current with the steps in our guide to updating Claude Code, linked in the install section above, and read Anthropic's own pages for anything that changes after 22-10-2026: advanced setup, installation troubleshooting and terminal configuration, listed under Sources below. We will recheck this page monthly and mark what changed.

Written by Samuel Rose, Founder of Agensi.

Sources

• Claude Code docs: advanced setup
• Claude Code docs: installation troubleshooting
• Claude Code docs: terminal configuration