# agentkairo

> ⚠️ **First install downloads an 8.99 GB AI model** (Qwen2.5-Coder-14B) during
> `npm install`. Requires **Linux x64 + an NVIDIA GPU (CUDA 12, ~12 GB VRAM)**.
> No GPU? Use [kairolite](https://www.npmjs.com/package/kairolite) (CPU, ~2 GB).

Kairo is a local coding-agent CLI copied out of the AI Workshop Tauri terminal
agent and packaged for npm.

It talks to a local OpenAI-compatible chat server. The default setup target is
`Qwen/Qwen2.5-Coder-14B-Instruct-GGUF:Q4_K_M`, an Apache-2.0 Qwen Coder 14B
GGUF model served through the bundled `tinyq4` server.

The npm package includes the `tinyq4` inference engine but not the 8.99 GB
model file. The model is downloaded once **at install time** (during
`npm install`), so there is no manual setup step.

## Requirements (read this first)

The bundled `tinyq4` engine is **Linux x86-64 + NVIDIA/CUDA only** — there is no
CPU fallback and no Windows/macOS build yet. You need:

- **Linux** on **x86-64** (Windows/macOS are not supported; `npm install` will
  refuse to install on them).
- An **NVIDIA GPU with ~12 GB VRAM** (the 14B Q4 model uploads ~9.8 GB).
- The **CUDA 12 runtime** and a recent driver (the engine links `libcudart.so.12`).
- **glibc ≥ 2.34** (Ubuntu 22.04+/Debian 12+; older LTS releases won't load it).

Run `agentkairo doctor` to check your machine. On an unsupported machine the
9 GB model download is skipped and Kairo tells you why instead of crashing.

If you already run your own OpenAI-compatible server (any OS), you can skip the
engine entirely and point Kairo at it: `agentkairo --url http://host:port`.

## Install

```sh
npm install -g agentkairo
```

`npm install` downloads the ~8.99 GB Qwen Coder model once into the package's
`models/` directory. If that download is interrupted (e.g. a network drop), the
install still succeeds — the model is fetched automatically the first time you
run `agentkairo`, or you can fetch it on demand with `agentkairo model`.

## Run

```sh
cd /path/to/project
agentkairo
```

That's it. Running `agentkairo` automatically starts the bundled `tinyq4`
model server, waits for it to load, and drops you into the agent. The server is
owned by that session and is shut down when you quit (freeing its VRAM).

While it works the model streams with a live "reading prompt" indicator, and
each reply ends with a dim stats line (`142 tok · 1.8s · 79 tok/s`). Press
`Ctrl-C` to cancel a running reply and return to the prompt; press it again at
an empty prompt to quit.

No external dependencies like `llama.cpp` are required. The only requirement is
Python 3 on your `PATH`.

## One-shot / scripting

Run a single prompt and exit — handy for scripts and pipes. The model's answer
goes to stdout; all status chrome goes to stderr, so redirects stay clean:

```sh
agentkairo -p "summarize what this project does"
echo "explain src/main.py" | agentkairo -p -
agentkairo -p "add a docstring to utils.py" --yolo > result.txt
```

Without `--yolo`, write/bash tools are auto-declined in one-shot mode, so `-p`
is read-only by default.

## Commands

```sh
agentkairo               # Start the agent (auto-starts the model server)
agentkairo -p "<text>"   # Run one prompt non-interactively, then exit
agentkairo model         # Download the model on demand, or show its status
agentkairo serve         # Run only the model server in the foreground
agentkairo doctor        # Show setup status and local server detection
agentkairo --url <url>   # Use an already-running OpenAI-compatible server
agentkairo --yolo        # Run write/bash tools without confirmation
```

(`kairo` is kept as an alias for `agentkairo`.)

Inside Kairo:

- `/yolo` — toggle write/bash confirmations.
- `/tools` — list available tools.
- `/model` — show model status / re-download if needed.
- `/save [file]` — save the conversation to a markdown transcript.
- `/cwd` — show the workspace directory.
- `/stats` — toggle the per-reply token/speed line.
- `/clear` — reset the chat.
- `/help` — list commands.
- `/exit` — quit.

## ⚠️ Disclaimer

Kairo is an **autonomous coding agent**: it can run shell commands, and read,
write, and overwrite files in your workspace. It is **experimental software,
provided "AS IS" with no warranty.** It may execute commands you did not intend,
make confident-but-wrong assumptions, or proceed after ambiguous input —
especially with `--yolo`, which disables all confirmations.

**You are responsible for everything it does on your system.** By using it you
accept the full terms in [DISCLAIMER.md](./DISCLAIMER.md). You pressed enter; the
machine listened.

## License

[Apache-2.0](./LICENSE). The bundled model is licensed separately — see
[MODEL_LICENSES.md](./MODEL_LICENSES.md).
