# Basic setup to start coding with an AI agent: Claude Code and OpenCode

A Bitflow Solutions guide. Web version: https://bitflow-solutions.com/en/guias-tecnicas/ai-coding-agent-setup-claude-code-opencode/

## 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.md` or `AGENTS.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

### Install Claude Code (Windows)

```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
```

```bash
# macOS, Linux or WSL
curl -fsSL https://claude.ai/install.sh | bash
```

### Install OpenCode

```powershell
# 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
```

```bash
# 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
```

### Sign in and choose the model

```powershell
# 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
```

### Example AGENTS.md / CLAUDE.md

```markdown
# 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.
```

### Permissions in Claude Code (.claude/settings.json)

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}
```

### Permissions and model in OpenCode (opencode.json)

```json
{
  "$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" }
  ]
}
```

### Everyday commands

| What you want to do | Claude Code | OpenCode |
|---|---|---|
| New conversation | /clear | /new |
| Change model | /model | /models |
| Point to a file | @path | @path |
| Terminal command | ! | ! |
| Interrupt | Esc | Esc |
| Undo | Esc Esc or /rewind | /undo, /redo |
| Summarise the context | /compact | Ctrl+X C |
| Previous sessions | /resume | /sessions |
| Plan without editing | Shift+Tab (plan mode) | Shift+Tab (Plan agent) |

```powershell
# 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
```

### Review the changes with Git

```powershell
# 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
```

## 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.md` or `AGENTS.md` with 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 -p` or `opencode run` (see the CI/CD with GitHub Actions guide).
