My Claude Code Setup Guide

A developer published a step-by-step guide for installing and configuring Claude Code on macOS, covering the curl and Homebrew install paths, GitHub CLI authentication, and connecting the Atlassian Rovo MCP server for Jira and Confluence access. The setup also includes a vim-style powerline status bar via the claude-powerline package to display git info, token usage, session cost, and model name.

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 https://code.claude.com/docs/en/overview or let me know. Official docs: https://code.claude.com/docs/en/setup 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 Check it installed correctly claude --version Run a health check claude doctor Start Claude Code and log in claude /login Follow the prompts to authenticate with your Claude Pro, Max, Team, or Enterprise account. Official docs: https://cli.github.com/ 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 or SSH 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/ 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: Available across all your projects user-level claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp --scope user Shared with your team via .mcp.json project-level claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp --scope project 1. Start Claude Code with claude 2. Run /mcp to see MCP servers 3. 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 https://code.claude.com/docs/en/statusline Package: https://github.com/Owloops/claude-powerline 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 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 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 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: allows gh 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 . - deny always wins -- Deny rules are evaluated first, so Read ./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 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 1. Go to the Chrome Web Store https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn 2. Click Add to Chrome 3. Sign in with your Claude account 4. Pin the extension click the puzzle piece icon in Chrome toolbar, then the pin Start Claude Code with Chrome enabled 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 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 gh for 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 https://code.claude.com/docs/en/cli-reference Continue the most recent conversation claude --continue or claude -c Pick a conversation to resume interactive picker claude --resume or claude -r Resume a specific named session claude -r "auth-refactor" Tip: Name your sessions with /rename my-feature so they're easy to find later. Ask a question and get the answer printed non-interactive claude -p "explain what this regex does: ^ a-z +$" Pipe content into Claude cat error.log | claude -p "explain these errors" Use a specific model 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 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 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 https://plugins.jetbrains.com/plugin/27310-claude-code-beta- 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 https://code.claude.com/docs/en/overview are always the best reference. If you spot anything wrong or have suggestions, I'd love to hear them.