kiwi-code 0.0.12

A textual-based terminal user interface application

Kiwi Code

A terminal-based interface for the Kiwi AI platform. Built with Textual and Typer, it provides a chat-style TUI and command-line access to manage and interact with actions, action graphs, and their runs.

Requires Python 3.13+.

Architecture

Kiwi Code has three entry points, but they are not three services — they are independent frontends to the same shared code:

                  ┌──────────────────────────────────┐
                  │         Shared Libraries          │
                  │                                    │
                  │  commands.py   Command handlers    │
                  │  client.py     HTTP/SSE client     │
                  │  auth.py       Token management    │
                  │  autobots_client  (generated SDK)  │
                  └──────┬───────────┬─────────────────┘
                         │           │
              ┌──────────┘           └──────────┐
              │                                  │
     ┌────────▼────────┐              ┌─────────▼─────────┐
     │   kiwi (TUI)    │              │  kiwicli (CLI)     │
     │                  │              │                    │
     │  Full-screen     │              │  Typer commands    │
     │  Textual app     │              │  for scripting     │
     │                  │              │  and automation    │
     └────────┬─────────┘              └────────────────────┘
              │ auto-starts
              │ (if not already running)
              │
     ┌────────▼──────────────────────────────────────────┐
     │                kiwi-runtime                        │
     │                                                    │
     │  Independent process — one per working directory   │
     │  Connects to Kiwi server via WebSocket             │
     │  Executes shell commands for the LLM agent         │
     │                                                    │
     │  Can also be started directly:                     │
     │    kiwi-runtime connect --server app               │
     │                                                    │
     │  Survives TUI quit, logout, and restarts           │
     │  Stop explicitly: kiwicli runtime stop             │
     └───────────────────────────────────────────────────┘

Key points:

• kiwi and kiwicli do not depend on each other. They both import the same commands.py, client.py, and auth.py modules directly. Neither needs the other to be running.
• kiwi automatically spawns kiwi-runtime when you log in. The runtime runs as an independent process — quitting or restarting the TUI does not kill it.
• One runtime per directory. Each working directory gets its own runtime, scoped to that directory. Opening the TUI in two different project folders runs two independent runtimes.
• kiwicli is for headless/scripting use. It provides the same query commands (actions, runs, graphs) as the TUI, but as standalone CLI commands.
• Authentication is shared. Both use TokenManager to read/write tokens from ~/.kiwi/tokens.json, so logging in via one works for the other.
• Runtime lifecycle is independent. The runtime persists across TUI restarts. Use kiwicli runtime stop to explicitly stop it.

Installation

pip install kiwi-code

This installs three commands:

Command	Description
kiwi	Launch the interactive TUI (auto-starts runtime)
kiwicli	CLI for scripting — login, query actions/runs/graphs
kiwi-runtime	WebSocket agent for LLM command execution (usually auto-started by TUI)

Quick Start

# Login (once — tokens are saved locally)
kiwicli login

# Launch the interactive TUI (starts runtime automatically)
kiwi

# Or use CLI commands directly
kiwicli actions list
kiwicli runs list --status processing

Commands

kiwicli login                                  Authenticate with email and password
kiwicli logout                                 Logout and clear saved tokens
kiwicli whoami                                 Check authentication status
kiwicli tui                                    Launch the interactive TUI

kiwicli actions list [--name N]                List actions
kiwicli actions get <id>                       Get action details

kiwicli runs list [--action-id ID]             List action runs (results)
       [--action-name N] [--status S]
kiwicli runs get <id>                          Get run details

kiwicli graphs list [--name N]                 List action graphs
kiwicli graphs get <id>                        Get graph details

kiwicli graph-runs list [--graph-id ID]        List graph runs (results)
       [--graph-name N] [--status S]
kiwicli graph-runs get <id>                    Get graph run details

kiwicli runtime status                         Check if runtime is running (current dir)
kiwicli runtime stop [--all]                   Stop runtime (current dir, or all)
kiwicli runtime list                           List all runtimes across directories
kiwicli runtime logs                           Tail the runtime log (current dir)

All list commands support --limit and --offset for pagination. Runs can be filtered by --status (processing, success, error, stuck, waiting).

Interactive TUI

Launch with kiwi or kiwicli tui. The TUI provides a full-screen chat interface for conversing with actions in real time.

• Chat interface — Send messages to actions and receive streamed responses via SSE
• Session management — Switch actions, continue existing runs, or start new conversations
• Slash commands — All CLI commands work inside the TUI chat with a / prefix
• Authentication — Login screen with automatic token refresh
• Runtime logs — View the runtime agent's output in real time (Ctrl+R)
• Theming — Dark/light mode toggle (Ctrl+D)

Keyboard Shortcuts

Key	Action
Ctrl+C	Quit
Ctrl+R	Runtime logs
Ctrl+D	Toggle dark/light mode
Ctrl+L	Logout

Slash Commands (inside TUI)

/use <action_id>              Switch to a different action
/continue <run_id>            Continue an existing conversation run
/new                          Start a new conversation (resets to default action)
/status                       Show current action and run IDs

/actions list                 List all actions
/runs list --status success   Filter runs by status
/graphs get <id>              View graph details
/help                         Show all available commands

Streaming

Actions execute asynchronously. The TUI streams status updates in real time via SSE and automatically fetches the final result on completion. Falls back to polling if the SSE stream ends without delivering a result.

Runtime Agent

The runtime agent connects to the Kiwi server via WebSocket and executes terminal commands on behalf of the LLM agent.

The TUI auto-starts the runtime on login. Each working directory gets its own runtime instance, restricted to that directory. The runtime runs as an independent process — it survives TUI quit, logout, and restarts. When the TUI starts again, it detects the running runtime and reattaches to its logs.

To manage runtimes independently:

kiwicli runtime status    # Check if running (for current directory)
kiwicli runtime stop      # Stop the runtime (for current directory)
kiwicli runtime stop --all # Stop all runtimes
kiwicli runtime list      # List all runtimes across directories
kiwicli runtime logs      # Tail the runtime log (for current directory)

You can also run it standalone:

kiwi-runtime connect --server app           # Production (api.meetkiwi.ai)
kiwi-runtime connect --server dev           # Development
kiwi-runtime connect --server local         # Localhost
kiwi-runtime connect --server wss://custom  # Custom URL
kiwi-runtime connect --scope full           # Unrestricted execution (default: restricted)
kiwi-runtime connect --allow /extra/dir     # Allow additional directory in restricted mode

In restricted mode (default), commands are sandboxed to the current working directory. The --allow flag adds extra allowed paths.

Configuration

Stored at ~/.kiwi/config.json:

{
  "backend_url": "https://api.example.com",
  "log_level": "INFO",
  "theme": "dark",
  "refresh_interval": 5
}

Logs are written to ~/.kiwi/kiwi_tui.log.

Development

git clone https://github.com/jetoslabs/kiwi-code.git
cd kiwi-code
uv sync
uv run kiwi

License

Proprietary. All rights reserved.