Claude Code: Complete Beginner's Guide

Claude Code is Anthropic's command-line AI agent. Unlike browser-based AI assistants, it runs directly in your terminal, can read and write files on your computer, execute commands, and complete complex multi-step tasks from a single prompt. If you have used ChatGPT or Claude in a browser, Claude Code is the next level: an AI that does not just tell you what to do, but does it.

This guide walks you through installation, basic usage, practical examples, and tips for getting the best results.

What Makes Claude Code Different

Most AI tools operate in a browser window. You paste code in, get code back, and then manually copy it into your project. Claude Code eliminates that friction entirely. It runs where your code lives, in the terminal, inside your project directory.

When you give Claude Code a task, it can:

• Read any file in your project to understand the existing code
• Search across your entire codebase for relevant patterns
• Write new files or edit existing ones
• Run shell commands (install packages, run tests, start servers)
• Observe the output of those commands and adjust its approach
• Repeat this cycle until the task is complete

This means you can say "add dark mode to this app" and Claude Code will find the relevant style files, understand the existing theme system, add the toggle logic, update the CSS, and test that it works. You describe the goal; it handles the execution.

Installation

Claude Code requires Node.js 18 or later. If you do not have Node.js installed, download it from nodejs.org or use a version manager like nvm.

Step 1: Install the Package

npm install -g @anthropic-ai/claude-code

This installs Claude Code globally so you can run it from any directory.

Step 2: Set Up Your API Key

Claude Code uses the Anthropic API, which requires an API key. Sign up at console.anthropic.com if you do not have an account, then create an API key in the dashboard.

Set the key as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

To make this permanent, add the export line to your shell profile (~/.bashrc, ~/.zshrc, or equivalent).

Step 3: Verify Installation

claude --version

If you see a version number, you are ready to go.

Basic Usage

Navigate to a project directory (or any directory where you want to work) and run:

claude

This opens an interactive session. You type prompts, and Claude Code responds with text, code, and actions. It will ask for permission before writing files or running commands, so you stay in control.

Your First Prompt

Start with something simple:

Claude Code will create the file, write the HTML, and save it. You will see exactly what it is doing at each step, and it will ask you to confirm before writing the file.

Working with Existing Projects

Claude Code becomes more powerful when you use it inside an existing project. Navigate to a project directory and start a session:

cd ~/projects/my-app
claude

Now you can ask questions about the code ("What does the auth middleware do?"), request changes ("Add rate limiting to the /api/login endpoint"), or ask it to fix problems ("The tests in user.test.ts are failing, fix them").

Claude Code reads files as needed. You do not need to paste code into the prompt. It can search your project, find the relevant files, read them, and understand the context before making changes.

One-Shot Commands

For quick tasks, you can pass the prompt directly without entering interactive mode:

claude "Add a .gitignore file for a Node.js project"

This runs the task and exits. Useful for scripting or quick fixes.

Practical Examples

Building a Website from Scratch

Claude Code creates the directory structure, writes HTML, CSS, and any JavaScript needed, and produces a complete, working website. You can open the index.html file in a browser immediately to see the result.

Fixing Bugs

Claude Code reads the component, traces the click handler, identifies why it is not working (maybe the handler is not bound, or the API call is missing an await), and fixes it. If there is a related test file, it may update that too.

Refactoring Code

Claude Code analyzes the file, identifies logical groupings, creates new files for each group, moves the code, and updates every import statement in the project that referenced the old file. This is a task that would take a developer 30-60 minutes of careful, tedious work. Claude Code handles it in under a minute.

Adding Features

Claude Code finds the header component, adds the toggle button, creates the theme switching logic, updates the CSS to support both themes, and adds localStorage persistence. It reads the existing code first, so the new feature matches the existing patterns and style.

Deploying with Claude Code

One of the most satisfying things you can do with Claude Code is go from idea to live website in a single session. After building a site, you can ask it to deploy directly.

If you are using a hosting service with an API, Claude Code can read the API documentation and handle the deployment. For example, with AccessAgent.ai, the workflow is:

Claude Code reads the API documentation, zips the files, sends the upload request, and returns the live URL. The site is live in seconds. For future updates, you give it the secret key and describe the changes, and it handles both the code update and the redeployment.

AccessAgent.ai's API was built for AI agents — your agent reads the guide, handles the upload, and returns a live URL. No dashboard, no browser needed.

Tips for Getting Better Results

Be Specific About What You Want

Vague prompts get vague results. Instead of "make the page look better," try "increase the spacing between sections to 48px, make the headings larger at 2rem, and add a subtle bottom border to the header." The more specific you are, the closer the output matches your vision.

Provide Context

If you have design preferences, mention them. "I want a dark theme with a navy background, white text, and blue accent colors" gives Claude Code much more to work with than "make it dark." Reference existing pages or styles if you want consistency: "Match the style of the existing dashboard page."

Use Iterative Prompts

You do not have to get everything right in one prompt. Start with the structure, review it, then refine. "Now make the hero section taller and add a gradient background." This iterative approach often produces better results than trying to specify everything upfront.

Review Before Approving

Claude Code asks for permission before writing files. Use this as a checkpoint. Read the proposed changes. If something looks off, reject the change and provide more specific guidance. It is much easier to correct course before the file is written than after.

Use the CLAUDE.md File

For ongoing projects, create a CLAUDE.md file in your project root. Claude Code reads this file automatically at the start of each session. Use it to document your project's conventions, tech stack, coding standards, and any patterns you want Claude Code to follow. This is effectively a persistent set of instructions that shapes every interaction.

Break Large Tasks into Steps

For complex projects, break the work into phases. Instead of "build me a full e-commerce site," start with "create the product listing page with a grid layout" and build from there. Each prompt can build on the results of the previous one, and you maintain more control over the direction.

Common Issues and Solutions

Claude Code Is Not Seeing My Files

Make sure you are running claude from the correct directory. Claude Code uses your current working directory as its project root. Run pwd to confirm you are where you think you are.

Changes Are Not What I Expected

If Claude Code makes changes that miss the mark, do not just say "that's wrong." Explain specifically what you expected and how the result differs. "The button should be blue (#3b82f6), but you used green" is much more actionable than "fix the button."

API Key Issues

If you see authentication errors, verify your API key is set correctly: echo $ANTHROPIC_API_KEY should show your key. Make sure there are no extra spaces or newlines in the value. If the key is set in your shell profile, open a new terminal after editing.

Permission Errors

If Claude Code cannot write files, check directory permissions. On macOS, you may need to grant terminal access in System Preferences. On Linux, ensure your user owns the project directory.

What Comes Next

Once you are comfortable with the basics, explore more advanced workflows. Use Claude Code to write tests for your code, set up CI/CD pipelines, manage infrastructure configuration, or even analyze logs and debug production issues. The key insight is that anything you can do in a terminal, Claude Code can do too, and usually faster.

The best way to learn is to use it on a real project. Pick something you have been putting off, a personal site, a utility script, a feature for an existing project, and let Claude Code help you build it.