# Gemini CLI TypeScript: a practical developer workflow

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

Learn how to use Gemini CLI on TypeScript projects with strict tsconfig, type-safe prompts, GEMINI.md instructions, tsc in CI, and parallel agents.

**In short:**

- Gemini CLI uses tsc --noEmit as its main feedback loop, so strict tsconfig rules turn into machine-checkable instructions.
- Put exact build, test, and typecheck commands plus bans on any and @ts-ignore in GEMINI.md before asking for edits.
- Isolate parallel agents with git worktrees and review type diffs carefully to avoid weakened generics and suppressed errors.

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:

```markdown
# 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](/en/blog/how-to-use-gemini-cli/). Several useful prompts:

- Add a `Result<T, E>` generic type in `packages/shared/src/result.ts`, then update `AuthService.login` to return `Result<Session, AuthError>` instead of throwing; run typecheck and the auth tests.
- Refactor `parseConfig` to accept `unknown`, narrow the input with type guards, and remove all `as` casts; show the diff and typecheck output.
- Find all `any` uses under `packages/api/src`, propose specific replacements, and apply them one file at a time while keeping the public API unchanged.
- Update the `Order` interface in `packages/shared` to make `discount` optional, then fix all call sites in `packages/web` and `packages/api`; run `pnpm -r typecheck` and report the remaining errors.
- Introduce a `Branded<T, Brand>` helper and use it for `UserId` and `AccountId` in 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](/en/blog/debug-code-with-ai/) 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.

## Frequently asked questions

**How do I start Gemini CLI in a TypeScript project?** Run gemini from the project root where your tsconfig.json and GEMINI.md live. The agent reads those files automatically; after that you can describe TypeScript edits in plain English and ask it to run pnpm exec tsc --noEmit to verify.

**What should I put in GEMINI.md for TypeScript?** Include the exact typecheck, test, build, and lint commands, plus TypeScript-specific rules such as keeping strict mode on, no any, no @ts-ignore, and no as casts to silence errors. Also list the workspace folder layout so the agent knows where source and tests live.

**Can Gemini CLI handle strict TypeScript settings?** Yes, strict mode helps the agent because tsc gives unambiguous errors it can iterate on. You should still review the diff, because the agent may occasionally propose as any or @ts-ignore to make a type error disappear.

**How do I use multiple Gemini CLI agents on one TypeScript monorepo?** Run each agent in its own git worktree so changes do not overwrite each other. Tools like AgentVera can run Gemini CLI and other command line agents in parallel panels, and checkpoints let you undo a bad type refactor.

---

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