{"id":51051162,"url":"https://github.com/qibinlou/falcon","last_synced_at":"2026-06-22T17:01:32.633Z","repository":{"id":360540325,"uuid":"1246931657","full_name":"qibinlou/falcon","owner":"qibinlou","description":"Run any coding agent with any LLM in absolute privacy.","archived":false,"fork":false,"pushed_at":"2026-06-18T23:06:40.000Z","size":251,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T01:07:56.789Z","etag":null,"topics":["agent","claude-code","cli","codex","codex-cli","coding-agents","coding-harness","opencode","tui","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qibinlou.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-22T18:02:12.000Z","updated_at":"2026-06-18T23:06:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qibinlou/falcon","commit_stats":null,"previous_names":["qibinlou/falcon"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qibinlou/falcon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qibinlou%2Ffalcon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qibinlou%2Ffalcon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qibinlou%2Ffalcon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qibinlou%2Ffalcon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qibinlou","download_url":"https://codeload.github.com/qibinlou/falcon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qibinlou%2Ffalcon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34657902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","claude-code","cli","codex","codex-cli","coding-agents","coding-harness","opencode","tui","typescript"],"created_at":"2026-06-22T17:01:31.616Z","updated_at":"2026-06-22T17:01:32.625Z","avatar_url":"https://github.com/qibinlou.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦅 Falcon — Launch any coding agent with any LLM in absolute privacy.\n\n\n[![npm version](https://img.shields.io/badge/npm-1.1.0-blue.svg?style=flat-square\u0026color=0a0a0c)](https://www.npmjs.com/package/falconsh)\n[![Agent: Codex](https://img.shields.io/badge/Agent-Codex-orange.svg?style=flat-square\u0026color=00a67e)](https://github.com/openai/codex)\n[![Agent: Claude Code](https://img.shields.io/badge/Agent-Claude%20Code-orange.svg?style=flat-square\u0026color=cc9900)](https://docs.anthropic.com/en/docs/claude-code)\n[![Agent: OpenCode](https://img.shields.io/badge/Agent-OpenCode-blue.svg?style=flat-square\u0026color=3399ff)](https://opencode.ai)\n[![LLM Providers: All](https://img.shields.io/badge/LLM%20Providers-All-brightgreen.svg?style=flat-square\u0026color=16d3b4)](#-environment-configuration--api-gateways)\n[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg?style=flat-square\u0026color=6e5aff)](LICENSE)\n[![Built with TypeScript](https://img.shields.io/badge/Language-TypeScript-blue.svg?style=flat-square\u0026color=3178c6)](https://www.typescriptlang.org/)\n[![UI: Ink](https://img.shields.io/badge/UI-Ink%20%26%20React-red.svg?style=flat-square\u0026color=ff5a5f)](https://github.com/vadimdemedes/ink)\n\nFalcon is an elegant command-line interface (CLI) and interactive Terminal User Interface (TUI) orchestrator written in TypeScript. It wraps coding agents—specifically [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenAI Codex CLI](https://github.com/openai/codex), [Codex Desktop App](https://chatgpt.com/codex/), and [OpenCode](https://opencode.ai)—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.\n\n---\n\n## 🎯 Why Falcon?\n\n*   **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.\n*   **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.\n*   **TUI Model Catalog Explorer**: Search and filter through hundreds of models in a rich, keyboard-navigable terminal interface. View context lengths, modalities (text/vision), and token pricing directly before launching your agent.\n*   **Security \u0026 Encryption**: Your API keys are encrypted at rest using platform-specific material and AES-256-CBC, stored securely under `~/.falcon/config.json`.\n*   **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.\n*   **Pass-Through Command Forwarding**: Respects native options. Any extra flag or argument passed to Falcon is forwarded directly to the underlying agent binary.\n\n---\n\n## 🚀 Quick Start\n\nEnsure you have [Node.js](https://nodejs.org/) installed (v22+ recommended).\n\n### 1. Installation \u0026 Usage\n\nFalcon is published on npm as [`falconsh`](https://www.npmjs.com/package/falconsh). You can run it directly without installing, install it globally, or run/develop it from source.\n\n#### Option A: Run directly with `npx` (No installation needed)\n```bash\nnpx falconsh launch\n```\n\n#### Option B: Global Installation\nInstall the package globally:\n```bash\n# pnpm\npnpm add -g falconsh\n\n# npm\nnpm install -g falconsh\n\n# bun\nbun add -g falconsh\n```\nOnce installed, you can use the `falcon` command directly:\n```bash\nfalcon launch\n```\n\n#### Option C: Run from Source (Development Setup)\n```bash\ngit clone https://github.com/qibinlou/falcon.git\ncd falcon\n\n# Install dependencies using your preferred package manager:\npnpm install   # or npm install / bun install\n```\n\n### 2. Configure Your Keys\n\nFalcon automatically detects keys from your environment. Simply set any of the following:\n\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-...\"\nexport OPENAI_API_KEY=\"sk-proj-...\"\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n*(Alternatively, run in interactive mode to add and encrypt your gateway API keys via the TUI!)*\n\n### 3. Examples\n\nYou can run Falcon using `npx falconsh` (or `pnpm dlx falconsh`), globally via `falcon`, or from source (using `pnpm run dev --` in place of `falcon`):\n\n```bash\n# Start in interactive mode to pick agent and LLM provider\nfalcon launch\n\n# Shorthand to run Claude Code with interactive model picker\nfalcon claude\n\n# Shorthand to run OpenCode\nfalcon opencode\n\n# Shorthand to run Codex Desktop App\nfalcon codex-app\n\n# Launch codex CLI with a specific model directly (skips TUI)\nfalcon codex -m claude-opus-4-8\n\n# Launch claude with a specific model directly (skips TUI)\nfalcon claude --model chat-latest\n```\n\n---\n\n## 💻 CLI Commands \u0026 Options Reference\n\n### Commands\n\n| Command | Description |\n| :--- | :--- |\n| `falcon launch [agent] [options] [agentArgs...]` | Launches a coding agent (e.g. `codex`, `claude`, or `opencode`) with options. |\n| `falcon codex [options] [agentArgs...]` | Shorthand to launch OpenAI Codex CLI directly. |\n| `falcon codex-app [options] [agentArgs...]` | Shorthand to launch Codex Desktop App directly. |\n| `falcon claude [options] [agentArgs...]` | Shorthand to launch Claude Code directly. |\n| `falcon opencode [options] [agentArgs...]` | Shorthand to launch OpenCode directly. |\n| `falcon models [options]` | Query and list available models from detected API gateways. |\n\n### Launch Options\n\n| Option | Shorthand | Description |\n| :--- | :--- | :--- |\n| `--model \u003cmodel\u003e` | `-m` | Skip interactive picker and launch directly with the specified model name. |\n| `--gateway \u003cgateway\u003e` | `-g` | Specific API gateway to route requests (`openrouter`, `openai`, `anthropic`, `cloudflare`). |\n| `--list-gateways` | — | Display all detected API keys and active gateways, then exit. |\n\n---\n\n## 🔑 Environment Configuration \u0026 API Gateways\n\nFalcon leverages environment variables to identify and initialize connections to various providers:\n\n| Gateway | Env Variable(s) | Supported Features |\n| :--- | :--- | :--- |\n| **OpenRouter** | `OPENROUTER_API_KEY` | Fetches live model catalog (200+ models), prices, and context windows. Generates OpenAI and Anthropic compatible bridges. |\n| **OpenAI** | `OPENAI_API_KEY`\u003cbr\u003e`OPENAI_BASE_URL` (optional) | Live fetches native OpenAI/compatible catalog including reasoning models. |\n| **Anthropic** | `ANTHROPIC_API_KEY`\u003cbr\u003e`ANTHROPIC_BASE_URL` (optional) | Queries official Anthropic models with rich metadata catalog. |\n| **Cloudflare AI Gateway** | `CLOUDFLARE_API_KEY` or `CF_API_KEY`\u003cbr\u003e`CLOUDFLARE_ACCOUNT_ID`\u003cbr\u003e`CLOUDFLARE_GATEWAY_ID` | Routes requests through Cloudflare's secure AI proxy, auto-injecting gateway custom headers. |\n\n---\n\n## 📂 Codebase \u0026 Architecture\n\nFalcon is structured to make extending gateways and agents straightforward:\n\n*   **[src/cli.ts](./src/cli.ts)**: Command line router and entry point utilizing Commander.js.\n*   **[src/config.ts](./src/config.ts)**: Implements AES-256-CBC encryption to store credentials locally in `~/.falcon/config.json`.\n*   **[src/agents/](./src/agents/)**: Agent wrappers implementing `AgentLauncher` profile compilation and launch arguments.\n    *   [claude.ts](./src/agents/claude.ts): Disables Claude telemetry/feedback and forces full privacy.\n    *   [codex.ts](./src/agents/codex.ts): Updates Codex CLI's `config.toml` profiles, `model.json` catalog and disables analytics.\n    *   [codex-app.ts](./src/agents/codex-app.ts): Configures Codex Desktop App's top-level config keys, `auth.json`, and custom isolated catalog.\n    *   [codex-utils.ts](./src/agents/codex-utils.ts): Shared configuration helpers for Codex CLI and Desktop App launchers.\n    *   [opencode.ts](./src/agents/opencode.ts): Manages OpenCode's config directory and dynamically updates `opencode.json` config settings.\n*   **[src/gateways/](./src/gateways/)**: Providers logic matching API payloads to model metadata lists.\n*   **[src/ui/](./src/ui/)**: Reactive terminal components built on Ink and React.\n\n---\n\n## 🧩 Extending Falcon\n\n### 1. Add a New Agent\n1. Create a class implementing the `AgentLauncher` interface under `src/agents/`.\n2. Define:\n    *   `name`: Display name.\n    *   `slug`: CLI identifier.\n    *   `resolveConfig(...)`: Configure settings, environment variables, or start proxy bridges.\n    *   `buildSpawnConfig(...)`: Define command execution arguments.\n3. Add the instance to `ALL_AGENTS` inside [src/agents/index.ts](./src/agents/index.ts).\n\n### 2. Add a New API Gateway\n1. Create a class implementing the `Gateway` interface under `src/gateways/`.\n2. Define:\n    *   `name` \u0026 `slug`.\n    *   `detectKey()`: Auto-detect API key variables.\n    *   `listModels(apiKey)`: Fetch models from the endpoint.\n    *   `getEnvConfig(apiKey, model)`: Construct the proxy environment routing details.\n3. Add the instance to `ALL_GATEWAYS` inside [src/gateways/index.ts](./src/gateways/index.ts).\n\n---\n\n## 🛠️ Development \u0026 QA\n\nManage the development loop with the following scripts:\n\n```bash\n# Compile and check TypeScript types\npnpm run check:types\n\n# Format and autofix codebase with Biome\npnpm run check:format\n\n# Lint codebase with Biome\npnpm run check:lint\n\n# Run all unit tests\npnpm run test\n\n# Run end-to-end (e2e) tests\npnpm run e2e\n\n# Compile production bundle\npnpm run build\n```\n\n---\n\n## 📄 License\n\nDistributed under the MIT License. See [LICENSE](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqibinlou%2Ffalcon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqibinlou%2Ffalcon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqibinlou%2Ffalcon/lists"}