KISS Sorcar

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

KISS Sorcar is 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 workflow just via prompt. All agents run as daemon.

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"). KISS Sorcar is named after P. C. Sorcar, the Bengali magician. 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 GEMINI_API_KEY=...
export TOGETHER_API_KEY=...
export OPENROUTER_API_KEY=...
export MINIMAX_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 "Summarise 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

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, 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 read from ~/.kiss/INJECTIONS.md (one per ## Trick section), seeded on install from the bundled src/kiss/INJECTIONS.md. Edit the file to customise the dropdown; remove it to regenerate from the bundled defaults.
• VS Code welcome-screen sample-task chips read from ~/.kiss/SAMPLE_TASKS.md (one per ## Task section), seeded on install from the bundled src/kiss/agents/vscode/SAMPLE_TASKS.md. Edit the file to customise the chips; remove it to regenerate from the bundled defaults.

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 501 models across 8 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:

• 485 generation-capable models
• 321 function-calling-capable models
• 7 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}
}