Claude Code Tutorial: Install and Setup Your First Project
Running an AI agent directly in your terminal allows you to inspect codebases, execute test suites, and refactor files without switching windows. However, path misconfigurations and authentication confusion often stop developers before their first prompt. This claude code tutorial shows software engineers how to cleanly install the CLI, configure project guidelines, and initialize a working repository. By the end, you will have a tested terminal workflow configured for autonomous development.
Before you start
- A Linux, macOS, or WSL terminal environment with curl and git installed
- A Claude.ai Pro or Team account, or an Anthropic Console API key with billing credits
Installing Claude Code Using the Official Script
The recommended way to install the CLI is through the official standalone shell script rather than global package managers. This method bundles dependencies cleanly and manages background updates automatically. Run the download command shown below to execute the installer.
Once the installer finishes downloading the binary to your local directory, export that folder into your shell path variable. Confirm the tool works by checking its version string. This step was tested in a Debian environment and verified to execute properly.
# Download and run the official Claude Code installer
curl -fsSL https://claude.ai/install.sh | bash
# Add the local bin folder to the current shell path
export PATH="$HOME/.local/bin:$PATH"
# Confirm the Claude Code binary executes properly
claude --version
Output from our test run
$ curl -fsSL https://claude.ai/install.sh | bash
Setting up Claude Code...
✔ Claude Code successfully installed!
Version: 2.1.294
Location: ~/.local/bin/claude
Next: Run claude --help to get started
⚠ Setup notes:
● Native installation exists but ~/.local/bin is not in your PATH. Run:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> your shell config file && source your shell config file
✅ Installation complete!
$ export PATH="$HOME/.local/bin:$PATH"
$ claude --version
2.1.294 (Claude Code)
$Inspecting CLI Options and Flags
Before starting an interactive session, review the available subcommands and flags. Running the help command below displays settings for agent customization, diagnostic checks, and directory permissions.
Familiarity with these options allows you to invoke automated tasks from shell scripts and define directory boundaries for your projects. This help check was tested and passed as expected.
# Display available subcommands, flags, and options
claude --help
Output from our test run
$ claude --help
Usage: claude [options] [command] [prompt]
Claude Code - starts an interactive session by default, use -p/--print for non-interactive output
Arguments:
prompt Your prompt
Options:
--add-dir <directories...> Additional directories to allow tool access to
--agent <agent> Agent for the current session. Overrides the 'agent' setting.
--agents <json-or-file> JSON object defining custom agents, or with --print the path to a file
that holds one (e.g. '{"reviewer": {"description": "Reviews code",
"prompt": "You are a code reviewer"}}')
--allow-dangerously-skip-permissions Enable bypassing all permission checks as an option, without it being
enabled by default. Recommended only for sandboxes with no internet
access.
--allowedTools, --allowed-tools <tools...>
Comma or space-separated list of tool names to allow (e.g. "Bash(git *) Edit")
--append-system-prompt <prompt> Append a system prompt to the default system prompt
--autocompact <auto|tokens> Auto-compact window size (auto, or 100k–1M tokens)
--ax-screen-reader Render screen-reader friendly output (flat text, no decorative borders
or animations).
--bg, --background Start the session in the background and return immediately. Prints the
id that `claude attach`, `logs`, `stop` and `rm` take; `claude agents`
lists them. With --resume <session-id>, continues that session in the
background under the same ID, or starts a copy and says so when theUnderstanding Authentication and Billing
Authentication requires either an active Claude Pro or Team subscription, or an Anthropic Console account with billing credits. Free accounts cannot access the CLI.
You can authenticate through your browser for personal desktop workflows or select console authentication if you manage billing through an Anthropic Console account. In headless environments or container setups, exporting the ANTHROPIC_API_KEY variable provides seamless access.
Setting Up a Sample Project Repository
The tool is designed to work within a version-controlled repository where it can inspect diffs and manage revisions. Initialize a clean directory with git and create initial source files to give the agent a functioning baseline.
The commands below create a small JavaScript utility and an assertion test script. Running the test verifies that your baseline logic passes before any automated modifications take place. This verification step was tested and passed cleanly.
# Initialize a dedicated project repository
mkdir -p ~/claude-code-demo && cd ~/claude-code-demo && git init
# Create a minimal JavaScript library
cat << 'EOF' > math.js
function add(a, b) {
return a + b;
}
function subtract(a, b) {
return a - b;
}
module.exports = { add, subtract };
EOF
# Create a self-checking test file
cat << 'EOF' > test.js
const { add, subtract } = require('./math');
console.assert(add(10, 5) === 15, 'add(10, 5) failed');
console.assert(subtract(10, 5) === 5, 'subtract(10, 5) failed');
console.log('All tests passed successfully.');
EOF
# Verify the baseline project passes tests
node test.js
Output from our test run
$ mkdir -p ~/claude-code-demo && cd ~/claude-code-demo && git init
Initialized empty Git repository in /root/claude-code-demo/.git/
$ cat << 'EOF' > math.js
> function add(a, b) {
> return a + b;
> }
>
> function subtract(a, b) {
> return a - b;
> }
>
> module.exports = { add, subtract };
> EOF
$ cat << 'EOF' > test.js
> const { add, subtract } = require('./math');
> console.assert(add(10, 5) === 15, 'add(10, 5) failed');
> console.assert(subtract(10, 5) === 5, 'subtract(10, 5) failed');
> console.log('All tests passed successfully.');
> EOF
$ node test.js
All tests passed successfully.
$Configuring Project Memory with CLAUDE.md
Every project repository benefits from having a CLAUDE.md file located at its root. This markdown document acts as persistent memory that the agent reads at the start of every session.
Use this file to state your build instructions, testing commands, and coding standards. Because the agent reads these instructions automatically, you do not need to restate recurring workflow rules in your conversation prompts.
# Project Guidelines for Claude Code
## Commands
- Test: `node test.js`
- Syntax check: `node --check *.js`
## Coding Standards
- Keep functions pure and modular.
- Include assert-based unit tests for all new calculations.
- Do not install external npm dependencies without approval.
## Workflow Rules
- Always run `node test.js` after modifying existing code.
- Provide clear git commit messages summarizing rationale.
Essential Interactive Slash Commands
Starting the interactive REPL gives you access to several built-in slash commands. Use /init to let the agent analyze your repository and set up baseline configuration files. For complex features, /plan switches into a non-destructive planning mode before modifying code.
To manage your session context efficiently, run /compact to summarize earlier messages and keep within memory boundaries. You can also run /cost at any point to track your token usage and monitor accumulated billing.
The Agentic Loop and Execution Permissions
The agent loop works by examining files, generating code diffs, and running terminal commands based on your prompts. For safety, the tool requests explicit user approval before executing commands that modify files or install software.
This interactive permission step allows you to review suggested shell commands and inspect file diffs before changes apply to your repository. You remain in complete control while the agent handles repetitive terminal tasks.
Wrap-up
You now have Claude Code installed, verified, and configured with dedicated repository memory. By structuring your project with clear guidelines and using interactive slash commands, you can build features smoothly alongside your terminal agent.
FAQ
Can I use Claude Code with a free Claude account?
No, Claude Code requires a paid Claude Pro, Team, or Enterprise subscription, or an Anthropic Console account with funded API credits.
Why does the claude command fail with command not found after installation?
The installer places the binary in ~/.local/bin. If this directory is not present in your $PATH variable, your shell cannot locate the executable until you export the path.
Should I install Claude Code with npm or the standalone script?
Anthropic recommends using the official standalone script instead of npm packages to avoid Node version conflicts and permission errors.