Gemini CLI is a terminal coding agent you start by running gemini in a TypeScript project folder. It reads your source files and GEMINI.md instructions, plans edits, runs commands, and iterates on compiler output. This guide shows a practical TypeScript workflow: strict project setup, type-aware prompts, verification with tsc and tests, and running multiple agents.
A strict tsconfig gives the agent clear feedback
Gemini CLI is not a separate type checker; it treats TypeScript as the source of truth and uses tsc --noEmit output as its main feedback loop. That means it can see the same strict-mode errors you see in your editor, including missing return types, overly broad generic inference, and lost type narrowing. It shines on cross-file refactors because it reads tsconfig.json, types.d.ts, and package boundaries from a monorepo instead of editing a single file in isolation. When you keep a strict tsconfig, the agent has a precise, machine-checkable contract, which reduces the vague suggestions common with untyped JavaScript work. Concretely, that makes tasks like changing an interface in packages/shared and propagating the fix through packages/api and packages/web much more reliable than doing the same search-and-replace by hand. However, you still need to review the types it chooses, especially around any, as, and @ts-ignore.
Prepare GEMINI.md with exact commands and TypeScript rules
Create a GEMINI.md in the project root. Gemini CLI reads this file on start, so it should contain the exact commands, folder layout, and TypeScript rules you want the agent to follow. The goal is to remove guesswork: if the agent proposes npm test but the project uses pnpm workspaces, it will run the wrong thing; if it does not know that any is banned, it may use it to silence errors. Keep the file short enough to read, but include every command an agent would need to verify its work. A realistic GEMINI.md for a pnpm monorepo with strict TypeScript looks like this:
# Project commands
build: pnpm run build
typecheck: pnpm exec tsc --noEmit
test: pnpm run test
lint: pnpm run lint
# Folder conventions
packages/*/src: source code
packages/*/test: tests
packages/*/tsconfig.json: package-level TypeScript config
# TypeScript rules
- Respect the root tsconfig.json and package tsconfig.json settings.
- Strict mode stays on: no `any`, no non-null assertions (`!`), no `@ts-ignore`, no `as` casts to silence type errors.
- Use type guards and explicit narrows instead of `as`.
- Prefer explicit return types on exported functions and generic constraints on public utilities.
- Do not edit tests to make a failure pass; change the implementation instead.
- When changing a type in one package, check all consumers inside the repo.Keep GEMINI.md in version control and update it whenever you add a new command or change a strict rule. The file is the contract between you and the agent; if tsc fails in CI but the agent did not run typecheck, it should be because the file did not say to run it.
Plan, patch, typecheck: a working loop for type-safe edits
Start with a clean working tree and a passing baseline: run typecheck and tests before asking anything. Then describe the task at the type level, not just the runtime behavior. Ask the agent to plan first, then make one small edit, then run verification. After each edit, run pnpm exec tsc --noEmit and the focused unit tests yourself before accepting the next step. Review git diff -- packages/*/src to see which types changed; a small prompt can hide a broad type change. Keep steps small enough that a single type error is easy to trace. For the basic command workflow, see How to use Gemini CLI: a step-by-step guide. Several useful prompts:
- Add a
Result<T, E>generic type inpackages/shared/src/result.ts, then updateAuthService.loginto returnResult<Session, AuthError>instead of throwing; run typecheck and the auth tests. - Refactor
parseConfigto acceptunknown, narrow the input with type guards, and remove allascasts; show the diff and typecheck output. - Find all
anyuses underpackages/api/src, propose specific replacements, and apply them one file at a time while keeping the public API unchanged. - Update the
Orderinterface inpackages/sharedto makediscountoptional, then fix all call sites inpackages/webandpackages/api; runpnpm -r typecheckand report the remaining errors. - Introduce a
Branded<T, Brand>helper and use it forUserIdandAccountIdin the domain layer, then run the domain tests.
Those prompts work because each names the exact files or packages, requires typecheck, and limits the change. Avoid broad instructions like improve the types; they tend to produce large diffs and unintended public API changes.
Where the agent handles TypeScript well and where to watch the diff
Gemini CLI is strongest when the compiler can verify the result. Good tasks include removing any, adding type guards, extracting a generic helper, updating an interface across packages, and changing a function signature with call-site fixes. It is weaker when the correct type is not fully present in the code: external API responses, runtime schema mismatches, or implicit any from untyped dependencies. In those cases, it may invent a type or use as any to quiet tsc. Watch the diff for weak types, broadened generics, or a change from unknown to any. Also watch that it does not change only the TypeScript source while leaving generated types, .d.ts files, or zod schemas out of sync. The table below shows common patterns.
| TypeScript task | Good prompt angle | Pitfall to watch |
|---|---|---|
Remove any | Replace any with the narrowest possible type; no as. | It may add unknown and then cast back with as to make code compile. |
| Make a function generic | Add a generic T with the same constraint used by the caller. | It can over-generalize and weaken inference or return types. |
| Propagate an interface change | Update all packages and run pnpm -r typecheck. | It may miss runtime code that does not use the type, like object literals outside src. |
| Fix tsc errors | Fix the root cause; do not add @ts-ignore or any. | It may silence errors with suppressions instead of narrowing. |
Verify compiler output before accepting any agent change
Verification should be compiler-first, then tests. After every agent turn, run pnpm exec tsc --noEmit in the affected package or workspace root before looking at unit tests. A TypeScript change can compile in one package and break another through declaration emit or shared types, so use the workspace-level command. Then run the focused test files for the changed code, and only then a full test suite if the change is cross-cutting. Do not accept a diff that passes tests but fails typecheck; the agent may have edited tests or added a suppression. If the agent reports a type error, ask it to reproduce with the same command and show the error, then fix the narrowest cause. For debugging type-level issues, a workflow like the one in How to debug code with AI: a practical workflow works well: share the exact tsc output, ask for a hypothesis, and require a minimal repro before a fix.
Run parallel Gemini CLI instances without file conflicts with AgentVera
AgentVera is a desktop app that runs Gemini CLI and other coding agents’ real command line tools side by side in one window, each in its own terminal panel. For TypeScript work, the most useful pieces are parallel agents in separate git worktrees, automatic code review with file:line findings, and turn checkpoints you can undo. Parallel worktrees keep strict-mode changes isolated so one agent cannot overwrite another while refactoring types across packages. After an agent finishes, a second model catches type holes such as a weakened generic or a missed @ts-ignore. Checkpoints let you roll back a bad refactor without losing the conversation.
Keep the loop tight: final advice
Gemini CLI earns its place in TypeScript work when the project rules are explicit, the steps are small, and the compiler is used as the final gate. Keep GEMINI.md current, review type diffs carefully, and isolate parallel work with tools like AgentVera when the scope grows. With that discipline, the agent becomes a fast pair programmer that respects your strict tsconfig instead of fighting it.