Falcon is an elegant command-line interface (CLI) and interactive Terminal User Interface (TUI) orchestrator written in TypeScript. It wraps coding agents—specifically Claude Code, OpenAI Codex CLI, Codex Desktop App, and OpenCode—and provides multi-gateway API support (OpenRouter, OpenAI, Anthropic, Cloudflare AI Gateway), allowing you to run any compatible model under any agent harness with zero configuration overhead and absolute privacy.
- API Gateway Abstraction: No more memorizing gateway endpoints or manual token configurations. Falcon automatically maps models and manages API endpoints across OpenAI, Anthropic, OpenRouter, and Cloudflare AI Gateway.
- Bifrost Translation Engine: Want to run Anthropic's Claude Code using an OpenAI API key? Or run Codex using an Anthropic endpoint? Falcon utilizes a built-in proxy engine (
@maximhq/bifrost) under the hood to automatically translate Anthropic's messaging protocol to OpenAI's completion format and vice-versa. - TUI Model Catalog Explorer: Search and filter through hundreds of models in a rich, keyboard-navigable terminal interface. View context lengths, modalities, and token pricing directly before launching your agent. Falcon derives those details from live gateway catalogs and keeps a local cache for repeat launches.
- Security & Encryption: Your API keys are encrypted at rest using platform-specific material and AES-256-CBC, stored securely under
~/.falcon/config.json. - Opt-Out Telemetry by Default: Respects your privacy. Falcon automatically configures downstream agents to run in full privacy mode, disabling analytics, feedback prompts, telemetry, and non-essential external connections.
- Pass-Through Command Forwarding: Respects native options. Any extra flag or argument passed to Falcon is forwarded directly to the underlying agent binary.
Ensure you have Node.js installed (v22+ recommended).
Falcon is published on npm as falconsh. You can run it directly without installing, install it globally, or run/develop it from source.
npx falconsh launchInstall the package globally:
# pnpm
pnpm add -g falconsh
# npm
npm install -g falconsh
# bun
bun add -g falconshOnce installed, you can use the falcon command directly:
falcon launchgit clone https://github.com/qibinlou/falcon.git
cd falcon
# Install dependencies using your preferred package manager:
pnpm install # or npm install / bun installFalcon automatically detects keys from your environment. Simply set any of the following:
export OPENROUTER_API_KEY="sk-or-..."
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."(Alternatively, run in interactive mode to add and encrypt your gateway API keys via the TUI!)
You can run Falcon using npx falconsh (or pnpm dlx falconsh), globally via falcon, or from source (using pnpm run dev -- in place of falcon):
# Start in interactive mode to pick agent and LLM provider
falcon launch
# Shorthand to run Claude Code with interactive model picker
falcon claude
# Shorthand to run OpenCode
falcon opencode
# Shorthand to run Codex Desktop App
falcon codex-app
# Launch codex CLI with a specific model directly (skips TUI)
falcon codex -m claude-opus-4-8
# Launch claude with a specific model directly (skips TUI)
falcon claude --model chat-latest| Command | Description |
|---|---|
falcon launch [agent] [options] [agentArgs...] |
Launches a coding agent (e.g. codex, claude, or opencode) with options. |
falcon codex [options] [agentArgs...] |
Shorthand to launch OpenAI Codex CLI directly. |
falcon codex-app [options] [agentArgs...] |
Shorthand to launch Codex Desktop App directly. |
falcon claude [options] [agentArgs...] |
Shorthand to launch Claude Code directly. |
falcon opencode [options] [agentArgs...] |
Shorthand to launch OpenCode directly. |
falcon models [options] |
Query and list available models from detected API gateways. |
| Option | Shorthand | Description |
|---|---|---|
--model <model> |
-m |
Skip interactive picker and launch directly with the specified model name. |
--gateway <gateway> |
-g |
Specific API gateway to route requests (openrouter, openai, anthropic, cloudflare). |
--list-gateways |
— | Display all detected API keys and active gateways, then exit. |
Falcon leverages environment variables to identify and initialize connections to various providers:
| Gateway | Env Variable(s) | Supported Features |
|---|---|---|
| OpenRouter | OPENROUTER_API_KEY |
Fetches live model catalog (200+ models), prices, and context windows. Generates OpenAI and Anthropic compatible bridges. |
| OpenAI | OPENAI_API_KEYOPENAI_BASE_URL (optional) |
Live fetches native OpenAI/compatible catalog including reasoning models. |
| Anthropic | ANTHROPIC_API_KEYANTHROPIC_BASE_URL (optional) |
Queries official Anthropic models with rich metadata catalog. |
| Cloudflare AI Gateway | CLOUDFLARE_API_KEY or CF_API_KEYCLOUDFLARE_ACCOUNT_IDCLOUDFLARE_GATEWAY_ID |
Routes requests through Cloudflare's secure AI proxy, auto-injecting gateway custom headers. |
Falcon is structured to make extending gateways and agents straightforward:
- src/cli.ts: Command line router and entry point utilizing Commander.js.
- src/config.ts: Implements AES-256-CBC encryption to store credentials locally in
~/.falcon/config.json. - src/agents/: Agent wrappers implementing
AgentLauncherprofile compilation and launch arguments.- claude.ts: Disables Claude telemetry/feedback and forces full privacy.
- codex.ts: Updates Codex CLI's
config.tomlprofile, writesmodel.jsonfrom OpenRouter catalog metadata, and disables analytics. - codex-app.ts: Configures Codex Desktop App's top-level config keys,
auth.json, and custom isolated catalog built from the same metadata source. - codex-utils.ts: Shared configuration helpers for Codex CLI and Desktop App launchers, including OpenRouter-backed context window and modality lookup with local caching.
- opencode.ts: Manages OpenCode's config directory and dynamically updates
opencode.jsonconfig settings.
- opencode.ts: Manages OpenCode's config directory and dynamically updates
- src/gateways/: Providers logic matching API payloads to model metadata lists.
- src/ui/: Reactive terminal components built on Ink and React.
- Create a class implementing the
AgentLauncherinterface undersrc/agents/. - Define:
name: Display name.slug: CLI identifier.resolveConfig(...): Configure settings, environment variables, or start proxy bridges.buildSpawnConfig(...): Define command execution arguments.
- Add the instance to
ALL_AGENTSinside src/agents/index.ts.
- Create a class implementing the
Gatewayinterface undersrc/gateways/. - Define:
name&slug.detectKey(): Auto-detect API key variables.listModels(apiKey): Fetch models from the endpoint.getEnvConfig(apiKey, model): Construct the proxy environment routing details.
- Add the instance to
ALL_GATEWAYSinside src/gateways/index.ts.
Manage the development loop with the following scripts:
# Compile and check TypeScript types
pnpm run check:types
# Format and autofix codebase with Biome
pnpm run check:format
# Lint codebase with Biome
pnpm run check:lint
# Run all unit tests
pnpm run test
# Run end-to-end (e2e) tests
pnpm run e2e
# Compile production bundle
pnpm run buildDistributed under the MIT License. See LICENSE for more details.