# opencode TypeScript: A Practical Guide for Developers

URL: https://agentvera.dev/en/blog/opencode-for-typescript/ · Published: 2026-11-01

This practical guide shows how to use opencode on a TypeScript project with AGENTS.md, strict mode, testing, monorepo tips, and how to avoid common type pitfalls.

**In short:**

- Configure AGENTS.md with exact build, test, lint commands and TypeScript rules so opencode uses your project conventions.
- Work in small typed steps, run tsc and tests after each change, and review diffs to keep the agent honest about type assumptions.
- Watch closely around generics, narrowing, and tsconfig strict settings; opencode can generate plausible code that still fails type-checking.

opencode is a terminal coding agent you start with `opencode` in the project folder. It reads your project files and any AGENTS.md instructions, then edits code and runs commands. For TypeScript, `tsc --noEmit` is the fastest reliable check, and strict mode turns type errors into concrete guidance. If you are new to the agent, see [How to use opencode: a step-by-step guide](/en/blog/how-to-use-opencode/).

## Type checking gives opencode a fast feedback loop

Concretely, TypeScript gives opencode a feedback loop that plain JavaScript does not. After each change the agent can run the compiler and read exact positions of type mismatches. This works especially well in strict mode, where `noImplicitAny`, `strictNullChecks`, and `noUncheckedIndexedAccess` make most invalid code fail at compile time. The agent can refactor a discriminated union, update a generic constraint, or replace `any` with inferred types, then verify with `tsc`. The limit is that opencode may still write plausible-looking code that only fails under complex type relationships, so you still need to review diffs and run the test suite.

## Make AGENTS.md your project contract

The most important file you can add is AGENTS.md in the repo root. Keep it short and command-focused. It should not explain what TypeScript is; it should tell the agent the exact commands, folder conventions, and rules that are easy to break. For general agent usage, see [opencode](/en/agents/opencode/); this guide focuses on TypeScript specifics.

A realistic AGENTS.md example:

```markdown
# AGENTS.md

## Commands
- Install: pnpm install
- Build: pnpm build (`tsc -b`)
- Test: pnpm test (`vitest run`)
- Lint: pnpm lint (`eslint .`)
- Typecheck: pnpm typecheck (`tsc --noEmit`)
- Typecheck one package: pnpm --filter @acme/api exec tsc --noEmit

## Folders
- packages/api/src: API route handlers and zod schemas
- packages/shared/src: domain types, utility types, no server-only imports
- packages/web/src: React components, only import from packages/shared

## TypeScript rules
- tsconfig.base.json enables strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes.
- Do not add `any`, `@ts-ignore`, or `@ts-expect-error` without an explicit reason in a comment.
- Prefer type predicates and `satisfies` over `as` casts.
- Keep generic constraints minimal; do not over-constrain `T` unless every caller needs it.
- After any edit, run `pnpm typecheck` and fix all errors before saying the task is done.
```

## How to run a TypeScript change loop

Treat each task as a cycle: plan the change in the prompt, let the agent edit one small scope, run typecheck and tests, then review the diff before moving on. Avoid asking for a large refactor and a new feature at the same time. If the agent runs into type errors, ask it to explain what it changed and paste the `tsc` output; don’t just accept a fix that adds a cast.

Example prompts for TypeScript tasks:

- "Refactor this function to remove the `any` return type. Keep all existing call sites type-correct and run typecheck."
- "Add a `status` field to the `Order` interface and update the discriminated union in `processOrder` so each branch narrows correctly."
- "Rewrite the generic `fetchList` function so it accepts readonly arrays and returns `ReadonlyArray<T>` without breaking existing callers."
- "Find all uses of `as` in `packages/api/src` and replace them with type predicates or `satisfies` where possible."
- "Move the `User` type from `packages/web` to `packages/shared` and update imports; run build and tests."

## What opencode gets right and where to watch closely

