--- If you've ever wished you could describe what you want to build and have an AI agent figure out how to implement it across your entire codebase, Claude Code is that tool. It's an agentic coding assistant from Anthropic that lives in your terminal, understands your project structure, and can read files, write code, run tests, open pull requests, and trigger production deployments — all through natural language. Unlike chat-based AI assistants where you copy and paste code snippets back and forth, Claude Code operates directly inside your development environment. It sees your files, understands the relationships between them, and executes real changes. That makes it significantly more powerful for real-world web development — but it also requires a different mental model than a chat box, and a real plan for what happens once Claude's changes land on `main`. This guide covers system requirements, installation on macOS, Linux, and Windows, configuration, the daily workflow patterns Anthropic's own teams use, and — critically — how to wire Claude Code into a [Git deployment automation](https://www.deployhq.com/features/automatic-deployments) pipeline so that the code Claude writes ships to production the same day. --- ## Why Claude Code Matters for Web Developers Traditional AI coding assistants work in isolation. You describe a problem, get a code snippet, paste it into your editor, then manually handle all the integration work — imports, dependencies, related files that need updating. The context-switching slows you down and introduces errors. Claude Code flips this model. When you ask it to add a feature or fix a bug, it searches your codebase to understand the existing patterns, identifies all the files that need to change, makes the edits, and runs your tests to verify the changes work. You stay in flow while Claude handles the implementation details. For web developers specifically, that means you can describe features at a higher level. Instead of writing out the exact controller method, view template, and route configuration, you can say *"add a user profile page that shows their recent orders"* and let Claude figure out how that fits into your existing application architecture — Rails service objects, Laravel form requests, Next.js server actions, whatever you already use. The same logic applies on the way out. Once Claude has shipped a commit, an [automated deployment tool](https://www.deployhq.com/features/build-pipelines) can pick the change up, build it, and push it to production. That second half is where most Claude Code tutorials stop — and where Step 8 of this guide picks up. --- ## Step 1: System Requirements Before installing Claude Code, confirm your system meets the official requirements published by Anthropic. These are the most-searched details for this tool, so they belong up front. **Operating Systems** - macOS 10.15 (Catalina) or higher - Ubuntu 20.04+, Debian 10+, or any modern Linux distribution with glibc 2.31+ - Windows 10 or 11 (native, or via WSL 2 / Git Bash) **Hardware (minimum vs. recommended)** | Resource | Minimum | Recommended | |----------|---------|-------------| | RAM | 4 GB | 8 GB+ for monorepos and large Rails/Next.js codebases | | Disk | ~500 MB for the CLI itself | 2 GB free for cache, logs, and `.claude/` artifacts | | CPU | Any 64-bit x86_64 or Apple Silicon | M-series or Ryzen 5+ for parallel sub-agent workflows | **Software** - Node.js 18 or higher *(only required for the npm install path — the native installer ships its own runtime)* - A modern terminal: Bash, Zsh, Fish, or PowerShell 7+ **Network** - Active internet connection. Authentication tokens and model inference both round-trip to Anthropic. Air-gapped use is not supported today. --- ## Step 2: Install Claude Code Claude Code offers two installation methods: the native installer (recommended) and npm. Pick the one that matches your toolchain. ### Option A: Native installer (recommended) The native installer doesn't require Node.js and includes automatic updates. **macOS and Linux:** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` To pin a specific version: ```bash curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58 ``` **Windows (PowerShell):** Native Windows installation is now supported. Open PowerShell and follow the prompts at `claude.ai/download`, or run the installer inside WSL 2 if you want full Unix tool parity (recommended for projects with `Makefile`, `bash` scripts, or POSIX-only build steps). ### Option B: NPM installation If you prefer npm or need fine-grained control: ```bash npm install -g @anthropic-ai/claude-code ``` **Do not use `sudo` with `npm install`.** Sudo-installed Node globals are a well-known footgun and break `npm update`. Configure a user-level npm prefix instead: ```bash mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc ``` Then retry the install. ### Verify ```bash claude --version ``` You should see a version number printed cleanly — no Python errors, no `EACCES` permission warnings. --- ## Step 3: Configure Authentication Claude Code requires authentication to reach Claude's API. You have two options. ### Option A: Claude Console (recommended) Simplest path for most developers: 1. Navigate to your project directory 2. Run `claude` 3. Follow the OAuth prompts to connect through the Claude Console 4. Complete authentication in your browser A "Claude Code" workspace is created automatically in your console for usage tracking and per-project spend limits. ### Option B: API key If you prefer a raw API key (useful for CI/CD or shared dev containers): 1. Visit `console.anthropic.com` 2. Generate an API key (it begins with `sk-`) 3. Export it: ```bash export ANTHROPIC_API_KEY="sk-your-api-key-here" ``` Persist it by appending the same line to `~/.zshrc` or `~/.bashrc`. For CI runners, store it as a masked secret in your provider's secret manager — never commit it to the repo, and never paste it into `.env` files that ship in Docker images. ### Understanding Costs Claude Code charges based on API usage and that bill can climb fast on complex agentic tasks — large refactors, long planning sessions, and chatty TDD loops are the usual culprits. If you run Claude Code daily, a **Claude Max** subscription gives you higher usage limits at a fixed monthly cost, which most heavy users land on after their first usage-based bill. For predictable team budgets, scope what Claude can do per session with the `--allowedTools` flag (covered in Step 5) so a runaway agent can't burn tokens on a misunderstood ticket. --- ## Step 4: Start Using Claude Code Once Claude Code is installed, here's how to use it productively day to day. ### Basic Workflow ```bash cd your-project claude ``` You enter an interactive session. Type natural language requests; Claude analyzes the codebase and takes action. ### Example Tasks **Understand a codebase:** ``` What does this project do? Explain the main architecture. ``` **Add a feature:** ``` Add a user settings page where users can update their email and password. Follow the existing patterns in this codebase. ``` **Fix a bug:** ``` Users report the checkout page crashes when their cart is empty. Find and fix this bug. ``` **Refactor code:** ``` Refactor UserController to use service objects instead of putting business logic in the controller. ``` **Write tests:** ``` Write unit tests for OrderProcessor covering the main success and failure paths. ``` ### Thinking Modes Claude Code supports tiered "thinking" levels for harder problems. The trigger phrases bias the model toward more deliberation before acting: - `think` — Standard extended thinking - `think hard` — More thorough analysis - `think harder` — Deeper consideration - `ultrathink` — Maximum thinking budget for the most complex problems Example: ``` Think hard about how to add rate limiting across all API endpoints without breaking the public webhook contract. ``` --- ## Step 5: Advanced Features ### Slash Commands Built-in commands available in any session: - `/help` — Show available commands - `/clear` — Clear the conversation context - `/bug` — Report an issue to Anthropic - `/compact` — Condense conversation history when you get near the context limit ### Custom Commands Store reusable prompt templates as Markdown files in `.claude/commands/`: ```bash mkdir -p .claude/commands ``` Create `.claude/commands/review.md`: ```markdown Review the most recent changes for: - Security vulnerabilities - Performance issues - Code style consistency - Missing tests Provide specific, actionable feedback. ``` Invoke it with `/review` in any session in that project. ### MCP Server Integration Claude Code can connect to MCP (Model Context Protocol) servers to extend its capabilities. Add entries to `.mcp.json` at the project root: ```json { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] } } } ``` This wires in [Context7 for up-to-date library documentation](https://www.deployhq.com/guides/context7) so Claude stops citing API signatures that changed two major versions ago. The same `.mcp.json` slot accepts Puppeteer (browser automation), database servers, and your own internal tools. For a curated list, see our [roundup of the best MCP servers for AI coding assistants](https://www.deployhq.com/blog/best-mcp-servers-for-web-developers). ### Headless Mode for CI/CD Claude Code can run non-interactively in CI pipelines or GitHub Actions runners: ```bash claude -p "Run the test suite and fix any failing tests" \ --allowedTools Edit,Bash ``` The `-p` flag passes a single prompt and exits. `--allowedTools` restricts which tools Claude can use — pair it with a tightly scoped IAM role on the runner so an agent can't, for example, force-push to `main`. For a deeper walkthrough comparing headless Claude Code, Codex CLI, and Gemini CLI side by side, see our guide to [running AI coding agents in CI/CD pipelines](https://www.deployhq.com/blog/running-ai-coding-agents-cicd-headless-mode-claude-code-codex-gemini). ### Cutting the Token Bill The single biggest knob is context size. Use `/clear` between unrelated tasks, `/compact` before deep dives, and keep a tight `CLAUDE.md` in the repo root so Claude doesn't re-read the same conventions every session. We collected six community repos that reliably bring monthly spend down in our writeup on [free GitHub repos that cut your Claude Code token bill](https://www.deployhq.com/blog/free-github-repos-for-claude-code). --- ## Step 6: Best Practices for Effective Use These patterns come from Anthropic's internal teams and developers shipping with Claude Code in production. ### Research → Plan → Implement Don't lead with "write the code." Lead with research: 1. Ask Claude to investigate the codebase and identify relevant patterns 2. Ask for a written plan of the changes it intends to make 3. Approve the plan, then ask for implementation 4. Ask for tests and documentation last This three-step pattern measurably reduces "Claude rewrote the whole file" surprises on non-trivial features. ### Use Test-Driven Development TDD is unusually well-suited to agentic coding. The tests act as a verifiable contract Claude can self-check against: 1. Ask Claude to write tests based on expected behavior 2. Have it commit the failing tests 3. Ask it to implement code until the tests pass 4. Review the diff ### Be Specific About Constraints If you have opinions about implementation, state them: ``` Add pagination to the products list. Use Kaminari since that's what we use elsewhere. Keep existing filtering and sorting working. ``` ### Let Claude Verify Its Work After changes: ``` Run the tests for the files you just modified and confirm they pass. ``` Or: ``` Run our linter on the changed files and fix any violations. ``` ### Use Sub-Agents for Hard Problems For the genuinely tricky stuff, ask Claude to spawn sub-agents and parallelize the investigation: ``` Research three different ways we could implement Redis-backed caching for our API responses. Investigate each approach in parallel, then summarize the tradeoffs and recommend one. ``` ### Compare Before You Commit Claude Code isn't the only agentic CLI in town. For a side-by-side feature/cost comparison with the two main alternatives, see our breakdown of [Claude Code vs Codex CLI vs Gemini CLI](https://www.deployhq.com/blog/comparing-claude-code-openai-codex-and-google-gemini-cli-which-ai-coding-assistant-is-right-for-your-deployment-workflow) — or, if you're evaluating an in-editor agent instead, check the [Cursor setup guide](https://www.deployhq.com/guides/cursor), the [Aider workflow guide](https://www.deployhq.com/guides/aider), and the [Cline for VS Code setup](https://www.deployhq.com/guides/cline). --- ## Step 7: IDE Integration Claude Code is terminal-first, but it integrates with the editors most developers spend their day in. ### VS Code Extension Install the Claude Code extension from the VS Code marketplace. It surfaces Claude's changes as visual diffs in a sidebar while the terminal session keeps running underneath. ### Cursor and Windsurf Both are VS Code forks, so the same extension works. Install it from the extensions marketplace as you would in vanilla VS Code. ### JetBrains IDEs Native extensions are available for IntelliJ IDEA, WebStorm, RubyMine, PyCharm, and the other JetBrains IDEs. Search for "Claude Code" in the plugin marketplace. ### Git Attribution When Claude commits on your behalf, the resulting commits include a `Co-Authored-By: Claude` trailer by default. That's deliberate — it preserves traceability for code review, security audits, and license reviews. If you're new to mixing AI-authored commits into your Git history, read our walkthrough on [how to use Git with Claude Code, including the Co-Authored-By attribution](https://www.deployhq.com/blog/how-to-use-git-with-claude-code-understanding-the-co-authored-by-attribution). --- ## Step 8: Deploy Claude Code Changes to Production with DeployHQ This is where most Claude Code guides stop and where shipping engineers actually start. Claude wrote the feature, you reviewed the diff, you merged the PR. Now it needs to be live on staging in under five minutes and in production within the hour. That's a deployment pipeline, not a `git push`. [DeployHQ automates the path from Git to your servers](https://www.deployhq.com/deploy-from-github), which makes it a natural pairing for an agentic workflow that's already producing several commits per hour. ### Why Claude Code + DeployHQ Works Claude Code operates on your local checkout and produces real commits and pull requests. The moment those changes land on your main or release branch, DeployHQ: 1. Detects the push 2. Runs your build pipeline (e.g., `npm run build`, `bundle install`, `composer install`, asset compilation) 3. Transfers only changed files over SFTP/SSH/Rsync/S3 4. Performs a [zero-downtime deployment](https://www.deployhq.com/features/zero-downtime-deployments) using atomic symlink swaps 5. Surfaces a [one-click rollback](https://www.deployhq.com/features/one-click-rollback) button on the dashboard if anything is wrong The reason this compounds: Claude Code dramatically reduces the time to *write* a change, but a slow or fragile deploy step is now the bottleneck. Removing that bottleneck is what a deployment automation platform is for. ### Setting Up the Pipeline (Five Steps) 1. **Create a DeployHQ project** and connect it to your GitHub, GitLab, or Bitbucket repo. [Sign up free for DeployHQ](https://www.deployhq.com/signup) — the free tier covers most solo and small-team projects. 2. **Add a server** with your hosting details (SFTP, SSH, Rsync, S3, or an Atomic SSH server for symlink-based deploys). 3. **Enable automatic deployments** so a push to `main` triggers a production deploy and a push to `staging` triggers a staging deploy. 4. **Configure a [build pipeline](https://www.deployhq.com/support/build-pipelines)** if your project needs compilation — `npm run build`, `composer install --no-dev`, `bundle install --deployment`, etc. Build artifacts are cached between deploys to keep cold-start times under control. 5. **Add post-deploy SSH commands** to run database migrations, restart workers, warm caches, or ping a Slack channel. ### The Full Workflow Here's the end-to-end loop, exactly as it runs in real projects: ```bash # Open Claude Code in your project cd my-rails-app claude # Describe the feature > Add a webhook endpoint at /webhooks/stripe that receives Stripe payment > events, verifies the signature with STRIPE_WEBHOOK_SECRET, and updates > order.payment_status. Follow the existing controller patterns. # Claude reads the codebase, edits the routes, controller, service object, # and adds a model concern. # Ask Claude to write the tests > Write request specs for /webhooks/stripe covering successful payment, > failed payment, invalid signature, and replay attacks. # Claude writes RSpec specs. You run them, they pass. # Ask Claude to commit > Commit these changes with a descriptive message and the > Co-Authored-By trailer. # Push git push origin main # DeployHQ takes over: # 1. Detects the push (typically <5s) # 2. Runs bundle install + assets:precompile in a build container # 3. SFTPs only changed files to your server # 4. Atomically swaps the release symlink # 5. Runs rails db:migrate as a post-deploy SSH command # 6. Posts to #deploys on Slack ``` End-to-end: idea → production in single-digit minutes. ### Headless Claude Code + DeployHQ in CI For teams running fully agentic CI (a GitHub issue closes itself when an agent ships the fix), pair Claude Code's headless mode with DeployHQ webhooks. Your GitHub Action runs: ```bash claude -p "$ISSUE_BODY" \ --allowedTools Edit,Bash \ --output-format stream-json > claude.log git push origin "fix/issue-${ISSUE_NUMBER}" ``` Open the PR, your humans review the diff, merge to `main`, and DeployHQ deploys. The same headless pattern is the foundation behind what we built at [DeployHQ Agents — deploy from your terminal or let your AI agent do it](https://www.deployhq.com/agents). For a deeper dive — including how to chain Claude Code with the DeployHQ API to trigger deploys from inside a Claude session — read our writeup on [automating deployments with Claude Code and the DeployHQ API](https://www.deployhq.com/blog/effortless-automation-prompting-your-way-to-deployment-with-claude-code-and-deployhq). --- ## Step 9: Troubleshooting ### "Command not found" after installation Add the install directory to your `PATH`: ```bash echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` If you used the native installer, the binary lives at `~/.claude/bin/claude` — confirm that path is in your `PATH` and restart your terminal. ### Permission errors during npm install Never use `sudo`. Configure a user-level npm prefix as shown in Step 2. ### Authentication failures Run `claude doctor`. It auto-detects most config problems (expired tokens, missing env vars, clock skew) and suggests fixes. If `claude doctor` reports a token issue, generate a fresh API key in the console and re-export it. ### High API costs Three levers, in order of impact: 1. **Switch to Claude Max** if you're consistently hitting usage-based limits — fixed monthly cost is easier to budget than per-call billing on long sessions. 2. **Restrict the toolset** per session with `--allowedTools Edit` (no Bash) or `--allowedTools Read` (read-only) when you want analysis, not action. 3. **Tighten your `CLAUDE.md`** so Claude doesn't waste tokens re-discovering project conventions every run. ### Claude breaks something on push This is exactly the case the rollback button is built for. Roll back from the DeployHQ dashboard in seconds while you and Claude figure out what went wrong, then redeploy the corrected commit. ### Getting Help - Use `/bug` inside Claude Code to report issues directly to Anthropic - Join the Claude Developers Discord for community support - File issues on the public Anthropic GitHub repos --- ## Conclusion Claude Code is a shift in how developers interact with AI assistants. Instead of a chat window where you exchange code snippets, it's an agent that operates directly in your development environment — reading your codebase, executing real changes, and producing real commits. The learning curve is about thinking in goals rather than implementations. Instead of writing the code yourself and asking the AI to review it, you describe what you want and let Claude figure out how to achieve it within your existing patterns. Paired with the deployment pipeline in Step 8, that loop closes. You describe features in natural language, Claude implements them following your existing patterns, your tests verify them, and DeployHQ ships them. The full loop — idea to production — runs in minutes, not days. Start small: bug fixes, test writing, code explanation. As your intuition for how Claude thinks about your codebase develops, the size of the changes you trust it with will grow. The deploy pipeline you set up once will quietly carry every one of those changes to production. --- *Ready to put this into practice?* Install Claude Code with the steps above, then create your DeployHQ project and connect it to the repo you're working in. The first deploy takes about ten minutes to configure. Every Claude-authored commit after that ships automatically. Questions about pricing tiers or what's included on the free plan are answered on the [DeployHQ pricing page](https://www.deployhq.com/pricing).