heartcode 0.0.0-stage → 0.1.1

package/src/headless.js

@@ -0,0 +1,218 @@
+// Headless mode (heartcode -p): for other programs to run HeartCode, the way they run Claude Code.
+// Same flags and the same output as `claude -p`, so a program that drives Claude Code (like
+// Nibedita) drives HeartCode by changing the command name:
+//   heartcode -p "fix the test"                                   the answer on stdout
+//   heartcode -p --output-format json "…"                         one JSON result
+//   heartcode -p --input-format stream-json --output-format stream-json
+//       stdin:  {"type":"user","message":{"role":"user","content":"…"}}   one per line, any number
+//               {"type":"control_request","request_id":"1","request":{"subtype":"interrupt"}}
+//       stdout: {"type":"system","subtype":"init",…}, {"type":"assistant",…}, {"type":"user",…}
+//               (tool results), {"type":"result",…} after each message
+// Nothing asks anything: what the permission mode would ask about is declined, with the reason
+// told to the model. Logs and warnings go to stderr (and HEART_LOG), never stdout.
+import readline from 'node:readline'
+import { log } from './log.js'
+import { clip, TOOL_DEFS, extraTools, loadMcpTools } from './tools.js'
+import { allowed } from './agent.js'
+
+// Claude Code's tool names → HeartCode's (for --allowedTools / --disallowedTools).
+const CLAUDE_TOOLS = { Read: 'read_file', Grep: 'search', Glob: 'list_files', LS: 'list_files', Edit: 'edit_file', MultiEdit: 'edit_file', Write: 'write_file', NotebookEdit: 'edit_file', Bash: 'run_command' }
+export function toolNames(list) {
+  const names = list.flatMap((x) => String(x).split(/[,\s]+/)).filter(Boolean).map((t) => t.replace(/\(.*$/, '')) // ponytail: "Bash(git:*)" allows every command, not just git
+  return new Set(names.map((t) => CLAUDE_TOOLS[t] ?? t)) // mcp__server__tool and mcp__server as they are (tools.js allowed)
+}
+
+// --permission-mode, in HeartCode's terms or Claude Code's.
+export const PERMISSION_MODES = { all: 'all', commands: 'commands', ask: 'ask', bypassPermissions: 'all', acceptEdits: 'commands', default: 'ask', plan: 'plan', dontAsk: 'ask' }
+
+// A UI that shows nothing and asks nobody.
+export class HeadlessUI {
+  constructor({ permission = 'all', verbose = false } = {}) {
+    Object.assign(this, { permission, verbose, log: [], showThinking: true, full: false, noUser: true })
+  }
+  #err(text) {
+    if (this.verbose) process.stderr.write(`${text}\n`)
+  }
+  warn(text) {
+    log('warn', text)
+    this.#err(`heartcode: ${text}`)
+  }
+  retrying(err, ms, attempt) {
+    if (err) this.#err(`heartcode: retrying in ${Math.ceil(ms / 1000)}s (attempt ${attempt}): ${err.message}`)
+  }
+  async confirm(question, kind = 'edit') {
+    if (this.permission === 'all' || (this.permission === 'commands' && kind === 'edit') || (this.permission === 'plan' && kind === 'read')) return true // plan: only reading
+    log('headless', `declined: ${question}`)
+    return `Not allowed: HeartCode runs headless with permission mode "${this.permission}", so this can't be approved. Don't retry it; say in your reply what you would have done.`
+  }
+  setPermission(mode) {
+    this.permission = mode
+  }
+  response() {
+    return { text() {}, think() {}, end() {} }
+  }
+  async ask() {
+    return null
+  }
+  async pick() {
+    return null
+  }
+  spinner() {}
+  stopSpin() {}
+  print() {}
+  write() {}
+  gap() {}
+  step() {}
+  result() {}
+  busy() {}
+  idle() {}
+  render() {}
+  notice() {}
+  refreshMenu() {}
+  cancelAsk() {}
+  clear() {}
+  setLog() {}
+  close() {}
+  leaveFullscreen() {}
+}
+
+// Runs the messages (prompt, or stdin) and writes the output. Returns the exit code.
+// app: the App (bin/heartcode.js); opts: { prompt, input, output, appendSystem }
+export async function runHeadless(app, opts) {
+  const out = opts.output ?? 'text'
+  const emit = (obj) => process.stdout.write(JSON.stringify(obj) + '\n')
+  const s = await app.session()
+  if (!s) {
+    const error = 'no model set up: add a provider and choose a model (heart settings), or pass --base-url and --model'
+    if (out === 'text') process.stderr.write(`heartcode: ${error}\n`)
+    else emit({ type: 'result', subtype: 'error_during_execution', is_error: true, result: error, num_turns: 0, session_id: app.chat.id })
+    return 1
+  }
+  s.appendSystem = opts.appendSystem || undefined
+  const session_id = app.chat.id
+  const model = `${app.cfg.provider}/${s.client.model}`
+
+  // usage and request count, over everything this message sends (tool loop, compaction, memory)
+  let usage = { input_tokens: 0, output_tokens: 0 }
+  let requests = 0
+  const chat = s.client.chat.bind(s.client)
+  s.client.chat = async (...a) => {
+    const r = await chat(...a)
+    requests++
+    usage.input_tokens += r.usage?.prompt_tokens ?? 0
+    usage.output_tokens += r.usage?.completion_tokens ?? 0
+    return r
+  }
+
+  let said = false // the model's text was already sent as an assistant message
+  if (out === 'stream-json') {
+    s.onEvent = (e) => {
+      if (e.type === 'assistant') {
+        const content = [
+          ...(e.reasoning ? [{ type: 'thinking', thinking: e.reasoning }] : []),
+          ...(e.content ? [{ type: 'text', text: e.content }] : []),
+          ...e.toolCalls.map((t) => ({ type: 'tool_use', id: t.id, name: t.function.name, input: parseArgs(t.function.arguments) })),
+        ]
+        if (e.content) said = true
+        if (content.length) emit({ type: 'assistant', message: { role: 'assistant', model, content }, session_id })
+      } else if (e.type === 'tool') {
+        emit({ type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: e.id, content: e.output, is_error: e.output.startsWith('error') }] }, session_id })
+      }
+    }
+    if (s.strat.actions === 'tools' && s.mcp?.names.length) await loadMcpTools(s) // their tools are in the list, as in Claude Code's
+    const tools = s.strat.actions === 'tools' ? [...TOOL_DEFS, ...extraTools(s)].map((f) => f.name).filter((n) => allowed(s, n)) : []
+    emit({ type: 'system', subtype: 'init', session_id, model, cwd: app.root, tools, mcp_servers: app.mcp.names.map((name) => ({ name, status: s.mcpCatalog?.has(name) ? 'connected' : 'pending' })), permissionMode: app.ui.permission, apiKeySource: 'none' })
+  }
+
+  let current = null // the message running now: { ctl }
+  const turn = async (text, images = []) => {
+    const t0 = Date.now()
+    const spent = app.chat.usage?.cost ?? 0
+    usage = { input_tokens: 0, output_tokens: 0 }
+    requests = 0
+    said = false
+    current = { ctl: new AbortController() }
+    app.signal = current.ctl.signal
+    let answer = ''
+    let error = null
+    try {
+      const k = /^\/(\S+)\s*([\s\S]*)$/.exec(text)
+      const skill = k && app.skills.get(k[1])
+      answer = await s.run(skill && skill.use !== 'model' ? await app.expandSkill(skill, k[2]) : text, current.ctl.signal, images)
+    } catch (e) {
+      error = current.ctl.signal.aborted ? 'interrupted' : e.message
+      if (e.maxTurns) current.maxTurns = true
+      log('error', error, e.stack)
+    } finally {
+      app.save()
+    }
+    const subtype = current.maxTurns ? 'error_max_turns' : error ? 'error_during_execution' : 'success' // as Claude Code names them
+    current = null
+    const result = { type: 'result', subtype, is_error: Boolean(error), result: error ?? answer, num_turns: Math.max(1, requests), duration_ms: Date.now() - t0, total_cost_usd: (app.chat.usage?.cost ?? 0) - spent, usage, modelUsage: { [model]: { inputTokens: usage.input_tokens, outputTokens: usage.output_tokens } }, session_id }
+    if (out === 'stream-json') {
+      if (!error && answer && !said) emit({ type: 'assistant', message: { role: 'assistant', model, content: [{ type: 'text', text: answer }] }, session_id }) // guided mode
+      emit(result)
+    } else if (out === 'json') emit(result)
+    else if (error) process.stderr.write(`heartcode: ${error}\n`)
+    else process.stdout.write(answer.trim() + '\n')
+    return !error
+  }
+
+  if (opts.input !== 'stream-json') {
+    const text = opts.prompt || (process.stdin.isTTY ? '' : await readAll(process.stdin))
+    if (!text.trim()) {
+      process.stderr.write('heartcode: -p needs a prompt (as an argument or on stdin)\n')
+      return 1
+    }
+    return (await turn(text.trim())) ? 0 : 1
+  }
+
+  // stream-json: messages one per line, in order; an interrupt stops the one running
+  let ok = true
+  let queue = Promise.resolve()
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity })
+  for await (const line of rl) {
+    if (!line.trim()) continue
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      log('headless', `not JSON: ${clip(line, 200)}`)
+      continue
+    }
+    if (msg.type === 'control_request') {
+      if (msg.request?.subtype === 'interrupt') current?.ctl.abort()
+      emit({ type: 'control_response', response: { subtype: 'success', request_id: msg.request_id } })
+      continue
+    }
+    if (msg.type !== 'user') continue
+    const { text, images } = contentOf(msg.message?.content)
+    queue = queue.then(() => turn(text, images)).then((r) => (ok = r))
+  }
+  await queue
+  return ok ? 0 : 1
+}
+
+// A message's content: a string, or blocks of text and images (Claude's or OpenAI's shape).
+export function contentOf(content) {
+  if (typeof content === 'string') return { text: content, images: [] }
+  const blocks = Array.isArray(content) ? content : []
+  return {
+    text: blocks.filter((b) => b.type === 'text').map((b) => b.text).join('\n'),
+    images: blocks.flatMap((b) => (b.type === 'image' && b.source?.data ? [`data:${b.source.media_type ?? 'image/png'};base64,${b.source.data}`] : b.type === 'image_url' ? [b.image_url?.url ?? b.image_url] : [])),
+  }
+}
+
+function parseArgs(text) {
+  try {
+    return JSON.parse(text || '{}')
+  } catch {
+    return { raw: text }
+  }
+}
+
+async function readAll(stream) {
+  let text = ''
+  for await (const ch of stream) text += ch
+  return text
+}

