How to Run Claude Code in Terminal

Introduction

The terminal is where developers live. It's where we run builds, manage version control, deploy applications, and orchestrate our entire development workflow. Running Claude Code from the terminal puts AI assistance exactly where you need it, integrated directly into your command-line workflow.

Unlike browser-based AI tools that require context switching, Claude Code runs in the same environment as your code. You can pipe output to it, run it alongside your other terminal tools, and keep your hands on the keyboard throughout your entire development session. There's no copying and pasting between windows, no uploading files, and no breaking your flow.

This guide walks you through everything you need to get Claude Code running in your terminal. From initial installation to advanced workflow tips, you'll learn how to make Claude Code a natural part of your command-line toolkit.

Prerequisites

Before installing Claude Code, you need three things: Node.js, npm, and an Anthropic API key.

Node.js and npm

Claude Code is distributed as an npm package, so you'll need Node.js installed on your system. Node.js version 18 or higher is required.

To check if you have Node.js installed and verify your version:

node --version
npm --version

If you don't have Node.js installed or need to upgrade, download it from nodejs.org. The LTS (Long Term Support) version is recommended for stability.

Anthropic API Key

Claude Code connects to Anthropic's API, which requires an API key. You'll need to create an account at console.anthropic.com and generate an API key from the dashboard.

Keep your API key secure. You'll configure it during first run, and Claude Code will store it securely on your system. Never commit your API key to version control or share it publicly.

Installation

Installing Claude Code is straightforward with npm. Open your terminal and run:

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

The -g flag installs Claude Code globally, making the claude command available from any directory on your system.

Verify the Installation

After installation completes, verify that Claude Code is accessible:

claude --version

You should see the version number printed to your terminal. If you get a "command not found" error, your npm global bin directory may not be in your PATH. See the troubleshooting section below for solutions.

Alternative: Using npx

If you prefer not to install globally, you can run Claude Code directly with npx:

npx @anthropic-ai/claude-code

This downloads and runs the latest version without a permanent installation. However, global installation is recommended for regular use since it starts faster and doesn't require downloading each time.

Your First Run

With Claude Code installed, navigate to any project directory and start it:

cd ~/projects/my-app
claude

Initial Configuration

On first run, Claude Code will prompt you to enter your Anthropic API key. Paste the key you generated from the Anthropic console. Claude Code stores this securely and won't ask again unless you explicitly reconfigure.

You'll also be asked to accept the terms of service. Once configured, Claude Code initializes and presents you with an interactive prompt.

The Claude Code Interface

Claude Code runs in an interactive REPL (Read-Eval-Print Loop) mode. You'll see a prompt where you can type natural language requests. Claude Code processes your request, shows you what it's doing, and waits for your next input.

> What files are in this project?

Claude Code reads your directory structure and responds with a summary of your project files, their purposes, and the overall architecture.

Basic Usage

Working with Claude Code follows a conversational pattern. You describe what you want, Claude Code investigates and takes action, and you review the results.

Starting a Session

Always start Claude Code from your project's root directory. This gives Claude Code access to your entire codebase and helps it understand project context:

cd /path/to/your/project
claude

Giving Prompts

Type your requests in natural language. Be specific about what you want:

> Add input validation to the login form in src/components/LoginForm.jsx

> Fix the bug where users can submit empty comments

> Refactor the fetchUserData function to use async/await instead of promises

Vague prompts produce vague results. Instead of "make it better," specify what improvement you want.

Reviewing Changes

Before modifying any file, Claude Code shows you exactly what it intends to change. You'll see the file path, the lines being modified, and the new content. This transparency lets you verify changes before they're applied.

Accepting or Rejecting

Claude Code asks for permission before writing changes. You can accept the proposed changes, ask Claude Code to modify its approach, or reject the changes entirely. This keeps you in control of your codebase at all times.

Essential Commands

Claude Code includes built-in commands that control its behavior. These commands start with a forward slash.

/help

Display available commands and usage information:

> /help

/clear

Clear the conversation history and start fresh. Useful when you want to change topics or if the conversation has accumulated too much context:

> /clear

/compact

Summarize the current conversation to reduce token usage while preserving important context. Use this during long sessions to stay within context limits:

> /compact

/config

