ccnav 1.0.0 → 1.1.0

package/README.md

@@ -6,15 +6,24 @@ Works on Windows, macOS and Linux with Node 20 or later. Everything that differs
 
 ## Install
 
-From a checkout (any OS):
+```sh
+npm install -g ccnav    # the -g matters
+ccnav --install-shell   # optional: leave your shell in the session's directory afterwards
+```
+
+Without `-g`, npm treats the current folder as a project and puts the command in
+`./node_modules/.bin`, which is not on PATH — the install succeeds and `ccnav` still
+reports `command not found`. If that happens after a `-g` install, npm's global bin
+folder is missing from PATH; `npm prefix -g` prints the folder whose `bin` belongs there.
+
+From a checkout instead:
 
 ```sh
 npm install
 npm link                # puts `ccnav` on PATH
-ccnav --install-shell   # optional: leave your shell in the session's directory afterwards
 ```
 
-Or build a tarball once and install it anywhere, e.g. on a Mac:
+Or build a tarball once and install it anywhere:
 
 ```sh
 npm pack                        # -> ccnav-1.0.0.tgz
@@ -23,7 +32,21 @@ npm install -g ./ccnav-1.0.0.tgz
 
 `--install-shell` writes a function to the right file for your shell: the PowerShell `$PROFILE` on Windows, `~/.zshrc` for zsh (macOS default), `~/.bash_profile` (macOS) or `~/.bashrc` (Linux) for bash, and `~/.config/fish/functions/ccnav.fish` for fish. Running it again replaces the block rather than adding a second one.
 
-New tabs (`t`) use Windows Terminal, iTerm2, WezTerm, kitty, GNOME Terminal or Konsole. Terminal.app gets a new window, because real tabs need Accessibility permission.
+New tabs (`t`) use Windows Terminal, iTerm2, WezTerm, kitty, GNOME Terminal or Konsole. Terminal.app gets a new window, because real tabs need Accessibility permission. On macOS the first new tab asks for permission to control the terminal; if it is refused, allow it again under System Settings → Privacy & Security → Automation.
+
+## Agents
+
+Sessions are listed whether or not the agent that wrote them is still installed, so an
+old machine's transcripts stay visible. Resuming one whose agent is missing offers to
+install it:
+
+```
+codex is not installed. Install it now with "npm install -g @openai/codex"? (y/N)
+```
+
+Answer `y` and ccnav runs that install, then launches the agent so you can sign in and
+finish its own setup. Answer `n` and nothing is installed. `claude` maps to
+`@anthropic-ai/claude-code` and `codex` to `@openai/codex`.
 
 ## Use
 
@@ -34,7 +57,38 @@ ccnav --codex          only Codex sessions
 ccnav --list           print sessions and exit
 ccnav --json           print sessions as JSON and exit
 ccnav --model opus     any other arguments are passed to the agent
+ccnav here             new session in the current directory, running unattended
+ccnav here --codex     the same, without being asked which agent
+```
+
+## Start one here
+
+`ccnav here` ignores the session list entirely. It asks which agent, then starts a
+**new** session in the current directory with that agent's permission prompts turned
+off, so it runs unattended:
+
 ```
+New session in /Users/you/project
+
+  1) ◆ claude  claude --dangerously-skip-permissions
+  2) ● codex   codex --dangerously-bypass-approvals-and-sandbox
+
+Which agent? [1]
+```
+
+Pressing enter takes the first agent; `1`/`2` or a name (`codex`, `cl`) picks one.
+`ccnav here --claude` or `--codex` skips the question, and any other arguments go to
+the agent (`ccnav here --claude --model opus`). The exact command is printed before it
+runs, and ctrl-D at the prompt starts nothing.
+
+What those flags mean is worth being clear about. Claude's
+`--dangerously-skip-permissions` bypasses every permission check. Codex's
+`--dangerously-bypass-approvals-and-sandbox` skips approvals *and* runs without a
+sandbox — its own help calls it EXTREMELY DANGEROUS and intends it for environments
+that are already sandboxed. Neither confines the agent to the directory you started in.
+Codex removed `--full-auto` in 0.156, so the sandboxed middle ground is now spelled
+`--ask-for-approval never --sandbox workspace-write` if you would rather edit
+`src/providers/codex.mjs` to use that instead.
 
 | Key | Action |
 |---|---|

package/bin/ccnav.mjs

@@ -2,8 +2,8 @@
 import React from 'react';
 import { render } from 'ink';
 import { App } from '../src/app.mjs';
-import { ago, humanSize, listSessions, providerOf, shortPath } from '../src/sessions.mjs';
-import { installShellFunction, launchAgent, reportCwd } from '../src/actions.mjs';
+import { AGENTS, PROVIDERS, ago, humanSize, listSessions, providerOf, shortPath } from '../src/sessions.mjs';
+import { askUser, ensureAgent, installShellFunction, launchAgent, reportCwd } from '../src/actions.mjs';
 
 const args = process.argv.slice(2);
 
