SuperCode

SuperCode is a production-grade AI coding assistant CLI built with strict TypeScript on Node.js 20+.

It provides a Code-style terminal workflow for understanding, editing, refactoring, and generating code across local repositories, with interchangeable LLM providers.

Features

• Multi-provider AI abstraction:
  • Anthropic Claude
  • OpenAI
  • Google Gemini
  • DeepSeek
  • OpenRouter
  • Ollama (local)
• Real-time streaming responses in terminal
• Repository context builder with relevance + recency prioritization
• AI-powered file editing with unified diff preview and confirmation before apply
• Shell command execution in project root (/run)
• Repository summarization (/summary)
• Conversation memory in-session
• Plugin hook surface (beforeModelCall, afterModelResponse)
• Improved CLI presentation (status panels, structured output, provider-aware prompt)

API Key Management

SuperCode stores provider API keys locally and reuses them across sessions.

• Config path: ~/.supercode/config.json
• Keys are masked when displayed
• Keys are never intentionally printed in logs
• First-time provider setup prompts for key when missing
• Key is validated with a small provider request before saving
• Invalid/expired key flow prompts update automatically

Example ~/.supercode/config.json:

{
  "providers": {
    "openai": {
      "apiKey": "sk-xxxx"
    },
    "claude": {
      "apiKey": "sk-ant-xxxx"
    },
    "gemini": {
      "apiKey": "xxxx"
    }
  }
}

Commands

• /help
• /provider
• /provider <name> [model]
• /apikeys
• /apikey add <provider>
• /apikey remove <provider>
• /apikey test [provider]
• /files [pattern]
• /run <command>
• /summary
• /exit

Notes:

• Ollama does not require an API key.
• SuperCode checks whether Ollama is reachable locally.

Project Structure

supercode/
|-- bin/
|   `-- supercode.ts
|-- src/
|   |-- cli/
|   |   |-- index.ts
|   |   `-- ui.ts
|   |-- core/
|   |   |-- agent.ts
|   |   |-- apiKeyManager.ts
|   |   |-- commandRunner.ts
|   |   |-- contextBuilder.ts
|   |   `-- fileEditor.ts
|   |-- providers/
|   |   |-- claudeProvider.ts
|   |   |-- deepseekProvider.ts
|   |   |-- geminiProvider.ts
|   |   |-- ollamaProvider.ts
|   |   |-- openaiProvider.ts
|   |   |-- openrouterProvider.ts
|   |   |-- provider.ts
|   |   `-- providerFactory.ts
|   |-- types/
|   |   `-- index.ts
|   |-- utils/
|   |   |-- apiKeyStore.ts
|   |   |-- config.ts
|   |   |-- fileScanner.ts
|   |   `-- logger.ts
|   `-- index.ts
|-- .env.example
|-- package.json
|-- tsconfig.json
`-- README.md

Installation

npm install
npm run build

Run:

npm start

Development:

npm run dev

Configuration

Copy .env.example to .env and optionally set defaults:

SUPERCODE_PROVIDER=claude
SUPERCODE_CONTEXT_MAX_FILES=12
SUPERCODE_CONTEXT_MAX_CHARS=24000

Provider model and base URL overrides are also supported in .env.

You can still set API keys in .env, but SuperCode key management commands persist them to ~/.supercode/config.json.

Usage

Start:

npx supercode

Startup flow:

1. SuperCode UI loads first.
2. You select provider with an interactive selector.
3. You select model with an interactive selector.
4. SuperCode validates API key (and prompts only if missing/invalid).

Provider selection:

npx supercode --provider claude
npx supercode --provider openai
npx supercode --provider gemini
npx supercode --provider deepseek
npx supercode --provider openrouter
npx supercode --provider ollama

In-session key setup example:

/provider openai
OpenAI API key not found.
Enter your OpenAI API key:

After validation, the key is saved and reused automatically.