Skip to content

README.md

Latest commit

 

History

History
47 lines (37 loc) · 3.15 KB

README.md

File metadata and controls

47 lines (37 loc) · 3.15 KB
Raw

xBot documentation

Written before the code, so that the code has something to be measured against. Where a document and the implementation disagree, one of them is wrong and it is worth finding out which — see the last section of CLAUDE.md.

Reading order

xBot was redesigned in October 2026: a native app that drives the agent CLIs people already have, with no Docker and no services. Read ADR-0009, then the redesign spec, then:

  1. Architecture — what runs, and how a message becomes a reply.
  2. The Mac app — modules, ownership, tests.
  3. Design system — tokens, typography, motion, materials. Derived from Apple's Designing Fluid Interfaces. Still current.

The rest describe xBot 1.x and say so at the top. Each is rewritten in the sub-project that touches it: vision, model providers, onboarding, UI specification, security, packaging and updates, roadmap, launch checklist.

Decisions

Architecture Decision Records. Each one exists because the decision looks wrong without its context.

# Decision
0001 Replace the mandatory hosted history service with a local provider
0002 Resolve the model per agent at request time, not per process at boot
0003 Which container runtime the app drives, and how it hedges
0004 Native SwiftUI for the product surface, embedded web for admin
0005 Developer ID and a DMG, not the Mac App Store
0006 Open questions about the name and the visual reference
0007 Wrap OpenBot rather than re-engineer it, and keep Intelligence for v1. Defers 0001 and re-orders the roadmap — read it before 01 or 03
0008 Conversations kept locally by a durable wrapper around the vendor's SSE runner. Supersedes 0007's "keep Intelligence" for v1
0009 A native app that drives the agents people already have. No Docker, no services; a bot's computer is an Apple Containerization VM. Supersedes 0001, 0002, 0003, 0007, 0008

Conventions in these documents

  • "A harness" is an agent CLI the person has installed and signed in to (Claude Code, Codex), which xBot drives on their subscription.
  • "A brain" is whatever answers a turn: a harness, or later the native loop.
  • "A bot" is a persona with a soul, a memory and optionally a computer (sub-project 3 onward).
  • "The computer" is a bot's own Linux VM. Kept from 1.x, because it is a good word.
  • A line marked ⚠️ is a known risk with no settled answer yet.