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(ask me): the question renders as markdown, and agents are told to write it
Larry Williamson9edf34ea800f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5e2b27a1..70c59087 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,18 @@ All notable changes to this project are documented here. The format is based on## [Unreleased]+### Added++- **The ASK ME card renders markdown.** Questions arrived with their asterisks and backticks on+ screen, because the card printed the raw text. It now renders the same way the file preview does:+ emphasis, bullets, `code`, tables, and links that open in the browser instead of navigating the+ app. The task detail's Q&A trail renders too, answers included. A single newline is still a line+ break, so a question written as plain text looks exactly as it did before. Raw HTML is still shown+ as text rather than parsed, which is what keeps agent-written markdown safe to display.+- **Agents are told to format what they ask you.** The orchestrator prompt and `PROTOCOL.md` now+ ask for a bold lead line, backticks around paths and commands, and bullets whenever a question has+ more than one option.+## [0.4.5] — 2026-08-22**The release that fixes the things you trusted and were quietly wrong.** Cost reporting was offdiff --git a/src/main/hive.ts b/src/main/hive.tsindex f3b9c03d..f6ae53c1 100644--- a/src/main/hive.ts+++ b/src/main/hive.ts@@ -1331,7 +1331,7 @@ export class HiveManager {: '';const godLine = meta.isGod? 'You are the GOD / ORCHESTRATOR of this hive — your job is to ORCHESTRATE, not to implement: maintain live situational awareness and delegate the work. (1) AWARENESS — always know what is going on: keep an accurate picture of every agent (active vs archived/idle), the task board, and all in-flight work; drain your inbox continually and triage every other agent\'s requests, answering clarifications so the team runs autonomously. (2) DELEGATE — decompose work and fan it out to the hive agents via their inboxes (route messages and assign owners; do not do their jobs); do NOT take on grunt implementation yourself. Stay aware of who is already on the floor and delegate OPPORTUNISTICALLY: BEFORE you spawn anything, CHECK THE LIVE ROSTER (active agents in registry.json + their state in fleet.json) and prefer routing to an EXISTING agent that fits — above all when the request names one ("ask Pam to…", "have Jim…"), route to that agent instead of reflexively creating a new one. Reuse an idle or already-running agent whose role matches; only spawn a fresh agent when no existing one is a sensible fit, and say that you checked. One capable owner beats a duplicate. (3) OWN ONLY THE IMPORTANT, high-leverage things — task decomposition, dispatch decisions, sign-offs, conflict resolution, branch integration, and final QA — and remain the sole scribe of board.md. You are otherwise fully autonomous — there is NO separate approval queue. For the genuinely critical (destructive actions, spending real money, scope changes, unresolvable conflicts), ask the human directly in your own session and let the tool-permission prompt gate the action; the human approves natively, including remotely from their phone via /remote-control. Keep the team unblocked. When you DISPATCH a task, write it as a 4-part contract so the agent can run autonomously: (1) OBJECTIVE — the concrete goal; (2) OUTPUT — the expected deliverable/format; (3) TOOLS — what to use or avoid, and any references to read instead of re-deriving; (4) BOUNDARIES — scope limits + the definition of done. Pass references (file paths, message ids, board sections), not pasted content — keep dispatches short.'- + ` MONITOR the floor by reading ${inRoot('fleet.json')} (live per-agent tokens, cost, status, last tool, breaker level, inbox backlog) and ${inRoot('registry.json')} — note that running 'claude agents' will NOT list your hive's sibling agents. A full Claude Code command reference is at ${inRoot('COMMANDS.md')} (slash commands act ONLY on your own session; CLI commands run in your shell and can target the fleet). You periodically receive scheduler / "Heartbeat" standup requests — on each, review every agent via fleet.json, re-engage anyone stalled, over-budget, or breaker-armed, and keep board.md and tasks.json accurate. In tasks.json, ALWAYS set each task's "assignee" to the worker's agent id the moment you dispatch it, and NEVER clear it on status changes — a done card must still say who did the work (the human reads the board by who-did-what). HUMAN FEEDBACK is first-class in the ledger: when a task can only proceed with the human's input — a QUESTION to answer OR an ACTION only the human can perform (create an account, approve a purchase, provide credentials/screenshots, test on their device) — set its status to "blocked" and append the concrete ask to the card's "humanQA" array (push {"q":"...","askedAt":"<iso>"}; phrase actions as clear to-dos; keep every past entry — the history documents the card's decisions). The harness surfaces open questions on the office floor's ASK ME board; the human's answer lands in the same entry ("a") AND arrives as an inbox message to you — read it, act on it, and unblock the card so work continues. Do NOT park human questions in separate files (no HumanQuestion.md) and never sit waiting on the human in your own session. Steward the token budget.`+ + ` MONITOR the floor by reading ${inRoot('fleet.json')} (live per-agent tokens, cost, status, last tool, breaker level, inbox backlog) and ${inRoot('registry.json')} — note that running 'claude agents' will NOT list your hive's sibling agents. A full Claude Code command reference is at ${inRoot('COMMANDS.md')} (slash commands act ONLY on your own session; CLI commands run in your shell and can target the fleet). You periodically receive scheduler / "Heartbeat" standup requests — on each, review every agent via fleet.json, re-engage anyone stalled, over-budget, or breaker-armed, and keep board.md and tasks.json accurate. In tasks.json, ALWAYS set each task's "assignee" to the worker's agent id the moment you dispatch it, and NEVER clear it on status changes — a done card must still say who did the work (the human reads the board by who-did-what). HUMAN FEEDBACK is first-class in the ledger: when a task can only proceed with the human's input — a QUESTION to answer OR an ACTION only the human can perform (create an account, approve a purchase, provide credentials/screenshots, test on their device) — set its status to "blocked" and append the concrete ask to the card's "humanQA" array (push {"q":"...","askedAt":"<iso>"}; phrase actions as clear to-dos; keep every past entry — the history documents the card's decisions). WRITE THE ASK SHORT AND IN MARKDOWN. The human reads it on a CARD, not in a terminal, so an ask longer than a short paragraph plus its options (roughly 700 characters) is a report, not a question — cut the narrative, keep the decision. Open with ONE **bold** sentence saying exactly what you need from them; put paths, commands, values and identifiers in \`backticks\`; give each option or step its own "-" bullet or "1." number; leave a blank line between paragraphs (a single newline is a line break, so each option stays on its own line). When the ask originates in another agent's report, REWRITE it into that shape — never paste the report body in as the question, and never make the human read the investigation to find the decision. The harness surfaces open questions on the office floor's ASK ME board; the human's answer lands in the same entry ("a") AND arrives as an inbox message to you — read it, act on it, and unblock the card so work continues. Do NOT park human questions in separate files (no HumanQuestion.md) and never sit waiting on the human in your own session. Steward the token budget.`: meta.isAssistant? 'You are Michael\'s PREP ASSISTANT. You will be handed short, possibly vague instructions (each begins with "ENRICH TASK:"). For each one: (1) figure out which project it concerns and cd into the most relevant repo — you start in Michael\'s home directory; (2) gather concrete context READ-ONLY (exact file paths, current state, relevant code, conventions, active branch, gotchas) — NEVER modify, create, or delete files; (3) rewrite the instruction into ONE clear, self-contained prompt that Michael can execute autonomously, preserving the user\'s original intent without inventing scope. Then deliver it: write ONE message JSON into your outbox with "to":"god", "act":"request", a short subject, and the finished prompt as the body. Do NOT perform the task yourself — your only output is the improved prompt sent to Michael.': 'For anything ambiguous, cross-cutting, or needing sign-off, address a message to "god".';@@ -2458,6 +2458,32 @@ There are two shared surfaces, both in the hive root:- \`tasks.json\` — the structured task ledger (a kanban: \`todo / doing / blocked / done\`, with title,assignee, priority, deps). Keep the task you're working reflected in its status.+## Asking the human (the ASK ME card)+When a card can only move with the human — a question to answer, or an action only they can do+(create an account, approve a spend, hand over credentials, test on their device) — the god sets the+card \`"status": "blocked"\` and appends the ask to its \`humanQA\` array:++\`\`\`json+{ "q": "the ask, in markdown", "askedAt": "<iso timestamp>" }+\`\`\`++The harness shows the open ask on the ASK ME board and in the ASK ME tab, and the human's reply lands+in the same entry as \`"a"\` plus an inbox message to god. Every past entry stays on the card — that+trail is the decision history.++**Write the ask short, and in markdown.** The card renders it, so plain-text asterisks and backticks+show up literally, and a card is not a terminal — an ask longer than a short paragraph plus its+options (roughly 700 characters) is a report, not a question. Cut the narrative and keep the decision:+- open with ONE **bold** sentence saying exactly what you need from them;+- \`backticks\` for paths, commands, values, and identifiers;+- \`-\` bullets or \`1.\` numbering for every option or step;+- a blank line between paragraphs; a single newline is rendered as a line break, so each option+ stays on its own line.++When the ask originates in another agent's report, REWRITE it into that shape. Never paste the report+body in as the question, and never make the human read the investigation to find the decision. Do NOT park human questions in separate files (no \`HumanQuestion.md\`),+and never sit idle waiting for a reply — move on to other work and pick the answer up when it arrives.+## Guardrails: circuit breaker & token budgetsA circuit breaker watches every agent for runaway behavior (looping on the same tool, error storms,overspending). It escalates gently: \`steer\` → \`constrain\` → \`stop\`. If a \`Circuit breaker: steer\`diff --git a/src/renderer/src/components/AskMeTab.tsx b/src/renderer/src/components/AskMeTab.tsxindex db1dd86f..06e655c5 100644--- a/src/renderer/src/components/AskMeTab.tsx+++ b/src/renderer/src/components/AskMeTab.tsx@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';import { PixelButton } from './PixelButton';import { PixelBadge } from './PixelBadge';import { useStore } from '@/store/store';+import { MarkdownPreview } from '@/markdown/MarkdownPreview';import { type HiveTask, type HumanQA, openQuestion, waitsOnHuman } from './TasksKanban';/**@@ -206,9 +207,13 @@ export function AskMeTab() {</div><div style={{ padding: 9, display: 'flex', flexDirection: 'column', gap: 8 }}>- {/* the question */}- <div style={{ fontSize: 15, lineHeight: '19px', color: 'var(--cth-ink-900)', whiteSpace: 'pre-wrap' }}>- {open.q}+ {/* The question, rendered as markdown. The god writes these with+ emphasis, lists, `code` and links; as plain text the asterisks+ and backticks were on screen literally. The card variant keeps+ this card's mono face and turns a single newline into a break, so+ a question with no markdown in it looks exactly as it did. */}+ <div style={{ fontSize: 15, lineHeight: '19px', color: 'var(--cth-ink-900)' }}>+ <MarkdownPreview source={open.q} variant="card" /></div>{/* answer box */}@@ -217,7 +222,7 @@ export function AskMeTab() {onChange={(e) => setAnswerDraft(t.id, e.target.value)}onKeyDown={(e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) void sendAnswer(t); }}rows={3}- placeholder="Your answer — or 'done', with the result… (Ctrl+Enter to send)"+ placeholder="Your answer — or 'done', with the result… (markdown ok · Ctrl+Enter to send)"style={{width: '100%', boxSizing: 'border-box', padding: '6px 8px', resize: 'vertical',background: 'var(--cth-paper-100)', border: 'none',diff --git a/src/renderer/src/components/TasksKanban.tsx b/src/renderer/src/components/TasksKanban.tsxindex f2b7aea6..89c2e056 100644--- a/src/renderer/src/components/TasksKanban.tsx+++ b/src/renderer/src/components/TasksKanban.tsx@@ -4,6 +4,7 @@ import { PixelButton } from './PixelButton';import { PixelBadge } from './PixelBadge';import { Icon } from './Icon';import { useStore } from '@/store/store';+import { MarkdownPreview } from '@/markdown/MarkdownPreview';/** A card on the task kanban. Mirrors HiveTask in the main/preload process —* re-declared locally so the renderer doesn't reach into the preload package@@ -349,7 +350,9 @@ export function TaskDetail({ task, all, assigneeName, onMove, onAssign, onClose{task.description?.trim() || <span style={{ color: 'var(--cth-ink-300)' }}>(no description on this card)</span>}</div>- {/* The human Q&A trail — every decision documented on the card */}+ {/* The human Q&A trail — every decision documented on the card.+ Rendered as markdown (card variant), matching the ASK ME tab the+ "view earlier answers" link arrives from. */}{(task.humanQA?.length ?? 0) > 0 && (<div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}><div style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, color: 'var(--cth-ink-500)' }}>@@ -358,21 +361,27 @@ export function TaskDetail({ task, all, assigneeName, onMove, onAssign, onClose{task.humanQA!.map((e, i) => (<div key={i} style={{ display: 'flex', flexDirection: 'column', gap: 2 }}><div style={{- padding: '5px 7px', background: 'var(--cth-lilac-light, #ece2f5)',+ display: 'flex', gap: 6, padding: '5px 7px',+ background: 'var(--cth-lilac-light, #ece2f5)',boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',- fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)', whiteSpace: 'pre-wrap'+ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)'}}>- <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, marginRight: 6 }}>Q</span>- {e.q}+ <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, flexShrink: 0, marginTop: 2 }}>Q</span>+ <div style={{ flex: 1, minWidth: 0 }}>+ <MarkdownPreview source={e.q} variant="card" />+ </div></div>{e.a ? (<div style={{- padding: '5px 7px', background: 'var(--cth-mint-light, #d9eed9)',+ display: 'flex', gap: 6, padding: '5px 7px',+ background: 'var(--cth-mint-light, #d9eed9)',boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',- fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)', whiteSpace: 'pre-wrap'+ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)'}}>- <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, marginRight: 6 }}>A</span>- {e.a}+ <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, flexShrink: 0, marginTop: 2 }}>A</span>+ <div style={{ flex: 1, minWidth: 0 }}>+ <MarkdownPreview source={e.a} variant="card" />+ </div></div>) : (<div style={{ fontSize: 11, color: 'var(--cth-coral)', fontFamily: 'var(--cth-font-display)' }}>diff --git a/src/renderer/src/design/global.css b/src/renderer/src/design/global.cssindex d3afc3c8..1c5c0d97 100644--- a/src/renderer/src/design/global.css+++ b/src/renderer/src/design/global.css@@ -261,3 +261,37 @@ canvas, img, svg { image-rendering: pixelated; image-rendering: crisp-edges; }background: var(--cth-cream-200); box-shadow: inset 0 0 0 1px var(--cth-ink-100);color: var(--cth-ink-500); border-radius: 2px;}++/* ─── Markdown inside a card (v0.4.6) ────────────────────────────────────────+ The same renderer, hosted in a surface that already has its own type: the+ ASK ME question and the task detail's Q&A trail. It inherits the host's face+ and size (the mono face those cards set, not the UI face) and drops the document+ chrome — no 72ch measure, no page padding — so a one-line question is still+ one line. Every size below is relative, so the host sets the scale. */+.cth-md-preview.cth-md-card {+ font-family: inherit; font-size: inherit; line-height: inherit;+ max-width: none; padding: 0;+ /* A long path or URL in an agent's question wraps rather than widening the+ card: the ASK ME column is narrow and does not scroll sideways. */+ overflow-wrap: anywhere;+}+.cth-md-card > :first-child { margin-top: 0; }+.cth-md-card > :last-child { margin-bottom: 0; }+.cth-md-card p { margin: 1.1em 0; }+.cth-md-card h1, .cth-md-card h2, .cth-md-card h3,+.cth-md-card h4, .cth-md-card h5 {+ margin: 0.8em 0 0.3em; border-bottom: none; padding-bottom: 0;+}+.cth-md-card h1 { font-size: 1.25em; }+.cth-md-card h2 { font-size: 1.15em; }+.cth-md-card h3, .cth-md-card h4, .cth-md-card h5 { font-size: 1.05em; }+.cth-md-card code { font-size: 0.9em; padding: 0 3px; }+.cth-md-card pre { margin: 0.5em 0; padding: 6px 8px; }+/* 22px, not less: the list marker is painted OUTSIDE the padding box, and a+ tighter indent clips "1." against the card's own 9px edge. */+.cth-md-card ul, .cth-md-card ol { padding-left: 22px; margin: 0.4em 0; }+.cth-md-card li { margin: 1px 0; }+.cth-md-card blockquote { margin: 0.5em 0; padding-left: 10px; }+.cth-md-card hr { margin: 0.8em 0; }+.cth-md-card table { margin: 0.5em 0; }+.cth-md-card th, .cth-md-card td { padding: 3px 7px; font-size: 0.9em; }diff --git a/src/renderer/src/markdown/MarkdownPreview.tsx b/src/renderer/src/markdown/MarkdownPreview.tsxindex f4a9b050..93ce7463 100644--- a/src/renderer/src/markdown/MarkdownPreview.tsx+++ b/src/renderer/src/markdown/MarkdownPreview.tsx@@ -1,7 +1,8 @@/*** Rendered markdown view (v0.3.4) — the shared preview used by the IDE's* split/preview modes, the fullscreen file overlay, and (via those) the- * terminal ⌘-click flow.+ * terminal ⌘-click flow. The `card` variant renders agent-written markdown+ * inside another surface: the ASK ME question and the task detail's Q&A trail.** SECURITY: agent-generated markdown is untrusted. react-markdown WITHOUT* rehype-raw renders to React elements only — no HTML sink exists, raw HTML in@@ -17,6 +18,19 @@ import ReactMarkdown from 'react-markdown';import remarkGfm from 'remark-gfm';import { useWorkspaceImage } from '@/hooks/useWorkspaceImage';import { isExternal, isRelativeMd, resolveLocalImageRel, resolveRel } from './mdLinks';+import { remarkSoftBreaks } from './remarkSoftBreaks';++/** How the rendered markdown sits in its host.+ * - `document` (default): a page — its own type scale, 72ch measure, page padding.+ * - `card`: markdown INSIDE another surface (an ASK ME question, a Q&A entry).+ * Inherits the host's font and size, drops the page chrome, and keeps a single+ * newline as a line break the way the plain-text block it replaced did. */+export type MarkdownVariant = 'document' | 'card';++// Hoisted: a fresh array on every render would make react-markdown re-run the+// whole pipeline even when nothing about the source changed.+const DOC_PLUGINS = [remarkGfm];+const CARD_PLUGINS = [remarkGfm, remarkSoftBreaks];export interface MarkdownPreviewProps {source: string;@@ -28,15 +42,18 @@ export interface MarkdownPreviewProps {root?: string;/** Open a sibling markdown file (repo-relative path) in the host's context. */onOpenMarkdownLink?: (rel: string) => void;+ /** Page vs in-card rendering. Defaults to `document`. */+ variant?: MarkdownVariant;}export const MarkdownPreview = memo(function MarkdownPreview({- source, baseRel, root, onOpenMarkdownLink+ source, baseRel, root, onOpenMarkdownLink, variant = 'document'}: MarkdownPreviewProps) {+ const card = variant === 'card';return (- <div className="cth-md-preview">+ <div className={card ? 'cth-md-preview cth-md-card' : 'cth-md-preview'}><ReactMarkdown- remarkPlugins={[remarkGfm]}+ remarkPlugins={card ? CARD_PLUGINS : DOC_PLUGINS}components={{a: ({ href, children }) => {const h = href ?? '';diff --git a/src/renderer/src/markdown/remarkSoftBreaks.ts b/src/renderer/src/markdown/remarkSoftBreaks.tsnew file mode 100644index 00000000..6d199c5c--- /dev/null+++ b/src/renderer/src/markdown/remarkSoftBreaks.ts@@ -0,0 +1,47 @@+/**+ * Treat a single newline as a line break.+ *+ * CommonMark folds a soft break into a space, so a question written as+ *+ * Do X first.+ * Then tell me about Y.+ *+ * renders as one run-on line. That is correct for a document, and wrong for a+ * card that used to be a `white-space: pre-wrap` block — the ASK ME question+ * and the task detail's Q&A trail both read as messages, not as prose files.+ * So the card variant of MarkdownPreview runs this and the document variant+ * does not.+ *+ * The walk only rewrites `text` nodes. Fenced and indented code are `code`+ * nodes carrying a raw `value` with no children, and inline code is+ * `inlineCode` — neither is touched, so newlines inside code survive as-is.+ */++interface MdNode {+ type: string;+ value?: string;+ children?: MdNode[];+}++function walk(node: MdNode): void {+ const children = node.children;+ if (!children) return;+ const out: MdNode[] = [];+ for (const child of children) {+ if (child.type === 'text' && typeof child.value === 'string' && child.value.includes('\n')) {+ const parts = child.value.split('\n');+ for (let i = 0; i < parts.length; i++) {+ if (i > 0) out.push({ type: 'break' });+ if (parts[i]) out.push({ type: 'text', value: parts[i] });+ }+ continue;+ }+ walk(child);+ out.push(child);+ }+ node.children = out;+}++export function remarkSoftBreaks() {+ return (tree: unknown): void => { walk(tree as MdNode); };+}