Terminal and Shell Setup Guide for Developers

A good terminal setup takes about thirty minutes and saves hours later. You need a terminal app you like, a shell that suits your system, your Git identity, an SSH key and a few editor settings.

This guide covers terminal setup for Windows, macOS and Linux, then the extra steps for Claude Code. It uses Microsoft, Apple, GitHub, Git, VS Code and Claude Code documentation. Sources were checked on October 22, 2026.

The short answer

Pick a terminal app, confirm which shell it runs, set your Git name and email, create an SSH key for GitHub, and learn how your editor opens its terminal. Then fix anything your tools complain about.

On Windows, use Windows Terminal and WSL for Linux commands. On a Mac, you can start with the built-in Terminal and its default shell, zsh. On Linux, your desktop terminal is usually fine.

Terminal, shell and console

In Microsoft's words, Windows Terminal is a modern host app that runs command-line shells like Command Prompt, PowerShell and bash through WSL. That wording shows the split: the host is the window, and the shells run inside it.

This matters because most setup advice is about one or the other. Fonts, tabs and colors belong to the terminal. Prompts, aliases and PATH belong to the shell.

Terminal setup for Windows

Get Windows Terminal from the Microsoft Store. Microsoft says that if you cannot use the Store, you can get builds from GitHub, but those builds do not update automatically.

Microsoft also documents a default terminal setting. Open Windows Terminal, go to Settings, choose Startup and set Windows Terminal as the default terminal application. Command-line apps will then open there.

Microsoft says every version of Windows 11 has this setting, as does Windows 10 22H2 once the May 23, 2023 update, KB5026435, is installed.

Running Linux on Windows

Microsoft's install guide says that running wsl –install in PowerShell as administrator installs the features WSL needs and the Ubuntu distribution by default. Restart your machine afterward.

Windows Terminal then shows your Linux distribution as a profile. Our guides to every wslconfig setting explained and how to reclaim WSL disk space cover what comes after the install.

Terminal setup for macOS

macOS includes the Terminal app, so you can start without installing anything. The real question is which shell it runs.

Apple's support page says zsh is the default shell for newly created user accounts starting with macOS 10.15, and that bash was the default in macOS 10.14 and earlier.

It adds that you can switch shells from the command line or in the Users and Groups settings.

To see what you have, type the command below. Your result may differ if your account is older.

echo $SHELL

Apple suggests man zsh in Terminal for more about zsh and its completion system.

Terminal setup for Linux

Most Linux desktops include a terminal app already. Open it and check the shell with the same echo command. Our guide to Linux commands for beginners covers the commands you will use first.

This section is our advice. If a tool needs special key handling, check its documentation for your terminal. For example, Claude Code's documentation lists gnome-terminal as a terminal where Shift+Enter is not available.

Choose a shell

This table lists the shells you are most likely to meet. It shows what is common, not what you should switch to.

Shell	Where you will meet it
zsh	The default for new macOS accounts since macOS 10.15, according to Apple
bash	The default on macOS 10.14 and earlier, and the shell most Linux tutorials assume
PowerShell	A shell Windows Terminal can host
Command Prompt	The older Windows shell Windows Terminal can also host

The macOS rows follow Apple's support page. The note that Linux tutorials assume bash is our observation.

Set up Git

Git's setup guide asks you to tell Git who you are, since every commit you make carries that identity. Run these two commands once.

git config --global user.name "Your Name"
git config --global user.email you@example.com

Git's guide also says that from version 2.28 you can choose the name of the first branch. This command sets it to main.

git config --global init.defaultBranch main
git config --list

The list command shows every setting Git can find. Our Git tutorial from basics to advanced continues from here with your first commit.

Create an SSH key for GitHub

GitHub's documentation uses ssh-keygen with the Ed25519 algorithm and an email label. It adds that you can use RSA with 4096 bits if a legacy system does not support Ed25519.

ssh-keygen -t ed25519 -C "you@example.com"

When it asks where to save the key, pressing Enter accepts the default location. GitHub's guide then covers adding the key to the SSH agent.

Share only the public key, which ends in .pub. Never paste or send the private key. This is our advice, and it applies to every service that uses SSH keys.

The terminal inside VS Code

VS Code's documentation says it includes a full-featured integrated terminal, and it opens in your project folder. Open it through the View menu, the Command Palette or the Terminal menu.

