---
title: KISS Agent Framework Overview
url: https://www.emergentmind.com/topics/kiss-agent-framework
type: topic
---

# KISS Agent Framework Overview

The KISS Agent Framework is “a stupidly simple AI agent framework containing around 1,850 lines of code,” organized as a five-layer agent hierarchy in which each layer adds exactly one concern: budget-tracked ReAct execution, automatic continuation across sub-sessions via summarization, coding and browser tools with parallel sub-agents, persistent multi-turn chat with history recall, and git worktree isolation so every task runs on its own branch. It is the generic, reusable core beneath KISS Sorcar, a free, open-source Visual Studio Code extension that runs locally as a general-purpose and software engineering assistant, supports browser automation, multimodal input, and Docker containers, and is explicitly optimized for long-horizon tasks and output quality over latency [2604.23822].

## 1. Definition and design orientation

“KISS” is literal: **Keep It Simple, Stupid**. In the framework’s own formulation, simplicity is not a rhetorical preference but a structural constraint. The system is intentionally narrow, opinionated, and implemented so that an LLM can itself understand and maintain it. Its core design rules are **single concern per layer**, **minimal code, strong prompts**, **quality over latency and cost**, **robustness and debuggability**, and a **stateless core, stateful wrappers** architecture [2604.23822].

The framework addresses a set of concrete failure modes in agentic coding systems: **finite context windows**, **error cascades / agents getting stuck**, **AI slop**, **irreversible or hard-to-review changes**, and **opaque cost**. The response is correspondingly concrete. Rather than relying on a large orchestration substrate, the framework uses a rich, highly structured system prompt plus a strict inheritance hierarchy. The innermost KISS Agent remains stateless across runs, while persistence, history recall, branch management, and related concerns are delegated to outer layers [2604.23822].

This architecture differs from large, general agent frameworks such as LangChain and AutoGen. The framework is described as “very small but carefully engineered,” with the intended result being a **robust, debuggable, long-horizon assistant** whose behavior remains easy to reason about because each layer contributes exactly one new responsibility [2604.23822].

## 2. Layered architecture

All five layers are implemented as a **strict inheritance chain**, each delegating upward for concerns it does not own. The framework consists of these five classes plus the system prompt; KISS Sorcar, the IDE application, instantiates the outermost layer [2604.23822].

| Layer | Agent class | Added concern |
|---|---|---|
| 1 | KISS Agent | budget-tracked ReAct loop with native function calling |
| 2 | Relentless Agent | automatic summarization and continuation across sub-sessions |
| 3 | Sorcar Agent | coding tools, browser automation, and parallel sub-agents |
| 4 | Chat Sorcar Agent | persistent multi-turn chat with history recall |
| 5 | Worktree Sorcar Agent | git worktree isolation so every task runs on its own branch |

At the first layer, the **KISS Agent** is the generic ReAct executor. It generates OpenAI-compatible tool schemas from plain Python callables with type-annotated signatures, caches those schemas, passes tool results back to the model as tool outputs, and tracks **step / token / cost budgets**. At each LLM call it extracts input and output token counts from provider usage metadata, computes dollar cost using a per-model price table, increments both a **per-agent** budget counter and a **global** budget counter guarded by a class-level lock, and checks per-agent budget, global budget, and maximum step count before each step. It retries transient API errors such as rate limits and 5xx responses up to a configurable number of consecutive failures, immediately fails on non-retryable errors such as auth and permission failures, and can operate in **non-agentic mode** through a single generation call when no tools are needed. Each `run()` resets conversation history, token counters, and tool registry, preserving the layer’s statelessness [2604.23822].

The framework’s code-size distribution reinforces the one-concern-per-layer philosophy. The KISS Agent is 409 lines, the Relentless Agent 297 lines, the Sorcar Agent 323 lines, the Chat Sorcar Agent 120 lines, and the Worktree Sorcar Agent 692 lines, for a total of roughly 1,850 lines excluding comments and blank lines. The implementation is all Python under `kiss.core` and `kiss.agents.*`, while the KISS Sorcar VS Code extension is separate TypeScript/JavaScript code that hosts the Worktree Sorcar Agent and renders the UI, including a chat panel, live budget, browser view, and commit/merge/discard controls [2604.23822].

## 3. Continuation, summaries, and long-horizon execution

