> Everything should be made as simple as possible, but not simpler.

— Albert Einstein

# Tell it what to do, in English and give it a concrete goal. It picks the best LLMs, runs on your laptop, and ships the work.

Apache 2.0 · open source 62.2% on Terminal Bench 2.0 502 models · 9 providers ~2,500 lines of core agents code

KISS Sorcar is an open-source general-purpose AI agent for long-horizon tasks and AI discovery. It is a simple, local-first, bring-your-own-key AI agent framework. It runs as a VS Code extension, a Claude-Code-style CLI, and a browser/mobile web app. Your prompts and code are sent directly to the model provider or local endpoint you configure — not through our servers. It supports multi-model workflows just via prompts. All agents run as daemons.

Watch the KISS Sorcar demo video

### Full installation script

★ Recommended

Preferred way to install KISS Sorcar — macOS & Linux, one command, no extra steps.

Install (VS Code)
★ Star on GitHub …
§ 01 — KISS Sorcar vs Claude Code vs Cursor

## How does it compare?¶

A side-by-side look at the differences that matter for everyday use.

Capability | KISS Sorcar | Claude Code | Cursor
--- | --- | --- | ---
Interfaces | CLI + VS Code extension + web/mobile app | CLI + mobile app | Custom VS Code
AI Discovery | ✓ simply via prompt | ✗ | ✗
GEPA Prompt Optimization | ✓ simply via prompt | ✗ | ✗
Multiple models from multiple vendors in the same task | ✓ Mix OpenAI, Anthropic, Gemini, Together, Z.AI, Moonshot AI, OpenRouter, Claude Code CLI, and Codex CLI | ✗ Anthropic Claude models only | ✗ One model per task
Primary focus | ✓ Quality — rigorous review, end-to-end tests | Speed and developer ergonomics | Speed
Core Agents # LoC | ~2500 | Unknown | Unknown
Models in bundled catalog | 502 across 9 provider categories | Claude family only | Subset chosen by Cursor
Bring your own API key / endpoint | ✓ Yes — keys stay on your machine | ✓ Anthropic key | ⚠ Routed through Cursor backend
Open source | ✓ Apache-2.0 | ✗ Proprietary | ✗ Proprietary
Price | Free framework; pay only your chosen model provider | Subscription / API usage | Subscription
Run on top of Claude Code / Codex CLI | ✓ `cc/*` and `codex/*` namespaces | N/A | ✗
Messaging and communication channels | ✓ 23 third-party agents, including Slack, Gmail, Phone Control, SMS, and WhatsApp | ⚠ Slack, mobile Remote Control, and research-preview channels for Telegram, Discord, and iMessage; no documented built-in Gmail, WhatsApp, phone-call, or SMS channel | ⚠ Slack and Microsoft Teams Cloud Agent integrations; no documented built-in Gmail, WhatsApp, phone-call, or SMS channel
Terminal Bench 2.0 score | 62.2% | 58% | 61.7% (Cursor agent)

§ 02 — All you need is a short prompt in KISS Sorcar to do big complex tasks

## All You Need is a Short Prompt in KISS Sorcar to do Big Complex Tasks.¶

