@ywldan/kiro 0.2.11 → 0.3.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 +134 -147
- package/dist/agent/compact.js +1 -1
- package/dist/agent/prompt.js +1 -0
- package/dist/doctor.js +251 -0
- package/dist/headless.js +1 -1
- package/dist/index.js +10 -1
- package/dist/model/wizard.js +4 -4
- package/dist/tools/index.js +1 -1
- package/dist/tools/search.js +2 -60
- package/dist/tools/shell.js +1 -1
- package/dist/tools/walk.js +62 -0
- package/dist/ui/App.js +23 -5
- package/dist/ui/Input.js +199 -31
- package/dist/ui/MessageList.js +26 -0
- package/dist/ui/UsageCard.js +2 -2
- package/dist/ui/file-index.js +111 -0
- package/dist/ui/mention.js +63 -0
- package/dist/ui/mouse.js +1 -1
- package/dist/ui/text.js +159 -7
- package/dist/update.js +5 -5
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,45 +1,38 @@
|
|
|
1
1
|
# Kiro
|
|
2
2
|
|
|
3
|
-
|
|
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
4
|
|
|
5
|
-
|
|
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
6
|
|
|
7
7
|
## Requirements
|
|
8
8
|
|
|
9
|
-
- Node.js 20 or newer
|
|
10
|
-
-
|
|
11
|
-
-
|
|
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
12
|
|
|
13
13
|
## Install
|
|
14
14
|
|
|
15
|
-
From npm:
|
|
16
|
-
|
|
17
15
|
```bash
|
|
18
16
|
npm install -g @ywldan/kiro
|
|
19
17
|
```
|
|
20
18
|
|
|
21
|
-
Then run `kiro` from
|
|
19
|
+
Then run `kiro` from a project directory.
|
|
22
20
|
|
|
23
21
|
From source:
|
|
24
22
|
|
|
25
23
|
```bash
|
|
26
24
|
pnpm install
|
|
27
25
|
pnpm build
|
|
28
|
-
|
|
29
|
-
# pnpm
|
|
30
|
-
pnpm add -g .
|
|
31
|
-
|
|
32
|
-
# pnpm 9/10
|
|
33
|
-
# pnpm link --global
|
|
26
|
+
pnpm add -g . # pnpm 11+
|
|
27
|
+
# pnpm link --global # pnpm 9/10
|
|
34
28
|
```
|
|
35
29
|
|
|
36
|
-
If `kiro` is
|
|
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.
|
|
37
31
|
|
|
38
|
-
You can also run it without
|
|
32
|
+
You can also run it without installing:
|
|
39
33
|
|
|
40
34
|
```bash
|
|
41
35
|
node dist/index.js
|
|
42
|
-
# or, during development:
|
|
43
36
|
pnpm dev
|
|
44
37
|
```
|
|
45
38
|
|
|
@@ -47,50 +40,39 @@ pnpm dev
|
|
|
47
40
|
|
|
48
41
|
```bash
|
|
49
42
|
cd ~/src/my-project
|
|
50
|
-
kiro model
|
|
51
|
-
kiro
|
|
43
|
+
kiro model # add a model, pick a provider, paste the key
|
|
44
|
+
kiro # start the session
|
|
52
45
|
```
|
|
53
46
|
|
|
54
|
-
The wizard
|
|
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.
|
|
55
48
|
|
|
56
|
-
|
|
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.
|
|
57
50
|
|
|
58
|
-
|
|
51
|
+
To skip the wizard:
|
|
59
52
|
|
|
60
53
|
```bash
|
|
61
54
|
export OPENROUTER_API_KEY="sk-or-..."
|
|
62
55
|
kiro model add --name openrouter --base-url https://openrouter.ai/api/v1 \
|
|
63
56
|
--model anthropic/claude-sonnet-4 --api-key-env OPENROUTER_API_KEY --set-active
|
|
64
|
-
kiro
|
|
65
57
|
```
|
|
66
58
|
|
|
67
|
-
Set `KIRO_CONFIG_PATH` to use a different config file
|
|
59
|
+
Set `KIRO_CONFIG_PATH` to use a different config file.
|
|
68
60
|
|
|
69
61
|
## Managing models
|
|
70
62
|
|
|
71
|
-
Kiro keeps named connection profiles. `kiro model` opens a
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
Model workflow
|
|
75
|
-
1. Select the active model
|
|
76
|
-
2. Add a new model
|
|
77
|
-
3. Edit a model
|
|
78
|
-
4. Remove a model
|
|
79
|
-
5. Quit
|
|
80
|
-
```
|
|
63
|
+
Kiro keeps named connection profiles. `kiro model` opens a menu with select, add, edit, remove, and quit.
|
|
81
64
|
|
|
82
65
|
### Adding a model
|
|
83
66
|
|
|
84
|
-
1. Pick a preset or
|
|
85
|
-
2. Confirm
|
|
86
|
-
3.
|
|
87
|
-
4.
|
|
88
|
-
5.
|
|
89
|
-
6.
|
|
90
|
-
7.
|
|
91
|
-
8. Confirm **Set as active profile?** (`Y/n`).
|
|
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.
|
|
92
74
|
|
|
93
|
-
`Esc` or `Ctrl+C` cancels
|
|
75
|
+
`Esc` or `Ctrl+C` cancels a step and leaves `config.json` and `.env` untouched.
|
|
94
76
|
|
|
95
77
|
### Presets
|
|
96
78
|
|
|
@@ -105,7 +87,7 @@ Model workflow
|
|
|
105
87
|
| LM Studio (local) | `http://localhost:1234/v1` | none |
|
|
106
88
|
| Custom endpoint | you enter it | optional |
|
|
107
89
|
|
|
108
|
-
Presets only
|
|
90
|
+
Presets only fill in the base URL and a suggested variable name. Every field stays editable.
|
|
109
91
|
|
|
110
92
|
### Scripted commands
|
|
111
93
|
|
|
@@ -121,39 +103,49 @@ kiro model add --name <name> --base-url <url> --model <id> \
|
|
|
121
103
|
[--temperature <0-2>] [--max-tokens <n>] [--set-active] [--no-test]
|
|
122
104
|
```
|
|
123
105
|
|
|
124
|
-
`--flag=value` works
|
|
106
|
+
`--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.
|
|
125
107
|
|
|
126
|
-
|
|
108
|
+
Keys for `kiro model add`:
|
|
127
109
|
|
|
128
|
-
- `--api-key <key>` writes the key to `~/.kiro/.env` under `--api-key-env`, or under a generated `KIRO_<
|
|
129
|
-
- `--api-key-env <VAR>`
|
|
130
|
-
-
|
|
110
|
+
- `--api-key <key>` writes the key to `~/.kiro/.env` under `--api-key-env`, or under a generated `KIRO_<PROFILE>_API_KEY`.
|
|
111
|
+
- `--api-key-env <VAR>` stores nothing; the variable must already exist in the environment or in `~/.kiro/.env`.
|
|
112
|
+
- With neither flag, the profile has no key, which is fine for local servers.
|
|
131
113
|
|
|
132
|
-
###
|
|
114
|
+
### Updates
|
|
133
115
|
|
|
134
116
|
```bash
|
|
135
|
-
kiro check
|
|
136
|
-
kiro update
|
|
117
|
+
kiro check # installed version vs npm
|
|
118
|
+
kiro update # npm install -g @ywldan/kiro@latest
|
|
137
119
|
```
|
|
138
120
|
|
|
139
|
-
`check` exits `0` when current, `1` when an update
|
|
121
|
+
`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.
|
|
122
|
+
|
|
123
|
+
### Diagnostics
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
kiro doctor # config, key storage, and endpoint checks
|
|
127
|
+
kiro doctor --offline # skip the network checks
|
|
128
|
+
kiro doctor --test # also send a small chat completion
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`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.
|
|
140
132
|
|
|
141
133
|
### Where keys live
|
|
142
134
|
|
|
143
|
-
|
|
135
|
+
`config.json` stores only `apiKeyEnv`, the name of a variable. Values live in the environment or in `~/.kiro/.env`:
|
|
144
136
|
|
|
145
137
|
```
|
|
146
138
|
# ~/.kiro/.env
|
|
147
139
|
OPENROUTER_API_KEY=sk-or-...
|
|
148
140
|
```
|
|
149
141
|
|
|
150
|
-
- The file is created on demand with mode `0600`;
|
|
151
|
-
-
|
|
152
|
-
- Updating a key rewrites only that line
|
|
153
|
-
- Keys are
|
|
154
|
-
- Values
|
|
142
|
+
- The file is created on demand with mode `0600`; the directory uses `0700` where the platform supports it.
|
|
143
|
+
- Kiro loads `~/.kiro/.env` at startup, and real environment variables win.
|
|
144
|
+
- Updating a key rewrites only that line. Removing a profile leaves its secret in `.env` so other profiles can reuse it.
|
|
145
|
+
- 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`.
|
|
146
|
+
- 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.
|
|
155
147
|
|
|
156
|
-
Set `KIRO_ENV_PATH` to use a different `.env` file
|
|
148
|
+
Set `KIRO_ENV_PATH` to use a different `.env` file.
|
|
157
149
|
|
|
158
150
|
## Configuration
|
|
159
151
|
|
|
@@ -184,16 +176,16 @@ Set `KIRO_ENV_PATH` to use a different `.env` file (useful for testing).
|
|
|
184
176
|
|
|
185
177
|
| Field | Required | Meaning |
|
|
186
178
|
| --- | --- | --- |
|
|
187
|
-
| `type` | yes | Provider type. Only `openai` is implemented
|
|
179
|
+
| `type` | yes | Provider type. Only `openai` is implemented. |
|
|
188
180
|
| `baseUrl` | yes | API base URL including the version segment, e.g. `https://api.openai.com/v1`. Kiro appends `/chat/completions`. |
|
|
189
181
|
| `apiKeyEnv` | no | Name of the environment variable holding the API key. Omit for local servers that need no auth. |
|
|
190
182
|
| `model` | yes | Model name sent to the endpoint. |
|
|
191
183
|
| `models` | no | Model ids the `/model` picker offers for this profile. Filled by discovery; the model in use is always included. |
|
|
192
184
|
| `temperature` | no | Sampling temperature. |
|
|
193
185
|
| `maxTokens` | no | Maximum response tokens. |
|
|
194
|
-
| `contextWindow` | no | Approximate
|
|
186
|
+
| `contextWindow` | no | Approximate context window in tokens, at least 1000. Defaults to `128000`; drives the ctx meter and compaction. |
|
|
195
187
|
|
|
196
|
-
`activeProfile` selects the profile used at startup. `/model <name>` switches at runtime
|
|
188
|
+
`activeProfile` selects the profile used at startup. `/model <name>` switches at runtime and `--profile` switches for one run.
|
|
197
189
|
|
|
198
190
|
### Example endpoints
|
|
199
191
|
|
|
@@ -207,7 +199,7 @@ kiro model add --name openrouter \
|
|
|
207
199
|
--api-key-env OPENROUTER_API_KEY --set-active
|
|
208
200
|
```
|
|
209
201
|
|
|
210
|
-
**Ollama** (no key; discovery normally works, but a manually pulled tag
|
|
202
|
+
**Ollama** (no key; discovery normally works, but you can enter a manually pulled tag)
|
|
211
203
|
|
|
212
204
|
```bash
|
|
213
205
|
kiro model add --name ollama \
|
|
@@ -215,21 +207,20 @@ kiro model add --name ollama \
|
|
|
215
207
|
--model qwen2.5-coder:14b --set-active
|
|
216
208
|
```
|
|
217
209
|
|
|
218
|
-
**LM Studio
|
|
210
|
+
**LM Studio, vLLM, or another local server**
|
|
219
211
|
|
|
220
212
|
```bash
|
|
221
213
|
kiro model add --name local \
|
|
222
214
|
--base-url http://localhost:1234/v1 \
|
|
223
215
|
--model local-model --set-active
|
|
224
216
|
|
|
225
|
-
# A server without GET /models:
|
|
226
|
-
# and skip the test if it is not running yet.
|
|
217
|
+
# A server without GET /models: name the model directly.
|
|
227
218
|
kiro model add --name vllm \
|
|
228
219
|
--base-url http://gpu-box:8000/v1 \
|
|
229
220
|
--model my-model --no-test
|
|
230
221
|
```
|
|
231
222
|
|
|
232
|
-
|
|
223
|
+
The JSON form above still works if you prefer editing by hand. `kiro model` then **Edit a model** can update fields and re-test.
|
|
233
224
|
|
|
234
225
|
## CLI options
|
|
235
226
|
|
|
@@ -254,13 +245,14 @@ kiro [options]
|
|
|
254
245
|
|
|
255
246
|
kiro check Compare the installed version with the latest on npm
|
|
256
247
|
kiro update Install the latest version from npm globally
|
|
248
|
+
kiro doctor Check Node, config, key storage, and the active endpoint
|
|
257
249
|
```
|
|
258
250
|
|
|
259
|
-
`--flag=value` works
|
|
251
|
+
`--flag=value` works too. CLI overrides last for the current process only.
|
|
260
252
|
|
|
261
253
|
## Headless mode
|
|
262
254
|
|
|
263
|
-
`kiro -p "…"` runs
|
|
255
|
+
`kiro -p "…"` runs one turn without Ink, for scripts, cron jobs, and CI:
|
|
264
256
|
|
|
265
257
|
```bash
|
|
266
258
|
kiro -p "explain what this repo does" # read-only answers work immediately
|
|
@@ -270,17 +262,18 @@ kiro -p "continue" --continue # continue this directory
|
|
|
270
262
|
echo "summarize README.md" | kiro -p - > summary.md # "-" reads stdin
|
|
271
263
|
```
|
|
272
264
|
|
|
273
|
-
Assistant text goes to
|
|
265
|
+
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.
|
|
274
266
|
|
|
275
|
-
Approvals are denied
|
|
267
|
+
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.
|
|
276
268
|
|
|
277
|
-
Exit codes: `0` success, `1` model/tool/session error, `2` usage error
|
|
269
|
+
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).
|
|
278
270
|
|
|
279
271
|
## Using the TUI
|
|
280
272
|
|
|
281
273
|
| Key | Action |
|
|
282
274
|
| --- | --- |
|
|
283
275
|
| `Enter` | Send the prompt, or run the highlighted `/` command |
|
|
276
|
+
| `Ctrl+J`, `Alt+Enter`, or `\` + Enter | Start a new line without sending |
|
|
284
277
|
| `Ctrl+C` | Press twice to exit; while a turn runs, the first press cancels it |
|
|
285
278
|
| `PgUp` / `PgDn` | Scroll the history (the wheel works too, unless you pass `--no-mouse`) |
|
|
286
279
|
| `Ctrl+O` | Expand or collapse the full output of the most recent tool call |
|
|
@@ -293,33 +286,37 @@ Exit codes: `0` success, `1` model/tool/session error, `2` usage error (includin
|
|
|
293
286
|
| `Ctrl+W` | Delete the previous word |
|
|
294
287
|
| Left / Right / Home / End | Move the cursor |
|
|
295
288
|
|
|
296
|
-
The
|
|
289
|
+
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.
|
|
290
|
+
|
|
291
|
+
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
292
|
|
|
298
|
-
The
|
|
293
|
+
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
294
|
|
|
300
|
-
|
|
295
|
+
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
296
|
|
|
302
|
-
|
|
297
|
+
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
298
|
|
|
304
|
-
|
|
299
|
+
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
300
|
|
|
306
|
-
|
|
301
|
+
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
302
|
|
|
308
|
-
|
|
303
|
+
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
304
|
|
|
310
|
-
|
|
305
|
+
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, 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
306
|
|
|
312
|
-
|
|
307
|
+
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
308
|
|
|
314
|
-
|
|
309
|
+
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
310
|
|
|
316
|
-
|
|
311
|
+
`/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
312
|
|
|
318
|
-
|
|
313
|
+
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
314
|
|
|
320
|
-
|
|
315
|
+
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
316
|
|
|
322
|
-
|
|
317
|
+
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.
|
|
318
|
+
|
|
319
|
+
### Slash commands
|
|
323
320
|
|
|
324
321
|
| Command | Action |
|
|
325
322
|
| --- | --- |
|
|
@@ -347,19 +344,19 @@ Slash commands:
|
|
|
347
344
|
| `/allow clear` | Ask for approval again for every tool |
|
|
348
345
|
| `/exit` | Quit |
|
|
349
346
|
|
|
350
|
-
`/model`
|
|
347
|
+
`/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.
|
|
351
348
|
|
|
352
349
|
## Sessions
|
|
353
350
|
|
|
354
|
-
Kiro saves
|
|
351
|
+
Kiro saves each conversation under `~/.kiro/sessions/`, in a directory named from a hash of the working directory:
|
|
355
352
|
|
|
356
353
|
```
|
|
357
354
|
~/.kiro/sessions/<cwd-hash>/<session-id>.json
|
|
358
355
|
```
|
|
359
356
|
|
|
360
|
-
|
|
357
|
+
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`.
|
|
361
358
|
|
|
362
|
-
Saving happens after
|
|
359
|
+
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.
|
|
363
360
|
|
|
364
361
|
Resume with:
|
|
365
362
|
|
|
@@ -368,23 +365,23 @@ kiro --continue # most recent session for this directory
|
|
|
368
365
|
kiro --resume <id> # a specific session
|
|
369
366
|
```
|
|
370
367
|
|
|
371
|
-
|
|
368
|
+
`/sessions` and `/resume <n|id>` do the same from inside the TUI. `/clear` starts a new session without deleting the old one. Kiro does not auto-resume; without a flag it starts fresh.
|
|
372
369
|
|
|
373
|
-
Session files are plaintext and contain
|
|
370
|
+
Session files are plaintext and contain prompts, code from tools, and command output. They never contain API keys, but treat them like shell history.
|
|
374
371
|
|
|
375
372
|
## Context and compaction
|
|
376
373
|
|
|
377
|
-
Kiro tracks how much of the
|
|
374
|
+
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.
|
|
378
375
|
|
|
379
|
-
Each profile may set `contextWindow` (default `128000`). At about 80% of
|
|
376
|
+
Each profile may set `contextWindow` (default `128000`). At about 80% of the window, Kiro compacts before the next request:
|
|
380
377
|
|
|
381
|
-
- the system prompt
|
|
382
|
-
- the last four user turns,
|
|
383
|
-
- older turns become a
|
|
384
|
-
- very large old tool results
|
|
385
|
-
- the cut
|
|
378
|
+
- the system prompt stays;
|
|
379
|
+
- the last four user turns stay verbatim, with their assistant and tool messages;
|
|
380
|
+
- older turns become a summary of the goal, files touched, decisions, current state, and open TODOs;
|
|
381
|
+
- very large old tool results become short placeholders first, so the summarizer is not flooded;
|
|
382
|
+
- the cut always falls on a user-message boundary, so a tool-call round is never split.
|
|
386
383
|
|
|
387
|
-
Compaction
|
|
384
|
+
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.
|
|
388
385
|
|
|
389
386
|
## Tools and safety
|
|
390
387
|
|
|
@@ -400,40 +397,40 @@ Compaction appears as a notice in the transcript and is written into the session
|
|
|
400
397
|
| `apply_patch(patch)` | Applies a unified diff to one or more files after validating every hunk | always (except `--yolo`) |
|
|
401
398
|
| `run_command(command, timeout_seconds?)` | Runs a shell command in the working directory | always (except `--yolo`) |
|
|
402
399
|
|
|
403
|
-
|
|
400
|
+
`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.
|
|
404
401
|
|
|
405
|
-
|
|
402
|
+
Approvals show a diff, or the exact command, and offer:
|
|
406
403
|
|
|
407
404
|
- `[y]` allow once
|
|
408
|
-
- `[a]`
|
|
409
|
-
- `[n]` deny
|
|
405
|
+
- `[a]` allow this tool for the rest of the session (the status bar shows `auto:<tool>`; `/allow clear` revokes it)
|
|
406
|
+
- `[n]` deny and return the refusal to the model
|
|
410
407
|
|
|
411
|
-
Paths
|
|
408
|
+
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.
|
|
412
409
|
|
|
413
|
-
Read-only tools (`read_file`, `list_dir`, `glob`, `grep`)
|
|
410
|
+
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.
|
|
414
411
|
|
|
415
|
-
`--yolo` skips all approvals
|
|
412
|
+
`--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.
|
|
416
413
|
|
|
417
414
|
### Undo and checkpoints
|
|
418
415
|
|
|
419
|
-
Before
|
|
416
|
+
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.
|
|
420
417
|
|
|
421
|
-
|
|
418
|
+
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.
|
|
422
419
|
|
|
423
420
|
## AGENTS.md
|
|
424
421
|
|
|
425
|
-
If
|
|
422
|
+
If `AGENTS.md` exists in the working directory, its contents are appended to the system prompt every turn, including after edits.
|
|
426
423
|
|
|
427
424
|
## Skills
|
|
428
425
|
|
|
429
|
-
A skill is a folder of instructions that Kiro loads
|
|
426
|
+
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:
|
|
430
427
|
|
|
431
428
|
1. `<cwd>/.kiro/skills/`
|
|
432
|
-
2. `<cwd>/.claude/skills
|
|
429
|
+
2. `<cwd>/.claude/skills/` (Claude Code skills work unchanged)
|
|
433
430
|
3. `~/.kiro/skills/`
|
|
434
431
|
4. `~/.claude/skills/`
|
|
435
432
|
|
|
436
|
-
Each skill is a directory with
|
|
433
|
+
Each skill is a directory with `SKILL.md`:
|
|
437
434
|
|
|
438
435
|
```md
|
|
439
436
|
---
|
|
@@ -444,51 +441,40 @@ description: Remove AI-slop patterns from prose before answering.
|
|
|
444
441
|
Delete "delve", "tapestry", and stacked em dashes. Prefer concrete nouns.
|
|
445
442
|
```
|
|
446
443
|
|
|
447
|
-
Only `name` and `description` are read
|
|
444
|
+
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.
|
|
448
445
|
|
|
449
|
-
|
|
446
|
+
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.
|
|
450
447
|
|
|
451
|
-
`/skills` lists what was found,
|
|
448
|
+
`/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.
|
|
452
449
|
|
|
453
|
-
Every installed skill is also a slash command
|
|
450
|
+
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.
|
|
454
451
|
|
|
455
|
-
The index is rebuilt every turn, so edits to `SKILL.md` apply on the next message.
|
|
452
|
+
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.
|
|
456
453
|
|
|
457
454
|
## How it works
|
|
458
455
|
|
|
459
|
-
- The OpenAI provider
|
|
460
|
-
-
|
|
461
|
-
- A stream
|
|
462
|
-
-
|
|
463
|
-
-
|
|
464
|
-
-
|
|
465
|
-
-
|
|
466
|
-
-
|
|
467
|
-
-
|
|
468
|
-
-
|
|
469
|
-
-
|
|
470
|
-
- Ctrl+C aborts the HTTP stream and any running command; partial assistant text is preserved.
|
|
471
|
-
- `kiro -p` runs the same agent loop without Ink, streams assistant text to stdout and diagnostics to stderr, denies tool calls unless `--yolo` is given, and saves the session like the TUI.
|
|
472
|
-
- Sessions are saved atomically after each user message and completed turn, and are restored by rebuilding the visible transcript from the stored messages.
|
|
473
|
-
- Reply timing is measured per model round (request start to finished reply) and includes network latency. Token throughput uses the endpoint's completion-token usage; both are shown only in the live TUI and are not persisted. Session token totals are persisted separately in the session file.
|
|
474
|
-
- Model discovery calls `GET {baseUrl}/models` with a 10-second timeout; the connection test sends one tiny non-tool chat completion with the same timeout. Both can be cancelled.
|
|
475
|
-
- Config saves are atomic and merge into the file on disk, so fields Kiro does not know about are preserved. Invalid JSON can be backed up and replaced with a fresh template.
|
|
476
|
-
- Keys are never written to `config.json`, sessions, or logs. They live in `~/.kiro/.env` (mode `0600`) or the real environment, and the config stores only `apiKeyEnv`; actual values are never printed, are stripped from `run_command`'s environment, and are redacted from tool output before it reaches the model.
|
|
456
|
+
- 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.
|
|
457
|
+
- 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.
|
|
458
|
+
- A stream that sends no bytes for `KIRO_STREAM_IDLE_MS` (default 120000, `0` disables) is cancelled and retried like a dropped connection.
|
|
459
|
+
- 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.
|
|
460
|
+
- If the endpoint rejects a request as too long (400/413 with a context-length message), Kiro compacts and retries the round once.
|
|
461
|
+
- `finish_reason: length` produces an explicit notice, including when tool-call arguments were cut off.
|
|
462
|
+
- 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).
|
|
463
|
+
- Malformed tool JSON, unknown tools, non-zero exits, and timeouts go back to the model as tool errors instead of ending the session.
|
|
464
|
+
- A turn is capped at 25 tool rounds.
|
|
465
|
+
- Model discovery and the connection test both time out after 10 seconds and can be cancelled.
|
|
466
|
+
- 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.
|
|
477
467
|
|
|
478
468
|
## Testing
|
|
479
469
|
|
|
480
470
|
```bash
|
|
481
|
-
pnpm test # backend tests against an in-process mock
|
|
482
|
-
pnpm mock #
|
|
471
|
+
pnpm test # backend tests against an in-process mock server
|
|
472
|
+
pnpm mock # mock server on port 8787 for manual TUI testing
|
|
483
473
|
```
|
|
484
474
|
|
|
485
|
-
The mock server
|
|
486
|
-
|
|
487
|
-
The suite covers streaming, multiple tool calls per response, approvals and denials, malformed tool JSON, the round cap, HTTP errors, malformed SSE, unreachable endpoints, retries for 429/5xx and connection drops, no retry after partial output or a 401, the retry limit, read-only batching and ordered results, the global result cap, abort, workspace escapes, read paging, edit uniqueness, command exit codes and timeouts, output truncation, config validation, missing keys, system-prompt/`AGENTS.md` injection, and session persistence. Search tests cover glob matching, `.gitignore` handling, heavy-directory skips, result caps, ripgrep and the built-in grep fallback, binary/large-file skipping, and invalid regexes. Editing tests cover `replace_all`, near-miss hints, atomic multi-edits, and patch validation for updates, new files, conflicts, and rejected deletions. Context tests cover `stream_options` and usage parsing, token estimates and formatting, the 80% threshold, compaction boundaries, kept tool-call rounds, the old-result placeholder pass, empty-summary rejection, loop-level compaction (once per turn, non-fatal failures), persistence of compacted sessions, the `ctx` status-bar meter, and `contextWindow` config/wizard handling. Session tests cover atomic save/load, usage totals, file permissions, per-directory isolation, sorting, corrupt-file skipping, id validation, and reconstruction of resumed tool blocks and statuses. TUI unit tests cover Markdown styles, wrapping, and table alignment, slash-command filtering/shared help text, the Usage card and its width collapse, the centered model-picker overlay with its frame and hidden-entry counts, and SGR mouse-wheel parsing; pty runs exercise the command palette, mouse and PgUp/PgDn scrolling, Markdown rendering, approvals, cancellation, and the `/usage` toggle.
|
|
488
|
-
|
|
489
|
-
Model workflow tests use a temp `$HOME` so the real `~/.kiro` is never touched. They cover atomic config saves that preserve unknown fields, profile-name and URL validation, corrupt-config backup/recovery, `.env` parsing and real-environment precedence, `0600` writes, masking, the exact preset list, discovery success/401/missing-`/models`/timeout, the connection test, and wizard add/edit/select/remove/last-profile refusal/cancel/manual-model fallback. Scripted `kiro model add`, `list`, `use`, `test`, and `remove` run through the real CLI against the in-process mock; a failed test saves nothing, keys never appear in `config.json`, and generated keys land in `.env`. The wizard screen renderer is unit-tested against a fake stream: alternate-screen enter/leave, a new menu replacing the previous one, the breadcrumb of answered prompts (menu title instead of `Choose`, the value kept by pressing Enter, confirmation of a `Y/n` default, and the reset on Escape or a return to the root menu), stale errors dropped at a step change, log trimming to the terminal height with the prompt always visible, keyboard scrolling of an over-long list (page, top, bottom, clamping, reset on new output), and replaying results after the screen is restored. `/model` groups profiles by endpoint so several models behind one base URL are listed as siblings.
|
|
475
|
+
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.
|
|
490
476
|
|
|
491
|
-
The
|
|
477
|
+
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`. Pty runs exercise the palette, scrolling, Markdown, approvals, cancellation, and the `/usage` toggle. Model workflow tests use a temporary `$HOME`, so the real `~/.kiro` is never touched.
|
|
492
478
|
|
|
493
479
|
## Project layout
|
|
494
480
|
|
|
@@ -514,9 +500,10 @@ test/
|
|
|
514
500
|
|
|
515
501
|
- Only the `openai` provider type. Anthropic-style APIs are not supported.
|
|
516
502
|
- Model discovery assumes an OpenAI-compatible `GET /models`. Endpoints without it work, but the model id must be typed manually.
|
|
503
|
+
- `@` lists files only and stops at 50,000 paths; directories and ignored files are not offered.
|
|
517
504
|
- Removing a profile leaves its key in `~/.kiro/.env`; there is no command that deletes stored secrets.
|
|
518
505
|
- No sub-agents, MCP, plugins, web search, image input, themes, or git integration.
|
|
519
|
-
- Sessions are single-process and stored as plaintext JSON. There is no delete or rename command and no cross-directory session browser; `/export` writes a Markdown transcript you can keep
|
|
506
|
+
- Sessions are single-process and stored as plaintext JSON. There is no delete or rename command and no cross-directory session browser; `/export` writes a Markdown transcript you can keep.
|
|
520
507
|
- `/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.
|
|
521
508
|
- Prompt history is plaintext, capped at 200 entries per directory, and only recalled in the TUI (not in `-p` mode).
|
|
522
509
|
- Only contiguous read-only tool calls run in parallel; writes, edits, patches, and commands stay sequential.
|
|
@@ -524,5 +511,5 @@ test/
|
|
|
524
511
|
- Markdown support covers the common subset; images and syntax highlighting are shown as plain text.
|
|
525
512
|
- 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`.
|
|
526
513
|
- 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.
|
|
527
|
-
- The TUI targets Linux, macOS, and Windows Terminal; Windows
|
|
514
|
+
- The TUI targets Linux, macOS, and Windows Terminal; Windows process killing uses `taskkill` but has not been exercised on a real Windows machine.
|
|
528
515
|
- Very narrow terminals and unusually long approval previews are clipped rather than paginated.
|