kiss-agent 0.1.2

Terminal-based stupid assistant

kiss-agent

A terminal-based stupid assistant.
He might be stupid, but he now runs as a unified phase-aware coding agent with one turn engine and a shared event loop.

Context

Experimental AI agent written in python for personal use and learning lessons.

It started from personal chat to understand the basics.
Then I tried to use pydantic-ai to avoid reinventing the wheel. It simplified lots of things.
But I felt losing control and not learning how things work.
So here we are, with this new experiment relying on mirascope. The library provides the core toolkit for LLM calls. So I can focus on tooling and logic.

Quick Start

Installation

Requires Python 3.12+.

With pip:

pip install kiss-agent

With uv:

uv tool install kiss-agent

Minimal Configuration

Create .kiss/settings.json:

{
  "model": "anthropic:claude-sonnet-4-6"
}

Then set your API key as an environment variable:

export ANTHROPIC_API_KEY=sk-...

Or authenticate interactively from within the UI with /connect — it opens a provider picker showing all supported providers and their current auth status.

Usage

kiss                               # Rich UI (default)
kiss --tui                         # Textual TUI
kiss "Explain this codebase"       # headless

Documentation

• Architecture Overview: High-level technical design.
• Configuration Reference: Detailed settings and CLI flags.
• Tool System & Permissions: How agents interact with your files.
• Agent Loop: Details on the core execution and streaming.
• Turn Engine & Phases: Deep dive into the unified turn engine and phase flow.
• Context Compaction: How history and tokens are managed.
• Observability: Tracing and local diagnostics.
• Terminal UI: Rich and Textual backend design and parity rules.

License

MIT — do whatever you want with this stupid agent.