`kia` — an AI agent for your terminal¶

[source] · pip install "kiui[kia]"

kia is a lightweight coding agent that works where you do: in the terminal and inside your project. It can inspect a repository, edit files, run commands, search the web, delegate work, and keep long sessions focused. Bring any model served through an OpenAI-compatible API.

$ kia --model gpt
> find the cause of this failing test, fix it, and run the smallest relevant check

● reads the repository and test output
● edits only the affected files
● runs the focused test
✓ explains what changed and what was verified

Features¶


Agentic coding Reads, searches, edits, and runs commands with live output.	Model agnostic Works with OpenAI-compatible APIs and switches models without leaving the session.
Terminal + Web UI A polished Rich terminal experience with an optional synchronized, mobile-friendly browser UI.	Sub-agents and goals Delegates independent research or iterates autonomously toward a standing objective.
Skills Loads reusable Agent Skills only when relevant, keeping the base prompt lean.	Long-context management Compacts large tool results, prunes old output, and summarizes history as context fills.
Rewind and sessions Resumes previous work or rolls conversation and file changes back to an earlier round.	Human control Offers three confirmation modes plus a hard guard against recognized destructive operations.
Web access Searches current information and turns web pages into readable text.	Developer-friendly UI Streams responses, shows diffs and token usage, and autocompletes file references with `@`.

One agent, two interfaces. Start work in the terminal, open the optional Web UI from another device, and interact with the same live session from either place.

Install¶

Install the agent and its optional dependencies from PyPI:

pip install "kiui[kia]"

For the latest development version:

pip install -U "kiui[kia] @ git+https://github.com/ashawkey/kiuikit.git"

This installs two commands:

kia — the coding agent and shared Web UI hub.
kib — the optional Git-backed personal skill library.

Configure a model¶

Create .kiui.yaml in the current project or ~/.kiui.yaml for a global configuration. A project configuration takes precedence.

openai:
  gpt:                         # short alias used by kia
    model: gpt-5               # model ID sent to the provider
    api_key: sk-...
    base_url: https://api.openai.com/v1
    reasoning_effort: high     # optional

  local:
    model: my-model
    api_key: not-needed
    base_url: http://localhost:8000/v1

kia_web_token: change-me       # optional fixed Web UI token

The provider only needs to expose an OpenAI-compatible chat-completions API. Keep API keys out of files committed to version control.

List the configured profiles and their detected capabilities:

kia --list

Quick start¶

Run kia from the root of the project you want it to work on:

cd my-project
kia --model gpt

If --model is omitted, the first profile in openai is used.

Talk to it naturally:

> explain how authentication flows through this repository
> fix the parser bug reported in issue #42 and run its tests
> compare these two approaches using current upstream documentation
> @src/server.py simplify this function without changing its API

Prefix a command with ! to bypass the model and run it directly:

> !git diff --stat
> !pytest tests/test_parser.py -q

Type @ to autocomplete a project path. Responses, reasoning for compatible models, tool activity, command output, and diffs stream in the terminal.

Web UI¶

kia remains terminal-first, but a shared hub can mirror many agents into one authenticated browser UI. Each running agent appears as a tab, even when agents were started in different projects or terminals.

┌──────────────────────────────┐       WebSocket       ┌─────────────────────┐
│ kia --hub                    │◀──────────────────────▶│ browser             │
│  ├─ project-a · gpt          │                       │  [project-a] [docs] │
│  └─ docs · local             │                       └─────────────────────┘
└──────────────▲───────────────┘
               │ local agent links
        ┌──────┴──────┐
        │ kia sessions │
        └──────────────┘

Start the hub once, then launch agents normally:

# terminal 1: owns the browser UI port
kia --hub --web-port 8765

# other terminals: automatically discover and join the hub
cd ~/project-a && kia --model gpt
cd ~/project-b && kia --model local

Open the URL printed by the hub and sign in with its generated token, or set kia_web_token in .kiui.yaml. Connection information is stored in ~/.kia/hub.json; agents continue terminal-only if no hub is available.

The hub listens on loopback. To use it from another machine, forward the port with SSH or place it behind an authenticated tunnel:

ssh -L 8765:127.0.0.1:8765 user@workstation

Then open http://127.0.0.1:8765 locally.

Skills¶

Skills are reusable instruction packs in the open Agent Skills format. kia discovers them from:

The installed kiui package — bundled skills; these take precedence and stay in sync with the installed version.
./.kia/skills/ — project skills; these take precedence over personal skills.
~/.kia/skills/ — personal skills shared across projects.

Only each skill’s name and description enter the base prompt. Full instructions and bundled resources are loaded on demand, preserving context for the actual task.

.kia/skills/pdf-processing/
├── SKILL.md
├── scripts/       # optional
├── references/    # optional
└── assets/        # optional

A minimal SKILL.md looks like this:

---
name: pdf-processing
description: Extract, inspect, merge, and fill PDF documents. Use for PDF tasks.
---

Follow the workflow in `references/workflow.md`.
Use `scripts/extract.py` when text extraction is required.

Useful commands:

/skills                 list discovered skills
/skills reload          discover new or edited skills
/skills pdf-processing  load one manually

kia ships with skill-creator for drafting and validating skill packs and pdf-reading for converting PDFs to Markdown and structured data with the external MinerU CLI. The PDF skill reads extracted text, LaTeX, tables, and captions; direct image-pixel inspection requires a vision-capable tool. Bundled skills are loaded directly from the installed package rather than copied into .kia, so upgrading kiui also updates them. Create custom skills under a different name.

Personal skill library¶

Configure a Git repository to share skills between projects:

kia_lib: git@github.com:username/kia-skills.git

Then manage it with kib:

kib list
kib list --local
kib install pdf-processing
kib update [pdf-processing ...]
kib update pdf-processing --prefer local
kib upload pdf-processing
kib upload pdf-processing --force
kib remove pdf-processing
kib remove pdf-processing --local

Remote skills are not exposed to the agent until installed. kib update safely synchronizes all installed skills, or only the optional names: local-only changes are uploaded, remote-only changes are downloaded, and conflicts require --prefer local or --prefer remote. The committed .kib.json in each skill records its last synchronized tree, so this works across machines without relying on a local cache. kib remove deletes from the library; --local deletes only from the project. kib only manages project skills under ./.kia/skills/ and does not list or special-case bundled skills. Upload validates the pack and rejects symlinks; kib install never overwrites existing local skills.

Personas¶

A persona owns the agent’s identity, system prompt, and tool surface — unlike skills, which add instructions, a persona replaces them. Personas are Python modules bundled in kiui/agent/personas/; coder (the default) is the full coding agent, while chatter is a general chatbot limited to web_search and web_fetch, with no file/shell access and no environment context in its prompt.

kia --persona chatter   # start as another persona

/persona                list installed personas and their tool surface
/persona chatter        switch persona (restarts the conversation, like /clear)

Each persona module defines build_system_prompt(ctx) — composed from the shared blocks and builders in kiui/agent/personas/common.py — and a TOOLS whitelist that controls which tools are advertised to the model. This is capability guidance, not a security boundary: interactive commands such as !<command> and /skills remain available to the user and are governed by the normal permission and safety checks.

kia — an AI agent for your terminal¶