an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
feat(onboarding): feature-aware first-run + permissions & reliability step
Chaitanya Giri84afd1493923
diff --git a/src/main/index.ts b/src/main/index.tsindex 104ff121..c5636a45 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -2179,6 +2179,24 @@ ipcMain.handle('github:ciRuns', (_evt, cwd: unknown) =>// ─── IPC: desktop notifications toggle ──────────────────────────────────────ipcMain.handle('app:setNotifications', (_evt, val) => writeConfig({ notifications: val === true }));+// ─── IPC: onboarding reliability — open Settings deep-link + login-item toggle ─+/** Open a System Settings deep-link (or https URL) in the OS default handler.+ * Restricted to Settings panes / https so the renderer can't shell arbitrary+ * schemes. Used by the onboarding "Permissions & reliability" step. */+ipcMain.handle('app:openExternal', async (_evt, url: unknown) => {+ if (typeof url !== 'string' || !/^(x-apple\.systempreferences:|https:\/\/)/.test(url)) {+ return { ok: false, error: 'blocked url' };+ }+ await shell.openExternal(url);+ return { ok: true };+});+/** Toggle macOS "Open at Login" — fully programmatic, no permission prompt.+ * Returns the resulting state so the renderer toggle reflects reality. */+ipcMain.handle('app:setLoginItem', (_evt, enabled: unknown) => {+ app.setLoginItemSettings({ openAtLogin: enabled === true });+ return app.getLoginItemSettings().openAtLogin;+});+// ─── IPC: Slack integration ─────────────────────────────────────────────────ipcMain.handle('slack:start', () => startSlackServer());ipcMain.handle('slack:stop', () => { stopSlackServer(); return { ok: true }; });diff --git a/src/preload/index.ts b/src/preload/index.tsindex 7c7d0831..f3ced960 100644--- a/src/preload/index.ts+++ b/src/preload/index.ts@@ -174,6 +174,9 @@ export interface HarnessConfig {opsStandupSeeded?: boolean;heartbeatSeeded?: boolean;notifications?: boolean;+ /** Opt-in strong keep-alive (prevent-display-sleep). Mirrors main + renderer+ * HarnessConfig so updateConfig({ strongKeepalive }) is typed across the bridge. */+ strongKeepalive?: boolean;slackEnabled?: boolean;slackSigningSecret?: string;slackBotToken?: string;@@ -744,6 +747,15 @@ const api = {setNotifications: (v: boolean): Promise<HarnessConfig> =>ipcRenderer.invoke('app:setNotifications', v),+ // ─── Reliability / OS integration (onboarding permissions step) ──────────────+ /** Open a System Settings deep-link (or https URL) in the OS handler. Main+ * restricts the scheme; the renderer just points at the pane. */+ openExternal: (url: string): Promise<{ ok: boolean; error?: string }> =>+ ipcRenderer.invoke('app:openExternal', url),+ /** Toggle macOS "Open at Login". Resolves to the resulting state (no prompt). */+ setLoginItem: (enabled: boolean): Promise<boolean> =>+ ipcRenderer.invoke('app:setLoginItem', enabled),+// ─── Agent lifecycle (archival) ─────────────────────────────────────────────/** Archive/unarchive a hive agent in the registry. Closing a terminal tab* archives it automatically via pty:kill; this is the explicit primitive. */diff --git a/src/renderer/src/components/OnboardingWizard.tsx b/src/renderer/src/components/OnboardingWizard.tsxindex 87685929..137147b1 100644--- a/src/renderer/src/components/OnboardingWizard.tsx+++ b/src/renderer/src/components/OnboardingWizard.tsx@@ -1,7 +1,7 @@import { useEffect, useState } from 'react';import { PixelPanel } from './PixelPanel';import { PixelButton } from './PixelButton';-import { Icon } from './Icon';+import { Icon, type IconName } from './Icon';import { SpritePortrait } from './SpritePortrait';import { AGENT_PROVIDER_PRESETS, modelsForProvider, type AgentProvider, type HarnessConfig } from '@/store/config';import { canReceiveInbox, providerPreset } from '@shared/agentProvider';@@ -10,7 +10,55 @@ export interface OnboardingWizardProps {onComplete: (config: HarnessConfig) => void;}-type Step = 'welcome' | 'home' | 'orchestrator' | 'repos' | 'auto' | 'done';+type Step = 'welcome' | 'home' | 'orchestrator' | 'repos' | 'auto' | 'permissions' | 'done';++// First-run showcase — the 4-6 highest-value features a brand-new user should+// understand before any setup. Kept to one scannable grid (not a manual).+interface Feature {+ icon: IconName;+ label: string;+ desc: string;+ tint: string; // tile background token+ edge: string; // tile border token+}+const FEATURES: Feature[] = [+ {+ icon: 'mcp',+ label: 'MULTI-PROVIDER HIVE',+ desc: 'Claude Code, Antigravity & Codex run as live agents in one shared office.',+ tint: 'var(--cth-lilac-light)', edge: 'var(--cth-lilac)'+ },+ {+ icon: 'gear',+ label: 'MICHAEL ORCHESTRATES',+ desc: 'An always-on GOD agent triages requests, routes tasks, and escalates only what needs you.',+ tint: 'var(--cth-sky-light)', edge: 'var(--cth-sky)'+ },+ {+ icon: 'web',+ label: 'LONG-TERM MEMORY',+ desc: 'Each agent keeps notes, mined into a shared, searchable MemPalace.',+ tint: 'var(--cth-mint-light)', edge: 'var(--cth-mint)'+ },+ {+ icon: 'terminal',+ label: 'COMMAND CENTER',+ desc: 'Terminal · Floor · Memory · Activity · Tasks · Schedules in one control surface.',+ tint: 'var(--cth-lemon-light)', edge: 'var(--cth-lemon)'+ },+ {+ icon: 'pause',+ label: 'GUARDRAILS',+ desc: 'Per-agent token budgets, a steer→constrain→stop circuit breaker, and human approvals.',+ tint: 'var(--cth-coral-light)', edge: 'var(--cth-coral)'+ },+ {+ icon: 'sparkle',+ label: 'READY-MADE HIRES',+ desc: 'Grab a pre-configured agent from the Agent Gallery and spawn it in one click.',+ tint: 'var(--cth-peach-light)', edge: 'var(--cth-peach)'+ }+];export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {const [step, setStep] = useState<Step>('welcome');@@ -24,6 +72,31 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {const [error, setError] = useState<string | undefined>();const [busy, setBusy] = useState(false);+ // Permissions & reliability toggles. These apply IMMEDIATELY on change (their+ // own IPC / OS state) — they are NOT part of finish()'s config write. First-run+ // defaults: notifications off (config default), login-item off (fresh install);+ // each reconciles to the real state the IPC returns.+ const [strongKeepalive, setStrongKeepalive] = useState(false);+ const [notifications, setNotifications] = useState(false);+ const [openAtLogin, setOpenAtLogin] = useState(false);++ const toggleStrongKeepalive = async (v: boolean) => {+ setStrongKeepalive(v); // optimistic+ try { setStrongKeepalive((await window.cth.updateConfig({ strongKeepalive: v })).strongKeepalive === true); }+ catch { setStrongKeepalive(!v); }+ };+ const toggleNotifications = async (v: boolean) => {+ setNotifications(v); // optimistic+ try { await window.cth.setNotifications(v); }+ catch { setNotifications(!v); } // revert on failure+ };+ const toggleOpenAtLogin = async (v: boolean) => {+ setOpenAtLogin(v); // optimistic+ try { setOpenAtLogin(await window.cth.setLoginItem(v)); } // reconcile to OS truth+ catch { setOpenAtLogin(!v); }+ };+ const openSettings = (url: string) => { void window.cth.openExternal(url); };+// Default-suggest a sensible harness home on first renderuseEffect(() => {if (!home) {@@ -87,11 +160,12 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {<PixelPanelvariant="dialog"title={- step === 'welcome' ? 'WELCOME'- : step === 'home' ? 'STEP 1 OF 4 · HARNESS HOME'- : step === 'orchestrator' ? "STEP 2 OF 4 · MICHAEL'S ENGINE"- : step === 'repos' ? 'STEP 3 OF 4 · YOUR REPOS'- : step === 'auto' ? 'STEP 4 OF 4 · AUTO MODE'+ step === 'welcome' ? 'MEET YOUR OFFICE'+ : step === 'home' ? 'STEP 1 OF 5 · HARNESS HOME'+ : step === 'orchestrator' ? "STEP 2 OF 5 · MICHAEL'S ENGINE"+ : step === 'repos' ? 'STEP 3 OF 5 · YOUR REPOS'+ : step === 'auto' ? 'STEP 4 OF 5 · AUTO MODE'+ : step === 'permissions' ? 'STEP 5 OF 5 · PERMISSIONS & RELIABILITY': 'ALL SET'}noPadding@@ -102,7 +176,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {<><div style={{ display: 'flex', gap: 12, alignItems: 'center' }}><div style={{- width: 64, height: 64,+ width: 56, height: 56, flexShrink: 0,background: 'var(--cth-sky-light)',boxShadow: 'inset 0 0 0 2px var(--cth-ink-900)',display: 'flex', alignItems: 'flex-end', justifyContent: 'center', overflow: 'hidden'@@ -112,18 +186,43 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {<div><div style={{fontFamily: 'var(--cth-font-display)',- fontSize: 12, lineHeight: '20px'- }}>HI, I'M YOUR HARNESS</div>- <div style={{ fontSize: 14, color: 'var(--cth-ink-700)' }}>- A control room for the Claude Code agents you run on this machine.+ fontSize: 12, lineHeight: '18px'+ }}>A CONTROL ROOM FOR A TEAM OF AGENTS</div>+ <div style={{ fontSize: 13, color: 'var(--cth-ink-700)', lineHeight: '18px' }}>+ You run a hive of AI coding agents — coordinated, persistent, and watchable.+ Here's what's inside:</div></div></div>- <p style={{ margin: 0, lineHeight: '22px' }}>- We're going to set up a folder where the harness lives, add the project repos- you want agents to work on, and confirm that agents should run unattended.- Three quick steps.- </p>++ <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 8 }}>+ {FEATURES.map((f) => (+ <div key={f.label} style={{+ display: 'flex', gap: 10, alignItems: 'flex-start',+ padding: 10,+ background: f.tint,+ boxShadow: `inset 0 0 0 2px ${f.edge}`+ }}>+ <div style={{+ width: 28, height: 28, flexShrink: 0,+ display: 'flex', alignItems: 'center', justifyContent: 'center',+ background: 'var(--cth-paper-100)',+ boxShadow: 'inset 0 0 0 1px var(--cth-ink-900)'+ }}>+ <Icon name={f.icon} />+ </div>+ <div style={{ minWidth: 0 }}>+ <div style={{+ fontFamily: 'var(--cth-font-display)',+ fontSize: 10, lineHeight: '14px', marginBottom: 3+ }}>{f.label}</div>+ <div style={{ fontSize: 12, lineHeight: '16px', color: 'var(--cth-ink-700)' }}>+ {f.desc}+ </div>+ </div>+ </div>+ ))}+ </div></>)}@@ -160,8 +259,9 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {{step === 'orchestrator' && (<><p style={{ margin: 0, lineHeight: '22px' }}>- <strong>Michael</strong> coordinates the whole floor — he triages your requests,- assigns tasks, and manages the team. Give him a longer-context, higher-capability model.+ <strong>Michael</strong>, the orchestrator you just met, coordinates the whole floor —+ he triages your requests, assigns tasks, and manages the team. Give him a+ longer-context, higher-capability model.</p><div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>{AGENT_PROVIDER_PRESETS.filter((p) => canReceiveInbox(p.id)).map((p) => (@@ -303,6 +403,84 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {</>)}+ {step === 'permissions' && (+ <>+ <p style={{ margin: 0, lineHeight: '22px' }}>+ Your agents keep working on a schedule and in live terminals. The+ harness already holds a light power blocker, but if your Mac fully+ sleeps — lid closed or idle — those timers pause and{' '}+ <strong>catch up the moment you're back</strong>. Nothing is lost; it+ may just run late. These keep you in the loop and, optionally, keep+ missions firing on time while you're away.+ </p>++ <ToggleRow+ icon="clock"+ label="KEEP WORKING WHILE AWAY"+ desc="Strong keep-alive: stops your Mac from sleeping while an agent is live, so schedules and terminals fire on time even when you step away. Uses more battery — best on power. Off by default."+ on={strongKeepalive}+ tint="var(--cth-mint-light)"+ edge="var(--cth-mint)"+ onChange={toggleStrongKeepalive}+ />++ <ToggleRow+ icon="bell"+ label="DESKTOP NOTIFICATIONS"+ desc="Get pinged when an agent needs you or a terminal needs reviving — even while you're away. macOS asks permission the first time one fires."+ on={notifications}+ tint="var(--cth-peach-light)"+ edge="var(--cth-peach)"+ onChange={toggleNotifications}+ />++ <ToggleRow+ icon="play"+ label="OPEN AT LOGIN"+ desc="Relaunch the harness after a reboot so scheduled missions resume on their own. No prompt — applies immediately."+ on={openAtLogin}+ tint="var(--cth-sky-light)"+ edge="var(--cth-sky)"+ onChange={toggleOpenAtLogin}+ />++ {/* LEVER 4 — instruction-only: macOS won't let the app flip Energy, so we deep-link the pane. */}+ <div style={{+ display: 'flex', gap: 10, alignItems: 'flex-start', padding: 10,+ background: 'var(--cth-lemon-light)',+ boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)'+ }}>+ <span style={{+ width: 28, height: 28, flexShrink: 0, display: 'flex',+ alignItems: 'center', justifyContent: 'center',+ background: 'var(--cth-paper-100)', boxShadow: 'inset 0 0 0 1px var(--cth-ink-900)'+ }}>+ <Icon name="gear" />+ </span>+ <div style={{ minWidth: 0, display: 'flex', flexDirection: 'column', gap: 8 }}>+ <div>+ <div style={{ fontFamily: 'var(--cth-font-display)', fontSize: 10, lineHeight: '14px', marginBottom: 3 }}>+ STAY AWAKE ON POWER (MANUAL)+ </div>+ <div style={{ fontSize: 12, lineHeight: '16px', color: 'var(--cth-ink-700)' }}>+ macOS only lets you set this one yourself. In Battery → Options,+ turn on “Prevent automatic sleeping when the display is off” (on+ power adapter) so timers keep firing with the display asleep.+ Without a sleep-preventing setting the Mac still truly sleeps —+ work survives and catches up on wake.+ </div>+ </div>+ <PixelButton variant="secondary" size="sm"+ onClick={() => openSettings('x-apple.systempreferences:com.apple.preference.battery')}>+ <span style={{ display: 'inline-flex', gap: 6, alignItems: 'center' }}>+ <Icon name="arrow-right" /> open Battery settings+ </span>+ </PixelButton>+ </div>+ </div>+ </>+ )}+{error && (<div style={{padding: '6px 10px',@@ -322,12 +500,12 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {back</PixelButton>)}- {step !== 'auto' && (+ {step !== 'permissions' && (<PixelButton variant="primary" size="md" onClick={() => setStep(nextStep(step))}>- {step === 'welcome' ? "let's go" : 'next'}+ {step === 'welcome' ? 'set it up' : 'next'}</PixelButton>)}- {step === 'auto' && (+ {step === 'permissions' && (<PixelButton variant="primary" size="md" onClick={finish} disabled={busy}>{busy ? 'saving...' : 'finish'}</PixelButton>@@ -341,8 +519,49 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {);}+function ToggleRow({ icon, label, desc, on, tint, edge, onChange }: {+ icon: IconName;+ label: string;+ desc: string;+ on: boolean;+ tint: string; // background token when on+ edge: string; // border token when on+ onChange: (v: boolean) => void;+}) {+ return (+ <label style={{+ display: 'flex', gap: 10, alignItems: 'flex-start', padding: 10,+ background: on ? tint : 'var(--cth-paper-100)',+ boxShadow: `inset 0 0 0 ${on ? 2 : 1}px ${on ? edge : 'var(--cth-ink-300)'}`,+ cursor: 'pointer'+ }}>+ <input+ type="checkbox"+ checked={on}+ onChange={(e) => onChange(e.target.checked)}+ style={{ width: 18, height: 18, flexShrink: 0, marginTop: 5 }}+ />+ <span style={{+ width: 28, height: 28, flexShrink: 0, display: 'flex',+ alignItems: 'center', justifyContent: 'center',+ background: 'var(--cth-paper-100)', boxShadow: 'inset 0 0 0 1px var(--cth-ink-900)'+ }}>+ <Icon name={icon} />+ </span>+ <span style={{ minWidth: 0 }}>+ <span style={{ display: 'block', fontFamily: 'var(--cth-font-display)', fontSize: 10, lineHeight: '14px', marginBottom: 3 }}>+ {label}+ </span>+ <span style={{ display: 'block', fontSize: 12, lineHeight: '16px', color: 'var(--cth-ink-700)' }}>+ {desc}+ </span>+ </span>+ </label>+ );+}+function Dots({ step }: { step: Step }) {- const order: Step[] = ['welcome', 'home', 'orchestrator', 'repos', 'auto'];+ const order: Step[] = ['welcome', 'home', 'orchestrator', 'repos', 'auto', 'permissions'];return (<div style={{ display: 'flex', gap: 4 }}>{order.map((s) => (@@ -357,10 +576,10 @@ function Dots({ step }: { step: Step }) {}function nextStep(s: Step): Step {- return s === 'welcome' ? 'home' : s === 'home' ? 'orchestrator' : s === 'orchestrator' ? 'repos' : s === 'repos' ? 'auto' : 'done';+ return s === 'welcome' ? 'home' : s === 'home' ? 'orchestrator' : s === 'orchestrator' ? 'repos' : s === 'repos' ? 'auto' : s === 'auto' ? 'permissions' : 'done';}function prevStep(s: Step): Step {- return s === 'auto' ? 'repos' : s === 'repos' ? 'orchestrator' : s === 'orchestrator' ? 'home' : s === 'home' ? 'welcome' : 'welcome';+ return s === 'permissions' ? 'auto' : s === 'auto' ? 'repos' : s === 'repos' ? 'orchestrator' : s === 'orchestrator' ? 'home' : s === 'home' ? 'welcome' : 'welcome';}const inputStyle: React.CSSProperties = {diff --git a/src/renderer/src/store/config.ts b/src/renderer/src/store/config.tsindex 717b3a6a..f5b65b90 100644--- a/src/renderer/src/store/config.ts+++ b/src/renderer/src/store/config.ts@@ -66,6 +66,11 @@ export interface HarnessConfig {opsStandupSeeded?: boolean;heartbeatSeeded?: boolean;notifications?: boolean;+ /** Opt-in "strong keep-alive": escalates the in-app power blocker to+ * prevent-display-sleep so scheduled missions/terminals keep firing on time+ * while away (battery cost; best on AC). Default off = survive + catch up on+ * resume. Mirrors the main-process field (src/main/config.ts). */+ strongKeepalive?: boolean;slackEnabled?: boolean;slackSigningSecret?: string;slackBotToken?: string;