clideck 1.31.23 → 1.31.24

package/agent-session-guide.js

@@ -0,0 +1,43 @@
+const { binName } = require('./utils');
+
+const GUIDE = `CliDeck session guide:
+You are running inside CliDeck only when CLIDECK_SESSION_ID is set.
+Use clideck agents to discover peer sessions.
+Use clideck ask status to see which sessions are idle or busy.
+Use clideck ask "<target>" "<message>" --timeout 10m to ask an idle peer agent.
+Use the exact @project/session address from clideck agents --all for cross-project asks.
+Keep clideck ask running until it exits; the answer returns on stdout.
+If a target is busy, the request is not queued. Try later or ask another idle agent.
+If CLIDECK_SESSION_ID is missing, ignore this guide.`;
+
+function commandStart(parts) {
+  if (process.platform === 'win32' && parts.length > 2 && /^cmd(?:\.exe)?$/i.test(binName(parts[0])) && parts[1].toLowerCase() === '/c') {
+    return 2;
+  }
+  return 0;
+}
+
+function hasCodexDeveloperInstructions(parts) {
+  return parts.some((part, idx) => {
+    if (part === '-c' || part === '--config') return String(parts[idx + 1] || '').startsWith('developer_instructions=');
+    return String(part || '').startsWith('-cdeveloper_instructions=')
+      || String(part || '').startsWith('--config=developer_instructions=');
+  });
+}
+
+function withCliDeckGuide(parts, presetId) {
+  const next = [...parts];
+  const idx = commandStart(next);
+
+  if (presetId === 'claude-code') {
+    if (next.includes('--system-prompt') || next.includes('--append-system-prompt')) return next;
+    next.splice(idx + 1, 0, '--append-system-prompt', GUIDE);
+  } else if (presetId === 'codex') {
+    if (hasCodexDeveloperInstructions(next)) return next;
+    next.splice(idx + 1, 0, '-c', `developer_instructions=${JSON.stringify(GUIDE)}`);
+  }
+
+  return next;
+}
+
+module.exports = { withCliDeckGuide, GUIDE };

package/bin/clideck.js

