mainloop

A single conversation to manage all of your AI sessions - that keeps working while you're away.

Your main conversation thread is the closest digital mapping to your own internal thread of consciousness. Everything else flows into a unified inbox that surfaces only what needs your attention.

Inspired by You Are The Main Thread — you are the bottleneck, so spawn parallel AI sessions and let them handle the work while you stay in flow.

Desktop	Mobile

How It Works

You (phone/laptop)
    │
    ▼
┌─────────────────────────────────────────────────────┐
│                   Main Thread                        │
│           Claude with spawn_session tool            │
│                                                      │
│   user@mainloop$ research X      ← inline sessions  │
│   ├── [research X] thinking...   ← threaded reply   │
│   └── [research X] here's what   ← notification     │
└──────────────┬────────────────┬─────────────────────┘
               │                │
       ┌───────▼──────┐  ┌──────▼───────┐
       │   Session 1  │  │   Session 2  │  ...
       │   (Claude)   │  │   (Opus)     │
       │              │  │              │
       │   Research   │  │  Feature dev │
       └──────────────┘  └──────────────┘

• Main thread: One continuous conversation — sessions spawn inline and surface results back
• Sessions: Background AI work with their own conversations; appear as colored threads in your timeline
• Notifications: Slack-style thread replies notify you when sessions need attention or complete
• Persistence: Conversations and sessions survive restarts via compaction + DBOS

Quick Start

# Copy example environment file and configure
cp .env.example .env
# Edit .env with your GitHub username (GHCR_USER) and domains

# Setup Claude credentials (Linux - interactive login)
make setup-claude-creds

# Start all services
make dev

# Frontend: http://localhost:3000
# Backend:  http://localhost:8000/docs

Production Deployment

# Copy and edit the production config example
cp k8s/apps/mainloop/overlays/prod/personal-config-patch.yaml.example \
   k8s/apps/mainloop/overlays/prod/personal-config-patch.yaml
# Edit with your domains and GitHub username

# Deploy to k8s
kubectl apply -k k8s/apps/mainloop/overlays/prod

Project Structure

mainloop/
├── backend/       # Python FastAPI + DBOS workflows
├── frontend/      # SvelteKit + Tailwind v4 (mobile-first responsive)
├── claude-agent/  # Claude Code CLI container
├── models/        # Shared Pydantic models
├── packages/ui/   # Design tokens + theme.css
└── k8s/           # Kubernetes manifests

UI

• Mobile: Bottom tab bar (Chat / Sessions)
• Desktop: Chat with always-visible Sessions sidebar

Chat — your main thread with inline sessions:

• Sessions spawn as colored thread blocks in your timeline
• Session messages appear as Slack-style thread notifications
• Click to expand inline or zoom to fullscreen view
• Terminal-style prompt: user@context$ with content on new line

Sessions — all background work in one place:

1. Active sessions (with live status)
2. Sessions needing input (questions, plan reviews)
3. Completed and failed sessions
4. Each session has its own conversation you can zoom into

Agent Workflow

Agents are sessions spawned for development tasks. Each agent gets its own K8s namespace for isolated iteration.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Spawn     │────►│    Work     │────►│     PR      │────►│    Close    │
│   (main)    │     │  (k8s ns)   │     │  (GitHub)   │     │  (summary)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       ▲                   │
       └───────────────────┘
         check in / spawn more

1. Spawn - Main thread creates agent for a task
2. Work - Agent iterates in its own K8s namespace (build, test, debug)
3. PR - Agent creates and merges GitHub PR when ready
4. Close - Agent posts summary back to main thread

You stay in main thread, checking in on agents and spawning new ones as needed.

Documentation

Specs (source of truth for app behavior):

• Chat - Main thread conversation
• Sessions - Background work and status
• Layout - Mobile and desktop views

Guides:

• Architecture - System design and data flow
• Development - Local setup and commands
• Contributing - How to contribute

License

This project is licensed under the Sustainable Use License v1.0 - a source-available license that allows free use for internal business, non-commercial, and personal purposes.