@@ -17,6 +17,9 @@ usage:
   ccnav --codex          only Codex sessions
   ccnav --list           print sessions as a table and exit
   ccnav --json           print sessions as JSON and exit
+  ccnav here             skip the picker: start a NEW session in the current
+                         directory, running unattended with no permission prompts
+                         (ccnav here --claude / --codex picks the agent outright)
   ccnav --install-shell  add a shell function (PowerShell, zsh, bash or fish) so
                          your shell is left in the session's directory afterwards
 
@@ -24,6 +27,40 @@ Any other arguments are passed to the agent (e.g. ccnav --model opus).`);
   process.exit(0);
 }
 
+// `ccnav here` never touches the session list: it starts a new one in this directory.
+async function chooseAgent() {
+  if (!process.stdin.isTTY) {
+    console.error('ccnav here needs an interactive terminal, or name the agent: ccnav here --claude');
+    process.exit(1);
+  }
+  console.log(`\nNew session in ${process.cwd()}\n`);
+  AGENTS.forEach((a, i) => {
+    const p = PROVIDERS[a];
+    console.log(`  ${i + 1}) ${p.glyph} ${a.padEnd(7)} ${p.command} ${p.AUTO_ARGS.join(' ')}`);
+  });
+  const answer = await askUser(`\nWhich agent? [1] `);
+  // EOF is not a choice: never start an unattended agent nobody actually asked for.
+  if (answer === null) { console.error('\nNo answer given, nothing started.'); process.exit(1); }
+  if (!answer) return AGENTS[0];
+  const byNumber = AGENTS[Number(answer) - 1];
+  if (byNumber) return byNumber;
+  const byName = AGENTS.find(a => a.startsWith(answer.toLowerCase()));
+  if (byName) return byName;
+  console.error(`Not an agent: ${answer}`);
+  process.exit(1);
+}
+
+if (args[0] === 'here') {
+  const rest = args.slice(1);
+  const named = AGENTS.find(a => rest.includes(`--${a}`));
+  const extra = rest.filter(a => a !== '--' && !AGENTS.some(x => a === `--${x}`));
+  const provider = PROVIDERS[named || await chooseAgent()];
+  if (!await ensureAgent(provider.command)) process.exit(127);
+  const argv = [...provider.AUTO_ARGS, ...extra];
+  console.log(`\n\u2192 ${process.cwd()}\n\u2192 ${provider.command} ${argv.join(' ')}\n`);
+  process.exit(await launchAgent(provider.command, process.cwd(), argv));
+}
+
 if (args.includes('--install-shell')) {
   const { shell, file, reload } = installShellFunction();
   console.log(`ccnav ${shell} function written to ${file}\nto use it now: ${reload}`);
@@ -64,6 +101,9 @@ const { action, session } = choice;
 const provider = providerOf(session);
 const agentArgs = provider.launchArgs(action, session, passthrough);
 
+// The agent may not be installed yet; offer to install it rather than just failing.
+if (!await ensureAgent(provider.command)) process.exit(127);
+
 reportCwd(session.cwd);
 console.log(`\n→ ${session.cwd}\n→ ${provider.command} ${agentArgs.join(' ')}\n`);
 process.exit(await launchAgent(provider.command, session.cwd, agentArgs));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccnav",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Claude Codex Navigator - pick a Claude Code or Codex session and resume it in its directory",
   "scripts": {
     "test": "node --test"

package/src/actions.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-export { copyToClipboard, installShellFunction, launchAgent, openFolder, openInNewTab } from './platform.mjs';
+export { askUser, copyToClipboard, ensureAgent, hasCommand, installShellFunction, launchAgent, openFolder, openInNewTab } from './platform.mjs';
 
 // Sessions touched this recently may be open in another terminal.
 export const LIVE_WINDOW_MS = 10 * 60 * 1000;

package/src/app.mjs

@@ -1,7 +1,7 @@
 import React, { useEffect, useMemo, useState } from 'react';
 import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import { AGENTS, ago, humanSize, providerOf } from './sessions.mjs';
-import { archiveSession, copyToClipboard, isMaybeLive, openFolder, openInNewTab, searchTranscript } from './actions.mjs';
+import { archiveSession, copyToClipboard, hasCommand, isMaybeLive, openFolder, openInNewTab, searchTranscript } from './actions.mjs';
 
 const h = React.createElement;
 
@@ -212,6 +212,11 @@ export function App({ sessions: initialSessions, onChoose, passthrough = [] }) {
     else if (input === 't' && sel && requireDir()) {
       try {
         const p = providerOf(sel);
+        // A new tab has nowhere to report an install prompt, so send them to enter instead.
+        if (!hasCommand(p.command)) {
+          flash(`${p.command} is not installed — press enter to resume and ccnav will offer to install it.`, 'yellow');
+          return;
+        }
         const where = openInNewTab(p.command, sel.cwd, p.launchArgs('resume', sel, passthrough), oneLine(sel.title) || sel.id);
         flash(`Opened "${oneLine(sel.title) || sel.id}" in a new ${where}`);
       } catch (e) { flash(`Could not open a new tab: ${e.message}`, 'red'); }

package/src/platform.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import readline from 'node:readline';
 import { spawn, spawnSync } from 'node:child_process';
 
 export const IS_WIN = process.platform === 'win32';
@@ -11,16 +12,20 @@ const has = cmd => IS_WIN
   ? spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0
   : spawnSync('sh', ['-c', `command -v ${cmd}`], { stdio: 'ignore' }).status === 0;
 
+// Exported so the picker can warn before opening a tab that would only fail.
+export const hasCommand = has;
+
 // POSIX single-quote escaping for building `sh -c` / AppleScript command lines.
 const shq = s => `'${String(s).replace(/'/g, `'\\''`)}'`;
 // Windows command lines: quote args with spaces, strip embedded quotes (args are UUIDs and flags).
 const winq = s => /[\s"]/.test(s) ? `"${String(s).replace(/"/g, '')}"` : s;
 const osaString = s => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 
-const INSTALL_HINT = {
-  claude: 'npm install -g @anthropic-ai/claude-code',
-  codex: 'npm install -g @openai/codex',
+export const INSTALL_PKG = {
+  claude: '@anthropic-ai/claude-code',
+  codex: '@openai/codex',
 };
+const hint = cmd => INSTALL_PKG[cmd] ? ` Install it: npm install -g ${INSTALL_PKG[cmd]}` : '';
 
 // Runs the agent in the foreground with the session's directory as cwd; resolves with its exit code.
 export function launchAgent(cmd, cwd, args) {
@@ -31,7 +36,7 @@ export function launchAgent(cmd, cwd, args) {
       : spawn(cmd, args, { cwd, stdio: 'inherit' });
     child.on('error', e => {
       console.error(e.code === 'ENOENT'
-        ? `${cmd} was not found on PATH.${INSTALL_HINT[cmd] ? ` Install it: ${INSTALL_HINT[cmd]}` : ''}`
+        ? `${cmd} was not found on PATH.${hint(cmd)}`
         : `could not start ${cmd}: ${e.message}`);
       resolve(127);
     });
@@ -39,13 +44,85 @@ export function launchAgent(cmd, cwd, args) {
   });
 }
 
+// ---- installing a missing agent ----
+
+// Resolves the trimmed answer, or null when stdin closed without one (ctrl-D, a closed pipe).
+// Resolving on 'close' rather than only in the callback keeps the promise from hanging on EOF.
+export function askUser(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let answer = null;
+    rl.question(question, a => { answer = String(a).trim().toLowerCase(); rl.close(); });
+    rl.on('close', () => resolve(answer));
+  });
+}
+
+// Offers to install the agent when it is missing. Resolves true if it is on PATH afterwards.
+// The agent's own first-run login/setup then runs as usual when it launches.
+export async function ensureAgent(cmd) {
+  if (has(cmd)) return true;
+
+  const pkg = INSTALL_PKG[cmd];
+  if (!pkg) {
+    console.error(`${cmd} was not found on PATH.`);
+    return false;
+  }
+  // Without a terminal there is nobody to answer the prompt (e.g. piped output).
+  if (!process.stdin.isTTY) {
+    console.error(`${cmd} is not installed.${hint(cmd)}`);
+    return false;
+  }
+  if (!has('npm')) {
+    console.error(`${cmd} is not installed, and npm is not available to install it.`);
+    console.error(`Install Node.js 20 or later, then run: npm install -g ${pkg}`);
+    return false;
+  }
+
+  const answer = await askUser(`\n${cmd} is not installed. Install it now with "npm install -g ${pkg}"? (y/N) `);
+  if (answer !== 'y' && answer !== 'yes') {
+    console.log(`Skipped. You can install it later: npm install -g ${pkg}`);
+    return false;
+  }
+
+  console.log(`\nnpm install -g ${pkg}\n`);
+  const r = spawnSync(IS_WIN ? 'npm.cmd' : 'npm', ['install', '-g', pkg], { stdio: 'inherit', shell: IS_WIN });
+  if (r.error || r.status !== 0) {
+    console.error(`\nInstall failed${r.error ? `: ${r.error.message}` : ` (npm exited with ${r.status})`}.`);
+    console.error(`If it was a permissions error, npm's global folder is not writable by you.`);
+    console.error(`Check where it points with: npm prefix -g`);
+    return false;
+  }
+  if (!has(cmd)) {
+    console.error(`\n${pkg} installed, but "${cmd}" is still not on PATH.`);
+    console.error(`npm's global bin folder is probably not in PATH. Find it with: npm prefix -g`);
+    return false;
+  }
+  console.log(`\n${cmd} installed.\n`);
+  return true;
+}
+
+// ---- new terminal tabs ----
+
+const run = (cmd, argv) => {
+  const r = spawnSync(cmd, argv, { encoding: 'utf8' });
+  if (r.error) throw new Error(r.error.message);
+  if (r.status !== 0) {
+    // Keep the tool's own message: AppleScript errors are the only clue to a denied permission.
+    const detail = String(r.stderr || '').trim().split('\n').find(Boolean);
+    throw new Error(detail || `${cmd} exited with ${r.status}`);
+  }
+};
+
+// macOS asks for Automation permission the first time; a denial comes back as -1743.
+function macAutomationError(e, app) {
+  const msg = e?.message || String(e);
+  return /-1743|not authoriz/i.test(msg)
+    ? `macOS blocked ccnav from controlling ${app}. Allow your terminal under System Settings → Privacy & Security → Automation, then try again.`
+    : msg;
+}
+
 // Opens a new terminal tab (or window) in `cwd` running `cmd` with `args`. Throws if nothing worked.
 export function openInNewTab(cmd, cwd, args, title = cmd) {
-  const run = (cmd, argv) => {
-    const r = spawnSync(cmd, argv, { stdio: 'ignore' });
-    if (r.error || r.status !== 0) throw new Error(`${cmd} failed${r.error ? `: ${r.error.message}` : ` (exit ${r.status})`}`);
-  };
-
   if (IS_WIN) {
     const argv = ['-w', '0', 'new-tab', '--title', title.replace(/[;"]/g, ' ').slice(0, 40), '-d', cwd,
       'pwsh', '-NoExit', '-Command', cmd, ...args];
@@ -68,15 +145,27 @@ export function openInNewTab(cmd, cwd, args, title = cmd) {
   }
   if (IS_MAC) {
     if (term === 'iTerm.app') {
-      run('osascript', [
-        '-e', 'tell application "iTerm" to tell current window to create tab with default profile',
-        '-e', `tell application "iTerm" to tell current session of current window to write text ${osaString(shellCmd)}`,
-      ]);
+      try {
+        // A tab needs a window to live in: iTerm can be running with none open.
+        run('osascript', ['-e', [
+          'tell application "iTerm"',
+          '  activate',
+          '  if (count of windows) = 0 then',
+          '    create window with default profile',
+          '  else',
+          '    tell current window to create tab with default profile',
+          '  end if',
+          `  tell current session of current window to write text ${osaString(shellCmd)}`,
+          'end tell',
+        ].join('\n')]);
+      } catch (e) { throw new Error(macAutomationError(e, 'iTerm')); }
       return 'iTerm tab';
     }
     // Terminal.app (and anything else): a new Terminal window. Real tabs would need Accessibility permission.
-    run('osascript', ['-e', `tell application "Terminal" to do script ${osaString(shellCmd)}`,
-      '-e', 'tell application "Terminal" to activate']);
+    try {
+      run('osascript', ['-e', `tell application "Terminal" to do script ${osaString(shellCmd)}`,
+        '-e', 'tell application "Terminal" to activate']);
+    } catch (e) { throw new Error(macAutomationError(e, 'Terminal')); }
     return 'Terminal window';
   }
   if (has('gnome-terminal')) {

package/src/providers/claude.mjs

@@ -8,6 +8,8 @@ export const agent = 'claude';
 export const command = 'claude';
 export const glyph = '◆';
 export const color = 'cyan';
+// `ccnav here`: a fresh session that never stops to ask for permission.
+export const AUTO_ARGS = ['--dangerously-skip-permissions'];
 
 export const HOME_DIR = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 export const SESSIONS_ROOT = path.join(HOME_DIR, 'projects');

package/src/providers/codex.mjs

@@ -8,6 +8,9 @@ export const agent = 'codex';
 export const command = 'codex';
 export const glyph = '●';
 export const color = 'green';
+// `ccnav here`: codex removed --full-auto in 0.156, so the policy is named directly.
+// This is the counterpart to Claude's --dangerously-skip-permissions: no approvals, no sandbox.
+export const AUTO_ARGS = ['--dangerously-bypass-approvals-and-sandbox'];
 
 export const HOME_DIR = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
 export const SESSIONS_ROOT = path.join(HOME_DIR, 'sessions');