Quick Start Guide
From installation to your first conversation — master SpectrAI in 5 minutes
1
Install & Launch
Download & Install
- Go to the download page and grab the installer for your OS
- Windows: double-click the
.exeinstaller and follow the setup wizard - macOS: drag the
.appinto Applications. If you see "app is damaged", see FAQ #3
Prerequisites
SpectrAI itself has no extra dependencies, but your chosen AI provider may require:
| AI Provider | Requirement | Install Command |
|---|---|---|
| Claude Code | Node.js 18+ | npm i -g @anthropic-ai/claude-code |
| Codex CLI | Node.js 22+ | npm i -g @openai/codex |
| Gemini CLI | Node.js 18+ | npm i -g @anthropic-ai/claude-code (built-in) |
| OpenAI-compatible API | None | API key + endpoint URL only |
2
Configure an AI Provider
Open SpectrAI → click Settings (gear icon) in the bottom-left → select the AI provider tab.
AI Provider settings: view, edit, and test all configured providers
Option 1: Use a built-in CLI tool (recommended)
Using Claude Code as an example:
- Install globally:
npm i -g @anthropic-ai/claude-code - Run
claude loginin your terminal to authenticate - Back in SpectrAI, find the Claude Code card and click Test to verify the connection
- If Test fails, set the Executable Path manually (see FAQ #4)
Option 2: Use an API key (third-party relay)
- Click "Add custom AI provider" at the bottom of the page
- Set Adapter Type to
OpenAI Compatible API - Fill in the API Base URL, API Key, and model name
- Save and you're ready to go
Add a custom AI provider: choose adapter type and fill in the API details
CLI-based providers (Claude Code, Codex, etc.) authenticate via their own command-line login — no API key needed in SpectrAI. See FAQ #1.
3
Create Your First Session
New session dialog: choose working directory, AI provider, and session mode
- Click the "+" button in the left sidebar to open the new session dialog
- Session name — customize or leave as the default timestamp
- Working directory — select your project folder; the AI will read, write, and run commands here
- Initial instruction (optional) — enter a task for the AI to start on immediately, or leave blank for interactive mode
- AI provider — select the provider you just configured (e.g. Claude Code)
- Session mode — for your first session, choose Normal
- Click "Create" and wait for the AI to initialize — then start chatting
Enabling "Auto-accept permission requests" lets the AI read/write files and run commands without prompting each time. Use in trusted project environments.
4
Three Session Modes Explained
Pick the mode that fits your task:
Normal
DefaultOne-on-one chat with the AI. The simplest and most-used mode.
- Coding Q&A
- Single-file edits
- Debugging
- Day-to-day dev
Supervisor
CommanderThe AI becomes a "project manager" that spins up multiple sub-agents to work in parallel.
- Large refactors
- Multi-file edits
- Parallel analysis
- Mix multiple AI models
Mission
MissionDescribe the goal and the AI plans, assembles a team, and executes autonomously.
- End-to-end delivery
- Automated teamwork
- Task decomposition
- Fully autonomous
Quick Mode Reference
| What I want to do | Recommended mode |
|---|---|
| Ask a coding question / fix a bug | Normal |
| Analyze dependencies across multiple files | Supervisor |
| Edit frontend + backend + tests at once | Supervisor |
| "Implement the full user registration feature" | Mission |
| "Refactor the project's state management" | Mission |
5
AI Provider Recommendations
Not sure which to use? Here's a quick guide:
Claude Code
Best all-around reasoning
Codex CLI
Code generation specialist
Gemini CLI
Long context understanding
OpenCode
Multi-model switching
iFlow CLI
Workflow integration
| Task type | Recommended | Why |
|---|---|---|
| Complex architecture, multi-file refactors | Claude Code | Best overall reasoning |
| Write code, fix bugs, add features | Codex CLI | Specialized in code generation |
| Large-file analysis, code review | Gemini CLI | Massive context window |
| Doc summarization, knowledge mapping | Gemini CLI | Excels at long-form comprehension |
| Multiple parallel sub-tasks | Mixed | Different AI perspectives complement each other |
In Supervisor mode, the main session can assign different AI providers to different sub-agents to leverage each model's strengths.