instar 0.1.0 → 0.1.2

package/README.md

@@ -187,7 +187,11 @@ The goal: make it possible for anyone to give their Claude Code project the kind
 - Node.js 18+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 - tmux (`brew install tmux` on macOS, `apt install tmux` on Linux)
-- A Claude subscription (Max or Pro) -- Instar uses your existing subscription, not API keys
+- Claude authentication -- either:
+  - An [Anthropic API key](https://console.anthropic.com/) (recommended for production/commercial use)
+  - A Claude subscription (Max or Pro) with Claude Code logged in (for personal use)
+
+Instar spawns the official Claude Code CLI and respects whatever authentication you have configured. It never extracts or proxies your credentials.
 
 ## License
 

package/dist/cli.js

@@ -25,7 +25,7 @@ const program = new Command();
 program
     .name('instar')
     .description('Persistent autonomy infrastructure for AI agents')
-    .version('0.1.0')
+    .version('0.1.2')
     .option('--classic', 'Use the classic inquirer-based setup wizard instead of Claude')
     .action((opts) => runSetup(opts)); // Default: run interactive setup when no subcommand given
 // ── Setup (explicit alias) ────────────────────────────────────────

package/dist/commands/init.js

@@ -31,7 +31,7 @@ import path from 'node:path';
 import pc from 'picocolors';
 import { randomUUID } from 'node:crypto';
 import { ensureStateDir } from '../core/Config.js';
-import { checkPrerequisites, printPrerequisiteCheck } from '../core/Prerequisites.js';
+import { ensurePrerequisites } from '../core/Prerequisites.js';
 import { defaultIdentity } from '../scaffold/bootstrap.js';
 import { generateAgentMd, generateUserMd, generateMemoryMd, generateClaudeMd, } from '../scaffold/templates.js';
 /**
@@ -57,9 +57,9 @@ async function initFreshProject(projectName, options) {
     console.log(pc.bold(`  Creating new agent project: ${pc.cyan(projectName)}`));
     console.log(pc.dim(`  Directory: ${projectDir}`));
     console.log();
-    // Check prerequisites
-    const prereqs = checkPrerequisites();
-    if (!printPrerequisiteCheck(prereqs)) {
+    // Check and install prerequisites
+    const prereqs = await ensurePrerequisites();
+    if (!prereqs.allMet) {
         process.exit(1);
     }
     // Check if directory already exists
@@ -198,9 +198,9 @@ async function initExistingProject(options) {
     const port = options.port || 4040;
     console.log(pc.bold(`\nInitializing instar in: ${pc.cyan(projectDir)}`));
     console.log();
-    // Check prerequisites
-    const prereqs = checkPrerequisites();
-    if (!printPrerequisiteCheck(prereqs)) {
+    // Check and install prerequisites
+    const prereqs = await ensurePrerequisites();
+    if (!prereqs.allMet) {
         process.exit(1);
     }
     const tmuxPath = prereqs.results.find(r => r.name === 'tmux').path;

package/dist/commands/setup.js

@@ -14,13 +14,14 @@
  *
  * No flags needed. No manual config editing. Just answers.
  */
-import { spawn } from 'node:child_process';
+import { execSync, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import pc from 'picocolors';
 import { input, confirm, select, number } from '@inquirer/prompts';
 import { Cron } from 'croner';
-import { detectTmuxPath, detectClaudePath, ensureStateDir } from '../core/Config.js';
+import { detectClaudePath, ensureStateDir } from '../core/Config.js';
+import { ensurePrerequisites } from '../core/Prerequisites.js';
 import { UserManager } from '../users/UserManager.js';
 /**
  * Launch the conversational setup wizard via Claude Code.
@@ -31,13 +32,21 @@ export async function runSetup(opts) {
     if (opts?.classic) {
         return runClassicSetup();
     }
-    // Check for Claude CLI
+    // Check and install prerequisites
+    console.log();
+    const prereqs = await ensurePrerequisites();
+    // Check for Claude CLI (may have been just installed)
     const claudePath = detectClaudePath();
     if (!claudePath) {
         console.log();
         console.log(pc.yellow('  Claude CLI not found — falling back to classic setup wizard.'));
         console.log(pc.dim('  Install Claude Code for the conversational experience:'));
-        console.log(pc.dim('  https://docs.anthropic.com/en/docs/claude-code'));
+        console.log(pc.dim('  npm install -g @anthropic-ai/claude-code'));
+        console.log();
+        return runClassicSetup();
+    }
+    if (!prereqs.allMet) {
+        console.log(pc.yellow('  Some prerequisites are still missing. Falling back to classic setup.'));
         console.log();
         return runClassicSetup();
     }
@@ -114,22 +123,14 @@ async function runClassicSetup() {
     console.log(pc.bold('  Welcome to Instar'));
     console.log(pc.dim('  Persistent agent infrastructure for any Claude Code project'));
     console.log();
-    // ── Step 0: Check prerequisites ──────────────────────────────────
-    const tmuxPath = detectTmuxPath();
-    const claudePath = detectClaudePath();
-    if (!tmuxPath) {
-        console.log(pc.red('  tmux is required but not installed.'));
-        console.log('  Install: brew install tmux (macOS) or apt install tmux (Linux)');
+    // ── Step 0: Check and install prerequisites ─────────────────────
+    const prereqs = await ensurePrerequisites();
+    if (!prereqs.allMet) {
         process.exit(1);
     }
-    console.log(`  ${pc.green('✓')} tmux found: ${pc.dim(tmuxPath)}`);
-    if (!claudePath) {
-        console.log(pc.red('  Claude CLI is required but not installed.'));
-        console.log('  Install: https://docs.anthropic.com/en/docs/claude-code');
-        process.exit(1);
-    }
-    console.log(`  ${pc.green('✓')} Claude CLI found: ${pc.dim(claudePath)}`);
-    console.log();
+    const tmuxPath = prereqs.results.find(r => r.name === 'tmux').path;
+    // Use a scoped name to avoid shadowing the outer runSetup's claudePath
+    const claudePath = prereqs.results.find(r => r.name === 'Claude CLI').path;
     // ── Step 1: Project ──────────────────────────────────────────────
     const detectedDir = process.cwd();
     const detectedName = path.basename(detectedDir);
@@ -302,6 +303,29 @@ async function runClassicSetup() {
     console.log(`    ${pc.cyan('.instar/jobs.json')}    — job definitions`);
     console.log(`    ${pc.cyan('.instar/users.json')}   — user profiles`);
     console.log();
+    // Check if instar is globally installed (needed for server commands)
+    const isGloballyInstalled = isInstarGlobal();
+    if (!isGloballyInstalled) {
+        console.log(pc.dim('  Tip: instar is not installed globally. For persistent server'));
+        console.log(pc.dim('  commands (start, stop, status), install it globally:'));
+        console.log();
+        const installGlobal = await confirm({
+            message: 'Install instar globally? (npm install -g instar)',
+            default: true,
+        });
+        if (installGlobal) {
+            try {
+                console.log(pc.dim('  Running: npm install -g instar'));
+                execSync('npm install -g instar', { encoding: 'utf-8', stdio: 'inherit' });
+                console.log(`  ${pc.green('✓')} instar installed globally`);
+            }
+            catch {
+                console.log(pc.yellow('  Could not install globally. You can run it later:'));
+                console.log(`    ${pc.cyan('npm install -g instar')}`);
+            }
+        }
+        console.log();
+    }
     // Offer to start server
     const startNow = await confirm({
         message: 'Start the agent server now?',
@@ -324,6 +348,22 @@ async function runClassicSetup() {
     }
     console.log();
 }
+/**
+ * Check if instar is installed globally (vs running via npx).
+ */
+function isInstarGlobal() {
+    try {
+        const result = execSync('which instar 2>/dev/null || where instar 2>/dev/null', {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        }).trim();
+        // npx creates a temp binary — check if it's a real global install
+        return !!result && !result.includes('.npm/_npx');
+    }
+    catch {
+        return false;
+    }
+}
 // ── Prompt Helpers ───────────────────────────────────────────────
 /**
  * Full Telegram walkthrough. Returns config or null if skipped.

package/dist/core/Prerequisites.d.ts

@@ -1,8 +1,8 @@
 /**
- * Prerequisite detection and installation guidance.
+ * Prerequisite detection and auto-installation.
  *
  * Checks for required software (tmux, Claude CLI, Node.js)
- * and provides clear installation instructions when something is missing.
+ * and offers to install missing dependencies automatically.
  */
 export interface PrerequisiteResult {
     name: string;
@@ -10,6 +10,10 @@ export interface PrerequisiteResult {
     path?: string;
     version?: string;
     installHint: string;
+    /** Whether this prerequisite can be auto-installed. */
+    canAutoInstall: boolean;
+    /** The command to run to auto-install this prerequisite. */
+    installCommand?: string;
 }
 export interface PrerequisiteCheck {
     allMet: boolean;
@@ -25,4 +29,9 @@ export declare function checkPrerequisites(): PrerequisiteCheck;
  * Returns true if all prerequisites are met.
  */
 export declare function printPrerequisiteCheck(check: PrerequisiteCheck): boolean;
+/**
+ * Interactive prerequisite check that offers to install missing dependencies.
+ * Returns a fresh PrerequisiteCheck after any installations.
+ */
+export declare function ensurePrerequisites(): Promise<PrerequisiteCheck>;
 //# sourceMappingURL=Prerequisites.d.ts.map

package/dist/core/Prerequisites.js

@@ -1,11 +1,12 @@
 /**
- * Prerequisite detection and installation guidance.
+ * Prerequisite detection and auto-installation.
  *
  * Checks for required software (tmux, Claude CLI, Node.js)
- * and provides clear installation instructions when something is missing.
+ * and offers to install missing dependencies automatically.
  */
 import { execSync } from 'node:child_process';
 import pc from 'picocolors';
+import { confirm } from '@inquirer/prompts';
 import { detectTmuxPath, detectClaudePath } from './Config.js';
 /**
  * Detect the current platform for install guidance.
@@ -69,27 +70,46 @@ function getNodeVersion() {
     return { version, major };
 }
 /**
- * Build install hint for tmux based on platform.
+ * Build install hint and command for tmux based on platform.
  */
-function tmuxInstallHint() {
+function tmuxInstallInfo() {
     const platform = detectPlatform();
     switch (platform) {
         case 'macos-arm':
         case 'macos-intel':
-            return hasHomebrew()
-                ? 'Install with: brew install tmux'
-                : 'Install Homebrew first (https://brew.sh), then: brew install tmux';
+            if (hasHomebrew()) {
+                return {
+                    hint: 'Install with: brew install tmux',
+                    canAutoInstall: true,
+                    command: 'brew install tmux',
+                };
+            }
+            return {
+                hint: 'Install Homebrew first (https://brew.sh), then: brew install tmux',
+                canAutoInstall: false,
+            };
         case 'linux':
-            return 'Install with: sudo apt install tmux (Debian/Ubuntu) or sudo yum install tmux (RHEL/CentOS)';
+            return {
+                hint: 'Install with: sudo apt install tmux (Debian/Ubuntu) or sudo yum install tmux (RHEL/CentOS)',
+                canAutoInstall: true,
+                command: 'sudo apt install -y tmux',
+            };
         default:
-            return 'Install tmux: https://github.com/tmux/tmux/wiki/Installing';
+            return {
+                hint: 'Install tmux: https://github.com/tmux/tmux/wiki/Installing',
+                canAutoInstall: false,
+            };
     }
 }
 /**
- * Build install hint for Claude CLI based on platform.
+ * Build install hint and command for Claude CLI.
  */
-function claudeInstallHint() {
-    return 'Install Claude Code: npm install -g @anthropic-ai/claude-code\n  Docs: https://docs.anthropic.com/en/docs/claude-code';
+function claudeInstallInfo() {
+    return {
+        hint: 'Install Claude Code: npm install -g @anthropic-ai/claude-code',
+        canAutoInstall: true,
+        command: 'npm install -g @anthropic-ai/claude-code',
+    };
 }
 /**
  * Check all prerequisites and return a structured result.
@@ -105,24 +125,31 @@ export function checkPrerequisites() {
         installHint: node.major < 18
             ? `Node.js 18+ required (found ${node.version}). Update: https://nodejs.org`
             : '',
+        canAutoInstall: false,
     });
     // 2. tmux
     const tmuxPath = detectTmuxPath();
+    const tmuxInfo = tmuxInstallInfo();
     results.push({
         name: 'tmux',
         found: !!tmuxPath,
         path: tmuxPath || undefined,
         version: tmuxPath ? getTmuxVersion(tmuxPath) : undefined,
-        installHint: tmuxInstallHint(),
+        installHint: tmuxInfo.hint,
+        canAutoInstall: tmuxInfo.canAutoInstall,
+        installCommand: tmuxInfo.command,
     });
     // 3. Claude CLI
     const claudePath = detectClaudePath();
+    const claudeInfo = claudeInstallInfo();
     results.push({
         name: 'Claude CLI',
         found: !!claudePath,
         path: claudePath || undefined,
         version: claudePath ? getClaudeVersion(claudePath) : undefined,
-        installHint: claudeInstallHint(),
+        installHint: claudeInfo.hint,
+        canAutoInstall: claudeInfo.canAutoInstall,
+        installCommand: claudeInfo.command,
     });
     const missing = results.filter(r => !r.found);
     return {
@@ -131,6 +158,26 @@ export function checkPrerequisites() {
         missing,
     };
 }
+/**
+ * Attempt to install a missing prerequisite.
+ * Returns true if installation succeeded.
+ */
+function installPrerequisite(result) {
+    if (!result.installCommand)
+        return false;
+    try {
+        console.log(pc.dim(`  Running: ${result.installCommand}`));
+        execSync(result.installCommand, {
+            encoding: 'utf-8',
+            stdio: 'inherit',
+            timeout: 120000, // 2 min timeout
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Print prerequisite check results to console.
  * Returns true if all prerequisites are met.
@@ -156,4 +203,61 @@ export function printPrerequisiteCheck(check) {
     }
     return check.allMet;
 }
+/**
+ * Interactive prerequisite check that offers to install missing dependencies.
+ * Returns a fresh PrerequisiteCheck after any installations.
+ */
+export async function ensurePrerequisites() {
+    let check = checkPrerequisites();
+    console.log(pc.bold('  Checking prerequisites...'));
+    console.log();
+    for (const result of check.results) {
+        if (result.found) {
+            const versionStr = result.version ? ` (${result.version})` : '';
+            const pathStr = result.path ? pc.dim(` ${result.path}`) : '';
+            console.log(`  ${pc.green('✓')} ${result.name}${versionStr}${pathStr}`);
+        }
+    }
+    if (check.allMet) {
+        console.log();
+        return check;
+    }
+    // Handle missing prerequisites
+    for (const missing of check.missing) {
+        console.log();
+        console.log(`  ${pc.red('✗')} ${missing.name} — not found`);
+        if (missing.canAutoInstall && missing.installCommand) {
+            const install = await confirm({
+                message: `Install ${missing.name}? (${pc.dim(missing.installCommand)})`,
+                default: true,
+            });
+            if (install) {
+                const success = installPrerequisite(missing);
+                if (success) {
+                    console.log(`  ${pc.green('✓')} ${missing.name} installed successfully`);
+                }
+                else {
+                    console.log(`  ${pc.red('✗')} Failed to install ${missing.name}`);
+                    console.log(`    Try manually: ${missing.installHint}`);
+                }
+            }
+            else {
+                console.log(`    ${missing.installHint}`);
+            }
+        }
+        else {
+            console.log(`    ${missing.installHint}`);
+        }
+    }
+    // Re-check after installations
+    check = checkPrerequisites();
+    console.log();
+    if (!check.allMet) {
+        const stillMissing = check.missing.map(r => r.name).join(', ');
+        console.log(pc.red(`  Still missing: ${stillMissing}`));
+        console.log(pc.dim('  Install the missing prerequisites and run instar again.'));
+        console.log();
+    }
+    return check;
+}
 //# sourceMappingURL=Prerequisites.js.map

package/dist/core/SessionManager.js

@@ -68,9 +68,8 @@ export class SessionManager extends EventEmitter {
         }
         claudeArgs.push('-p', options.prompt);
         // Create tmux session and run claude
-        // Unset ANTHROPIC_* env vars so Claude uses OAuth (subscription) not API key
-        const cleanEnv = 'unset ANTHROPIC_API_KEY ANTHROPIC_ADMIN_KEY CLAUDECODE;';
-        const claudeCmd = `${cleanEnv} ${this.config.claudePath} ${claudeArgs.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`;
+        // Respect the user's configured auth method (API key or OAuth subscription)
+        const claudeCmd = `${this.config.claudePath} ${claudeArgs.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`;
         const tmuxCmd = [
             this.config.tmuxPath,
             'new-session',
@@ -223,9 +222,9 @@ export class SessionManager extends EventEmitter {
             }
             return tmuxSession;
         }
-        // Unset ANTHROPIC_* env vars so Claude uses OAuth (subscription) not API key
+        // Respect the user's configured auth method (API key or OAuth subscription)
         const claudeCmd = `${this.config.claudePath} --dangerously-skip-permissions`;
-        const shellCmd = `cd '${this.config.projectDir}' && unset ANTHROPIC_API_KEY ANTHROPIC_ADMIN_KEY CLAUDECODE && ${claudeCmd}`;
+        const shellCmd = `cd '${this.config.projectDir}' && ${claudeCmd}`;
         const tmuxCmd = `${this.config.tmuxPath} new-session -d -s '${tmuxSession}' -x 200 -y 50 'bash -c "${shellCmd.replace(/"/g, '\\"')}"'`;
         try {
             execSync(tmuxCmd, { encoding: 'utf-8' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -29,7 +29,7 @@ const program = new Command();
 program
   .name('instar')
   .description('Persistent autonomy infrastructure for AI agents')
-  .version('0.1.0')
+  .version('0.1.2')
   .option('--classic', 'Use the classic inquirer-based setup wizard instead of Claude')
   .action((opts) => runSetup(opts)); // Default: run interactive setup when no subcommand given
 

package/src/commands/init.ts

@@ -32,7 +32,7 @@ import path from 'node:path';
 import pc from 'picocolors';
 import { randomUUID } from 'node:crypto';
 import { detectTmuxPath, detectClaudePath, ensureStateDir } from '../core/Config.js';
-import { checkPrerequisites, printPrerequisiteCheck } from '../core/Prerequisites.js';
+import { ensurePrerequisites } from '../core/Prerequisites.js';
 import { defaultIdentity } from '../scaffold/bootstrap.js';
 import {
   generateAgentMd,
@@ -75,9 +75,9 @@ async function initFreshProject(projectName: string, options: InitOptions): Prom
   console.log(pc.dim(`  Directory: ${projectDir}`));
   console.log();
 
-  // Check prerequisites
-  const prereqs = checkPrerequisites();
-  if (!printPrerequisiteCheck(prereqs)) {
+  // Check and install prerequisites
+  const prereqs = await ensurePrerequisites();
+  if (!prereqs.allMet) {
     process.exit(1);
   }
 
@@ -246,9 +246,9 @@ async function initExistingProject(options: InitOptions): Promise<void> {
   console.log(pc.bold(`\nInitializing instar in: ${pc.cyan(projectDir)}`));
   console.log();
 
-  // Check prerequisites
-  const prereqs = checkPrerequisites();
-  if (!printPrerequisiteCheck(prereqs)) {
+  // Check and install prerequisites
+  const prereqs = await ensurePrerequisites();
+  if (!prereqs.allMet) {
     process.exit(1);
   }
 

package/src/commands/setup.ts

@@ -22,6 +22,7 @@ import pc from 'picocolors';
 import { input, confirm, select, number } from '@inquirer/prompts';
 import { Cron } from 'croner';
 import { detectTmuxPath, detectClaudePath, ensureStateDir } from '../core/Config.js';
+import { ensurePrerequisites } from '../core/Prerequisites.js';
 import { UserManager } from '../users/UserManager.js';
 import { validateJob } from '../scheduler/JobLoader.js';
 import type { AgentKitConfig, JobDefinition, UserProfile, UserChannel } from '../core/types.js';
@@ -36,13 +37,23 @@ export async function runSetup(opts?: { classic?: boolean }): Promise<void> {
     return runClassicSetup();
   }
 
-  // Check for Claude CLI
+  // Check and install prerequisites
+  console.log();
+  const prereqs = await ensurePrerequisites();
+
+  // Check for Claude CLI (may have been just installed)
   const claudePath = detectClaudePath();
   if (!claudePath) {
     console.log();
     console.log(pc.yellow('  Claude CLI not found — falling back to classic setup wizard.'));
     console.log(pc.dim('  Install Claude Code for the conversational experience:'));
-    console.log(pc.dim('  https://docs.anthropic.com/en/docs/claude-code'));
+    console.log(pc.dim('  npm install -g @anthropic-ai/claude-code'));
+    console.log();
+    return runClassicSetup();
+  }
+
+  if (!prereqs.allMet) {
+    console.log(pc.yellow('  Some prerequisites are still missing. Falling back to classic setup.'));
     console.log();
     return runClassicSetup();
   }
@@ -123,25 +134,16 @@ async function runClassicSetup(): Promise<void> {
   console.log(pc.dim('  Persistent agent infrastructure for any Claude Code project'));
   console.log();
 
-  // ── Step 0: Check prerequisites ──────────────────────────────────
-
-  const tmuxPath = detectTmuxPath();
-  const claudePath = detectClaudePath();
+  // ── Step 0: Check and install prerequisites ─────────────────────
 
-  if (!tmuxPath) {
-    console.log(pc.red('  tmux is required but not installed.'));
-    console.log('  Install: brew install tmux (macOS) or apt install tmux (Linux)');
+  const prereqs = await ensurePrerequisites();
+  if (!prereqs.allMet) {
     process.exit(1);
   }
-  console.log(`  ${pc.green('✓')} tmux found: ${pc.dim(tmuxPath)}`);
 
-  if (!claudePath) {
-    console.log(pc.red('  Claude CLI is required but not installed.'));
-    console.log('  Install: https://docs.anthropic.com/en/docs/claude-code');
-    process.exit(1);
-  }
-  console.log(`  ${pc.green('✓')} Claude CLI found: ${pc.dim(claudePath)}`);
-  console.log();
+  const tmuxPath = prereqs.results.find(r => r.name === 'tmux')!.path!;
+  // Use a scoped name to avoid shadowing the outer runSetup's claudePath
+  const claudePath = prereqs.results.find(r => r.name === 'Claude CLI')!.path!;
 
   // ── Step 1: Project ──────────────────────────────────────────────
 
@@ -349,6 +351,31 @@ async function runClassicSetup(): Promise<void> {
   console.log(`    ${pc.cyan('.instar/users.json')}   — user profiles`);
   console.log();
 
+  // Check if instar is globally installed (needed for server commands)
+  const isGloballyInstalled = isInstarGlobal();
+  if (!isGloballyInstalled) {
+    console.log(pc.dim('  Tip: instar is not installed globally. For persistent server'));
+    console.log(pc.dim('  commands (start, stop, status), install it globally:'));
+    console.log();
+
+    const installGlobal = await confirm({
+      message: 'Install instar globally? (npm install -g instar)',
+      default: true,
+    });
+
+    if (installGlobal) {
+      try {
+        console.log(pc.dim('  Running: npm install -g instar'));
+        execSync('npm install -g instar', { encoding: 'utf-8', stdio: 'inherit' });
+        console.log(`  ${pc.green('✓')} instar installed globally`);
+      } catch {
+        console.log(pc.yellow('  Could not install globally. You can run it later:'));
+        console.log(`    ${pc.cyan('npm install -g instar')}`);
+      }
+    }
+    console.log();
+  }
+
   // Offer to start server
   const startNow = await confirm({
     message: 'Start the agent server now?',
@@ -373,6 +400,22 @@ async function runClassicSetup(): Promise<void> {
   console.log();
 }
 
+/**
+ * Check if instar is installed globally (vs running via npx).
+ */
+function isInstarGlobal(): boolean {
+  try {
+    const result = execSync('which instar 2>/dev/null || where instar 2>/dev/null', {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    }).trim();
+    // npx creates a temp binary — check if it's a real global install
+    return !!result && !result.includes('.npm/_npx');
+  } catch {
+    return false;
+  }
+}
+
 // ── Prompt Helpers ───────────────────────────────────────────────
 
 /**

package/src/core/Prerequisites.ts

@@ -1,13 +1,14 @@
 /**
- * Prerequisite detection and installation guidance.
+ * Prerequisite detection and auto-installation.
  *
  * Checks for required software (tmux, Claude CLI, Node.js)
- * and provides clear installation instructions when something is missing.
+ * and offers to install missing dependencies automatically.
  */
 
 import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import pc from 'picocolors';
+import { confirm } from '@inquirer/prompts';
 import { detectTmuxPath, detectClaudePath } from './Config.js';
 
 export interface PrerequisiteResult {
@@ -16,6 +17,10 @@ export interface PrerequisiteResult {
   path?: string;
   version?: string;
   installHint: string;
+  /** Whether this prerequisite can be auto-installed. */
+  canAutoInstall: boolean;
+  /** The command to run to auto-install this prerequisite. */
+  installCommand?: string;
 }
 
 export interface PrerequisiteCheck {
@@ -87,28 +92,47 @@ function getNodeVersion(): { version: string; major: number } {
 }
 
 /**
- * Build install hint for tmux based on platform.
+ * Build install hint and command for tmux based on platform.
  */
-function tmuxInstallHint(): string {
+function tmuxInstallInfo(): { hint: string; canAutoInstall: boolean; command?: string } {
   const platform = detectPlatform();
   switch (platform) {
     case 'macos-arm':
     case 'macos-intel':
-      return hasHomebrew()
-        ? 'Install with: brew install tmux'
-        : 'Install Homebrew first (https://brew.sh), then: brew install tmux';
+      if (hasHomebrew()) {
+        return {
+          hint: 'Install with: brew install tmux',
+          canAutoInstall: true,
+          command: 'brew install tmux',
+        };
+      }
+      return {
+        hint: 'Install Homebrew first (https://brew.sh), then: brew install tmux',
+        canAutoInstall: false,
+      };
     case 'linux':
-      return 'Install with: sudo apt install tmux (Debian/Ubuntu) or sudo yum install tmux (RHEL/CentOS)';
+      return {
+        hint: 'Install with: sudo apt install tmux (Debian/Ubuntu) or sudo yum install tmux (RHEL/CentOS)',
+        canAutoInstall: true,
+        command: 'sudo apt install -y tmux',
+      };
     default:
-      return 'Install tmux: https://github.com/tmux/tmux/wiki/Installing';
+      return {
+        hint: 'Install tmux: https://github.com/tmux/tmux/wiki/Installing',
+        canAutoInstall: false,
+      };
   }
 }
 
 /**
- * Build install hint for Claude CLI based on platform.
+ * Build install hint and command for Claude CLI.
  */
-function claudeInstallHint(): string {
-  return 'Install Claude Code: npm install -g @anthropic-ai/claude-code\n  Docs: https://docs.anthropic.com/en/docs/claude-code';
+function claudeInstallInfo(): { hint: string; canAutoInstall: boolean; command: string } {
+  return {
+    hint: 'Install Claude Code: npm install -g @anthropic-ai/claude-code',
+    canAutoInstall: true,
+    command: 'npm install -g @anthropic-ai/claude-code',
+  };
 }
 
 /**
@@ -126,26 +150,33 @@ export function checkPrerequisites(): PrerequisiteCheck {
     installHint: node.major < 18
       ? `Node.js 18+ required (found ${node.version}). Update: https://nodejs.org`
       : '',
+    canAutoInstall: false,
   });
 
   // 2. tmux
   const tmuxPath = detectTmuxPath();
+  const tmuxInfo = tmuxInstallInfo();
   results.push({
     name: 'tmux',
     found: !!tmuxPath,
     path: tmuxPath || undefined,
     version: tmuxPath ? getTmuxVersion(tmuxPath) : undefined,
-    installHint: tmuxInstallHint(),
+    installHint: tmuxInfo.hint,
+    canAutoInstall: tmuxInfo.canAutoInstall,
+    installCommand: tmuxInfo.command,
   });
 
   // 3. Claude CLI
   const claudePath = detectClaudePath();
+  const claudeInfo = claudeInstallInfo();
   results.push({
     name: 'Claude CLI',
     found: !!claudePath,
     path: claudePath || undefined,
     version: claudePath ? getClaudeVersion(claudePath) : undefined,
-    installHint: claudeInstallHint(),
+    installHint: claudeInfo.hint,
+    canAutoInstall: claudeInfo.canAutoInstall,
+    installCommand: claudeInfo.command,
   });
 
   const missing = results.filter(r => !r.found);
@@ -157,6 +188,26 @@ export function checkPrerequisites(): PrerequisiteCheck {
   };
 }
 
+/**
+ * Attempt to install a missing prerequisite.
+ * Returns true if installation succeeded.
+ */
+function installPrerequisite(result: PrerequisiteResult): boolean {
+  if (!result.installCommand) return false;
+
+  try {
+    console.log(pc.dim(`  Running: ${result.installCommand}`));
+    execSync(result.installCommand, {
+      encoding: 'utf-8',
+      stdio: 'inherit',
+      timeout: 120000, // 2 min timeout
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Print prerequisite check results to console.
  * Returns true if all prerequisites are met.
@@ -185,3 +236,67 @@ export function printPrerequisiteCheck(check: PrerequisiteCheck): boolean {
 
   return check.allMet;
 }
+
+/**
+ * Interactive prerequisite check that offers to install missing dependencies.
+ * Returns a fresh PrerequisiteCheck after any installations.
+ */
+export async function ensurePrerequisites(): Promise<PrerequisiteCheck> {
+  let check = checkPrerequisites();
+
+  console.log(pc.bold('  Checking prerequisites...'));
+  console.log();
+
+  for (const result of check.results) {
+    if (result.found) {
+      const versionStr = result.version ? ` (${result.version})` : '';
+      const pathStr = result.path ? pc.dim(` ${result.path}`) : '';
+      console.log(`  ${pc.green('✓')} ${result.name}${versionStr}${pathStr}`);
+    }
+  }
+
+  if (check.allMet) {
+    console.log();
+    return check;
+  }
+
+  // Handle missing prerequisites
+  for (const missing of check.missing) {
+    console.log();
+    console.log(`  ${pc.red('✗')} ${missing.name} — not found`);
+
+    if (missing.canAutoInstall && missing.installCommand) {
+      const install = await confirm({
+        message: `Install ${missing.name}? (${pc.dim(missing.installCommand)})`,
+        default: true,
+      });
+
+      if (install) {
+        const success = installPrerequisite(missing);
+        if (success) {
+          console.log(`  ${pc.green('✓')} ${missing.name} installed successfully`);
+        } else {
+          console.log(`  ${pc.red('✗')} Failed to install ${missing.name}`);
+          console.log(`    Try manually: ${missing.installHint}`);
+        }
+      } else {
+        console.log(`    ${missing.installHint}`);
+      }
+    } else {
+      console.log(`    ${missing.installHint}`);
+    }
+  }
+
+  // Re-check after installations
+  check = checkPrerequisites();
+  console.log();
+
+  if (!check.allMet) {
+    const stillMissing = check.missing.map(r => r.name).join(', ');
+    console.log(pc.red(`  Still missing: ${stillMissing}`));
+    console.log(pc.dim('  Install the missing prerequisites and run instar again.'));
+    console.log();
+  }
+
+  return check;
+}

package/src/core/SessionManager.ts

@@ -92,9 +92,8 @@ export class SessionManager extends EventEmitter {
     claudeArgs.push('-p', options.prompt);
 
     // Create tmux session and run claude
-    // Unset ANTHROPIC_* env vars so Claude uses OAuth (subscription) not API key
-    const cleanEnv = 'unset ANTHROPIC_API_KEY ANTHROPIC_ADMIN_KEY CLAUDECODE;';
-    const claudeCmd = `${cleanEnv} ${this.config.claudePath} ${claudeArgs.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`;
+    // Respect the user's configured auth method (API key or OAuth subscription)
+    const claudeCmd = `${this.config.claudePath} ${claudeArgs.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`;
     const tmuxCmd = [
       this.config.tmuxPath,
       'new-session',
@@ -269,9 +268,9 @@ export class SessionManager extends EventEmitter {
       return tmuxSession;
     }
 
-    // Unset ANTHROPIC_* env vars so Claude uses OAuth (subscription) not API key
+    // Respect the user's configured auth method (API key or OAuth subscription)
     const claudeCmd = `${this.config.claudePath} --dangerously-skip-permissions`;
-    const shellCmd = `cd '${this.config.projectDir}' && unset ANTHROPIC_API_KEY ANTHROPIC_ADMIN_KEY CLAUDECODE && ${claudeCmd}`;
+    const shellCmd = `cd '${this.config.projectDir}' && ${claudeCmd}`;
     const tmuxCmd = `${this.config.tmuxPath} new-session -d -s '${tmuxSession}' -x 200 -y 50 'bash -c "${shellCmd.replace(/"/g, '\\"')}"'`;
 
     try {