Metadata-Version: 2.5
Name: kiwi-code
Version: 0.0.449
Summary: A textual-based terminal user interface application
Project-URL: Homepage, https://kiwicode.ai
Author-email: Anurag <anurag@meetkiwi.co>
License: Proprietary
Keywords: cli,terminal,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4.0,>=3.11
Requires-Dist: codeglass>=0.1.2
Requires-Dist: httpx>=0.25.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pykiwiai==0.0.13
Requires-Dist: setproctitle>=1.3.0
Requires-Dist: textual-dev>=1.8.0
Requires-Dist: textual>=8.1.1
Requires-Dist: typer>=0.24.1
Requires-Dist: websockets>=14.1
Requires-Dist: wonderwords>=2.2.0
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
kiwi login
```

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

| Choice | Account | Sign-in |
|---|---|---|
| 1 | Work (app.meetkiwi.ai) | email and password |
| 2 | Personal (kiwicode.ai) | email and password, Google, Outlook |

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

To skip the question, name the account:

```bash
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:

| Server | Login file |
|---|---|
| Personal (kiwicode.ai) | `~/.kiwi/tokens.json` |
| Work (app.meetkiwi.ai) | `~/.kiwi/tokens-work.json` |
| dev | `~/.kiwi/tokens-dev.json` |
| local or a URL | `~/.kiwi/tokens-<host>.json` |

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

```bash
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:

```bash
kiwi whoami
```

To clear saved credentials:

```bash
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)

```bash
kiwi
```

Or choose a server preset:

```bash
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:

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

Fresh conversation for a specific action:

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

Continue an existing run:

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

Pipe the message on stdin:

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

Connect the local CLI runtime from terminal mode:

```bash
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:

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

---

## Terminal mode usage

### Human-readable output

```bash
kiwi --terminal "Hello"
```

This prints the run result directly in your terminal.

### JSON output for scripts

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

### Disable live status streaming

```bash
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:

```bash
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:

```bash
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.

| 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 overview

### `kiwi`

`kiwi` is the primary user-facing CLI.

Examples:

```bash
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:

```bash
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.

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

Terminal mode examples:

```bash
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.

| `--server` | `--account` | Connects to |
|---|---|---|
| not given | not given | the server you logged in to; at login, asks Work or Personal (default: Personal for kiwi-ai, Work for kiwi-code) |
| not given, or `app` | `work` | Work (app.meetkiwi.ai) |
| not given, or `app` | `personal` | Personal (kiwicode.ai) |
| `app` | not given | Personal (kiwicode.ai) for kiwi-ai, Work (app.meetkiwi.ai) for kiwi-code |
| `dev` | any | `dev.api.myautobots.com` |
| `local` | any | `localhost:8000` |
| a URL | any | that URL |
- `--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:

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

From the repo (recommended for development):

```bash
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](#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](#2-log-in-from-the-terminal)).

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

```bash
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

```bash
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:

```bash
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:

```bash
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.
