Claude Code · Series · Part 1 of 8

Meet Claude and set it up: the interfaces, the first session, and choosing a model

Every time I start work on a project with an AI assistant, I catch myself explaining the same things again: how to build it, which folders matter, which style we follow. This eight-part series is about ending that habit with one small file called CLAUDE.md. Before the file makes sense, though, you need the basics, so Part 1 covers what Claude is, the official ways to use it, how to install it, how much freedom to give it, and how to pick a model.

Words you will see

1. What is Claude?

Claude is a family of AI models made by Anthropic. You give it text (and, for some uses, images or files), and it writes text back: answers, explanations, summaries, and code. Under the hood it is a large language model, the same kind of “very fancy autocomplete” I described in my Android AI chat post. It reads your input as tokens, and writes a reply one token at a time.

Two names get mixed up, so let me separate them:

2. The official ways to use it

Claude Code is not tied to one window. Anthropic ships it in several places, and they share the same engine, so a habit you learn in one carries over to the others.

3. Installing Claude Code

Before you install

• An account that includes Claude Code: a Claude Pro, Max, Team or Enterprise subscription, or a Claude Console account billed by usage. Cloud accounts on Amazon Bedrock, Google Cloud or Microsoft Foundry also work. The free claude.ai plan does not include Claude Code. See Claude pricing for current plans.
• A supported computer: macOS 13 or later, Windows 10 (1809) or later, Ubuntu 20.04+, Debian 10+ or Alpine 3.19+, with at least 4 GB of RAM and an internet connection.
• A supported country. If the installer says the app is unavailable in your region, see Anthropic's supported countries.
• A project folder to work in, ideally one under git.

Pick the install command for your system

Debian, Ubuntu, Fedora, RHEL and Alpine users can also install through apt, dnf or apk; the steps are in the official setup guide. On native Windows, Git for Windows is recommended but optional: without it, Claude Code uses PowerShell as its shell tool. The installer shows no progress while it downloads, so leave the window open until it says Claude Code was installed.

Check that it worked

Open a new terminal window and run:

claude --version

It prints a version number followed by (Claude Code). For a fuller health check of your install and settings, run claude doctor. To update by hand later, run claude update.

If you see “command not found: claude”

This is the most common first-day problem. It means the folder where the installer put claude is not on your PATH yet (the list of folders your terminal searches for commands). The installer prints the exact fix under “Setup notes”; otherwise use the one for your shell, then open a new terminal and try again:

# macOS (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Linux (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows (PowerShell)
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

If it still is not found, check that the file ~/.local/bin/claude exists; if not, the install did not finish. Two other common messages: syntax error near unexpected token '<' means the installer address returned a web page instead of a script, so retry or install with Homebrew; and on Windows 'irm' is not recognized means you are in CMD rather than PowerShell. The official installation troubleshooting guide matches every error message to a fix.

Start it and sign in

1. Go to your project. Claude Code works relative to the folder you start it in, so this matters.

   cd ~/projects/my-app

2. Start it.

   claude

3. Sign in. The first run opens your browser to log in with your Claude or Console account. Your credentials are stored, so you will not need to do this again. Type /login inside a session to switch accounts.

4. Your first session

Once you run claude, you get a prompt. You type in plain language. A good first message is not “write me a feature”, it is a question that lets Claude look around:

> What does this project do, and how do I run it?

● I'll look at the project files first.
  Read(README.md)
  Read(app/build.gradle.kts)
  Search(pattern: "MainActivity")

● This is an Android app that shows a list of notes.
  • UI is in app/src/main/java/.../ui/ (Jetpack Compose)
  • Data is stored with Room in .../data/
  • Run it with ./gradlew installDebug

> _

Notice what happened. You did not paste any code. Claude chose which files to read. In Manual mode, whenever it wants to edit a file or run a command, it asks for your permission first. Other modes ask less, and you can change mode at any time.

Claude wants to run a command

  ./gradlew testDebugUnitTest

  1. Yes
  2. Yes, and don't ask again for this command
  3. No, and tell Claude what to do differently

How to stop, interrupt and quit

You cannot click in the terminal. Use the arrow keys to move around and press Enter to choose an option.

Stay safe on day one

5. Slash commands worth knowing

Typing / at the prompt opens a menu of commands that control the session itself rather than talk to the model. These are the ones I use most. The full list is in the official commands reference:

6. Manual, auto-accept and plan mode

Earlier you saw Claude ask before running a command. That is one of several permission modes, which decide how much Claude may do without asking. The official documentation lists six: Manual (config value default), accept edits (acceptEdits), plan, auto (a second model reviews actions instead of you), dontAsk (for locked-down CI) and bypassPermissions (for isolated containers only). This section covers the three you will switch between most, plus where auto fits. Full reference: Choose a permission mode.

Manual mode: you approve each action

