GitHub - kstonekuan/gemini-workspacer: Gemini CLI as an agent harness for Google Workspace CLI (gws)

4 min read Original article ↗

Gemini Workspacer turns a rough idea into a Google Doc, Google Sheet, and Google Slides deck. It uses Gemini for planning and orchestration, then drives Google Workspace tools to generate polished artifacts.

What It Does

  • Starts with a chat-based planning flow that asks for clarification only when needed
  • Produces a structured draft plan with a concept title, summary, and goals for the Doc, Sheet, and Slides deck
  • Generates all three Google Workspace artifacts from that confirmed plan
  • Streams live server and Gemini CLI logs to the frontend during generation
  • Extracts final Workspace URLs deterministically from CLI output, with a Gemini SDK fallback if needed

How The App Works

  1. You describe an idea in the chat UI.
  2. /api/plan-chat sends the conversation to Gemini through @google/genai.
  3. Gemini either asks one follow-up question or returns a draft artifact plan.
  4. You keep chatting to revise the plan or confirm it.
  5. /api/generate runs the local gemini CLI with Google Workspace tools enabled.
  6. The server streams status updates and CLI logs back to the browser as NDJSON events.
  7. The app recovers the final Google Doc, Sheet, and Slides URLs and shows them in the results UI.

Tech Stack

  • Next.js 16 App Router
  • React 19
  • TypeScript
  • Tailwind CSS v4
  • Biome
  • Vercel AI SDK for the planning chat UI
  • TanStack Query for generation mutation state
  • Motion for UI animation
  • @google/genai for structured Gemini SDK calls
  • Gemini CLI for artifact execution

Requirements

You need all of the following available locally:

  • Node.js
  • pnpm
  • A valid GEMINI_API_KEY
  • The gemini CLI installed and authenticated
  • Google Workspace CLI tooling/extensions available to the Gemini CLI
  • A Google account you are comfortable creating test Docs, Sheets, and Slides in

This app is currently intended for localhost demo use only.

Setup

Install dependencies:

Create your local environment file:

Set the required variables in .env:

GEMINI_API_KEY=your_api_key
GEMINI_PLANNING_MODEL=gemini-3-flash-preview
GEMINI_PARSER_MODEL=gemini-3-flash-preview
GEMINI_CLI_COMMAND=gemini

Optional development flag:

NEXT_PUBLIC_ENABLE_AGENTATION=1

Running The App

Start the development server:

Then open:

Available Scripts

pnpm dev       # Start the local dev server
pnpm build     # Create a production build
pnpm start     # Run the production build
pnpm test      # Run Vitest tests
pnpm lint      # Run Biome with write-enabled fixes
pnpm format    # Format files with Biome
pnpm typecheck # Generate Next.js route types and run TypeScript
pnpm check     # Run lint + typecheck

Project Structure

app/
  api/plan-chat/route.ts   # Planning chat endpoint
  api/generate/route.ts    # Streaming generation endpoint
  layout.tsx
  page.tsx

src/components/
  gemini-workspacer-app.tsx        # Main app UI
  gemini-workspacer-providers.tsx  # React Query provider
  ai-elements/                     # Chat UI building blocks

src/lib/
  gemini-workspacer-domain.ts      # Shared schemas and types
  gemini-workspacer-service.ts     # Gemini SDK + Gemini CLI orchestration
  gemini-workspacer-service.test.ts

Environment Variables

GEMINI_API_KEY

  • Required.
  • Used for Gemini SDK planning and fallback parsing.

GEMINI_PLANNING_MODEL

  • Optional.
  • Model used for the planning phase.
  • Defaults to gemini-3-flash-preview if not set.

GEMINI_PARSER_MODEL

  • Optional.
  • Model used only when deterministic link extraction fails.
  • Defaults to gemini-3-flash-preview if not set.

GEMINI_CLI_COMMAND

  • Optional.
  • Command used to launch the local Gemini CLI.
  • Defaults to gemini.

NEXT_PUBLIC_ENABLE_AGENTATION

  • Optional.
  • Enables the development-only agentation toolbar.

Notes On Generation

  • Artifact generation can take several minutes.
  • The app streams Gemini CLI output to the frontend so you can inspect what it is doing.
  • Final artifact links are extracted from raw CLI output with a deterministic parser first.
  • If the deterministic parser cannot recover all three URLs, the app falls back to a structured Gemini SDK extraction step.
  • The app encourages Docs and Slides to use stronger layout, formatting, and native Slides elements like shapes, callouts, dividers, timelines, and simple diagrams.

Limitations

  • This is a localhost-first demo app, not a hardened multi-user service.
  • Generated artifacts are created in the authenticated Google account available to your CLI/tooling setup.
  • Gemini CLI failures can still happen due to quota limits, tool issues, or network instability.
  • Image insertion quality depends on what the available Workspace tools and reachable image sources can actually support at runtime.

Testing

Current tests focus on real business logic rather than mocked internals. Right now the main regression coverage is around deterministic extraction of the final Google Workspace URLs from Gemini CLI output.

Run tests with:

Development Notes

  • Use pnpm check before finishing changes.
  • Use pnpm build to verify the app still produces a production build.
  • Formatting and linting are handled with Biome.
  • The codebase uses explicit Zod schemas and typed variants heavily to keep invalid states out of the UI and route handlers.