adongwanai/learn-workbuddy

What it solves

Building a desktop AI assistant is far harder than a command-line agent. A simple loop that calls tools works fine in the terminal, but a desktop app must stay alive across sessions, manage huge tool outputs without blowing the context window, store long-term memory safely, control permissions so the agent can't become a backdoor, and separate dozens of moving parts. This project turns those problems into 24 structured lessons, each adding exactly one mechanism with working Python code and a diagram.

How it works

The project is a teaching blueprint, not production source code. It decomposes a desktop agent into six layers: UI, agent reasoning, tool execution, extension system, memory system, and safety governance. Each lesson (s01 through s24) builds on the previous one, adding one core mechanism at a time — from the basic agent loop, tool dispatch, and permission hooks, through Electron shell, sidecar server, session management and model routing, to JSONL transcripts, workspace/user/cloud memory, output externalization, prompt assembly, skills, MCP connectors, experts, visualization, SQLite, automation, and an audit sandbox with a hash chain.

A minimal reference implementation called Mini WorkBuddy is included — built only with the Python standard library — so you can inspect the full request path: agent loop, tools with permission guards, JSONL storage, externalized outputs, append-only audit log, a REST/ACP-like server, and a provider adapter that normalizes DeepSeek, Anthropic, OpenAI, and OpenAI-compatible gateways into a single ToolCall/ModelTurn interface.

You can run many demos fully offline (no API key needed) by executing each chapter's code.py with the --demo flag. For real-model lessons, you can fill in a DEEPSEEK_API_KEY (or Anthropic/OpenAI keys) and run interactive teaching CLIs or unified evaluation modes that write model/tool JSONL traces. A scripts/verify.py checks syntax, tests, offline demos, docs, and clean-room compliance.

Who it’s for

It’s for developers who already understand basic CLI agents (like the companion learn-claude-code project) and want to go deeper into desktop product engineering — learning how to architect long-running processes, manage memory and context, handle multi-agent collaboration, enforce safety, and integrate with multiple model providers. It's also for educators and self-learners who prefer a hands-on, chapter-by-chapter approach with minimal dependencies.

Highlights

• 24 chapters with runnable Python code and 28 diagrams, each lesson adding exactly one mechanism
• Six-layer architecture showing responsibility boundaries: UI, reasoning, tools, extensions, memory, and safety
• Multi-provider support (DeepSeek, Anthropic, OpenAI, OpenAI-compatible gateways) through a provider adapter layer — the loop stays stable while models can be swapped
• Fully offline demos for most examples, including a standard-library Mini WorkBuddy harness, so anyone can run and inspect the complete pipeline without API keys
• Detailed memory system split into five layers (workspace, user, remote profile, transcript, tool-result swap) with the key idea: context window is RAM; JSONL, SQLite, memory files, and tool results are disk
• Clean-room guarantee: contains only original teaching code and public architectural observations, never WorkBuddy's closed-source code, keys, or private prompts
• Includes advanced example evaluations for memory resilience, evidence-grounded RAG, retrieval routing, and a model benchmark that can compare providers across all lessons