View or modify Claude Code configuration, including API key settings:

> /config

/cost

Display token usage and estimated costs for the current session:

> /cost

/exit or Ctrl+C

End your Claude Code session and return to your regular terminal prompt.

Working with Projects

Claude Code becomes most powerful when it understands your project's structure and conventions.

Project Context Awareness

When you start Claude Code in a directory, it recognizes common project structures. It identifies package.json for Node projects, Cargo.toml for Rust, requirements.txt for Python, and many other configuration files. This helps Claude Code understand your technology stack and follow appropriate conventions.

Using CLAUDE.md

For deeper customization, create a CLAUDE.md file in your project root. This file contains instructions that Claude Code reads at the start of every session:

# Project Instructions

This is a React application using TypeScript.

## Conventions
- Use functional components with hooks
- Place tests next to their source files
- Use named exports, not default exports

## Key Files
- src/api/client.ts - API configuration
- src/hooks/useAuth.ts - Authentication logic

Learn more in our complete CLAUDE.md guide.

Multi-Directory Projects

For monorepos or projects spanning multiple directories, start Claude Code from the root. Claude Code can navigate subdirectories and understand how different parts of your project relate to each other.

Tips for Terminal Users

These workflows help you integrate Claude Code into your existing terminal habits.

Use with tmux or screen

Running Claude Code in a tmux or screen session lets you keep it running while you work in other terminal panes. Switch between your editor, Claude Code, and other tools without losing context:

# Create a new tmux session with Claude Code
tmux new-session -s claude

# In another pane, you can run your editor, tests, etc.
# Switch panes with Ctrl+B then arrow keys

Combine with Git

Claude Code works excellently alongside Git. A typical workflow:

# Create a feature branch
git checkout -b feature/new-validation

# Start Claude Code
claude

# After making changes, exit and commit
# Ctrl+C to exit
git add -p  # Review changes
git commit -m "Add input validation"

Pipe Output to Claude Code

You can start Claude Code with an initial prompt by piping text to it:

# Start with a specific task
echo "Review the error handling in src/api/" | claude

Quick Questions with -p Flag

For quick, one-off questions without starting an interactive session:

claude -p "What does the useCallback hook do in React?"

Terminal Aliases

Create shell aliases for common workflows:

# Quick Claude Code alias
alias cc='claude'

# Start Claude Code in a specific project
alias cc-myapp='cd ~/projects/my-app && claude'

Troubleshooting

Common issues and their solutions:

"command not found: claude"

Your npm global bin directory isn't in your PATH. Find it with:

npm config get prefix

Add the bin subdirectory to your PATH in ~/.bashrc or ~/.zshrc:

export PATH="$(npm config get prefix)/bin:$PATH"

API Key Errors

If you see authentication errors, verify your API key is correct. You can reconfigure it with:

claude /config

Permission Denied Errors

On Mac or Linux, you may need to fix npm permissions. The recommended solution is to use a Node version manager like nvm, or reconfigure npm to use a different directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Slow Startup

If Claude Code takes a long time to start, it may be scanning a very large directory. Use a .gitignore file to exclude node_modules, build directories, and other large folders that Claude Code doesn't need to index.

Context Length Exceeded

If you hit context limits during a long session, use /compact to summarize the conversation, or /clear to start fresh while keeping your file system context.

Conclusion: From Terminal to Structured Development

Running Claude Code from your terminal brings AI assistance directly into your development workflow. No context switching, no file uploads, no breaking your concentration. Just natural language requests and direct file modifications in the environment where you already work.

You've learned how to install Claude Code, configure it for your projects, and integrate it with terminal tools like tmux and git. You know the essential commands and how to troubleshoot common issues.

But as your projects grow and you use Claude Code more extensively, you'll encounter a new challenge: maintaining consistency. Claude Code is powerful, but it doesn't inherently know your architecture patterns, naming conventions, or how different parts of your system should interact. Over long sessions and across multiple files, instructions get forgotten and patterns drift.

That's where Claude Architect comes in. Claude Architect provides the structure that keeps Claude Code consistent. It enforces your architecture decisions, maintains patterns across sessions, and coordinates development across multiple platforms. Instead of hoping Claude follows your instructions, you get structural enforcement that guarantees it.