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

KISS Sorcar

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.

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

Features: the complete feature inventory, checked against the source tree, is in FEATURES.md.

KISS Sorcar vs Claude Code vs Cursor

Terminal-Bench 2.0: KISS Sorcar vs Pi, Codex CLI, and Claude Code

The HarnessTax study (Pan, Yang, Arabzadeh, Chiang, Stoica, Zaharia; UC Berkeley and Arena Intelligence) holds the model fixed, swaps the harness between Claude Code, Codex CLI, and Pi, and finds that the harness moves cost far more than it moves what gets solved. We added KISS Sorcar to their Terminal-Bench 2.0 table: the same 30 sampled tasks, the same seven models, three attempts per task, graded by the official Terminal-Bench 2.0 verifier. For the benchmark the general-purpose material was stripped from the system prompt, leaving 727 words of coding rules (papers/kisssorcar/evidence/tb2_prompt.txt) instead of the 3,851 words of the full SYSTEM.md. Averaged over the seven models, KISS Sorcar solved 75.6% of attempts; Pi 70.0%, Codex CLI 65.7%, Claude Code 65.1%, with the best point estimate on every one of the seven models. Full write-up: The Harness Tax, Audited; method and intervals: the paper, Section 5.

Terminal-Bench 2.0, the study's 30-task sample, three attempts per task: percentage of attempts solved and cost per attempt in USD. KISS Sorcar: 630 attempts run on 25 September 2026, no turn cap, $50 budget per attempt, providers' default request parameters. The other three columns are the study's published numbers (100-turn cap, high reasoning effort, priced on a 1 September list). Bold marks the best point estimate per row.

Thirty tasks is a small sample: the pooled 95% interval over tasks, 63.8 to 85.9, contains all three published means, and the comparison with the published table also differs in date, price list, turn cap, and prompt. So we reran Pi ourselves, paired, on the same model and the same tasks:

• Study's 30 tasks, Claude Fable 5. Harbor's Pi agent (Pi 0.87.1) at the study's high-effort setting, no turn cap, no wall-clock limit, three attempts per task, priced with the same table as ours. Pi solved 68.9% of attempts at $1.45 and 14.5 turns per attempt; KISS Sorcar solved 80.0% at $1.50 and 15.3 turns. Resampling tasks jointly for both harnesses, the gap is +11.1 points in KISS Sorcar's favor, 95% interval +3.3 to +20.0, for five cents more per attempt (interval −$0.71 to +$0.70). KISS Sorcar has the higher task mean on 7 tasks, Pi on none, and 23 are ties. All three Pi attempts on feal-linear-cryptanalysis died with API errors; without that task the gap is +8.0 points (sign test p = 0.031).
• The 59 tasks the study did not sample. The same frozen prompt on Claude Fable 5 solved 79.1% of attempts (79.4% over all 89 tasks), so the sampled-task result is not an artifact of tuning on the sample. Pi on 57 of those tasks (two qemu tasks were dropped because the verifier did not score the two harnesses alike) solved 71.9% at $1.00 and 12.3 turns; KISS Sorcar solved 82.5% at $1.63 and 17.3 turns. The paired gap is +10.5 points, interval +2.9 to +18.7 (15 tasks to 3, 39 ties, p = 0.008); here KISS Sorcar paid 63 cents more per attempt.

What to keep in mind: only Pi was rerun, on one model, at high effort with its own prompt and no budget cap; the pooled seven-model comparison changes effort, turn cap, and date at once, and the paired runs leave effort and prompt tangled together. The benchmark exercises the loop, six tools, and the coding rules; the discovery and adversarial-testing procedures, the memory, the reviewer, and the IDE features were switched off. The HarnessTax study stands: the band a fourth harness draws is wider than the one three harnesses drew. The runners, the Pi subclass, and the per-attempt records are in benchmarkings/harnesstax/ (tb2_runner.py, pi_agent.py, results/pi/README.md) and papers/kisssorcar/evidence/tb2_trials.json.

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.

Installation

Full install from source

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

When a new release is available, the update toast in the chat panel offers Update and Update when idle; once an idle update is armed it offers Update now and Cancel instead (the daemon installs the update as soon as no task is running; Cancel disarms it). When the daemon itself launches the installer (an idle update, or Update pressed in the web app), it refuses to start new tasks while the installer is starting and running; tasks already running are left alone, and the refusal is lifted as soon as the installer exits without restarting the daemon. Update pressed in VS Code runs the installer in an integrated terminal instead, guarded by the installer's own cross-process lock. Whichever way the installer ran, when it has replaced the VS Code extension it writes ~/.kiss/.extension-updated; the running extension polls that marker every two seconds and then reloads the VS Code window itself, without asking, as soon as the new extension bundle has stopped changing (after 15 s at the latest). If the Update button in the settings UI fails, run the full installation command again. It will not delete your history.

After an install or update, the chat panel opens a Tips window with the usage tips from src/kiss/TIPS.md once per version: the VS Code extension claims the popup for the whole machine ($KISS_HOME/TIPS_SHOWN-<version>, so only one window shows it), the web app once per browser (the version is remembered in localStorage). The window's "Don't show tips automatically" checkbox writes $KISS_HOME/TIPS_DISABLED, which silences the auto-open on every surface; the Tips button in the Settings panel reopens it at any time. 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. At the end it waits for the daemon the extension starts, trusts the daemon's local certificate authority in your browsers (kiss-web --trust-ca), and opens the web app at https://127.0.0.1:PORT in your default browser; on a remote machine (an SSH session, or Linux without a display) it prints the cloudflared URL to open on your own device instead. KISS_WEBAPP_WAIT_SECS (default 900) caps the wait.

