# KISS Sorcar — Full Documentation

> Concatenation of all Markdown documentation from https://kisssorcar.github.io/docs/. See https://kisssorcar.github.io/llms.txt for the structured index.

---

<!-- Source: https://kisssorcar.github.io/docs/index.md -->

# KISS Sorcar Documentation

> Pure-Markdown documentation for KISS Sorcar — the free, open-source, local-first, bring-your-own-key general-purpose AI agent framework. These pages are optimized for both humans and LLMs/coding assistants. See also [/llms.txt](https://kisssorcar.github.io/llms.txt) and [/llms-full.txt](https://kisssorcar.github.io/llms-full.txt).

## Contents

- [Overview](https://kisssorcar.github.io/docs/overview.md) — What KISS Sorcar is, the name, and how it compares to Claude Code and Cursor
- [Installation](https://kisssorcar.github.io/docs/installation.md) — Install from source, pipx/uv, API-key configuration, VS Code extension, Docker
- [Client Interfaces](https://kisssorcar.github.io/docs/cli.md) — The `kiss-web` daemon, VS Code extension, web/mobile app, and Python client API
- [Python API Reference](https://kisssorcar.github.io/docs/api.md) — KISSAgent, RelentlessAgent, SorcarAgent, ChatSorcarAgent, WorktreeSorcarAgent, GitWorktreeOps
- [Supported Models](https://kisssorcar.github.io/docs/models.md) — 660-model catalog across 9 provider categories
- [Messaging & Third-Party Agents](https://kisssorcar.github.io/docs/messaging-agents.md) — 32 messaging-channel agents and 9 service agents, plus infrastructure agents, the Govee smart-home CLI, and Muse-auth credential isolation
- [Sample Tasks](https://kisssorcar.github.io/docs/sample-tasks.md) — Ready-to-use example prompts
- [Prompt Tricks](https://kisssorcar.github.io/docs/prompt-tricks.md) — Reusable prompt snippets that boost result quality
- [Tips](https://kisssorcar.github.io/docs/tips.md) — Practical tips for getting the highest-quality work

## Quick Links

- Website: <https://kisssorcar.github.io/>
- Source: <https://github.com/ksenxx/kiss_ai>
- PyPI: <https://pypi.org/project/kiss-agent-framework/>
- Paper: <https://arxiv.org/abs/2604.23822>

## Quick Start

```bash
# Full install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/ksenxx/kiss_ai/main/scripts/install.sh | bash

# Or Python package only (Python 3.13+)
pipx install kiss-agent-framework

# Set at least one model API key
export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY, GEMINI_API_KEY, ...

# Start the daemon that serves the VS Code extension and the web app
kiss-web
```

Then open the KISS Sorcar sidebar in VS Code, or open the remote web app URL shown in the Settings panel. From Python:

```python
from kiss.server import sorcar

result = sorcar.run("What is 2435*234?")
print(result.text)
```

---

<!-- Source: https://kisssorcar.github.io/docs/overview.md -->

# KISS Sorcar Overview

> Open-source general-purpose AI agent for long-horizon tasks and AI discovery.

**KISS Sorcar is a free, simple, local-first, bring-your-own-key AI agent framework.** It runs as a VS Code extension and a browser/mobile web app, both served by a local daemon, and offers a Python client API for scripting tasks. 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. Agents run as daemons hosted by the local server (a standalone `sorcar` terminal command can also run a task without the daemon). Complex AI systems/techniques can be replaced with a paragraph of prompt in KISS Sorcar.

*"Everything should be made as simple as possible, but not simpler." — Albert Einstein*

- **Version:** 2026.9.13
- **License:** Apache-2.0
- **Python:** 3.13+
- **Website:** <https://kisssorcar.github.io/>
- **Source:** <https://github.com/ksenxx/kiss_ai>
- **Paper:** <https://arxiv.org/abs/2604.23822>

## KISS Sorcar vs Claude Code vs Cursor

| Capability | KISS Sorcar | Claude Code | Cursor |
|---|---|---|---|
| Interfaces | VS Code extension + web/mobile app + Python API | CLI + mobile app | Custom VS Code |
| AI Discovery | Yes — simply via prompt | No | No |
| GEPA Prompt Optimization | Yes — simply via prompt | No | No |
| Multiple models from multiple vendors in the same task | Yes — mix OpenAI, Anthropic, Gemini, Together, Z.AI, Moonshot AI, OpenRouter, Claude Code CLI, and Codex CLI | No — Anthropic Claude models only | No — one model per task |
| Primary focus | Quality — rigorous review, end-to-end tests | Speed and developer ergonomics | Speed |
| Core agents lines of code | ~3000 | Unknown | Unknown |
| Models in bundled catalog | 660 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 | Yes — 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 | Yes — `cc/*` and `codex/*` namespaces | N/A | No |
| Messaging and communication channels | 43 third-party agents: 32 messaging channels (Slack, Gmail, Email (IMAP/SMTP), Phone Control, SMS, WhatsApp, Home Assistant, …) plus service agents for GitHub, Notion, Postgres, Brave Search, Firecrawl, and Google Workspace | Slack, mobile Remote Control, and research-preview channels; 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 |
| Scheduled automations | Natural-language cron agent | — | — |
| Wake word for voice interaction | Sorcar | N/A | N/A |

## Unique Features

- **AI discovery and auto research via prompt.** Describe a discovery or optimization goal in a paragraph; Sorcar iterates over ideas, tracks what worked, and doesn't stop until the target metrics are met.
- **GEPA prompt optimization via prompt.** Run the GEPA reflective prompt-evolution algorithm on your own data with a single task prompt.
- **Multi-model orchestration in one task.** Ask one model to implement and another to review — expressed entirely in the prompt, e.g. "Use claude-fable-5 for development and gpt-5.6-sol for review."
- **Dynamic model switching and steering.** A running agent can change its own LLM mid-task (`set_model`), and you can inject user messages into a running agent to steer it on the fly.
- **Git-worktree task isolation.** Each interactive task runs on an isolated git worktree branch that is auto-committed and squash-merged back when it finishes.
- **Voice interaction.** With the `sorcar` wake word, KISS Sorcar behaves like a super-intelligent Alexa; it distinguishes among different speakers.
- **43 third-party agents.** 32 messaging channels — Slack, Gmail, Email (IMAP/SMTP), WhatsApp, SMS, iMessage, Telegram, Discord, Signal, phone control, Home Assistant, and more — plus service agents for GitHub, Notion, PostgreSQL, Brave Search, Firecrawl, and Google Workspace (Calendar, Drive, Docs, Sheets).
- **Pre-run task classification.** A single fast non-agentic model call detects whether a task is a development task that requires creating or editing files — non-development tasks (questions, git-only operations) skip worktree isolation, and simple tasks get a lite system prompt for faster starts. Toggleable in the Settings panel.
- **Persistent agent memory.** On by default: standard Sorcar runs get seven `memory_*` tools (search, pull, read, write, list, refresh, delete) and a memory protocol, so agents recall lessons, preferences, and decisions across tasks. Pages are Markdown files under `~/.kiss/memories` with a SQLite vector index; toggle it in the Settings panel or set `KISS_USE_MEMORY=0`.
- **Credential isolation (Muse auth).** On Linux, credentials for the 22 Muse-supported connectors are isolated by default behind a Meta-Muse-style security boundary: legacy tokens auto-migrate into a local auth daemon's vault on first use (a one-time hand-off of the real credential; plaintext copies are then scrubbed on a best-effort basis), after which the agent process holds only opaque surrogate tokens that the daemon swaps for the real ones at the network edge, and every boundary-routed API request is host-allowlisted, classified read vs. write, and checked against an allow/deny/ask policy with an audit log. Opt out with `KISS_MUSE_AUTH=0`.

## What Is in the Name

**KISS Agent Framework** is a deliberately small agent runtime organized around the KISS principle ("Keep it Simple, Stupid"). The name "Sorcar" pays homage to P. C. Sorcar, the legendary Bengali magician, evoking the idea of an agent that performs feats that appear magical yet are grounded in disciplined engineering. Note: **Sorcar** also means government in Bengali.

## Citation

```bibtex
@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}
}
```

---

<!-- Source: https://kisssorcar.github.io/docs/installation.md -->

# Installing KISS Sorcar

> Install KISS Sorcar from source, as a Python package, as a VS Code extension, or in Docker. Requires Python 3.13+.

## Full Install from Source

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

The installer targets macOS and Linux on `x86_64`, `aarch64`, and `arm64`. It installs or checks the tools needed to run KISS Sorcar and build/install the VS Code extension.

If the Update button in the settings UI fails, run the full installation command again. It will not delete your history.

## Python Package Install

If you only want the Python package (the `kiss-web` daemon, the Python client API, and the messaging-agent entry points):

```bash
pipx install kiss-agent-framework
# or
uv tool install kiss-agent-framework
```

KISS Sorcar requires **Python 3.13+**. The PyPI package name is `kiss-agent-framework` and the daemon entry point is `kiss-web`.

## Configure Model Access

Provide at least one model backend. You can use environment variables such as:

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

You can also set API keys, a custom model endpoint, and custom HTTP headers in the Settings panel of the VS Code extension or web app — useful for local or self-hosted models.

You can register your own models (e.g. a local vLLM/Ollama endpoint or a provider model not in the bundled catalog) in the **Custom Models** section of the Settings panel; entries are stored in `~/.kiss/MY_MODELS.json` and appear in the model picker alongside the bundled catalog.

## 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.

## Docker

To run KISS Sorcar in a Docker container (exposes a VS Code interface in the host machine's browser):

```bash
~/kiss_ai/sorcar-docker
```

## Next Steps

- [Client Interfaces](https://kisssorcar.github.io/docs/cli.md) — the `kiss-web` daemon, chat clients, and Python API
- [Supported Models](https://kisssorcar.github.io/docs/models.md) — pick a model
- [Tips](https://kisssorcar.github.io/docs/tips.md) — get the highest-quality results

---

<!-- Source: https://kisssorcar.github.io/docs/cli.md -->

# KISS Sorcar Client Interfaces

> KISS Sorcar is used through three client interfaces, all served by one local daemon (`kiss-web`): the VS Code extension, the remote web/mobile app, and the Python client API `kiss.server.sorcar.run`. A fourth interface, the `sorcar` terminal command, runs a SorcarAgent directly in the current directory without the daemon.

## The `sorcar` Terminal Command

The standalone `sorcar` command runs a task without the daemon: `sorcar -t "Summarize README.md"` runs an inline task, and `sorcar -f task.txt` runs the file's content as the task (exactly one of `-t`/`-f` is required; see `sorcar --help` for the model, budget, and work-dir flags).

## The `kiss-web` Daemon

The `kiss-web` daemon hosts the agents, chat sessions, and the web app, and services every client command — including config reads/writes, default-model lookup, and the wake-word listener — over its socket. The VS Code extension starts it automatically; you can also manage it yourself:

```bash
# Start the daemon (serves the web app and the extension).
kiss-web

# Pin the daemon's working directory.
kiss-web --workdir "$HOME/projects/my-repo"

# Print the active remote (cloudflared) URL and exit.
kiss-web --url
```

| Flag | Description |
|------|-------------|
| `--workdir` | Working directory for the daemon |
| `--url` | Print the active remote URL and exit |

## VS Code Extension and Web/Mobile App

Open the KISS Sorcar sidebar in VS Code (or the remote web app in a browser) and type or speak your task. The chat interface provides:

- `@` file/folder mentions with ranked project-file completion.
- Per-task **git worktree isolation** — worktrees are pre-warmed in the background for fast task start, with auto-commit and merge on success, or an interactive merge/discard prompt — toggle both in the Settings panel.
- A pre-run **task classifier** (a single fast non-agentic model call — structured output with a plain-text fallback; skipped for `cc/*` and `codex/*` models) that detects whether the task is a development task that requires creating or editing files — non-development tasks (questions, git-only operations) skip worktree isolation, and simple tasks get a lite system prompt for faster starts. Toggleable in the Settings panel.
- A model picker, per-task budget caps, chat history with resume (filtered to the current workspace by default), an agent dashboard (burger menu, bottom-left), and inline rendering of tool-generated images in the chat panels.
- **Persistent agent memory** (on by default): standard Sorcar runs get seven `memory_*` tools (search, pull, read, write, list, refresh, delete) and a memory protocol, so agents recall lessons, preferences, and decisions across tasks (not for Docker runs, `cc/*`/`codex/*` models, runs that drop the built-in toolset, or runs whose `model_config` supplies its own `system_instruction`). Pages are Markdown files under `~/.kiss/memories` with a SQLite vector index (OpenAI embeddings when an `OPENAI_API_KEY` is available, otherwise a fully offline hashed embedder). Toggle it — or point it at a custom directory — in the Settings panel, or set `KISS_USE_MEMORY=0`.
- Wake-word voice chat ("sorcar, …") via the mic button, including steering a running agent by voice.
- Live steering: inject a message into a running agent, or switch its model mid-run. Wrapping the message in `<task>…</task>` tags instead queues it as a follow-up task that runs sequentially after the current task finishes.
- Tab mirroring — every VS Code window and web client opened on the same workspace shows the same tabs with the same contents; the tab bar is scoped to the client's workspace directory, and sub-agents dispatched with `run_agent` open their own tab in the calling workspace.
- Scheduled automations: ask in plain language ("every weekday at 9am, summarize my unread Slack messages") and the built-in cron agent (also runnable from the shell as `kiss-cron`) creates, lists, pauses, resumes, or removes the schedule. A job runs an unattended LLM task or a plain shell command and can deliver its result to an authenticated messaging channel (25 of the 32 channels support delivery, e.g. `telegram:123456`, `email:user@example.com`).
- API keys, a custom model endpoint, custom HTTP headers, budget limits, and the remote-access password, all set in the Settings panel.

The remote web app is the same interface served over a cloudflared tunnel: copy the URL and password from the Settings panel and open it on any device.

## Python Client API

Any Python process can run a task on the daemon with `kiss.server.sorcar.run` and block until it finishes:

```python
from kiss.server import sorcar

result = sorcar.run("Summarize README.md", work_dir="/path/to/repo")
print(result.text, result.success, result.cost, result.tokens, result.steps)

# Continue the same chat (the agent sees the prior task as context):
follow_up = sorcar.run("Now fix the typos you found", chat_id=result.chat_id)
```

Keyword options:

| Option | Description |
|--------|-------------|
| `work_dir` | Working directory for the task; the daemon's default when empty |
| `scope_work_dir` | Workspace-scope directory for the task's tab; the task's working directory when empty |
| `parent_task_id` | Task-history row id of the calling task; non-empty marks the run as a sub-agent of that task (nested tab and history row) — how the `run_agent` tool dispatches |
| `parent_tab_id` | Frontend tab id of the calling task's tab, so the webview knows which tab spawned the sub-agent |
| `model` | Model name; the daemon's selected default when empty |
| `chat_id` | Existing chat session id to continue; a new chat when empty |
| `tools` | Path to a Python file whose `get_tools()` function returns the functions the daemon registers as extra agent tools |
| `system_prompt` | Replace the default system prompt for the run (and its sub-agents) |
| `append_to_system_prompt` | Append text to the system prompt instead of replacing it |
| `append_to_prompt` | Append text to the task prompt |
| `append_basic_tools` | Set `False` to restrict the agent to `finish` plus your `tools` file, dropping the built-in toolset (default `True`) |
| `extension_agent_path` | Run a full Sorcar Extension Agent (SEA) — a Python file that computes the run's parameters and tools on the daemon (see below) |
| `use_worktree` | Run the task in an isolated git worktree (default `True`) |
| `auto_commit` | Auto-commit the task's changes on success (default `True`) |
| `max_budget` | Per-task budget override in USD |
| `model_config` | Per-task model configuration override (custom endpoint / headers) |
| `use_web_tools` | Per-task browser-tool enablement override (maps to the agent's `web_tools` toggle; `None` uses the daemon's configured default — the settings panel's "Use web tools" checkbox) |
| `classify_tasks` | Per-run override of pre-run task classification: `True` forces it on, `False` skips it, `None` (default) uses the daemon's persisted setting — the settings panel's "Classify tasks before running" checkbox |
| `use_memory` | Per-run persistent-memory override: `True` gives the run (and its `run_parallel` sub-agents) the `memory_*` tools plus the memory protocol, `False` withholds them, `None` (default) uses the daemon's default — a non-empty `KISS_USE_MEMORY` environment variable on the daemon process, else the settings panel's "Use persistent memory" checkbox. The memory safety gates (stripped basic tools, Docker runs, `cc/*`/`codex/*` models, a caller `system_instruction`) always win |
| `is_parallel` | Whether the agent may spawn parallel sub-agents (default `True`) |
| `timeout` | Maximum seconds to wait for the task to finish (default `3600`) |
| `stop_on_timeout` | Also stop the task when `timeout` expires; default `False` — the task keeps running |
| `sock_path` | Daemon Unix-domain-socket path override |

The returned `TaskResult` carries `text`, `success`, `cost`, `tokens`, `steps`, `chat_id`, and `task_id`.

## Sorcar Extension Agents (SEAs)

A **Sorcar Extension Agent (SEA)** is a plain Python file whose path you pass as `extension_agent_path` to `sorcar.run()`. The daemon imports the file on every run and calls its top-level `X()` functions — named after `run()`'s parameters — to compute the run's parameters; parameters without a getter keep whatever the caller passed. One file can define the task prompt, system prompt, model, budget, tools, and safety hooks — a complete custom agent.

- **Overridable parameters.** Every `sorcar.run()` parameter except `timeout`, `stop_on_timeout`, `sock_path`, `parent_task_id`, `parent_tab_id`, and `extension_agent_path` itself has a getter named after it: `prompt()`, `work_dir()`, `model()`, `chat_id()`, `system_prompt()`, `tools()`, `use_worktree()`, `auto_commit()`, `max_budget()`, `model_config()`, `if_append_basic_tools()` (overrides `append_basic_tools`), `append_to_system_prompt()`, `append_to_prompt()`, `scope_work_dir()`, `use_web_tools()`, `classify_tasks()`, `use_memory()`, and `is_parallel()`. `use_web_tools()`, `classify_tasks()`, and `use_memory()` return a bool, or `None` to fall back to the daemon's default (the persisted setting — for `use_memory()` a non-empty `KISS_USE_MEMORY` environment variable on the daemon process wins over the stored value).
- **Atomic, type-checked overrides.** Getters run in the daemon process and are re-imported from source on every run. Each return value is type-checked; overrides apply only after every getter succeeds, and a broken getter fails the task with a diagnostic in `TaskResult.text`.
- **Tools, two ways.** `tools()` may return a list of callables — making the script its own tools file — or the path of a separate Python file whose `get_tools()` (or `tools()`) returns the callables. Either way the tools execute in the daemon process; nothing is serialized over the socket. `tools()` overrides (does not append to) the caller's `tools` argument.
- **Hook getters.** `llm_call_hook()` and `tool_call_hook()` return functions with no `run()` equivalent. `llm_call_hook(new_messages)` runs before every LLM call and its return value replaces the outgoing messages; `tool_call_hook(name, args)` runs before every tool call — returning `"OK"` lets the tool execute, any other string suppresses the call and is given to the model as the tool's result.

```python
# guarded_agent.py — veto dangerous shell commands
def veto_destructive(name, args):
    if name == "Bash" and "rm -rf" in str(args.get("command", "")):
        return "Blocked: destructive command"
    return "OK"

def tool_call_hook():
    return veto_destructive
```

The full authoring guide is in [`src/kiss/server/README.md`](https://github.com/ksenxx/kiss_ai/blob/main/src/kiss/server/README.md).

## Skills, MCP Servers, and Customization

- Agent Skills loaded from `~/.kiss/skills`, `<project>/.kiss/skills`, Claude skill directories, `.agents/skills`, and bundled Sorcar skills.
- MCP server discovery from `~/.kiss/mcp.json`, `<project>/.kiss/mcp.json`, and `<project>/.mcp.json`; OAuth tokens are persisted under `~/.kiss/mcp_auth/`. A curated catalog of privacy-first MCP connectors (fetch, time, memory, GitHub, Slack, Google Workspace, WhatsApp, …) ships in [`connectors/`](https://github.com/ksenxx/kiss_ai/blob/main/connectors/README.md) with `enable.py`/`verify.py` CLIs.
- "Tricks" (inject-instruction) entries are the concatenation of two `## Trick`-sectioned Markdown files: `~/.kiss/MY_INJECTION.md` (your personal tricks, auto-created on first read and never overwritten thereafter) and the bundled `src/kiss/INJECTIONS.md`, read directly from the package so every upgrade delivers the latest bundled tricks. Edit `~/.kiss/MY_INJECTION.md` to customize; your tricks are listed first.
- Welcome-screen sample-task chips are the concatenation of `~/.kiss/MY_TASK_TEMPLATES.md` (your personal tasks) and the bundled `src/kiss/SAMPLE_TASKS.md`.

---

<!-- Source: https://kisssorcar.github.io/docs/api.md -->

# KISS Sorcar Python API Reference

> The core Python classes of the KISS Agent Framework (`kiss-agent-framework` on PyPI): KISSAgent, RelentlessAgent, SorcarAgent, ChatSorcarAgent, WorktreeSorcarAgent, and GitWorktreeOps. Auto-generated from source; the canonical version lives at <https://github.com/ksenxx/kiss_ai/blob/main/API.md>.

## `kiss.core.kiss_agent` — Core KISS agent with native function calling

### `class KISSAgent(Base)`

A KISS agent using native function calling.

**Constructor:** `KISSAgent(name: str) -> None`

- **run** — Runs the agent's main ReAct loop to solve the task. Run-to-completion models (`cc/*`, `codex/*`) skip the ReAct loop entirely: the whole task is handed to the CLI agent in one `generate()` call and its final output is returned; `tools` are registered but never exposed to such a model — it uses its own native tools.

  ```python
  run(model_name: str, prompt_template: str, arguments: dict[str, str] | None = None,
      system_prompt: str = '', tools: list[Callable[..., Any]] | None = None,
      is_agentic: bool = True, max_steps: int | None = None, max_budget: float | None = None,
      model_config: dict[str, Any] | None = None, printer: Printer | None = None,
      verbose: bool | None = None, attachments: list[Attachment] | None = None,
      print_prompts: bool = True,
      llm_call_hook: Callable[[list[dict[str, Any]]], list[dict[str, Any]]] | None = None,
      tool_call_hook: Callable[[str, dict[str, Any]], str] | None = None) -> str
  ```

  Key parameters: `model_name` (LLM to use), `prompt_template` + `arguments` (task prompt with substitutions), `tools` (callables exposed to the model; a built-in `finish` tool is always added), `max_steps` (default 10000), `max_budget` (default $10), `attachments` (images/PDFs for the initial prompt), `llm_call_hook` (called before every LLM call with the new messages about to be sent; its return value replaces them), `tool_call_hook` (called before every tool call with the tool's name and arguments; returning `"OK"` lets the tool execute, any other string suppresses the call and is returned to the model as the tool's result). Returns the result string of the agent's task.

- **finish** — `finish(result: str) -> str`. The agent must call this with the final answer.

## `kiss.agents.sorcar.relentless_agent` — Auto-continuation for long tasks

### `class RelentlessAgent(Base)`

Base agent with auto-continuation across multiple sub-sessions for long-horizon tasks.

- **perform_task** — `perform_task(tools, attachments=None) -> str`. Executes the task with auto-continuation across sub-sessions; returns a YAML string with `success` and `summary` keys.
- **run** — Full signature adds: `model_name`, `prompt_template`, `arguments`, `system_prompt`, `max_steps` (per sub-session), `max_budget` (USD), `model_config`, `work_dir`, `printer`, `max_sub_sessions`, `docker_image` (run tools inside a container), `verbose`, `tools`, `attachments`, `llm_call_hook`, `tool_call_hook` (both installed on every per-session executor `KISSAgent`). Returns YAML with `success` and `summary`.
- **finish** — `finish(success: bool, is_continue: bool = False, summary_in_html: str = '') -> str`. The summary is always HTML (Markdown/plain-text input is converted). `is_continue=True` pauses an incomplete task so it resumes in a new sub-session.

## `kiss.agents.sorcar.sorcar_agent` — Coding + browser automation

### `class SorcarAgent(RelentlessAgent)`

Agent with both coding tools and browser automation for web + code tasks.

**Constructor:** `SorcarAgent(name: str) -> None`

- **classify_task_for_run** — `classify_task_for_run(model_name, task, model_config=None, enabled=None) -> TaskClassification | None`. Classify the task now (one lightweight non-agentic LLM call) and pre-seed the verdict for the coming run, so an external driver can know the run's effective worktree mode before calling `run` — the verdict decides worktree gating and lite-vs-full system prompt selection. `enabled` is a per-run override of the persisted `classify_tasks` setting (`True` forces classification, `False` skips it, `None` follows the config); the `KISS_DISABLE_TASK_CLASSIFIER` environment kill switch wins over any override. Returns `None` when classification is disabled or failed.
- **run** — Adds on top of `RelentlessAgent.run`: `web_tools: bool = True` (set False for terminal-only), `is_parallel: bool = True` (enables the `run_parallel` tool for spawning parallel sub-agents), `current_editor_file` (path appended to the prompt), `ask_user_question_callback` (collects a text response from the user), `base_system_prompt` (replaces the default system prompt for this agent and its `run_parallel` sub-agents), `append_basic_tools` (set False to run with only `finish` plus the caller's tools), `llm_call_hook`, `tool_call_hook` (forwarded to every sub-session's `KISSAgent`), `use_memory: bool | None = None` (per-run persistent-memory toggle: `True` gives the run the `memory_*` tools and the memory protocol prompt block, `False` withholds them, `None` follows the `KISS_USE_MEMORY` environment variable / stored setting; forwarded to every `run_parallel` sub-agent, and a boolean never bypasses the memory hard gates — stripped basic tools, Docker runs, `cc/*`/`codex/*` models, a caller-supplied `model_config["system_instruction"]`). Returns YAML with `success` and `summary`.

### Module helpers

- **`auto_commit_changes(commit_dir, user_prompt, message_fn, notify_fn=None, task_result=None) -> bool`** — Stage all changes, generate a commit message (typically via an LLM), and commit. Re-stages just before committing so late-arriving files are included. Falls back to a generic message if `message_fn` raises. Returns True if a commit was created.
- **`run_tasks_parallel(tasks, max_workers=None, model_name=None, work_dir=None, printer=None, totals_out=None, max_budget=None, model_config=None, usage_monitor=None, parent_agent=None, chat_id='', parent_tab_id='', base_system_prompt='', system_prompt_suffix='', web_tools=True, use_memory=None) -> list[str]`** — Execute multiple SorcarAgent tasks concurrently with a thread pool; each task gets its own `ChatSorcarAgent`. `web_tools=False` denies each sub-agent the browser tools, so a parent running without web tools spawns children that cannot re-acquire them. `use_memory` forwards a parent run's persistent-memory override to each sub-agent's `run` (`None`, the default, lets each sub-agent fall back to the environment/config default). Returns YAML result strings in the same order as `tasks`.

## `kiss.agents.sorcar.chat_sorcar_agent` — Chat-session persistence

### `class ChatSorcarAgent(SorcarAgent)`

SorcarAgent with chat-session state management.

- **chat_id** *(property)* — Current chat session ID ("" means new session).
- **new_chat()** — Reset to a new chat session.
- **resume_chat_by_id(chat_id)** — Resume a chat session by stable identifier.
- **resume_from_task_id(task_id)** — One-shot seed of the next prompt's context from a task's parent chain.
- **build_chat_prompt(prompt) -> str** — Load chat context and prepend previous tasks/results to the prompt.
- **`run(prompt_template='', **kwargs) -> str`** — Run with chat-session context: loads prior context, persists the new task, runs the underlying agent, and saves the result to history.

## `kiss.agents.sorcar.git_worktree` — Git worktree operations

### `class GitWorktree` — Immutable snapshot of a pending worktree task.

### `class MergeResult(enum.Enum)` — Outcome of a merge operation (`SUCCESS` / `CONFLICT`).

### `class GitWorktreeOps` — Stateless helper with all git worktree operations

Highlights (all methods take explicit `repo`/`wt_dir` paths):

- `discover_repo(path)`, `current_branch(repo)`, `head_sha(wt_dir)`, `branch_exists(repo, branch)`
- `create(repo, branch, wt_dir)`, `remove(repo, wt_dir)`, `prune(repo)`, `cleanup_partial(repo, branch, wt_dir)`
- `stage_all(wt_dir)`, `commit_all(wt_dir, message)`, `commit_staged(wt_dir, message, no_verify=False)`, `staged_diff(wt_dir)`
- `has_uncommitted_changes(wt_dir)`, `status_porcelain(wt_dir)`
- `checkout(repo, branch)`, `stash_if_dirty(repo)`, `stash_pop(repo)`, `delete_branch(repo, branch)`
- `squash_merge_branch(repo, branch)`, `squash_merge_from_baseline(repo, branch, baseline)` — squash-merge a task branch (or only the agent's changes after a baseline commit) into HEAD, returning `MergeResult`
- `copy_dirty_state(repo, wt_dir)`, `save_baseline_commit` / `load_baseline_commit`, `save_original_branch` / `load_original_branch`
- `ensure_excluded(repo)` — adds `.kiss-worktrees/` to the repo-local git exclude
- `ensure_scratch_merge_driver(repo)` — installs a merge driver that auto-resolves agent scratch files (e.g. `PROGRESS.md`)

### Module helpers

- **`repo_lock(repo) -> threading.RLock`** — Per-repo re-entrant lock serializing multi-step git operations across concurrent tabs.
- **`strip_worktree_suffix(path) -> str`** — Strip the ephemeral `.kiss-worktrees/kiss_wt-<slug>` suffix so persisted paths always point at the parent repo.

## `kiss.agents.sorcar.worktree_sorcar_agent` — Isolated task branches

### `class WorktreeSorcarAgent(ChatSorcarAgent)`

SorcarAgent that isolates every task in a git worktree.

- **`run(prompt_template='', **kwargs) -> str`** — Creates a new worktree and branch, redirects `work_dir` into the worktree, and delegates to `ChatSorcarAgent.run()`. Any previously pending branch from an earlier run is retired first: finished work is auto-committed and squash-merged into its original branch (kept in git for manual resolution when that merge fails or conflicts), while a failed or stopped run's work is committed only to its own `kiss/wt-*` branch, never touching the original. Falls back to direct execution when `use_worktree=False`, when the pre-run task classifier is enabled and reports the task is not a development task (the verdict likewise forces a worktree when it reports `is_development=True`), when `work_dir` is not in a git repo, when the repo has no commits, or when HEAD is detached.
- **merge() -> str** — Merge the task branch into the original branch. Idempotent; auto-commits uncommitted worktree changes and stashes/restores user edits on main.
- **discard() -> str** — Throw away the task branch and worktree, checkout the original branch. Idempotent.
- **leave_as_is() -> str** — Detach from the pending worktree, leaving the branch, directory, and uncommitted changes untouched on disk (the "Do nothing" button of the post-task worktree bar); a preserve-for-review marker keeps future processes from silently publishing it.
- **new_chat()** — Reset to a new chat session, retiring any pending worktree first (finished work is auto-committed and squash-merged; failed or stopped work is committed only to its own branch).

---

<!-- Source: https://kisssorcar.github.io/docs/models.md -->

# Models Supported by KISS Sorcar

> KISS Sorcar ships a catalog of **660 models** across **9 provider categories**, with built-in prices, context lengths, and capability flags (`fc` function calling, `gen` generation, `emb` embedding).

The machine-readable source of truth is [`src/kiss/core/models/MODEL_INFO.json`](https://raw.githubusercontent.com/ksenxx/kiss_ai/main/src/kiss/core/models/MODEL_INFO.json) in the source repository. Models are grouped by the provider that routes them (i.e., whose API key or CLI serves the model); open-weight `openai/gpt-oss-*` and `google/gemma-*` models are served via Together AI.

## Provider Categories

| Provider category | Catalog entries |
|---|---:|
| OpenAI | 102 |
| Anthropic | 14 |
| Gemini | 24 |
| Together AI | 102 |
| Z.AI | 8 |
| Moonshot AI | 10 |
| OpenRouter | 378 |
| Claude Code CLI (`cc/*`) | 14 |
| Codex CLI (`codex/*`) | 8 |

## Capability Totals

- **640** generation-capable models
- **481** function-calling-capable models
- **11** embedding models

## Configuring Model Access

Set one or more environment variables:

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

Or point at any OpenAI-compatible local/self-hosted endpoint by setting a custom model endpoint and headers in the Settings panel of the VS Code extension or web app (e.g. `http://localhost:8000/v1` with an `Authorization: Bearer xxx` header).

## Model Namespaces

- Plain names (e.g. `claude-sonnet-4-6`, `gpt-4.1`) map to the native provider APIs.
- `openrouter/...` routes through OpenRouter (378 entries, including `openrouter/~vendor/model-latest` aliases that always track the newest model).
- `cc/haiku`, `cc/sonnet`, `cc/opus` run on top of the Claude Code CLI.
- `codex/...` (e.g. `codex/gpt-5.6-sol`) run on top of the Codex CLI.

## Multi-Model Workflows

KISS Sorcar can mix models from multiple vendors within a single task, purely via the prompt:

```
Use claude-fable-5 model for all tasks including software development.
Use gpt-5.6-sol (not codex) for thorough review and debugging of the work
done by the other model.
```

A running agent can also switch its own model mid-task with the `set_model` tool, and you can steer running agents by injecting messages on the fly.

## Choosing a Default

When no model is selected, KISS Sorcar defaults to the best available model for the API keys you have configured.

The full per-model list (all 660 entries) is in the [project README](https://github.com/ksenxx/kiss_ai#models-supported).

---

<!-- Source: https://kisssorcar.github.io/docs/messaging-agents.md -->

# Messaging & Third-Party Agents

> KISS Sorcar includes 43 third-party agents that act on messaging services, mailboxes, devices, and web services on your behalf — 32 messaging-channel agents and 9 service agents — plus infrastructure agents and a Govee smart-home CLI.

## The 32 Messaging-Channel Agents

- BlueBubbles
- DingTalk
- Discord
- Email (IMAP/SMTP)
- Feishu
- Gmail
- Google Chat
- Home Assistant
- iMessage
- IRC
- LINE
- Matrix
- Mattermost
- Microsoft Teams
- Nextcloud Talk
- Nostr
- ntfy
- Phone Control
- QQ
- Signal
- SimpleX
- Slack
- SMS
- Synology Chat
- Telegram
- Tlon
- Twitch
- Webhook
- WeCom
- WeiXin
- WhatsApp
- Zalo

## The 9 Service Agents

Nine service agents give Sorcar authenticated API tools for productivity and data services:

- Brave Search (`kiss-brave`)
- Firecrawl (`kiss-firecrawl`)
- GitHub (`kiss-github`)
- Google Calendar (`kiss-gcal`)
- Google Docs (`kiss-gdocs`)
- Google Drive (`kiss-gdrive`)
- Google Sheets (`kiss-gsheets`)
- Notion (`kiss-notion`)
- PostgreSQL (`kiss-postgres`)

In a chat task, just say what you want ("send 'running late' to Alice on WhatsApp", "list my open GitHub PRs") — Sorcar dispatches the matching agent through its `run_agent` tool. Each agent also has its own CLI entry point (`kiss-slack`, `kiss-gmail`, `kiss-whatsapp`, ...) for running tasks directly from the shell.

## Infrastructure Agents

Two infrastructure agents round out the set: an **A2A agent** (`kiss-a2a`) exposing Sorcar over the agent-to-agent protocol, and an **OpenAI-compatible server** (`kiss-oai`) that serves Sorcar behind an OpenAI-style HTTP API.

These agents live in `src/kiss/agents/third_party_agents/` in the source repository.

## Smart Home

KISS Sorcar also ships a **Govee smart-home CLI** for controlling IoT lights (on/off, brightness, color, and color temperature) via the Govee Developer API.

## Credential Isolation (Muse Auth)

On Linux, credentials for the 22 Muse-supported connectors (the six Google services — Google Chat's service-account mode excepted — plus Slack, GitHub, Notion, Discord, Home Assistant, Firecrawl, Brave Search, ntfy, Govee, LINE, Mattermost, Nextcloud Talk, Synology Chat, Twitch, Zalo, and BlueBubbles) are isolated by default behind a Meta-Muse-style security boundary: legacy tokens auto-migrate into a vault owned by a local auth daemon on first use (a one-time hand-off of the real credential; plaintext copies are then scrubbed on a best-effort basis), the agent process holds only opaque surrogate tokens that the daemon swaps for the real ones at the network edge, and every boundary-routed API request is host-allowlisted, classified read vs. write, and checked against an allow/deny/ask policy with an audit log. Reads are allowed by default; writes ask for a grant. Manage it with `python -m kiss.agents.third_party_agents.muse_auth` (`status`, `enroll`, `grant`, `audit`, and an `export` command that reads a vaulted credential back out for recovery); opt out with `KISS_MUSE_AUTH=0`.

## Example Prompts

```text
Authenticate slack workspace <<workspace name>>.
```

```text
Authenticate Gmail [, or gcal, gdrive, gdoc, gsheets]?
```

```text
Can you send "Hello from Sorcar!" to 1-800-999-9999?
```

```text
Can you check my Gmail every hour and ping me on Slack if there is any important
email that needs my immediate attention?
```

See [Sample Tasks](https://kisssorcar.github.io/docs/sample-tasks.md) for more ready-to-use prompts.

---

<!-- Source: https://kisssorcar.github.io/docs/sample-tasks.md -->

# Sample Tasks for KISS Sorcar

> Ready-to-use example prompts shipped with KISS Sorcar. Replace the `<<...>>` placeholders with your own values. In the VS Code extension these appear as welcome-screen chips. The bundled tasks live in [`src/kiss/SAMPLE_TASKS.md`](https://github.com/ksenxx/kiss_ai/blob/main/src/kiss/SAMPLE_TASKS.md); you can add your own at `~/.kiss/MY_TASK_TEMPLATES.md`.

## Code Understanding & Editing

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

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

## Messaging

```text
Authenticate slack workspace <<workspace name>>.
```

```text
Authenticate Gmail [, or gcal, gdrive, gdoc, gsheets]?
```

```text
Can you check my Gmail every hour and ping me on Slack if there is any important email that
needs my immediate attention?
```

```text
Authenticate iMessage.
```

```text
Can you send "Hello from Sorcar!" to 1-800-999-9999?
```

## Fact-Checking & Security Review

```text
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 the internet extensively and do not believe what people
say -- verify it yourself. Do not hesitate to download code and run it to validate results. For
security vulnerabilities, create a POC and test it. Create a report.
```

## AI Discovery

```text
Sorcar for AI Discovery: Can you AI-discover the lightest and fastest AI model that will give
the best accuracy and recall on the data at <</path/to/data>> at the lowest price? Use 'modal'
CLI to train your models on GPUs and evaluate if needed. The total budget for Modal.com is
$ 1,000. Do not STOP until accuracy/recall reaches 99% and the model's price per query is less
than $0.50. Create a report.
```

## Software Optimization

```text
Sorcar for Optimization: Can you run the command <<command>> and optimize it with respect to the
following metrics: <<speed, accuracy, recall, cost>>. Then use AI discovery to optimize. You can
add a diagnostic code that prints metrics, such as running time, at a finer granularity. 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>>. Create a report.
```

## GEPA Prompt Optimization

```text
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-fable-5? 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 a 50% dev set and a 50% val set.

RUN_GEPA: Sample 100 data points from the val set and call it the sval set. Maintain a Pareto
frontier in the folder ./pareto, with 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 data
points (ids) from the sval set that were correctly predicted by the prompt. When you add a node
to the Pareto frontier, make sure that the list of correctly predicted data points is not a
subset of or equal to an existing list of data points 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 data
points is a subset of or equal to the list of data points 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 data points 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 data points, analyze and reflect on the
      trajectory events of the agent on those data points available at ~/.kiss/sorcar.db and
      propose a new prompt that will fix the mistakes made by the agent on data points
      incorrectly predicted
   d. If the agent predicts correctly on the minibatch, then evaluate it on the sval set and
      create the list of data points on which the agent with the new prompt predicts correctly.
   e. Add the new prompt and the list of data points to the Pareto frontier

1. Pick two nodes from the Pareto frontier randomly with the remaining probability.
   a. Sample a minibatch of 5 data points 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 data points to the Pareto frontier

1. 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.

At each step, keep track of the best prompt, which has the maximum number of successfully
predicted data points, in ./pareto/optimal.md. MAKE SURE THAT YOU DO NOT DO REWARD HACKING OR
CHEATING IN THE AGENT YOU ARE IMPLEMENTING TO FIT THE 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 cannot improve the accuracy and recall after three consecutive
rollouts. Use gpt-5.6-sol model (not codex) for a thorough review of the work done at every
step by the other model.
```

See also [Prompt Tricks](https://kisssorcar.github.io/docs/prompt-tricks.md) and [Tips](https://kisssorcar.github.io/docs/tips.md).

---

<!-- Source: https://kisssorcar.github.io/docs/prompt-tricks.md -->

# Prompt Tricks

> Reusable prompt snippets ("tricks") that boost KISS Sorcar result quality. In the VS Code extension these appear under the "Tricks" button; they are the concatenation of two `## Trick`-sectioned Markdown files: `~/.kiss/MY_INJECTION.md` (your personal tricks, auto-created on first read and never overwritten thereafter) and the bundled [`src/kiss/INJECTIONS.md`](https://github.com/ksenxx/kiss_ai/blob/main/src/kiss/INJECTIONS.md), read directly from the package so every upgrade delivers the latest bundled tricks. Edit `~/.kiss/MY_INJECTION.md` to customize; your tricks are listed first. Append one or more to your task prompt.

## Multi-Model Quality

```text
Use 'claude-fable-5' model for all tasks, including software development. Use 'gpt-5.6-sol'
(not codex) using `run_parallel` tool for a thorough read-only review and debugging of the
other model's work. Thoroughly check whether the other model has missed any code or wiring or
introduced any bugs. Use at most 50% of the task budget in gpt-5.6-sol for reviewing and
debugging, and ask the model not to invent new problems. Use the model names literally without
hallucinating new model names.
```

## Bug Fixing

```text
Reproduce any violation of the invariant by writing end-to-end tests with 100% coverage. Then
fix the issue.
```

## Instructions from a File

```text
Can you use the instructions in the file @ to perform the task?
```

## Git

```text
Can you check the following message for a merge conflict and help me fix it?
```

## Autonomous Browser Authentication

```text
You MUST use the user's default browser and computer use to authenticate using claude-fable-5-1
as the model. Do all the steps on the user's behalf and ask the user's help ONLY if you are
stuck on login or captcha.
```

## Multi-Model Quality (GPT-6 Astra Review)

```text
Use 'claude-fable-5' model for all tasks, including software development. Use 'gpt-6-astra'
(not codex) using `run_parallel` tool for a thorough read-only review and debugging of the
other model's work. Thoroughly check whether the other model has missed any code or wiring or
introduced any bugs. Use at most 50% of the task budget in gpt-6-astra for reviewing and
debugging, and ask the model not to invent new problems. Use the model names literally without
hallucinating new model names.
```

## Multi-Model Quality (Kimi K3)

```text
Use 'openrouter/moonshotai/kimi-k3' model for all tasks, including software development. Use
'gpt-5.6-sol' (not codex) using `run_parallel` tool for a thorough read-only review and
debugging of the other model's work. Thoroughly check whether the other model has missed any
code or wiring or introduced any bugs. Use at most 50% of the task budget in gpt-5.6-sol for
reviewing and debugging, and ask the model not to invent new problems. Use the model names
literally without hallucinating new model names.
```

## Self-Improving Model Routing

```text
If ./ROUTING.md exists, use the instructions in the file for model routing. Otherwise, use the
best model from ~/.kiss/MODEL_INFO.json for various subtasks. Search the internet extensively
to figure out which model is best yet cheap for each subtask. Here are some hints, but the
internet has better knowledge: claude-fable-5 and openrouter/moonshotai/kimi-k3 — best for SWE
work; gpt-5.6-sol — best for reviewing; openrouter/qwen/qwen3.8-max, openrouter/x-ai/grok-4.6,
openrouter/z-ai/glm-5.3, openrouter/deepseek/deepseek-v4-pro-0813 — for SWE tasks when
budget is low; and gpt-5.6-luna and openrouter/deepseek/deepseek-v4-pro-0813 for review when
budget is low. Irrespective of whether ./ROUTING.md exists or not, after the task completes,
based on your experience in completing the task, create or update the model routing strategy
(as text) in ./ROUTING.md that reduces token cost while not degrading the quality of the work.
```

See also [Sample Tasks](https://kisssorcar.github.io/docs/sample-tasks.md) and [Tips](https://kisssorcar.github.io/docs/tips.md).

---

<!-- Source: https://kisssorcar.github.io/docs/tips.md -->

# Tips for KISS Sorcar

> Practical tips for getting the highest-quality work from KISS Sorcar. These mirror the built-in tips shipped in [`src/kiss/TIPS.md`](https://github.com/ksenxx/kiss_ai/blob/main/src/kiss/TIPS.md).

## Update Button in the Settings

If the Update button in settings fails, run the full installation command again. It will not delete your history.

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

## Chat in the Editor or in the Sidebar

In VS Code, you can run KISS Sorcar in two modes: full editor mode, where the chats open as editor tabs, and non-editor mode, where the chats open in the sidebar. You can switch between the two modes by selecting/deselecting the "Chat in the editor" option on the KISS Sorcar settings page.

## Task Classifier

KISS Sorcar now uses a quick task classifier to determine whether the task should run with git worktree mode and whether the task is complex or simple. You can toggle the task classifier in the settings by selecting/deselecting the option "Classify tasks before running".

## Sorcar Extension Agents (SEAs)

A **Sorcar Extension Agent (SEA)** is a plain Python file that defines a complete custom agent: its top-level `X()` functions — named after `sorcar.run()`'s parameters — compute the run's task prompt, system prompt, model, budget, tools, and safety hooks. Pass the file's path as `extension_agent_path` to `sorcar.run()` and the daemon imports it on every run. All third-party agents, such as the Slack and Gmail agents, are implemented in KISS Sorcar as SEAs. See the "Sorcar Extension Agents (SEAs)" section in the [README](https://github.com/ksenxx/kiss_ai#sorcar-extension-agents-seas) for a full example, and the detailed SEA guide at [`src/kiss/server/README.md`](https://github.com/ksenxx/kiss_ai/blob/main/src/kiss/server/README.md).

## Prompt KISS Sorcar Like the Developer of KISS Sorcar

**Always write precise less than 10 sentence prompts.** Long prompts confuse models. **Do not plan ahead of time.** Let KISS Sorcar plan dynamically, which is always better than AI-written static plans. The waterfall model doesn't work well in contemporary times.

See the commit messages at <https://github.com/ksenxx/kiss_ai> which include the prompts used by the developer of KISS Sorcar.

**No need to use generic skills for debugging, code review, etc.** Frontier models have been trained on those skills.

## Get the Highest Quality Work

- Add both `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` in the Settings panel.
- Add the following text to your prompt:

```text
Use 'claude-fable-5-1' model for all tasks, including software development. Use 'gpt-5.6-sol'
(not codex) using `run_parallel` tool for a thorough read-only review and debugging of the
other model's work. Thoroughly check whether the other model has missed any code or wiring
or introduced any bugs. Use at most 50% of the task budget in gpt-5.6-sol for reviewing and
debugging, and ask the model not to invent new problems. Use model names literally; don't
hallucinate new model names.
```

## Ask for Task Status Anytime

To get the status of a task, open a new chat and ask KISS Sorcar what the status is of the task being done…

## Novel Features: `set_model` and Steering-on-the-Fly

You can **instantaneously inject a user message** into a running agent and make the agent take the message into account in the rest of its execution.

Moreover, while an agent is running, you can ask it to **dynamically change its model** for the rest of the agent's execution.

These are unique features of KISS Sorcar. These two **IPs (intellectual properties)** make KISS Sorcar super powerful for multi-model reasoning and dynamic steering of tasks running for hours to days. You can describe model-routing intelligence in a few sentences.

## Voice Chat with KISS Sorcar

If you have an **`OPENAI_API_KEY`**, with the **sorcar** wake word, KISS Sorcar starts behaving like a super-intelligent **Alexa**.

```text
Speak 'sorcar', your task ...
```

Click the **mic** button below the chat input box if it is grey and wait for it to start pulsing blue. Speak "sorcar" followed by your task, and KISS Sorcar will automatically run the task and tell you the results using its own voice. The voice interface distinguishes among different speakers.

You can also steer the agent's execution and ask for status when an agent is running using voice.

## Use the KISS Sorcar Remote Web/Mobile App

Go to the Settings panel and copy the URL at the top. This URL contains a message showing the latest cloudflared URL where you can find the KISS Sorcar web app. Send the URL from the Settings page to your mobile device. Also view or set the remote password on the Settings page. You can SMS, Slack, or email the URL to the mobile device.

Open the URL in a browser on the mobile device and enter your remote password. You will see your familiar Codex-like chat interface.

## Run Tasks from Python Scripts

Any Python process can launch a task on the running KISS Sorcar daemon and block until it finishes:

```python
from kiss.server import sorcar

result = sorcar.run("Summarize README.md", work_dir="/path/to/repo")
print(result.text, result.success, result.cost)

# Continue the same chat with the prior task as context:
sorcar.run("Now fix the typos you found", chat_id=result.chat_id)
```

You can also pass a Python file of extra tools via `tools="/path/to/my_tools.py"`.

## Run KISS Sorcar in a Docker Container

Just run:

```bash
sorcar-docker
```

It runs KISS Sorcar in a Docker container and exposes a VS Code interface in the host machine's browser.

## Run KISS Sorcar on a Server via SSH

Just run:

```bash
rsorcar username@ip_address
```

## Fix a git Merge Conflict

Then run the following task:

```text
Can you check the following merge conflict message and help me fix it? <<copy_paste_the_conflict_message_from_the_chat>>
```

## No Need to Use a Shell

Just type or speak your shell command in the chat input textbox.

## AI Discovery and Auto Research

All you need to do is use a variant of the following prompt with KISS Sorcar:

```text
Can you AI discover the lightest and fastest AI model that will give >95% accuracy and
recall on the data at <</path/to/data>> at the cost of $0.25 per query? Use 'modal' CLI to
train your models on GPUs and evaluate if needed. Your total budget for Modal.com is $1,000.
Experiment with a smaller data subset and fewer model parameters to run experiments quickly,
then extrapolate. Do not STOP until you reach the goals. Create a detailed report.
```

## AI Optimization of Software and AI Systems

All you need to do is use a variant of the following prompt with KISS Sorcar:

```text
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>> for the following metrics: <<speed, accuracy,
recall, cost>>. Then use AI discovery to optimize. You may add diagnostic code that prints
metrics, such as running time, at a finer granularity. Don't forget to remove the diagnostic
code after optimization is complete. You MUST NOT STOP until the metrics achieve the
following values: <<give_concrete_values_for_metrics>>. Create a report.
```

## More Prompt Examples for Connecting to Slack, SMS, Gmail…

See them on the welcome page when you create a new chat. Click on them to copy them to the chat input textbox.

## Useful Promptlets

Click on the "Inject Promptlet" button below the chat input textbox to insert a useful promptlet into your prompt.

## Agent Dashboard and History

Click the burger menu button in the bottom-left corner to see all agents in KISS Sorcar, along with various stats and filters, including running and failed tasks. It is an agent dashboard.

## Settings

Click on the settings button in the "..." menu. Use the Settings interface to get the URL for the remote web/mobile app, set the remote web app access password, set the budget limit per task, set the working directory, and set various API keys and a custom model endpoint.

## Use Optimized Multi-Model Routing to Save Cost or Improve Quality

Add the following text to your prompt:

```text
If ./ROUTING.md exists, use the instructions in the file for model routing. Otherwise, use
the best model from ~/.kiss/MODEL_INFO.json for various subtasks. Search the internet
extensively to figure out which model is best yet cheap for each subtask. Here are some
hints, but the internet has better knowledge: claude-fable-5 and
openrouter/moonshotai/kimi-k3 — best for SWE work; gpt-5.6-sol — best for reviewing;
openrouter/qwen/qwen3.8-max, openrouter/x-ai/grok-4.6, openrouter/z-ai/glm-5.3,
openrouter/deepseek/deepseek-v4-pro-0813 — for SWE tasks when budget is low; and
gpt-5.6-luna and openrouter/deepseek/deepseek-v4-pro-0813 for review when budget is low.
Irrespective of whether ./ROUTING.md exists or not, after the task completes, based on your
experience in completing the task, create or update the model routing strategy (as text) in
./ROUTING.md that reduces token cost while not degrading the quality of the work.
```