The toggle shortcut is Ctrl+` on Windows and Linux, and the new terminal shortcut is Ctrl+Shift+` according to the same page. Shells are detected and listed in the terminal profiles dropdown.

Our comparison of VS Code, Cursor and JetBrains covers how each editor handles terminals and AI tools.

Terminal setup for Claude Code

Claude Code's documentation says it works in any terminal without configuration. The terminal page is for fixing a specific problem, so start with the symptom, not the setup steps.

The most common one is Shift+Enter. This table is from Claude Code's terminal documentation.

Terminal	Does Shift+Enter add a new line
Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal	Works without setup
VS Code, Cursor, Devin Desktop, Alacritty before 0.16, Zed	Run /terminal-setup once
gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio	Not available, so use Ctrl+J or a backslash then Enter

It adds that terminals with kitty keyboard protocol support, including foot and Alacritty 0.16 or newer, also work without setup, provided you run Claude Code v2.1.269 or later.

What the terminal-setup command does

For the editors in the middle row, running /terminal-setup adds a Shift+Enter keybinding to the terminal's config file. In VS Code, Cursor and Devin Desktop, it additionally changes two editor settings.

One of them turns terminal GPU acceleration off to prevent garbled text. If you want it back, set it to auto and reload the window. Existing bindings are left in place.

Run it from the terminal app itself

The documentation tells you to launch /terminal-setup straight from the host terminal, never inside tmux or screen, because it has to edit that terminal's own configuration.

This is also the safest explanation for the error people search for, terminal setup cannot be run from xterm-256color. That value is a generic terminal type, not an app.

I could not find that exact message in the documentation, so treat this as a likely cause, not a confirmed one.

Our advice is to check where you ran it. Open the terminal app itself, outside tmux or screen, and try again.

Option key shortcuts on macOS

Claude Code's documentation says most macOS terminals do not treat the Option key as a modifier unless you turn that on. Shortcuts that use it, such as Option+Enter for a new line, do nothing until you enable it.

In Apple Terminal, go to Settings, Profiles, Keyboard and tick Use Option as Meta Key. If you accepted the first-run prompt in Claude Code, this is already set.

For iTerm2, go to Settings, Profiles, Keys, General, and change the Left Option key and the Right Option key to Esc+.

A terminal bell when Claude finishes

Out of the box, Claude Code shows desktop notifications only in Ghostty, Kitty and iTerm2. Elsewhere, the documentation's fix is the preferredNotifChannel setting, with the value terminal_bell, in your settings file.

{
"preferredNotifChannel": "terminal_bell"
}

The setting goes in the settings.json file inside the .claude folder in your home directory, according to the same page.

Using tmux

Inside tmux, Shift+Enter sends the message instead of adding a line, and notifications do not reach the outer terminal. Claude Code's documentation gives three lines for your tmux configuration file.

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

After adding them, run the source-file command from the documentation to apply them to the running server.

Fixing common problems

This table collects the fixes above. The first four come from the sources named in this guide, and the last is our suggestion.

Problem	What to try
Windows apps do not open in Windows Terminal	Set it as the default terminal application under Startup
Git commits show the wrong author	Run the git config commands for name and email
Shift+Enter submits in Claude Code	Check the terminal table, then run /terminal-setup or use Ctrl+J
Option shortcuts do nothing on Mac	Turn on Use Option as Meta Key in your terminal
Nothing works and you are not sure why	Test in the plainest terminal you have, then add changes back one at a time

A setup checklist

Work through this list once on a new machine.

Frequently asked questions

How do I get a terminal ready for coding?

Install a terminal app, confirm the shell, set your Git identity and SSH key, and learn your editor's terminal. Add tool-specific settings only when needed.

How is a terminal different from a shell?

The terminal is the window you type into. The shell is the program that interprets what you type.

What shell does macOS use?

Apple says zsh is the default for new accounts since macOS 10.15. Older versions used bash.

How do I run Linux on Windows?

Use WSL. Microsoft's wsl –install command installs it with Ubuntu as the default distribution.

Do I need terminal setup for Claude Code?

Not usually. The documentation states that it runs in any terminal with no configuration, and it lists fixes for particular problems.

Why does terminal setup fail from xterm-256color?

I could not confirm the cause. Run the command in the host terminal, outside tmux or screen, because that is what the documentation requires.

Up nextVS Code vs Cursor vs JetBrainsYour editor is the other half of your setup. Read our comparison of VS Code vs Cursor vs JetBrains.→