A step-by-step guide to installing and configuring Claude Code on macOS, the way I use it. This isn't meant to be the definitive reference -- it's just my personal setup that's been working well for me. Things change fast, so if something looks off, check the official docs or let me know.
Official docs: https://code.claude.com/docs/en/setup
- macOS 13.0+ (Ventura or later)
- 4 GB+ RAM
- Internet connection
curl -fsSL https://claude.ai/install.sh | bash
Alternatively, via Homebrew (note: won't auto-update):
brew install --cask claude-code
claude --version
claude doctor
claude
/login
Follow the prompts to authenticate with your Claude Pro, Max, Team, or Enterprise account.
Official docs: https://cli.github.com/
I use gh extensively to interact with GitHub repos from the terminal, and Claude Code uses it too when working with private repos. GitHub also offers an official MCP server, but gh is the better choice for Claude Code: it consumes far less context, is faster to execute, easier to debug when things fail, and Claude already knows how to compose gh commands fluently since it's well-represented in its training data.
brew install gh
gh auth login
You'll be prompted to choose:
- GitHub.com or GitHub Enterprise
- HTTPS orSSH protocol
- Web browser authentication (recommended)
gh auth status
gh repo clone owner/repo # Clone a repo
gh pr create # Create a pull request
gh pr list # List open PRs
gh pr checkout 123 # Check out a PR locally
gh issue list # List issues
gh issue view 456 # View an issue
gh browse # Open repo in browser
Official docs: https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/
This connects Claude Code to Jira and Confluence via the official Atlassian Rovo MCP Server. It uses OAuth 2.1 so no API tokens are needed.
claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp
You can scope it to different levels:
claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp --scope user
claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp --scope project
- Start Claude Code with
claude - Run
/mcpto see MCP servers - Follow the browser-based OAuth flow to log in with your Atlassian account
claude mcp list
claude mcp get atlassian
Official docs: https://code.claude.com/docs/en/statusline Package: https://github.com/Owloops/claude-powerline
This one is purely cosmetic but I really like it. It adds a vim-style powerline bar at the bottom of Claude Code showing git info, token usage, session cost, model name, and more.
Add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "npx @owloops/claude-powerline@latest"
}
}
No manual install needed -- npx fetches the latest version automatically.
You can pass flags to customize the appearance:
{
"statusLine": {
"type": "command",
"command": "npx @owloops/claude-powerline@latest --style=powerline --theme=nord"
}
}
Available styles: minimal, powerline, capsule
Available themes: dark, light, nord, tokyo-night, rose-pine, gruvbox
If you don't have a Nerd Font installed, add --charset=text for ASCII-only mode.
Official docs: https://code.claude.com/docs/en/settings
By default, Claude Code appends a Co-Authored-By: Claude ... trailer to every git commit and a generated-by note to pull request descriptions. This is totally a personal preference, but I like clean commits and PRs, so I disable it.
Add to ~/.claude/settings.json:
{
"attribution": {
"commit": "",
"pr": ""
}
}
Setting both to empty strings removes all attribution from commits and pull request descriptions. You can also customize them individually if you want attribution on one but not the other.
Official docs: https://code.claude.com/docs/en/hooks
This is one of my favorite little tweaks. Hooks let you run shell commands when certain events happen in Claude Code. I use them to play a sound when Claude finishes a task or needs my attention, so I can context-switch to something else and know when to come back.
Add to ~/.claude/settings.json:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Hero.aiff &"
}
]
}
],
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Hero.aiff &"
}
]
}
]
}
}
- Stop : Fires when Claude finishes responding. Great for long tasks.
- Notification : Fires when Claude needs attention (e.g., a permission prompt or idle input).
- matcher : An empty string matches all events. You can filter by specific notification types like
"permission_prompt"or"idle_prompt". &at the end : Runs the sound in the background so it doesn't block Claude.
You can swap Hero.aiff for any sound file in /System/Library/Sounds/ (macOS). Try Submarine.aiff, Glass.aiff, Ping.aiff, etc.
Official docs: https://code.claude.com/docs/en/permissions
Permissions control which tools Claude can use without asking. My setup is tailored to a Ruby/Rails workflow -- you'll want to adjust the allow list to match your own stack. The idea is to pre-allow the commands you trust so you don't get prompted constantly, while keeping sensitive files locked down.
Add to ~/.claude/settings.json:
{
"permissions": {
"allow": [
"Bash(rbenv:*)",
"Bash(ruby:*)",
"Bash(bundle:*)",
"Bash(gem:*)",
"Bash(rspec:*)",
"Bash(find:*)",
"Bash(cat:*)",
"Bash(gh:*)",
"Bash(ls:*)",
"Read(~/.zshrc)",
"Read(~/projects/src/intellum/dev-context-docs/**)",
"Write(~/projects/src/intellum/dev-context-docs/**)",
"Edit(~/projects/src/intellum/dev-context-docs/**)"
],
"deny": [
"Read(./secrets/**)"
]
}
}
Bash(command:*)-- Allow any arguments for that command (e.g.,Bash(gh:*)allowsgh pr list,gh issue view 123, etc.)Read(path)/Write(path)/Edit(path)-- Allow file operations on matching paths. Supports glob patterns (**for recursive,*for single level).denyalways wins -- Deny rules are evaluated first, soRead(./secrets/**)blocks access even if a broader allow rule would match.
Adjust the allow list to match the tools and paths you use day-to-day. The goal is to reduce permission prompts for trusted operations while keeping sensitive files protected.
Official docs: https://code.claude.com/docs/en/chrome
Claude in Chrome is a browser extension that lets Claude Code control your browser -- navigate pages, click buttons, fill forms, read console logs, and more.
- Google Chrome or Microsoft Edge (Arc, Brave, etc. are not supported)
- Claude Code 2.0.73+
- A direct Anthropic paid plan (Pro, Max, Team, or Enterprise)
- Go to the Chrome Web Store
- Click Add to Chrome
- Sign in with your Claude account
- Pin the extension (click the puzzle piece icon in Chrome toolbar, then the pin)
claude --chrome
Or enable it from within a session:
/chrome
To enable it by default (so you don't need --chrome every time), run /chrome and select "Enabled by default".
Run /mcp inside Claude Code and check that claude-in-chrome appears as a connected server.
Official docs: https://code.claude.com/docs/en/memory
The CLAUDE.md file is Claude Code's memory. Instructions placed here are included in every conversation. I keep mine in ~/.claude/CLAUDE.md so they apply globally across all projects.
Create or edit ~/.claude/CLAUDE.md:
- Always respond in English, even when questions are asked in other languages.
- Use the gh CLI for all GitHub operations (repos, PRs, issues).
- When my instructions are unclear or conflicting, stop and ask for clarification instead of guessing.
- Never override or skip my instructions without asking first.
- Always ask for confirmation before making git commits, unless I explicitly tell you to commit.
- Respond in English -- I work in multilingual environments but want consistent English responses.
- Use gh CLI -- Ensures Claude uses
ghfor all GitHub operations, which works with private repos via my authenticated session. - Ask for clarification -- Prevents Claude from guessing when instructions are ambiguous. Better to stop and ask than go in the wrong direction.
- Don't override my instructions -- Claude sometimes decides it knows better and skips what you asked. This keeps it in check.
- Confirm before committing -- I want to review changes before any git commit happens, unless I explicitly tell Claude to commit.
| File Location | Scope |
|---|---|
~/.claude/CLAUDE.md |
Global -- all projects |
project-root/CLAUDE.md |
Project -- shared with team via git |
project-root/CLAUDE.local.md |
Local -- auto-gitignored, private to you |
You can also create a CLAUDE.md with /init inside a project directory.
Official docs: https://code.claude.com/docs/en/cli-reference
claude --continue
claude -c
claude --resume
claude -r
claude -r "auth-refactor"
Tip: Name your sessions with /rename my-feature so they're easy to find later.
claude -p "explain what this regex does: ^[a-z]+$"
cat error.log | claude -p "explain these errors"
claude --model opus
claude --model sonnet
| Flag | What It Does |
|---|---|
--continue ,-c |
Resume most recent conversation |
--resume ,-r |
Pick a previous conversation to resume |
--print ,-p |
Non-interactive mode (prints answer and exits) |
--model |
Choose model ( sonnet ,opus , or full model ID) |
--verbose |
Show detailed turn-by-turn output |
--chrome |
Enable browser automation |
--add-dir ../other-project |
Add extra directories as context |
--max-turns N |
Limit number of agentic turns (print mode) |
--allowedTools "Bash(npm test)" |
Pre-allow specific tools |
--append-system-prompt "..." |
Add custom instructions for the session |
Official docs: https://code.claude.com/docs/en/interactive-mode
| Command | What It Does |
|---|---|
/help |
Show all commands |
/compact |
Compress conversation to free up context |
/context |
Visualize how much context is used |
/cost |
Show token usage and costs |
/stats |
View usage statistics |
/model |
Switch models mid-session |
/memory |
Edit your CLAUDE.md |
/rename name |
Name the current session |
/resume |
Resume a previous session |
/mcp |
Manage MCP server connections |
/doctor |
Check installation health |
/chrome |
Manage Chrome integration |
| Shortcut | Action |
|---|---|
Shift+Tab |
Toggle permission modes (Auto-Accept / Plan / Normal) |
Ctrl+G |
Open prompt in your text editor |
Ctrl+V |
Paste an image from clipboard |
Esc +Esc |
Rewind to a previous point in conversation |
\ +Enter |
Multiline input |
!command |
Run a bash command directly (e.g., !git status ) |
@path |
Reference a file with autocomplete |
Run /terminal-setup once to enable additional shortcuts like Option+T (toggle thinking) and Shift+Enter (multiline).
A few things I've picked up that make the day-to-day experience smoother.
You can interrupt Claude at any time with two different keys:
| Keystroke | What It Does |
|---|---|
Esc |
Stops Claude mid-action. Context is preserved so you can redirect with a follow-up prompt. Also dismisses autocomplete menus, permission dialogs, and other UI elements depending on context. |
Ctrl+C |
Standard interrupt. Cancels the current generation or input. If pressed at an empty prompt, it exits the session (same as Ctrl+D ). |
In practice, Esc is the one you'll use most -- it cleanly stops Claude and lets you course-correct. Ctrl+C is the heavier hammer.
Pressing Esc twice opens the rewind menu, which lets you restore code and/or conversation to a previous point (see the keyboard shortcuts table above).
Ctrl+C is handy for discarding what you've typed before sending it, but be careful: if Claude is actively running, Ctrl+C will interrupt the execution instead of just clearing your text. Safer alternatives:
| Shortcut | What It Does |
|---|---|
Ctrl+U |
Deletes the entire line. Pure text editing -- will never interrupt Claude. You can recover the deleted text with Ctrl+Y . |
Ctrl+K |
Deletes from the cursor to the end of the line. Also safe during generation. |
Ctrl+S |
Stashes your current prompt for later instead of discarding it. |
Tip: Build the habit of using Ctrl+U instead of Ctrl+C to clear your input. It's always safe regardless of whether Claude is running or not.
Claude Code can read images when you give it a file path. On macOS, take a screenshot with Cmd+Shift+4 (saves to Desktop by default), then get the path to Claude:
Option A: Drag and drop (terminal only) Drag the screenshot file from Finder straight into the terminal. It pastes the full path for you -- fewest clicks.
Option B: Copy path and paste
Select the file in Finder, press Cmd+Opt+C to copy its full path, then paste it into Claude.
Either way, Claude recognizes it as an image and reads it visually. Really handy for sharing error dialogs, UI bugs, or design mockups.
Note: Drag and drop only works when running Claude Code in a terminal. If you're using Claude inside an IDE like VS Code or IntelliJ, use Option B instead.
Official docs: https://code.claude.com/docs/en/vs-code
If you're using Claude Code in VS Code or Cursor, the default experience is a chat panel that feels a lot like ChatGPT. It works, but it only gives you a subset of what Claude Code can do. I'd recommend switching to terminal mode, which runs the full CLI inside your IDE and unlocks everything in this guide.
Add this to your VS Code settings (Cmd+, → search "Claude Code"):
{
"claudeCode.useTerminal": true§
}
This replaces the chat panel with the full CLI running in your IDE's integrated terminal. You still get IDE features like native diff viewing and selection context sharing, but now with the complete set of commands and shortcuts.
JetBrains already works this way by default -- the Claude Code plugin is just a connector that runs claude in the integrated terminal. No setting to change.
The chat panel only exposes a subset of features. Terminal mode gives you everything:
| Feature | Chat Panel | Terminal Mode |
|---|---|---|
| Slash commands | Partial subset | All commands |
| Keyboard shortcuts | Limited | Full set (vim mode, history search, etc.) |
| Status line | Not supported | Fully customizable |
! bash shortcut |
Not available | !git status runs inline |
| Tab completion | Not available | Full autocomplete |
| MCP configuration | Must use CLI | Direct setup |
Once you switch, run /terminal-setup inside a Claude Code session to configure Shift+Enter for multi-line prompts.
One thing I use all the time: select some lines in your editor and press the shortcut to insert an @file.ts#5-10 reference directly into the Claude prompt with the file path and line numbers. No need to copy-paste code.
| IDE | Shortcut |
|---|---|
| VS Code / Cursor | Option+K (Mac) /Alt+K (Windows/Linux) |
| JetBrains (IntelliJ, RubyMine, etc.) | Cmd+Option+K (Mac) /Alt+Ctrl+K (Windows/Linux) |
You can also type @ followed by a filename for manual references with fuzzy matching.
On top of that, Claude automatically sees whatever you have selected in the editor -- there's a small indicator in the prompt box footer showing how many lines are highlighted. No shortcut needed for that, it just works in the background.
Here's the complete ~/.claude/settings.json with all the settings described above:
{
"attribution": {
"commit": "",
"pr": ""
},
"permissions": {
"allow": [
"Bash(rbenv:*)",
"Bash(ruby:*)",
"Bash(bundle:*)",
"Bash(gem:*)",
"Bash(rspec:*)",
"Bash(find:*)",
"Bash(cat:*)",
"Bash(gh:*)",
"Bash(ls:*)",
"Read(~/.zshrc)",
"Read(~/projects/src/intellum/dev-context-docs/**)",
"Write(~/projects/src/intellum/dev-context-docs/**)",
"Edit(~/projects/src/intellum/dev-context-docs/**)"
],
"deny": [
"Read(./secrets/**)"
]
},
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Hero.aiff &"
}
]
}
],
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Hero.aiff &"
}
]
}
]
},
"statusLine": {
"type": "command",
"command": "npx @owloops/claude-powerline@latest"
}
}
That's it! This is the setup that works for me day-to-day. Claude Code evolves quickly, so some of this might be outdated by the time you read it -- when in doubt, the official docs are always the best reference. If you spot anything wrong or have suggestions, I'd love to hear them.