koris-bot

Koris Assistant is an autonomous AI agent framework written in strict TypeScript and run with Node.js 24+ and pnpm. It is organized as a modular system with four plugin families: channels, tools, skills, and MCP servers. Plugins can be downloaded on demand from a companion hub repository and hot-loaded without restarting the agent. Channels include Telegram, WhatsApp, an interactive terminal UI, and a React 19 web dashboard. A unified message gateway and session manager drive all of them. The framework also supports the Model Context Protocol over Streamable HTTP, discovering remote tools and namespacing them as server__tool inside the LLM tool pipeline. Voice support is local: speech-to-text uses Whisper via sherpa-onnx and text-to-speech uses Piper neural voices, both served by a lightweight sidecar on port 6006. Voice notes in WhatsApp or the web UI are transcribed automatically, and a per-conversation voice reply mode is available. Memory and sessions are persisted in SQLite, covering long-term facts, lessons, summaries, semantic embeddings, session tracking, and conversation history. Model access is multi-provider: Ollama, OpenAI-compatible presets such as openai, deepseek, groq, openrouter, xai, mistral, together, gemini, and nvidia, plus a Mock provider. Different providers and models can be assigned per role, for example the main agent versus background workers versus embeddings. Client shells include the web dashboard, the TUI, a Tauri desktop app using the native OS webview, and an Electron desktop shell. Scheduled cron-driven background sub-agents, called heartbeat agents, handle autonomous routines, maintenance, and notifications. Tool execution is sandboxed, including domain-gated HTTP curl, self-hosted SearXNG web search, issue tracking, beat management, stickers, and custom plugins. The project documents an "errands" feature: delegated conversations run by a Negotiator agent plugin that pursues a goal with a contact while keeping the requesting user informed. Each errand creates a fresh delegated child session per target, with parent session ID, errand ID, and instructions stored in SQLite metadata. Commands include listing, approving, replying, retrying, closing, and cancelling errands. The README describes state transitions, delivery recovery, queue promotion, expiry behavior, and known limitations around web polling and exactly-once delivery. Setup involves installing dependencies, copying an example settings file to koris.json or using a web setup wizard, validating configuration, and building. The agent can then run as a web service, in the TUI, or as a desktop app. Optional Docker Compose services provide SearXNG and the audio sidecar. The project states it uses strict TypeScript checks, Vitest test suites, and Stryker mutation testing, and is licensed under ISC.