The **Relentless Agent** is the mechanism by which the framework handles context limits and session derailment. Its responsibility is **long-horizon execution across context windows**, using summarization and automatic continuation. The key protocol is built around a `finish` tool whose schema contains `success: bool`, `is_continue: bool`, and `summary: str`. If `is_continue = False`, execution terminates normally. If `is_continue = True`, the current run is treated as the end of a **sub-session**, and a new sub-session starts with a fresh context while carrying forward the `summary` [2604.23822].

The summaries are not generic recaps. The model is instructed to produce a **precise, chronologically ordered list of actions** with reasons and code snippets. The framework reports that naive “summarize the context” instructions produced poor continuations, whereas this more structured format worked much better. A new sub-session receives a numbered list of all previous summaries as `{progress_text}` together with directives such as “Complete the rest of the task,” “DON’T redo completed work,” and “If you have been retrying the same approach without progress, rethink from scratch” [2604.23822].

Continuation is also made proactive. The system prompt includes a hard rule that at a specified `step_threshold`, the agent **must** call `finish(success=False, is_continue=True, summary="…")` if the task is not complete and it is at risk of running out of steps or context length. The effect is that, instead of rushing to finish under pressure, the agent hands off to a fresh context with an explicit work log. The paper characterizes this as ensuring that tasks “never die quietly”; even when a sub-session crashes or hits a step limit without calling `finish`, the full trajectory is dumped to `{trajectory_file}`, and a separate summarizer agent in non-agentic mode is prompted to read the trajectory file and return a precise chronologically ordered list of actions, reasons, and relevant code snippets. That generated summary becomes the next `progress_text` [2604.23822].

This yields a two-level memory system. Within a sub-session, the model relies on the normal LLM conversation and tool results. Across sub-sessions, memory is purely textual: chronological summaries that record what was attempted, what worked, what failed, and what should not be retried. There is no vector store and no learned memory in this layer [2604.23822].

## 4. Tools, persistent chat, and git-isolated software workflow

The **Sorcar Agent** adds the practical tooling needed for software and web tasks. Its coding tools intentionally match Claude Code’s names: `Read`, `Write`, `Edit`, and `Bash`. `Read` reads files, with instructions to read large files in chunks; `Write` writes new files only; `Edit` performs precise, string-based edits of existing files and enforces pre-read; and `Bash` runs shell commands with streaming output and `timeout_seconds`, while respecting a user stop event. The same layer adds browser automation through a `web-use`/`go_to_url` tool built on Chromium and Playwright, capable of navigating, reading the accessibility tree, clicking, typing, scrolling, pressing keys, and taking screenshots. It also exposes a parallel-execution tool that spawns multiple Sorcar Agent instances in a thread pool, each with its own context and tools, and returns results in input order. In the VS Code extension this parallel tool is disabled by default because streaming many parallel traces into one chat UI is described as messy. A user-interaction tool, `ask-user-question`, pauses execution and routes questions either into the VS Code UI or to stdin in CLI mode. When a Docker image is configured, coding tools are replaced by containerized versions so that shell and file operations execute inside the container, providing sandboxing and environment consistency [2604.23822].

The **Chat Sorcar Agent** adds persistence through **chat sessions and IDs**. For each task in a chat, it stores the task description, result, and metadata including model, working directory, cost, execution time, parallelization, and worktree isolation in a local database. When a new task arrives in an existing chat session, it loads all prior tasks and results for that chat ID and prepends them as numbered context entries in the prompt. Session management supports starting a new chat, resuming by task description, and resuming by explicit chat ID. There is no vector store; retrieval is deterministic and consists simply of all past tasks for that chat, ordered chronologically [2604.23822].

The outermost **Worktree Sorcar Agent** makes the framework’s software-engineering workflow safe and reversible through **git worktree isolation**. When a task starts in a git repository, it creates a new branch named `kiss/{chat_id}/{timestamp}` and a corresponding git worktree directory. All coding happens in the worktree, while the main working tree remains untouched. If the main working tree has uncommitted changes, the framework copies them into the worktree and creates a **baseline commit** there; on merge, it cherry-picks from the baseline commit while excluding the dirty snapshot, so only agent modifications are replayed onto the main branch. On successful completion, the UI offers **Commit and Merge** or **Discard**. Commit and Merge stages all changes in the worktree, asks the LLM to generate a commit message, commits on the task branch, merges into the original branch by squash or similar means, deletes the worktree and task branch, and ensures the original working tree is left clean. Discard deletes the worktree and task branch and returns to the original branch untouched [2604.23822].

