Technical Specifications

Barnaby is an Electron + React desktop IDE for multi-agent orchestration. It supports windowed agent panels, workspace-aware context, CLI-connected providers (Codex, Claude, Gemini), and API-connected providers (OpenRouter and OpenAI models inside the Codex provider path).

Core Capabilities

Up to 5 concurrent agent panels with horizontal/vertical/grid layouts
Workspace locking with stale-lock recovery for multi-instance safety
Provider routing across codex, claude, gemini, and openrouter
Streaming chat with markdown rendering and operation traces
Queue-aware sending, reconnect flow, and auto-scroll behavior
Session persistence via local app state storage keys
Panel interaction modes: agent, plan, debug, ask
Workspace window with file explorer, source control, and terminal
Connectivity checks plus per-model ping support

Installation & Build

Download or npm

Download: GitHub Releases (Windows portable and installer builds).
npm (Node.js 20+): npx '@barnaby.build/barnaby' or npm install -g '@barnaby.build/barnaby'

PowerShell: Use single quotes around @barnaby.build/barnaby. Without quotes, @ is interpreted as a variable.

Windows (npm): A Start menu shortcut is created on global install. For correct taskbar icon, pin the shortcut (not the running window).

Barnaby does not auto-install provider CLIs. Install and authenticate provider tools before first use.

Prerequisites

Node.js >=20 <27 (recommended: Node 22 LTS)
CLI providers (optional): Codex, Claude Code, Gemini CLI
API providers (optional): OpenRouter API key and/or OpenAI API key (for Codex API models)

# Verification commands
codex --version
claude --version
gemini --version

Build From Source

# Initialize environment
npm install
npm run dev

# Packaged Outputs
npm run build              # Default local portable build path
npm run build:dist         # Renderer + electron dist build
npm run build:portable     # Portable with version bump
npm run build:release      # Installer + portable outputs

Latest Verified Build (Local Codebase)

Item	Value
Package version	`0.0.224`
Windows portable artifact	`release/0.0.224/Barnaby_0.0.224_portable.exe`
Windows installer payload	`release/0.0.224/@barnaby.buildbarnaby-0.0.224-x64.nsis.7z`
Observed build timestamp (local)	March 9, 2026 (Auckland time)

Supported Provider Catalog

Provider	Type	Setup	Upgrade / Notes
Codex / OpenAI	CLI + API (limited model IDs)	`codex login`	`npm update -g '@openai/codex'`
Claude	CLI	`claude`	`npm update -g '@anthropic-ai/claude-code'`
Gemini	CLI	`gemini`	`npm update -g '@google/gemini-cli'`
OpenRouter	API	API key: `https://openrouter.ai/keys`	Configured in Application Settings -> Connectivity

Model Accessibility

Model lists are queried at runtime from provider sources, with built-in fallback catalogs. Availability depends on your CLI login state, API keys, and subscription tier.

Discovery Logic

Codex: Reads ~/.codex/models_cache.json when present.
Claude: Uses Anthropic Models API when API key is present; otherwise fallback catalog + aliases.
Gemini: Uses Google Models API when API key is present; otherwise gemini list models; then fallback catalog.
OpenRouter: Uses /api/v1/models, preferring free-tier models and capping list size.

Codex / OpenAI Model Catalog

ID	Display Name
`gpt-5.3-codex`	gpt-5.3-codex (default)
`gpt-5.4`	gpt-5.4
`gpt-5.2-codex`	gpt-5.2-codex
`gpt-5.1-codex-max`	gpt-5.1-codex-max
`gpt-5.1-codex-mini`	gpt-5.1-codex-mini
`gpt-5.2`	gpt-5.2

Other Codex models are routed through Codex App Server (CLI-based). API model IDs (gpt-4o, gpt-4o-mini, gpt-4-turbo) are also supported via the OpenAI API path.

Gemini Fallback Catalog (Built-In)

ID	Display Name
`gemini-2.5-flash`	Gemini 2.5 Flash
`gemini-2.5-flash-lite`	Gemini 2.5 Flash Lite
`gemini-2.5-pro`	Gemini 2.5 Pro
`gemini-3-pro-preview`	Gemini 3 Pro (Preview)
`gemini-3-flash-preview`	Gemini 3 Flash (Preview)

Claude Fallback Catalog (Built-In)

ID	Display Name
`claude-opus-4-6`	Claude Opus 4.6
`claude-sonnet-4-6`	Claude Sonnet 4.6
`claude-haiku-4-5-20251001`	Claude Haiku 4.5
`claude-sonnet-4-5-20250929`	Claude Sonnet 4.5
`claude-opus-4-5-20251101`	Claude Opus 4.5
`claude-opus-4-1-20250805`	Claude Opus 4.1
`claude-sonnet-4-20250514`	Claude Sonnet 4
`claude-opus-4-20250514`	Claude Opus 4
`opus`	Claude Opus
`sonnet`	Claude Sonnet
`haiku`	Claude Haiku

OpenRouter Free-Tier Model Catalog

Model ID
`openrouter/free`
`stepfun/step-3.5-flash:free`
`arcee-ai/trinity-large-preview:free`
`liquid/lfm-2.5-1.2b-thinking:free`
`liquid/lfm-2.5-1.2b-instruct:free`
`nvidia/nemotron-3-nano-30b-a3b:free`
`arcee-ai/trinity-mini:free`
`nvidia/nemotron-nano-12b-v2-vl:free`
`qwen/qwen3-vl-30b-a3b-thinking`
`qwen/qwen3-vl-235b-a22b-thinking`
`qwen/qwen3-next-80b-instruct:free`
`nvidia/nemotron-nano-9b-v2:free`
`openai/gpt-oss-120b:free`
`openai/gpt-oss-20b:free`
`z-ai/glm-4.5-air:free`
`qwen/qwen3-coder:free`
`cognitivecomputations/dolphin-mistral-24b-venice-edition:free`
`google/gemma-3n-e2b-it:free`
`google/gemma-3n-e4b-it:free`
`qwen/qwen3-4b:free`
`mistralai/mistral-small-3.1-24b-instruct:free`
`google/gemma-3-4b-it:free`
`google/gemma-3-12b-it:free`
`google/gemma-3-27b-it:free`

Troubleshooting & Maintenance

Upgrades

Barnaby can run provider upgrades from Edit -> Application Settings -> Connectivity by clicking Upgrade CLI where available. Manual upgrades:

# Manual CLI Updates (PowerShell: use single quotes around package names)
npm update -g '@openai/codex'
npm update -g '@anthropic-ai/claude-code'
npm update -g '@google/gemini-cli'

Common Resolutions

Codex disconnect: If you see app-server closed, run codex app-server in a terminal to inspect and reconnect.
Authentication: Ensure you are logged in globally (for example, codex login).
Path not found: Restart terminal/OS after CLI installs so executables resolve from PATH.
OpenRouter API missing: Add key in Connectivity settings; OpenRouter will not connect without it.