Reading files is allowed, but most actions that change your project or machine, or reach the network, need a yes. It is slower, but you see every edit before it lands. It is the right choice for your first sessions, for production code, and whenever you do not yet trust the task.

If a prompt keeps repeating for something safe, such as running your tests, add it to the allow list in your settings (section 8) instead of switching everything off.

Accept edits: fewer interruptions

Claude creates and edits files in your working folder without asking, and also runs common file commands such as mkdir, touch, mv, cp and sed there. Anything else, including other shell commands and paths outside the project, still prompts. You review the result afterwards in your editor or with git diff. It suits well-defined work on a git branch where everything can be undone.

Plan mode: think first, change nothing

In plan mode Claude researches and proposes changes without making them. It reads files, can run shell commands to explore, and writes a plan, but it does not edit your source. Edits stay blocked until you approve the plan.

> Add an offline fallback when the online model is unreachable.

● Read(app/engine/EngineSelector.kt)
  Read(app/chat/ChatViewModel.kt)

● Proposed plan
  1. Add a reachability check in EngineSelector
  2. If online fails before any text arrives, switch to local
  3. Show a one-line notice in the chat
  4. Add unit tests for the three cases

  1. Yes, and use auto mode
  2. Yes, manually approve edits
  3. No, keep planning   (tell Claude what to change)

⏸ plan mode on (shift+tab to cycle)

Why it matters: a plan is cheap to correct, and code is not. Catching a wrong assumption in step 2 of a plan costs you one sentence. Catching it after twenty edited files costs a lot of tokens and time. It is my default for anything touching several files, for new features, and for any code I do not know well. Two handy extras from the docs: press Ctrl+G to open the plan in your text editor and edit it before Claude proceeds, and use the opusplan model alias (section 7) to plan with the largest Opus model and then execute with Sonnet.

Ways to enter it:

# press Shift+Tab until the status bar says "plan mode on"

# or type /plan, optionally with a task
/plan fix the login bug

# or start there
claude --permission-mode plan

To make plan mode the default for a project's terminal sessions, set "defaultMode": "plan" under permissions in .claude/settings.json.

And auto mode?

In auto mode a separate classifier model reviews each action and blocks the risky ones, so you get far fewer prompts without switching checks off completely. It needs a supported model and can be turned off by an organisation. It is convenient for long tasks, but while you are learning, Manual or accept edits teach you more about what Claude is doing.

7. Changing the model

Claude comes in different sizes. A larger model reasons better about hard problems but is slower and uses more of your usage allowance. A smaller one is quick and cheap, and is plenty for simple edits, renames and questions. Matching the model to the job is one of the easiest ways to work faster and spend less. The official cost guidance says Sonnet handles most coding tasks well and costs less than Opus, so keep Opus for complex architectural decisions and multi-step reasoning.

There are four ways to choose. They are listed in priority order, so if two disagree, the earlier one wins:

> /model

 Select model
 ✓ 1. Default   (recommended for your plan)
   2. Opus      long-running coding and knowledge work
   3. Sonnet    best mix of speed and intelligence
   4. Haiku     fastest, high-volume tasks

# 1. Inside a session (also saved as your default for new sessions)
/model sonnet

# 2. When you start Claude Code (this launch only)
claude --model sonnet

# 3. Environment variable (sessions started with it)
export ANTHROPIC_MODEL=sonnet

# 4. Saved in a settings file (see section 8)
{ "model": "sonnet" }

Short aliases save you from remembering long model IDs. According to the official model configuration docs:

“Latest” depends on where you run Claude: on Amazon Bedrock, Google's platform or Microsoft Foundry the aliases can point to older versions. To pin an exact version for repeatable results, use a full model name such as claude-opus-5-5. Model names change often, so run /model to see what your account offers today.

Two related controls: the effort level (adjustable in /model or with /effort) trades reasoning depth for speed and cost on models that support it, and the model you pick also applies to subagents that inherit your session's model.

8. Settings files and where they live

Beyond the model, you can save preferences such as permissions, the default model and environment variables in settings.json files. The three levels you will use most are below, and the more specific one wins. (The docs also describe settings from the command line and organisation-managed settings, which sit above all three.)

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(./gradlew test *)"],
    "deny":  ["Read(./.env)"]
  }
}

That small file says: use Sonnet by default, let Claude run the Gradle tests without asking each time, and never read the .env file. The /config command can edit many of these for you. The full list of keys and the precedence order are in the official settings documentation.

Notice that settings configure behaviour. They do not tell Claude anything about your project. For that, we need a different kind of file.

9. What comes next

You can now install Claude Code, talk to it, approve its actions, and switch models. But close the session and open a new one, and Claude has forgotten everything you taught it. That is not a bug; it is how language models work. In Part 2 we fix it with CLAUDE.md. Part 3 shows how that saves tokens and speeds up onboarding, and Part 4 covers the Claude API, the full model list and the official links.