Concurrency and recovery are handled at the repository level. A **per-repo file lock** serializes git operations such as checkout, merge, prune, and stash/pop. Thread-local storage is used for per-task state, including streaming buffers, so stopping one task does not corrupt another. Crash recovery stores the necessary state in git itself, including branch names and git config entries rather than sidecar files; on restart, the agent searches for pending branches with chat-ID prefixes and reconstructs attributes from git config. If git is unavailable, if the directory is not a git repo, if the repo has no commits, or if `HEAD` is detached, the system falls back to direct execution using Sorcar Agent behavior rather than refusing to work [2604.23822].

## 5. Quality-first execution and empirical results

A defining operational choice is the deliberate prioritization of **output quality over latency**. The framework encourages the model to run linters, type-checkers, and tests, to achieve high coverage, and to verify behavior before claiming success. The authors explicitly accept higher per-task cost and latency in exchange for fewer failed or low-quality runs, on the expectation that model prices and latency will continue to fall. This emphasis is presented as a direct response to “AI slop” and unverified code generation [2604.23822].

The system was also developed under a self-referential stress condition: “The entire system was built using itself in 4.5 months,” so any agent-introduced bug would immediately impair the assistant’s own ability to continue working. This does not constitute a formal proof of robustness, but it provides a continuous stress test embedded in the development workflow [2604.23822].

Evaluation is reported on **Terminal Bench 2.0**. The setup uses 89 tasks in Docker containers, 5 trials per task for 445 total runs, Claude Opus 4.6 as the model, no benchmark-specific prompt modifications, and a `SorcarHarborAgent` described as a thin adapter that installs and calls the `sorcar` CLI in each container. On this benchmark, KISS Sorcar achieves a **62.2% overall pass rate** with **277/445** successful runs, **pass@any 78.7%** with **70/89** tasks solved at least once across five trials, and **pass@all 43.8%** with **39/89** tasks solved in all five trials. Reported comparisons using the same model are **Claude Code: ~58%** and **Cursor Composer 2: 61.7%**. Median cost per trial is **\$0.45** with mean **\$0.90**, and median duration is **202 s** with mean **446 s** [2604.23822].

The paper interprets these results as evidence that the **architecture + prompt**—especially continuation summaries, worktree isolation, testing discipline, and budget tracking—provide measurable gains without any RL fine-tuning. At the same time, the authors do not report explicit ablations such as turning off continuation and rerunning the benchmark. The support for individual mechanisms is therefore partly benchmark-based and partly qualitative [2604.23822].

## 6. Limitations, scope, and relation to other agent frameworks

The framework’s limitations are explicit. First, it is intentionally not optimized for minimal delay: running linters, type-checkers, tests, reading many files into summary files, and exploring many web pages is expensive in both latency and cost. Second, its simplicity is also a constraint: there is **no vector store or learned RAG**, memory is “just text summaries and history lists,” and continuation follows only one pattern, namely chronological summaries. Third, summaries may grow large over very long tasks; the authors note that they have not seen this become problematic in practice, but also state that it is not solved systematically. Fourth, the design assumes a “frontier model” such as Opus 4.6 or a GPT-class model, because so much discipline is enforced via prompt rather than code. Fifth, parallel sub-agents are powerful but disabled in the IDE UI because interleaving many tool traces is confusing. Finally, the framework offers no explicit formal guarantees; budget tracking and worktree isolation are engineering safeguards rather than verified properties [2604.23822].

The name also requires disambiguation. It should not be conflated with **“KISS: Keeping it Simple and Slotted when Learning to Communicate over Wireless”**, which studies fully decentralized MAC learning with Bayesian DDQN agents over a slotted channel [2606.00266]. Nor is it the same as **Kiko**, a protocol-based programming model in which decision makers act over enabled forms to guarantee protocol compliance and realize protocol enactments [2606.26156]. Other contemporary agent architectures in the supplied literature address different targets: **K²-Agent** separates declarative “know-what” and procedural “know-how” for hierarchical mobile device control [2603.00676], whereas **Agents-K1** constructs agent-native scientific knowledge graphs and exposes them through a tri-source agent interface for multi-hop scientific reasoning [2606.13669].

These comparisons suggest that “KISS Agent Framework” refers to a specifically software-engineering-oriented LLM agent stack rather than a general umbrella for all simple agent designs. Its distinguishing characteristics are not merely compactness but the combination of a **budget-aware ReAct core**, **relentless continuation across sub-sessions**, **coding and browser tools**, **persistent chat recall**, and **git worktree isolation** in a layered system small enough for direct inspection and maintenance [2604.23822].

Source: https://www.emergentmind.com/topics/kiss-agent-framework