🤖 Koda — Terminal-Native AI Coding Assistant

A CLI-powered AI coding assistant with multi-agent workflows, powered by AI Mesh and Multica.

Koda runs inside your terminal (VS Code, Cursor, any shell) and uses a three-agent pipeline — Planner, Executor, Reviewer — to break down tasks, generate code, and validate output.

Table of Contents

• Installation
• User Flow
  • Step 1: Initialize
  • Step 2: Verify Config
  • Step 3: Chat
  • Step 4: Run a Task
  • Step 5: Multica Integration
• Commands Reference
• Agent Pipeline
• Project Structure
• Configuration
• Updating
• Uninstalling
• Development

Installation

Quick Install (recommended)

Windows (PowerShell):

irm https://koda.medinovai.com/install.ps1 | iex

macOS / Linux:

curl -fsSL https://koda.medinovai.com/install.sh | sh

These scripts check for Node.js >= 18, install Koda via npm, and verify the installation.

Prerequisites

• Node.js >= 18.0.0
• An AI Mesh API key (get one here)
• (Optional) Multica CLI for team task tracking (install)

Install manually via npm

npm install -g koda-cli-myonsite

Verify

koda -V
# → 1.0.0

That's it. The koda command is now available globally in any terminal.

User Flow

Step 1: koda init — First-Time Configuration

Run the setup wizard to configure your API key, provider, and model:

koda init

You'll see an interactive prompt:

  ╔═══════════════════════════════════╗
  ║  🤖 Koda — AI Coding Assistant   ║
  ╚═══════════════════════════════════╝

  Koda Setup

  Step 1: AI Mesh API Key
  Get your key at https://aimesh.myonsitehealthcare.com

  API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx

  Available Providers:

    1. openai      (gpt-4o, gpt-4o-mini, gpt-4.1-nano, gpt-4-turbo, o1, o1-mini)
    2. anthropic   (claude-sonnet-4, claude-3.5-haiku, claude-opus-4)
    3. gemini      (gemini-2.0-flash, gemini-2.0-pro, gemini-1.5-pro)
    4. perplexity  (sonar-pro, sonar, sonar-reasoning-pro)

  Select provider (1-4): 1

  Models for openai:

    1. gpt-4o
    2. gpt-4o-mini
    3. gpt-4.1-nano
    4. gpt-4-turbo
    5. o1
    6. o1-mini

  Select model: 1

  Custom AI Mesh URL (enter to skip):

  ✔ Koda initialized successfully!
    Configuration saved to ~/.koda/config.json
    Provider: openai
    Model:    gpt-4o

What happened: Config saved at ~/.koda/config.json with your credentials and defaults.

Step 2: koda config — Verify or Tweak Settings

View your current config:

koda config

Update individual values:

koda config --set model=gpt-4o-mini
koda config --set temperature=0.5
koda config --get provider

Step 3: koda chat — Talk to the AI

Navigate to any project directory and start an interactive chat:

cd ~/my-project
koda chat

Key features:

• Auto-detects your project (reads package.json, file tree, languages, frameworks)
• Maintains conversation context across messages
• Streams responses token-by-token in real time
• /clear resets conversation history; exit or quit ends the session
• Override model: koda chat --model claude-sonnet-4-20250514

Step 4: koda run — Assign a Task to the Agent Pipeline

Give Koda a task and three agents handle it end-to-end:

koda run "build a REST API with auth using Express and JWT"

The pipeline runs: Planner (breaks task into steps) → You (confirm plan) → Executor (builds code) → Reviewer (scores and validates)

Run Flags

koda run --dry-run "add OAuth to the app"
koda run --no-review "create a landing page"
koda run --model claude-sonnet-4-20250514 "refactor the auth module"
koda run --multica "build a REST API with auth"

Step 5 (Optional): koda multica — Connect to Multica for Team Workflows

koda multica --status
koda multica --issues
koda multica --agents