Branding. The product name, tagline, and agent identity shown in the chat panel, the extension manifest, the system prompt, and the channel agents come from one file, src/kiss/agents/vscode/media/brand.json (product_name, short_name, tagline, identity, extension_description), read by the Python package (kiss.core.brand), the extension host (src/brand.ts), and the chat page. The {{IDENTITY}} placeholder in src/kiss/SYSTEM.md/SYSTEM_LITE.md and the {{PRODUCT_NAME}} placeholders in src/kiss/TIPS.md are filled from it, and media/brand.css, loaded after the stock stylesheet, is an empty skin hook. A white-label build puts its own copies of brand.json, brand.css, kiss-icon.svg, kiss-icon.png, welcome-logo.png, welcome-logo-dark.png (the light- and dark-theme logos on the chat panel's welcome screen), and thumbnail.jpeg in a git-ignored .brand/ directory at the checkout root: install.sh copies them over media/ only for the extension build (copy-kiss.sh runs scripts/apply-brand.js, which rewrites the display strings in package.json from brand.json, and bundles the branded runtime; npm run package then builds the VSIX) and restores the checkout's own files afterwards, also when the build fails. Without .brand/ nothing changes, and the checked-in files always carry the stock KISS Sorcar brand.

Python package install

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

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

KISS Sorcar requires Python 3.13+.

Configure model access

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

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.

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.

The picker also lists the SEAs that register as models (any SEA whose register_as_model() returns True; see the SEA section below), under the Router group. They are not models: with one selected, every task you type runs through that SEA on the model its model() getter names, with the model routing protocol its add_to_system_prompt() returns added to the system prompt; /xxx slash commands keep their own agent and only take that model from the pick. Two are bundled: autorouter (src/kiss/agents/seas/autorouter/autorouter_sea.py, the same agent as the /autorouter command described below) splits the task into units and dispatches each to the cheapest model tier that passes its acceptance check, running itself on the first runnable frontier-tier model of that file's TIERS menu, and, each time it is picked, making sure an enabled weekly cron job that runs /rsi7d autorouter exists (Saturday 01:00 Pacific, in the KISS checkout the tab works in when there is one; a paused job is resumed, an existing enabled one is left as you tuned it); bestrouter (src/kiss/agents/seas/bestrouter/bestrouter_sea.py) runs every task on claude-fable-5-1 and has gpt-6-astra, dispatched read-only through run_parallel on at most 75% of the task budget, review and debug the result. The entries appear once at least one model is runnable.

VS Code Extension Installation

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.

Using KISS Sorcar

KISS Sorcar has three client interfaces, all served by one local daemon: the VS Code extension, the remote web/mobile app, and the Python client API. A fourth interface, the sorcar terminal command, runs a SorcarAgent directly in the current directory without the daemon: sorcar -t "Summarize README.md" runs an inline task, 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).

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. An empty tab shows a welcome screen — the product logo in a light or dark variant matching the theme, the product name and tagline — that gives way to the transcript on the first message. The chat interface provides:

• @ file/folder mentions with ranked file completion. The picker searches the working directory and the rest of your home directory: matches inside the working directory are inserted as ./path, matches elsewhere under home as ~/path (the working directory's files come first, but at least five slots are kept for the home matches), a query starting with ./ searches the working directory only and one starting with ~/ searches all of home. The picker reads a persistent file index ($KISS_HOME/file-index): one index of the home directory serves the working directories below it (a working directory outside it, or inside a directory the scan skips, gets an index of its own), is reloaded rather than rescanned when the daemon restarts, is refreshed by re-listing only directories whose mtime changed, and a query against an index older than a minute schedules a background refresh, after which new files are found. Dot-directories, common junk directories, the non-glob entries of .gitignore files met on the way down, and depth beyond 12 are skipped, and bulk data dumps are collapsed to their directory entry. Files you mentioned before rank first; other matches outside wide or generated-run containers rank before matches inside them, and within those groups they are ordered by how close the match is to the end of the path and then by the index's build-time order (source files and directories before data and dotfiles, shallow before deep).
• Per-task git worktree isolation — with worktrees enabled for a working directory that is a git repository, a spare worktree is prepared in the background when the daemon starts and when a task is submitted (before the classifier has ruled), so a task starts in a ready checkout, with auto-commit and merge on success, or an interactive merge/discard prompt — toggle both in the Settings panel. The auto-commit message is a conventional-commit subject and optional body generated from the diff by a fast model (a fixed subject when that call fails), followed by User prompt: and Result: blocks carrying the task prompt and the task's result; the result, which the agent produces as HTML, is converted to Markdown first so git log, GitHub, and VS Code's Git hovers show it readably. An auto-commit merge that hits conflicts is finished by the bundled merge agent (src/kiss/agents/seas/merge/merge_sea.py) running as a sub-agent of the task, and a merge deferred because a task on another tab is working directly in the main working tree — that guard fires only when the main tree has uncommitted changes to tracked files (or its git status cannot be read); untracked files alone do not hold a merge back — is retried automatically when the main tree is clean again: the occupying task finishes, or you press Git Commit or Discard.
• A pre-run task classifier that detects whether the task may create or modify files in the project (code, docs, reports, presentations, data — anything that could become git-tracked) and so needs a worktree — tasks that write no files (questions, Internet answers given in the reply, git-only operations) skip worktree isolation, and simple tasks get a lite system prompt for faster starts. By default it makes one fast non-agentic call on the run's own model; with "Use Jev (decisions model)" ticked and an OPENROUTER_API_KEY it first asks the ~typesafe/jev-latest decisions model one typed question (about 0.2 s and $0.00003 per task; on a 415-prompt benchmark it matched hand labels more often than the LLM classifiers, see benchmarkings/task_classifier/) and only falls back to the LLM call if that fails. The LLM classifier is one non-agentic call on the run's own model (structured output, with one plain-text retry if that fails; skipped for cc/* and codex/* models). Both are Settings-panel checkboxes: "Classify tasks before running" (classify_tasks) and "Use Jev (decisions model)" (classify_with_decisions, off by default). The Jev checkbox is the one switch for the decisions model: ticked, the classifier asks Jev first and every agent gets the decide tool; unticked, the LLM classifier answers and no task calls Jev.
• 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), a Working directory panel in the "…" menu (type a path, pick a folder, or reopen one of the directories opened so far; in VS Code it only changes where the current chat's next task runs, the window keeps its folder), and inline rendering of tool-generated images in the chat panels. A question the agent asks with ask_user_question appears as a "Question" panel in the transcript and is answered from the composer. A one-line message that is nothing but the path of an existing regular file (~ expanded, a relative path resolved against the working directory or the tab's pending worktree), typed into a tab that is neither running a task nor waiting for an answer, opens the file in the extension's editor or a content tab of the web app and starts no task; any other ordinary task that is only a path — a directory, or a file path given to the sorcar command — is treated as "open it": the agent runs the platform opener (open, xdg-open, or rundll32 url.dll,FileProtocolHandler) on the path and finishes without reading or editing it (an agent script with a system prompt of its own, such as /review_paper <pdf>, and sub-agents keep their own reading of a bare path). When a task finishes, the daemon stamps its task_history row in ~/.kiss/sorcar.db with classification tags (src/kiss/agents/sorcar/task_metadata.py: a deterministic classifier, no model call, that emits work or personal first, then secret, chore, question, activity tags such as coding, testing, paper, messaging, scheduling, and subagent/failed for how the task ran; at most six), with the name of the agent script (SEA) that ran it, and refreshes the chat's row in the chat_summaries table: a summary of up to eight words taken from the leading words of the chat's oldest tasks (sub-agent rows excluded), plus the launch time of its newest task. The history panel shows the tags and SEA on each row, names each chat by its summary (the first task until one exists), and under Filters adds an SEA dropdown (All, None, every script seen) and a Tag dropdown that the daemon applies in SQL, so a rare tag is found on every page. Databases created before these columns existed are migrated at daemon start; uv run python -m kiss.scripts.backfill_task_metadata [--db PATH] [--refresh] fills the empty tags, infers the SEA of sub-agent rows that lack one, and creates the missing chat summaries (--refresh recomputes every task's tags and every chat summary; inferred SEA names are kept). Every model call that reports usage is also recorded as an llm_call event with its model, tokens, cost, and duration, and the thoughts panel that is open when the event arrives shows the summed cost of its call(s) next to its time label.
• Image and PDF attachments: attach files to a task via the picker, paste, or drag-and-drop — images (HEIC/HEIF converted, oversized ones re-encoded) and PDFs are sent to the model along with the prompt.
• 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 in the Settings panel or set KISS_USE_MEMORY=0; a custom directory goes in the memory_dir key of ~/.kiss/config.json. A run whose working directory is inside a git repository also gets that repository's own memory, the sub-directory ~/.kiss/memories/<repo>/ named after the repository directory (shared by a main checkout and its linked worktrees; independent clones share it only when their directory names match): its pages are addressed as <repo>/<page>, memory_search covers every memory unless narrowed with memory=, and the protocol tells the agent to keep repository knowledge there and cross-project lessons in the general memory. ./rsorcar user@host, the script that deploys this checkout to a remote Linux machine, also syncs the memory pages both ways on every deploy (after the task database): a page one machine lacks is added, a page both have keeps the copy with the newer timestamp (the frontmatter updated field when parsable, otherwise file modification time), a page with different contents but the same timestamp on both is reported and left as each machine has it, and a page deleted on one machine (recorded as a tombstone under .tombstones/<name> in the memory directory) is removed on the other unless the other side has edited it since the deletion; the two machines' clock offset is measured first and applied as the comparison tolerance, and the vector index is rebuilt locally rather than copied. The same deploy also merges the two autorouter notes both ways by meaning (src/kiss/scripts/sync_kiss_notes.py): ~/.kiss/AUTOROUTER.md keeps the copy with the later refreshed date (same date: the tables' rows are united by model and the bullets united) and ~/.kiss/MODEL_DECISIONS.md becomes the union of both machines' ledger rows in time order; and the task-database sync carries the chat_summaries table along with the tasks and events, each chat keeping the row with the later launch time. A sync failure is a warning, not a failed deploy.
• Wake-word voice chat via the mic button, including steering a running agent by voice. The listener is an offline Vosk model that wakes only on the full phrase "Hey Sorcar, …" (a bare "Sorcar" does not trigger it); the speech that follows is transcribed and translated to English by a gpt-audio transcription agent, with distinct speakers numbered by local voice recognition.
• 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. A message typed while the task is already finishing (result broadcast, persistence, worktree merge) is run as the tab's next task with the same settings rather than dropped.
• 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. A sub-agent dispatched with run_agent or run_parallel opens a nested tab of its own on every client viewing the parent task, and that tab stays open on every client — through a collapsed fan-out panel and reconnects — until the sub-agent finishes; it is then closed everywhere, and still-running sub-agents of its own move under the nearest open ancestor tab. Closing a running sub-agent's tab by hand closes it on every surface and it stays closed — a reconnecting client does not get it back and the sub-agent finishing changes nothing — until you reopen it from its history row (collapsing and expanding the fan-out panel also brings it back). Sub-agents started after a running chat was closed and reopened from the history nest under the reopened tab. The sub-agent's history row nests under the parent task.
• A Browser tab: the Browser entry of the "…" menu opens the default browser of the machine running the daemon — Chrome, Chromium, Brave, Edge, Vivaldi or Opera ($BROWSER names the default when set; KISS_BROWSER, an executable, overrides every probe); Firefox and Safari have no DevTools protocol, so the daemon falls back to any Chromium-family browser installed and then to Playwright's bundled Chromium, and runs it headless when the machine has no display — as a tab on every surface: the page is streamed as JPEG frames through the DevTools screencast API to the surfaces showing the tab, and your clicks, scrolling, typing and pastes are replayed on it, under an address bar with back, forward and reload (a bare host name gets https://, words become a Google search; the home page is KISS_BROWSER_HOME, Google by default). Every page that browser opens, popups included, becomes such a tab on every client; closing the tab by hand closes the page for everyone, a reconnecting client gets the live pages back, and the browser exits with its last page and with the daemon. It runs on a persistent profile of its own (~/.kiss/browser-tab-profile), so logins and cookies survive tasks and daemon restarts. An agent's show_browser() tool moves the page it is browsing headlessly into that tab (URL, cookies and the page origin's localStorage carried along) whenever you should see or act on a page: a login or OAuth consent, a CAPTCHA, a live demo of a web app. You and the agent then drive the same page; show_browser(visible=False) closes the tab and carries that state back to the headless session. Sub-agents use the same browser; a run without the daemon (the sorcar command) shows a local browser window instead.
• 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. Schedules are kept in Pacific time (PDT/PST), whatever the time zone of the machine running the scheduler: cron expressions and timestamps without a UTC offset are read as America/Los_Angeles, a timestamp with an offset keeps its instant, intervals such as "every 30 minutes" are zone-free, the cron agent converts a time you give in another zone to Pacific before storing the job, and listings and run logs show next-run times in Pacific. 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). A job can name the directory it works in (work_dir); a prompt job bound to a Git repository can additionally run in a worktree with auto-commit like a chat task, and every job can override its timeout (10 minutes for commands, 1 hour for prompts by default). Sub-agents a prompt job spawns with run_agent or run_parallel inherit the rule never to ask questions or wait for approval.

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. It opens in a light theme (VS Code's Light Modern palette) by default; a sun/moon button switches to Dark Modern and the choice is remembered per browser in localStorage (the VS Code webview has no toggle and follows the editor theme). Its desktop mode adds a docked Task Info sidebar next to the chat — live token, cost, step, elapsed-time, machine, work-dir, and budget metrics for the visible tab's running task, plus a Task update: a short report, written by the bundled task_update agent (src/kiss/agents/seas/task_update/task_update_sea.py), of what that task has done so far and its partial results. The agent runs when the panel first shows the task, every 10 minutes after that, and whenever you press the refresh button at the top right of the report; it runs as a sub-agent in the task's own chat and its cost counts towards the task. Both panels are expanded by default and can be collapsed, scrolled, and resized vertically by dragging the separator between them; collapse state and dragged heights are remembered per client, and every expanded section keeps a minimum height (half an equal share of the panel, at most 4rem) so a remembered drag can never hide another section's content (the same sidebar serves the phone layout's Task Info drawer and the VS Code extension's Task Info view). Under the per-task panels every surface stacks three global subpanels: Schedule lists the scheduled cron jobs (each row shows the job's name, a running badge while it runs or a paused badge when it is disabled, its schedule with the next run — the last run for a paused job — when known, a button that copies the scheduled prompt or shell command to the clipboard, and a tooltip with the whole task and, when there was one, the last run's outcome); Apps lists every third-party channel agent with its authentication state, and clicking one that is not connected starts a new chat whose task signs it in (preferring an OAuth consent or device-code flow, asking you only for what cannot be automated); Spend shows the task history's all-time cost, a daily cost heatmap and cost-by-model bars, counting top-level tasks only (a task's cost includes its sub-tasks'; uv run python -m kiss.scripts.backfill_subtask_costs [--db PATH] [--apply] re-adds sub-task spend that an older daemon left out of a parent stopped while it waited on a sub-agent — a dry run lists the short rows, --apply repairs them). The three are refreshed every 30 seconds (the daemon caches the Apps probe, which runs in a short-lived subprocess, and re-probes while a sign-in you started is pending); each has a refresh button. File links in a transcript and files picked in the sidebar's Explorer view open in content tabs of their own, which are per client and not mirrored: text files are edited in the Monaco editor (loaded from the jsDelivr CDN; a read-only viewer stands in when it cannot be loaded) with a File / Edit / Selection / View / Go menu bar and a colour theme that follows the app's light/dark toggle, Markdown and HTML files also offer preview and source views, images open in the browser's own viewer, PDFs open in a bundled pdf.js viewer (media/pdfView.js, the library fetched from jsDelivr; the VS Code extension opens a .pdf link in a webview editor panel with the same viewer, one panel per file), which draws the pages on canvases in a scrollable box fitted to the page width, zooms with the toolbar's − / + buttons, a pinch, or Ctrl/Cmd + wheel, shows an editable "Page N of M" field that jumps to a typed page, offers a Download link, and answers PageUp/PageDown, the left and right arrow keys, Home/End and Ctrl/Cmd with 0, + or − from the keyboard; other binary files are offered as downloads.

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:

# 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

# Trust the daemon's TLS certificate in this user's browsers and exit.
kiss-web --trust-ca

The web app is always served over HTTPS. The Cloudflare URL uses Cloudflare's certificate; the Local (https://127.0.0.1:PORT) and LAN (https://<lan-ip>:PORT) URLs use a certificate the daemon issues from a machine-local certificate authority kept in ~/.kiss/tls/ (ca.pem, ca-key.pem). Browsers warn about that certificate until they trust the CA, once per device:

• On the machine running the daemon: kiss-web --trust-ca adds ca.pem to the Chromium/Firefox NSS databases on Linux and the Firefox profiles on macOS (needs certutil: libnss3-tools/nss-tools on Linux, Homebrew's nss on macOS, found under $HOMEBREW_PREFIX or the default /opt/homebrew and /usr/local prefixes even though it is keg-only), the login keychain (macOS, for Safari and Chrome) and the user Root store (Windows). Restart the browser afterwards.
• On a phone or tablet on the same network: open https://<lan-ip>:PORT/ca.crt, install the downloaded certificate, then enable trust for it (iOS: Settings > General > About > Certificate Trust Settings; Android: Settings > Security > Encryption & credentials > Install a certificate > CA certificate). Compare the SHA-256 fingerprint printed by kiss-web --trust-ca with the one the device shows.

The CA certificate is public; the CA key never leaves ~/.kiss/tls/. The server certificate is re-issued automatically when it is expiring or when the machine's LAN address changes, so the CA has to be trusted only once. The password gate and the LAN lockdown while no remote_password is set are unchanged.

Python client API

Any Python process can run a task on the daemon with kiss.server.sorcar.run and block until it finishes (up to timeout, one hour by default):

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)

run() accepts keyword options mirroring the chat interface — model, work_dir, scope_work_dir (workspace directory the task's tab is scoped to, when different from the execution work_dir), chat_id, use_worktree, auto_commit, max_budget, model_config (custom endpoint/headers), use_web_tools, classify_tasks (per-run task-classifier override; None falls back to the daemon's persisted setting), use_memory (per-run persistent-memory override — the memory_* tools plus the memory protocol; None falls back to the daemon process's non-empty KISS_USE_MEMORY environment variable, else its persisted setting), is_parallel, tool_profile (name of the tool profile the run's built-in toolset is cut down to — "full", "review", "shell", "assistant", or "bash"; empty lets the daemon choose: a reviewer sub-agent whose task is not an implementation task gets "review" unless KISS_TOOL_PROFILES=0 is set on the daemon, every other run "full"), docker_image (run the task's shell and file tools inside a Docker container instead of on the daemon's host: an image name such as "python:3.12" starts a fresh container that is removed when the task ends, with the task's work_dir bind-mounted at the same path as its working directory; container:<name-or-id> attaches to a container you already run, in that container's own working directory with no extra mount; background Bash jobs and persistent memory are unavailable in a Docker run; empty runs on the host), timeout (how long the client waits for the result — 3600 seconds by default, None waits indefinitely; on expiry the client raises TimeoutError while the daemon task keeps running), stop_on_timeout (also stop the task when timeout expires; default False), sock_path (daemon socket override), parent_task_id / parent_tab_id (attach the run as a sub-agent of a calling task, nesting its tab and history row under that task — how the run_agent tool dispatches), parent_reviewer (mark that sub-agent run as part of a reviewer's sub-tree — a marker its own sub-agents inherit — so that the reviewer default of tool_profile above applies to it: "review" when its task is not an implementation task and no explicit profile is given; default False), side_channel (mark that sub-agent run as a side channel whose result is delivered into the parent's transcript, as /ask answers are, so its own nested tab is closed when the run ends; default False) — plus options to customize the agent itself:

• tools="/path/to/my_tools.py" — a Python file whose get_tools() function returns the functions the daemon registers as extra agent tools. The functions are never serialized: only the path travels over the socket, and the daemon imports the file, calls get_tools(), and runs the tools in its own process.
• system_prompt — replace the default system prompt for the run (and its sub-agents); append_to_system_prompt / append_to_prompt — append text to the system prompt or task prompt instead of replacing them.
• append_basic_tools=False — restrict the agent to finish plus your tools file, dropping the built-in toolset. The built-in toolset includes Bash — which with background=True starts the command detached and returns a job id — and bash_job(job_id, action="wait" | "tail" | "kill") to wait for, read, or stop such a job (not available in Docker runs). Every Bash call runs in a fresh shell in the working directory; a foreground command that outlives timeout_seconds (default 300 s, 30 s in Docker; ignored with background=True, and 1,800 s per command in run_commands_parallel) is killed and the tool returns whatever it printed before the kill, and package installs and builds (apt, pip, uv, conda, npm, yarn, pnpm, cargo, gem, go, make, cmake, ninja) get at least 900 s regardless of the value passed. Both the host and the Docker shells refuse, before running anything, a command that would kill every process (kill -1, kill -9 -1, pkill -f .) or rm / or the working directory (under either its given or its resolved path).
• 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 Sorcar Extension Agents (SEAs) below.

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(). Each SEA lives in its own folder named after it, <name>/<name>_sea.py, next to the helper modules and data files it needs (the bundled ones are laid out this way: src/kiss/agents/seas/sh/sh_sea.py, src/kiss/agents/third_party_agents/slack/slack_sea.py, ...). 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. Every SEA must also define description(), a zero-argument function returning one sentence that says what the SEA does and how to use it; it is not a run parameter, it is what /<name> help prints. One file can define the task prompt, system prompt, model, budget, tools, and safety hooks — a complete custom agent:

# weather/weather_sea.py — a minimal SEA
import requests


def description() -> str:
    return (
        "Reports the current weather in San Francisco from wttr.in; pass its path as "
        "extension_agent_path or send `/weather now` (any text after the command) once "
        "its parent folder is listed in ~/.kiss/SEAS.md."
    )


def prompt() -> str:
    return "Look up the current weather in San Francisco and report it."

def max_budget() -> float:
    return 0.50

def use_worktree() -> bool:
    return False  # no repo changes expected

def if_append_basic_tools() -> bool:
    return False  # restrict the agent to finish + our tools

def system_prompt() -> str:
    return ("You are a weather assistant. Use the get_weather tool "
            "to look up weather, then call finish with the result.")

def get_weather(city: str) -> str:
    """Return current weather for a city from wttr.in.

    Args:
        city: City name to look up.
    """
    resp = requests.get(f"https://wttr.in/{city}?format=3", timeout=10)
    resp.raise_for_status()
    return resp.text.strip()

def tools() -> list:
    """Return the tools the agent may call."""
    return [get_weather]

from kiss.server import sorcar

result = sorcar.run(
    "placeholder",  # required non-blank; overridden by prompt()
    extension_agent_path="weather/weather_sea.py",
)

Key points:

• Overridable parameters. Every sorcar.run() parameter except timeout, stop_on_timeout, sock_path, parent_task_id, parent_tab_id, parent_reviewer, side_channel, 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(), is_parallel(), tool_profile(), and docker_image(); two more getters, add_to_system_prompt() (text added to the system prompt after the caller's append_to_system_prompt, never replacing it) and register_as_model() (True lists the SEA in the model picker under its command name, as autorouter and bestrouter are), make a SEA a model routing entry; a third, on_picked_as_model(work_dir), is a hook the daemon runs when the SEA is picked in the model picker and once per run whose model is the SEA (with the tab's, then the run's, work directory) so the SEA can act on being picked — autorouter schedules its weekly /rsi7d autorouter cron job there; its return value is logged; an exception is logged and a hook still running after 15 s is left behind, neither failing the run. 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). tool_profile() returns the name of the tool profile the run's built-in toolset is cut down to — "full", "review" (a reduced reviewer set — Bash, bash_job, Read, run_commands_parallel, the read-only memory_search/memory_pull/memory_read/memory_list, decide, summary — with no file editing, browser, talk, agent dispatch, or fan-out; Bash itself is unrestricted, so it is not a sandbox; the bundled /ask agent uses it), "shell" (Bash, bash_job, Read, run_commands_parallel), "assistant" (the shell set plus ask_user_question, talk, decide, summary, set_model), or "bash" (Bash only; the bundled /sh agent uses it) — or "" for the daemon's choice: a reviewer sub-agent gets review when the tool_profiles config flag is on and its task does not ask for changes (is_implementation_task), everything else gets full. docker_image() returns the Docker image the run's shell and file tools execute in, container:<name-or-id> to attach to a running container, or "" for the host.
• 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 (callables can't travel the wire). 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:

# 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 — every getter's semantics, error handling, chat continuation, model configuration, and a complete worked example — is in src/kiss/server/README.md.

Slash commands. Every SEA folder xxx/xxx_sea.py in a scanned folder is also a chat command named after the folder: typing /xxx some text in the VS Code extension or web app makes the session call run_agent with that file and "some text" as the task, and /xxx help prints the SEA's description() without running it (a SEA without a usable description() gets a diagnostic instead). A loose xxx_sea.py file outside its own folder is not registered. run_agent waits 300 seconds by default and then stops the sub-task, so an SEA that runs longer defines dispatch_timeout() returning the seconds it needs, and the directive passes it as timeout. The bundled channel agents are registered this way (/slack, /gmail, ...). The 17 bundled SEAs in src/kiss/agents/seas/ are commands too: /ask <question> (answers a question about the current task from a digest of its persisted events in ~/.kiss/sorcar.db read through three tools (task_overview, task_transcript, task_step) on the review tool profile; typed into a running task's tab it runs as a nested sub-agent without interrupting the agent, and the reply appears as an "Answer" panel in the transcript), /sh <command> (runs the command with the Bash tool alone, directly in the tab's working directory, and returns its raw output), /dummy <task> (dummy/dummy_sea.py defines no getters besides description(), so it runs a plain Sorcar sub-agent with the defaults — the same agent run_agent uses when no agent is named), /coding <task> (coding/coding_sea.py is the harness the benchmarkings/harnesstax trial runners use to run Sorcar unattended inside a Docker container — the full toolset minus browser and memory, no step cap, a per-trial budget, every call logged to a JSONL trajectory; it needs a running container and a config, so the chat command itself runs Sorcar with its defaults), /rsi7d all (seven-day recursive self-improvement of the bundled SEAs, rsi7d itself included: mines their runs of the last 7 days in ~/.kiss/sorcar.db for agentic mistakes, speed and cost sinks and quality problems, proposes instructions, judges them pairwise, applies the winners to each SEA's SYSTEM_PROMPT constant — an AST gate rejects any edit outside the constant's text — evaluates the change by replaying the past task that best exercises it (runs that cost under $500 are eligible; a task that modified files is replayed by its replay_in_clone tool in a clone of the task's repository checked out at the commit the task started from, under tmp/rsi7d/replays/, so the checkout being edited is never touched), keeps or reverts it, and refreshes the model evidence /autorouter routes on by rewriting ~/.kiss/AUTOROUTER.md (the autorouter SEA file itself is not edited for that); the task text starts with the scope: /rsi7d review_paper write_paper restricts the mining and the patching to those SEAs, /rsi7d --seas-dir <folder> [<name> ...] to the SEAs of that folder, which then are the editable ones (a folder from ~/.kiss/SEAS.md, for instance) — the tools enforce it, listing, mining and patching nothing outside it — and free-form instructions may follow; it also mines the plain runs on Sorcar's own prompt as the pseudo-SEA sorcar and may improve KISS Sorcar itself — the system prompt src/kiss/SYSTEM.md, the standing instructions in ~/.kiss/SORCAR.md, and its code under src/kiss/ — but only through a permission-gated patch_sorcar tool: its request_sorcar_permission tool asks you in the chat for exactly the files and change it intends, unless the task text itself grants the permission (/rsi7d all, you may modify KISS Sorcar itself), and a scheduled sweep, a "no" or a "yes, but" leaves the proposal in the report as a recommendation; a slash command needs task text, so /rsi7d alone is not dispatched), /merge <instructions> (resolves and stages the conflicted files of an in-progress git merge, committing only when the instructions ask for it — the same agent the auto-commit worktree merge runs on its own when the merge conflicts), /task_update <task_id> (reports what that task has done so far and its partial results), /autorouter <task> (finishes the task at the lowest cost per accepted result: it splits the task into units with a mechanical acceptance check, classifies each unit into the small, medium or frontier tier with the decide tool (judging it against the same criteria itself when decide is unavailable), picks the first runnable candidate of that tier — the candidates within each tier are ordered by coding quality per dollar, with prices read from the local catalog — with its pick_model tool, dispatches the unit to that model through run_agent, verifies the result through the check, escalates on a verified failure (one tier up for a slip, two for a reasoning failure, never more than twice per unit), and logs every decision, stamped with the task id, to the shared ledger ~/.kiss/MODEL_DECISIONS.md, which accumulates across tasks and worktrees (the unit, reason and outcome cells are single-line and cut at 120 characters); the tier menu is the TIERS constant of src/kiss/agents/seas/autorouter/autorouter_sea.py, and the per-model evidence the protocol weighs against it is read from ~/.kiss/AUTOROUTER.md when the SEA loads — at most 2,500 characters: a longer file is cut at the last line break within the cap, or at the cap itself when its first line alone is longer, and a marker line replaces the dropped tail — so a /rsi7d refresh reaches the next task without a code change), /bestrouter <task> (runs the task on claude-fable-5-1 and has gpt-6-astra review and debug the result read-only through run_parallel, on at most 75% of the task budget), /skillopt <instructions> (optimizes the prompt text of a skill, an SEA's system_prompt() constant, or any module-level string constant against an evaluation set and writes the accepted text next to the target as <target>.proposed; also runnable as python -m kiss.agents.seas.skillopt.skillopt_sea), and /write_paper <instructions> (writes or revises a research paper under the rules embedded in src/kiss/agents/seas/write_paper/write_paper_sea.py, appended to the system prompt: the instructions name the venue, the .tex path, the topic, the sources of truth and optionally the writer and reviewer models (a new paper without a path or topic makes the agent ask first); the agent reads the highly cited related work of the last two or three years before writing, and gets a check_paper tool that runs the prompt's AI-slop and consistency gates on the prose with line numbers — slop vocabulary, scope-inflating openers, signposting, motivational closers, significance puffery, vague attribution, leaked LLM output such as oaicite markers, and, in the .bib file, the signatures of fabricated references (placeholder authors, et al. in an author field, XXXX arXiv ids, implausible page ranges), which fail the check — and a build_paper tool that runs pdflatex, then bibtex or biber when the paper asks for a bibliography, then pdflatex twice, and summarizes errors, undefined references and overfull boxes), and /review_paper <instructions> (reviews a paper, a PDF, .tex, .md or .txt file, for any venue: the instructions name the paper, the venue, the output path and the cutoff date for related work, and optionally the word limit (700 words by default) and a second model that checks the review; the agent first reads page 1 with a read_paper tool and stops with a report instead of a review when the file is not a research paper (a slide deck, a garbled conversion), then reads the rest page by page, searches the related work through the Semantic Scholar and arXiv APIs from three perspectives (the paper's benchmarks and baselines, the same problem, the same method in other settings) at three levels of specificity (at least 20 sources, each logged with its URL, date and a one-line relevance verdict; the 5 to 8 closest papers are downloaded, read and summarized against the reviewed paper), judges the novelty against recent papers of the venue, pinpoints problems by page and table with a fix for each, scores seven dimensions from 1 to 10 under a Scores heading (originality, importance of the research question, support for the claims, soundness of the experiments, clarity, value to the community, contextualization relative to prior work) from which the venue's own rating follows, and runs a check_review tool that checks the review's structure, the seven scores, the word limit and the AI-slop gates with line numbers), and /revise_and_review_paper <instructions> (the write-review loop: the task text carries a Writing: block for /write_paper and a Review: block for /review_paper; each round the coordinator runs the writer, stages a copy of the built PDF, runs the reviewer as a fresh memory-free session that sees no earlier review or notes and must end with a Recommendation: line, and revises against the review, running experiments, ablations or the AI-discovery loop on the benchmarks the writing instructions allow when the review asks for evidence; it stops at strong accept, at the round cap (default 6), or when two rounds in a row fail to raise the verdict, and leaves the paper, every review and a per-round log under reports/), and /git_extract_knowledge <repo> (builds the durable memory of a git repository, a local path or a clone URL, and keeps it current: an index_repo tool writes one full-text block per file, 80-line chunk, symbol definition, commit, per-file change with its patch, tag, branch, contributor and directory into ~/.kiss/memories/<repo>/knowledge.sqlite3 (millions of blocks, incremental after the first run), the agent reads the code and history and writes curated pages (overview, domain glossary and concepts, architecture, conventions, history, one page per module, FAQ) into the repository's domain memory where every Sorcar run in that repository finds them with memory_search, a knowledge-lookup page tells other agents how to query the block store from the shell (python -m kiss.agents.seas.git_extract_knowledge.git_extract_knowledge_sea search <repo> "<query>"), and the first run registers a cron job that re-runs the agent with update <repo> every morning at 04:00 America/Los_Angeles (PDT or PST — cron schedules are evaluated in Pacific time whatever the daemon machine's clock), pinned to the claude-fable-5-1 model with an explicit budget and a four-hour timeout; /git_extract_knowledge ask <repo> <question> answers from the memory), /write <what to write> (writes prose for a general audience in concise, professional American English that reads as if a person wrote it: src/kiss/agents/seas/write/write_sea.py adds a writing protocol to the default system prompt through add_to_system_prompt(), fixing the register, banning the vocabulary and sentence patterns that mark machine text, and ending with an edit pass against those lists; the task names the subject, the sources, and optionally the output file, else the prose is the answer), and /remember <instruction> and /forget <instruction> (add the instruction to, or remove it from, ~/.kiss/SORCAR.md, the file appended to the system prompt of every task, so every later task follows it; each instruction is one bullet line, /remember creates the file on first use and leaves anything you wrote there by hand alone, and /forget matches the stored line ignoring case and spacing, or lists the stored instructions and removes the one you meant). List your own SEA folders, one per line, in ~/.kiss/SEAS.md; they are picked up within two seconds, no restart needed. Syntax, precedence, and the dispatch flow are documented in docs/sea-commands.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. Remote servers that follow the MCP authorization spec (Notion, Linear, Asana, or any URL) are signed into from the chat: the agent's connect_mcp_server tool adds a new server to ~/.kiss/mcp.json, registers the client with the server's authorization server (Client ID Metadata Document or Dynamic Client Registration — no KISS-owned app or broker in between), opens the consent URL for you (in the Browser tab under the kiss-web daemon, else in your default browser) and returns it; you sign in and click Allow, the redirect lands on a fixed loopback port, and finish_mcp_server_connect stores the tokens under ~/.kiss/mcp_auth/<server>.json, where later runs reuse and refresh them without asking again. A server whose authorization server allows neither registration method (Zoom) needs a pre-registered app named by KISS_MCP_<NAME>_CLIENT_ID (and _CLIENT_SECRET); python -m kiss.agents.sorcar.mcp_oauth <name> [url] runs the same sign-in from the shell. A curated catalog of privacy-first MCP connectors (fetch, time, memory, GitHub, Slack, Google Workspace, WhatsApp, …) ships in connectors/ with enable.py/verify.py CLIs.
• "Tricks" (inject-instruction) entries are the concatenation of two ## Trick-sectioned Markdown files: (1) ~/.kiss/MY_INJECTION.md — your personal tricks, auto-created on first read with a starter trick and never overwritten thereafter; (2) the bundled src/kiss/INJECTIONS.md, read directly from the package so every upgrade delivers the latest bundled tricks. The Inject panel in the chat lists them (your tricks first, filtered by its search box); clicking a row injects it at the composer's cursor, every row has a copy button, and your own rows also have a pencil button that edits the trick in place and a two-step delete button, both writing ~/.kiss/MY_INJECTION.md (its Add box appends a new trick). The file is shared by every window, so an add, edit, or delete repaints the panel everywhere; editing the file by hand works too.

Messaging & Third-Party Agents

KISS Sorcar includes 44 third-party agents that act on messaging services, mailboxes, devices, and web services on your behalf. 32 are 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

Ten more are service agents that 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) · Overleaf (kiss-overleaf) · 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. Besides the task and the optional agent name (empty runs a plain Sorcar sub-session through the bundled src/kiss/agents/seas/dummy/dummy_sea.py), the tool takes a workspace (account identifier for multi-account channels such as Slack; default "default") and the same optional per-run options as sorcar.run() — model_name, max_budget, timeout, chat_id, system_prompt, tools, model_config, use_worktree, auto_commit, use_web_tools, classify_tasks, use_memory, is_parallel, append_basic_tools, append_to_system_prompt, append_to_prompt, tool_profile — as strings ("true"/"false" for booleans, a JSON object for model_config); an empty value keeps the default. Channel and cron sub-tasks always run without a worktree or auto-commit. Each agent also has its own CLI entry point (kiss-slack, kiss-gmail, kiss-whatsapp, …) for running tasks directly from the shell.

Channels also work inbound: gateway-capable messaging channels can become prompt surfaces of their own. A one-shot --channel poll tick (normally scheduled as a recurring cron job — just ask for "an always-on Telegram gateway" in chat) drains new inbound messages and runs each as a Sorcar task, with persisted thread continuity across ticks, a delivery ledger, per-channel model/budget overrides, sender allow-lists (--allow-users), and an optional pairing handshake (--pairing, --approve, --list-pending) so only approved senders can drive the agent.

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. It also ships a Govee smart-home CLI for controlling IoT lights (on/off, brightness, color, and color temperature) via the Govee Developer API.

Sign-in. Every service agent carries its own check_<service>_auth / authenticate_<service> tools (most add clear_<service>_auth; the six Google agents get theirs from the shared helper in _google_workspace_utils.py), plus a finish_<service>_auth tool where the sign-in waits on a browser consent, so a task can connect a service on the spot, and the Apps subpanel of the sidebar starts such a task when you click a service that is not connected. The six Google Workspace agents (Gmail, Calendar, Docs, Drive, Sheets, Chat) go through Composio: Google only lets verified OAuth apps request Workspace scopes, so authenticate_<service> returns a Composio Connect Link (with a COMPOSIO_API_KEY, or an api_key= passed once — a Composio project key, ak_...; the older ck_... consumer keys are rejected), you sign in to Google and click Allow there, and every API call then goes through Composio's proxy, which adds the Google token — no Google token is stored locally (Google Chat needs a custom Composio auth config named by KISS_COMPOSIO_AUTH_CONFIG_GOOGLECHAT, or its service-account bot mode). GitHub, Microsoft Teams, Slack, and Discord sign in through public OAuth apps — the device-code flow for GitHub and Teams, PKCE with the fixed loopback redirect http://localhost:53682/callback for Slack and Discord — so there is no client secret and nothing is pasted back. _oauth_apps.py is where KISS-owned client IDs would be embedded; in this checkout they are empty, so the tool answers with the KISS_<PROVIDER>_CLIENT_ID variable to set (the client ID of an app registered with the same settings; that variable overrides an embedded ID too). A Slack or Discord sign-in yields a user token: Slack acts as you, and Discord can list your servers and post to the channel you pick (reading messages and channel mode still need a bot token). Nextcloud Talk uses Login Flow v2, Matrix uses the OAuth 2.0 device grant of homeservers backed by Matrix Authentication Service (matrix.org included), Signal links this computer like Signal Desktop via a signal-cli link QR code, and Twitch needs an OAuth app of your own. Every one of these sign-ins ends on a page only you may complete, and it is put in front of you rather than driven by the agent: under the kiss-web daemon the sign-in, consent, QR or developer-portal page opens in the Browser tab that every surface switches to, so you are never asked to open a URL; without the daemon it opens in the default browser of that machine and the URL is shown in the chat as well. The agent never asks for your account password or a 2FA code there. Connectors configured by credential (an access token for ntfy, an account or app password for Email over IMAP/SMTP, and the like) take that credential as a tool argument instead.

Credential isolation (Muse auth). On Linux, credentials for the 18 Muse-covered connectors (Slack, GitHub, Notion, Discord, Home Assistant, Firecrawl, Brave Search, ntfy, Govee, LINE, Mattermost, Nextcloud Talk, Synology Chat, Twitch, Zalo, BlueBubbles, Microsoft Teams, and Telegram; the Google agents hold no token to isolate, see above) 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 (credential-free, bodyless GET/HEAD redirect hops are the one permitted off-list exception), 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. The refresh tokens the OAuth sign-ins above produce are renewed by the daemon (oauth2_refresh_token credentials) or, for Matrix, by the agent itself; Microsoft Teams requires Muse auth, since its delegated token pair must live in the vault for the daemon to refresh it (with KISS_MUSE_AUTH=0 the Teams sign-in refuses). Manage it with python -m kiss.agents.third_party_agents.muse_auth (status, import, grant, revoke, audit, clear, daemon, stop, and an export command that reads a vaulted credential back out for recovery); opt out with KISS_MUSE_AUTH=0.

These agents live in src/kiss/agents/third_party_agents/; a prompt-oriented usage guide with a complete agent catalog and 26 worked examples is in src/kiss/agents/third_party_agents/README.md.

Models Supported

KISS Sorcar ships a catalog of 706 models across 9 provider categories, with built-in prices, context lengths, and capability flags (fc function calling, gen generation, emb embedding, dec typed decisions via OpenRouter's /api/alpha/decisions). The source of truth is src/kiss/core/models/MODEL_INFO.json. Cost and budget tracking use these prices, except for openrouter/* models, where the cost OpenRouter reports for each response (usage.cost; the upstream provider's separate charge is added only when the response is marked is_byok, since a non-BYOK cost already includes it) is billed instead of the catalog estimate, since the same model id is priced differently per upstream route. A response the adapters reject after the provider has billed it — output cut off at the token limit, an incomplete/failed Responses status, a safety refusal — still counts towards the task's cost and budget, and the task total shown in the UI includes the task classifier's spend, every earlier session of a task that was continued after a crash, and the whole spend of the sub-tasks the task dispatches with run_agent and run_parallel — the last total each sub-task reports, so spend booked after its result (its classifier, a merge agent, a side channel) is counted too, and the spend already seen is kept when the wait on a sub-task is interrupted or the daemon connection drops. Models are grouped below 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.

Current catalog capability totals:

• 687 generation-capable models
• 525 function-calling-capable models
• 7 embedding models
• 4 decision models

Full model list:

Contributing

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

License

Apache-2.0. See LICENSE.

Citation

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

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