Kiwi Code

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

Primary entrypoints:

• TUI: kiwi (or python -m kiwi_tui.main)
• Terminal mode: kiwi --terminal ...
• Inspection CLI: kiwicli (optional; list/get style scripting)
• Runtime: kiwi-runtime

Requires Python 3.11+.

Quick start

1) Install

pip install kiwi-code

2) Log in from the terminal

kiwi login

This prompts for your email and password and stores tokens at:

• ~/.kiwi/tokens.json

You can inspect auth state anytime with:

kiwi whoami

To clear saved credentials:

kiwi logout

3) Launch the TUI (unchanged default)

kiwi

Or choose a server preset:

kiwi --server dev

Available presets:

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

4) Use terminal mode instead of the full-screen TUI

Fresh conversation on the default action:

kiwi --terminal "Hi, what are you doing?"

Fresh conversation for a specific action:

kiwi --terminal --action-id <ACTION_ID> "Inspect this repository"

Continue an existing run:

kiwi --terminal --run-id <RUN_ID> "What changed?"

Pipe the message on stdin:

echo "Summarize the latest output" | kiwi --terminal --run-id <RUN_ID>

Connect the local CLI runtime from terminal mode:

kiwi --terminal --connect-cli
kiwi --terminal --connect-cli --action-id <ACTION_ID>
kiwi --terminal --connect-cli --run-id <RUN_ID>

Rules:

• kiwi by itself still launches the TUI.
• --action-id starts a fresh conversation for that action.
• --run-id continues an existing run.
• --action-id and --run-id are mutually exclusive.
• --connect-cli cannot be combined with a user message.

5) (Optional) Start the runtime manually

In most cases, let Kiwi manage the runtime automatically via /connect-cli in the TUI or kiwi --terminal --connect-cli in terminal mode.

If you want to run it yourself:

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

Terminal mode usage

Human-readable output

kiwi --terminal "Hello"

This prints the run result directly in your terminal.

JSON output for scripts

kiwi --terminal --json --action-id <ACTION_ID> "Hello"

Disable live status streaming

kiwi --terminal --no-stream --run-id <RUN_ID> "Continue this task"

Authentication in terminal mode

If you are not logged in, terminal mode exits with a helpful message telling you to run:

kiwi login

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

From the TUI:

• /connect-cli

From terminal mode:

kiwi --terminal --connect-cli
kiwi --terminal --connect-cli --action-id <ACTION_ID>
kiwi --terminal --connect-cli --run-id <RUN_ID>

What it does:

• Ensures a local runtime exists for the current run_id.
• If the runtime was disconnected (e.g. after a 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.
• In terminal mode, --connect-cli is a setup action only, so it must not be combined with a message.

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.

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 overview

kiwi

kiwi is the primary user-facing CLI.

Examples:

kiwi
kiwi login
kiwi whoami
kiwi --terminal "Hello"
kiwi --terminal --connect-cli --run-id <RUN_ID>

kiwicli

kiwicli remains available for list/get style 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 whenever Kiwi Code needs to start a runtime, whether you are in the TUI or terminal mode.

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

Terminal mode examples:

kiwi --terminal --server dev "Hello"
kiwi --terminal --json --action-id <ACTION_ID> "Hello"
kiwi --terminal --no-stream --run-id <RUN_ID> "Continue"

• --server: app | dev | local | <full url>
• --scope: restricted | full
• --allow PATH: repeatable; additional allowed directories in restricted mode
• --terminal: run Kiwi in plain terminal mode instead of the full-screen TUI
• --action-id: start a fresh conversation for the given action
• --run-id: continue an existing run
• --connect-cli: ensure runtime exists and send the connect prompt
• --json: print machine-readable output for terminal mode
• --no-stream: wait for the final result without live status streaming

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.