When you use koda run --multica, Koda will create a tracking issue, post results, and update status in Multica.

Commands Reference

| Command | Description | |---------|-------------| | koda init | Interactive setup — API key, provider, model | | koda chat | Streaming AI chat with project context | | koda chat -m <model> | Chat with a specific model | | koda chat -p <provider> | Chat with a specific provider | | koda run <prompt> | Full agent pipeline (Plan → Execute → Review) | | koda run --dry-run <prompt> | Show plan only, don't execute | | koda run --no-review <prompt> | Skip the reviewer agent | | koda run --multica <prompt> | Track run as a Multica issue | | koda config | View current configuration | | koda config --set key=value | Update a config value | | koda config --get key | Get a config value | | koda config --reset | Reset to defaults | | koda multica | Show Multica integration status | | koda update | Check for and install the latest version | | koda help [command] | Show help (general or per-command) | | koda -V / koda --version | Print version |

Agent Pipeline

| Agent | Role | What It Does | |-------|------|-------------| | Planner | Architect | Analyzes the task, breaks it into atomic steps, identifies dependencies | | Executor | Builder | Executes steps in dependency order, generates production-ready code | | Reviewer | QA | Reviews all generated code, scores 0–100, flags issues, recommends fixes |

Project Structure

koda/
├── cli/
│   ├── index.ts              # CLI entry point + command registration
│   └── commands/
│       ├── init.ts            # koda init — setup wizard
│       ├── chat.ts            # koda chat — interactive streaming chat
│       ├── run.ts             # koda run  — multi-agent pipeline
│       ├── config.ts          # koda config — view/update settings
│       ├── multica.ts         # koda multica — Multica integration
│       └── update.ts          # koda update — npm self-update
│
├── core/
│   ├── ai-mesh-client.ts      # OpenAI-compatible API client with SSE streaming
│   ├── agent-manager.ts       # Orchestrates Planner → Executor → Reviewer pipeline
│   ├── context-engine.ts      # Detects project languages, frameworks, structure
│   └── multica-client.ts      # Multica CLI wrapper (issues, agents, daemon)
│
├── agents/
│   ├── planner.ts             # Planner agent — task decomposition
│   ├── executor.ts            # Executor agent — code generation & file ops
│   └── reviewer.ts            # Reviewer agent — quality scoring & feedback
│
├── utils/
│   ├── file.ts                # File read/write/delete/diff utilities
│   └── logger.ts              # Colored logs, spinners, agent tags, streaming
│
├── config/
│   └── schema.ts              # Zod config schema, load/save/update
│
├── website-docs/              # Documentation website
│
├── package.json
├── tsconfig.json
└── README.md

Configuration

Config is stored at ~/.koda/config.json.

| Key | Type | Default | Description | |-----|------|---------|-------------| | apiKey | string | — | AI Mesh API key (required) | | provider | string | — | openai, anthropic, gemini, or perplexity | | model | string | — | Model name (e.g. gpt-4o, claude-sonnet-4-20250514) | | aiMeshBaseUrl | string | https://aimesh.myonsitehealthcare.com/v1 | AI Mesh API endpoint | | maxTokens | number | 4096 | Max tokens per response | | temperature | number | 0.7 | Sampling temperature (0–2) | | streamResponses | boolean | true | Stream responses token-by-token |

Updating

koda update

Or manually:

npm install -g koda-cli-myonsite@latest

Uninstalling

npm uninstall -g koda-cli-myonsite

Optionally remove config:

rm -rf ~/.koda

Development

git clone https://git.myonsitehealthcare.com/myOnsite/koda.git
cd koda
npm install
npm run build
npm link

npm run dev      # Watch mode
npm run clean    # Clean build output

Publishing a New Version

npm run release:patch   # 1.0.0 → 1.0.1
npm run release:minor   # 1.0.0 → 1.1.0
npm run release:major   # 1.0.0 → 2.0.0

This bumps the version and publishes to npm automatically.

License

MIT