lazyclaw 6.5.0 → 6.7.0

package/agents.mjs

@@ -90,6 +90,16 @@ function defaultShape(name) {
     tools: [...DEFAULT_TOOLS],
     tags: [],
     iconEmoji: '',
+    // Explicit Team Live sprite choice: an integer 1..20 picks one of the 20
+    // built-in pixel-art avatars (web/avatars/NN.png); null lets the dashboard
+    // keep inferring one from the agent's name/role/tags. (dashboard.js
+    // avatarIndexFor already honours rec.avatar — this is the registry side.)
+    avatar: null,
+    // Optional custom character image: a ready-to-use <img src> — either a
+    // remote http(s) URL or a daemon-served '/agent-avatars/<file>' path for a
+    // photo the user supplied (copied under <configDir>/agent-avatars/). null =
+    // none. Takes precedence over `avatar` and the keyword inference.
+    avatarImage: null,
     // Optional parent agent (hierarchy). '' = top-level. A team's org tree is
     // derived from members' manager links (see teams.teamTree). Validated to
     // reference a registered agent and to never form a cycle.
@@ -124,6 +134,18 @@ function writeAtomic(filePath, obj) {
 const VALID_MEMORY_WRITE = ['auto', 'manual', 'off'];
 const VALID_SKILL_WRITE = ['auto', 'manual', 'off'];
 
+// Normalise an explicit avatar choice. null/''/undefined → null (keep the
+// dashboard's keyword inference). A value that parses to an integer 1..20 picks
+// that built-in sprite. Anything else (0, 21, fractional, non-numeric) throws.
+function validateAvatar(v) {
+  if (v === undefined || v === null || v === '') return null;
+  const n = typeof v === 'number' ? v : Number(String(v).trim());
+  if (!Number.isInteger(n) || n < 1 || n > 20) {
+    throw new AgentError('avatar must be an integer 1..20 (or null to clear)', 'AGENT_BAD_AVATAR');
+  }
+  return n;
+}
+
 // Validate a proposed `manager` (parent agent) for `name`: it must reference a
 // registered agent, may not be the agent itself, and may not close a cycle
 // (i.e. `name` must not already be an ancestor of the proposed manager).
@@ -151,7 +173,7 @@ function validateManager(name, manager, configDir) {
   return mgr;
 }
 
-export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', memoryWrite, memoryMaxChars, skillWrite, manager } = {}, configDir = defaultConfigDir()) {
+export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', avatar, memoryWrite, memoryMaxChars, skillWrite, manager } = {}, configDir = defaultConfigDir()) {
   ensureValidName(name);
   const p = agentPath(name, configDir);
   if (fs.existsSync(p)) {
@@ -175,6 +197,7 @@ export function registerAgent({ name, displayName, role = '', provider = 'claude
     tools: toolsClean,
     tags: Array.isArray(tags) ? tags : [],
     iconEmoji: String(iconEmoji || ''),
+    avatar: validateAvatar(avatar),
     memoryWrite: mw,
     memoryMaxChars: Number.isFinite(+memoryMaxChars) && +memoryMaxChars > 0 ? +memoryMaxChars : 12 * 1024,
     skillWrite: sw,
@@ -220,6 +243,12 @@ export function patchAgent(name, patch, configDir = defaultConfigDir()) {
   if (patch.skillWrite !== undefined && !VALID_SKILL_WRITE.includes(patch.skillWrite)) {
     throw new AgentError(`skillWrite must be one of ${VALID_SKILL_WRITE.join(', ')}`, 'AGENT_BAD_SKILL_WRITE');
   }
+  if (patch.avatar !== undefined) {
+    next.avatar = validateAvatar(patch.avatar);
+  }
+  if (patch.avatarImage !== undefined) {
+    next.avatarImage = (patch.avatarImage == null || patch.avatarImage === '') ? null : String(patch.avatarImage);
+  }
   if (patch.manager !== undefined) {
     next.manager = validateManager(name, patch.manager, configDir);
   }
@@ -227,6 +256,44 @@ export function patchAgent(name, patch, configDir = defaultConfigDir()) {
   return next;
 }
 
+// Supported custom-avatar image types → their served content-type. svg is
+// deliberately excluded (inline-script XSS risk in an <img>/object context).
+export const AVATAR_IMAGE_TYPES = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp',
+};
+
+// Point an agent at a custom character image. `src` is either a remote http(s)
+// URL (stored verbatim) or a path to a local image file (copied into
+// <configDir>/agent-avatars/<name><ext> and stored as a daemon-served
+// '/agent-avatars/<name><ext>' path). Returns the patched record. The image
+// takes precedence over the numeric sprite + keyword inference in the dashboard.
+export function setAgentAvatarImage(name, src, configDir = defaultConfigDir()) {
+  if (!getAgent(name, configDir)) throw new AgentError(`no agent "${name}"`, 'AGENT_NO_AGENT');
+  const s = String(src ?? '').trim();
+  if (!s) throw new AgentError('avatar image source required (a file path or http(s) URL)', 'AGENT_BAD_AVATAR_IMAGE');
+  if (/^https?:\/\//i.test(s)) {
+    return patchAgent(name, { avatarImage: s }, configDir);
+  }
+  const ext = path.extname(s).toLowerCase();
+  if (!AVATAR_IMAGE_TYPES[ext]) {
+    throw new AgentError(`unsupported image type "${ext || '(none)'}" — use png/jpg/jpeg/gif/webp or an http(s) URL`, 'AGENT_BAD_AVATAR_IMAGE');
+  }
+  if (!fs.existsSync(s) || !fs.statSync(s).isFile()) {
+    throw new AgentError(`no such image file: ${s}`, 'AGENT_BAD_AVATAR_IMAGE');
+  }
+  const destDir = path.join(configDir, 'agent-avatars');
+  fs.mkdirSync(destDir, { recursive: true });
+  // Drop any previously stored image for this agent (it may have a different
+  // extension) so a re-point doesn't leave a stale file shadowing the new one.
+  for (const e of Object.keys(AVATAR_IMAGE_TYPES)) {
+    const old = path.join(destDir, `${name}${e}`);
+    if (fs.existsSync(old)) fs.unlinkSync(old);
+  }
+  fs.copyFileSync(s, path.join(destDir, `${name}${ext}`));
+  return patchAgent(name, { avatarImage: `/agent-avatars/${name}${ext}` }, configDir);
+}
+
 export function removeAgent(name, configDir = defaultConfigDir()) {
   const p = agentPath(name, configDir);
   if (!fs.existsSync(p)) {

package/cli.mjs

@@ -403,6 +403,11 @@ async function main() {
       await (await import('./commands/config.mjs')).cmdDoctor();
       break;
     }
+    case 'login': {
+      const code = await (await import('./commands/login.mjs')).cmdLogin(rest.positional, rest.flags);
+      if (code) process.exitCode = code;
+      break;
+    }
     case 'status': {
       await (await import('./commands/config.mjs')).cmdStatus();
       break;

package/commands/agents_registry.mjs

@@ -35,6 +35,7 @@ export async function cmdAgentRegistry(sub, positional, flags = {}) {
           model: flags.model || '',
           tools: tools === null ? undefined : tools,
           tags: agentsMod.parseToolsFlag(flags.tags) || [],
+          avatar: flags.avatar,
           skillWrite: flags['skill-write'],
           manager: flags.manager,
         }, cfgDir);
@@ -64,6 +65,7 @@ export async function cmdAgentRegistry(sub, positional, flags = {}) {
       if (flags.tags !== undefined)         patch.tags = agentsMod.parseToolsFlag(flags.tags);
       if (flags['skill-write'] !== undefined)  patch.skillWrite = String(flags['skill-write']);
       if (flags['memory-write'] !== undefined) patch.memoryWrite = String(flags['memory-write']);
+      if (flags.avatar !== undefined)          patch.avatar = /^(none|clear|off)$/i.test(String(flags.avatar)) ? null : flags.avatar;
       if (Object.keys(patch).length === 0) {
         console.error('agent edit: no fields to update');
         process.exit(2);
@@ -72,6 +74,26 @@ export async function cmdAgentRegistry(sub, positional, flags = {}) {
       catch (err) { console.error(`agent edit: ${err?.message || err}`); process.exit(2); }
       return;
     }
+    case 'set-avatar': {
+      const val = positional[1];
+      if (!name || val === undefined) {
+        console.error('Usage: lazyclaw agent set-avatar <name> <1-20 | none | <image-file> | http(s)://url>\n  1-20      pick a built-in pixel-art sprite\n  none      keep the role-inferred default\n  file/url  use a custom character photo');
+        process.exit(2);
+      }
+      const v = String(val).trim();
+      try {
+        if (/^(none|clear|off)$/i.test(v)) {
+          emitJson(agentsMod.patchAgent(name, { avatar: null, avatarImage: null }, cfgDir));
+        } else if (/^\d+$/.test(v)) {
+          // a built-in sprite index — clear any custom image so it shows through
+          emitJson(agentsMod.patchAgent(name, { avatar: v, avatarImage: null }, cfgDir));
+        } else {
+          // a local image file or a remote URL
+          emitJson(agentsMod.setAgentAvatarImage(name, val, cfgDir));
+        }
+      } catch (err) { console.error(`agent set-avatar: ${err?.message || err}`); process.exit(2); }
+      return;
+    }
     case 'remove':
     case 'rm':
     case 'delete': {

package/commands/login.mjs

@@ -0,0 +1,108 @@
+// commands/login.mjs — `lazyclaw login [claude]`.
+//
+// lazyclaw is keyless: chatting via the claude-cli provider spawns the `claude`
+// binary, which carries its own login. But the model-LISTING path makes a
+// direct api.anthropic.com call that needs a bearer, and on macOS the `claude`
+// login lives in the Keychain (no credential file), so listing failed with
+// "set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN". This command resolves the
+// credential across env / file / Keychain and, when none is present, mints a
+// long-lived token via `claude setup-token`. The minted token is stored in
+// <config>/.env (0600, gitignored) — the same env path model listing reads.
+
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { _claudeCodeOAuthToken } from '../providers/model_catalogue.mjs';
+import { readClaudeKeychainToken } from '../providers/claude_keychain.mjs';
+import { writeDotenvMerge } from '../dotenv_min.mjs';
+import { configPath } from '../lib/config.mjs';
+
+// Where the claude-cli bearer comes from, in priority order. Pure + injectable.
+export function resolveClaudeAuth({ env = process.env, home, readFileSync, keychainReader } = {}) {
+  if (env.CLAUDE_CODE_OAUTH_TOKEN) return { authenticated: true, source: 'env' };
+  if (env.ANTHROPIC_API_KEY) return { authenticated: true, source: 'apiKey' };
+  // Credential file (Linux / non-keychain) — keychain disabled here so we can
+  // distinguish the two sources for the status message.
+  const fileTok = _claudeCodeOAuthToken({ home, readFileSync, keychainReader: () => null });
+  if (fileTok) return { authenticated: true, source: 'file' };
+  const kcTok = (keychainReader || readClaudeKeychainToken)();
+  if (kcTok) return { authenticated: true, source: 'keychain' };
+  return { authenticated: false, source: 'none' };
+}
+
+function _hasClaudeBinary() {
+  try { execFileSync('claude', ['--version'], { stdio: 'ignore', timeout: 4000 }); return true; }
+  catch { return false; }
+}
+
+function _runSetupToken() {
+  return new Promise((resolve) => {
+    try {
+      const p = spawn('claude', ['setup-token'], { stdio: 'inherit' });
+      p.on('exit', (code) => resolve(code ?? 1));
+      p.on('error', () => resolve(1));
+    } catch { resolve(1); }
+  });
+}
+
+const SOURCE_LABEL = {
+  env: 'CLAUDE_CODE_OAUTH_TOKEN env var',
+  apiKey: 'ANTHROPIC_API_KEY env var',
+  file: 'claude credential file (~/.claude)',
+  keychain: 'macOS Keychain (your `claude login`)',
+};
+
+export async function cmdLogin(positional = [], flags = {}, deps = {}) {
+  const log = deps.log || ((s) => process.stdout.write(s + '\n'));
+  const err = deps.err || ((s) => process.stderr.write(s + '\n'));
+  const provider = String(positional[0] || 'claude').toLowerCase();
+  if (provider !== 'claude' && provider !== 'claude-cli') {
+    err(`login: only 'claude' is supported right now (got "${provider}"). Other providers use their own CLI login.`);
+    return 2;
+  }
+  const cfgDir = deps.cfgDir || path.dirname(configPath());
+  const resolve = deps.resolve || resolveClaudeAuth;
+  const writeEnv = deps.writeEnv || ((vars) => writeDotenvMerge(cfgDir, vars));
+
+  // Save a token the user already minted (e.g. via `claude setup-token`).
+  if (flags.token) {
+    const tok = String(flags.token).trim();
+    if (!tok) { err('login: --token was empty'); return 2; }
+    writeEnv({ CLAUDE_CODE_OAUTH_TOKEN: tok });
+    log('✓ saved CLAUDE_CODE_OAUTH_TOKEN to <config>/.env (0600). claude-cli model listing + recall will use it.');
+    return 0;
+  }
+
+  const status = resolve();
+  if (status.authenticated) {
+    log(`✓ claude-cli is already authenticated — via ${SOURCE_LABEL[status.source] || status.source}.`);
+    log('  Model listing, recall, and the keyless trainer will work. Nothing to do.');
+    return 0;
+  }
+
+  if (flags.check) {
+    err('✗ no claude-cli credential found (no env token, ~/.claude credential file, or macOS Keychain login).');
+    return 1;
+  }
+
+  const hasClaude = deps.hasClaudeBinary ? deps.hasClaudeBinary() : _hasClaudeBinary();
+  if (!hasClaude) {
+    err('No claude-cli credential found, and no `claude` binary on PATH.');
+    log('Install the Claude CLI and log in:');
+    log('  npm i -g @anthropic-ai/claude-code');
+    log('  claude login');
+    log('Then re-run `lazyclaw login`. (Headless/CI: set CLAUDE_CODE_OAUTH_TOKEN, or `lazyclaw login --token <token>`.)');
+    return 1;
+  }
+
+  log('No usable credential found. Launching `claude setup-token` to mint a long-lived token…');
+  log('(A browser opens for OAuth; the token is printed when it finishes.)\n');
+  const code = deps.runSetupToken ? await deps.runSetupToken() : await _runSetupToken();
+  if (code !== 0) {
+    err('\n`claude setup-token` did not complete. Alternatively run `claude login`, then re-run `lazyclaw login`.');
+    return 1;
+  }
+  log('\nDone. Copy the token printed above, then save it with EITHER:');
+  log('  lazyclaw login --token <paste-token>      # writes <config>/.env (recommended)');
+  log('  export CLAUDE_CODE_OAUTH_TOKEN=<paste-token>');
+  return 0;
+}

package/daemon/route_table.mjs

@@ -28,6 +28,7 @@ export const ROUTES = [
   { m: (c) => c.route === 'GET /dashboard.css', h: meta.dashboardCss },
   { m: (c) => c.route === 'GET /dashboard.js', h: meta.dashboardJs },
   { m: (c) => c.req.method === 'GET' && /^\/avatars\/\d{2}\.png$/.test(c.path || ''), h: meta.avatar },
+  { m: (c) => c.req.method === 'GET' && /^\/agent-avatars\/[A-Za-z0-9_-]+\.[a-z]+$/.test(c.path || ''), h: meta.agentAvatar },
   { m: (c) => c.route === 'GET /version', h: meta.version },
   { m: (c) => c.route === 'POST /exec/request', h: conversation.execRequest },
   { m: (c) => c.route === 'GET /health' || c.route === 'GET /healthz', h: meta.health },

package/daemon/routes/meta.mjs

@@ -65,6 +65,35 @@ export async function dashboardJs(c) {
   return serveWebFile(c, 'dashboard.js', 'text/javascript; charset=utf-8');
 }
 
+// Serve a custom agent character image (web app: <img src="/agent-avatars/NN">).
+// These are user-supplied photos copied under <configDir>/agent-avatars/ by
+// `lazyclaw agent set-avatar`. Served from the config dir (NOT the package web/
+// dir) since they're per-install user data. The filename is constrained to
+// `<word>.<ext>` so no path traversal escapes the agent-avatars directory.
+const _AGENT_AVATAR_CT = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp',
+};
+export async function agentAvatar(c) {
+  const { res } = c;
+  const m = /^\/agent-avatars\/([A-Za-z0-9_-]+\.[a-z]+)$/.exec(c.path || '');
+  const file = m && m[1];
+  const ct = file && _AGENT_AVATAR_CT[nodePath.extname(file).toLowerCase()];
+  const base = c.gwConfigDir;
+  if (!file || file.includes('..') || !ct || !base) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    return res.end('not found\n');
+  }
+  try {
+    const body = _readAssetCached(nodePath.join(base, 'agent-avatars', file));
+    res.writeHead(200, { 'content-type': ct, 'cache-control': 'no-cache' });
+    return res.end(body);
+  } catch (e) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    return res.end(`not found: ${file} (${e?.message || e})\n`);
+  }
+}
+
 export async function dashboard(c) {
   const { res } = c;
           // Serve the lazyclaw-only web dashboard (a single static

package/lib/args.mjs

@@ -10,7 +10,7 @@ export const SUBCOMMANDS = [
   'run', 'resume', 'inspect', 'clear', 'validate', 'graph',
   'workflow',
   'config', 'chat', 'agent',
-  'doctor', 'status', 'onboard',
+  'doctor', 'status', 'onboard', 'login',
   'sessions', 'skills', 'providers',
   'daemon', 'version', 'completion', 'help',
   'export', 'import',
@@ -277,6 +277,6 @@ _lazyclaw "$@"
 // AGENT_REG_SUBS to decide whether a bare `agent <sub>` routes to the agent
 // registry vs a one-shot agent run. TEAM_SUBS/TASK_SUBS mirror their command's
 // subcommands for the same disambiguation pattern.
-export const AGENT_REG_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete', 'memory', 'reflect', 'skill-synth']);
+export const AGENT_REG_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete', 'memory', 'reflect', 'skill-synth', 'set-avatar']);
 export const TEAM_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete']);
 export const TASK_SUBS = new Set(['start', 'tick', 'list', 'show', 'abandon', 'done', 'transcript', 'remove', 'rm', 'delete']);

package/mas/index_db.mjs

@@ -42,6 +42,33 @@ function _logIndexFailure(configDir, scope, err) {
   } catch { /* swallow — surface only via console.warn below */ }
 }
 
+// The native better-sqlite3 addon fails to load when node_modules was built
+// against a different Node.js ABI than the one running lazyclaw (a Node switch
+// via nvm/brew, or copied node_modules). Every index op then throws the same
+// thing — so instead of dumping the raw stack on each write, recognise it and
+// print ONE actionable hint, then stay quiet. Chat is unaffected; only recall /
+// skill search degrade until the addon is rebuilt.
+let _nativeHintShown = false;
+export function _resetNativeHint() { _nativeHintShown = false; } // test seam
+export function _isNativeAbiError(e) {
+  return /NODE_MODULE_VERSION|was compiled against a different Node|better_sqlite3\.node|invalid ELF header|dlopen\(/i
+    .test(String(e?.message || e || ''));
+}
+export function _warnIndexFailure(label, e) {
+  if (_isNativeAbiError(e)) {
+    if (_nativeHintShown) return;
+    _nativeHintShown = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[index_db] recall index disabled — better-sqlite3 was built for a different Node.js version.\n' +
+      '           Re-enable it once with:  npm rebuild better-sqlite3   (in the lazyclaw install dir),\n' +
+      '           or reinstall deps with the Node you run lazyclaw with. Chat is unaffected.');
+    return;
+  }
+  // eslint-disable-next-line no-console
+  console.warn(`[index_db] ${label}:`, e.message);
+}
+
 function dbPath(configDir) {
   return path.join(configDir, 'index.db');
 }
@@ -180,8 +207,7 @@ export function indexSessionTurn(row, configDir = defaultConfigDir()) {
     );
   } catch (e) {
     _logIndexFailure(configDir, 'sessions', e);
-    // eslint-disable-next-line no-console
-    console.warn('[index_db] indexSessionTurn failed:', e.message);
+    _warnIndexFailure('indexSessionTurn failed', e);
   }
 }
 
@@ -196,8 +222,7 @@ export function indexSkill(row, configDir = defaultConfigDir()) {
     );
   } catch (e) {
     _logIndexFailure(configDir, 'skills', e);
-    // eslint-disable-next-line no-console
-    console.warn('[index_db] indexSkill failed:', e.message);
+    _warnIndexFailure('indexSkill failed', e);
   }
 }
 
@@ -212,8 +237,7 @@ export function deleteSkill(skillName, configDir = defaultConfigDir()) {
     s.deleteSkill.run(String(skillName || ''));
   } catch (e) {
     _logIndexFailure(configDir, 'skills', e);
-    // eslint-disable-next-line no-console
-    console.warn('[index_db] deleteSkill failed:', e.message);
+    _warnIndexFailure('deleteSkill failed', e);
   }
 }
 
@@ -228,8 +252,7 @@ export function indexTrajectory(row, configDir = defaultConfigDir()) {
     );
   } catch (e) {
     _logIndexFailure(configDir, 'trajectories', e);
-    // eslint-disable-next-line no-console
-    console.warn('[index_db] indexTrajectory failed:', e.message);
+    _warnIndexFailure('indexTrajectory failed', e);
   }
 }
 
@@ -243,8 +266,7 @@ export function indexMemory(row, configDir = defaultConfigDir()) {
     );
   } catch (e) {
     _logIndexFailure(configDir, 'memories', e);
-    // eslint-disable-next-line no-console
-    console.warn('[index_db] indexMemory failed:', e.message);
+    _warnIndexFailure('indexMemory failed', e);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama, orchestrating multi-step LLM workflows, and running multi-agent Slack teams with cross-task memory. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",

package/providers/claude_keychain.mjs

@@ -0,0 +1,40 @@
+// claude_keychain.mjs — read the Claude Code OAuth token from the macOS login
+// Keychain.
+//
+// `claude login` on macOS stores its credential in the OS Keychain (there is no
+// ~/.claude/.credentials.json file like on Linux), so lazyclaw's keyless paths
+// (model listing, trainer detection) couldn't see an existing, working login
+// and fell back to an "authenticate first" error. This reads that Keychain item
+// — the same JSON blob the Linux file holds — and returns its accessToken.
+//
+// Read-only and macOS-only. The token is only ever sent to api.anthropic.com,
+// never logged. The first read may surface a one-time Keychain access prompt;
+// granting it ("Always Allow") makes subsequent reads silent.
+
+import { execFileSync } from 'node:child_process';
+
+// macOS stores the Claude Code credential under this generic-password service.
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+
+// Pull the accessToken out of the credential blob (same shape as the Linux
+// ~/.claude/.credentials.json file). Returns a non-empty string or null.
+export function _extractAccessToken(raw) {
+  if (!raw || !String(raw).trim()) return null;
+  let j;
+  try { j = JSON.parse(raw); } catch { return null; }
+  const o = (j && j.claudeAiOauth) || j || {};
+  const tok = o.accessToken || o.access_token || (j && j.accessToken);
+  return (typeof tok === 'string' && tok) ? tok : null;
+}
+
+// Read the Claude Code OAuth access token from the macOS Keychain. Returns the
+// token string, or null on non-macOS, a missing item, denied access, or an
+// unparseable blob. `exec`/`platform` are injectable for tests.
+export function readClaudeKeychainToken({ platform = process.platform, exec } = {}) {
+  if (platform !== 'darwin') return null;
+  const run = exec || ((args) => execFileSync('security', args, { encoding: 'utf8', timeout: 8000 }));
+  let raw;
+  try { raw = run(['find-generic-password', '-s', KEYCHAIN_SERVICE, '-w']); }
+  catch { return null; }
+  return _extractAccessToken(raw);
+}

package/providers/model_catalogue.mjs

@@ -14,6 +14,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { readClaudeKeychainToken } from './claude_keychain.mjs';
 
 /**
  * Whether a provider exposes a model catalogue we can live-fetch. True for
@@ -146,7 +147,7 @@ export function modelCatalogueFor({ cfg, registryMod, resolveAuthKey, providerId
 // (no file), so this returns null there — the caller falls through to its
 // honest "set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN" error. Read-only;
 // the token is only ever sent to api.anthropic.com, never logged.
-export function _claudeCodeOAuthToken({ home, readFileSync } = {}) {
+export function _claudeCodeOAuthToken({ home, readFileSync, keychainReader } = {}) {
   const h = home || os.homedir();
   const read = readFileSync || fs.readFileSync;
   for (const rel of ['.claude/.credentials.json', '.config/claude/.credentials.json']) {
@@ -156,7 +157,9 @@ export function _claudeCodeOAuthToken({ home, readFileSync } = {}) {
       if (typeof tok === 'string' && tok) return tok;
     } catch { /* missing / unreadable / not JSON — try the next location */ }
   }
-  return null;
+  // macOS keeps the login in the Keychain (no file) — read it there.
+  const fromKeychain = (keychainReader || readClaudeKeychainToken)();
+  return fromKeychain || null;
 }
 
 // A plain API key stored by `codex login --api-key` in ~/.codex/auth.json.

package/web/dashboard.js

@@ -1409,7 +1409,13 @@
       }
       return 1; // generic PM look
     }
-    function avatarSrc(rec) { return `/avatars/${String(avatarIndexFor(rec)).padStart(2, '0')}.png`; }
+    // A user-supplied custom image (set via `lazyclaw agent set-avatar`) wins
+    // over the picked/inferred built-in sprite. rec.avatarImage is already a
+    // ready-to-use src (a remote URL or a daemon-served /agent-avatars/ path).
+    function avatarSrc(rec) {
+      if (rec && rec.avatarImage) return rec.avatarImage;
+      return `/avatars/${String(avatarIndexFor(rec)).padStart(2, '0')}.png`;
+    }
     // Build the { name, children[] } tree rooted at the lead (mirrors teamTree).
     function buildTeamTree(team, byId) {
       const lead = team.lead;