Skip to content

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

docs: v0.3.4 implementation plan for the four researched features

Chaitanya Giri911a1ab74289
diff --git a/docs/research/v0.3.4-implementation-plan.md b/docs/research/v0.3.4-implementation-plan.md
new file mode 100644
index 00000000..c8881039
--- /dev/null
+++ b/docs/research/v0.3.4-implementation-plan.md
@@ -0,0 +1,89 @@
+# v0.3.4 Implementation Plan — the four researched features
+
+> Execution plan derived from `v0.3.5-feature-research.md` (architecture + rationale live
+> there). Owner decision 2026-08-06: ship all four IN v0.3.4, on `integrate/v0.3.4`.
+> Merge + tag happen only after explicit owner approval.
+
+## Order & scope
+
+### F1 — Markdown preview (first: fastest visible win)
+1. Deps: `react-markdown`, `remark-gfm`.
+2. `src/renderer/src/markdown/MarkdownPreview.tsx` — CTH-token styled (light+dark via
+ `useAppTheme`), GFM, NO rehype-raw; every anchor intercepted: http(s)/mailto →
+ `window.cth.openExternal`, relative `.md` → `onOpenMarkdownLink(rel)`, else inert.
+3. IDE: per-md-tab `view: 'code'|'split'|'preview'` (default split, localStorage-persisted);
+ 3-segment toggle in EditorBar (md only); preview renders live edit buffer via
+ `useDeferredValue`; md links open sibling tabs via `openEdit`.
+4. Overlay: store gains `fullscreenFileView: 'edit'|'preview'` (+ optional arg on
+ `setFullscreenFile`); FullscreenFileEditor gets edit|preview toggle (preview default when
+ opened from a terminal link); "open in IDE" button → new `ideInitialFile` store field,
+ consumed+cleared by IdePanel on mount. FilesTab editor gets the same toggle (FilesTab was
+ removed from tabs; its component remains used by FullscreenFileEditor only — verify).
+5. Terminal: `fs:stat` IPC (main/fs.ts `statPath` + index.ts handler + preload fn + d.ts —
+ 3-mirror gotcha); custom `ILinkProvider` registered in `acquireTerminal()`:
+ regex for absolute/`~`/relative `*.md` (tolerant of quotes/backticks/parens/`:line`),
+ resolve vs owning agent cwd (store lookup by ptyId), existence-verified (memoized),
+ **Cmd/Ctrl+click** → `setFullscreenFile(abs, 'preview')`.
+
+### F2 — Git visualization
+1. `git.ts`: `getLogGraph` (`--all --topo-order --skip`), `getCommitFiles`
+ (`diff-tree -r --root -z -M --name-status`, R/C handling), `getFileAtRev`
+ (any-rev `show`, 2MB cap + binary sniff, strict rev regex + `--`), `compareRefs`
+ (three-dot default + two-dot mode + left-right counts), `listWorktrees` (--porcelain),
+ `checkoutRef` (switch / switch --detach) — **main-side guards**: clean tree, no live
+ agent whose cwd resolves into the same repo root, worktree-held branches mapped to a
+ friendly error.
+2. IPC `git:logGraph/commitFiles/showFile/compareRefs/worktrees/checkout` + preload mirrors.
+3. IDE rail sub-tabs CHANGES · HISTORY · COMPARE:
+ - HISTORY: existing `git/CommitGraph.tsx` mounted at `mainRepoRoot`, `onCommitClick` →
+ commit file list (CHANGES row styling) → Monaco diff tabs (`commit::sha::path`,
+ sha^ vs sha), refresh on tab activation only (never the 4s poll).
+ - COMPARE: base/head selects + swap + ahead/behind + dot-mode toggle → file list →
+ diff tabs (`cmp::base::head::path`, merge-base vs head for three-dot).
+ - Checkout buttons on branch rows/commit rows behind guard dialogs; detached-HEAD notice.
+4. Remount slim `GitTab` as 4th sidebar tab (`git`).
+
+### F3 — Voice: live context + control
+1. Snapshot: replace thin `realtimeSessionSummary` with compact floor table
+ (name|status|action|ctx%|breaker|inbox + doing/blocked + missions count), injected as the
+ FIRST conversation item (sendMessage, triggerResponse:false) — instructions stay static.
+2. New read tools: `get_floor_state` (zustand store + agentDirectory merge, flagged JSON),
+ `get_app_info` (app version + top CHANGELOG section via IPC `app:info`).
+3. `src/main/realtimeFloorWatcher.ts` (sibling of completion watcher): coalesced deltas
+ (status flips, task moves, spawn/archive, breaker, ctx 70/90%), live-push channel →
+ renderer injects via the sanitized sendMessage path, debounce ≥10s, drop when closed.
+4. Verb spine extensions (realtimeActions.ts):
+ soft — `resume_agent`, `set_auto_delivery`, `gate_tool`, `delete_task`;
+ destructive — `clear_context` (main confirm → `realtime:enqueue` push → renderer
+ `enqueueMessage('/clear')`), `archive_agent` (archive destructive/unarchive soft),
+ `create_schedule`, `update_setting` (per-key policy table: forbidden = harnessHome +
+ secrets + providerBaseUrls + integrations; soft = notifications/themes/freeflow/idle/
+ keepalive; confirm = autoMode/defaultModel/god engine/worker caps/breaker/slack/webhook/
+ maxTurns; typed validation; old→new echo).
+5. Persona: preamble line ("say 'let me check…' while calling tools"), tool naming pass;
+ model const → `gpt-realtime-2.1`.
+6. DEFERRED (explicitly): `restart_agent` (needs CommandCenterPanel service extraction —
+ highest-risk; goes to next release).
+
+### F4 — Settings redesign
+1. Primitives: `settings/SettingRow.tsx` (+Section, Toggle, Advanced disclosure) with
+ `keywords` for search.
+2. Tabs: General (home+reset, appearance single theme control + office theme, notifications,
+ keep-awake, explain-simply/audience, auto-update; Adv: multiWindow) · Agents & Models
+ (defaultModel NEW, god engine, BYOK keys w/ unlock notes; Adv: base URLs, defaultCommand,
+ maxTurns) · Autonomy & Budgets (autoMode preset, FULL breaker incl. hardStop, floor budget
+ + velocity; Adv: worker fleet knobs) · Connections (MCP, Slack, Webhook, REST — collapsible
+ setup) · Voice (Free Flow + Realtime) · Memory & Knowledge (semantic+embedding, KG; Adv:
+ reflection basic).
+3. Config fixes: knowledgeGraph default false, freeflow seed bug, multiWindow comment/code
+ reconcile, remove costCapUsd (config.ts + consumers + 3-mirror).
+4. Search field in header; Danger Zone → red row in General.
+
+### F5 — Docs, site, verify, gate
+CHANGELOG [0.3.4] additions · RELEASE.md · README features · docs/index.html if needed ·
+typecheck + test:focused + suites + build + dev smoke · push · **ASK OWNER before merge+tag**.
+
+## Working rules
+- Commit per feature phase, typecheck green before every commit.
+- 3-file HarnessConfig mirror on every config field change.
+- No new renderer policy for voice — main owns all safety decisions.