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, a Claude-Code-style CLI, and a browser/mobile web app. Your prompts and code are sent directly to the model provider or local endpoint you configure — not through our servers. It supports multi-model workflows just via prompts. All agents run as daemons. 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

🆚 KISS Sorcar vs Claude Code vs Cursor

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

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.

Python package / CLI install

If you only want the Python package and CLI 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 configure a custom endpoint with --endpoint / -e and optional repeated --header Key:Value CLI flags.

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.

CLI Interface

sorcar runs in two modes:

• Interactive (no -t/--task or -f/--file) — a Claude-Code-style REPL that connects as a thin terminal client to the local sorcar web daemon. Chat-session control (new chat, resume by id, list history) and worktree merge/discard prompts are driven from slash commands. Each task is isolated in a git worktree by default.
• Non-interactive (-t or -f supplied) — runs a plain SorcarAgent once on the supplied task and exits. Worktree isolation and chat-session control are unavailable in this mode; display events are still streamed into the chat DB so the run is replayable in the chat webview.

# Launch the interactive Sorcar CLI, similar to Claude Code.
sorcar

# Run a one-shot task (non-interactive).
sorcar -t "What is 2435*234?"

# Use a specific model.
sorcar -m "claude-sonnet-4-6" -t "What is 2435*234?"

# Custom endpoint and headers for a local or self-hosted model.
sorcar -e "http://localhost:8000/v1" --header "Authorization:Bearer xxx" \
       -t "Summarize this codebase."

# Cap spend at $2 and pin the working directory.
sorcar -b 2.0 -w "$HOME/projects/my-repo" -t "Refactor utils.py for clarity."

# Use the contents of a file as the task.
echo "Can you find the cheapest non-stop flight from SFO to JFK on June 15?" > prompt
sorcar -f prompt

# Disable browser/web tools (terminal-only mode).
sorcar --no-web -t "Lint and fix every Python file under src/."

# Disable parallel sub-agents for a deterministic single-thread run.
sorcar --no-parallel -t 'Run pytest and report which tests fail and why.'

# Ask Sorcar to use desktop/browser/messaging tools.
sorcar -t 'Can you send the message "Hello from Sorcar!" to ksen via the desktop Slack app?'

# Ask Sorcar to explain code.
sorcar -t 'Can you show me the detailed step-by-step workflow of gepa.py?'

# Manage MCP servers (see "sorcar mcp" subcommand below).
sorcar mcp list --ping

# Print the installed sorcar version and exit.
sorcar --version

CLI options

--worktree / --no-worktree / --auto-commit / --no-auto-commit are rejected with exit 2 when combined with -t/-f, since the non-interactive path runs a bare SorcarAgent that does not implement them. Argparse prefix abbreviations are disabled, so each flag must be spelled out in full.

Interactive CLI features

The interactive CLI includes:

• @ file/folder mentions with ranked project-file completion.
• Slash commands: /help, /clear (alias /new), /resume, /model, /model list, /cost (aliases /usage, /context), /commands, /skills, /mcp, /autocommit, /voice (toggle wake-word voice chat), and /exit (alias /quit).
• Custom Markdown slash commands loaded from ~/.kiss/commands, <project>/.kiss/commands, ~/.claude/commands, and <project>/.claude/commands.
• 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.
• VS Code "Tricks" button entries are the concatenation of two ## Trick-sectioned Markdown files: (1) ~/.kiss/MY_INJECTION.md — your personal tricks, auto-seeded on first read with a starter trick and never overwritten thereafter; (2) the bundled src/kiss/INJECTIONS.md — tricks shipped with the extension, read directly from the package so every upgrade delivers the latest defaults. To customise your dropdown edit ~/.kiss/MY_INJECTION.md; to reset it remove the file.
• VS Code welcome-screen sample-task chips are the concatenation of two ## Task-sectioned Markdown files: (1) ~/.kiss/MY_TASK_TEMPLATES.md — your personal tasks, auto-created on first launch with the seed ## Task\n\nHi!\n and never overwritten thereafter; (2) the bundled src/kiss/SAMPLE_TASKS.md — sample tasks shipped with the extension, read directly from the package so every upgrade delivers the latest chips. To customise your chips edit ~/.kiss/MY_TASK_TEMPLATES.md; to reset it remove the file.

sorcar mcp subcommand

Manage Model-Context-Protocol servers used by Sorcar:

💬 Messaging & Third-Party Agents

KISS Sorcar includes 23 third-party messaging agents that can send and receive messages on your behalf:

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

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

These agents live in src/kiss/agents/third_party_agents/.

🤖 Models Supported

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

Current catalog capability totals:

• 586 generation-capable models
• 428 function-calling-capable models
• 8 embedding 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}
}