Claude Code Tutorial: Setting Up Anthropic's CLI Agent for Local Refactoring

Anthropic has shifted the AI developer wars directly to the command line.

While code editors like Cursor and extensions like Cline have integrated AI into the IDE, Anthropic's official Claude Code CLI operates directly inside your terminal.

Claude Code is an agentic command-line tool that can write, search, run, and test code on your local machine. Because it lives in the terminal, it has direct access to git, your compiler, package managers, and test suites. It doesn't just suggest edits — it runs your test commands, looks at the console failures, and iteratively edits your files until your tests pass.

Here is a complete setup and optimization tutorial to get you up and running with Claude Code.

Prerequisites

Before installing Claude Code, ensure you have:

1. Node.js 18+ installed on your system.
2. An active Claude Pro subscription, Team/Enterprise seat, or an Anthropic Console (API) account with billing configured. (Note: Claude Code is not available on Anthropic's free tier).
3. Git installed and initialized in your target project directory.

Step 1: Install Claude Code

Claude Code can be installed using several methods depending on your operating system.

Option A: Native Installer (Recommended)

The native installer script manages all paths and dependencies automatically.

• macOS, Linux, or WSL (Windows Subsystem for Linux):

  curl -fsSL https://claude.ai/install.sh | bash
  

  Copy Snippet

• Windows (PowerShell - run as Administrator):

  irm https://claude.ai/install.ps1 | iex
  

  Copy Snippet

• Windows (Command Prompt):

  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  

  Copy Snippet

Option B: npm Global Installation

If you prefer standard JavaScript package managers, install it globally using npm:

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

Option C: Homebrew (macOS)

If you use Homebrew, tap and install the cask:

brew install --cask claude-code

Step 2: Authenticate Your Session

Once installed, navigate to the root folder of the project you want to work on:

cd /path/to/your/project

Initialize Claude Code by running:

claude

The CLI will generate a unique authentication link and display it in the terminal:

Login required. Please open this URL in your browser:
https://claude.ai/login-cli?code=XXXX-XXXX

1. Open the link in your browser.
2. Log in to your Anthropic account (the one associated with your Claude Pro or Console billing).
3. Approve the CLI connection.
4. Return to your terminal. Claude Code will sync and show an active agent prompt.

Step 3: Core Commands & Interactions

When inside the claude prompt, you can talk to the agent in natural language or use terminal slash commands.

Key Slash Commands

Step 4: Practical Guide: Local Codebase Refactoring

Let's look at three practical scenarios where Claude Code outclasses browser-based AI chats.

Scenario 1: Bulk API Route Refactoring

Suppose you need to upgrade all your API routes from Next.js Pages router format to Next.js App Router route handlers.

Your Prompt:

"Find all files in /pages/api and refactor them into Next.js App Router route handlers inside /app/api/route/route.ts. Ensure you retain TypeScript type safety and error responses."

What Claude Code Does:

1. Runs find or searches the codebase to identify files under /pages/api.
2. Creates the new directories under /app/api.
3. Translates Page API structure (e.g. req: NextApiRequest, res: NextApiResponse) into route handler standard syntax (request: Request).
4. Deletes the old deprecated files (if requested) or moves them to an archive.
5. Shows you a unified git diff for review.

Scenario 2: Test-Driven Bug Fixing

One of the most powerful workflows in Claude Code is its ability to run local scripts and respond to console output.

Your Prompt:

"Run the test suite using pnpm test. If there are any failing tests, read the failing test files and the associated source code, modify the codebase until the tests pass, and verify by re-running the tests."

What Claude Code Does:

1. Executes pnpm test in a local sub-process.
2. Reads the stderr output containing the trace of the failing tests.
3. Opens the offending files and diagnoses the logical bug.
4. Makes file modifications.
5. Re-runs pnpm test to verify success, repeating the cycle if other tests fail.

Scenario 3: Clean Commit Generation

When you are ready to save your work, Claude can write structural commits.

Your Prompt:

"Analyze the current git diff of my unstaged changes, write a clean, semantic commit message following Conventional Commits, stage the changes, and commit them."

What Claude Code Does:

1. Runs git diff to see what has changed.
2. Creates a message like feat(auth): integrate Supabase session checks in middleware.
3. Runs git add . and git commit -m "message".

Best Practices for Token Optimization

Because Claude Code operates using the Anthropic API (or your Pro account limits), it can consume token limits quickly if not managed.

1. Use .claudeignore: Create a .claudeignore file in your project root. Add folders like node_modules, .next, dist, build artifacts, and large assets (PNGs, PDFs) to prevent Claude from indexing non-code files and wasting tokens.
2. Run /compact regularly: If you have been in a long debugging session, the conversation history grows large, increasing the cost of every subsequent prompt. Running /compact summarizes the history and clears out raw logs.
3. Narrow your prompts: Instead of asking "Fix my app," ask "Find why the database connection times out in lib/db.ts." Specificity keeps the file reading context focused.

Claude Code represents a major leap forward for developer efficiency. By integrating directly with your local shell and repository, it bridges the gap between AI generation and actual build-test verification loops.