@@ -9,6 +9,7 @@ function usage() {
     'Usage:',
     '  clideck [--host <host>] [--port <port>]',
     '  clideck agents [--json] [--all]',
+    '  clideck ask status [--json] [--all]',
     '  clideck ask --session <name-or-id> --message <text> [--timeout 10m]',
     '',
     'Options:',
@@ -25,6 +26,8 @@ function usage() {
     '',
     '  clideck ask',
     '    Use from inside a CliDeck session when one agent needs an answer from another session.',
+    '    This lets agents communicate with each other without manual copy/paste through the user.',
+    '    Use `clideck ask status` first when the agent only needs idle/busy state.',
     '',
     'Ask behavior:',
     '  Unscoped target lookup is limited to the same project as the caller session.',
@@ -45,13 +48,18 @@ function usage() {
     '  clideck agents',
     '  clideck agents --json',
     '  clideck agents --all',
+    '  clideck ask status',
+    '  clideck ask status --all',
     '  clideck ask --session "Reviewer" --message "Review my changes and return only findings."',
     '  clideck ask "research manager" "Check this plan and tell me what is missing." --timeout 15m',
     '  clideck ask "@website/Docs Writer" "Check if the docs mention the new CLI flags." --timeout 15m',
     '  cat notes.md | clideck ask --session "Docs Writer" --timeout 10m',
     '',
     'Notes for agents:',
+    '  CliDeck supports agent-to-agent communication: discover teammates with `clideck agents`,',
+    '  then ask them directly with `clideck ask`.',
     '  Run `clideck agents` to discover available same-project sessions.',
+    '  Run `clideck ask status` to check who is idle or busy before dispatching work.',
     '  Run `clideck agents --all` before a cross-project ask.',
     '  Run `clideck ask --help` for the exact ask command contract.',
     '  If a target has spaces, quote the whole target, including @project/session addresses.',

package/clideck-agents-cli.js

@@ -7,6 +7,7 @@ function usage() {
     '  clideck agents [--json] [--all]',
     '',
     'Lists active CliDeck sessions in the same project as the caller session.',
+    'Use this to discover other agents before communicating with them through `clideck ask`.',
     'Use this from inside a CliDeck session before `clideck ask` to discover target names.',
     'Use --all to discover cross-project targets and their @project/session ask addresses.',
     'Use the printed ask= value exactly when present, and prefer idle targets for `clideck ask`.',

package/clideck-ask-cli.js

@@ -4,15 +4,18 @@ const https = require('https');
 function usage() {
   return [
     'Usage:',
+    '  clideck ask status [--json] [--all]',
     '  clideck ask --session <name-or-id> --message <text> [--timeout 10m]',
     '  clideck ask <name-or-id> <message> [--timeout 10m]',
     '  clideck ask "@project-name/session-name" <message> [--timeout 10m]',
     '  cat file.txt | clideck ask --session <name-or-id> [--timeout 10m]',
     '',
     'Use from inside a CliDeck session when this agent needs an answer from another active session.',
+    'CliDeck ask lets agents communicate with each other without manual copy/paste through the user.',
     'Unscoped target lookup is limited to the same project as the caller session.',
     'Use @project/session only when you intentionally need to ask across projects.',
     'Run `clideck agents` or `clideck agents --all` first to discover available target sessions.',
+    'Run `clideck ask status` to quickly see which project sessions are idle or busy.',
     'Copy and use the target exactly as listed by `clideck agents`; quote it if it contains spaces.',
     '',
     'Important for agents:',
@@ -28,15 +31,32 @@ function usage() {
     '  To ask multiple agents, start one `clideck ask` command per target and keep each command open.',
     '',
     'Options:',
+    '  status                   Show idle/busy state for active project sessions.',
     '  -s, --session <name-or-id>  Target session name or id.',
     '  -m, --message <text>       Message to send. If omitted, stdin is used.',
     '  -t, --timeout <duration>   Wait time. Examples: 30s, 10m, 1h. Default: 10m.',
     '  --url <url>                CliDeck server URL. Default: CLIDECK_URL or local port.',
+    '  --json                     With status: print machine-readable JSON.',
+    '  --all                      With status: include all projects.',
     '  --no-progress              Do not print waiting hints to stderr.',
     '  -h, --help                 Show this help.',
   ].join('\n');
 }
 
+function parseStatusArgs(args) {
+  const port = process.env.CLIDECK_PORT || process.env.PORT || '4000';
+  const out = { json: false, all: false, url: process.env.CLIDECK_URL || `http://127.0.0.1:${port}` };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') out.json = true;
+    else if (arg === '--all') out.all = true;
+    else if (arg === '--url') out.url = args[++i];
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else throw new Error(`Unknown status argument: ${arg}`);
+  }
+  return out;
+}
+
 function parseDuration(value) {
   if (!value) return 10 * 60 * 1000;
   const m = String(value).trim().match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i);
@@ -133,6 +153,32 @@ function findAgent(agents, target) {
   return insensitive.length === 1 ? insensitive[0] : null;
 }
 
+function formatStatus(agents, opts = {}) {
+  if (!agents.length) return opts.all ? 'No active sessions found.' : 'No active sessions found in this project.';
+  return agents.map(a => {
+    const status = a.working ? 'busy' : 'idle';
+    const self = a.caller ? ' self' : '';
+    const address = a.address && a.address !== a.name ? ` ${a.address}` : '';
+    const project = opts.all && a.project ? ` project="${a.project}"` : '';
+    return `${status.padEnd(4)}  ${a.name}${self}${address}${project}`;
+  }).join('\n');
+}
+
+async function runStatus(args) {
+  const opts = parseStatusArgs(args);
+  if (opts.help) {
+    console.log(usage());
+    return;
+  }
+  const callerSessionId = process.env.CLIDECK_SESSION_ID || '';
+  if (!callerSessionId) throw new Error('CLIDECK_SESSION_ID is missing. Run this from inside a CliDeck session.');
+  const all = opts.all ? '&all=1' : '';
+  const res = await getJson(opts.url, `/api/session/agents?callerSessionId=${encodeURIComponent(callerSessionId)}${all}`);
+  const agents = (res.agents || []).map(a => ({ ...a, status: a.working ? 'busy' : 'idle' }));
+  if (opts.json) process.stdout.write(JSON.stringify(agents, null, 2) + '\n');
+  else process.stdout.write(formatStatus(agents, opts) + '\n');
+}
+
 function startProgressHints(opts, callerSessionId) {
   if (!opts.progress) return () => {};
   const started = Date.now();
@@ -212,6 +258,10 @@ function postJson(url, payload, timeoutMs) {
 
 async function run(args) {
   try {
+    if (args[0] === 'status') {
+      await runStatus(args.slice(1));
+      return;
+    }
     const opts = parseArgs(args);
     if (opts.help) {
       console.log(usage());
@@ -236,4 +286,4 @@ async function run(args) {
   }
 }
 
-module.exports = { run, parseArgs, parseDuration };
+module.exports = { run, parseArgs, parseDuration, parseStatusArgs, formatStatus };

package/config.js

@@ -47,6 +47,8 @@ const DEFAULTS = {
   notifySoundEnabled: true,
   notifySound: 'soft-beep',
   notifyMinWork: 0,
+  askDispatchSoundEnabled: true,
+  askDispatchSound: 'agent-dispatch-ambient',
   defaultTheme: 'catppuccin-mocha',
   defaultShell,
   prompts: [],

package/handlers.js

@@ -261,11 +261,11 @@ function detectTelemetryConfig(c) {
           repairAllowed = repairAllowed || hasAnyExistingHook(hooks, 'claude-hook.js');
           detected = hasExistingHook(hooks.UserPromptSubmit, 'claude-hook.js', 'start')
                   && hasExistingHook(hooks.Stop, 'claude-hook.js', 'stop')
-                  && hasExistingHook(hooks.StopFailure, 'claude-hook.js', 'stop')
                   && hasExistingHook(hooks.SessionStart, 'claude-hook.js', 'session-start')
                   && hasExistingHook(hooks.SessionEnd, 'claude-hook.js', 'session-end')
                   && hasExistingHook(hooks.PreToolUse, 'claude-hook.js', 'menu')
-                  && hooks.Notification?.some(h => h.matcher === 'idle_prompt' && hasExistingHook([h], 'claude-hook.js', 'idle'));
+                  && hooks.Notification?.some(h => h.matcher === 'idle_prompt' && hasExistingHook([h], 'claude-hook.js', 'idle'))
+                  && !hooks.StopFailure;
           if (detected && cmd.telemetrySetupConsent !== true) {
             cmd.telemetrySetupConsent = true;
             changed = true;
@@ -765,24 +765,23 @@ function applyTelemetryConfig(preset, cmd = null) {
       const hasClideck = (arr, path) => arr?.some(h => h.hooks?.some(x => x.command === hookCmd(path)));
       if (hasClideck(hooks.UserPromptSubmit, 'start')
           && hasClideck(hooks.Stop, 'stop')
-          && hasClideck(hooks.StopFailure, 'stop')
           && hasClideck(hooks.SessionStart, 'session-start')
           && hasClideck(hooks.SessionEnd, 'session-end')
           && hasClideck(hooks.PreToolUse, 'menu')
-          && hooks.Notification?.some(h => h.matcher === 'idle_prompt' && h.hooks?.some(x => x.command === hookCmd('idle')))) {
+          && hooks.Notification?.some(h => h.matcher === 'idle_prompt' && h.hooks?.some(x => x.command === hookCmd('idle')))
+          && !hooks.StopFailure) {
         return { success: true, message: 'Already configured' };
       }
       const stripOld = (arr) => (arr || []).filter(h => !h.hooks?.some(x => x.url?.includes('/hook/claude/') || x.command?.includes('claude-hook.js')));
       hooks.UserPromptSubmit = stripOld(hooks.UserPromptSubmit);
       hooks.Stop = stripOld(hooks.Stop);
-      hooks.StopFailure = stripOld(hooks.StopFailure);
+      delete hooks.StopFailure;
       hooks.SessionStart = stripOld(hooks.SessionStart);
       hooks.SessionEnd = stripOld(hooks.SessionEnd);
       hooks.PreToolUse = stripOld(hooks.PreToolUse);
       hooks.Notification = stripOld(hooks.Notification);
       if (!hasClideck(hooks.UserPromptSubmit, 'start')) hooks.UserPromptSubmit = [...(hooks.UserPromptSubmit || []), clideckHook('start')];
       if (!hasClideck(hooks.Stop, 'stop')) hooks.Stop = [...(hooks.Stop || []), clideckHook('stop')];
-      if (!hasClideck(hooks.StopFailure, 'stop')) hooks.StopFailure = [...(hooks.StopFailure || []), clideckHook('stop')];
       if (!hasClideck(hooks.SessionStart, 'session-start')) hooks.SessionStart = [...(hooks.SessionStart || []), clideckHook('session-start')];
       if (!hasClideck(hooks.SessionEnd, 'session-end')) hooks.SessionEnd = [...(hooks.SessionEnd || []), clideckHook('session-end')];
       if (!hasClideck(hooks.Notification, 'idle')) hooks.Notification = [...(hooks.Notification || []), { matcher: 'idle_prompt', ...clideckHook('idle') }];
@@ -883,7 +882,8 @@ function removeTelemetryConfig(preset, cmd = null) {
       let settings = {};
       try { settings = JSON.parse(readFileSync(configPath, 'utf8')); } catch {}
       if (!settings.hooks) return { success: true, message: 'No hooks to remove' };
-      for (const event of ['UserPromptSubmit', 'Stop', 'StopFailure', 'SessionStart', 'SessionEnd', 'Notification', 'PreToolUse']) {
+      delete settings.hooks.StopFailure;
+      for (const event of ['UserPromptSubmit', 'Stop', 'SessionStart', 'SessionEnd', 'Notification', 'PreToolUse']) {
         const arr = settings.hooks[event];
         if (!arr) continue;
         settings.hooks[event] = arr.filter(h => !h.hooks?.some(x => x.url?.includes('/hook/claude/') || x.command?.includes('claude-hook.js')));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clideck",
-  "version": "1.31.23",
+  "version": "1.31.24",
   "description": "One screen for all your AI coding agents — run, monitor, and manage multiple CLI agents from a single browser tab",
   "main": "server.js",
   "bin": {

package/public/index.html

@@ -372,6 +372,25 @@
             </button>
           </div>
         </div>
+        <div class="mb-5">
+          <label class="flex items-center gap-2 text-sm text-slate-300 cursor-pointer">
+            <input type="checkbox" id="cfg-ask-dispatch-sound" name="cfg-ask-dispatch-sound" class="accent-blue-500" checked>
+            Play sound when an agent dispatches another agent
+          </label>
+          <p class="text-xs text-slate-500 mt-1.5 ml-6">Soft ambient cue when `clideck ask` sends work into another session</p>
+        </div>
+        <div id="ask-dispatch-sound-row" class="mb-5 ml-6">
+          <label class="block text-xs text-slate-400 mb-1.5">Dispatch sound</label>
+          <div class="flex items-center gap-2">
+            <select id="cfg-ask-dispatch-sound-pick" class="flex-1 px-3 py-1.5 text-sm bg-slate-800 border border-slate-600 rounded-md text-slate-200 outline-none focus:border-blue-500 transition-colors cursor-pointer">
+              <option value="agent-dispatch-ambient">Ambient dispatch</option>
+              <option value="agent-dispatch-soft">Soft dispatch</option>
+            </select>
+            <button id="btn-ask-dispatch-sound-preview" class="flex-shrink-0 w-8 h-8 flex items-center justify-center rounded-md border border-slate-600 text-slate-400 hover:text-slate-200 hover:bg-slate-700 transition-colors" title="Preview dispatch sound">
+              <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"/><path d="M15.54 8.46a5 5 0 0 1 0 7.07"/><path d="M19.07 4.93a10 10 0 0 1 0 14.14"/></svg>
+            </button>
+          </div>
+        </div>
         <div class="mb-5">
           <label class="block text-xs text-slate-400 mb-1.5 ml-6">Minimum working time before notifying</label>
           <select id="cfg-notify-min-work" class="ml-6 px-3 py-1.5 text-sm bg-slate-800 border border-slate-600 rounded-md text-slate-200 outline-none focus:border-blue-500 transition-colors cursor-pointer">
@@ -384,8 +403,9 @@
           <p class="text-[11px] font-medium text-slate-400 mb-1.5">When do notifications fire?</p>
           <div class="text-[11px] text-slate-500 leading-relaxed space-y-1">
             <p><span class="text-slate-400">Sound</span> — plays for background sessions. If you're viewing the session, no sound.</p>
+            <p><span class="text-slate-400">Dispatch</span> — plays when `clideck ask` sends work into another agent.</p>
             <p><span class="text-slate-400">Browser</span> — only when the CliDeck tab is not in focus.</p>
-            <p><span class="text-slate-400">Mute</span> — right-click a session to mute both sound and browser notifications.</p>
+            <p><span class="text-slate-400">Mute</span> — right-click a session to mute notifications and dispatch cues for it.</p>
           </div>
         </div>
       </div>

package/public/js/app.js

@@ -37,6 +37,14 @@ function expandProjectForNewSession(projectId) {
   send({ type: 'config.update', config: state.cfg });
 }
 
+function playAskDispatchSound(msg) {
+  if (state.cfg.askDispatchSoundEnabled === false) return;
+  const target = state.terms.get(msg.toId);
+  if (target?.muted) return;
+  const sound = state.cfg.askDispatchSound || 'agent-dispatch-ambient';
+  new Audio(`/fx/${sound}.mp3`).play().catch(() => {});
+}
+
 function connect() {
   const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
   state.ws = new WebSocket(`${wsProtocol}//${location.host}`);
@@ -122,6 +130,9 @@ function connect() {
       case 'session.status':
         setStatus(msg.id, msg.working);
         break;
+      case 'session.dispatch':
+        playAskDispatchSound(msg);
+        break;
       // Server requests terminal capture (e.g. after PermissionRequest hook)
       case 'terminal.capture': {
         const ce = state.terms.get(msg.id);

package/public/js/settings.js

@@ -565,6 +565,11 @@ function renderNotifications() {
   document.getElementById('cfg-notify-sound').checked = soundEnabled;
   document.getElementById('notify-sound-row').classList.toggle('hidden', !soundEnabled);
   document.getElementById('cfg-notify-sound-pick').value = state.cfg.notifySound || 'default-beep';
+
+  const dispatchSoundEnabled = state.cfg.askDispatchSoundEnabled !== false;
+  document.getElementById('cfg-ask-dispatch-sound').checked = dispatchSoundEnabled;
+  document.getElementById('ask-dispatch-sound-row').classList.toggle('hidden', !dispatchSoundEnabled);
+  document.getElementById('cfg-ask-dispatch-sound-pick').value = state.cfg.askDispatchSound || 'agent-dispatch-ambient';
 }
 
 document.getElementById('cfg-notify-idle').addEventListener('change', (e) => {
@@ -589,6 +594,18 @@ document.getElementById('btn-sound-preview').addEventListener('click', () => {
   new Audio(`/fx/${sound}.mp3`).play().catch(() => {});
 });
 
+document.getElementById('cfg-ask-dispatch-sound').addEventListener('change', (e) => {
+  document.getElementById('ask-dispatch-sound-row').classList.toggle('hidden', !e.target.checked);
+  saveConfig();
+});
+
+document.getElementById('cfg-ask-dispatch-sound-pick').addEventListener('change', saveConfig);
+
+document.getElementById('btn-ask-dispatch-sound-preview').addEventListener('click', () => {
+  const sound = document.getElementById('cfg-ask-dispatch-sound-pick').value;
+  new Audio(`/fx/${sound}.mp3`).play().catch(() => {});
+});
+
 // ── Save ──
 
 function saveConfig() {
@@ -628,6 +645,8 @@ function saveConfig() {
   state.cfg.notifyMinWork = parseInt(document.getElementById('cfg-notify-min-work').value, 10) || 0;
   state.cfg.notifySoundEnabled = document.getElementById('cfg-notify-sound').checked;
   state.cfg.notifySound = document.getElementById('cfg-notify-sound-pick').value;
+  state.cfg.askDispatchSoundEnabled = document.getElementById('cfg-ask-dispatch-sound').checked;
+  state.cfg.askDispatchSound = document.getElementById('cfg-ask-dispatch-sound-pick').value;
   // Preserve fields not managed by this form
   // (projects, prompts, etc. live on state.cfg and must not be dropped)
   send({ type: 'config.update', config: state.cfg });

package/session-ask.js

@@ -214,6 +214,13 @@ async function askSession(payload, sessionsApi, cfg = {}) {
 
   console.log(`[ask] ${caller.name || callerId.slice(0, 8)} -> ${target.name || targetId.slice(0, 8)} (${timeoutMs}ms timeout)`);
   const cancelSubmit = submitAskInput(sessionsApi, targetId, injected);
+  sessionsApi.broadcast({
+    type: 'session.dispatch',
+    fromId: callerId,
+    fromName: caller.name || callerId.slice(0, 8),
+    toId: targetId,
+    toName: target.name || targetId.slice(0, 8),
+  });
 
   const response = await waitForAnswer({ sessionsApi, targetId, sinceTs, timeoutMs }).finally(cancelSubmit);
   console.log(`[ask] completed ${target.name || targetId.slice(0, 8)} -> ${caller.name || callerId.slice(0, 8)}`);

package/sessions.js

@@ -11,6 +11,7 @@ const piBridge = require('./pi-bridge');
 const plugins = require('./plugin-loader');
 const { presetForCommand } = require('./preset-utils');
 const { stripAnsi } = require('./ansi-utils');
+const { withCliDeckGuide } = require('./agent-session-guide');
 
 const THEMES = require('./themes');
 const MAX_BUFFER = 2 * 1024 * 1024;
@@ -98,12 +99,14 @@ function isLightTheme(themeId) {
 }
 
 function spawnSession(id, cmd, parts, cwd, name, themeId, commandId, savedToken, projectId, cols, rows) {
+  const preset = matchPreset(cmd);
+  const launchParts = withCliDeckGuide(parts, preset?.presetId);
   const telemetryEnv = buildTelemetryEnv(id, cmd);
   const colorEnv = isLightTheme(themeId) ? { COLORFGBG: '0;15' } : { COLORFGBG: '15;0' };
   const extraEnv = commandEnv(cmd);
   let term;
   try {
-    term = pty.spawn(parts[0], parts.slice(1), {
+    term = pty.spawn(launchParts[0], launchParts.slice(1), {
       name: 'xterm-256color', cols: cols || 80, rows: rows || 24, cwd,
       env: { ...process.env, ...extraEnv, ...telemetryEnv, ...colorEnv },
     });
@@ -112,7 +115,6 @@ function spawnSession(id, cmd, parts, cwd, name, themeId, commandId, savedToken,
   }
 
   const sessionIdRe = cmd.sessionIdPattern ? new RegExp(cmd.sessionIdPattern, 'i') : null;
-  const preset = matchPreset(cmd);
   const session = { name, themeId, commandId, cwd, pty: term, chunks: [], chunksSize: 0, sessionToken: savedToken || null, projectId: projectId || null, presetId: preset?.presetId || 'shell', working: undefined };
   sessions.set(id, session);
   transcript.setFinalizeOnIdle(id, ['claude-code', 'codex', 'gemini-cli', 'opencode', 'pi', 'clideck-agent'].includes(session.presetId) ? session.presetId : null);