kiss-agent 0.1.3

Terminal-based stupid assistant

kiss-agent

A terminal-based coding assistant.

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

First Run

Start the app, then connect a provider from inside the UI:

kiss

Run /connect to authenticate a provider, then /model to pick the model you want to use.

If you prefer environment variables, you can still set provider credentials manually and then use /model.

settings.jsonc.example is an advanced reference for optional settings. It is not the recommended first-run path.

Usage

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

Documentation

• Architecture Overview: High-level technical design.
• Capabilities Overview: Overview of what the agent can do.
• 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.

Current Capabilities

• Write Guard to prevent accidental overwrite of existing files.
• Intent-aware tool gating and per-role tool access controls.
• Thinking and cycle budgets with budget-exceeded turn finish handling.
• Quality monitor with automatic correction retry for empty/malformed responses.
• Stateful Bash sessions with reset command and cwd visibility in status UI.
• Evidence store and snapshot restore/export support for durable context hints.
• Dynamic skill loading with cache, mtime invalidation, and tool-category expansion.

License

MIT — do whatever you want with this stupid agent.