How ace-haxxed/atomic works
Atomic is a local-first desktop AI assistant with Chat, Cowork, and Code modes sharing one streaming agent runtime. The user selects a mode and model, submits a conversation, and receives streamed responses; tool calls pass through permission checks and approval before execution. The React shell uses the host-agnostic LocalHost, composed with Tauri-provided platform, keychain, SQLite, and app-directory services. Core capabilities also include model discovery and selection, settings, audit and conversation persistence, and workspace tools. Source excerpts and index references support the main runtime links; unsampled subsystem links are omitted where their callers are not shown.
Main entry points: local.ts LocalHost · loop.ts Agent loop · registry.ts Provider registry · app.tsx React app
Components 23
Desktop app
- React app
apps/desktop/src/app/app.tsx - Agent run hook
apps/desktop/src/app/use-agent-run.ts - Message view
apps/desktop/src/components/message-list.tsx - Settings UI
apps/desktop/src/components/settings-panel.tsx - Desktop composition
apps/desktop/src/lib/bootstrap.ts - Tauri host
apps/desktop/src-tauri/src/lib.rs
Agent runtime
- LocalHost
packages/core/src/host/local.ts - Agent loop
packages/core/src/agent/loop.ts - Tool registry
packages/core/src/tools/registry.ts - Workspace tools
packages/core/src/tools/index.ts
Models and providers
- Model catalog
packages/core/src/models/catalog-service.ts - Provider registry
packages/core/src/providers/registry.ts - Zen provider
packages/core/src/providers/zen/provider.ts - Ollama provider
packages/core/src/providers/ollama/provider.ts - Provider HTTP
packages/core/src/providers/http.ts - Model service
packages/core/src/models/provider.ts
Local data and policy
- Permission gate
packages/core/src/permissions/gate.ts - Settings schema
packages/core/src/settings/schema.ts - Audit log
packages/core/src/audit/audit-log.ts - Repositories
packages/core/src/storage/repositories.ts - SQLite database
packages/core/src/storage/database.ts
Other components
- User
- OS keychain
Connections 27
- User → React app: interacts with
apps/desktop/src/app/app.tsx - React app → Agent run hook: starts runs
apps/desktop/src/app/app.tsx - Agent run hook → LocalHost: requests stream
- LocalHost → Agent loop: runs agent
packages/core/src/host/local.ts - Agent loop → Model service: streams completion
packages/core/src/agent/loop.ts - Agent loop → Tool registry: dispatches tools
packages/core/src/agent/loop.ts - Agent loop → Permission gate: checks calls
packages/core/src/agent/loop.ts - Agent loop → Audit log: records calls
- Permission gate → Settings schema: reads policy
packages/core/src/permissions/gate.ts - Tool registry → Workspace tools: registers tools
- Agent loop → Message view: streams events
- React app → Model catalog: resolves model
apps/desktop/src/app/app.tsx - Settings UI → LocalHost: configures host
- Model catalog → Provider registry: looks up providers
packages/core/src/models/catalog-service.ts - LocalHost → Provider registry: selects provider
packages/core/src/host/local.ts - Provider registry → Zen provider: creates provider
packages/core/src/providers/registry.ts - Provider registry → Ollama provider: creates provider
- Zen provider → Provider HTTP: sends requests
packages/core/src/providers/zen/provider.ts - Ollama provider → Provider HTTP: sends requests
packages/core/src/providers/ollama/provider.ts - Zen provider → Model service: implements provider
packages/core/src/providers/zen/provider.ts - Ollama provider → Model service: implements provider
packages/core/src/providers/ollama/provider.ts - Desktop composition → LocalHost: composes host
- Desktop composition → Tauri host: uses native services
- Tauri host → OS keychain: stores secrets
- LocalHost → Repositories: persists data
packages/core/src/host/local.ts - Repositories → SQLite database: uses database port
- LocalHost → Settings schema: uses settings
packages/core/src/host/local.ts