KISS Agent Framework Overview
- KISS Agent Framework is a layered AI system with a five-tier hierarchy, each layer addressing a single concern like budget tracking and stateful persistence.
- The design emphasizes structural simplicity and modularity, ensuring each layer—from ReAct execution to git worktree isolation—adds measurable value.
- Empirical results highlight robust, quality-first execution with ongoing session summaries, controlled context management, and reproducible performance.
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
| 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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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” (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Sen, 26 Apr 2026).
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 (Szczech et al., 29 May 2026). 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 (Christie et al., 23 Jun 2026). 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 (Wu et al., 28 Feb 2026), whereas Agents-K1 constructs agent-native scientific knowledge graphs and exposes them through a tri-source agent interface for multi-hop scientific reasoning (Cao et al., 11 Jun 2026).
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 (Sen, 26 Apr 2026).