# opencode for Node.js Projects: A Practical Guide

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

Learn how to run opencode on a Node.js project: set up AGENTS.md, use safe working loops, verify with npm test, and avoid ESM and lockfile pitfalls.

**In short:**

- Set up an AGENTS.md with npm scripts, module style, and test commands so opencode follows your Node.js project’s conventions.
- Work in small steps: ask for a plan, review diffs, and run npm test and lint after every agent change.
- Watch for Node-specific pitfalls like ESM/CJS interop, package-lock changes, and environment variable leakage.

Running [opencode](/en/agents/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.

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

Keep 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](/en/blog/how-to-use-opencode/).

## 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)](/en/blog/best-tools-parallel-ai-coding-agents/) 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.

## Frequently asked questions

**How do I start opencode in a Node.js project?** Run opencode in the project folder where package.json and AGENTS.md live. The agent reads AGENTS.md and can run the npm scripts defined there.

**Does opencode work with npm, pnpm, or yarn?** Yes. opencode runs whatever package manager commands are in your AGENTS.md or package scripts. There is no special integration; just keep the lockfile consistent and use the same package manager in every prompt.

**Can opencode run and debug Node.js tests?** It can run npm test, read failures, and adjust code, but it does not attach an interactive debugger. Use logs and stack traces from test output, and reserve interactive debugging for yourself when needed.

**What should I put in AGENTS.md for a Node.js project?** Include exact build, test, lint, and run commands, the module system, folder conventions, environment variable rules, and any Node.js-specific rules such as no direct process.env access. Keep it short and command-focused.

---

**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/