Running opencode in a Node.js project means treating it as a senior colleague that can read your package.json, execute npm scripts, and edit files. You get the most value when the project is explicit about commands, module style, and conventions. This guide focuses on Express or Fastify, ES modules, node:test or Jest, and npm scripts.
Why opencode works well with Node.js
opencode is a command line coding agent that you start from the project directory with opencode; it picks up project instructions from AGENTS.md and can run your existing Node.js tooling. For Node.js work, that matters because npm scripts, test runners, and linters are already the source of truth for common tasks. The agent can inspect package.json to understand dependency relationships, execute npm test to see real failures, and read stack traces from Node.js errors. It also handles ES module import graphs well when you use explicit file extensions and avoid ambiguous barrel files. In short, opencode fits Node.js because it works through the same commands and files you already use, not through a separate abstraction.
Set up the project for the agent with AGENTS.md
Put an AGENTS.md in the project root. opencode reads it on startup, so keep it short, factual, and command-focused. For a Node.js project, include the exact npm scripts you expect the agent to use, the module system, folder conventions, environment variable handling, and any Node.js-specific rules that prevent common mistakes. If you use Express or Fastify, state the entry point and how the server is started in development.
# AGENTS.md
## Commands
- Install: `npm ci`
- Run dev server: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`
## Project layout
- `src/` contains ES modules; use `import`/`export`, no `require`
- `test/` contains Jest unit and integration tests
- `config/env.js` is the only place that reads `process.env`
## Node.js rules
- Keep `"type": "module"` in package.json; do not change it
- Never edit package-lock.json manually; use `npm install <pkg>`
- Prefer built-in `node:` modules over small dependencies
- Always handle promise rejections in request handlers and middleware
- Use `config/env.js` for all environment variables; no direct `process.env` outside itKeep the file under one screen; the agent does not need a novel. If you switch between Express and Fastify or between Jest and node:test, update the commands and folder notes accordingly.
A practical working loop for Node.js changes
Use a plan-first loop: ask opencode to inspect the relevant files and propose a small change, then review the proposed diff before accepting. After each accepted change, run npm test and npm run lint yourself or tell opencode to run them. Review git diff carefully, especially around package.json and package-lock.json. Keep the agent to one logical change per turn.
| Task | Good prompt |
|---|---|
| Add a route | “Add a GET /users route to this Fastify app. Use the existing UserService in src/services/user-service.js and return JSON.” |
| Write a failing test | “Write a node:test for the /health endpoint that checks status 200 and JSON body. Run only that test file.” |
| Refactor env access | “Move all direct process.env reads in src/ into config/env.js. Keep the existing exported names and update tests.” |
| Separate app and server | “Refactor src/server.js so app creation is separate from listen, and export the app for tests. Do not change the listen port default.” |
When opencode proposes a diff, ask for a summary of changed files and why. For Node.js, verify that new dependencies are actually used, that imports resolve with the project’s module resolution, and that no console.log debugging artifacts remain. If the agent suggests a package update, require it to show npm outdated or the changelog before accepting. Node.js apps often break silently when a transitive dependency changes, so prefer npm ci over npm install for installs in automated loops. For a step-by-step walkthrough of the basics, see How to use opencode: a step-by-step guide.
Where opencode excels and where it slips on Node.js
opencode handles common Node.js tasks well: adding HTTP routes, middleware, validation, service modules, and test skeletons. It is also useful for converting callbacks to async/await, updating imports after a file move, and updating dependencies with npm install. However, Node.js has specific failure modes that need close review. Watch especially for:
- ESM/CJS interop: the agent may add a require in an ES module or omit file extensions in relative imports.
- package-lock.json changes: accidental or broad dependency updates can break lockfile determinism.
- Top-level await: the agent may use it in a file that is not a module or in a CommonJS file.
- Environment variables: it may read process.env directly or introduce secrets into source.
- Test false positives: a test file with no assertions or with a skipped suite still exits 0.
- Event loop leakage: the agent may forget to close database connections or intervals, causing tests or the server to hang.
For Express work, ask it to add error-handling middleware and route-level validation. For Fastify, it can add schemas and plugins, but watch that serialization rules are not overridden accidentally. In both cases, ensure the agent does not leave synchronous JSON parsing in request handlers for large payloads.
Verify every change with Node.js tests
Make verification non-negotiable. After every code-generating turn, have opencode run npm test and npm run lint, and ask it to paste the test output. If the project uses Jest, npm test -- --runInBand avoids worker flakiness in some setups; if it uses node:test, node --test works without extra configuration. For a change that touches a specific module, ask for the relevant test file to be run first. Check that the agent did not modify test files to make them pass unless you asked for it. For environment-dependent code, run the tests with a local .env file or with NODE_ENV=test set explicitly. A final git diff --stat plus git diff review of non-test files should close every loop.
Run multiple opencode agents in parallel on a Node.js project
On a larger Node.js project, AgentVera runs opencode and other CLI agents side by side in real terminal panels, each in its own git worktree so parallel agents do not overwrite each other’s files. Automatic code review by a second model catches Node.js mistakes such as broken imports or missing error handling, with findings linked to file:line. Checkpoints let you undo an agent turn and replay a session, which is useful when an npm install or test refactor goes wrong. Token budgets per agent keep a long debugging session from consuming your entire account. See Best tools to run AI coding agents in parallel (2026) for the parallel workflow.
Final notes
Treat opencode on a Node.js project as a fast implementer, not a replacement for your judgment. A precise AGENTS.md, a small-step loop, and strict test verification will keep the agent effective. When a feature grows beyond a single agent’s context, isolate work in git worktrees with AgentVera and review the diffs the same way you would from a human colleague.