KISS Sorcar ships with a curated set of sample tasks (long-horizon prompts you can drop straight into the CLI or VS Code extension or Web app) and promptlet tricks (short reusable directives that steer Sorcar's behaviour by injecting to the prompt). The tasks live in `src/kiss/SAMPLE_TASKS.md`; the tricks live in `src/kiss/INJECTIONS.md`. You can add your tasks at `~/.kiss/MY_TASK_TEMPLATES.md` and your promptlets at `~/.kiss/MY_INJECTIONS.md`.

### Explain a workflow step-by-step

Task

Ask Sorcar to walk you through the detailed step-by-step workflow of any algorithm or feature in your codebase, so you can understand it before changing it.

    Can you show me the detailed step-by-step workflow of <<your algorithm or feature>>

### Edit a specific step of a workflow

Task

Modify a specific step of an existing workflow with a precise natural-language instruction — no need to point Sorcar at the file, it will find the right code.

    Can you change the step <<specify step>> as follows: <<whatever way you want to change>>

### Authenticate with a Slack workspace

Task

Have Sorcar log you into a Slack workspace using the bundled Slack agent, so it can send and receive messages on your behalf.

    can you authenticate me with the <<workspace name>> workspace on Slack using the Slack agent?

### Run a Slack-driven cron job

Task

Spin up a named cron job that polls a Slack channel for unanswered messages, runs them as Sorcar tasks in arrival order, and replies with Slack-formatted results.

    Can you create a cron job with a name prefixed with "kiss-" which will check every 3 seconds if there are latest unanswered messages from /<<user name>> in the channel sorcar using the Slack agent, then it will run the messages as tasks one-by-one in the order of arrival and respond with the result suitably formatted for Slack.

### Authenticate with iMessage

Task

Connect Sorcar to your iMessage account so it can send and receive texts directly from macOS.

    can you authenticate me with the iMessage agent?

### Send an SMS to a phone number

Task

Dispatch a one-line SMS to any phone number through Sorcar's messaging agents — no scripting required.

    can you send "Hello" to 1-800-772-1213?

### Authenticate with Gmail

Task

Walk through the OAuth login flow for Gmail using the bundled Gmail agent, with the browser handling consent and Sorcar storing the token locally.

    can you authenticate me with Gmail using the Gmail agent? Use the user's default browser to ask the user to log in and to get the authentication token.

### Audit a paper or repo for fraud

Task

Have Sorcar fact-check a URL for wrong assumptions, cheating, irreproducibility, fraud, AI slop, and security vulnerabilities — verifying every claim and shipping an HTML report.

    Can you read <<url>>, and thoroughly and precisely check for **wrong assumptions**, **cheating**, **irreproducibility issues**, **fraud**, **potential for cheating in evaluation**, **AI Slop**, and **security vulnerabilities**? Use internet search extensively and do not believe what people say -- verify them yourself. Do not hesitate to download code and run it to validate results. For security vulnerabilities, create a POC and test it. Generate an html report in ./sorcar_reported_frauds/ and open in the user's default browser. Thoroughly fact check everything you claim in the report.

### Sorcar for AI Discovery

Task

Let Sorcar search, train, and benchmark candidate models on your data to find the lightest, fastest, cheapest model that hits a target accuracy and recall — without reward-hacking the evals.

    Sorcar for AI Discovery: Can you discover the lightest and fastest AI model that will give the best accuracy and recall on the data at <</path/to/data>> at the cheapest price? Analyze the data and search the internet extensively to propose the first few models. Implement and experiment with each of your proposals. Note down the ideas you used to optimize the accuracy/recall and speed/cost metrics achieved in a file, so that you can use the file to not repeat ideas that have already been tried and/or failed. You can also use the file to combine ideas that have been successful in the past. Separate 20% of the data for evals, and your discovery strategy must not look at the evals data. Use 'lambda' CLI to train your models on GPUs and evaluate if needed. Total budget for Lambda Labs is $1000. Experiment with a smaller subset of data and fewer parameters in a model to do experiments quickly, and then extrapolate. Use internet search extensively at every step. MAKE SURE THAT YOU DO NOT DO REWARD HACKING OR CHEATING IN THE MODELS OR AGENTS YOU ARE IMPLEMENTING TO FIT DATA. YOUR SOLUTION MUST GENERALIZE BEYOND THE DATA PROVIDED. Do not STOP until accuracy/recall reaches 95% on evals and you can process each query in less than 600 seconds and under 50 USD per query amortized over all queries. Create an html report with diagrams and illustrations in ./reports and open it in the user's default browser?

### Sorcar for Optimization

Task

Run a command in the background, let Sorcar instrument and monitor its output, and iteratively rewrite the code to hit your speed, accuracy, recall, and cost targets.

    Sorcar for Optimization: Can you run the command <<command>> in the background and monitor its output in real time to optimize the code at <<folder_name_or_url>> with respect to the following metrics: <<speed,accuracy,recall,cost>>. You can add diagnostic code which will print the metrics, such as running time at a finer level of granularity. Check for opportunities to optimize the code on the basis of the metrics information. If you discover any opportunities to optimize the metric based on the code, logs, events, and the command output, optimize the code and run the command again. Note down the ideas you used to optimize the code and the metric you achieved in a file, so that you can use the file to not repeat ideas that have already been tried and failed. You can also use the file to combine ideas that have been successful in the past. Repeat the process. Do not forget to remove the diagnostic code after the optimization is complete. You MUST NOT STOP until the metrics achieve the following values:<<give_concrete_values_for_metrics>>. Use the internet extensively to get new ideas for optimization. Create an html report with diagrams and illustrations in ./reports and open it in the user's default browser?

### Sorcar GEPA Prompt Optimizer

Task

Run a full GEPA Pareto-frontier prompt-optimization loop over your dataset to evolve the best prompt for a `ChatSorcarAgent`, with cross-model review and no reward hacking.

    Sorcar GEPA Prompt Optimizer: Can you optimize a prompt for a ChatSorcarAgent of the kiss-agent-framework Python library using the following GEPA algorithm on the data at <<url_or_db_file_of_data>> using claude-opus-4-7? You can find the trajectory events of an agent execution in ~/.kiss/sorcar.db after the agent has finished its execution. Split the dataset into 50% dev set and 50% val set.

    RUN_GEPA: Sample 100 data points from the val set and call it sval set. Maintain a pareto frontier in the folder ./pareto where we have a sub-folder for each node in the frontier. A node contains a prompt file (prompt.md) and a json file, say score.json, containing the list of datapoints (ids) from the sval set that were correctly predicted with the prompt. When you add a node to the pareto frontier make sure that the list of correctly predicted datapoints is not a subset or equal to an existing list of datpoints in some node in the frontier. If such a node exists, do not add the new node. After adding a node, remove all nodes whose list of datapoints is a subset or equal to the list of datapoints in the added node. Then run the following algorithm.

    1. pick a node from the pareto frontier with probability 0.5
       a. sample a minibatch of 5 datapoints from the dev set
       b. run the agent with the prompt from the node on the minibatch
       c. if the agent incorrectly predicts for some datapoints, analyze and reflect on the trajectory events of the agent on those datapoints available at ~/.kiss/sorcar.db and propose a new prompt which will fix the mistakes made by the agent on datapoints incorrectly predicted.
       d. if the agent predicts correctly on the minibatch, then evaluate it on the sval set and create the list of datapoints on which the agent with the new prompt predicts correctly.
       e. Add the new prompt and the list of datapoints to the pareto frontier

    2. pick two nodes from the pareto frontier randomly with the remaining probability.
       a. sample a minibatch of 5 datapoints from the dev set
       b. merge the prompts from the two nodes into a new prompt.
       c. if the agent predicts correctly on the minibatch with the new prompt, then evaluate it on the sval set and create the list of datapoints on which the agent with the new prompt predicts correctly.
       d. Add the new prompt and the list of datapoints to the pareto frontier

    3. Repeat steps 1 and 2 until there is no change in the prompt after 3 iterations.
    END_RUN_GEPA
    Repeat RUN_GEPA until there is no change in the prompt after 3 iterations.

    In each step, keep track of the best prompt which has the maximum number of successfully predicted datapoints in ./pareto/optimal.md. MAKE SURE THAT YOU DO NOT DO REWARD HACKING OR CHEATING IN THE AGENT YOU ARE IMPLEMENTING TO FIT DATA. YOUR SOLUTION MUST GENERALIZE BEYOND THE DATA PROVIDED. Use internet search extensively at every step. Do not worry about budget. Create an html report with diagrams and illustrations in ./reports and open it in the user's default browser. Do NOT STOP until you could not improve the accuracy and recall after three consecutive rollouts. Use gpt-5.5 model (not codex) for thorough review of the work done at every step by the other model.

### Run GEPA on HotpotQA

Task

A one-liner to invoke `gepa.py` on the HotpotQA dataset with `gpt-4o-mini` as both the task model and the optimizer.

    Can you run gepa.py on hotpotqa using gpt-4o-mini as both models

### Force exhaustive web search

Trick

Drop this trick into any task so Sorcar grounds its reasoning in current web evidence instead of stale training data.

    Search internet extensively.

### Reproduce with an integration test

Trick

Enforce a test-first workflow for bug fixes — write a failing integration test that reproduces the issue before changing any production code.

    Reproduce the issue by writing an integration test. Then fix the issue.

### Reproduce with an end-to-end test

Trick

Same as the integration-test trick, but demands full end-to-end coverage so the regression is locked down across module boundaries.

    Reproduce the issue by writing an end-to-end test. Then fix the issue.

### Reproduce invariant violations

Trick

Codify suspected invariant breaks as end-to-end tests first, then let Sorcar fix the offending code so the invariant holds forever.

    Reproduce any violation of the ivariant by writing end-to-end tests. Then fix the issue.

### Pair-program with multi-model review

Trick

Use Claude Opus as the implementer and GPT-5.5 as the reviewer/debugger so missed code paths and silent bugs are caught before they ship.

    Use claude-opus-4-7 model for all tasks including coding, bug fixing, and test creation. Use gpt-5.5 model (not codex) for thorough review and debugging of the work done by the other model. Check if the other model has missed some code or has introduced bugs. No need to check if the models exist.

### Review the last task with GPT-5.5

Trick

Spawn a review pass on your previous task: GPT-5.5 finds bugs and missing code, Claude Opus reproduces and fixes them with end-to-end tests, in a loop until the review is clean.

    Can you review the updates made in the last task using gpt-5.5 (non codex) and find bugs or missing code. Then write end-to-end tests reproducing the bugs reported by the review, fix them, and test them using claude-opus-4-7? Run all the tests in parallel and fix bugs after thoroughly reviewing the fixes with gpt-5.5 (non codex). Repeat the process until you fail to reproduce the bugs reported by the review done by gpt-5.5 (non codex). No need to check if the models exist.

### Self-review the current task

Trick

The same dual-model review loop, but applied to the in-flight task before you finish — bugs are reproduced, fixed, and re-reviewed in place.

    Review the updates made in the current task using gpt-5.5 (non codex) and find bugs or missing code. Then write end-to-end tests reproducing the bugs reported by the review, fix them, and test them using claude-opus-4-7? Run all the tests in parallel and fix bugs after thoroughly reviewing the fixes with gpt-5.5 (non codex). Repeat the process until you fail to reproduce the bugs reported by the review done by gpt-5.5 (non codex). No need to check if the models exist.

### Use GLM-5.2 with dual review

Trick

Switch the implementer to OpenRouter's GLM-5.2 and have both GPT-5.5 and Claude Opus carefully review its output for bugs and missing code.

    Use openrouter/z-ai/glm-5.2 model for all tasks including coding, bug fixing, and test creation. ALWAYS use gpt-5.5 model (not codex) to carefully and thoroughly review and debug the work done by openrouter/z-ai/glm-5.2 for bugs and missing code. Then use claude-opus-4-7 to do the same thing.

### Resolve a merge conflict

Trick

Paste the merge-conflict message after this trick and let Sorcar analyse the diff and resolve the conflict for you.

    Can you check the following message on merge conflict and help me fix it?

### Generate an HTML report

Trick

Have Sorcar package its findings into a polished HTML report with diagrams and illustrations under `./reports`, and open it in your default browser.

    Can you create an html report with diagrams and illustrations in ./reports and open it in the user's default browser?

### Guard against reward hacking

Trick

Add this guard so Sorcar audits its own implementation for shortcuts, overfitting, or cheating that would inflate metrics but fail to generalise.

    Make sure that there is no reward hacking and cheating when reviewing your implementation.

### Push to origin

Trick

A quick reminder for Sorcar to push your committed work upstream when you're done.

    git push origin

### Rewind to a specific commit

Trick

Reset both your local branch and the remote to a specific commit, discarding every commit that came after it.

    Get rid of all commits after the following commit from both main and origin:

### Build paper & screenshot-check formatting

Trick

Have Sorcar compile your LaTeX paper, take screenshots of the rendered PDF, and iterate on the source until the layout is right.

    Build the paper, and take screenshots to check and fix formatting.

### Debug the last failure

Trick

Analyse the previous task's logs and trajectory events, reproduce the issue with an integration test, then fix the underlying cause.

    Why did the last task failed? Thoroughly and precisely analyze the logs and the events of the task. Reproduce the issue by writing an integration test. Then fix the issue.

§ 03 — What is in the Name

## What is in the Name?¶

Two names. One principle. A nod to a Bengali magician.

KISS Agent Framework

### Keep it Simple, Stupid.

KISS Agent Framework is a deliberately small agent runtime organized around the KISS principle — "Keep it Simple, Stupid."

KISS Sorcar

### Named after P. C. Sorcar.

KISS Sorcar is named after P. C. Sorcar, the Bengali magician. Note: Sorcar also means government in Bengali.

§ 04 — Installation

## Install in one line.¶

Pick the install path that fits you — full source, Python package, or the VS Code extension. All you need is at least one API key from a major LLM provider. The one-line install script below is the recommended way to install the full KISS Sorcar stack.

### Full install from source ★ Recommended

Preferred way to install the full KISS Sorcar stack. Works on macOS and Linux (`x86_64`, `aarch64`, `arm64`). Installs or checks every tool needed to run KISS Sorcar and build/install the VS Code extension — one command, no extra steps.

$ curl -fsSL https://raw.githubusercontent.com/ksenxx/kiss_ai/main/scripts/install.sh | bash

### Python package / CLI install

For just the Python package and CLI entry points. KISS Sorcar requires Python 3.13+.

$ pipx install kiss-agent-framework
# or
$ uv tool install kiss-agent-framework

### Configure model access

Provide at least one model backend through environment variables:

export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GEMINI_API_KEY=...
export TOGETHER_API_KEY=...
export ZAI_API_KEY=...
export MOONSHOT_API_KEY=...
export OPENROUTER_API_KEY=...

Or configure a custom endpoint with `--endpoint` / `-e` and optional repeated `--header Key:Value` CLI flags.

### VS Code Extension

To install only the KISS Sorcar extension, open Visual Studio Code, search for KISS Sorcar in the extension marketplace, install it, and relaunch VS Code.

Press `ESC` if you do not have a specific API key ready, but configure at least one model backend before running tasks.

§ 05 — CLI in 30 seconds

## The `sorcar` CLI.¶

Run `sorcar` alone for an interactive Claude-Code-style REPL with worktree-isolated tasks, slash commands, and chat history; pass `-t "…"` or `-f task.md` for a one-shot non-interactive run. Pick any model with `-m`, point at a self-hosted endpoint with `-e`, cap spend with `-b`, and add MCP servers with `sorcar mcp add`.

### Four invocations to get you started

# 1. Interactive REPL (recommended for first run)
sorcar
# 2. One-shot task on any model, with a $2 cap
sorcar -m "claude-sonnet-4-6" -b 2.0 -t "Refactor utils.py for clarity."
# 3. Self-hosted or local model
sorcar -e "http://localhost:8000/v1" -t "Summarise this codebase."
# 4. Run a Slack/Gmail/SMS task via a third-party agent
sorcar -t 'Send "Hello from Sorcar!" to ksen via the desktop Slack app.'

Full reference (every flag, `sorcar mcp` subcommands, slash commands, skills, MCP discovery, and VS Code Tricks): Full CLI reference →

§ 06 — Messaging & Third-Party Agents

## 💬 Reach the agent from anywhere.¶

KISS Sorcar includes 23 third-party messaging agents that can send and receive messages on your behalf. It also ships a Govee smart-home CLI for controlling IoT lights (on/off, brightness, color, and color temperature) via the Govee Developer API. These agents live in `src/kiss/agents/third_party_agents/`.

### 23 messaging channels

BlueBubbles Discord Feishu Gmail Google Chat iMessage IRC LINE Matrix Mattermost Microsoft Teams Nextcloud Talk Nostr Phone Control Signal Slack SMS Synology Chat Telegram Tlon Twitch WhatsApp Zalo

### Plus: smart-home control

A Govee smart-home CLI for controlling IoT lights — on/off, brightness, color, and color temperature — directly via the Govee Developer API.

§ 07 — Models Supported

## 🤖 502 models. 9 provider categories.¶

KISS Sorcar ships a catalog of 502 models across 9 provider categories, with built-in prices, context lengths, and capability flags (`fc` function calling, `gen` generation, `emb` embedding). The source of truth is src/kiss/core/models/MODEL_INFO.json.

### Provider categories

OpenAI 70
Anthropic 13
Gemini / Google 23
Together AI 77
Z.AI 8
Moonshot AI 6
OpenRouter 295
Claude Code CLI (`cc/*`)3
Codex CLI (`codex/*`)7

### Catalog capability totals

Across all bundled providers, the catalog currently reports:

486
generation-capable models
326
function-calling-capable models
7
embedding models

See the full per-provider model list in the README, including the `cc/*` and `codex/*` namespaces that let KISS Sorcar run on top of the Claude Code and Codex CLIs.

§ 08 — Contributing

## 🤗 Contributing.¶

Contributions in the form of issues are welcome. KISS Sorcar should be able to help implement and review them.

### Open an issue

Report bugs, request features, or share ideas. Each issue becomes a candidate task KISS Sorcar can pick up and work on.

Open an issue →

### Let KISS Sorcar implement and review

Drop an issue link into a Sorcar task and it will draft a fix, run tests, and self-review before opening a PR.

GitHub repo →

§ 09 — License

## 📄 License.¶

KISS Sorcar is released under a permissive open-source license.

### Apache-2.0

Use it for anything — personal, commercial, research, education. See LICENSE for the full text.

Apache License 2.0
§ 10 — Citation

## 📚 Cite the paper.¶

If you use KISS Sorcar in your research, please cite:

Koushik Sen. KISS Sorcar: A Stupidly-Simple General-Purpose and Software Engineering AI Assistant. arXiv preprint arXiv:2604.23822, 2026.

    @misc{sen2026kisssorcar,
      title         = {KISS Sorcar: A Stupidly-Simple General-Purpose and Software Engineering AI Assistant},
      author        = {Sen, Koushik},
      year          = {2026},
      eprint        = {2604.23822},
      archivePrefix = {arXiv},
      primaryClass  = {cs.SE},
      url           = {https://arxiv.org/abs/2604.23822}
    }