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   # defaults to a Work account (app.meetkiwi.ai)
pip install kiwi-ai     # defaults to a Personal account (kiwicode.ai)

Both packages are built from this repository and provide the same commands. Install one or the other, not both.

2) Log in from the terminal

kiwi login

Kiwi has two kinds of account, on separate servers. Login asks which one you have:

The default is Personal for kiwi-ai and Work for kiwi-code.

To skip the question, name the account:

kiwi login --account work
kiwi login --account personal

Login then prompts for your email and password. Each server keeps its own login file, so you can be signed in to both accounts at once:

To use both side by side, name the account in each terminal:

kiwi --account work        # one tab
kiwi --account personal    # another tab

With no --account or --server, a command uses the account you logged in to most recently (remembered in ~/.kiwi/server).

You can inspect auth state anytime with:

kiwi whoami

To clear saved credentials:

kiwi logout                  # the account you logged in to most recently
kiwi logout --account work   # one account
kiwi logout --all            # every account

3) Launch the TUI (unchanged default)

kiwi

Or choose a server preset:

kiwi --server dev

Available presets:

• app (prod): Personal (kiwicode.ai) for kiwi-ai and Work (app.meetkiwi.ai) for kiwi-code; --account work / --account personal pick Work / Personal in either
• dev (dev): dev.api.myautobots.com, for every account
• local (localhost): localhost:8000, for every account

--server also takes a full URL, for example --server http://localhost:9000.

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>
• --account: work | personal. Picks the server when --server is app or not given. On dev, local or a URL the server stays the same, and the account only decides how to sign in: a work account has email and password, no Google or Outlook.

• --scope: restricted | full. In the TUI you can also click the mode to switch it: the Mode: line on the login screen, or mode:restricted in the top bar once signed in. Switching replaces the current run's runtime with one in the new mode.
• --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).
• --account work|personal picks the account; see Server / flags. With neither --server, --account nor --token, the runtime asks which account before login.
• --login google|outlook is for Personal (kiwicode.ai) accounts only.
• --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 the login file of that server (~/.kiwi/tokens.json for personal, ~/.kiwi/tokens-work.json for work; see Log in).

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

A checkout runs as kiwi-ai (src/kiwi_cli/_edition.py). Set KIWI_EDITION=kiwi-code to run it as kiwi-code.

Run tests:

uv run python -m pytest -q
KIWI_EDITION=kiwi-code uv run python -m pytest -q

Releasing

kiwi-ai and kiwi-code are both published from main. The differences between them (package name, default backend, author) live in EDITIONS in src/kiwi_cli/edition.py. Push a tag naming the package and version:

git tag kiwi-code-v0.0.449 && git push origin kiwi-code-v0.0.449
git tag kiwi-ai-v0.0.25    && git push origin kiwi-ai-v0.0.25

The publish workflow runs scripts/set_edition.py to stamp the package name, version and edition into the build, checks the built wheel, and publishes with that package's token (PYPI_TOKEN_KIWI_CODE or PYPI_TOKEN_KIWI_AI). You can also run it manually from the Actions tab by choosing the package and version.

License

Proprietary. All rights reserved.