Overview

Overview

Source: docs/design/README.md

KepCup is a local desktop Personal Agent: a multi-Bot team that serves one user. You chat; Bots remember, keep knowledge, and execute work without blocking the conversation.

Product intent

• Local-first — macOS / Windows / Linux client; data under ~/.kepcup/ by default.
• Team, not group chat — a project team is a shared work board (one message list + project wiki + planned boards/OKRs), not bots hanging out socially.
• Human-like dual loops — the message list is the long-term communication channel; each user message starts an independent reply turn; tasks run in separate loops with their own context.
• Slogan: Create a team that serves only you.

Dual loops (D75)

Layer	Role	Tools	Concurrency
Reply turn (loop_type=turn)	Talk, route, schedule	Read-only + start_task / inject_task / cancel_task / capability two-pack	One turn per (Bot, conversation)
Task (loop_type=task)	Do the work	Full tool surface	Parallel within caps; write lease on workdir

The reply turn never waits for tasks. Task settlement is an event that may wake the next turn. See 30-Supervisor-and-Tasks and 02-Execution.

Core objects

• Bot — profile, private memory, private wiki, skills, widgets; optional Butler (unique, pinned, undeletable). 03-Bot
• Conversation — direct DM or project team session. 01-Conversation 41-Project-Team
• Workdir — shared folder bound to a conversation; write lease serializes writers. 08-Workdir
• Run — one loop execution (turn or task), recorded in runs.db.

Isolation

Soft path checks + OS sandbox for shell; Bot wikis isolated (project wiki is the only shared knowledge channel); credentials field-encrypted. 06-Isolation-and-Storage 10-Sandbox 13-Permissions

Stack

Embedded pi agent loop, Electron shell, Svelte 5 + shadcn-svelte UI, better-sqlite3-multiple-ciphers + FTS5 + sqlite-vec. 09-Tech-Stack 11-Storage

How to read this wiki

Pages mirror docs/design/NN-*.md. Prefer Decision-Log for cross-cutting rules (delete Bot, project routing, unattended mode, etc.). Implementation checklists live in docs/dev/ and are not mirrored here unless the design doc itself is the source of truth.