kira-glasses-bridge 2.27.0 → 2.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.27.0",
+  "version": "2.29.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.278",
+    "smol-toml": "1.9.0",
     "ws": "^8.18.0"
   },
   "keywords": [

package/src/agent-files.mjs

@@ -1,10 +1,12 @@
-// Subagents on this Mac: Claude Code's (one Markdown file each in ~/.claude/agents, front matter
-// for its settings and the body as its system prompt, with `memory: user` kept in
-// ~/.claude/agent-memory/<name>/MEMORY.md) and Codex's (~/.codex/agents/<name>.toml, listed only:
-// the bridge doesn't run Codex yet). Kira's agents are Claude Code subagents: she writes their
-// files and memory here, and a task runs as one (agents/claude.mjs).
+// Subagents on this Mac, in each agent's own format: Claude Code's (one Markdown file each in
+// ~/.claude/agents, front matter for its settings and the body as its system prompt, with
+// `memory: user` kept in ~/.claude/agent-memory/<name>/MEMORY.md) and Codex's (one TOML file each
+// in ~/.codex/agents: name, description, developer_instructions and any config key; Codex keeps no
+// memory per agent). Kira's agents are one or the other: she writes their files (and a Claude Code
+// one's memory) here, and a task runs as one (agents/claude.mjs, agents/codex-agent.mjs).
 import { readdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
+import { parse } from 'smol-toml'
 import {
   FOLDERS,
   agentFolders,
@@ -29,12 +31,34 @@ const LOAD_BYTES = 25 * 1024
 const KIRAS_LINE = /^- \d{4}-\d{2}-\d{2}: /
 const WHAT = 'a subagent'
 const NAMED = { loose: true }
-const claudeRoot = () => agentFolders()[0].root
 
-/** A TOML string value on its own line (`name = "x"`), enough for Codex's name and description. */
+/** Each agent's folder and file: where Kira writes it, and what a file of it must be. */
+const KINDS = {
+  claude: { root: () => agentFolders()[0].root, ext: '.md', check: checkMd },
+  codex: { root: () => agentFolders()[1].root, ext: '.toml', check: checkToml },
+}
+const kindOf = provider => KINDS[provider ?? 'claude'] ?? KINDS.claude
+
+function checkMd(text) {
+  if (!/^---\r?\n/.test(text)) throw new Error('A subagent file starts with front matter between --- lines')
+}
+
+function checkToml(text) {
+  try {
+    parse(text)
+  } catch (err) {
+    throw new Error(`A Codex agent file is TOML: ${err.message}`)
+  }
+}
+
+/** A Codex agent file's string field, or null (and null for all when it isn't TOML). */
 const tomlField = (toml, key) => {
-  const m = new RegExp(`^${key}\\s*=\\s*(?:"((?:[^"\\\\]|\\\\.)*)"|'([^']*)')`, 'm').exec(toml)
-  return m ? (m[1] ?? m[2]).replace(/\\"/g, '"') : null
+  try {
+    const v = parse(toml)[key]
+    return typeof v === 'string' ? v : null
+  } catch {
+    return null
+  }
 }
 
 /** The name and description a tool shows, from a subagent file (its file name when it has none). */
@@ -78,34 +102,44 @@ async function readMemory(name, root) {
   }
 }
 
-/** One of Claude Code's subagents, with its memory. */
-export async function readAgent({ slug } = {}, root = claudeRoot(), memoryRoot = FOLDERS.claude.agentMemory()) {
-  const file = inside(root, slug, WHAT, { ...NAMED, ext: '.md' })
+/**
+ * One subagent, `provider`'s (Claude Code's by default), with its memory (Claude Code's only). `md`
+ * is its file's text whatever the format: Markdown for Claude Code, TOML for Codex.
+ */
+export async function readAgent({ slug, provider } = {}, root, memoryRoot = FOLDERS.claude.agentMemory()) {
+  const kind = kindOf(provider)
+  const file = inside(root ?? kind.root(), slug, WHAT, { ...NAMED, ext: kind.ext })
   const md = await readSmall(file, MAX_MD)
   if (md === null) return { error: `No subagent at ${display(file)}` }
-  const summary = agentSummary(md, slug)
-  return { slug, ...summary, path: display(file), md, memory: await readMemory(summary.name, memoryRoot) }
+  const summary = agentSummary(md, slug, kind.ext)
+  const memory = kind === KINDS.claude ? await readMemory(summary.name, memoryRoot) : ''
+  return { slug, ...summary, path: display(file), md, memory }
 }
 
 /**
- * Write a Claude Code subagent's file, whole: replacing the one there, or with `create` only a new
- * one (a subagent already there, Kira's or not, is never overwritten by a new one of that name).
+ * Write a subagent's file (`provider`'s), whole: replacing the one there, or with `create` only a
+ * new one (a subagent already there, Kira's or not, is never overwritten by a new one of that name).
  */
-export async function writeAgent({ slug, md, create = false } = {}, root = claudeRoot()) {
-  const file = inside(root, slug, WHAT, { ...NAMED, ext: '.md' })
+export async function writeAgent({ slug, md, create = false, provider } = {}, root) {
+  const kind = kindOf(provider)
+  const dir = root ?? kind.root()
+  const file = inside(dir, slug, WHAT, { ...NAMED, ext: kind.ext })
   const text = String(md ?? '')
-  if (!/^---\r?\n/.test(text)) throw new Error('A subagent file starts with front matter between --- lines')
+  kind.check(text)
   if (Buffer.byteLength(text) > MAX_MD) throw new Error('That subagent file is too large')
-  await refuseLinks([root, file], 'edit')
+  await refuseLinks([dir, file], 'edit')
   if (create && (await exists(file))) throw new Error(`A subagent named ${slug} is already on your Mac`)
   await writeWhole(file, text)
-  return { slug, ...agentSummary(text, slug), path: display(file), providers: ['claude'] }
+  const providers = [kind === KINDS.codex ? 'codex' : 'claude']
+  return { slug, ...agentSummary(text, slug, kind.ext), path: display(file), providers }
 }
 
-/** Remove a Claude Code subagent's file. Its memory folder stays (it's what it learned). */
-export async function removeAgent({ slug } = {}, root = claudeRoot()) {
-  const file = inside(root, slug, WHAT, { ...NAMED, ext: '.md' })
-  await refuseLinks([root, file], 'remove')
+/** Remove a subagent's file (`provider`'s). A Claude Code one's memory folder stays (it's what it learned). */
+export async function removeAgent({ slug, provider } = {}, root) {
+  const kind = kindOf(provider)
+  const dir = root ?? kind.root()
+  const file = inside(dir, slug, WHAT, { ...NAMED, ext: kind.ext })
+  await refuseLinks([dir, file], 'remove')
   const removed = await unlink(file).then(
     () => true,
     e => {

package/src/agents/codex-agent.mjs

@@ -0,0 +1,47 @@
+// A Kira agent that runs on Codex: its Codex agent file (~/.codex/agents/<handle>.toml, written by
+// agent-files.mjs). Codex's app server has no "start this thread as agent X" (its agent roles are a
+// config layer it applies when it spawns a subagent: codex-rs/agent-roles), so a job applies the
+// file the way Codex applies a role: its `developer_instructions` are the thread's developer
+// instructions (what Kira adds for the run after them) and its other settings (model,
+// model_reasoning_effort…) the thread's config. Fields from codex-rs/agent-roles/src/agent_role_config.rs.
+import { parse } from 'smol-toml'
+import { FOLDERS, display, inside, readSmall } from '../config-folders.mjs'
+
+const MAX_TOML = 256 * 1024
+/** What names and describes the agent: Codex reads them for its spawn list, never as config. */
+const NOT_CONFIG = new Set(['name', 'description', 'nickname_candidates', 'developer_instructions'])
+
+/** A table's settings as Codex's config overrides take them: one dotted key per value. */
+function flatten(table, prefix = '', out = {}) {
+  for (const [k, v] of Object.entries(table)) {
+    const key = prefix + k
+    if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)) flatten(v, `${key}.`, out)
+    else out[key] = v instanceof Date ? v.toISOString() : v
+  }
+  return out
+}
+
+/** An agent file as a thread takes it: its instructions and the rest of its config. Throws when it isn't TOML. */
+export function roleLayer(toml) {
+  const table = parse(String(toml ?? ''))
+  const rest = Object.fromEntries(Object.entries(table).filter(([k]) => !NOT_CONFIG.has(k)))
+  const said = table.developer_instructions
+  return { instructions: typeof said === 'string' ? said.trim() : '', config: flatten(rest) }
+}
+
+/** The thread's developer instructions: the agent's own, then what Kira adds for this run. */
+export const developerInstructions = (role, persona) =>
+  [role?.instructions, persona?.systemPrompt].filter(Boolean).join('\n\n')
+
+/** The Codex agent a job runs as (null for none); throws, saying where, when its file isn't there. */
+export async function codexAgentOf(persona, root = FOLDERS.codex.agents()) {
+  if (!persona?.agent) return null
+  const file = inside(root, persona.agent, 'a Codex agent', { loose: true, ext: '.toml' })
+  const toml = await readSmall(file, MAX_TOML)
+  if (toml === null) throw new Error(`@${persona.agent}'s Codex agent isn't on this Mac (${display(file)})`)
+  try {
+    return roleLayer(toml)
+  } catch (err) {
+    throw new Error(`${display(file)} isn't TOML Codex can read: ${err.message}`)
+  }
+}

package/src/agents/codex.mjs

@@ -6,6 +6,8 @@ import { TEXT_CAP, short } from './claude-calls.mjs'
 import { callsOf, codexOptionsFor, itemAction, itemResult, strictest } from './codex-items.mjs'
 import { codexBin, openCodex } from './codex-rpc.mjs'
 import { kiraDecides } from './checks.mjs'
+import { codexAgentOf, developerInstructions } from './codex-agent.mjs'
+import { kiraSkillRoots } from '../kira-plugin.mjs'
 
 const COMMAND = 'item/commandExecution/requestApproval'
 const APPROVALS = new Set([COMMAND, 'item/fileChange/requestApproval'])
@@ -111,8 +113,14 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   try {
     await codex.request('initialize', { clientInfo: { name: 'kira', title: 'Kira', version: '1' }, capabilities: null })
     codex.notify('initialized')
-    const config = persona?.kiraTools ? kiraServer(persona.kiraTools) : undefined
-    const instructions = persona?.systemPrompt ? { developerInstructions: persona.systemPrompt } : {}
+    // A Kira agent on Codex: its agent file, applied as Codex applies a role (codex-agent.mjs).
+    const role = await codexAgentOf(persona)
+    // Kira's built-in skills, as Codex's own for this app server: the folder Claude Code's plugin uses.
+    const roots = await kiraSkillRoots(persona)
+    if (roots.length) await codex.request('skills/extraRoots/set', { extraRoots: roots })
+    const config = { ...role?.config, ...(persona?.kiraTools ? kiraServer(persona.kiraTools) : {}) }
+    const said = developerInstructions(role, persona)
+    const instructions = said ? { developerInstructions: said } : {}
     const opened = thread
       ? await codex.request('thread/resume', { threadId: thread, cwd, ...options, ...instructions, config })
       : await codex.request('thread/start', { cwd, ...options, ...instructions, config })

package/src/appollo/asc-launch.mjs

@@ -0,0 +1,90 @@
+// Appollo (POC): getting an app in App Store Connect to Apple's review. Reads asc's release
+// dashboard and its submission readiness report; the only writes are three fixed fixes the person
+// starts from the page (price Free, every country, the reviewer's sign-in). Also finds the app's
+// code on this Mac by its bundle id.
+import { execFile } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { run } from './asc-run.mjs'
+
+const APP_ID = /^\d{6,12}$/
+const UUID = /^[0-9a-f-]{36}$/i
+const BUNDLE_ID = /^[A-Za-z0-9.-]{3,155}$/
+const FIND_MS = 20_000
+const FIND_ROOT = join(homedir(), 'Developer')
+
+/** The project files that name an app's bundle id: Xcode, XcodeGen, Expo. */
+const PROJECT_FILES = ['project.pbxproj', 'project.yml', 'app.json', 'app.config.ts', 'app.config.js']
+const SKIP_DIRS = ['node_modules', 'Pods', 'DerivedData', '.git', 'build', 'dist', '.expo']
+
+function appId(args) {
+  const id = String(args.app_id ?? '')
+  if (!APP_ID.test(id)) throw new Error('not an App Store Connect app id')
+  return id
+}
+
+/** The project folder a project file belongs to (the folder holding the .xcodeproj, or app.json's). */
+function projectFolder(file) {
+  const parts = file.split('/')
+  const xcodeproj = parts.findIndex(p => p.endsWith('.xcodeproj'))
+  return (xcodeproj > 0 ? parts.slice(0, xcodeproj) : parts.slice(0, -1)).join('/')
+}
+
+export const ascLaunchTools = {
+  /** asc's release dashboard and readiness report for one app, as they come. */
+  async asc_launch_readiness(args) {
+    const id = appId(args)
+    const [status, report] = await Promise.all([
+      run(['status', '--app', id, '--output', 'json']),
+      run(['validate', '--app', id, '--deep', '--output', 'json'], { timeout: 120_000 }),
+    ])
+    return { status: status.data ?? null, report: report.data ?? null, error: status.error ?? report.error ?? null }
+  },
+
+  /** One of the fixes the person starts: price Free, every country, or the reviewer's sign-in. */
+  async asc_launch_fix(args) {
+    const id = appId(args)
+    const write = argv => run([...argv, '--output', 'json'], { readOnly: false })
+    if (args.action === 'free')
+      return write(['pricing', 'schedule', 'create', '--app', id, '--free', '--base-territory', 'US'])
+    if (args.action === 'everywhere')
+      return write([
+        'pricing', 'availability', 'create', '--app', id, '--all-territories', '--available', 'true',
+        '--available-in-new-territories', 'true', '--if-exists', 'update',
+      ])
+    if (args.action === 'reviewer') {
+      const detail = String(args.detail_id ?? '')
+      const name = String(args.name ?? '').trim()
+      const password = String(args.password ?? '')
+      if (!UUID.test(detail) || !name || !password || password.length > 100)
+        return { error: 'the reviewer needs a username and a password (100 characters or fewer)' }
+      // The password goes to asc through its environment (@env:), never on a command line.
+      return run(
+        [
+          'review', 'details-update', '--id', detail, '--demo-account-required', 'true',
+          '--demo-account-name', name, '--demo-account-password', '@env:APPOLLO_REVIEWER_PASSWORD', '--output', 'json',
+        ],
+        { readOnly: false, extraEnv: { APPOLLO_REVIEWER_PASSWORD: password } },
+      )
+    }
+    return { error: 'not a fix Appollo knows' }
+  },
+
+  /** Folders under ~/Developer whose project names this bundle id. */
+  appollo_find_project(args) {
+    const bundleId = String(args.bundle_id ?? '')
+    if (!BUNDLE_ID.test(bundleId)) return Promise.resolve({ error: 'not a bundle id' })
+    const grep = [
+      '-rlF', ...PROJECT_FILES.map(f => `--include=${f}`), ...SKIP_DIRS.map(d => `--exclude-dir=${d}`),
+      '-e', `"${bundleId}"`, '-e', `= ${bundleId};`, '-e', `: ${bundleId}`, FIND_ROOT,
+    ]
+    return new Promise(resolve => {
+      execFile('grep', grep, { timeout: FIND_MS, maxBuffer: 1024 * 1024 }, (_err, stdout) => {
+        const all = [...new Set(String(stdout ?? '').split('\n').filter(Boolean).map(projectFolder))]
+        // An Expo app's ios/ folder names the bundle id too: keep only the outermost project.
+        const folders = all.filter(f => !all.some(o => o !== f && f.startsWith(`${o}/`)))
+        resolve({ folders: folders.slice(0, 5).map(f => f.replace(homedir(), '~')) })
+      })
+    })
+  },
+}

package/src/appollo/asc-run.mjs

@@ -1,5 +1,6 @@
 // Running the asc CLI on this Mac (Appollo's way to App Store Connect): reads with ASC_READ_ONLY=1
-// unless told otherwise, answered as JSON.
+// unless told otherwise, answered as JSON. A report that fails on purpose (asc validate exits 1 when
+// something blocks submission) still answers with its JSON.
 import { execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
 
@@ -23,12 +24,15 @@ export function run(args, { readOnly = true, extraEnv = {}, timeout = READ_TIMEO
         const out = String(stdout ?? '').trim()
         if (err && err.code === 'ENOENT')
           return resolve({ error: 'asc is not installed on this Mac (brew install asc)', missing: true })
-        if (err) return resolve({ error: (String(stderr ?? '').trim() || err.message).slice(0, 2000) })
+        let data = out
         try {
-          resolve({ data: out ? JSON.parse(out) : null })
+          data = out ? JSON.parse(out) : null
         } catch {
-          resolve({ data: out })
+          // Not JSON: asc's text.
         }
+        if (err && !(data && typeof data === 'object'))
+          return resolve({ error: (String(stderr ?? '').trim() || err.message).slice(0, 2000) })
+        resolve({ data })
       },
     )
   })

package/src/appollo/index.mjs

@@ -1,7 +1,8 @@
 // Appollo (POC) on this Mac: App Store Connect through asc, each app's workspace in ~/Appollo, and
 // the Doctor's checks. One export, so the bridge registers Appollo in one line (and drops it in one).
 import { ascTools } from './asc.mjs'
+import { ascLaunchTools } from './asc-launch.mjs'
 import { doctorTools } from './doctor.mjs'
 import { appolloTools } from './workspace.mjs'
 
-export const appolloBridgeTools = { ...ascTools, ...appolloTools, ...doctorTools }
+export const appolloBridgeTools = { ...ascTools, ...ascLaunchTools, ...appolloTools, ...doctorTools }

package/src/checkouts.mjs

@@ -0,0 +1,74 @@
+// Where a GitHub repo is already checked out on this Mac, so Kira links that folder instead of guessing a
+// path or cloning another copy: the folders Claude Code has worked in (and the checkouts they sit in),
+// then a shallow look through the usual places people keep code. Reads .git/config, runs nothing.
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { listProjects } from './claude-sessions.mjs'
+import { display, remoteToRepo } from './git.mjs'
+
+const ROOTS = ['Developer', 'code', 'src', 'Projects', 'dev', 'repos', 'work']
+const DEPTH = 3
+const BUDGET_MS = 4000
+const SKIP = new Set(['node_modules', 'Library', 'Applications', 'Pictures', 'Music', 'Movies'])
+
+/** The origin's URL in a .git/config's text, or null. */
+export function originOf(config) {
+  let inOrigin = false
+  for (const raw of String(config ?? '').split('\n')) {
+    const line = raw.trim()
+    if (line.startsWith('[')) inOrigin = /^\[remote\s+"origin"\]$/.test(line)
+    else if (inOrigin) {
+      const m = /^url\s*=\s*(.+)$/.exec(line)
+      if (m) return m[1].trim()
+    }
+  }
+  return null
+}
+
+const sameRepo = (a, b) => !!a && !!b && a.toLowerCase() === b.toLowerCase()
+const isDir = p => stat(p).then(s => s.isDirectory()).catch(() => false)
+
+/** The repo a checkout's origin points at (a main checkout: .git is a folder, not a worktree's file). */
+async function repoAt(dir) {
+  if (!(await isDir(join(dir, '.git')))) return null
+  return remoteToRepo(originOf(await readFile(join(dir, '.git', 'config'), 'utf8').catch(() => '')))
+}
+
+/** The checkout a folder sits in (itself or a parent), or null. */
+async function checkoutAround(dir) {
+  for (let d = dir; d && d !== dirname(d); d = dirname(d)) {
+    if (await isDir(join(d, '.git'))) return d
+  }
+  return null
+}
+
+/** Checkouts under a folder, a few levels down; a checkout isn't looked inside. */
+async function scan(dir, depth, until, found) {
+  if (depth < 0 || Date.now() > until) return
+  if (await isDir(join(dir, '.git'))) return found.add(dir)
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.') || SKIP.has(e.name)) continue
+    await scan(join(dir, e.name), depth - 1, until, found)
+  }
+}
+
+/** Every checkout of `repo` ("owner/name") on this Mac, as ~ paths; Kira's own worktrees aren't. */
+export async function findCheckouts(repo, { home = homedir(), known = null } = {}) {
+  const candidates = new Set()
+  const worked = known ?? ((await listProjects(50).catch(() => ({ projects: [] }))).projects ?? []).map(p => p.cwd)
+  for (const cwd of worked) {
+    const top = await checkoutAround(cwd)
+    if (top) candidates.add(top)
+  }
+  const until = Date.now() + BUDGET_MS
+  for (const root of ROOTS) await scan(join(home, root), DEPTH, until, candidates)
+  const kira = join(home, '.kira')
+  const matches = []
+  for (const dir of candidates) {
+    if (dir.startsWith(kira)) continue
+    if (sameRepo(await repoAt(dir), repo)) matches.push(dir)
+  }
+  return { repo, checkouts: [...new Set(matches)].sort().map(display) }
+}

package/src/config-folders.mjs

@@ -38,7 +38,7 @@ export const skillFolders = () => [
   { root: FOLDERS.codex.skills(), loadedBy: ['codex'] },
 ]
 
-/** The subagent folders, their file format and who loads each; Kira writes only Claude Code's. */
+/** The subagent folders, their file format and who loads each; Kira writes both (agent-files.mjs). */
 export const agentFolders = () => [
   { root: FOLDERS.claude.agents(), loadedBy: ['claude'], ext: '.md' },
   { root: FOLDERS.codex.agents(), loadedBy: ['codex'], ext: '.toml' },

package/src/git.mjs

@@ -65,9 +65,9 @@ export async function snapshot(dir) {
   }
 }
 
-function remoteToRepo(url) {
-  if (!url) return null
-  const m = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/.exec(url)
+/** "owner/name" from a GitHub remote URL (ssh or https), or null. */
+export function remoteToRepo(url) {
+  const m = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/.exec(String(url ?? '').trim())
   return m ? m[1] : null
 }
 

package/src/kira-plugin.mjs

@@ -1,8 +1,10 @@
-// Kira's built-in skills as Claude Code takes skills that come with something: a plugin, on this
-// Mac (~/.kira/claude-plugin: .claude-plugin/plugin.json and skills/<name>/SKILL.md). The API sends
-// the ones a person's Kira has with each job she runs as Claude Code (persona.skills); this brings
-// the folder in line with them (each written whole, the ones gone removed) and Claude Code loads it
-// with the job (the Agent SDK's `plugins`), so it reads them as its own: /kira:draft-page.
+// Kira's built-in skills, one folder on this Mac that both agents load as their own. The API sends
+// the ones a person's Kira has with each job (persona.skills); this brings the folder in line with
+// them (each written whole, the ones gone removed). It is a Claude Code plugin
+// (~/.kira/claude-plugin: .claude-plugin/plugin.json and skills/<name>/SKILL.md), which Claude Code
+// loads with the job (the Agent SDK's `plugins`: /kira:draft-page). Its skills/ folder is plain
+// Agent Skills (<name>/SKILL.md), which Codex loads as an extra skills root for the job
+// (`skills/extraRoots/set` on its app server: $draft-page).
 import { readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { KIRA_DIR } from './config.mjs'
@@ -47,15 +49,27 @@ export function writeKiraPlugin(skills, root = pluginRoot()) {
 }
 
 /**
- * The query options that load Kira's skills for a job: none when it has none, or when the folder
- * can't be written (the job still runs; `warn` says why).
+ * The folder written for a job's skills, or null when it has none or it can't be written (the job
+ * still runs; `warn` says why, naming the agent that goes without them).
  */
-export async function kiraPluginOptions(persona, warn = log, root = pluginRoot()) {
-  if (!Array.isArray(persona?.skills) || !persona.skills.length) return {}
+async function writtenFor(persona, agent, warn, root) {
+  if (!Array.isArray(persona?.skills) || !persona.skills.length) return null
   try {
-    return { plugins: [{ type: 'local', path: await writeKiraPlugin(persona.skills, root) }] }
+    return await writeKiraPlugin(persona.skills, root)
   } catch (err) {
-    warn(`Kira's skills couldn't be written for Claude Code: ${err.message}`)
-    return {}
+    warn(`Kira's skills couldn't be written for ${agent}: ${err.message}`)
+    return null
   }
 }
+
+/** The Agent SDK query options that load Kira's skills for a Claude Code job (none without them). */
+export async function kiraPluginOptions(persona, warn = log, root = pluginRoot()) {
+  const path = await writtenFor(persona, 'Claude Code', warn, root)
+  return path ? { plugins: [{ type: 'local', path }] } : {}
+}
+
+/** The skills roots Codex is given for a job (`skills/extraRoots/set`): the plugin's skills/ folder, or none. */
+export async function kiraSkillRoots(persona, warn = log, root = pluginRoot()) {
+  const path = await writtenFor(persona, 'Codex', warn, root)
+  return path ? [join(path, 'skills')] : []
+}

package/src/mac-tools.mjs

@@ -1,9 +1,10 @@
-// The bridge's tools for this Mac itself: its apps, a terminal, a new project's folder, and
+// The bridge's tools for this Mac itself: its apps, a terminal, a project's folder (found or new), and
 // (inside the Mac app only) its shells for other devices and its browser dock.
 import { execFile } from 'node:child_process'
 import { openApp, installedApps } from './apps.mjs'
 import { resolveUserPath } from './files.mjs'
 import { display, setupProjectFolder } from './git.mjs'
+import { findCheckouts } from './checkouts.mjs'
 import { terminalCall } from './terminals.mjs'
 import { safeCommand, terminalScript } from './terminal-command.mjs'
 import { host } from './host.mjs'
@@ -28,6 +29,13 @@ export const macTools = {
     })
   },
 
+  /** Where a repo ("owner/name") is already checked out here, so a project links it instead of cloning. */
+  async find_checkouts(args) {
+    const repo = String(args.repo ?? '').trim()
+    if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) return { error: 'repo must be "owner/name"' }
+    return findCheckouts(repo)
+  },
+
   /** This Mac's shells for a browser elsewhere (only inside the Mac app, only when switched on there). */
   terminal: args => terminalCall(args),
 

package/src/worktrees.mjs

@@ -9,7 +9,7 @@ import { mkdir, stat, readFile, writeFile, appendFile, rm } from 'node:fs/promis
 import { pipeline } from 'node:stream/promises'
 import { createWriteStream } from 'node:fs'
 import { Readable } from 'node:stream'
-import { display } from './git.mjs'
+import { display, remoteToRepo } from './git.mjs'
 import { resolveUserPath } from './files.mjs'
 
 const ROOT = join(homedir(), '.kira', 'worktrees')
@@ -24,11 +24,6 @@ function git(cwd, args, { timeout = 60_000 } = {}) {
   })
 }
 
-function remoteToRepo(url) {
-  const m = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/.exec(url ?? '')
-  return m ? m[1] : null
-}
-
 const sameRepo = (a, b) => !!a && !!b && a.toLowerCase() === b.toLowerCase()
 
 /** The GitHub repo a folder's origin points at, or null. */