Mikado - A CLI Coding Agent

A simplified, production-quality MVP of a terminal coding agent built with TypeScript, Node.js 22+, and the official Google GenAI SDK (@google/genai). Inspired by Claude Code.

Features

• 100% Free to Use: Powered by Google AI Studio's free tier for Gemini models (default: gemini-2.5-flash).
• Autonomous Tool Execution: Read files, write files, inspect directory trees, and execute shell commands.
• Safety First: Interactively requests user confirmation before running shell commands ([y/N]).
• Interactive & One-Shot Modes: Run single prompt tasks or start interactive multi-turn chat sessions.
• Streaming Terminal Output: Real-time text output with status progress spinners (Reading src/index.ts, Writing package.json, Running npm install).
• Clean Architecture: Modular TypeScript with strong typing, Zod schema validation, and graceful error handling.

Tech Stack

• Language: TypeScript
• Runtime: Node.js 22+
• Package Manager: pnpm
• LLM SDK: @google/genai (Google GenAI SDK)
• Key Libraries:
  • commander - CLI argument parsing
  • zod - Runtime schema validation
  • chalk & ora - Console styling and progress indicators
  • execa - Shell execution
  • @inquirer/prompts - Interactive user prompts
  • dotenv - Environment variable management

Prerequisites

• Node.js v22.0.0 or higher
• pnpm (npm install -g pnpm)
• A Free Gemini API Key from Google AI Studio.

Installation & Setup

1. Clone & Install Dependencies

   pnpm install

2. Configure Environment Variables Copy .env.example to .env and add your free Gemini API Key:

   cp .env.example .env

   Edit .env:

   GEMINI_API_KEY=your_gemini_api_key_from_ai_studio
   GEMINI_MODEL=gemini-2.5-flash

3. Build the Project

   pnpm build

Usage

Single-Prompt Command Mode

Run tasks directly from the command line:

pnpm start -- "create an express server in src/server.ts"

or if linked globally (pnpm link --global or npm link):

agent "create an express server"
agent "fix authentication bug"
agent "add docker support"

Interactive Chat Mode

Start a multi-turn interactive session:

pnpm start chat

or

agent chat

To exit the interactive chat session, type exit or quit.

Available Tools

1. read_file(path): Returns text contents of a file.
2. write_file(path, content): Creates or overwrites files (automatically creates missing directories).
3. list_directory(path): Generates a recursive tree view of directories (skipping clutter like node_modules and .git).
4. run_shell(command): Executes shell commands after requesting interactive confirmation.

Project Structure

src/
├── cli.ts             # CLI command definition & entrypoint
├── agent.ts           # Coding agent loop & tool orchestration
├── llm.ts             # Google GenAI SDK client wrapper & streaming
├── config.ts          # Environment configuration loading & validation
├── prompts.ts         # System instructions prompt
├── types.ts           # TypeScript interfaces & types
└── tools/
    ├── readFile.ts      # read_file tool implementation
    ├── writeFile.ts     # write_file tool implementation
    ├── listDirectory.ts # list_directory tool implementation
    ├── runShell.ts      # run_shell tool implementation
    └── index.ts         # Tool registry & execution router

License

MIT