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.
Start with one provider and one model. Do not configure three providers on day one. You will tune the rest of the setup faster if you are not also debugging model routing.
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:
- Did it use the right import style?
- Did it follow the test framework conventions?
- 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.
Do not run your first real task on a dirty working tree. OpenCode does not auto-commit. If the agent produces a bad diff, you want to recover with a clean
git checkout, not a manual revert.
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.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)