@ywldan/kiro 0.4.0 → 0.5.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 +669 -519
- package/dist/agent/loop.js +25 -3
- package/dist/agent/prompt.js +3 -1
- package/dist/config.js +87 -0
- package/dist/cost.js +87 -0
- package/dist/doctor.js +14 -13
- package/dist/headless.js +21 -4
- package/dist/index.js +84 -47
- package/dist/mcp/client.js +112 -0
- package/dist/mcp/config.js +112 -0
- package/dist/mcp/env.js +28 -0
- package/dist/mcp/http.js +168 -0
- package/dist/mcp/prompt.js +24 -0
- package/dist/mcp/registry.js +206 -0
- package/dist/mcp/rpc.js +208 -0
- package/dist/mcp/stdio.js +106 -0
- package/dist/model/cli.js +27 -4
- package/dist/model/discovery.js +8 -8
- package/dist/model/wizard.js +60 -1
- package/dist/permissions.js +240 -0
- package/dist/providers/openai.js +5 -7
- package/dist/providers/request.js +71 -0
- package/dist/tools/fs.js +6 -0
- package/dist/tools/index.js +18 -4
- package/dist/tools/patch.js +3 -0
- package/dist/tools/registry.js +16 -0
- package/dist/tools/shell.js +21 -2
- package/dist/ui/App.js +157 -8
- package/dist/ui/ApprovalPrompt.js +31 -34
- package/dist/ui/MessageList.js +10 -0
- package/dist/ui/StatusBar.js +6 -2
- package/dist/ui/UsageCard.js +3 -2
- package/dist/ui/approval-policy.js +40 -2
- package/dist/ui/approval-preview.js +81 -0
- package/dist/ui/commands.js +2 -0
- package/package.json +61 -61
package/README.md
CHANGED
|
@@ -1,519 +1,669 @@
|
|
|
1
|
-
# Kiro
|
|
2
|
-
|
|
3
|
-
Kiro is a small coding agent for the terminal. It streams replies from any OpenAI-compatible endpoint into an Ink TUI, reads and edits files, runs shell commands, and asks before it changes anything.
|
|
4
|
-
|
|
5
|
-
OpenAI, OpenRouter, Ollama, LM Studio, vLLM, and other servers that implement `POST {baseUrl}/chat/completions` with SSE streaming and tool calls all work. `kiro model` discovers the endpoint's models, tests the connection, and keeps keys out of the config file.
|
|
6
|
-
|
|
7
|
-
## Requirements
|
|
8
|
-
|
|
9
|
-
- Node.js 20 or newer.
|
|
10
|
-
- An OpenAI-compatible endpoint, plus an API key if the server needs one.
|
|
11
|
-
- pnpm when building from source. npm works too, but the lockfile and scripts use pnpm.
|
|
12
|
-
|
|
13
|
-
## Install
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
npm install -g @ywldan/kiro
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
Then run `kiro` from a project directory.
|
|
20
|
-
|
|
21
|
-
From source:
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
pnpm install
|
|
25
|
-
pnpm build
|
|
26
|
-
pnpm add -g . # pnpm 11+
|
|
27
|
-
# pnpm link --global # pnpm 9/10
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
If `kiro` is missing after a global install, pnpm's bin directory is not on `PATH`. Run `pnpm setup` once, add `~/.local/share/pnpm/bin` to `PATH`, or call the binary by its full path.
|
|
31
|
-
|
|
32
|
-
You can also run it without installing:
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
node dist/index.js
|
|
36
|
-
pnpm dev
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Quick start
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
cd ~/src/my-project
|
|
43
|
-
kiro model # add a model, pick a provider, paste the key
|
|
44
|
-
kiro # start the session
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
The wizard saves the key to `~/.kiro/.env` (mode `0600`), fetches the model list, sends a test completion, and can activate the new profile right away. `~/.kiro/config.json` is created on first use and never stores the key.
|
|
48
|
-
|
|
49
|
-
The wizard runs on the alternate screen and redraws one step at a time, with a breadcrumb of the answers so far. Long menus scroll with `↑`/`↓`, `PgUp`/`PgDn`, `Home`, and `End`, and a dim counter shows how many entries are hidden. `Esc` clears the breadcrumb; quitting restores the screen and prints the saved result. Piped output falls back to plain prompts.
|
|
50
|
-
|
|
51
|
-
To skip the wizard:
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
export OPENROUTER_API_KEY="sk-or-..."
|
|
55
|
-
kiro model add --name openrouter --base-url https://openrouter.ai/api/v1 \
|
|
56
|
-
--model anthropic/claude-sonnet-4 --api-key-env OPENROUTER_API_KEY --set-active
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Set `KIRO_CONFIG_PATH` to use a different config file.
|
|
60
|
-
|
|
61
|
-
## Managing models
|
|
62
|
-
|
|
63
|
-
Kiro keeps named connection profiles. `kiro model` opens a menu with select, add, edit, remove, and quit.
|
|
64
|
-
|
|
65
|
-
### Adding a model
|
|
66
|
-
|
|
67
|
-
1. Pick a preset or a custom endpoint.
|
|
68
|
-
2. Confirm the base URL and the environment variable for the key, then paste the key. Local presets skip these steps.
|
|
69
|
-
3. Kiro calls `GET {baseUrl}/models`. Pick a number, type part of an id to filter, or enter `0` to type the id yourself. If discovery fails, Kiro explains why and asks for the id.
|
|
70
|
-
4. Accept the suggested profile name or type your own. Names use letters, digits, `-`, and `_`, and must be unique.
|
|
71
|
-
5. Optionally set `temperature`, `maxTokens`, and `contextWindow` (defaults `0.2`, `4096`, `128000`).
|
|
72
|
-
6. Kiro sends a small test completion ("Reply with OK") and reports the latency or the exact error. On failure you can retry, edit the connection, save anyway, or cancel.
|
|
73
|
-
7. Confirm whether the new profile should become active.
|
|
74
|
-
|
|
75
|
-
`Esc` or `Ctrl+C` cancels a step and leaves `config.json` and `.env` untouched.
|
|
76
|
-
|
|
77
|
-
### Presets
|
|
78
|
-
|
|
79
|
-
| Provider | Base URL | Key variable |
|
|
80
|
-
| --- | --- | --- |
|
|
81
|
-
| OpenRouter | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` |
|
|
82
|
-
| OpenAI | `https://api.openai.com/v1` | `OPENAI_API_KEY` |
|
|
83
|
-
| Groq | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` |
|
|
84
|
-
| DeepSeek | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |
|
|
85
|
-
| Together | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` |
|
|
86
|
-
| Ollama (local) | `http://localhost:11434/v1` | none |
|
|
87
|
-
| LM Studio (local) | `http://localhost:1234/v1` | none |
|
|
88
|
-
| Custom endpoint | you enter it | optional |
|
|
89
|
-
|
|
90
|
-
Presets only fill in the base URL and a suggested variable name. Every field stays editable.
|
|
91
|
-
|
|
92
|
-
### Scripted commands
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
kiro model # wizard: select / add / edit / remove
|
|
96
|
-
kiro model list # configured profiles, active marked
|
|
97
|
-
kiro model use <name> # make a profile active
|
|
98
|
-
kiro model remove <name> # delete a profile (refuses the last one)
|
|
99
|
-
kiro model test [name] # small chat completion, reports latency or error
|
|
100
|
-
|
|
101
|
-
kiro model add --name <name> --base-url <url> --model <id> \
|
|
102
|
-
[--api-key-env <VAR>] [--api-key <key>] \
|
|
103
|
-
[--temperature <0-2>] [--max-tokens <n>] [--
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
- `--api-key
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
kiro doctor
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
-
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
"
|
|
162
|
-
"
|
|
163
|
-
"
|
|
164
|
-
"
|
|
165
|
-
"
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
"
|
|
171
|
-
"
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
}
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
|
180
|
-
|
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
|
|
188
|
-
`
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
--
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
--
|
|
235
|
-
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
--
|
|
239
|
-
--
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
--
|
|
243
|
-
|
|
244
|
-
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
|
279
|
-
|
|
|
280
|
-
|
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
|
|
|
286
|
-
| `
|
|
287
|
-
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
|
329
|
-
|
|
|
330
|
-
| `/
|
|
331
|
-
| `/
|
|
332
|
-
| `/
|
|
333
|
-
| `/
|
|
334
|
-
| `/
|
|
335
|
-
|
|
|
336
|
-
| `/
|
|
337
|
-
| `/
|
|
338
|
-
| `/
|
|
339
|
-
| `/
|
|
340
|
-
| `/
|
|
341
|
-
| `/
|
|
342
|
-
|
|
|
343
|
-
| `/
|
|
344
|
-
| `/
|
|
345
|
-
| `/
|
|
346
|
-
| `/
|
|
347
|
-
|
|
348
|
-
`/
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
kiro
|
|
367
|
-
```
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
1
|
+
# Kiro
|
|
2
|
+
|
|
3
|
+
Kiro is a small coding agent for the terminal. It streams replies from any OpenAI-compatible endpoint into an Ink TUI, reads and edits files, runs shell commands, and asks before it changes anything.
|
|
4
|
+
|
|
5
|
+
OpenAI, OpenRouter, Ollama, LM Studio, vLLM, and other servers that implement `POST {baseUrl}/chat/completions` with SSE streaming and tool calls all work. `kiro model` discovers the endpoint's models, tests the connection, and keeps keys out of the config file.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 20 or newer.
|
|
10
|
+
- An OpenAI-compatible endpoint, plus an API key if the server needs one.
|
|
11
|
+
- pnpm when building from source. npm works too, but the lockfile and scripts use pnpm.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install -g @ywldan/kiro
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Then run `kiro` from a project directory.
|
|
20
|
+
|
|
21
|
+
From source:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pnpm install
|
|
25
|
+
pnpm build
|
|
26
|
+
pnpm add -g . # pnpm 11+
|
|
27
|
+
# pnpm link --global # pnpm 9/10
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
If `kiro` is missing after a global install, pnpm's bin directory is not on `PATH`. Run `pnpm setup` once, add `~/.local/share/pnpm/bin` to `PATH`, or call the binary by its full path.
|
|
31
|
+
|
|
32
|
+
You can also run it without installing:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
node dist/index.js
|
|
36
|
+
pnpm dev
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quick start
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
cd ~/src/my-project
|
|
43
|
+
kiro model # add a model, pick a provider, paste the key
|
|
44
|
+
kiro # start the session
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The wizard saves the key to `~/.kiro/.env` (mode `0600`), fetches the model list, sends a test completion, and can activate the new profile right away. `~/.kiro/config.json` is created on first use and never stores the key.
|
|
48
|
+
|
|
49
|
+
The wizard runs on the alternate screen and redraws one step at a time, with a breadcrumb of the answers so far. Long menus scroll with `↑`/`↓`, `PgUp`/`PgDn`, `Home`, and `End`, and a dim counter shows how many entries are hidden. `Esc` clears the breadcrumb; quitting restores the screen and prints the saved result. Piped output falls back to plain prompts.
|
|
50
|
+
|
|
51
|
+
To skip the wizard:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
export OPENROUTER_API_KEY="sk-or-..."
|
|
55
|
+
kiro model add --name openrouter --base-url https://openrouter.ai/api/v1 \
|
|
56
|
+
--model anthropic/claude-sonnet-4 --api-key-env OPENROUTER_API_KEY --set-active
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Set `KIRO_CONFIG_PATH` to use a different config file.
|
|
60
|
+
|
|
61
|
+
## Managing models
|
|
62
|
+
|
|
63
|
+
Kiro keeps named connection profiles. `kiro model` opens a menu with select, add, edit, remove, and quit.
|
|
64
|
+
|
|
65
|
+
### Adding a model
|
|
66
|
+
|
|
67
|
+
1. Pick a preset or a custom endpoint.
|
|
68
|
+
2. Confirm the base URL and the environment variable for the key, then paste the key. Local presets skip these steps.
|
|
69
|
+
3. Kiro calls `GET {baseUrl}/models`. Pick a number, type part of an id to filter, or enter `0` to type the id yourself. If discovery fails, Kiro explains why and asks for the id.
|
|
70
|
+
4. Accept the suggested profile name or type your own. Names use letters, digits, `-`, and `_`, and must be unique.
|
|
71
|
+
5. Optionally set `temperature`, `maxTokens`, and `contextWindow` (defaults `0.2`, `4096`, `128000`).
|
|
72
|
+
6. Kiro sends a small test completion ("Reply with OK") and reports the latency or the exact error. On failure you can retry, edit the connection, save anyway, or cancel.
|
|
73
|
+
7. Confirm whether the new profile should become active.
|
|
74
|
+
|
|
75
|
+
`Esc` or `Ctrl+C` cancels a step and leaves `config.json` and `.env` untouched.
|
|
76
|
+
|
|
77
|
+
### Presets
|
|
78
|
+
|
|
79
|
+
| Provider | Base URL | Key variable |
|
|
80
|
+
| --- | --- | --- |
|
|
81
|
+
| OpenRouter | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` |
|
|
82
|
+
| OpenAI | `https://api.openai.com/v1` | `OPENAI_API_KEY` |
|
|
83
|
+
| Groq | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` |
|
|
84
|
+
| DeepSeek | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |
|
|
85
|
+
| Together | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` |
|
|
86
|
+
| Ollama (local) | `http://localhost:11434/v1` | none |
|
|
87
|
+
| LM Studio (local) | `http://localhost:1234/v1` | none |
|
|
88
|
+
| Custom endpoint | you enter it | optional |
|
|
89
|
+
|
|
90
|
+
Presets only fill in the base URL and a suggested variable name. Every field stays editable.
|
|
91
|
+
|
|
92
|
+
### Scripted commands
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
kiro model # wizard: select / add / edit / remove
|
|
96
|
+
kiro model list # configured profiles, active marked
|
|
97
|
+
kiro model use <name> # make a profile active
|
|
98
|
+
kiro model remove <name> # delete a profile (refuses the last one)
|
|
99
|
+
kiro model test [name] # small chat completion, reports latency or error
|
|
100
|
+
|
|
101
|
+
kiro model add --name <name> --base-url <url> --model <id> \
|
|
102
|
+
[--api-key-env <VAR>] [--api-key <key>] \
|
|
103
|
+
[--temperature <0-2>] [--max-tokens <n>] [--header <name:value>]...
|
|
104
|
+
[--set-active] [--no-test]
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`--flag=value` also works. `add` validates the URL, name, model, and numbers before saving, and a failed connection test saves nothing (use `--no-test` to skip it). Success exits `0`; validation, network, and test failures exit non-zero with a message on stderr.
|
|
108
|
+
|
|
109
|
+
Keys for `kiro model add`:
|
|
110
|
+
|
|
111
|
+
- `--api-key <key>` writes the key to `~/.kiro/.env` under `--api-key-env`, or under a generated `KIRO_<PROFILE>_API_KEY`.
|
|
112
|
+
- `--api-key-env <VAR>` stores nothing; the variable must already exist in the environment or in `~/.kiro/.env`.
|
|
113
|
+
- With neither flag, the profile has no key, which is fine for local servers.
|
|
114
|
+
- `--header "Name: value"` adds a request header and can repeat. The value may use `${VAR}` to read the environment, so a gateway token stays out of `config.json`. `Authorization`, `Content-Type`, and the other headers Kiro sends are refused; use `apiKeyEnv` for the key.
|
|
115
|
+
|
|
116
|
+
### Updates
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
kiro check # installed version vs npm
|
|
120
|
+
kiro update # npm install -g @ywldan/kiro@latest
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`check` exits `0` when current, `1` when an update exists, and `2` when the registry cannot be reached. `update` prints npm's output and needs the permissions of a global install.
|
|
124
|
+
|
|
125
|
+
### Diagnostics
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
kiro doctor # config, key storage, and endpoint checks
|
|
129
|
+
kiro doctor --offline # skip the network checks
|
|
130
|
+
kiro doctor --test # also send a small chat completion
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`doctor` checks the Node version, the config file, `.env` permissions, the active profile's key, and `GET /models`. Each line is marked `ok`, `warn`, `fail`, or `skip`, with a suggested fix when something is wrong. It never prints a key. Exit code is `0` when no check fails and `1` otherwise. `--profile <name>` inspects another profile. A missing `GET /models` is only a warning, because some servers do not implement it.
|
|
134
|
+
|
|
135
|
+
### Where keys live
|
|
136
|
+
|
|
137
|
+
`config.json` stores only `apiKeyEnv`, the name of a variable. Values live in the environment or in `~/.kiro/.env`:
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
# ~/.kiro/.env
|
|
141
|
+
OPENROUTER_API_KEY=sk-or-...
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- The file is created on demand with mode `0600`; the directory uses `0700` where the platform supports it.
|
|
145
|
+
- Kiro loads `~/.kiro/.env` at startup, and real environment variables win.
|
|
146
|
+
- Updating a key rewrites only that line. Removing a profile leaves its secret in `.env` so other profiles can reuse it.
|
|
147
|
+
- Keys are not written to `config.json`, sessions, logs, or the TUI. Kiro shows `set via $VAR`, `missing ($VAR)`, or a mask such as `sk-…abcd`.
|
|
148
|
+
- Values from `.env` and every profile's `apiKeyEnv` are removed from `run_command`'s environment and redacted from tool output, so `env` or `cat ~/.kiro/.env` cannot copy a key into the transcript or a saved session.
|
|
149
|
+
|
|
150
|
+
Set `KIRO_ENV_PATH` to use a different `.env` file.
|
|
151
|
+
|
|
152
|
+
## Configuration
|
|
153
|
+
|
|
154
|
+
`~/.kiro/config.json`:
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"activeProfile": "openai",
|
|
159
|
+
"profiles": {
|
|
160
|
+
"openai": {
|
|
161
|
+
"type": "openai",
|
|
162
|
+
"baseUrl": "https://api.openai.com/v1",
|
|
163
|
+
"apiKeyEnv": "OPENAI_API_KEY",
|
|
164
|
+
"model": "gpt-4.1",
|
|
165
|
+
"temperature": 0.2,
|
|
166
|
+
"maxTokens": 4096,
|
|
167
|
+
"contextWindow": 128000
|
|
168
|
+
},
|
|
169
|
+
"local": {
|
|
170
|
+
"type": "openai",
|
|
171
|
+
"baseUrl": "http://localhost:11434/v1",
|
|
172
|
+
"model": "qwen2.5-coder:14b",
|
|
173
|
+
"temperature": 0.2
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
| Field | Required | Meaning |
|
|
180
|
+
| --- | --- | --- |
|
|
181
|
+
| `type` | yes | Provider type. Only `openai` is implemented. |
|
|
182
|
+
| `baseUrl` | yes | API base URL including the version segment, e.g. `https://api.openai.com/v1`. Kiro appends `/chat/completions`. |
|
|
183
|
+
| `apiKeyEnv` | no | Name of the environment variable holding the API key. Omit for local servers that need no auth. |
|
|
184
|
+
| `model` | yes | Model name sent to the endpoint. |
|
|
185
|
+
| `models` | no | Model ids the `/model` picker offers for this profile. Filled by discovery; the model in use is always included. |
|
|
186
|
+
| `temperature` | no | Sampling temperature. |
|
|
187
|
+
| `maxTokens` | no | Maximum response tokens. |
|
|
188
|
+
| `contextWindow` | no | Approximate context window in tokens, at least 1000. Defaults to `128000`; drives the ctx meter and compaction. |
|
|
189
|
+
| `headers` | no | Extra request headers, for gateways that need a routing or API-version header. Values may use `${VAR}`. `Authorization` and the other headers Kiro sends are rejected. |
|
|
190
|
+
| `pricing` | no | Price overrides in dollars per million tokens: `{ "input": 0.5, "output": 1.5 }`. Used for the cost estimate; the built-in table is a fallback. |
|
|
191
|
+
|
|
192
|
+
`activeProfile` selects the profile used at startup. `/model <name>` switches at runtime and `--profile` switches for one run.
|
|
193
|
+
|
|
194
|
+
### Example endpoints
|
|
195
|
+
|
|
196
|
+
**OpenRouter** (key from `~/.kiro/.env` or the environment)
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
export OPENROUTER_API_KEY="sk-or-..."
|
|
200
|
+
kiro model add --name openrouter \
|
|
201
|
+
--base-url https://openrouter.ai/api/v1 \
|
|
202
|
+
--model anthropic/claude-sonnet-4 \
|
|
203
|
+
--api-key-env OPENROUTER_API_KEY --set-active
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
**Ollama** (no key; discovery normally works, but you can enter a manually pulled tag)
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
kiro model add --name ollama \
|
|
210
|
+
--base-url http://localhost:11434/v1 \
|
|
211
|
+
--model qwen2.5-coder:14b --set-active
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**LM Studio, vLLM, or another local server**
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
kiro model add --name local \
|
|
218
|
+
--base-url http://localhost:1234/v1 \
|
|
219
|
+
--model local-model --set-active
|
|
220
|
+
|
|
221
|
+
# A server without GET /models: name the model directly.
|
|
222
|
+
kiro model add --name vllm \
|
|
223
|
+
--base-url http://gpu-box:8000/v1 \
|
|
224
|
+
--model my-model --no-test
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
The JSON form above still works if you prefer editing by hand. `kiro model` then **Edit a model** can update fields and re-test.
|
|
228
|
+
|
|
229
|
+
## CLI options
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
kiro [options]
|
|
233
|
+
|
|
234
|
+
--profile <name> Use a profile from ~/.kiro/config.json
|
|
235
|
+
--base-url <url> Override the active profile's base URL
|
|
236
|
+
--model <name> Override the active profile's model
|
|
237
|
+
-c, --continue Resume the most recent session for this directory
|
|
238
|
+
--resume <id> Resume a specific saved session
|
|
239
|
+
-p, --prompt <text>
|
|
240
|
+
Run one turn without a TUI ("-" or no text reads the
|
|
241
|
+
prompt from stdin); replies stream to stdout
|
|
242
|
+
--yolo Skip all approval prompts (use with care)
|
|
243
|
+
--mouse Mouse reporting (on by default): wheel scrolls the transcript
|
|
244
|
+
--no-mouse Disable mouse reporting so plain click-drag selection works
|
|
245
|
+
--no-alt-screen Do not switch to the terminal's alternate screen
|
|
246
|
+
--no-skills Do not read skill folders at all (KIRO_NO_SKILLS=1 does the same)
|
|
247
|
+
--no-mcp Do not start MCP servers (KIRO_NO_MCP=1 does the same)
|
|
248
|
+
-h, --help Show help
|
|
249
|
+
-v, --version Show version
|
|
250
|
+
|
|
251
|
+
kiro check Compare the installed version with the latest on npm
|
|
252
|
+
kiro update Install the latest version from npm globally
|
|
253
|
+
kiro doctor Check Node, config, key storage, and the active endpoint
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
`--flag=value` works too. CLI overrides last for the current process only.
|
|
257
|
+
|
|
258
|
+
## Headless mode
|
|
259
|
+
|
|
260
|
+
`kiro -p "…"` runs one turn without Ink, for scripts, cron jobs, and CI:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
kiro -p "explain what this repo does" # read-only answers work immediately
|
|
264
|
+
kiro -p "add the missing tests" --yolo # let it write and run commands
|
|
265
|
+
git diff | kiro -p "review this patch" # pipe the prompt
|
|
266
|
+
kiro -p "continue" --continue # continue this directory's session
|
|
267
|
+
echo "summarize README.md" | kiro -p - > summary.md # "-" reads stdin
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Assistant text goes to stdout; tool calls, reasoning, compaction notices, and errors go to stderr, so `kiro -p … > out.md` stays clean. The turn uses the same provider, tools, system prompt, compaction, and session store as the TUI.
|
|
271
|
+
|
|
272
|
+
Approvals are denied unless you pass `--yolo`, so a piped run cannot write or execute anything unsupervised. Leave `--yolo` off when read-only tools are enough.
|
|
273
|
+
|
|
274
|
+
Exit codes: `0` success, `1` model/tool/session error, `2` usage error, `130` cancelled with Ctrl+C. Headless runs do not record prompt history. `KIRO_STREAM_IDLE_MS` changes the stall timeout (default 120000 ms; `0` disables it).
|
|
275
|
+
|
|
276
|
+
## Using the TUI
|
|
277
|
+
|
|
278
|
+
| Key | Action |
|
|
279
|
+
| --- | --- |
|
|
280
|
+
| `Enter` | Send the prompt, or run the highlighted `/` command |
|
|
281
|
+
| `Ctrl+J`, `Alt+Enter`, or `\` + Enter | Start a new line without sending |
|
|
282
|
+
| `Ctrl+C` | Press twice to exit; while a turn runs, the first press cancels it |
|
|
283
|
+
| `PgUp` / `PgDn` | Scroll the history (the wheel works too, unless you pass `--no-mouse`) |
|
|
284
|
+
| `Ctrl+O` | Expand or collapse the full output of the most recent tool call |
|
|
285
|
+
| `↑` / `↓` | Move through the `/` command menu; with an empty input, recall prompt history |
|
|
286
|
+
| `Tab` | Complete the highlighted `/` command |
|
|
287
|
+
| `Esc` | Clear the input, close the command menu, cancel a model wizard step, or deny a pending approval |
|
|
288
|
+
| `Ctrl+A` / `Ctrl+E` | Move to start / end of input |
|
|
289
|
+
| `Backspace` / `Delete` | Delete before / after the cursor |
|
|
290
|
+
| `Ctrl+U` / `Ctrl+K` | Delete before / after the cursor |
|
|
291
|
+
| `Ctrl+W` | Delete the previous word |
|
|
292
|
+
| Left / Right / Home / End | Move the cursor |
|
|
293
|
+
|
|
294
|
+
The input grows to six rows and scrolls with the cursor. Text pasted from another window keeps its line breaks and is not sent until you press Enter.
|
|
295
|
+
|
|
296
|
+
Type `@` to pick a file from the project. The list respects `.gitignore` and skips `node_modules`, `.git`, `dist`, and `build`. Use `↑`/`↓` to move, `Tab` or `Enter` to insert the path, and `Esc` to close the list without clearing the prompt. Names with spaces are inserted quoted.
|
|
297
|
+
|
|
298
|
+
The status bar shows the profile, model, working directory, context meter (`ctx 42k/128k`), queued message count, and state (`ready`, `thinking…`, `replying…`, `running <tool>…`, `approval needed`, `cancelling…`, `Ctrl+C again to quit`). Long profile names are shortened in the middle. On wide terminals the context meter moves into the Usage card.
|
|
299
|
+
|
|
300
|
+
You can type while the agent works. The prompt is queued, shown in the transcript, and runs when the current turn ends; the status bar shows `N queued`. Ctrl+C clears the queue with the running turn, and slash commands queue the same way.
|
|
301
|
+
|
|
302
|
+
Ctrl+C while idle waits two seconds for a second press before exiting. `/exit` quits immediately. During a turn, the first press cancels it.
|
|
303
|
+
|
|
304
|
+
Prompt history is stored per directory in `~/.kiro/history/` (mode `0600`, 200 entries). `↑` recalls with an empty input, `↓` moves forward, and editing leaves history mode. Keys are redacted before a prompt is written. Set `KIRO_HISTORY_DIR` to change the location.
|
|
305
|
+
|
|
306
|
+
Reasoning traces stream as a dim block and collapse to `reasoning (done, not saved)` when the answer starts. They are not written to sessions or `/export`.
|
|
307
|
+
|
|
308
|
+
Each finished reply shows its duration and, when the endpoint reports usage, output throughput (`8.4s · 23 tok/s`). Both are display-only and are not stored in sessions.
|
|
309
|
+
|
|
310
|
+
On terminals at least 110 columns wide with room for 9 transcript rows, a Usage card sits to the right of the conversation. It shows session token totals (`↑` sent, `↓` received), API requests, an estimated cost, a context gauge, and the last reply's timing. Totals come from endpoint usage, accumulate across tool rounds, and survive `/resume`; compaction requests are not counted. A `~` marks an estimated context number. Below 110 columns the card hides and `ctx` returns to the status bar. `/usage` toggles it, and `/context` prints the totals at any width.
|
|
311
|
+
|
|
312
|
+
Replies render as Markdown: headings, emphasis, inline code, lists, task checkboxes, blockquotes, links, code blocks, and tables. Table columns size to their content, honour alignment markers, and wrap; a table too wide to read falls back to plain rows. Unknown markers stay literal, so streaming never breaks the layout.
|
|
313
|
+
|
|
314
|
+
Typing `/` opens the command palette over the bottom rows of the transcript, so the conversation does not move. It filters as you type; `↑`/`↓` select, `Enter` runs, `Tab` completes, and `Esc` clears.
|
|
315
|
+
|
|
316
|
+
`/model` opens a centered picker over the transcript. The list uses the full height and reports hidden entries (`↑ 5 more · 6-15 of 30 · ↓ 15 more`). On terminals narrower than 60 columns or shorter than 18 rows it falls back to an inline panel.
|
|
317
|
+
|
|
318
|
+
On a TTY, Kiro uses the alternate screen. When it exits, through `/exit`, a double Ctrl+C, or an error, the shell contents come back. Pipes and CI logs are untouched. `--no-alt-screen` stays on the normal screen.
|
|
319
|
+
|
|
320
|
+
Mouse reporting is on by default, so the wheel scrolls the transcript. Hold Shift while dragging to select text, or run `/mouse` (or start with `--no-mouse`) to restore plain click-drag selection and scroll with `PgUp`/`PgDn`.
|
|
321
|
+
|
|
322
|
+
While `run_command` runs, the status bar shows its newest output line and the running tool call keeps a dim `⎿ …` tail under it, so a build or test run reports progress instead of an idle spinner. The live line is display only: the full output still arrives with the tool result, and headless runs never print it.
|
|
323
|
+
|
|
324
|
+
Tool results are one-line summaries. `Ctrl+O` expands the latest result inline; `PgUp`/`PgDn` scroll it. `/export` writes the whole conversation, including full tool arguments and results, to a Markdown file.
|
|
325
|
+
|
|
326
|
+
### Slash commands
|
|
327
|
+
|
|
328
|
+
| Command | Action |
|
|
329
|
+
| --- | --- |
|
|
330
|
+
| `/help` | Show commands and keys |
|
|
331
|
+
| `/model` | Open the centered model picker: profile first, then searchable stored models |
|
|
332
|
+
| `/model <name>` | Switch profile without restarting |
|
|
333
|
+
| `/model add` | Guided setup; prompts appear in the input box and the key is masked |
|
|
334
|
+
| `/model edit [name]` | Edit fields, replace the key, re-test, and save |
|
|
335
|
+
| `/model remove [name]` | Remove a profile after confirmation (refuses the last one) |
|
|
336
|
+
| `/model test [name]` | Test the active or named profile; prints latency or the exact error |
|
|
337
|
+
| `/model list --remote` | List models offered by the active endpoint's `GET /models` |
|
|
338
|
+
| `/context` | Show approximate context use by message role plus session token totals |
|
|
339
|
+
| `/usage` | Show or hide the Usage card, giving the transcript the full width |
|
|
340
|
+
| `/skills` | List installed skills, their source, and any skipped entries |
|
|
341
|
+
| `/skill <name> [request]` | Load a skill, optionally with your request in the same line |
|
|
342
|
+
| `/<skill name> [request]` | Call an installed skill directly, e.g. `/anti-slop rewrite this paragraph` |
|
|
343
|
+
| `/compact` | Summarize older turns now, keeping the last four user turns verbatim |
|
|
344
|
+
| `/sessions` | List saved sessions for this directory and for other directories |
|
|
345
|
+
| `/resume` | Open the session picker (tabs for this directory and others) |
|
|
346
|
+
| `/resume <n\|id>` | Resume a session from this directory by list number or id (prefixes work) |
|
|
347
|
+
| `/undo` | Revert the most recent write, edit, or patch (repeat to step further back) |
|
|
348
|
+
| `/clear` | Start a new session, keeping the old one on disk |
|
|
349
|
+
| `/export [file]` | Write the transcript (with full tool output) to a Markdown file |
|
|
350
|
+
| `/mouse` | Toggle mouse reporting: wheel scroll vs normal text selection |
|
|
351
|
+
| `/allow` | List tools that skip approval for this session |
|
|
352
|
+
| `/allow clear` | Ask for approval again for every tool |
|
|
353
|
+
| `/rules` | List saved rules in `.kiro/permissions.json`, numbered |
|
|
354
|
+
| `/rules remove <n>` | Delete one saved rule |
|
|
355
|
+
| `/rules clear` | Delete the rule file |
|
|
356
|
+
| `/mcp` | Show configured MCP servers, their state, and their tools |
|
|
357
|
+
| `/exit` | Quit |
|
|
358
|
+
|
|
359
|
+
`/model` has two steps. The first lists profiles grouped by endpoint, with the active one marked `*`; `Enter` opens the models. The second lists stored model ids with the current one marked `*`; `Enter` applies it and saves the choice. On the model step, type to filter (all space-separated terms must match), `Esc` clears the query and then goes back, and `Ctrl+R` refetches `GET /models`. `Ctrl+C` closes the picker.
|
|
360
|
+
|
|
361
|
+
## Sessions
|
|
362
|
+
|
|
363
|
+
Kiro saves each conversation under `~/.kiro/sessions/`, in a directory named from a hash of the working directory:
|
|
364
|
+
|
|
365
|
+
```
|
|
366
|
+
~/.kiro/sessions/<cwd-hash>/<session-id>.json
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
Sessions store user, assistant, and tool messages, the title, timestamps, and the profile and model in use. System prompts are rebuilt for the current directory every turn, so they are not stored. Writes are atomic, the directory uses `0700`, and files use `0600`.
|
|
370
|
+
|
|
371
|
+
Saving happens after each user message and again when a turn ends, so a crash loses at most the in-flight response. Ctrl+C and `/exit` wait for the save. Set `KIRO_SESSIONS_DIR` to store sessions elsewhere.
|
|
372
|
+
|
|
373
|
+
Resume with:
|
|
374
|
+
|
|
375
|
+
```bash
|
|
376
|
+
kiro --continue # most recent session for this directory
|
|
377
|
+
kiro --resume <id> # a specific session
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
`/sessions` and `/resume <n|id>` do the same from inside the TUI. `/resume` without arguments opens a picker with two tabs: `This directory` and `Other directories`, grouped by folder. Use `←`/`→` to switch tabs, `↑`/`↓` to move, type to filter by title, id, or path, `Enter` to resume, and `Esc` to close. Resuming a session from another directory switches Kiro's working directory to that folder, rebuilds the system prompt, skills, and prompt history for it, and saves the session there from then on. `/clear` starts a new session without deleting the old one. Kiro does not auto-resume; without a flag it starts fresh.
|
|
381
|
+
|
|
382
|
+
Session files are plaintext and contain prompts, code from tools, and command output. They never contain API keys, but treat them like shell history.
|
|
383
|
+
|
|
384
|
+
## Context and compaction
|
|
385
|
+
|
|
386
|
+
Kiro tracks how much of the context window the conversation uses. The OpenAI provider requests `stream_options: { include_usage: true }` and uses the endpoint's numbers when they arrive. Servers that ignore the option still work through a rough estimate of four characters per token. The status bar shows `ctx <used>/<window>` (or the Usage card on wide terminals), and `/context` breaks the total down by role and prints cumulative totals.
|
|
387
|
+
|
|
388
|
+
Each profile may set `contextWindow` (default `128000`). At about 80% of the window, Kiro compacts before the next request:
|
|
389
|
+
|
|
390
|
+
- the system prompt stays;
|
|
391
|
+
- the last four user turns stay verbatim, with their assistant and tool messages;
|
|
392
|
+
- older turns become a summary of the goal, files touched, decisions, current state, and open TODOs;
|
|
393
|
+
- very large old tool results become short placeholders first, so the summarizer is not flooded;
|
|
394
|
+
- the cut always falls on a user-message boundary, so a tool-call round is never split.
|
|
395
|
+
|
|
396
|
+
Compaction shows a notice and is written to the session, so a resumed conversation continues from the compacted history. `/compact` runs the same pass on demand. If the summary fails, the turn continues with the uncompacted context and an error notice. Counts are approximate and corrected when the endpoint reports usage.
|
|
397
|
+
|
|
398
|
+
## Tools and safety
|
|
399
|
+
|
|
400
|
+
| Tool | What it does | Approval |
|
|
401
|
+
| --- | --- | --- |
|
|
402
|
+
| `read_file(path, offset?, limit?)` | Reads a file with numbered lines and truncation notes | never |
|
|
403
|
+
| `list_dir(path)` | Lists one directory, with `/` after directories | never |
|
|
404
|
+
| `glob(pattern, path?)` | Finds files by glob, e.g. `src/**/*.ts`. Respects `.gitignore`; skips `node_modules`, `.git`, `dist`, `build`; caps at 200 results | never |
|
|
405
|
+
| `grep(pattern, path?, glob?, ignore_case?, context_lines?, max_results?)` | Regex search returning `file:line: text`. Uses `rg` when installed, otherwise a built-in scanner that skips binary and large files | never |
|
|
406
|
+
| `write_file(path, content)` | Creates or overwrites a file, creating parent directories | always (except `--yolo`) |
|
|
407
|
+
| `edit_file(path, old_string, new_string, replace_all?)` | Exact replacement; `replace_all` replaces every occurrence. Missing text returns a hint with the closest line | always (except `--yolo`) |
|
|
408
|
+
| `multi_edit(path, edits[])` | Several exact replacements in one file, validated together and written once | always (except `--yolo`) |
|
|
409
|
+
| `apply_patch(patch)` | Applies a unified diff to one or more files after validating every hunk | always (except `--yolo`) |
|
|
410
|
+
| `run_command(command, timeout_seconds?)` | Runs a shell command in the working directory | always (except `--yolo`) |
|
|
411
|
+
| `ask_user(question, options, header?, multi_select?, allow_other?)` | Asks the user to pick from 1 to 4 short options and waits for the answer. `Other` accepts typed text | never |
|
|
412
|
+
|
|
413
|
+
`grep` and `glob` keep large repositories manageable, and `read_file` pages through long files. Use `multi_edit` for several changes in one file and `apply_patch` for coordinated changes across files; `apply_patch` validates the whole patch before writing and rejects deletions and renames.
|
|
414
|
+
|
|
415
|
+
`ask_user` shows a centered prompt when the model needs a decision that belongs to you, such as a design direction or a choice between conflicting requirements. Use `↑/↓` to move, `Enter` to choose, `Space` to toggle when several answers are allowed, and `Esc` to dismiss. Dismissing returns a refusal to the model and the turn continues. Headless runs have no terminal, so the tool returns an error and the model is told to ask in plain text instead.
|
|
416
|
+
|
|
417
|
+
Approvals show a diff, or the exact command, and offer:
|
|
418
|
+
|
|
419
|
+
- `[y]` allow once
|
|
420
|
+
- `[a]` allow this tool for the rest of the session (the status bar shows `auto:<tool>`; `/allow clear` revokes it)
|
|
421
|
+
- `[s]` always allow this pattern (saved to `.kiro/permissions.json`; the prompt names the pattern first)
|
|
422
|
+
- `[d]` always deny this exact command or path
|
|
423
|
+
- `[n]` deny and return the refusal to the model
|
|
424
|
+
|
|
425
|
+
The preview keeps six rows. A diff drops its `---`/`+++` file headers and window markers so the changed lines fit, and a long command keeps both ends, since a destructive step is often the last line. A preview that still does not fit ends with a count of the hidden rows.
|
|
426
|
+
|
|
427
|
+
Paths resolve against the working directory. Symlinks and `..` escapes are caught with `realpath`: reads, listings, and searches outside the workspace are refused, while writes, edits, and patches outside it need an explicit approval warning. `run_command` times out after 60 seconds by default (maximum 600), kills the process group on timeout or cancel, and truncates output to about 20k characters, keeping the head and tail. `read_file` returns 400 lines by default (maximum 2000) and points at the next offset. `glob` and `grep` honour `.gitignore`, always skip `node_modules`, `.git`, `dist`, and `build`, and cap their output with a hint on narrowing the search. Every tool result is also capped at 60k characters.
|
|
428
|
+
|
|
429
|
+
Read-only tools (`read_file`, `list_dir`, `glob`, `grep`) in one response run in parallel, and results are appended in call order. A write, edit, patch, or command breaks the batch and runs with an approval prompt.
|
|
430
|
+
|
|
431
|
+
`--yolo` skips all approvals. The status bar shows a red `YOLO` badge, the transcript warns once, and `/help` repeats it. It cannot be turned off inside the session; restart without the flag. Use it only in directories you trust.
|
|
432
|
+
|
|
433
|
+
### Cost estimate
|
|
434
|
+
|
|
435
|
+
The Usage card shows an estimated cost in dollars next to the token counts, and
|
|
436
|
+
`/context` prints the same number with the price used. Prices come from a small
|
|
437
|
+
built-in table matched on the model id (`gpt-4o`, `claude-*-sonnet`, `gemini-*-flash`,
|
|
438
|
+
`deepseek-*`, and similar), in dollars per million tokens. Local endpoints
|
|
439
|
+
(`localhost`, a private address, `.local`) report `$0 free`. A `~` marks a total
|
|
440
|
+
that includes a request whose model had no known price.
|
|
441
|
+
|
|
442
|
+
The table is a convenience, not a bill. Set `pricing` in the profile for a
|
|
443
|
+
private or resold endpoint:
|
|
444
|
+
|
|
445
|
+
```json
|
|
446
|
+
{
|
|
447
|
+
"type": "openai",
|
|
448
|
+
"baseUrl": "https://gateway.internal/v1",
|
|
449
|
+
"model": "team-large",
|
|
450
|
+
"pricing": { "input": 0.5, "output": 1.5 }
|
|
451
|
+
}
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
Headless runs print one line of usage and cost to stderr at the end of a turn,
|
|
455
|
+
so a CI job can watch spend without parsing the transcript.
|
|
456
|
+
|
|
457
|
+
### Saved approval rules
|
|
458
|
+
|
|
459
|
+
`[s]` and `[d]` write a rule to `.kiro/permissions.json` in the project, so the
|
|
460
|
+
decision survives restarts and covers headless runs in CI:
|
|
461
|
+
|
|
462
|
+
```json
|
|
463
|
+
{
|
|
464
|
+
"version": 1,
|
|
465
|
+
"rules": [
|
|
466
|
+
{ "tool": "run_command", "match": "npm test*", "action": "allow" },
|
|
467
|
+
{ "tool": "run_command", "match": "curl*", "action": "deny" }
|
|
468
|
+
]
|
|
469
|
+
}
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
`tool` is a tool name or `*`; `match` is a glob over the command text or the
|
|
473
|
+
workspace-relative path, where `*` matches any characters (including `/`) and
|
|
474
|
+
`?` matches one. The prompt shows the pattern before it is saved: `[s]` on
|
|
475
|
+
`npm test -- --watch` offers `npm test*`, and on `rm -rf build` it offers
|
|
476
|
+
`rm -rf build*` rather than the dangerous `rm*`.
|
|
477
|
+
|
|
478
|
+
A shell command is split on `;`, `&&`, `||`, `|`, and newlines, and every part
|
|
479
|
+
must be allowed, so `npm test*` never covers `npm test; rm -rf ~`. A deny rule
|
|
480
|
+
always wins, and a deny still applies under `--yolo`. A rule never pre-approves
|
|
481
|
+
a write outside the working directory; those always ask.
|
|
482
|
+
|
|
483
|
+
Rules are read at startup and whenever the working directory changes. `/rules`
|
|
484
|
+
lists them numbered, `/rules remove <n>` deletes one, and `/rules clear` removes
|
|
485
|
+
the file. A broken file reports once and is treated as empty, so it cannot lock
|
|
486
|
+
you out. Headless runs use the same rules and never write new ones: `kiro -p`
|
|
487
|
+
approves only what a saved rule covers, plus `--yolo`. Set `KIRO_PERMISSIONS_PATH`
|
|
488
|
+
to keep the rules outside the project.
|
|
489
|
+
|
|
490
|
+
### Undo and checkpoints
|
|
491
|
+
|
|
492
|
+
Before each `write_file`, `edit_file`, `multi_edit`, and `apply_patch`, Kiro copies the affected files to `~/.kiro/checkpoints/<cwd-hash>/` (directory `0700`, backups `0600`). `/undo` restores the latest call: edited files get their previous bytes, created files are removed. Running it again steps back through the 30 most recent calls.
|
|
493
|
+
|
|
494
|
+
Snapshots are best effort; if one fails, the tool still runs. `run_command` is not checkpointed because a command can touch anything, so commit before running destructive commands. Set `KIRO_CHECKPOINTS_DIR` to change the location. The manifest stores paths, not contents, so it stays small.
|
|
495
|
+
|
|
496
|
+
## AGENTS.md
|
|
497
|
+
|
|
498
|
+
If `AGENTS.md` exists in the working directory, its contents are appended to the system prompt every turn, including after edits.
|
|
499
|
+
|
|
500
|
+
## Skills
|
|
501
|
+
|
|
502
|
+
A skill is a folder of instructions that Kiro loads when it is needed. Kiro checks four places in order, and the first definition of a name wins:
|
|
503
|
+
|
|
504
|
+
1. `<cwd>/.kiro/skills/`
|
|
505
|
+
2. `<cwd>/.claude/skills/` (Claude Code skills work unchanged)
|
|
506
|
+
3. `~/.kiro/skills/`
|
|
507
|
+
4. `~/.claude/skills/`
|
|
508
|
+
|
|
509
|
+
Each skill is a directory with `SKILL.md`:
|
|
510
|
+
|
|
511
|
+
```md
|
|
512
|
+
---
|
|
513
|
+
name: anti-slop
|
|
514
|
+
description: Remove AI-slop patterns from prose before answering.
|
|
515
|
+
---
|
|
516
|
+
|
|
517
|
+
Delete "delve", "tapestry", and stacked em dashes. Prefer concrete nouns.
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
Only `name` and `description` are read. Other keys such as `allowed-tools` and `license` are ignored, and a skill can never skip an approval. A folder counts as a skill when it holds `SKILL.md`, two levels deep, so `skills/<name>/SKILL.md` and `skills/<group>/<name>/SKILL.md` both work. Symlinked folders are followed with loop detection. Supporting files (references, templates, scripts) are read or run like any other file, with the same rules.
|
|
521
|
+
|
|
522
|
+
The system prompt gets only names and descriptions. Up to 30 skills keep a full description; beyond that descriptions are clipped to 60 characters; very large collections fall back to bare names, so the prompt stays bounded. When a request matches, the model calls `read_skill` to load the body. The tool is read-only, needs no approval, runs alongside other reads, and reports whether the skill came from the project or the user folder.
|
|
523
|
+
|
|
524
|
+
`/skills` lists what was found, its source, and every skipped folder with the reason (no `SKILL.md`, a loose `SKILL.md`, a missing description, a duplicate name, an oversized file). `/skill anti-slop` loads a skill for the next message, and `/skill anti-slop rewrite this paragraph` loads it and sends the request in the same turn. The transcript shows the short command while the model gets the full instructions. The first time a repository skill is loaded, Kiro says so once.
|
|
525
|
+
|
|
526
|
+
Every installed skill is also a slash command, so `/anti-slop rewrite this paragraph` is the same turn as `/skill anti-slop rewrite this paragraph`. Skill names appear in the `/` menu, labelled `skill · <description>`, and can be completed with `Tab`. Built-in commands win a clash, so a skill named `model` is reachable only as `/skill model`, and `/skills` flags it. The command list refreshes after each turn, so new skills appear without a restart.
|
|
527
|
+
|
|
528
|
+
The index is rebuilt every turn, so edits to `SKILL.md` apply on the next message. `KIRO_SKILLS_DIR` replaces both user roots. `--no-skills` or `KIRO_NO_SKILLS=1` (which can live in `~/.kiro/.env`) skips skill folders entirely.
|
|
529
|
+
|
|
530
|
+
## How it works
|
|
531
|
+
|
|
532
|
+
- The OpenAI provider streams SSE responses and assembles tool-call deltas by index. It also accepts a plain JSON reply from servers that ignore streaming.
|
|
533
|
+
- Reasoning models (`o1`/`o3`/`o4`, `gpt-5`) use `max_completion_tokens` instead of `max_tokens` and omit temperature. If another endpoint rejects `max_tokens` and names `max_completion_tokens`, Kiro retries once with the new parameter.
|
|
534
|
+
- A stream that sends no bytes for `KIRO_STREAM_IDLE_MS` (default 120000, `0` disables) is cancelled and retried like a dropped connection.
|
|
535
|
+
- When a profile has no `contextWindow`, Kiro infers one from the model id (a suffix such as `-32k`, or a family table) and falls back to `128000`. `/context` says whether the value was inferred.
|
|
536
|
+
- If the endpoint rejects a request as too long (400/413 with a context-length message), Kiro compacts and retries the round once.
|
|
537
|
+
- `finish_reason: length` produces an explicit notice, including when tool-call arguments were cut off.
|
|
538
|
+
- Transient failures are retried up to three times with backoff and jitter: network errors, dropped connections before output, 429, and 5xx. `Retry-After` is honoured up to 60 seconds. Errors after partial text, cancels, and 400/401/403/404 are not retried. `KIRO_RETRY_BASE_MS` changes the base delay (default 500ms).
|
|
539
|
+
- Malformed tool JSON, unknown tools, non-zero exits, and timeouts go back to the model as tool errors instead of ending the session.
|
|
540
|
+
- A turn is capped at 25 tool rounds.
|
|
541
|
+
- Model discovery and the connection test both time out after 10 seconds and can be cancelled.
|
|
542
|
+
- Config saves are atomic and merge with the file on disk, so unknown fields survive. Invalid JSON can be backed up and replaced with a template.
|
|
543
|
+
|
|
544
|
+
## MCP servers
|
|
545
|
+
|
|
546
|
+
Kiro can start Model Context Protocol servers and offer their tools to the model. Servers are configured in JSON, one file per scope:
|
|
547
|
+
|
|
548
|
+
1. `<cwd>/.kiro/mcp.json` for the project
|
|
549
|
+
2. `~/.kiro/mcp.json` for your machine
|
|
550
|
+
|
|
551
|
+
The project file wins when both define the same name. The shape matches the file other MCP clients use, so it can be copied in unchanged:
|
|
552
|
+
|
|
553
|
+
```json
|
|
554
|
+
{
|
|
555
|
+
"mcpServers": {
|
|
556
|
+
"filesystem": {
|
|
557
|
+
"command": "npx",
|
|
558
|
+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/notes"],
|
|
559
|
+
"env": { "LOG_LEVEL": "warn" }
|
|
560
|
+
},
|
|
561
|
+
"disabled-example": {
|
|
562
|
+
"command": "node",
|
|
563
|
+
"args": ["server.js"],
|
|
564
|
+
"disabled": true
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
}
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
Both transports work. An entry with a `url` (or `"type": "http"`) is called over streamable HTTP: one POST per message, the reply as JSON or as an SSE stream, and the `Mcp-Session-Id` header repeated after the handshake. An entry with a `command` is started as a child process and spoken to over stdio. Entries marked `"disabled"` are listed by `/mcp` and skipped. Set `KIRO_MCP_CONFIG` to load a different file instead of the two defaults.
|
|
571
|
+
|
|
572
|
+
A remote server usually needs a token. Put it in `headers` and point at the environment so the file stays free of secrets:
|
|
573
|
+
|
|
574
|
+
```json
|
|
575
|
+
{
|
|
576
|
+
"mcpServers": {
|
|
577
|
+
"agentrelay": {
|
|
578
|
+
"type": "http",
|
|
579
|
+
"url": "https://mcp.example.com/mcp",
|
|
580
|
+
"headers": { "Authorization": "Bearer ${AGENTRELAY_TOKEN}" },
|
|
581
|
+
"timeout": 3600000
|
|
582
|
+
}
|
|
583
|
+
}
|
|
584
|
+
}
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
`timeout` is milliseconds and raises the limit for one `tools/call` on that server; `KIRO_MCP_TIMEOUT_MS` (default 30000) is the global value. Raise it for a tool that blocks, such as a long-poll `wait_for_message`; a per-server `timeout` wins. Ctrl+C still cancels such a call, because the request is aborted rather than waited out.
|
|
588
|
+
|
|
589
|
+
The same server can be reached through a stdio shim instead, which is useful when the remote side needs a reconnect:
|
|
590
|
+
|
|
591
|
+
```json
|
|
592
|
+
{
|
|
593
|
+
"mcpServers": {
|
|
594
|
+
"agentrelay": {
|
|
595
|
+
"command": "npx",
|
|
596
|
+
"args": ["-y", "agentrelay-mcp", "--url", "https://mcp.example.com/mcp", "--token", "${AGENTRELAY_TOKEN}"],
|
|
597
|
+
"timeout": 3600000
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
}
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
Server names and tool names become one tool name, `mcp__<server>__<tool>`, so two servers can offer the same tool. `/mcp` prints every server with its state, its tool count, and where the config came from.
|
|
604
|
+
|
|
605
|
+
A few rules keep MCP predictable:
|
|
606
|
+
|
|
607
|
+
- Every MCP tool call asks for approval, even under a session `[a]` allow, and saved rules cannot pre-approve one because the request has no rule subject. A server runs outside the workspace sandbox, so a rule that matches a command or a path does not describe it.
|
|
608
|
+
- A server that fails to start is reported once and skipped. The rest of the session runs normally, and a server that prints non-JSON lines (a banner, a log line) produces a notice instead of an error.
|
|
609
|
+
- The server inherits the environment Kiro runs with, minus stored credentials, plus any `env` in its entry. `${VAR}` inside a value is expanded from the environment.
|
|
610
|
+
- Tool output is flattened to text: text and resource contents are kept, and image or audio blocks become a placeholder.
|
|
611
|
+
- `--no-mcp` (or `KIRO_NO_MCP=1`) starts nothing. `KIRO_MCP_CONNECT_MS` sets the handshake timeout (default 15000) and `KIRO_MCP_TIMEOUT_MS` the timeout for a `tools/call` (default 30000), which a server's own `timeout` overrides.
|
|
612
|
+
- A 401 or 403 on an HTTP server names the status and points at `headers`, instead of failing silently. An unreachable URL becomes an `error` status and the session continues.
|
|
613
|
+
|
|
614
|
+
MCP tools are always treated as unsafe: no parallel batch, always an approval prompt. The protocol is JSON-RPC 2.0 over stdio, one JSON object per line.
|
|
615
|
+
|
|
616
|
+
## Testing
|
|
617
|
+
|
|
618
|
+
```bash
|
|
619
|
+
pnpm test # backend tests against an in-process mock server
|
|
620
|
+
pnpm mock # mock server on port 8787 for manual TUI testing
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
The mock server streams scripted replies with tool calls, slow responses, and errors, and can force `401`/`404`, custom headers, or a dropped connection. Point a profile at `http://localhost:8787/v1` with any model name; no key is needed.
|
|
624
|
+
|
|
625
|
+
The tests cover streaming and tool calls, approvals, retries and timeouts, path escapes, search and edit behaviour, config and key handling, compaction, sessions, the TUI components, and the skills pipeline from `SKILL.md` to `read_skill`. Ink components are rendered with `renderToString`, so layouts are checked as text, not through a terminal. Palette, scrolling, Markdown, approvals, cancellation, and the `/usage` toggle are covered this way. Model workflow tests use a temporary `$HOME`, so the real `~/.kiro` is never touched.
|
|
626
|
+
|
|
627
|
+
## Project layout
|
|
628
|
+
|
|
629
|
+
```
|
|
630
|
+
src/
|
|
631
|
+
index.tsx CLI entry point
|
|
632
|
+
headless.ts one-shot -p runner (stdout text, stderr diagnostics)
|
|
633
|
+
config.ts config load/validation/overrides, atomic save, recovery
|
|
634
|
+
env.ts ~/.kiro/.env parser/writer, masking, key status
|
|
635
|
+
secrets.ts credential registry: redaction and child-process env filtering
|
|
636
|
+
sessions.ts atomic session save/load/list
|
|
637
|
+
model/ presets, discovery/test, context-window inference, shared wizard, CLI + screen renderer
|
|
638
|
+
mcp/ MCP config, JSON-RPC channel, stdio client, tool registry
|
|
639
|
+
providers/ Provider interface, OpenAI-compatible implementation
|
|
640
|
+
agent/ system prompt, skill discovery/parsing, agent loop, token estimates, compaction
|
|
641
|
+
tools/ tool registry, fs/search/patch/shell/skill tools, checkpoints, glob/gitignore matching
|
|
642
|
+
ui/ Ink app, markdown, command palette, prompt history, scrolling, approvals, status bar, export
|
|
643
|
+
test/
|
|
644
|
+
mock-server.ts scripted OpenAI-compatible SSE server + /models variants
|
|
645
|
+
mcp-server.ts small stdio MCP server used by the tests
|
|
646
|
+
e2e.ts backend test suite
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
## Known limitations
|
|
650
|
+
|
|
651
|
+
- Only the `openai` provider type. Anthropic-style APIs are not supported.
|
|
652
|
+
- Model discovery assumes an OpenAI-compatible `GET /models`. Endpoints without it work, but the model id must be typed manually.
|
|
653
|
+
- `@` lists files only and stops at 50,000 paths; directories and ignored files are not offered.
|
|
654
|
+
- Removing a profile leaves its key in `~/.kiro/.env`; there is no command that deletes stored secrets.
|
|
655
|
+
- No sub-agents, plugins, web search, image input, themes, or git integration.
|
|
656
|
+
- The HTTP transport has no SSE reconnect and no server-to-client requests: a server that pushes a request over HTTP gets a notice, not an answer.
|
|
657
|
+
- The live output line shows the newest line only, capped at 400 characters; earlier lines arrive with the tool result.
|
|
658
|
+
- Approval rules match a glob, not a shell grammar: a rule for `npm test*` also covers `npm test-evil`. Review saved rules with `/rules` when a project's rules come from someone else.
|
|
659
|
+
- The cost estimate uses a built-in list-price table that ages; `/context` names the price it used, and `pricing` in the profile overrides it.
|
|
660
|
+
- Sessions are single-process and stored as plaintext JSON. There is no delete or rename command. The `/resume` picker can load a session from another directory and switches the working directory to it; `/export` writes a Markdown transcript you can keep.
|
|
661
|
+
- `/undo` covers `write_file`, `edit_file`, `multi_edit`, and `apply_patch` only. It keeps the last 30 calls, and `run_command` changes are outside its reach; use Git for a complete safety net.
|
|
662
|
+
- Prompt history is plaintext, capped at 200 entries per directory, and only recalled in the TUI (not in `-p` mode).
|
|
663
|
+
- Only contiguous read-only tool calls run in parallel; writes, edits, patches, and commands stay sequential.
|
|
664
|
+
- Context use is approximate when the endpoint does not report usage, and compaction depends on the model producing a usable summary. `/compact` is the manual escape hatch.
|
|
665
|
+
- Markdown support covers the common subset; images and syntax highlighting are shown as plain text.
|
|
666
|
+
- Mouse reporting is on by default and takes over click-drag selection; use Shift+drag to copy, or `--no-mouse` / `/mouse` to turn it off and scroll with `PgUp`/`PgDn`.
|
|
667
|
+
- The context-window inference is a best-effort guess. For an unusual or self-hosted model, set `contextWindow` explicitly or compaction will trigger too late.
|
|
668
|
+
- The TUI targets Linux, macOS, and Windows Terminal; Windows process killing uses `taskkill` but has not been exercised on a real Windows machine.
|
|
669
|
+
- Very narrow terminals and unusually long approval previews are clipped rather than paginated.
|