falconsh 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +181 -0
- package/dist/cli.js +2191 -0
- package/package.json +50 -0
package/README.md
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# 🦅 Falcon — May your tokens never run out.
|
|
2
|
+
|
|
3
|
+
> Launch any coding agent with any LLM in absolute privacy.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](https://github.com/vadimdemedes/ink)
|
|
9
|
+
[](https://github.com/openai/codex)
|
|
10
|
+
[](https://docs.anthropic.com/en/docs/claude-code)
|
|
11
|
+
[](#-environment-configuration--api-gateways)
|
|
12
|
+
|
|
13
|
+
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](https://docs.anthropic.com/en/docs/claude-code) and [OpenAI Codex](https://github.com/openai/codex)—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.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 🎯 Why Falcon?
|
|
18
|
+
|
|
19
|
+
* **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.
|
|
20
|
+
* **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.
|
|
21
|
+
* **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.
|
|
22
|
+
* **Security & Encryption**: Your API keys are encrypted at rest using platform-specific material and AES-256-CBC, stored securely under `~/.falcon/config.json`.
|
|
23
|
+
* **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.
|
|
24
|
+
* **Pass-Through Command Forwarding**: Respects native options. Any extra flag or argument passed to Falcon is forwarded directly to the underlying agent binary.
|
|
25
|
+
|
|
26
|
+
> [!IMPORTANT]
|
|
27
|
+
> **Privacy by default**: Falcon automatically sets `DISABLE_TELEMETRY=1`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, and overrides Codex metrics inside `config.toml` to protect your source code and configurations.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 🚀 Quick Start
|
|
32
|
+
|
|
33
|
+
Ensure you have [Node.js](https://nodejs.org/) installed (v22+ recommended).
|
|
34
|
+
|
|
35
|
+
### 1. Installation
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
git clone https://github.com/sprite/falcon.git
|
|
39
|
+
cd falcon
|
|
40
|
+
npm install
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### 2. Configure Your Keys
|
|
44
|
+
|
|
45
|
+
Falcon automatically detects keys from your environment. Simply set any of the following:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
export OPENROUTER_API_KEY="sk-or-..."
|
|
49
|
+
export OPENAI_API_KEY="sk-proj-..."
|
|
50
|
+
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
*(Alternatively, run in interactive mode to add and encrypt your gateways via the TUI!)*
|
|
54
|
+
|
|
55
|
+
### 3. Run Falcon
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Start in interactive mode to pick agent and gateway
|
|
59
|
+
npm run dev -- launch
|
|
60
|
+
|
|
61
|
+
# Shorthand to run Claude Code with interactive model picker
|
|
62
|
+
npm run dev -- launch claude
|
|
63
|
+
|
|
64
|
+
# Shorthand to run Codex
|
|
65
|
+
npm run dev -- launch codex
|
|
66
|
+
|
|
67
|
+
# Launch with a specific model directly (skips TUI)
|
|
68
|
+
npm run dev -- launch claude --model claude-3-5-sonnet-latest
|
|
69
|
+
|
|
70
|
+
# Launch with a specific model using a specific gateway
|
|
71
|
+
npm run dev -- launch codex --gateway openrouter --model deepseek/deepseek-v4-flash:free
|
|
72
|
+
|
|
73
|
+
# Run a dry run to inspect final command and environment variables
|
|
74
|
+
npm run dev -- launch claude --model claude-3-5-haiku --dry-run
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
> [!TIP]
|
|
78
|
+
> Use the `--dry-run` flag to preview your configuration, Bifrost port forwarding, and exact executable parameters without launching the interactive loop.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## đź’» CLI Commands & Options Reference
|
|
83
|
+
|
|
84
|
+
### Commands
|
|
85
|
+
|
|
86
|
+
| Command | Description |
|
|
87
|
+
| :--- | :--- |
|
|
88
|
+
| `falcon launch [agent] [options] [agentArgs...]` | Launches a coding agent (e.g. `codex` or `claude`) with options. |
|
|
89
|
+
| `falcon codex [options] [agentArgs...]` | Shorthand to launch OpenAI Codex directly. |
|
|
90
|
+
| `falcon claude [options] [agentArgs...]` | Shorthand to launch Claude Code directly. |
|
|
91
|
+
| `falcon models [options]` | Query and list available models from detected API gateways. |
|
|
92
|
+
|
|
93
|
+
### Launch Options
|
|
94
|
+
|
|
95
|
+
| Option | Shorthand | Description |
|
|
96
|
+
| :--- | :--- | :--- |
|
|
97
|
+
| `--model <model>` | `-m` | Skip interactive picker and launch directly with the specified model name. |
|
|
98
|
+
| `--gateway <gateway>` | `-g` | Specific API gateway to route requests (`openrouter`, `openai`, `anthropic`, `cloudflare`). |
|
|
99
|
+
| `--dry-run` | — | Print final environment config, bridge ports, and command string without starting the agent. |
|
|
100
|
+
| `--list-gateways` | — | Display all detected API keys and active gateways, then exit. |
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## 🔑 Environment Configuration & API Gateways
|
|
105
|
+
|
|
106
|
+
Falcon leverages environment variables to identify and initialize connections to various providers:
|
|
107
|
+
|
|
108
|
+
| Gateway | Env Variable(s) | Supported Features |
|
|
109
|
+
| :--- | :--- | :--- |
|
|
110
|
+
| **OpenRouter** | `OPENROUTER_API_KEY` | Fetches live model catalog (200+ models), prices, and context windows. Generates OpenAI and Anthropic compatible bridges. |
|
|
111
|
+
| **OpenAI** | `OPENAI_API_KEY`<br>`OPENAI_BASE_URL` (optional) | Live fetches native OpenAI/compatible catalog including reasoning models. |
|
|
112
|
+
| **Anthropic** | `ANTHROPIC_API_KEY`<br>`ANTHROPIC_BASE_URL` (optional) | Queries official Anthropic models with rich metadata catalog. |
|
|
113
|
+
| **Cloudflare AI Gateway** | `CLOUDFLARE_API_KEY` or `CF_API_KEY`<br>`CLOUDFLARE_ACCOUNT_ID`<br>`CLOUDFLARE_GATEWAY_ID` | Routes requests through Cloudflare's secure AI proxy, auto-injecting gateway custom headers. |
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## đź“‚ Codebase & Architecture
|
|
118
|
+
|
|
119
|
+
Falcon is structured to make extending gateways and agents straightforward:
|
|
120
|
+
|
|
121
|
+
* **[src/cli.ts](./src/cli.ts)**: Command line router and entry point utilizing Commander.js.
|
|
122
|
+
* **[src/config.ts](./src/config.ts)**: Implements AES-256-CBC encryption to store credentials locally in `~/.falcon/config.json`.
|
|
123
|
+
* **[src/agents/](./src/agents/)**: Agent wrappers implementing `AgentLauncher` profile compilation and launch arguments.
|
|
124
|
+
* [claude.ts](./src/agents/claude.ts): Disables Claude telemetry/feedback and forces full privacy.
|
|
125
|
+
* [codex.ts](./src/agents/codex.ts): Updates Codex's `config.toml` profiles, `model.json` catalog and disables analytics.
|
|
126
|
+
* **[src/gateways/](./src/gateways/)**: Providers logic matching API payloads to model metadata lists.
|
|
127
|
+
* **[src/ui/](./src/ui/)**: Reactive terminal components built on Ink and React.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## 🧩 Extending Falcon
|
|
132
|
+
|
|
133
|
+
### 1. Add a New Agent
|
|
134
|
+
1. Create a class implementing the `AgentLauncher` interface under `src/agents/`.
|
|
135
|
+
2. Define:
|
|
136
|
+
* `name`: Display name.
|
|
137
|
+
* `slug`: CLI identifier.
|
|
138
|
+
* `resolveConfig(...)`: Configure settings, environment variables, or start proxy bridges.
|
|
139
|
+
* `buildSpawnConfig(...)`: Define command execution arguments.
|
|
140
|
+
3. Add the instance to `ALL_AGENTS` inside [src/agents/index.ts](./src/agents/index.ts).
|
|
141
|
+
|
|
142
|
+
### 2. Add a New API Gateway
|
|
143
|
+
1. Create a class implementing the `Gateway` interface under `src/gateways/`.
|
|
144
|
+
2. Define:
|
|
145
|
+
* `name` & `slug`.
|
|
146
|
+
* `detectKey()`: Auto-detect API key variables.
|
|
147
|
+
* `listModels(apiKey)`: Fetch models from the endpoint.
|
|
148
|
+
* `getEnvConfig(apiKey, model)`: Construct the proxy environment routing details.
|
|
149
|
+
3. Add the instance to `ALL_GATEWAYS` inside [src/gateways/index.ts](./src/gateways/index.ts).
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 🛠️ Development & QA
|
|
154
|
+
|
|
155
|
+
Manage the development loop with the following scripts:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
# Compile and check TypeScript types
|
|
159
|
+
npm run check:types
|
|
160
|
+
|
|
161
|
+
# Format and autofix codebase with Biome
|
|
162
|
+
npm run check:format
|
|
163
|
+
|
|
164
|
+
# Lint codebase with Biome
|
|
165
|
+
npm run check:lint
|
|
166
|
+
|
|
167
|
+
# Run all unit tests
|
|
168
|
+
npm run test
|
|
169
|
+
|
|
170
|
+
# Run end-to-end (e2e) tests
|
|
171
|
+
npm run e2e
|
|
172
|
+
|
|
173
|
+
# Compile production bundle
|
|
174
|
+
npm run build
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## đź“„ License
|
|
180
|
+
|
|
181
|
+
Distributed under the MIT License. See [LICENSE](LICENSE) for more details.
|