OpenCode First Project Setup: From Install to First Passing Test

Most AI coding agents promise to work out of the box. OpenCode does not. It is a harness, not a product, and the first-run experience reflects that. You will spend more time configuring it than Claude Code or Cursor, but the payoff is a setup that matches your project instead of a vendor’s defaults.

We have onboarded OpenCode to three projects: a TypeScript monorepo, a Python service, and a Go CLI. The same three setup steps mattered every time.

Step 1: Install and Add a Provider

Install the binary with the official shell script, then run opencode in a project directory. The first thing it asks for is a model provider. You can use Anthropic, OpenAI, Google, OpenRouter, or a local Ollama endpoint.

For most developers, Anthropic is the easiest starting point because Claude Sonnet is the most capable general-purpose model. OpenRouter is the better long-term choice if you want to switch models later without reconfiguring API keys for each provider.

Step 2: Define Context File Patterns

By default, OpenCode will try to read everything in your repository. That wastes tokens and confuses the agent with build artifacts, generated code, and dependency directories.

Create .opencode/config.toml in your project root and set include and exclude patterns. For a TypeScript project, we use something like this:

[context]
include = ["src/**/*.ts", "tests/**/*.ts", "package.json", "tsconfig.json"]
exclude = ["node_modules", "dist", "coverage", "*.min.js", ".next"]

The exact paths matter less than the principle: the agent should only see files that are relevant to the task. If your project uses path aliases like @/components, include the alias configuration so the agent understands imports.

Step 3: Write a Conventions File

This is the step most people skip, and it is the step that determines whether the agent’s first pass is usable. Create a CONTEXT.md file with short rules specific to your project:

• Import style: absolute aliases or relative paths?
• Error handling pattern: exceptions, Result types, or error codes?
• Test framework: Jest, Vitest, pytest, Go test?
• Formatting: Prettier, gofmt, ruff?
• Any naming conventions that are not obvious

We keep ours under 300 words. The agent reads it at the start of the session, and the output quality improves immediately.

Step 4: Run a Calibration Task

Before asking for real work, run a task you already know the answer to. Something like “add a simple utility function and a test for it.” Review the diff for three things:

1. Did it use the right import style?
2. Did it follow the test framework conventions?
3. Did it run the test and report the result?

If the answer is yes, your setup is solid. If not, adjust the context patterns or conventions file and try again. This ten-minute calibration saves hours of cleanup later.

What Good Output Looks Like

With the three setup steps in place, a typical request like “refactor the user service to use async database calls” produces a plan, reads the right files, generates a diff, and runs the tests. The diff will not be perfect, but it will be in the right shape. You review, approve, and edit rather than rewrite.

That is the real measure of a working setup. The agent is not replacing you. It is producing a first draft you can finish in minutes instead of hours.