Metadata-Version: 2.4
Name: kiwi-code
Version: 0.0.20
Summary: A textual-based terminal user interface application
Project-URL: Homepage, https://meetkiwi.ai
Project-URL: Repository, https://github.com/jetoslabs/kiwi-code
Author-email: Anurag Jha <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: autobots-client==0.1.0
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: 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
Description-Content-Type: text/markdown

# 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 deps (repo)

```bash
cd kiwi-code
uv sync
```

### 2) Start the TUI

Choose a server preset:

- `app` (prod)
- `dev` (dev)
- `local` (localhost)

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

Or, if installed as a package:

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

```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 when Kiwi Code needs to start a runtime.

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

```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).
- `--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):

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

Run tests:

```bash
uv run python -m pytest -q
```

---

## License

Proprietary. All rights reserved.
