kimiflare 0.47.0 β†’ 0.48.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 CHANGED
@@ -13,51 +13,44 @@
13
13
 
14
14
  <p align="center">
15
15
  <strong>A terminal coding agent powered by <a href="https://developers.cloudflare.com/workers-ai/models/kimi-k2.6/">Kimi-K2.6</a> on Cloudflare Workers AI.</strong><br>
16
- Moonshot's 1T-parameter open-source model, running directly on your Cloudflare account.
16
+ Moonshot's 1T-parameter open-source model, running directly in your terminal.
17
17
  </p>
18
18
 
19
- > πŸ’Έ **Heads up β€” this runs on your Cloudflare account.**
20
- > We recommend setting a [budget cap](https://developers.cloudflare.com/workers-ai/platform/pricing/) on Workers AI and checking your [Cloudflare billing](https://dash.cloudflare.com/) regularly while using KimiFlare.
21
- >
22
- > πŸš€ **Stay up to date.** Newer versions are significantly more token-efficient and cheaper to run. Run `/update` inside KimiFlare or `npm update -g kimiflare` to get the latest release.
23
-
24
19
  <p align="center">
25
20
  <img src="docs/screenshot.png" alt="kimiflare TUI" width="900">
26
21
  </p>
27
22
 
28
- ## Stay in the loop
29
-
30
- Kimiflare is shipping quickly.
31
-
32
- Get:
33
- - release notes,
34
- - technical write-ups,
35
- - early experimental features,
36
- - architecture notes on building coding agents on Cloudflare.
37
-
38
- β†’ Get updates: https://kimiflare.com
39
-
40
- ## Shipping fast
23
+ ## Two ways to run
41
24
 
42
- Recently shipped:
43
- - Cloudflare Code Mode support
44
- - Local agent memory
45
- - Major token cost reductions (70–90% lower)
46
- - Better session compaction
25
+ | Mode | How it works | Best for |
26
+ |------|-------------|----------|
27
+ | **BYOK** | Bring your own Cloudflare Account ID + API Token. Traffic goes straight to Workers AI from your account. | Power users who want full control and direct billing. |
28
+ | **Kimiflare Cloud** | Device auth β€” no API key needed. We proxy requests through our managed endpoint. | Getting started quickly without a Cloudflare account. |
47
29
 
48
- Coming next:
49
- - OpenCode parity improvements
50
- - Cost attribution dashboard
51
- - Cloudflare Artifacts experiments
30
+ > 🎁 **Try Kimiflare Cloud free** β€” sign up and get **5 million tokens** on us until May 14, 2026. Run `kimiflare --cloud` or pick "Cloud (managed)" during onboarding.
52
31
 
53
- Full changelog and notes at https://kimiflare.com
54
-
55
- ## Why kimiflare
32
+ ## What to remember
56
33
 
57
34
  - **262k context window** β€” Read entire modules, large configs, and full stack traces without the model losing track.
58
- - **Image understanding** β€” Drop image paths into your prompt (PNG, JPG, WebP, GIF, BMP). The model sees them inline β€” great for UI reviews, diagrams, screenshots, and mockups.
59
- - **Direct by default** β€” No proxy, no OpenAI SDK. Your traffic goes straight to Workers AI from your account, with optional AI Gateway routing for user-owned logging, caching, and analytics.
60
- - **Plan mode** β€” Ask the agent to research and produce a plan without touching your filesystem. Review it, then exit plan mode to execute.
35
+ - **Image understanding** β€” Drop image paths (PNG, JPG, WebP, GIF, BMP up to 5 MB) into any prompt. Great for UI reviews, diagrams, and screenshots.
36
+ - **Plan / Edit / Auto modes** β€” `plan` blocks mutating tools for safe research. `edit` (default) prompts per mutating call. `auto` approves everything for trusted tasks.
37
+ - **Live cost tracking** β€” Status bar shows real-time spend based on Cloudflare pricing. Know exactly what each turn costs.
38
+ - **LSP + MCP** β€” Semantic code intelligence (hover, go-to-definition, references, diagnostics) via Language Server Protocol. Extend with external tools via Model Context Protocol.
39
+ - **Local structured memory** β€” SQLite + embeddings cross-session memory. The agent recalls facts, instructions, and preferences across sessions via `remember`, `recall`, and `forget` tools.
40
+ - **Web search, GitHub, and headless browser** β€” Research the web, read GitHub repos, and fetch JavaScript-rendered pages without leaving your terminal.
41
+
42
+ ## Recently shipped
43
+
44
+ - **Turn supervisor architecture** β€” graceful preemption, visual cleanup, and better multi-step task management.
45
+ - **Web search, GitHub read-only, and headless browser tools** β€” research without leaving the terminal.
46
+ - **Tiered skill routing** β€” the agent picks the right skill depth for the task, with visible TUI indicators.
47
+ - **Extensible JSON themes** β€” WCAG contrast-validated, fully customizable color palettes.
48
+ - **KIMI.md drift detection** β€” memory-based staleness indicators warn when your project context file is out of date.
49
+ - **Fuzzy @ file picker** β€” type `@` to mention files with fuzzy matching and inline filtering.
50
+ - **Kimiflare Cloud mode** β€” device auth, no API key needed, with real-time token budget tracking.
51
+ - **Context-window guardrails** β€” prevents runs that would exceed the model's limit before they start.
52
+
53
+ See the full changelog at [github.com/sinameraji/kimiflare/releases](https://github.com/sinameraji/kimiflare/releases).
61
54
 
62
55
  ## Quick start
63
56
 
@@ -66,7 +59,7 @@ npm install -g kimiflare
66
59
  kimiflare
67
60
  ```
68
61
 
69
- On first run, an interactive onboarding wizard asks for your Cloudflare Account ID and API Token. That's it β€” you're ready.
62
+ On first run, an interactive onboarding wizard asks how you want to connect β€” BYOK or Cloud. That's it.
70
63
 
71
64
  Or run without installing:
72
65
 
@@ -76,176 +69,7 @@ npx kimiflare
76
69
 
77
70
  Requires Node.js β‰₯ 20.
78
71
 
79
- > For release notes and rapid feature drops: https://kimiflare.com
80
-
81
- ## Features
82
-
83
- | Feature | What it does |
84
- |---------|-------------|
85
- | **Plan / Edit / Auto modes** | `plan` blocks all mutating tools for safe research. `edit` (default) prompts per mutating call. `auto` approves everything for trusted tasks. |
86
- | **Live task panel** | For multi-step work, the agent publishes a task list with progress icons (β–  active, ☐ pending, βœ“ done), elapsed time, and token deltas. |
87
- | **14 terminal themes** | dark, light, high-contrast, dracula, nord, one-dark, monokai, solarized-dark/light, tokyo-night, gruvbox-dark/light, catppuccin-mocha, rose-pine. Interactive picker with live preview (`Ctrl+T`). |
88
- | **Paste collapse** | Large pastes (β‰₯200 chars or β‰₯2 newlines) collapse to `[pasted N lines #id]`. Full content still goes to the model β€” scrollback stays clean. |
89
- | **Type-ahead queue** | Type your next prompt while the model is still working. Queued prompts show as `⏳ …` and fire in order. `Ctrl-C` aborts current + clears queue. |
90
- | **Auto-compaction** | At ~80% context usage, kimiflare nudges you to run `/compact`. It summarizes older turns into a dense summary, keeping the last 4 turns intact. |
91
- | **Streaming reasoning** | Toggle the model's chain-of-thought with `/reasoning` or `Ctrl-R`. See how it thinks in real time. |
92
- | **Image understanding** | Drop image paths (PNG, JPG, WebP, GIF, BMP up to 5 MB) into any prompt. The model sees them inline β€” perfect for UI reviews, diagrams, and screenshots. |
93
- | **Live cost tracking** | Status bar shows real-time cost based on Cloudflare pricing: `$0.95/M input`, `$0.16/M cached`, `$4.00/M output`. |
94
- | **Optional AI Gateway** | Route Workers AI traffic through your own Cloudflare AI Gateway for request logs, cache status, and analytics while keeping your API token local. |
95
- | **Session persistence** | Every turn is auto-saved. `/resume` lists past sessions (with message counts) in a paginated picker. |
96
- | **Smart permissions** | Bash session-allow is keyed by the first token (e.g., allow all `git` commands). Write/edit show a unified diff before you approve. |
97
- | **Project context (`/init`)** | Scans your repo and writes a concise `KIMI.md` β€” build commands, layout, conventions. Auto-loaded on every launch. |
98
- | **MCP server integration** | Plug in external tools via the Model Context Protocol β€” local stdio servers or remote SSE endpoints. GitHub, Sentry, docs search, databases, etc. |
99
- | **Co-author auto-append** | Detects `git commit` commands and auto-injects `Co-authored-by: kimiflare <kimiflare@proton.me>`. |
100
- | **Local structured memory** | SQLite + embeddings cross-session memory. Extracts facts, instructions, and preferences at compaction time; recalls them via hybrid search (FTS5 + vector + exact) in future sessions. Team-shareable via `.kimiflare/memory.db`. |
101
- | **Resilient transport** | Retries Cloudflare capacity errors (code 3040) and 5xx with exponential backoff up to 5 attempts. |
102
-
103
- ## Configure
104
-
105
- Get credentials from Cloudflare:
106
-
107
- 1. https://dash.cloudflare.com β†’ your account β†’ copy **Account ID**.
108
- 2. https://dash.cloudflare.com/profile/api-tokens β†’ **Create Token** β†’ Custom token with **Account β€Ί Workers AI β€Ί Read** on your account β†’ **Create** β†’ copy.
109
-
110
- Then either export them each shell:
111
-
112
- ```sh
113
- export CLOUDFLARE_ACCOUNT_ID=...
114
- export CLOUDFLARE_API_TOKEN=...
115
- # Optional: route through a Cloudflare AI Gateway you own
116
- export KIMIFLARE_AI_GATEWAY_ID=...
117
- # Optional: enable local structured memory
118
- export KIMIFLARE_MEMORY_ENABLED=1
119
- export KIMIFLARE_MEMORY_DB_PATH=.kimiflare/memory.db
120
- export KIMIFLARE_MEMORY_MAX_AGE_DAYS=90
121
- export KIMIFLARE_MEMORY_MAX_ENTRIES=1000
122
- ```
123
-
124
- or save them once (`chmod 600` automatically):
125
-
126
- ```sh
127
- mkdir -p ~/.config/kimiflare
128
- cat > ~/.config/kimiflare/config.json <<'EOF'
129
- {
130
- "accountId": "YOUR_ACCOUNT_ID",
131
- "apiToken": "YOUR_API_TOKEN",
132
- "model": "@cf/moonshotai/kimi-k2.6",
133
- "aiGatewayId": "YOUR_GATEWAY_NAME"
134
- }
135
- EOF
136
- chmod 600 ~/.config/kimiflare/config.json
137
- ```
138
-
139
- ### Optional AI Gateway
140
-
141
- kimiflare talks directly to Workers AI unless `aiGatewayId` is configured. When set, chat completions are sent to Cloudflare's native Workers AI Gateway endpoint:
142
-
143
- ```text
144
- https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/{model_id}
145
- ```
146
-
147
- Create a gateway in the Cloudflare dashboard under **AI > AI Gateway**, then set `aiGatewayId` in `~/.config/kimiflare/config.json` or export `KIMIFLARE_AI_GATEWAY_ID`. The same Workers AI API token stays on your machine and is sent to Cloudflare.
148
-
149
- Optional per-request controls:
150
-
151
- ```json
152
- {
153
- "aiGatewayCacheTtl": 3600,
154
- "aiGatewaySkipCache": false,
155
- "aiGatewayCollectLogPayload": false,
156
- "aiGatewayMetadata": { "tool": "kimiflare" }
157
- }
158
- ```
159
-
160
- `cf-aig-cache-status` from AI Gateway is shown separately from Workers AI prompt-token caching (`cached_tokens`). If you enable gateway logs, kimiflare records metadata such as log id, cache hit/miss, tokens, duration, and status when Cloudflare returns it; prompt and response bodies are not stored by kimiflare.
161
-
162
- ## MCP servers (Model Context Protocol)
163
-
164
- kimiflare supports external tools via MCP. Add servers to your `~/.config/kimiflare/config.json`:
165
-
166
- ```json
167
- {
168
- "accountId": "YOUR_ACCOUNT_ID",
169
- "apiToken": "YOUR_API_TOKEN",
170
- "mcpServers": {
171
- "github": {
172
- "type": "local",
173
- "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
174
- "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
175
- },
176
- "fetch": {
177
- "type": "local",
178
- "command": ["uvx", "mcp-server-fetch"]
179
- },
180
- "my-remote": {
181
- "type": "remote",
182
- "url": "https://example.com/mcp",
183
- "headers": { "Authorization": "Bearer token123" }
184
- }
185
- }
186
- }
187
- ```
188
-
189
- - `type`: `"local"` (stdio subprocess) or `"remote"` (SSE/HTTP endpoint)
190
- - `command`: array with executable and args (local only)
191
- - `url`: endpoint URL (remote only)
192
- - `env`: environment variables for local servers
193
- - `headers`: HTTP headers for remote servers
194
- - `enabled`: set to `false` to skip a server
195
-
196
- MCP tools appear prefixed as `mcp_<server>_<tool>` alongside built-in tools.
197
-
198
- **Commands:**
199
- - `/mcp list` β€” show connected servers and tool counts
200
- - `/mcp reload` β€” disconnect and reconnect all configured servers
201
-
202
- ## Local structured memory
203
-
204
- kimiflare can remember facts, instructions, and preferences across sessions using a local SQLite database with vector search.
205
-
206
- **How it works:**
207
- - At compaction time, the agent extracts structured memories from the conversation
208
- - Memories are stored with embeddings (`@cf/baai/bge-base-en-v1.5`) in a local SQLite database
209
- - On future sessions, relevant memories are recalled via hybrid search (FTS5 full-text + vector similarity + exact file-path matching)
210
- - Supports team-shared memory: `.kimiflare/memory.db` in your repo root (add to `.gitignore`)
211
-
212
- **Enable:**
213
- ```sh
214
- export KIMIFLARE_MEMORY_ENABLED=1
215
- ```
216
-
217
- Or in `~/.config/kimiflare/config.json`:
218
- ```json
219
- {
220
- "memoryEnabled": true,
221
- "memoryDbPath": ".kimiflare/memory.db",
222
- "memoryMaxAgeDays": 90,
223
- "memoryMaxEntries": 1000,
224
- "memoryEmbeddingModel": "@cf/baai/bge-base-en-v1.5"
225
- }
226
- ```
227
-
228
- **Commands:**
229
- - `/memory` β€” show memory stats (total count, DB size, by category)
230
- - `/memory search <query>` β€” manual hybrid search over stored memories
231
- - `/memory clear` β€” wipe all memories for the current repo
232
-
233
- **Storage & cleanup:**
234
- - Default retention: 90 days, 1000 memories per repo
235
- - Automatic deduplication of near-identical memories
236
- - Cleanup runs on startup and after every compaction
237
- - Typical size: ~4–5 KB per memory; ~15 MB/month under heavy use
238
-
239
- ## Usage
240
-
241
- ### Interactive TUI
242
-
243
- ```sh
244
- kimiflare # launch TUI
245
- kimiflare --model @cf/moonshotai/kimi-k2.6 # override model
246
- ```
247
-
248
- ### Print mode (one-shot, non-interactive)
72
+ ### One-shot mode
249
73
 
250
74
  ```sh
251
75
  kimiflare -p "summarize PLAN.md" # stream answer to stdout
@@ -255,58 +79,31 @@ kimiflare -p "..." --reasoning # include chain-of-thought i
255
79
 
256
80
  ### Image understanding
257
81
 
258
- Reference image files directly in your prompt β€” the model sees them inline:
259
-
260
82
  ```sh
261
83
  kimiflare
262
84
  β€Ί fix the layout bug in this screenshot docs/bug.png
263
85
  β€Ί convert this mockup design.png to Tailwind HTML
264
- β€Ί explain this architecture diagram.png
265
86
  ```
266
87
 
267
- Supported formats: PNG, JPG, JPEG, WebP, GIF, BMP (up to 5 MB each, 10 per message).
268
-
269
- ### CLI flags
270
-
271
- | Flag | Short | Description |
272
- |------|-------|-------------|
273
- | `--print <prompt>` | `-p` | One-shot mode: send prompt, stream reply, exit |
274
- | `--model <id>` | `-m` | Model ID (default: `@cf/moonshotai/kimi-k2.6`) |
275
- | `--dangerously-allow-all` | β€” | Auto-approve every permission prompt (print mode only) |
276
- | `--reasoning` | β€” | Stream chain-of-thought to stderr (print mode only) |
277
- | `--version` | `-V` | Show version |
278
- | `--help` | `-h` | Show help |
279
-
280
88
  ## Slash commands
281
89
 
282
90
  | Command | Effect |
283
91
  |---------|--------|
284
- | `/mode edit\|plan\|auto` | Switch mode. `edit` prompts for permission (default), `plan` is read-only research, `auto` auto-approves every tool call. |
285
- | `/plan` `/auto` `/edit` | Shortcuts for the three modes. |
286
- | `/thinking low\|medium\|high` | Reasoning effort. `low` = fastest, shallow; `medium` = balanced (default); `high` = deepest, slowest. Saved to config. |
287
- | `/theme` | Interactive theme picker with live preview (`Ctrl+T`). Saved to config. |
288
- | `/theme NAME` | Set theme by name directly. |
289
- | `/resume` | Pick a past conversation to restore. |
290
- | `/compact` | Summarize older turns to free context. Suggested automatically at ~80% full. Extracts memories if memory is enabled. |
291
- | `/init` | Scan the repo and write a `KIMI.md` so future agents have project context. |
292
- | `/memory` | Show memory stats (total count, DB size, by category). |
293
- | `/memory search <query>` | Search stored memories manually. |
294
- | `/memory clear` | Wipe all memories for the current repo. |
295
- | `/mcp list` | List connected MCP servers and their tools. |
296
- | `/mcp reload` | Disconnect and reconnect all configured MCP servers. |
297
- | `/reasoning` | Toggle chain-of-thought display. |
298
- | `/clear` | Reset the current conversation. |
299
- | `/cost` | Show token usage for the current turn. |
300
- | `/model` | Show current model. |
301
- | `/update` | Check for updates manually. |
302
- | `/logout` | Clear saved credentials. |
303
- | `/help` | List all commands. |
304
- | `/exit` | Quit. |
92
+ | `/mode edit\|plan\|auto` | Switch permission mode |
93
+ | `/thinking low\|medium\|high` | Reasoning effort (persists) |
94
+ | `/theme` | Interactive theme picker (`Ctrl+T`) |
95
+ | `/resume` | Pick a past conversation to restore |
96
+ | `/compact` | Summarize older turns to free context |
97
+ | `/init` | Scan repo and write `KIMI.md` project context |
98
+ | `/memory` | Show memory stats and search |
99
+ | `/mcp list` / `/mcp reload` | Manage MCP servers |
100
+ | `/reasoning` | Toggle chain-of-thought display |
101
+ | `/cost` | Show token usage for current turn |
102
+ | `/update` | Check for updates |
103
+ | `/help` | List all commands |
305
104
 
306
105
  ## Keyboard shortcuts
307
106
 
308
- ### Global
309
-
310
107
  | Shortcut | Action |
311
108
  |----------|--------|
312
109
  | `Ctrl+C` / `Esc` | Interrupt current turn when busy; exit when idle |
@@ -316,70 +113,6 @@ Supported formats: PNG, JPG, JPEG, WebP, GIF, BMP (up to 5 MB each, 10 per messa
316
113
  | `Shift+Tab` | Cycle mode (edit β†’ plan β†’ auto) |
317
114
  | `↑` / `↓` | Walk prompt history |
318
115
 
319
- ### Editing (macOS / Linux)
320
-
321
- | Shortcut | Action |
322
- |----------|--------|
323
- | `βŒ₯←` / `βŒ₯β†’` | Jump word left/right |
324
- | `βŒ˜β†` / `βŒ˜β†’` | Jump to start / end of line |
325
- | `βŒ₯⌫` | Delete word backward |
326
- | `⌘⌫` | Delete to start of line |
327
- | `βŒ₯⌦` | Delete word forward |
328
- | `Ctrl+A` / `Ctrl+E` | Start / end of line |
329
- | `Ctrl+W` / `Ctrl+U` / `Ctrl+K` | Delete word backward / to start / to end of line |
330
-
331
- ## Modes
332
-
333
- - **edit** β€” default. The agent calls tools freely for read-only work; mutating tools (`write`, `edit`, `bash`) pause for your approval.
334
- - **plan** β€” read-only. Mutating tools are hard-blocked. Ask "plan a refactor" and the agent will investigate and produce a plan without touching the filesystem. Exit plan mode to execute.
335
- - **auto** β€” autonomous. Every tool call is auto-approved. Use for trusted, well-scoped tasks.
336
-
337
- ## Thinking level (quality vs speed)
338
-
339
- Kimi-K2.6 always reasons, but you can cap the effort:
340
-
341
- - **low** β€” fastest. Best for chat, small edits, running commands.
342
- - **medium** β€” balanced (default). Solid reasoning on real edits without the latency of deep thinking on trivial prompts.
343
- - **high** β€” deepest. Best for multi-file refactors, subtle bugs, architectural decisions.
344
-
345
- Set with `/thinking medium` (persists), or per-launch via `KIMI_REASONING_EFFORT=high`.
346
-
347
- ## Tools
348
-
349
- All tool calls show inline; mutating ones require per-call approval the first time, with an option to allow for the rest of the session.
350
-
351
- | Tool | Permission | What it does |
352
- |------|------------|--------------|
353
- | `read` | auto | Read a text file (≀ 2MB) with optional line range. |
354
- | `write` | prompt | Create or overwrite a file. Shows a unified diff before you approve. |
355
- | `edit` | prompt | Replace an exact substring. Fails unless `old_string` is unique (or `replace_all=true`). |
356
- | `bash` | prompt | Run a shell command via `bash -lc`. Session-allow is keyed by the first token of the command. |
357
- | `glob` | auto | Match files by pattern (`**/*.ts`), sorted by mtime. |
358
- | `grep` | auto | Regex search. Uses `rg` if installed; falls back to a JS walk. |
359
- | `web_fetch` | auto | Fetch a URL, convert HTML β†’ markdown (≀ 100KB). |
360
- | `tasks_set` | auto | Publish a live task list for multi-step work. |
361
-
362
- ## How it works
363
-
364
- ```
365
- β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
366
- β”‚ kimiflare (Node.js TUI) β”‚
367
- user ─▢ β”‚ β”‚
368
- β”‚ user msg ─▢ agent loop ─▢ runKimi() ──[POST SSE]──▢ β”‚
369
- β”‚ β–² β”‚
370
- β”‚ β”‚ β”‚
371
- β”‚ tool result ◀──tool executor──◀ tool_calls β”‚
372
- β”‚ (permission modal for write / edit / bash) β”‚
373
- β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
374
- β”‚
375
- β–Ό
376
- api.cloudflare.com/client/v4
377
- /accounts/{ID}/ai/run/
378
- @cf/moonshotai/kimi-k2.6
379
- ```
380
-
381
- Direct `fetch` to Workers AI by default, or the native Workers AI AI Gateway endpoint when `aiGatewayId` is configured. The payload remains OpenAI-compatible `messages` + `tools`, with an SSE stream containing reasoning + content + tool-call deltas accumulated by index.
382
-
383
116
  ## Development
384
117
 
385
118
  ```sh
@@ -387,114 +120,24 @@ git clone https://github.com/sinameraji/kimiflare
387
120
  cd kimiflare
388
121
  npm install
389
122
  npm run build
390
- npm link # or: ln -s "$PWD/bin/kimiflare.mjs" ~/.local/bin/kimiflare
123
+ npm link
391
124
  ```
392
125
 
393
126
  Scripts:
394
- - `npm run build` β€” bundle with tsup (`dist/` + `bin/kimiflare.mjs`)
395
- - `npm run dev` β€” run via tsx (`tsx src/index.tsx`)
127
+ - `npm run build` β€” bundle with tsup
128
+ - `npm run dev` β€” run via tsx
396
129
  - `npm run typecheck` β€” `tsc --noEmit`
397
- - `npm start` β€” run compiled bin
130
+ - `npm test` β€” run tests
398
131
 
399
132
  ## Contributing
400
133
 
401
- Contributions are welcome!
402
-
403
134
  1. Fork the repository
404
135
  2. Create a branch: `git checkout -b feat/your-feature`
405
136
  3. Make your changes
406
137
  4. Run `npm run typecheck` and `npm run build`
407
- 5. Commit: `git commit -m "feat: description"`
408
- 6. Push: `git push origin feat/your-feature`
409
- 7. Open a Pull Request
410
-
411
- ## Testing MCP locally
412
-
413
- You don't need a real MCP server to test the integration. Here's a minimal test server you can save as `test-mcp-server.js`:
414
-
415
- ```js
416
- // test-mcp-server.js β€” a minimal MCP server for testing
417
- import { Server } from "@modelcontextprotocol/sdk/server/index.js";
418
- import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
419
-
420
- const server = new Server({ name: "test-server", version: "1.0.0" }, { capabilities: { tools: {} } });
421
-
422
- server.setRequestHandler("tools/list", async () => ({
423
- tools: [
424
- {
425
- name: "greet",
426
- description: "Greet someone by name",
427
- inputSchema: {
428
- type: "object",
429
- properties: { name: { type: "string" } },
430
- required: ["name"],
431
- },
432
- },
433
- {
434
- name: "add",
435
- description: "Add two numbers",
436
- inputSchema: {
437
- type: "object",
438
- properties: { a: { type: "number" }, b: { type: "number" } },
439
- required: ["a", "b"],
440
- },
441
- },
442
- ],
443
- }));
444
-
445
- server.setRequestHandler("tools/call", async (req) => {
446
- if (req.params.name === "greet") {
447
- return { content: [{ type: "text", text: `Hello, ${req.params.arguments.name}!` }] };
448
- }
449
- if (req.params.name === "add") {
450
- const sum = req.params.arguments.a + req.params.arguments.b;
451
- return { content: [{ type: "text", text: String(sum) }] };
452
- }
453
- throw new Error("Unknown tool");
454
- });
455
-
456
- const transport = new StdioServerTransport();
457
- await server.connect(transport);
458
- ```
459
-
460
- Then add it to your config:
461
-
462
- ```json
463
- {
464
- "mcpServers": {
465
- "test": {
466
- "type": "local",
467
- "command": ["node", "/path/to/test-mcp-server.js"]
468
- }
469
- }
470
- }
471
- ```
472
-
473
- Launch kimiflare and try:
474
- - `/mcp list` β€” should show `test (local) β€” 2 tools`
475
- - `use mcp_test_greet with name "kimiflare"` β€” should return `Hello, kimiflare!`
476
- - `use mcp_test_add with a 3 and b 5` β€” should return `8`
477
-
478
- For a real-world test, try the [official GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github):
479
-
480
- ```json
481
- {
482
- "mcpServers": {
483
- "github": {
484
- "type": "local",
485
- "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
486
- "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
487
- }
488
- }
489
- }
490
- ```
491
-
492
- Then ask: `search for issues labeled bug in sinameraji/kimiflare`
493
-
494
- ## Credits
495
-
496
- - **Cloudflare Agent Memory** β€” This feature was inspired by [Cloudflare's Agent Memory](https://blog.cloudflare.com/introducing-agent-memory/) announcement. While Cloudflare's managed service requires a platform binding, kimiflare implements a local self-hosted equivalent using SQLite + Workers AI embeddings so you can use it today with your own account.
138
+ 5. Commit with [Conventional Commits](https://www.conventionalcommits.org/)
139
+ 6. Open a Pull Request
497
140
 
498
- ## License
141
+ ---
499
142
 
500
- [MIT](LICENSE) Β© Sina Meraji
143
+ Built by [Sina Meraji](https://github.com/sinameraji) and [contributors](https://github.com/sinameraji/kimiflare/graphs/contributors) Β· MIT License