Claude Code tutorial: from install to your first merged pull request

Claude Code is Anthropic's coding agent for the terminal: it reads your repository, edits files and runs commands until a task is done. This tutorial takes you from installation to a reviewed pull request, with the commands, settings and prompts you need at each step.

What do you need before starting this Claude Code tutorial?

You need three things: a terminal, a project in a git repository, and a paid Claude account. Claude Code works with a Pro, Max, Team or Enterprise subscription, a Claude Console account with prepaid API credits, or a cloud provider such as Amazon Bedrock. The free claude.ai plan does not include Claude Code.

At the time of writing (October 2026), Claude's pricing page lists Pro at $20 a month ($17 a month billed annually) and Max from $100 a month. Pro is enough to learn on. If you plan to run long agent sessions every day, read up on how Claude Code usage limits work before you choose a plan.

The system requirements are modest: macOS 13 or later, Windows 10 1809 or later, Ubuntu 20.04 or later, Debian 10 or later, or Alpine 3.19 or later, with 4 GB of RAM. Pick a real project for this tutorial, ideally one with a test suite. A toy repository teaches you the commands but not the judgment.

How do I install Claude Code?

Install Claude Code with the native installer, which also keeps itself updated in the background. Open a terminal and run the command for your system.

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

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

Then open a new terminal window and confirm the install:

claude --version

You should see a version number followed by (Claude Code). If the shell says claude is not found, the install directory is not on your PATH yet; the troubleshooting page covers the fix per shell.

Other install methods exist, with trade-offs:

If something feels off later, claude doctor prints read-only diagnostics for your install and settings without starting a session.

How do you start your first Claude Code session?

Start a session by running claude inside your project folder. On first launch it opens a browser to sign in; after that, credentials are stored and you won't be asked again.

cd ~/code/my-appclaude

Your first prompts should be questions, not changes. Claude Code reads files as it needs them, so you don't paste code in. Try these:

what does this project do, and where is the main entry point?

how do I run the tests here, and do they pass right now?

The second prompt is the useful one. If Claude can find and run your tests, it can check its own work later. If it can't, fix that first: it is the single biggest factor in how well the rest goes.

These shell commands cover most daily use:

Exit with /exit or Ctrl+D twice.

How do Claude Code permission modes work?

A permission mode decides which actions Claude takes without asking you. You switch modes during a session with Shift+Tab, and the status bar under the prompt shows the active one.

As of October 2026, with Claude Code v2.1.283 or later, new interactive sessions start in auto mode: Claude acts without routine prompts while a separate classifier model reviews each action and blocks anything that goes beyond your request. Older versions started in Manual mode on some plans.

From auto mode, Shift+Tab goes to Manual, then accept-edits, then plan. For your first week, Manual or accept-edits teaches you the most, because you see every command Claude wants to run and why.

On top of modes, you can add permanent rules in .claude/settings.json (shared with your team) or .claude/settings.local.json (only you). Deny rules apply in every mode.

{  "permissions": {    "allow": ["Bash(npm run *)", "Bash(git commit *)"],    "deny": ["Bash(git push *)", "Read(./.env)"]  }}

This lets Claude run any npm script and commit, while it can never push or read your .env file. The permissions reference explains the wildcard rules in detail: Bash(npm run *) matches npm run test but not npm install.

How do I set up a CLAUDE.md for my project?

CLAUDE.md is a markdown file of instructions that Claude Code loads at the start of every session. Run /init inside a session and Claude writes a first draft from what it finds in the repository.

The draft is a starting point. Cut it down to what Claude can't work out on its own: exact commands, conventions that differ from the defaults, and rules your team actually enforces. The memory docs recommend staying under 200 lines per file, because longer files cost context and reduce how closely Claude follows them.

## Commands- Install: `pnpm install`- Dev server: `pnpm dev` (port 3000)- Tests: `pnpm test` (Vitest); run one file with `pnpm test path/to/file`- Lint and types: `pnpm lint && pnpm typecheck`, run both before you say a task is done## Conventions- TypeScript strict mode, no `any`- Server code lives in `src/server`, UI in `src/app`- Use the existing `logger` from `src/lib/logger.ts`, never `console.log`## Workflow- Work on a new branch named `feat/<short-name>` or `fix/<short-name>`- Keep each change focused; ask before adding a dependency

Where the file lives decides who it applies to:

You can pull other files in with @path/to/file (for example @docs/architecture.md), and /memory opens your CLAUDE.md files for editing. Our guide to CLAUDE.md best practices covers structure and upkeep in more depth.

