kiwi-code 0.0.21

A textual-based terminal user interface application

Kiwi Code

Kiwi Code is a terminal-first UI (TUI) for chatting with Kiwi Actions and managing runs (action results). It also integrates with the Kiwi Runtime (a local CLI/terminal agent) so actions can execute terminal commands on your machine.

• TUI: kiwi (or python -m kiwi_tui.main)
• CLI: kiwicli (optional; scripting / inspection)

Requires Python 3.13+.

---

Quick start

1) Install

pip install kiwi-code

2) Start the TUI

Connect using a server preset:

kiwi connect --server app

Available presets:

• app (prod)
• dev (dev)

3) Login

The TUI will prompt for login if you’re not authenticated.

Tokens/config are stored under:

• ~/.kiwi/tokens.json
• ~/.kiwi/config.json

4) (Optional) Start the Runtime

If you want to run the runtime manually:

kiwi-runtime connect --server dev --scope full

Or for production:

kiwi-runtime connect --server app --scope full

Notes

• --scope full gives unrestricted access. Use restricted if you want tighter control.
• In most cases, you can skip manual runtime startup and just use /connect-cli inside the TUI.

2) Start the TUI

Choose a server preset:

• app (prod)
• dev (dev)
• local (localhost)

uv run python -m kiwi_tui.main --server dev

Or, if installed as a package:

kiwi --server dev

3) Login

The TUI will show a login screen if you’re not authenticated.

Tokens/config are stored under:

• ~/.kiwi/tokens.json
• ~/.kiwi/config.json

---

Daily workflow (TUI)

Pick an action → chat

• /actions list → pick an action
• Type a message and press Enter

Start a fresh conversation

• /new resets the chat to the default action and clears history in the UI.

Continue an existing run (conversation)

• /runs list → pick a run
• or /continue <run_id>

Kiwi Code will load the conversation history for that run.

---

Local CLI agent (Runtime)

Some actions can execute terminal commands via a local runtime process.

Connect the runtime to the current run

Inside the TUI:

• /connect-cli

What it does:

• Ensures a local runtime exists for the current run_id.
• If the runtime was disconnected (e.g., server redeploy), Kiwi Code detects it and starts a fresh one.
• Sends the instruction prompt: “Connect to the CLI right now before asking or doing anything.”

View runtime logs

• Slash command: /show-logs
• Keyboard shortcut: Ctrl+O (works even while the chat input is disabled / streaming)

Runtime lifecycle

• Runtime processes are tracked under ~/.kiwi/runtimes/.
• Runtimes are per run_id (one runtime process per run).
• Runtimes may survive TUI restarts.
• On quit (Ctrl+C), Kiwi Code shows an exit prompt listing runtimes and lets you choose which to kill.

---

Keyboard shortcuts (TUI)

These are designed to work even when input is blocked during streaming.

Key	Action
Ctrl+C	Quit (shows runtime cleanup prompt if runtimes are alive)
Ctrl+O	Open CLI logs (/show-logs)
Ctrl+G	Open slash-command picker (/ ...)
Ctrl+U	Attach files / content (@ ...)
Ctrl+J	Send message

---

Slash commands (TUI)

Session

• /use <action_id> — switch action (starts a fresh chat UI)
• /actions list — list & select actions
• /new — new conversation (default action)
• /continue <run_id> — continue an existing run and load history
• /runs list — list & select runs
• /status — show current action/run ids

Files

• @ opens the inline file picker
• /upload <path> [path2 ...] uploads files and attaches them to your next message
• /files shows pending attachments
• /clear-files clears pending attachments

Runtime

• /connect-cli — ensure runtime exists (per run_id) + send “connect” prompt
• /show-logs — open runtime logs screen

---

CLI (optional)

kiwicli provides the same “list/get” style commands for scripting and inspection.

Examples:

kiwicli actions list
kiwicli actions get <action_id>

kiwicli runs list --status processing
kiwicli runs get <run_id>

---

Server / flags

kiwi / python -m kiwi_tui.main supports runtime flags (mirrors kiwi-runtime connect). These flags are used when Kiwi Code needs to start a runtime.

kiwi --server dev \
  --scope restricted \
  --allow /some/extra/dir

• --server: app | dev | local | <full url>
• --scope: restricted | full
• --allow PATH: repeatable; additional allowed directories in restricted mode

Note: Kiwi Code does not modify the runtime implementation under src/kiwi_runtime/.

---

Using kiwi-runtime standalone (advanced)

You can run the Kiwi Runtime by itself (without the TUI). This is useful for:

• debugging runtime connectivity / permissions
• keeping a long-lived runtime running in a separate terminal tab
• watching runtime activity/logs directly

Start the runtime

If you installed kiwi-code as a package:

kiwi-runtime connect --server dev --scope restricted --allow "$PWD"

From the repo (recommended for development):

uv run python -m kiwi_runtime.main connect --server dev --scope restricted --allow "$PWD"

Notes:

• --server supports presets: app, dev, local (or a full URL).
• --scope restricted is the default; use --allow to add directories.
• The runtime prints connection status and will remain running until you stop it.

Authentication

The runtime typically needs an access token. When you run the TUI and log in, your token is saved to:

• ~/.kiwi/tokens.json

You can pass the token explicitly (if required by your setup):

kiwi-runtime connect --server dev --token <ACCESS_TOKEN>

Stop the runtime

Press Ctrl+C in the runtime terminal to disconnect and exit.

Important behavior when running standalone

• Standalone runtimes are not tracked in ~/.kiwi/runtimes/ (that directory is used by kiwi-code to track TUI-managed runtimes).
• If you run the TUI and then run /connect-cli, kiwi-code may start its own runtime process if it doesn’t detect a managed runtime for the current run.
  • For normal usage, prefer letting the TUI manage the runtime via /connect-cli.
  • For standalone/debug usage, run kiwi-runtime connect ... in a separate terminal and use it to observe activity.

---

Troubleshooting

“CLI runtime stopped responding” after server redeploy

If the backend restarts (common in dev), the runtime websocket may close.

Fix:

1. In Kiwi Code, run /connect-cli again.
2. If needed, open logs (Ctrl+O) to confirm the new runtime connected.

Kiwi Code validates existing runtime processes and will restart them when they’re invalid/disconnected.

Quit shows a runtime cleanup prompt

This is expected. Select runtimes to kill (or press Esc to keep them running).

---

Development

git clone https://github.com/jetoslabs/kiwi-code.git
cd kiwi-code
uv sync
uv run python -m kiwi_tui.main --server dev

Run tests:

uv run python -m pytest -q

---

License

Proprietary. All rights reserved.