A practical guide to start coding with an AI agent in your terminal: Claude Code, by Anthropic, and OpenCode, which is open source. How to install them on Windows, connect them, give them your project’s context and limit what they can do, with the everyday commands side by side. All the commands are also in the README.md on the left.
What you’ll learn
- What an AI coding agent does and how it differs from a chat.
- How to install Claude Code and OpenCode on Windows and check that they work.
- How to connect your account or model provider and choose the model.
- How to give the agent your project’s context with
CLAUDE.mdorAGENTS.md. - How to set permissions so it does not read your secrets or run anything you do not want.
- The everyday commands, how to undo and how to work safely.
Prerequisites
- Windows 10 (version 1809 or later) with PowerShell; the equivalent commands for macOS and Linux are in each step.
- For Claude Code: a Claude Pro, Max, Team or Enterprise plan, or a Claude Console (API) account. The free Claude plan does not include Claude Code.
- For OpenCode: an account with a model provider (Anthropic, OpenAI, GitHub Copilot…) or models on your own machine with Ollama (see the Ollama guide).
- Git (on Windows, Git for Windows, recommended: Claude Code uses Git Bash if it is installed and PowerShell otherwise).
- A project in a Git repository, so you can review and undo the agent’s changes.
Step by step
1. Understand what a coding agent does
An agent does not just answer questions: it reads your project, edits files and runs commands in your terminal to complete a task, and asks your permission for whatever you decide. That is why it needs to be set up properly before you use it on a real project.
| Claude Code | OpenCode | |
|---|---|---|
| Who makes it | Anthropic | Open-source project (MIT licence) |
| Models | Claude (also through Amazon Bedrock, Google Cloud or Microsoft Foundry) | Several providers: Anthropic, OpenAI, GitHub Copilot, local models… |
| Context file | CLAUDE.md | AGENTS.md (and it reads CLAUDE.md if there is none) |
| Configuration | .claude/settings.json | opencode.json |
2. Install Claude Code
The native installer is the recommended option on Windows: it does not need Node.js and updates itself in the background. From PowerShell:
# Native installer (recommended): no Node.js needed and it updates itself
irm https://claude.ai/install.ps1 | iex
# Alternative with WinGet (update it with winget upgrade Anthropic.ClaudeCode)
winget install Anthropic.ClaudeCode
# Open a new terminal and check
claude --version
claude doctor
On macOS, Linux or WSL:
# macOS, Linux or WSL
curl -fsSL https://claude.ai/install.sh | bash
claude doctor checks the installation without opening a session. Do not confuse Claude Code with the Claude desktop app: they are separate downloads.
3. Install OpenCode
OpenCode is not installed with Windows package managers: its documentation provides a zip with the executable for Windows (x64 and ARM64) and an installer for the desktop app. With the zip, unzip it into a folder and add that folder to your PATH:
# Windows: unzip the OpenCode zip for Windows (x64 or ARM64) linked from opencode.ai/docs,
# for example into C:\tools\opencode, and add that folder to your user PATH:
$current = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$current;C:\tools\opencode", 'User')
# Open a new terminal and check
opencode --version
On macOS and Linux:
# macOS or Linux: official script
curl -fsSL https://opencode.ai/v2/install | bash
# or with Homebrew
brew install anomalyco/tap/opencode-v2
# or with npm (on any system with Node.js)
npm install -g @opencode/cli
# Update later on
opencode upgrade
4. Sign in and choose the model
Both are started from the project folder. Claude Code takes you to the browser to sign in with your Claude account; in OpenCode you connect whichever provider you want from the interface itself:
# Claude Code: go into your project and start it; the first time it opens the browser to sign in
cd C:\projects\my-app
claude
claude auth status # check which account you are signed in with
# OpenCode: start it and, inside, connect a provider and choose the model
opencode
# /connect -> choose the provider (Anthropic, OpenAI, GitHub Copilot, Ollama…) and enter the credentials
# /models -> choose the model
# OpenCode from the command line too
opencode auth login
opencode auth list
opencode models
Inside Claude Code, /login and /logout switch accounts and /model changes the model.
5. Give it context with CLAUDE.md or AGENTS.md
When it starts, the agent reads a file with your project’s instructions: how it is built, how it is tested and which conventions you follow. In Claude Code, /init analyses the project and creates an initial CLAUDE.md (if one already exists, it suggests improvements). In OpenCode the file is AGENTS.md, at the root of the project. An example:
# My app
## Commands
- Install dependencies: npm install
- Run the tests: npm test
- Check the style: npm run lint
## Conventions
- Strict TypeScript; no any.
- Every logic change comes with its test.
- Do not touch the files in the migrations/ folder unless asked.
## Before finishing
- Run npm test and npm run lint and fix anything that fails.
One file can serve both: Claude Code reads AGENTS.md when there is no CLAUDE.md, and OpenCode reads CLAUDE.md when there is no AGENTS.md. Commit it to the repository so the whole team works the same way. For personal notes, Claude Code uses CLAUDE.local.md: add it to .gitignore.
6. Set the permissions
Decide what the agent can do without asking and what it must never do. In Claude Code, in .claude/settings.json (shared with the team) or .claude/settings.local.json (just for you, kept out of Git). deny rules always win:
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}
In OpenCode, in opencode.json at the root of the project, with a list of rules (allow, ask or deny; if none matches it asks, and if several match the last one wins). Set the model there too, in provider/model format:
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5",
"permissions": [
{ "action": "shell", "resource": "npm test*", "effect": "allow" },
{ "action": "read", "resource": "*.env", "effect": "deny" },
{ "action": "read", "resource": "*.env.*", "effect": "deny" }
]
}
Both files are JSON. In Claude Code it must be strict JSON: no comments and no trailing commas. In Claude Code, /permissions shows all the active rules and which file each one comes from.
7. Choose how it works: plan or edit
Before a large change, ask for a plan first. In Claude Code, Shift+Tab cycles through the modes: the normal one (asks permission), accept edits (edits without asking) and plan (analyses and proposes without touching anything). In recent versions, the interactive session may start in automatic mode: check it at the bottom of the screen.
In OpenCode there are two agents: Build, the default, with full access, and Plan, which explores and plans without editing the project files. You switch between them with Shift+Tab.
8. Use the everyday commands
| What you want to do | Claude Code | OpenCode |
|---|---|---|
| Start a new conversation | /clear | /new |
| Change model | /model | /models |
| Point to a file | @ + path | @ + path |
| Run a terminal command | ! at the start | ! at the start |
| Interrupt | Esc | Esc |
| Undo changes | Esc twice or /rewind | /undo (and /redo) |
| Summarise to free up context | /compact | Ctrl+X then C |
| See previous sessions | /resume | /sessions |
| See usage and limits | /usage | — |
And from the terminal, without opening the interface:
# A single request without opening the interface (useful in scripts)
claude -p "Explain what the src/services folder does"
opencode run "Explain what the src/services folder does"
# Pick up where you left off
claude -c # the last conversation in this folder
claude -r "name-or-id" # a specific session
If you use VS Code, both have an official extension: Claude Code (by Anthropic) and OpenCode. The Claude Code extension does not install the claude command: for the terminal, install it as in step 2.
9. Work safely
You are responsible for what the agent changes and runs. Work on a branch, review every change before approving it and commit it yourself:
# Before you start: leave the repository clean
git status
git switch -c agent/new-feature
# When you finish: review everything that has changed before committing it
git diff
git add -p
- Deny reading secrets (
.env, keys, certificates) as in step 6. - Do not pass the agent content of unknown origin (web pages, emails, third-party files) without reviewing it: it may carry hidden instructions (prompt injection).
- Do not use the mode that skips all permissions (
bypassPermissionsin Claude Code) outside an isolated environment. - In Claude Code,
/sandboxisolates the agent’s commands on macOS, Linux and WSL 2; it is not available on native Windows.
Common errors
“claude” is not recognised as a command
The installer folder is not on your PATH. Check that %USERPROFILE%\.local\bin\claude.exe exists with Test-Path "$env:USERPROFILE\.local\bin\claude.exe", add that folder to your user PATH as in step 3 and open a new terminal.
“opencode” is not recognised as a command
The folder where you unzipped the file is not on your PATH, or the terminal was opened before the change. Check the path from step 3 and open a new terminal.
Claude Code cannot find Git Bash
Find where Git is with where.exe git and set the path to bash.exe in settings.json: "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" }.
Session expired or “Not logged in”
In Claude Code, sign in again with /login or claude auth login and check that your computer’s clock is correct. In OpenCode, reconnect the provider with /connect and check with opencode auth list.
It does not work behind the company proxy
Set the proxy before installing and starting: $env:HTTPS_PROXY = "http://proxy.example.com:8080" and the same with HTTP_PROXY. OpenCode also supports NO_PROXY and NODE_EXTRA_CA_CERTS for the company CA.
Claude Code does not find files when searching
Install ripgrep (winget install BurntSushi.ripgrep.MSVC), add "USE_BUILTIN_RIPGREP": "0" to the env block of settings.json and check with claude doctor.
The agent read or changed something it should not have
Undo the change (/rewind in Claude Code, /undo in OpenCode, or git restore) and add the missing deny rule. In Claude Code, /permissions lets you review the active rules.
Next steps
- Use models on your own machine with Ollama, without sending your code anywhere (see the Ollama guide).
- Agree a shared
CLAUDE.mdorAGENTS.mdwith your team and mandatory review of the code the agent produces. - Connect external tools with MCP servers (in OpenCode,
opencode mcp add). - Use the agent in pipelines with
claude -poropencode run(see the CI/CD with GitHub Actions guide).