@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 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>] [--set-active] [--no-test]
104
- ```
105
-
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.
107
-
108
- Keys for `kiro model add`:
109
-
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.
113
-
114
- ### Updates
115
-
116
- ```bash
117
- kiro check # installed version vs npm
118
- kiro update # npm install -g @ywldan/kiro@latest
119
- ```
120
-
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.
132
-
133
- ### Where keys live
134
-
135
- `config.json` stores only `apiKeyEnv`, the name of a variable. Values live in the environment or in `~/.kiro/.env`:
136
-
137
- ```
138
- # ~/.kiro/.env
139
- OPENROUTER_API_KEY=sk-or-...
140
- ```
141
-
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.
147
-
148
- Set `KIRO_ENV_PATH` to use a different `.env` file.
149
-
150
- ## Configuration
151
-
152
- `~/.kiro/config.json`:
153
-
154
- ```json
155
- {
156
- "activeProfile": "openai",
157
- "profiles": {
158
- "openai": {
159
- "type": "openai",
160
- "baseUrl": "https://api.openai.com/v1",
161
- "apiKeyEnv": "OPENAI_API_KEY",
162
- "model": "gpt-4.1",
163
- "temperature": 0.2,
164
- "maxTokens": 4096,
165
- "contextWindow": 128000
166
- },
167
- "local": {
168
- "type": "openai",
169
- "baseUrl": "http://localhost:11434/v1",
170
- "model": "qwen2.5-coder:14b",
171
- "temperature": 0.2
172
- }
173
- }
174
- }
175
- ```
176
-
177
- | Field | Required | Meaning |
178
- | --- | --- | --- |
179
- | `type` | yes | Provider type. Only `openai` is implemented. |
180
- | `baseUrl` | yes | API base URL including the version segment, e.g. `https://api.openai.com/v1`. Kiro appends `/chat/completions`. |
181
- | `apiKeyEnv` | no | Name of the environment variable holding the API key. Omit for local servers that need no auth. |
182
- | `model` | yes | Model name sent to the endpoint. |
183
- | `models` | no | Model ids the `/model` picker offers for this profile. Filled by discovery; the model in use is always included. |
184
- | `temperature` | no | Sampling temperature. |
185
- | `maxTokens` | no | Maximum response tokens. |
186
- | `contextWindow` | no | Approximate context window in tokens, at least 1000. Defaults to `128000`; drives the ctx meter and compaction. |
187
-
188
- `activeProfile` selects the profile used at startup. `/model <name>` switches at runtime and `--profile` switches for one run.
189
-
190
- ### Example endpoints
191
-
192
- **OpenRouter** (key from `~/.kiro/.env` or the environment)
193
-
194
- ```bash
195
- export OPENROUTER_API_KEY="sk-or-..."
196
- kiro model add --name openrouter \
197
- --base-url https://openrouter.ai/api/v1 \
198
- --model anthropic/claude-sonnet-4 \
199
- --api-key-env OPENROUTER_API_KEY --set-active
200
- ```
201
-
202
- **Ollama** (no key; discovery normally works, but you can enter a manually pulled tag)
203
-
204
- ```bash
205
- kiro model add --name ollama \
206
- --base-url http://localhost:11434/v1 \
207
- --model qwen2.5-coder:14b --set-active
208
- ```
209
-
210
- **LM Studio, vLLM, or another local server**
211
-
212
- ```bash
213
- kiro model add --name local \
214
- --base-url http://localhost:1234/v1 \
215
- --model local-model --set-active
216
-
217
- # A server without GET /models: name the model directly.
218
- kiro model add --name vllm \
219
- --base-url http://gpu-box:8000/v1 \
220
- --model my-model --no-test
221
- ```
222
-
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.
224
-
225
- ## CLI options
226
-
227
- ```
228
- kiro [options]
229
-
230
- --profile <name> Use a profile from ~/.kiro/config.json
231
- --base-url <url> Override the active profile's base URL
232
- --model <name> Override the active profile's model
233
- -c, --continue Resume the most recent session for this directory
234
- --resume <id> Resume a specific saved session
235
- -p, --prompt <text>
236
- Run one turn without a TUI ("-" or no text reads the
237
- prompt from stdin); replies stream to stdout
238
- --yolo Skip all approval prompts (use with care)
239
- --mouse Mouse reporting (on by default): wheel scrolls the transcript
240
- --no-mouse Disable mouse reporting so plain click-drag selection works
241
- --no-alt-screen Do not switch to the terminal's alternate screen
242
- --no-skills Do not read skill folders at all (KIRO_NO_SKILLS=1 does the same)
243
- -h, --help Show help
244
- -v, --version Show version
245
-
246
- kiro check Compare the installed version with the latest on npm
247
- kiro update Install the latest version from npm globally
248
- kiro doctor Check Node, config, key storage, and the active endpoint
249
- ```
250
-
251
- `--flag=value` works too. CLI overrides last for the current process only.
252
-
253
- ## Headless mode
254
-
255
- `kiro -p "…"` runs one turn without Ink, for scripts, cron jobs, and CI:
256
-
257
- ```bash
258
- kiro -p "explain what this repo does" # read-only answers work immediately
259
- kiro -p "add the missing tests" --yolo # let it write and run commands
260
- git diff | kiro -p "review this patch" # pipe the prompt
261
- kiro -p "continue" --continue # continue this directory's session
262
- echo "summarize README.md" | kiro -p - > summary.md # "-" reads stdin
263
- ```
264
-
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.
266
-
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.
268
-
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).
270
-
271
- ## Using the TUI
272
-
273
- | Key | Action |
274
- | --- | --- |
275
- | `Enter` | Send the prompt, or run the highlighted `/` command |
276
- | `Ctrl+J`, `Alt+Enter`, or `\` + Enter | Start a new line without sending |
277
- | `Ctrl+C` | Press twice to exit; while a turn runs, the first press cancels it |
278
- | `PgUp` / `PgDn` | Scroll the history (the wheel works too, unless you pass `--no-mouse`) |
279
- | `Ctrl+O` | Expand or collapse the full output of the most recent tool call |
280
- | `↑` / `↓` | Move through the `/` command menu; with an empty input, recall prompt history |
281
- | `Tab` | Complete the highlighted `/` command |
282
- | `Esc` | Clear the input, close the command menu, cancel a model wizard step, or deny a pending approval |
283
- | `Ctrl+A` / `Ctrl+E` | Move to start / end of input |
284
- | `Backspace` / `Delete` | Delete before / after the cursor |
285
- | `Ctrl+U` / `Ctrl+K` | Delete before / after the cursor |
286
- | `Ctrl+W` | Delete the previous word |
287
- | Left / Right / Home / End | Move the cursor |
288
-
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.
292
-
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.
294
-
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.
296
-
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.
298
-
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.
300
-
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`.
302
-
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.
304
-
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.
306
-
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.
308
-
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.
310
-
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.
312
-
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.
314
-
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`.
316
-
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
320
-
321
- | Command | Action |
322
- | --- | --- |
323
- | `/help` | Show commands and keys |
324
- | `/model` | Open the centered model picker: profile first, then searchable stored models |
325
- | `/model <name>` | Switch profile without restarting |
326
- | `/model add` | Guided setup; prompts appear in the input box and the key is masked |
327
- | `/model edit [name]` | Edit fields, replace the key, re-test, and save |
328
- | `/model remove [name]` | Remove a profile after confirmation (refuses the last one) |
329
- | `/model test [name]` | Test the active or named profile; prints latency or the exact error |
330
- | `/model list --remote` | List models offered by the active endpoint's `GET /models` |
331
- | `/context` | Show approximate context use by message role plus session token totals |
332
- | `/usage` | Show or hide the Usage card, giving the transcript the full width |
333
- | `/skills` | List installed skills, their source, and any skipped entries |
334
- | `/skill <name> [request]` | Load a skill, optionally with your request in the same line |
335
- | `/<skill name> [request]` | Call an installed skill directly, e.g. `/anti-slop rewrite this paragraph` |
336
- | `/compact` | Summarize older turns now, keeping the last four user turns verbatim |
337
- | `/sessions` | List saved sessions for this directory and for other directories |
338
- | `/resume` | Open the session picker (tabs for this directory and others) |
339
- | `/resume <n\|id>` | Resume a session from this directory by list number or id (prefixes work) |
340
- | `/undo` | Revert the most recent write, edit, or patch (repeat to step further back) |
341
- | `/clear` | Start a new session, keeping the old one on disk |
342
- | `/export [file]` | Write the transcript (with full tool output) to a Markdown file |
343
- | `/mouse` | Toggle mouse reporting: wheel scroll vs normal text selection |
344
- | `/allow` | List tools that skip approval for this session |
345
- | `/allow clear` | Ask for approval again for every tool |
346
- | `/exit` | Quit |
347
-
348
- `/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.
349
-
350
- ## Sessions
351
-
352
- Kiro saves each conversation under `~/.kiro/sessions/`, in a directory named from a hash of the working directory:
353
-
354
- ```
355
- ~/.kiro/sessions/<cwd-hash>/<session-id>.json
356
- ```
357
-
358
- 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`.
359
-
360
- 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.
361
-
362
- Resume with:
363
-
364
- ```bash
365
- kiro --continue # most recent session for this directory
366
- kiro --resume <id> # a specific session
367
- ```
368
-
369
- `/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.
370
-
371
- Session files are plaintext and contain prompts, code from tools, and command output. They never contain API keys, but treat them like shell history.
372
-
373
- ## Context and compaction
374
-
375
- 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.
376
-
377
- Each profile may set `contextWindow` (default `128000`). At about 80% of the window, Kiro compacts before the next request:
378
-
379
- - the system prompt stays;
380
- - the last four user turns stay verbatim, with their assistant and tool messages;
381
- - older turns become a summary of the goal, files touched, decisions, current state, and open TODOs;
382
- - very large old tool results become short placeholders first, so the summarizer is not flooded;
383
- - the cut always falls on a user-message boundary, so a tool-call round is never split.
384
-
385
- 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.
386
-
387
- ## Tools and safety
388
-
389
- | Tool | What it does | Approval |
390
- | --- | --- | --- |
391
- | `read_file(path, offset?, limit?)` | Reads a file with numbered lines and truncation notes | never |
392
- | `list_dir(path)` | Lists one directory, with `/` after directories | never |
393
- | `glob(pattern, path?)` | Finds files by glob, e.g. `src/**/*.ts`. Respects `.gitignore`; skips `node_modules`, `.git`, `dist`, `build`; caps at 200 results | never |
394
- | `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 |
395
- | `write_file(path, content)` | Creates or overwrites a file, creating parent directories | always (except `--yolo`) |
396
- | `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`) |
397
- | `multi_edit(path, edits[])` | Several exact replacements in one file, validated together and written once | always (except `--yolo`) |
398
- | `apply_patch(patch)` | Applies a unified diff to one or more files after validating every hunk | always (except `--yolo`) |
399
- | `run_command(command, timeout_seconds?)` | Runs a shell command in the working directory | always (except `--yolo`) |
400
- | `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 |
401
-
402
- `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.
403
-
404
- `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.
405
-
406
- Approvals show a diff, or the exact command, and offer:
407
-
408
- - `[y]` allow once
409
- - `[a]` allow this tool for the rest of the session (the status bar shows `auto:<tool>`; `/allow clear` revokes it)
410
- - `[n]` deny and return the refusal to the model
411
-
412
- 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.
413
-
414
- 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.
415
-
416
- `--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.
417
-
418
- ### Undo and checkpoints
419
-
420
- 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.
421
-
422
- 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.
423
-
424
- ## AGENTS.md
425
-
426
- If `AGENTS.md` exists in the working directory, its contents are appended to the system prompt every turn, including after edits.
427
-
428
- ## Skills
429
-
430
- 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:
431
-
432
- 1. `<cwd>/.kiro/skills/`
433
- 2. `<cwd>/.claude/skills/` (Claude Code skills work unchanged)
434
- 3. `~/.kiro/skills/`
435
- 4. `~/.claude/skills/`
436
-
437
- Each skill is a directory with `SKILL.md`:
438
-
439
- ```md
440
- ---
441
- name: anti-slop
442
- description: Remove AI-slop patterns from prose before answering.
443
- ---
444
-
445
- Delete "delve", "tapestry", and stacked em dashes. Prefer concrete nouns.
446
- ```
447
-
448
- 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.
449
-
450
- 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.
451
-
452
- `/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.
453
-
454
- 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.
455
-
456
- 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.
457
-
458
- ## How it works
459
-
460
- - 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.
461
- - 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.
462
- - A stream that sends no bytes for `KIRO_STREAM_IDLE_MS` (default 120000, `0` disables) is cancelled and retried like a dropped connection.
463
- - 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.
464
- - If the endpoint rejects a request as too long (400/413 with a context-length message), Kiro compacts and retries the round once.
465
- - `finish_reason: length` produces an explicit notice, including when tool-call arguments were cut off.
466
- - 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).
467
- - Malformed tool JSON, unknown tools, non-zero exits, and timeouts go back to the model as tool errors instead of ending the session.
468
- - A turn is capped at 25 tool rounds.
469
- - Model discovery and the connection test both time out after 10 seconds and can be cancelled.
470
- - 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.
471
-
472
- ## Testing
473
-
474
- ```bash
475
- pnpm test # backend tests against an in-process mock server
476
- pnpm mock # mock server on port 8787 for manual TUI testing
477
- ```
478
-
479
- 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.
480
-
481
- 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.
482
-
483
- ## Project layout
484
-
485
- ```
486
- src/
487
- index.tsx CLI entry point
488
- headless.ts one-shot -p runner (stdout text, stderr diagnostics)
489
- config.ts config load/validation/overrides, atomic save, recovery
490
- env.ts ~/.kiro/.env parser/writer, masking, key status
491
- secrets.ts credential registry: redaction and child-process env filtering
492
- sessions.ts atomic session save/load/list
493
- model/ presets, discovery/test, context-window inference, shared wizard, CLI + screen renderer
494
- providers/ Provider interface, OpenAI-compatible implementation
495
- agent/ system prompt, skill discovery/parsing, agent loop, token estimates, compaction
496
- tools/ tool registry, fs/search/patch/shell/skill tools, checkpoints, glob/gitignore matching
497
- ui/ Ink app, markdown, command palette, prompt history, scrolling, approvals, status bar, export
498
- test/
499
- mock-server.ts scripted OpenAI-compatible SSE server + /models variants
500
- e2e.ts backend test suite
501
- ```
502
-
503
- ## Known limitations
504
-
505
- - Only the `openai` provider type. Anthropic-style APIs are not supported.
506
- - Model discovery assumes an OpenAI-compatible `GET /models`. Endpoints without it work, but the model id must be typed manually.
507
- - `@` lists files only and stops at 50,000 paths; directories and ignored files are not offered.
508
- - Removing a profile leaves its key in `~/.kiro/.env`; there is no command that deletes stored secrets.
509
- - No sub-agents, MCP, plugins, web search, image input, themes, or git integration.
510
- - 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.
511
- - `/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.
512
- - Prompt history is plaintext, capped at 200 entries per directory, and only recalled in the TUI (not in `-p` mode).
513
- - Only contiguous read-only tool calls run in parallel; writes, edits, patches, and commands stay sequential.
514
- - 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.
515
- - Markdown support covers the common subset; images and syntax highlighting are shown as plain text.
516
- - 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`.
517
- - 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.
518
- - The TUI targets Linux, macOS, and Windows Terminal; Windows process killing uses `taskkill` but has not been exercised on a real Windows machine.
519
- - Very narrow terminals and unusually long approval previews are clipped rather than paginated.
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.