Lobs Dashboard

Native macOS SwiftUI application for managing personal and collaborative task workflows with AI assistance.

Screenshot placeholder - add actual screenshot to docs/screenshot.png

Overview

Lobs Dashboard is a macOS desktop app that provides a visual interface for managing tasks, projects, and research workflows. It integrates with a Git-based state repository (lobs-control) and an AI orchestrator that can autonomously pick up and execute tasks.

Key Features:

• 🎯 Kanban Board — Visual task management with customizable columns
• 📚 Research Projects — Tile-based workspace for notes, links, and findings
• 🤖 AI Task Execution — Tasks are picked up automatically by the orchestrator
• 🔄 Git-Backed Sync — All changes versioned and synchronized automatically
• 👥 GitHub Mode — Collaborate on tasks via GitHub Issues (optional)
• 📥 Inbox — Review and manage artifacts generated by AI workers
• 📊 Activity Dashboard — Track project progress and velocity

Architecture:

┌─────────────┐
│  Dashboard  │ (macOS SwiftUI app - you are here)
└──────┬──────┘
       │ Git sync
       ↓
┌─────────────────┐
│  lobs-control   │ (Git state repository)
└──────┬──────────┘
       │ Polling
       ↓
┌─────────────────┐
│  Orchestrator   │ (Python service on server)
└──────┬──────────┘
       │
       ↓
┌─────────────────┐
│  OpenClaw       │ (AI worker runtime)
└─────────────────┘

Prerequisites

• macOS 13.0+ (Ventura or later)
• Git with SSH key configured for GitHub
• GitHub account (for repository access)
• A server with OpenClaw set up (see Server Setup below)

Installation

Option 1: Download Release (Recommended)

1. Download the latest .dmg or .app from the Releases page
2. Open the downloaded file
3. Drag Lobs Dashboard to your Applications folder
4. Launch Lobs Dashboard from Applications

Option 2: Build from Source

# Clone the repository
git clone git@github.com:RafeSymonds/lobs-dashboard.git
cd lobs-dashboard

# Build the app
./bin/build

# Run directly
./bin/run

# Or open in Xcode
open Package.swift

User Data & Settings

All user-specific settings and preferences are stored in ~/.lobs/config.json (outside the dashboard repository).

What's stored locally:

• Control repository path and URL
• Onboarding completion status
• UI preferences (appearance, hotkeys, filters)
• Read state (inbox items, threads)
• Auto-refresh settings

Privacy & Safety:

• The dashboard repo contains zero user-specific data
• Safe to clone fresh, reset, or share publicly
• All your data lives in:
  • ~/.lobs/config.json (app settings)
  • Your lobs-control repository (tasks, projects, state)

Migration Note: If upgrading from an older version, settings will automatically migrate from UserDefaults to the new config file on first launch.

For more details, see SETTINGS_MIGRATION.md.

First-Time Setup

When you first launch Lobs Dashboard, you'll be guided through an onboarding wizard:

1. Clone the Control Repository

The dashboard requires a local checkout of your lobs-control state repository:

git clone git@github.com:YOUR-USERNAME/lobs-control.git ~/lobs-control

Note: Replace YOUR-USERNAME with your GitHub username. You can use a different path, but ~/lobs-control is recommended.

2. Configure Repository Path

In the dashboard:

1. Click Choose lobs-control…
2. Navigate to your lobs-control folder (e.g., ~/lobs-control)
3. Click Select

The dashboard will validate the repository structure and load your projects and tasks.

3. Enable Auto-Sync (Optional)

Enable automatic Git pull/push to keep your local state synchronized:

• Navigate to Settings (⌘,)
• Toggle Enable auto-sync
• Set your preferred sync interval (default: 30 seconds)

Server Setup

To enable AI task execution, you need a server running the Lobs orchestrator.

Orchestrator Repository

The orchestrator is a Python service that monitors your lobs-control repository and executes tasks using OpenClaw:

Repository: lobs-orchestrator

What Runs on the Server

• Orchestrator Service — Monitors for new work, manages task queue
• OpenClaw Runtime — AI agent execution environment
• Worker Agent — Single shared worker that executes tasks sequentially

Setup Guide

See the lobs-orchestrator README for:

• Installation prerequisites (Python 3.11+, OpenClaw)
• Configuration instructions
• Running as a systemd service
• Troubleshooting common issues

Optional: guided setup script (server):

This repository includes a simple interactive wizard you can run on your server to install OpenClaw + clone/configure the orchestrator:

# from a checkout of lobs-dashboard
./bin/server-setup-wizard

# or pass your control repo URL up-front
LOBS_CONTROL_REPO_URL=git@github.com:YOUR-USER/lobs-control.git ./bin/server-setup-wizard

OpenClaw Setup

The orchestrator requires OpenClaw to run the AI worker. See the official documentation:

• OpenClaw Installation
• Agent Configuration
• Worker Agent Setup

Usage

Creating Tasks

Quick Create:

1. Press ⌘N or click + New Task
2. Enter task title and description
3. Set status (active, waiting, blocked, or done)
4. Optionally assign to a project
5. Click Create

From Inbox:

1. Navigate to the Inbox tab
2. Review artifacts generated by AI workers
3. Click Create Task to convert an artifact into a trackable task

Working with Projects

Project Types:

• Kanban — Task-based workflow with columns (active, waiting, blocked, done)
• Research — Note-taking and research workflows with tile-based organization

Creating Projects:

1. Click + New Project
2. Choose project type (Kanban or Research)
3. Set project name and optional description
4. Configure sync mode (Local or GitHub)

GitHub Sync Mode:

To enable collaborative task management via GitHub Issues:

1. Create a GitHub Personal Access Token:

   • Go to GitHub Settings → Developer settings → Personal access tokens
   • Generate new token with repo scope
   • Copy the token

2. Configure project for GitHub mode:

   • Edit project settings
   • Set Sync Mode to GitHub
   • Enter repository owner and name
   • Paste your access token
   • Save changes

Tasks will now sync bidirectionally with GitHub Issues using label-based status tracking.

How Sync Works

Local Mode (Default):

• Tasks stored as JSON files in ~/lobs-control/state/tasks/
• Dashboard commits changes to Git
• Auto-push keeps state synchronized across devices
• Orchestrator polls for changes and picks up new work

GitHub Mode:

• Tasks synced with GitHub Issues
• Local JSON files act as cache
• GitHub is source of truth
• Labels map to task statuses (e.g., status:active, work:in_progress)

Git Flow:

Dashboard edit → Commit → Push → Server polls → Orchestrator picks up task

How AI Assistant Picks Up Tasks

1. Create a task in the dashboard with status active or waiting
2. Push changes (automatic if auto-sync is enabled)
3. Orchestrator detects new work via Git polling
4. Worker spawns and executes the task
5. Results written to artifacts/ or task notes
6. Status updated to completed or failed
7. Dashboard syncs and displays updated state

Requesting Immediate Attention:

Tasks are picked up automatically by the orchestrator on its next polling cycle.

Managing Task Lifecycle

Status Transitions:

• Active → Work the AI can pick up immediately
• Waiting → Blocked on external dependency (manual review)
• Blocked → Cannot proceed, needs intervention
• Done → Task completed successfully

Work States:

• not_started → Task queued but not yet assigned
• in_progress → Worker currently executing
• completed → Successfully finished
• failed → Worker encountered an error

Troubleshooting

Dashboard doesn't load tasks

Check repository path:

1. Go to Settings (⌘,)
2. Verify the repository path points to your lobs-control clone
3. Click Choose lobs-control… to reselect if needed

Validate repository structure:

cd ~/lobs-control
ls -la state/
# Should show: projects.json, tasks/, ...

Tasks not syncing to server

Verify Git remote:

cd ~/lobs-control
git remote -v
# Should show your GitHub repository

Check for unpushed commits:

git status
git log origin/main..HEAD

Manually push if needed:

git push origin main

AI worker not picking up tasks

Check orchestrator status:

# On your server
systemctl --user status lobs-orchestrator

View orchestrator logs:

journalctl --user -u lobs-orchestrator -f

Verify OpenClaw worker configuration:

openclaw agent list
# Should show "worker" agent

GitHub sync not working

Verify access token:

• Ensure token has repo scope
• Test token with: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

Check rate limits:

curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit

Review sync logs:

• Dashboard logs errors in the console
• Run from terminal to see detailed output: ./bin/run

How to reset/reconfigure

Reset repository path:

1. Quit Lobs Dashboard
2. Clear stored path:

   defaults delete com.rafesymonds.LobsDashboard repoPath

3. Relaunch dashboard and reconfigure

Clear all settings:

defaults delete com.rafesymonds.LobsDashboard

Rebuild state from Git:

cd ~/lobs-control
git fetch origin
git reset --hard origin/main

Development

Building from Source

Requirements:

• Xcode 15.0+ or Swift 5.9+
• macOS 13.0+ SDK

Build and run:

# Clone repository
git clone git@github.com:RafeSymonds/lobs-dashboard.git
cd lobs-dashboard

# Build
swift build

# Run
swift run

# Or use the build script (generates build info)
./bin/build && ./bin/run

Open in Xcode:

open Package.swift

Architecture Overview

Key Components:

• Models.swift — Data structures (Task, Project, SyncMode, etc.)
• Store.swift — Git-backed persistence and GitHub sync logic
• GitHubService.swift — GitHub API client (Issues CRUD, rate limiting)
• AppViewModel.swift — Main view model (state management, CRUD operations)
• ContentView.swift — Root view (sidebar, project picker, navigation)
• BoardView.swift — Kanban board implementation
• ResearchView.swift — Research project tile grid
• InboxView.swift — Artifact and document viewer

Data Flow:

View → ViewModel → Store → Git + GitHub → File System

Git Sync Strategy:

1. Pull latest changes from remote
2. Apply local modifications
3. Commit with descriptive message
4. Push to remote (with rebase retry on conflict)

GitHub Sync Strategy:

1. Create local task JSON file
2. Create GitHub issue with metadata comment
3. Apply labels for status tracking
4. On load: merge GitHub issues with local tasks

Project Structure

lobs-dashboard/
├── Sources/
│   └── LobsDashboard/
│       ├── Models.swift              # Data models
│       ├── Store.swift               # Persistence layer
│       ├── GitHubService.swift       # GitHub API
│       ├── AppViewModel.swift        # State management
│       ├── ContentView.swift         # Root view
│       ├── BoardView.swift           # Kanban board
│       ├── ResearchView.swift        # Research workspace
│       ├── InboxView.swift           # Artifact viewer
│       └── ...
├── Package.swift                     # Swift package manifest
├── bin/
│   ├── build                         # Build script
│   └── run                           # Run script
├── AGENTS.md                         # AI agent documentation
└── README.md                         # This file

Running Tests

No formal test suite currently. Validate changes by:

1. Building: swift build
2. Manual testing of modified features
3. Checking Git operations don't corrupt state

Contributing

Contributions are welcome! Please read our Contributing Guide for:

• Development setup and workflow
• Architecture patterns and best practices
• Common pitfalls and debugging tips
• Testing strategies
• Code style guidelines
• Pull request process

Quick Start for Contributors:

1. Fork the repository
2. Create a feature branch
3. Make your changes (see CONTRIBUTING.md for patterns)
4. Build and test: swift build && ./bin/run
5. Submit a pull request with clear description

Documentation

User Documentation

• README.md (this file) — Overview, installation, usage guide
• SETTINGS_MIGRATION.md — Settings architecture and migration from UserDefaults

Developer Documentation

• CONTRIBUTING.md — Development guide, common pitfalls, debugging
• COMMAND_PALETTE.md — Command palette (⌘K) usage and architecture
• PERFORMANCE_FIXES.md — Background loading and async patterns
• IMPLEMENTATION_NOTES.md — Recent implementation notes
• KEYBOARD_SHORTCUTS_UI.md — Keyboard shortcuts documentation

Design & Planning

• docs/ux-improvement-plan.md — UX improvements roadmap
• SETTINGS_AUDIT.md — Settings audit and verification
• CHANGES.md — Recent changes summary
• TASKS.md — Task tracking and planning

AI Agent Documentation

• AGENTS.md — AI agent workflow and guidelines

License

[License information to be added]

Support

• Issues: GitHub Issues
• Orchestrator Docs: lobs-orchestrator
• OpenClaw Docs: docs.openclaw.ai

---

Built with ❤️ using SwiftUI