package/src/hooks.js

@@ -0,0 +1,80 @@
+// Hooks: your own commands, run at points in HeartCode's work, in Claude Code's format (so hooks
+// from it work here too). From ~/.heart/hooks.json and .heartcode/hooks.json (both, global first):
+//   { "hooks": { "PreToolUse": [ { "matcher": "edit_file|write_file", "hooks": [ { "type": "command", "command": "./check.sh", "timeout": 60 } ] } ] } }
+// Events:
+//   UserPromptSubmit  before a message goes to the model; exit 2 blocks it, stdout is added to it
+//   PreToolUse        before a tool runs (matcher: the tool's name); exit 2 blocks it, stderr is the reason
+//   PostToolUse       after a tool ran; exit 2 tells the model stderr (e.g. lint errors)
+//   Stop              when the model is done; exit 2 makes it carry on, with stderr as the reason
+// The command gets the event as JSON on stdin (session_id, cwd, hook_event_name, tool_name,
+// tool_input, tool_response, prompt, stop_hook_active), runs in the project folder, and can also
+// answer with JSON on stdout: {"decision": "block", "reason": "…"} (or "continue": false).
+// Matchers are regexes, tested against HeartCode's tool names and Claude Code's (Edit, Bash, …).
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME, readConfig } from './config.js'
+import { runCommand, clip } from './tools.js'
+import { log } from './log.js'
+
+export const EVENTS = ['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop']
+
+// HeartCode's tool names → Claude Code's, for matchers and tool_input written for Claude Code.
+export const CLAUDE_NAMES = { read_file: 'Read', edit_file: 'Edit', write_file: 'Write', run_command: 'Bash', search: 'Grep', list_files: 'Glob', web_fetch: 'WebFetch', web_search: 'WebSearch', todo: 'TodoWrite', agent: 'Task' }
+
+export const hookFiles = (root) => [path.join(HOME, 'hooks.json'), path.join(root, '.heartcode', 'hooks.json')]
+
+// { event: [{ matcher, command, timeout, file }] }
+export function loadHooks(root) {
+  const out = {}
+  const sources = hookFiles(root).filter((f) => fs.existsSync(f)).map((file) => ({ hooks: readConfig(file, {}), file }))
+  for (const { hooks: cfg, file } of sources) {
+    for (const [event, groups] of Object.entries(cfg.hooks ?? cfg)) {
+      if (!EVENTS.includes(event)) {
+        log('hooks', `${file}: unknown event ${event} (known: ${EVENTS.join(', ')})`)
+        continue
+      }
+      for (const g of [groups].flat()) {
+        for (const h of g?.hooks ?? []) if (h?.command) (out[event] ??= []).push({ matcher: g.matcher ?? '', command: h.command, timeout: Number(h.timeout) || 60, file })
+      }
+    }
+  }
+  return out
+}
+
+const matches = (matcher, tool) => {
+  if (!matcher || matcher === '*' || !tool) return true
+  try {
+    const re = new RegExp(`^(?:${matcher})$`)
+    return re.test(tool) || re.test(CLAUDE_NAMES[tool] ?? '') || (tool === 'mcp' && /^mcp__/.test(matcher))
+  } catch {
+    return matcher === tool
+  }
+}
+
+// Runs the event's hooks (those matching `tool`). Returns { block: reason | null, context: stdout of
+// hooks that passed }. A hook that fails to run is logged and ignored: it never stops the work.
+export async function runHooks(s, event, data = {}, signal) {
+  const hooks = (s.hooks?.[event] ?? []).filter((h) => matches(h.matcher, data.tool_name))
+  if (!hooks.length) return { block: null, context: '' }
+  const input = { session_id: s.chat?.id, cwd: s.root, hook_event_name: event, ...data }
+  if (input.tool_input?.path && !input.tool_input.file_path) input.tool_input = { ...input.tool_input, file_path: input.tool_input.path } // as Claude Code names it
+  const context = []
+  for (const h of hooks) {
+    const t0 = Date.now()
+    const { code, output, stderr } = await runCommand(s.root, h.command, { signal, timeout: h.timeout * 1000, stdin: JSON.stringify(input), env: { HEARTCODE_PROJECT_DIR: s.root, CLAUDE_PROJECT_DIR: s.root }, split: true })
+    log('hook', `${event} ${h.command} → exit ${code} in ${Date.now() - t0}ms`, clip(output + stderr, 2000))
+    let json = null
+    try {
+      json = /^\s*\{/.test(output) ? JSON.parse(output) : null
+    } catch {}
+    const reason = (json?.reason ?? json?.stopReason ?? stderr.trim()) || output.trim() || `blocked by the hook ${h.command}`
+    if (code === 2 || json?.decision === 'block' || json?.continue === false) {
+      s.ui.step('hook', `${event}: ${clip(h.command, 50)}`)
+      s.ui.result(`blocked: ${clip(reason.split('\n')[0], 100)}`)
+      return { block: clip(reason, 4000), context: context.join('\n') }
+    }
+    if (code !== 0) s.ui.warn(`hook ${h.command} (${event}) failed: exit ${code}${stderr.trim() ? `: ${clip(stderr.trim().split('\n')[0], 120)}` : ''}`)
+    else if (output.trim() && !json && event === 'UserPromptSubmit') context.push(output.trim())
+  }
+  return { block: null, context: context.join('\n') }
+}

package/src/importer.js

@@ -0,0 +1,202 @@
+// /import: finds what other coding CLIs have set up (commands, skills, MCP servers, instructions,
+// memory) and copies what the user picks into HeartCode's places, converted. Nothing is used from
+// the other tools until it's imported, so their setups never cost tokens by surprise; nothing that
+// already exists in HeartCode is overwritten.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { HOME, readJson, writeJson } from './config.js'
+import { frontMatter } from './skills.js'
+import { Memory } from './memory.js'
+
+const exists = (p) => {
+  try {
+    fs.accessSync(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Every file under dir with one of the extensions: [relative name without extension, full path]
+function filesIn(dir, exts) {
+  const out = []
+  const walk = (d, prefix) => {
+    let entries = []
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {}
+    for (const e of entries) {
+      if (e.isDirectory()) walk(path.join(d, e.name), `${prefix}${e.name}-`)
+      else if (exts.some((x) => e.name.endsWith(x))) out.push([`${prefix}${e.name.replace(/\.[^.]+$/, '')}`, path.join(d, e.name)])
+    }
+  }
+  walk(dir, '')
+  return out
+}
+
+const safe = (n) => String(n).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
+const skillsDir = (root, scope) => (scope === 'global' ? path.join(HOME, 'skills') : path.join(root, '.heartcode', 'skills'))
+const taken = (root, scope, name) => exists(path.join(skillsDir(root, scope), `${name}.md`)) || exists(path.join(skillsDir(root, scope), name))
+
+// A markdown command (Claude Code, Codex, OpenCode) → a HeartCode skill you type ("use: me").
+function importCommand(root, scope, name, file) {
+  if (taken(root, scope, name)) return `/${name} already exists, kept it`
+  const { meta, body } = frontMatter(fs.readFileSync(file, 'utf8'))
+  const head = [`description: ${(meta.description || body.split('\n')[0]).replace(/\n/g, ' ').slice(0, 200)}`, `use: ${meta['user-invocable'] === 'false' ? 'model' : 'me'}`]
+  if (meta['argument-hint']) head.push(`argument-hint: ${meta['argument-hint']}`)
+  fs.mkdirSync(skillsDir(root, scope), { recursive: true })
+  fs.writeFileSync(path.join(skillsDir(root, scope), `${name}.md`), `---\n${head.join('\n')}\n---\n\n${body}\n`)
+  return `/${name}`
+}
+
+// A Gemini CLI command (.toml with prompt and description) → a HeartCode skill. {{args}} stays as
+// is (it's HeartCode's too); !{cmd} becomes !`cmd`.
+function importToml(root, scope, name, file) {
+  if (taken(root, scope, name)) return `/${name} already exists, kept it`
+  const text = fs.readFileSync(file, 'utf8')
+  const str = (key) => {
+    const m = new RegExp(`^${key}\\s*=\\s*(?:"""([\\s\\S]*?)"""|'''([\\s\\S]*?)'''|"((?:[^"\\\\]|\\\\.)*)"|'([^']*)')`, 'm').exec(text)
+    return m ? (m[1] ?? m[2] ?? m[3]?.replace(/\\n/g, '\n').replace(/\\"/g, '"') ?? m[4]) : ''
+  }
+  const prompt = str('prompt').trim().replace(/!\{([^}]*)\}/g, '!`$1`')
+  if (!prompt) return `${name}: no prompt in it, skipped`
+  fs.mkdirSync(skillsDir(root, scope), { recursive: true })
+  fs.writeFileSync(path.join(skillsDir(root, scope), `${name}.md`), `---\ndescription: ${(str('description') || prompt.split('\n')[0]).slice(0, 200)}\nuse: me\n---\n\n${prompt}\n`)
+  return `/${name}`
+}
+
+// A skill folder (Claude Code, Codex): copied as is, supporting files included.
+function importSkillFolder(root, scope, name, dir) {
+  if (taken(root, scope, name)) return `${name} already exists, kept it`
+  fs.cpSync(dir, path.join(skillsDir(root, scope), name), { recursive: true })
+  return name
+}
+
+function importMcp(root, scope, name, cfg) {
+  const file = scope === 'global' ? path.join(HOME, 'mcp.json') : path.join(root, '.heartcode', 'mcp.json')
+  const data = readJson(file, {})
+  data.mcpServers ??= {}
+  if (data.mcpServers[name]) return `MCP server ${name} already exists, kept it`
+  const { command, args, env, url, httpUrl, headers, type } = cfg
+  data.mcpServers[name] = command
+    ? { command, ...(args?.length && { args }), ...(env && Object.keys(env).length && { env }) }
+    : { url: url ?? httpUrl, ...(headers && Object.keys(headers).length && { headers }), ...(type === 'sse' && { type }) } // Gemini CLI names it httpUrl
+  writeJson(file, data)
+  return `MCP server ${name}`
+}
+
+function importInstructions(file, from) {
+  const target = path.join(HOME, 'HEARTCODE.md')
+  const text = fs.readFileSync(file, 'utf8').trim()
+  const now = exists(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (now.includes(text)) return `${from} instructions were already there`
+  fs.mkdirSync(HOME, { recursive: true })
+  fs.writeFileSync(target, `${now.trim() ? `${now.trim()}\n\n` : ''}<!-- from ${from}: ${file} -->\n${text}\n`)
+  return `${from} instructions → ~/.heart/HEARTCODE.md`
+}
+
+// Claude Code's memory for this project: its notes become HeartCode notes (tags from the name;
+// /tidy_memory can refine them and move general ones to the global memory).
+function importClaudeMemory(root, dir) {
+  const memory = new Memory(root)
+  let n = 0
+  for (const [name, file] of filesIn(dir, ['.md'])) {
+    if (name === 'MEMORY') continue
+    const { meta, body } = frontMatter(fs.readFileSync(file, 'utf8'))
+    if (memory.read(meta.name || name)) continue
+    const type = /^\s*type:\s*(\w+)/m.exec(fs.readFileSync(file, 'utf8'))?.[1]
+    const tags = String(meta.name || name).split(/[-_\s]+/).filter((w) => w.length > 2).slice(0, 2)
+    memory.write({ name: meta.name || name, description: meta.description, type: type === 'user' || type === 'feedback' || type === 'reference' ? type : 'project', tags, content: body })
+    n++
+  }
+  return `${n} memory note${n === 1 ? '' : 's'} from Claude Code`
+}
+
+// Codex keeps MCP servers in TOML: [mcp_servers.name] with command, args and env.
+function codexServers(file) {
+  let text = ''
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch {
+    return {}
+  }
+  const out = {}
+  for (const m of text.matchAll(/^\[mcp_servers\.("?)([^\]"]+)\1\]\s*\n([\s\S]*?)(?=^\[|$(?![\s\S]))/gm)) {
+    const block = m[3]
+    const command = /^command\s*=\s*"([^"]*)"/m.exec(block)?.[1]
+    const args = [...(/^args\s*=\s*\[([^\]]*)\]/m.exec(block)?.[1] ?? '').matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((a) => a[1])
+    const env = Object.fromEntries([...(/^env\s*=\s*\{([^}]*)\}/m.exec(block)?.[1] ?? '').matchAll(/"?([\w.-]+)"?\s*=\s*"([^"]*)"/g)].map((e) => [e[1], e[2]]))
+    if (command) out[m[2]] = { command, args, env }
+  }
+  return out
+}
+
+// Everything importable, as picker items: { label, desc, group, run() → what was done }.
+export function findImports(root, home = os.homedir()) {
+  const items = []
+  const add = (group, label, desc, run) => items.push({ group, label, desc, run })
+  const commandSources = [
+    ['Claude Code', 'project', path.join(root, '.claude', 'commands')],
+    ['Claude Code', 'global', path.join(home, '.claude', 'commands')],
+    ['Codex', 'global', path.join(home, '.codex', 'prompts')],
+    ['OpenCode', 'project', path.join(root, '.opencode', 'commands')],
+    ['OpenCode', 'project', path.join(root, '.opencode', 'command')],
+    ['OpenCode', 'global', path.join(home, '.config', 'opencode', 'commands')],
+    ['OpenCode', 'global', path.join(home, '.config', 'opencode', 'command')],
+  ]
+  for (const [tool, scope, dir] of commandSources) {
+    for (const [rel, file] of filesIn(dir, ['.md'])) {
+      const name = safe(rel)
+      const { meta, body } = frontMatter(fs.readFileSync(file, 'utf8'))
+      add(`${tool} · ${scope === 'global' ? 'yours' : 'this project'} · commands`, `/${name}`, (meta.description || body.split('\n')[0]).slice(0, 90), () => importCommand(root, scope, name, file))
+    }
+  }
+  for (const [scope, dir] of [['project', path.join(root, '.gemini', 'commands')], ['global', path.join(home, '.gemini', 'commands')]]) {
+    for (const [rel, file] of filesIn(dir, ['.toml'])) {
+      const name = safe(rel)
+      add(`Gemini CLI · ${scope === 'global' ? 'yours' : 'this project'} · commands`, `/${name}`, /^description\s*=\s*"([^"]*)"/m.exec(fs.readFileSync(file, 'utf8'))?.[1] ?? '', () => importToml(root, scope, name, file))
+    }
+  }
+  const skillSources = [
+    ['Claude Code', 'project', path.join(root, '.claude', 'skills')],
+    ['Claude Code', 'global', path.join(home, '.claude', 'skills')],
+    ['Codex', 'global', path.join(home, '.codex', 'skills')],
+  ]
+  for (const [tool, scope, dir] of skillSources) {
+    let entries = []
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {}
+    for (const e of entries) {
+      const file = path.join(dir, e.name, 'SKILL.md')
+      if (!e.isDirectory() || !exists(file)) continue
+      const { meta } = frontMatter(fs.readFileSync(file, 'utf8'))
+      add(`${tool} · ${scope === 'global' ? 'yours' : 'this project'} · skills`, safe(e.name), (meta.description ?? '').slice(0, 90), () => importSkillFolder(root, scope, safe(e.name), path.join(dir, e.name)))
+    }
+  }
+  const claudeJson = readJson(path.join(home, '.claude.json'), {})
+  const mcpSources = [
+    ['Claude Code', 'project', readJson(path.join(root, '.mcp.json'), {}).mcpServers],
+    ['Claude Code', 'project', claudeJson.projects?.[root]?.mcpServers],
+    ['Claude Code', 'global', claudeJson.mcpServers],
+    ['Cursor', 'project', readJson(path.join(root, '.cursor', 'mcp.json'), {}).mcpServers],
+    ['Cursor', 'global', readJson(path.join(home, '.cursor', 'mcp.json'), {}).mcpServers],
+    ['Gemini CLI', 'project', readJson(path.join(root, '.gemini', 'settings.json'), {}).mcpServers],
+    ['Gemini CLI', 'global', readJson(path.join(home, '.gemini', 'settings.json'), {}).mcpServers],
+    ['Codex', 'global', codexServers(path.join(home, '.codex', 'config.toml'))],
+  ]
+  for (const [tool, scope, servers] of mcpSources) {
+    for (const [name, cfg] of Object.entries(servers ?? {})) {
+      if (!cfg?.command && !cfg?.url && !cfg?.httpUrl) continue
+      add(`${tool} · ${scope === 'global' ? 'yours' : 'this project'} · MCP servers`, name, (cfg.command ? `${cfg.command} ${(cfg.args ?? []).join(' ')}` : (cfg.url ?? cfg.httpUrl)).slice(0, 90), () => importMcp(root, scope, name, cfg))
+    }
+  }
+  for (const [tool, file] of [['Claude Code', path.join(home, '.claude', 'CLAUDE.md')], ['Codex', path.join(home, '.codex', 'AGENTS.md')], ['Gemini CLI', path.join(home, '.gemini', 'GEMINI.md')]]) {
+    if (exists(file)) add(`${tool} · yours · instructions`, path.basename(file), `your ${tool} instructions → ~/.heart/HEARTCODE.md`, () => importInstructions(file, tool))
+  }
+  const claudeMemory = path.join(home, '.claude', 'projects', root.replace(/[^a-zA-Z0-9]/g, '-'), 'memory')
+  const notes = filesIn(claudeMemory, ['.md']).filter(([n]) => n !== 'MEMORY')
+  if (notes.length) add('Claude Code · this project · memory', `${notes.length} memory notes`, 'become HeartCode memory notes for this project', () => importClaudeMemory(root, claudeMemory))
+  return items
+}

package/src/log.js

@@ -0,0 +1,139 @@
+// Logs, when they're switched on (the settings page: Logging).
+// - The run's log: everything HeartCode does, as readable text. HEART_LOG_DIR (bin/heart.js sets
+//   one folder per run): a file per tab (tab-1.log, tab-2.log…; heartcode.log before any tab).
+//   HEART_LOG=/path/file.log: all of it in that one file.
+// - Requests: each request to a model, and its reply or error, a JSON file of its own in
+//   <logs>/requests/<when the run started>/, and a line for it in that folder's index.jsonl.
+// Written synchronously so the last lines survive a crash.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { inspect } from 'node:util'
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export const LOG_FILE = process.env.HEART_LOG && process.env.HEART_LOG !== 'off' ? path.resolve(process.env.HEART_LOG) : null
+export const LOG_DIR = !LOG_FILE && process.env.HEART_LOG !== 'off' && process.env.HEART_LOG_DIR ? path.resolve(process.env.HEART_LOG_DIR) : null
+// The run's log on or off. HEART_LOG_RUN=on|off (bin/heart.js): its folder is set aside, and config.json's
+// "log" switches it, also while HeartCode runs (useRequestLog); else it's on when a file or folder is given.
+const AUTO = Boolean(LOG_DIR) && ['on', 'off'].includes(process.env.HEART_LOG_RUN)
+export const runLog = { on: Boolean(LOG_FILE || (LOG_DIR && (!AUTO || process.env.HEART_LOG_RUN === 'on'))) }
+// Where the logs go: bin/heart.js says (the system's temp folder with --temp)
+export const LOGS = path.resolve(process.env.HEART_LOGS || path.join(process.env.HEART_HOME || path.join(os.homedir(), '.heart'), 'logs'))
+export const REQUESTS = path.join(LOGS, 'requests')
+export const DAYS = 30 // how long logs are kept, unless config.json's logDays says otherwise
+const STAMP = process.env.HEART_LOG_STAMP || stamp()
+
+export function stamp(d = new Date()) {
+  return `${d.getDate()}-${d.getMonth() + 1}-${d.getFullYear()}-${d.getHours()}-${d.getMinutes()}-${d.getSeconds()}`.replace(/\b(\d)\b/g, '0$1')
+}
+// Logs older than `days` go: run folders, request folders, and the older one-file-per-run logs.
+// Returns how many went.
+export function pruneLogs(days = DAYS) {
+  const before = Date.now() - days * 86_400_000
+  let gone = 0
+  for (const [dir, isLog] of [[path.join(LOGS, 'runs'), () => true], [REQUESTS, () => true], [LOGS, (f) => f.endsWith('.log')]]) {
+    try {
+      for (const f of fs.readdirSync(dir)) {
+        const at = path.join(dir, f)
+        if (!isLog(f) || at === LOG_DIR || at === requestLog.dir || fs.statSync(at).mtimeMs >= before) continue
+        fs.rmSync(at, { recursive: true, force: true })
+        gone++
+      }
+    } catch {}
+  }
+  return gone
+}
+export const logDays = (cfg) => (Number.isInteger(cfg.logDays) && cfg.logDays > 0 ? cfg.logDays : DAYS)
+
+// Which tab this is running for (tabs.js runs each tab's work in it): its log file, its requests.
+export const logContext = new AsyncLocalStorage()
+const tabOf = () => logContext.getStore()?.tab ?? null
+
+const fds = new Map()
+function fdFor() {
+  if (!runLog.on) return null
+  const file = LOG_FILE ?? (LOG_DIR && path.join(LOG_DIR, tabOf() ? `tab-${tabOf()}.log` : 'heartcode.log'))
+  if (!file) return null
+  if (!fds.has(file)) {
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true })
+      fds.set(file, fs.openSync(file, 'a'))
+    } catch {
+      fds.set(file, null)
+    }
+  }
+  return fds.get(file)
+}
+
+const show = (x) => (typeof x === 'string' ? x : inspect(x, { depth: 8, breakLength: 140, maxArrayLength: 200, maxStringLength: 50_000 }))
+
+// log('http', 'POST', url, body) → "2026-10-25T08:00:00.000Z [http] POST https://… {…}"
+export function log(topic, ...parts) {
+  const fd = fdFor()
+  if (fd === null) return
+  try {
+    const text = parts.map(show).join(' ').replace(/\x1b\[[0-9;]*m/g, '')
+    fs.writeSync(fd, `${new Date().toISOString()} [${topic}] ${text}\n`)
+  } catch {}
+}
+
+// The requests log: on, and how much of each (from config.json: logRequests, logDetail).
+export const requestLog = { on: false, detail: 'full', dir: null }
+export function useRequestLog(cfg) {
+  if (AUTO) runLog.on = cfg.log === true
+  return Object.assign(requestLog, { on: cfg.logRequests === true, detail: cfg.logDetail === 'summary' ? 'summary' : 'full' })
+}
+// At the start: the request log as set, and logs past their days gone.
+export function useLogs(cfg) {
+  useRequestLog(cfg)
+  pruneLogs(logDays(cfg))
+}
+let count = 0
+const safe = (s) => String(s ?? '').replace(/[^\w.-]+/g, '_').slice(0, 60) || 'none'
+
+// One request, after it ended: { ok, stopped, provider, model, place, of, url, status, error, ms,
+// firstTokenMs, usage, request, reply }. "full" keeps what was sent and what came back; "summary"
+// only their sizes. API keys are never in it (they're headers, not the body).
+export function logRequest(rec) {
+  if (!requestLog.on) return
+  try {
+    if (!requestLog.dir) {
+      let dir = path.join(REQUESTS, STAMP)
+      for (let n = 2; fs.existsSync(dir); n++) dir = path.join(REQUESTS, `${STAMP}-${n}`) // another run started in the same second
+      fs.mkdirSync(dir, { recursive: true })
+      requestLog.dir = dir
+    }
+    const n = ++count
+    const result = rec.ok ? 'ok' : rec.stopped ? 'stopped' : 'failed'
+    const file = `${String(n).padStart(4, '0')}-${result}-${safe(rec.provider)}-${safe(rec.model)}.json`
+    const { request, reply, ...summary } = rec
+    const head = { n, at: new Date().toISOString(), tab: tabOf(), result, ...summary }
+    const sizes = { requestChars: request ? JSON.stringify(request).length : 0, messages: request?.messages?.length ?? 0, replyChars: reply ? (reply.content ?? '').length : 0, toolCalls: reply?.toolCalls?.length ?? 0 }
+    const body = requestLog.detail === 'full' ? { ...head, request, reply } : { ...head, ...sizes }
+    fs.writeFileSync(path.join(requestLog.dir, file), JSON.stringify(body, null, 2))
+    fs.appendFileSync(path.join(requestLog.dir, 'index.jsonl'), JSON.stringify({ file, ...head, ...sizes, errorBody: head.errorBody?.slice(0, 500) }) + '\n') // the list's line: kept short
+  } catch {}
+}
+
+// The requests logged, newest first (for the settings page): each run's index.jsonl, read backwards.
+export function listRequests(limit = 300) {
+  const out = []
+  try {
+    const runs = fs.readdirSync(REQUESTS, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => [d.name, fs.statSync(path.join(REQUESTS, d.name)).mtimeMs]).sort((a, b) => b[1] - a[1])
+    for (const [run] of runs) {
+      const lines = fs.existsSync(path.join(REQUESTS, run, 'index.jsonl')) ? fs.readFileSync(path.join(REQUESTS, run, 'index.jsonl'), 'utf8').trim().split('\n').filter(Boolean) : []
+      for (const line of lines.reverse()) {
+        try {
+          out.push({ run, ...JSON.parse(line) })
+        } catch {}
+        if (out.length >= limit) return out
+      }
+    }
+  } catch {}
+  return out
+}
+// One request's file, by its run folder and name (nothing outside the requests folder).
+export function readRequest(run, file) {
+  if (![run, file].every((x) => /^[\w.-]+$/.test(String(x ?? '')) && !/^\.+$/.test(x)) || !file.endsWith('.json')) throw new Error('no such request')
+  return JSON.parse(fs.readFileSync(path.join(REQUESTS, run, file), 'utf8'))
+}