ksenxx/kiss_ai

KISS Sorcar – a local‑first AI‑agent framework

What it is – KISS Sorcar (short for KISS Agent Framework) is an open‑source, general‑purpose AI‑agent platform that runs entirely on your own machine. It lets you issue natural‑language tasks (via VS Code, a web/mobile UI, or a Python API) and orchestrates large‑language‑model calls, tool usage, git worktrees, and even messaging‑service actions without ever sending your data through the framework’s servers. You bring your own API keys (OpenAI, Anthropic, Gemini, Together, etc.) or point it at a local model endpoint.

Key components

• kiss-web daemon – a local server that hosts the agents, chat history, and the web UI. The VS Code extension and mobile web app talk to it over a Unix socket.
• VS Code extension & web/mobile app – graphical front‑ends where you type or speak a task. They provide file‑mention completion, git worktree isolation, voice wake‑word (“sorcar …”), scheduled automations, and tab‑mirroring across devices.
• Python client API – kiss.server.sorcar.run() lets any Python script submit a task to the daemon, wait for the result, and optionally chain follow‑up tasks.
• Sorcar Extension Agents (SEAs) – plain Python files that can dynamically compute any run() parameter (prompt, model, budget, tools, etc.) and supply custom tools. This makes the framework highly extensible without recompiling.
• Third‑party agents – 43 built‑in agents for messaging, email, phone/SMS, WhatsApp, Slack, GitHub, Notion, Google services, databases, search, and more. They can be invoked by natural language (“send ‘running late’ to Alice on WhatsApp”) or via dedicated CLI wrappers (kiss‑slack, kiss‑gmail, …).
• Model catalog – ships with metadata for 660 models across nine provider categories, allowing you to mix‑and‑match providers in a single workflow.

Typical workflow

1. Configure one or more model back‑ends by setting environment variables (e.g., OPENAI_API_KEY).
2. Start the daemon (kiss‑web) – VS Code launches it automatically.
3. Open the Sorcar sidebar (or the remote web app) and type or speak a task, e.g., Summarize README.md.
4. The system classifies the task, optionally creates an isolated git worktree, and runs the LLM with any required tools.
5. Results appear in the chat pane; you can inject follow‑up messages, switch models on‑the‑fly, or schedule recurring jobs with plain‑language cron syntax.

Why it matters

• Local‑first & privacy‑first – all prompts, code, and model calls stay on your machine; the framework never proxies your data.
• Multi‑model flexibility – you can chain calls to OpenAI, Anthropic, Gemini, Together, local Ollama/vLLM, or even CLI‑based models like Claude Code or Codex, all within a single task.
• Extensible tooling – SEAs and the built‑in tool system let you add custom Python functions (e.g., weather look‑up, safe‑shell‑command guards) without modifying the core.
• Broad integration – the 43 third‑party agents make Sorcar act like a personal assistant that can read emails, send messages, query databases, control smart‑home devices, and more, all from natural language.

Getting started

# Full install (macOS/Linux) – installs the daemon, VS Code extension, and dependencies
curl -fsSL https://raw.githubusercontent.com/ksenxx/kiss_ai/main/scripts/install.sh | bash

# Or just the Python package
pipx install kiss-agent-framework   # or: uv tool install kiss-agent-framework

After installing, set at least one API key (export OPENAI_API_KEY=…) and launch VS Code. The extension will prompt you to sign in to the local daemon and you’re ready to start issuing tasks.

---

TL;DR – KISS Sorcar is a free, open‑source, locally hosted AI‑agent framework that lets you run sophisticated, multi‑model LLM workflows (including code generation, git operations, and messaging automation) from VS Code, a web UI, or Python, while keeping all data on your own machine.