Architecture

Supercode CLI is a terminal-based AI coding agent built with TypeScript on Bun. This document describes its architecture, components, and data flow.

System Overview

The system consists of two main components:

  1. CLI App — Commander-based terminal application (Bun/TypeScript)
  2. API Server — Express server for auth, AI proxy, and persistence (deployed on Render)
~ $
┌─────────────┐ ┌──────────────┐ ┌──────────┐ │ Terminal │ ─────► │ API Server │ ─────► │ AI │ │ (Bun/CLI) │ ◄───── │ (Express) │ ◄───── │ Providers│ └─────────────┘ └──────────────┘ └──────────┘ │ ▼ ┌──────────┐ │PostgreSQL│ │ (Prisma) │ └──────────┘

CLI App (supercode-cli)

The CLI is the primary interface. It handles:

  • User authentication (device code flow)
  • Project initialization and taste profiling
  • AI interaction (Chat, Tools, Agent modes)
  • File system operations and command execution

API Server

The server acts as a secured proxy between the CLI and AI providers:

  • Manages authentication sessions via Better-Auth
  • Proxies AI requests (API keys stay server-side)
  • Stores conversations and messages in PostgreSQL
  • Handles device authorization flow

Database Schema

User

  • GitHub-authenticated user accounts
  • Links to sessions, accounts, and conversations
  • Stores provider API keys (encrypted)

Session

  • Better-Auth session management
  • Tracks expiry, IP, and user agent
  • 30-day inactivity timeout

Account

  • OAuth provider accounts (GitHub)
  • Stores access/refresh tokens and scopes

DeviceCode

  • Device authorization grant codes
  • 10-minute TTL with polling status tracking
  • Used for CLI authentication flow

Conversation

  • AI chat sessions
  • Supports three modes: chat, tools, agent
  • Each conversation belongs to a user and contains messages
  • Tracked by title, mode, and creation date

Message

  • Individual messages within conversations
  • Roles: user, assistant, system, tool
  • Stores raw content and metadata
  • Ordered by creation timestamp

CLI Flow

Entry Point

~ $
supercode <command>

The CLI outputs a styled banner and registers commands via Commander.js.

Commands

  • login — Device code authentication via GitHub OAuth
  • init — Start an interactive AI coding session
  • --version — Print version
  • --help — Show help

Init Flow

  1. Auth check — Read stored token → authenticate with server (GET /api/user/me)
  2. Workspace scan — Analyze project structure, language, dependencies
  3. Provider prompt — Select AI provider and model
  4. Mode prompt — Choose Chat, Tools, or Agent
  5. Interactive loop — Launch the chosen mode
~ $
supercode → ✓ Authenticated as yashdev9274 → Scanning workspace... (Next.js, TypeScript, Tailwind) → Select provider: [Gemini / OpenRouter / MiniMax] → Select mode: [Chat / Tools / Agent] → Ready. Type your prompt.

AI Modes

Chat Mode

Direct conversation with the AI. Workspace context is sent as a system prompt. Best for questions, explanations, and code review.

Tools Mode

AI has file system access via tool calls:

  • read — Read file contents
  • search — Full-text search across files
  • grep — Pattern matching in files
  • ls — List directory contents

Best for changes that need file exploration.

Agent Mode

Autonomous coding agent that can read, write, and execute shell commands:

  • Full file read/write/create/delete
  • Command execution with output capture
  • Multi-step reasoning and planning
  • Git-aware operations (status, diff, commit)

Best for building features, refactoring, and debugging.

API Endpoints

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/auth/* | Any | Better-Auth routes (OAuth, sessions) | | /api/user/me | GET | Current user info | | /api/conversations | POST | Create/get conversation | | /api/conversations/:id/messages | GET/POST | Message history / new message | | /api/conversations/:id/mode | PUT | Update conversation mode | | /api/conversations/:id/title | PUT | Update conversation title | | /api/ai/chat | POST | Streaming AI chat (proxied) | | /api/ai/generate-object | POST | Structured generation |

AI requests are proxied through the server so API keys remain server-side.

Supported AI Providers

| Provider | Models | Key Required | |----------|--------|--------------| | Google Gemini | gemini-2.5-flash, gemini-2.0-flash | Server-configured | | OpenRouter | gpt-oss-120b, deepseek-v4-flash, claude-3.5 | Server-configured | | MiniMax | MiniMax-M2 | Server-configured | | NVIDIA NIM | minimax-m2.7, deepseek-v4-flash, llama-3.3-70b | Server-configured |

API keys are configured server-side via environment variables.

Deployment

Server

  • Platform: Render (free tier)
  • Port: 10000 (default)
  • Runtime: Node.js / Express
  • Database: PostgreSQL via Prisma ORM

Cold Start Notes

  • Free tier spins down after 15 minutes of inactivity
  • Cold start takes 30-60 seconds
  • First CLI request after inactivity will fail — wait and retry

Security Architecture

  • AI provider API keys stored server-side only (encrypted database columns)
  • Session tokens encrypted with BETTER_AUTH_SECRET
  • GitHub OAuth handled entirely server-side
  • All production traffic over HTTPS
  • Device codes have 10-minute TTL
  • CLI stores only a session token locally (~/.supercode/token.json)