Gemini CLI is a terminal coding agent you start in a Node.js project folder by running gemini. It reads your code, edits files, and runs commands such as npm test, npm run lint, and node --test, which makes it a natural fit for Express or Fastify work. This guide focuses on Node.js-specific setup and workflow: the GEMINI.md contract, small change loops, test gates, and parallel agent use. For command basics, see the Gemini CLI page.
How Gemini CLI maps to Node.js workflows
Node.js projects already define almost everything an agent needs in plain text: package.json scripts, test files, lint config, and module conventions. Gemini CLI can follow those signals instead of guessing. It handles async/await patterns, ESM imports, and npm lifecycle commands well when the project gives it a short contract. Since Node.js backends often consist of small, testable units such as route handlers, services, and middleware, the agent can make changes and verify them with node --test, Jest, or npm run lint without learning a new tool. This reduces the loop between a prompt and a passing test suite. The agent can also inspect runtime errors from node and adjust code on the next pass, which is a more direct feedback loop than static analysis alone. It works particularly well with Fastify and Express because their request/response model is explicit: a route handler receives a request and returns or sends a response, making it easy for the agent to add an endpoint and test it against the documented behavior.
Give the agent a GEMINI.md contract
The most important file is GEMINI.md, placed in the project root. Keep it short and actionable: the agent reads it as project instructions before acting. For Node.js, include the exact install, test, build, and lint commands; the module system; where source, tests, and config live; and a few hard rules. The following file works for a small Fastify API using node:test and ES modules:
# Commands
install: npm ci
test: npm test
build: npm run build
lint: npm run lint
start: npm run dev
# Project layout
- src/ contains route handlers, services, and app entry.
- test/ contains node:test files named *.test.js.
- config/ holds environment-specific settings; use .env only locally.
# Node.js rules
- Use ES modules (`"type": "module"` in package.json).
- Prefer Fastify; keep handlers async and use `return reply.send(...)`.
- Do not edit package-lock.json manually; use npm install <pkg>.
- Run `npm test` and `npm run lint` after any source change.
- Do not commit .env files; add new variables to .env.example.Treat GEMINI.md as a contract. If the agent starts adding dependencies, it should use npm install so package-lock.json stays consistent. If you use npm workspaces, add the workspace commands and folder boundaries to the same file. Keep the rules specific: no committing .env, always run tests after source changes, and do not change the module system without an explicit instruction. Update GEMINI.md whenever you change the test runner, add a workspace, or move folders; an outdated contract makes the agent do plausible but wrong things like running npm start instead of npm run dev.
Run a tight change-and-test loop
Use a tight loop: agree on the smallest next change, let the agent edit, run the project’s tests, review the diff, then commit or adjust. Avoid large ‘build a full API’ prompts; break them into endpoints, middleware, or modules. The how-to guide on Gemini CLI covers this interaction model in more detail. Example prompts for typical Node.js tasks:
- Add a GET /health route to the Fastify app that returns
{ status: 'ok' }and add a node:test case for it. - Refactor the Express error handler to use an async wrapper so rejected promises return 500 instead of hanging.
- Add zod validation to POST /users and return a 400 response with the first validation error message.
- Replace the current logger with pino and update the request logging middleware, then run npm test.
- Update the npm test script to run node —test with a 10-second timeout and ensure all tests pass.
After each prompt, run npm test yourself or let the agent do it, but always inspect git diff before merging the change. Check that no package-lock.json changes arrived without a corresponding dependency change. If a test fails, paste the exact output back to the agent; it is usually enough to identify the regression. For a more conversational rhythm, see AI pair programming.
Where Gemini CLI excels and where to double-check
Gemini CLI handles many routine Node.js tasks well: adding endpoints, writing tests, moving logic into services, updating imports for ESM, converting callbacks to async/await, and adding validation or logging. It is less reliable around package manager side effects, native modules, subtle event loop behavior, and production configuration. Watch closely when the agent changes package.json, docker-compose or deployment files, or anything involving process.exit or unhandled rejections. It may add a dependency that already exists in devDependencies, switch from node:test to a heavier runner without being asked, or silently turn a CJS module into ESM and break a require caller. The table below highlights the areas where you should review its work most carefully.
| Area | What Gemini CLI does well | Watch closely |
|---|---|---|
| Route handlers | Adds endpoints and tests | Ensure reply/return semantics match framework |
| Async code | Converts callbacks to async/await | Prevent unhandled rejections and blocking the event loop |
| Package management | Runs npm install | Lockfile consistency, unnecessary dependencies |
| Environment config | Creates .env.example | Never commit real secrets; validate required variables |
One specific Node.js pitfall is unhandled promise rejections: the agent may add an async function without a try/catch or without returning a promise from an Express handler, causing a silent hang in older runtime versions or an unhandled rejection warning. Another is the event loop: it may add a CPU-bound loop in a request handler that blocks all other requests. Review any code that performs synchronous file I/O, large JSON parsing, or heavy computation inside a route.
Make tests the feedback gate
Testing is the best contract for Node.js work. Keep the test command fast and deterministic: node --test or npm run test -- --runInBand for Jest. Tell the agent to run the suite after each change, and add new tests for every new endpoint or behavior. If the agent breaks a test, give it the exact failing output; it can often fix the regression in one step. For async routes, ask for at least one happy path and one error path test. Use npm run lint as a second gate. A useful verification loop is: npm test, npm run lint, then git diff --stat to see the blast radius. Also check that the agent did not skip a test by using .skip or .only accidentally. When working with node:test, make sure the agent uses assert/strict and not a browser-style assertion library; subtle differences in deep equality can hide bugs. For Jest projects, keep the agent away from snapshots unless you explicitly maintain them, because snapshot updates can mask intended changes.
Parallel agents with isolated worktrees
AgentVera, a desktop app, runs several coding agents including Gemini CLI in parallel real terminal panels. On a Node.js project, the most useful pieces are parallel git worktrees, so agents do not overwrite each other’s edits to package.json or src/routes; automatic code review that links findings to file:line after each turn; checkpoints that snapshot every turn and can be undone in one click; and token budgets that stop a runaway agent before it exhausts your API limit. These keep branching, dependency changes, and async error handling under control. See the AI agent orchestration guide for more patterns.
Keep Node.js changes small and verified
Gemini CLI works well on Node.js projects when you give it a clear GEMINI.md and a fast test loop. Keep prompts small, verify with npm test, and review diffs before committing. For parallel work, isolate agents in separate worktrees and use code review and checkpoints to keep the project stable.