Which Claude Code slash commands should you learn first?

Type / in a session to see every command and skill available to you. Out of dozens, about eight matter in the first month:

The habit that saves the most trouble is /clear between unrelated tasks. A conversation full of yesterday's debugging leads Claude to make assumptions that no longer hold.

How do you use plan mode for bigger changes?

Plan mode makes Claude research and propose a change without editing your source. Use it for anything that touches more than one or two files.

Enter it by pressing Shift+Tab until the status bar shows plan mode on, by starting a prompt with /plan, or by launching with claude --permission-mode plan. Claude reads code, may run commands to explore, and then presents a plan with three choices:

1. Yes, and use auto mode: approve and let Claude carry it out.
2. Yes, manually approve edits: approve, but confirm each edit.
3. No, keep planning: tell Claude what to change in the plan.

Press Ctrl+G to open the plan in your text editor and change it yourself before approving. This is where you catch the expensive mistakes: a wrong file, a migration nobody asked for, a new dependency. Fixing a plan costs a sentence; fixing an implementation costs a review cycle.

Walkthrough: your first real task, from issue to pull request

Here is a complete first task, end to end. Pick a small, real issue: a bug with a clear reproduction or a feature that fits in an afternoon.

1. Start clean. Make sure git status is clean and you are on your main branch, then run claude.
2. Describe the task with acceptance criteria. Vague prompts produce vague work.

/plan Users who enter a wrong password see a blank screen instead of an error.Expected: the login form shows "Email or password is incorrect" under thepassword field and keeps the email filled in.Write a failing test for this first, then fix it.Create a branch named fix/login-error-message before editing.Don't change the API response format.

3. Read the plan. Check which files it names, whether it starts with a test, and whether it stays inside the scope you gave. Choose "No, keep planning" and correct it if needed.
4. Approve and watch. Choose manual approval for your first few tasks. Read each edit and each command before you accept it.
5. Make Claude prove it. Ask it to run the full test suite, the linter and the type checker, and to show you the output.

run pnpm test, pnpm lint and pnpm typecheck and show me the results.Then summarize what you changed and why, file by file.

6. Review the diff yourself. Run git diff main or open the changes in your editor. You own this code once it merges, so read it like a colleague's pull request.
7. Commit and open the pull request. Claude writes good commit messages and descriptions when you tell it what reviewers need.

commit with a clear message, push the branch, and open a pull request withthe GitHub CLI. In the description, explain the bug, the fix, and how to test it.

If you denied git push in your settings, Claude stops and asks, which is the point. If the GitHub CLI (gh) isn't installed, push yourself and open the pull request in the browser. After review and CI pass, merge as usual.

For bigger work, the quality of step 2 decides most of the outcome. Our guide on how to write tasks for AI coding agents has templates for that.

What mistakes do beginners make with Claude Code?

Most early frustration comes from a handful of habits, and each has a simple fix:

• Huge first tasks. "Build the billing system" gets you a large, hard-to-review diff. Split it into steps that each end in passing tests.
• No way to verify. Without tests or a runnable check, Claude can only guess whether its change works. Give it a command that proves success.
• One endless conversation. Context fills up and older details get compressed. Use /clear between tasks and keep lasting rules in CLAUDE.md.
• Approving without reading. Accepting every prompt on autopilot defeats the point of reviewing. If prompts are too frequent, add allow rules instead.
• Correcting by repetition. If Claude goes the wrong way twice, rewind to before the mistake and rephrase, rather than piling corrections onto a confused conversation.
• Running long tasks on a laptop. A session dies when the machine sleeps or the terminal closes.

That last one matters once your tasks start taking an hour or more. You can keep sessions alive with tmux on a server, a headless claude -p run, or a hosted machine; our guide to running Claude Code 24/7 compares the options. Orkio is one of them: an always-on cloud box where Claude Code keeps working on your own Claude account after you close your laptop, and you review the pull requests later from your phone or the web.

Your first-week checklist

Work through this list over your first few sessions:

• Install with the native installer and confirm claude --version
• Ask Claude to find and run your tests; fix anything that blocks it
• Run /init, then trim CLAUDE.md to commands and real conventions
• Add allow rules for safe commands and deny rules for git push and secrets
• Do three small tasks in Manual or accept-edits mode, reading every diff
• Use /plan for your first multi-file change and edit the plan before approving
• Ship one change as a pull request that a teammate reviews

Once that feels routine, look at Claude Code hooks to run your formatter automatically after each edit, and at MCP servers to connect Claude to tools such as your issue tracker.

Frequently asked questions