opencode handles mechanical, type-driven work well: extracting interfaces from object literals, updating function signatures across many files, changing generic bounds, converting enums to union types, and removing `any` when inference is obvious. It also does well with straightforward refactors like flipping optional properties or fixing import paths after moving types.

Watch closely for these TypeScript-specific pitfalls:

- **Casts**: the agent may add `as unknown as X` to silence errors. This hides real issues and breaks later. Require type predicates or `satisfies`.
- **Generic over-constraining**: the agent may add `extends SomeObject` to avoid an error but then rejects valid inputs. Check that constraints are truly needed.
- **Narrowing in callbacks**: narrowing does not persist inside callbacks. The agent may write code that reads an optional property after a check in a `setTimeout` and fails under `strictNullChecks`.
- **Strict optional and indexed access**: `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess` trip up the agent. It may assume optional property is always defined or indexed access returns `T` not `T | undefined`.
- **Monorepo project references**: the agent may run `tsc` at root and miss package-specific config, or import from a package not listed in references. Ask it to use the per-package typecheck command.
- **`satisfies` vs `as`**: the agent may use `satisfies` incorrectly when the value needs widening; verify that the inferred type is the one you want.

## Verify with tsc, tests, and CI

Make typecheck the first gate. The most useful command is `pnpm typecheck` or `pnpm exec tsc --noEmit`. After every agent turn, run it yourself before reviewing the diff. If the agent says tests pass, confirm by running the test script, because the agent may run a subset or not run tests at all. In CI, keep `tsc --noEmit` as a separate job from tests so type errors don’t hide behind a failing test suite. For monorepos, typecheck each touched package with `--filter` or project references.

| Command | What it verifies | When to run |
|---------|------------------|-------------|
| `pnpm typecheck` | Type errors under the project tsconfig | After every agent edit, before commit |
| `pnpm test` | Unit/component behavior | After typecheck passes; for behavior changes |
| `pnpm lint` | ESLint rules, including banned `any` or strict casts | Before review; catches style and unsafe patterns |
| `pnpm build` | Project references, emit, and monorepo boundaries | Before merge; catches cross-package import errors |

## Parallel agents with AgentVera for TypeScript

For TypeScript work across multiple agent sessions, AgentVera helps by running opencode and other CLI agents in parallel, each in its own git worktree, so agents don’t overwrite each other’s files while changing shared types. Its automatic code review from a second model catches type-level mistakes, and links findings to file:line, which is useful when a change spans several packages. Checkpoints let you undo a bad type refactor and replay the session. That combination matters because TypeScript changes often ripple through imports and generics.

## Keep the type gate tight

opencode is most useful on TypeScript when you give it precise compiler rules and a short loop. Keep AGENTS.md concrete, run `tsc --noEmit` after every change, review diffs around generics and narrowing, and use CI as the final type gate. That discipline turns a helpful coding agent into a reliable part of a typed codebase.

## Frequently asked questions

**Do I need a special setup to use opencode with a TypeScript project?** No, you can start with opencode in the project folder, but adding an AGENTS.md with your build, test, lint commands and TypeScript rules makes the agent far more reliable. Keep tsconfig.json checked in and tell the agent to run tsc --noEmit before considering a change done.

**Can opencode run tsc and fix type errors automatically?** Yes, opencode can run tsc --noEmit and other npm scripts itself in the terminal. It can iterate on type errors, but for complex generics or narrowing it may need your guidance in the prompt.

**How do I make opencode follow strict TypeScript mode?** State in AGENTS.md that strict mode is enabled and that the agent must not weaken types with any unless explicitly allowed. Include strict: true in tsconfig.json and add a rule like 'always run tsc --noEmit after changes'.

**Does opencode work with TypeScript monorepos?** Yes, but be explicit about workspace boundaries and package-specific tsconfig files. Put in AGENTS.md the package layout, the command to type-check only changed packages, and instructions to avoid cross-package import cycles.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/