feat: print mode by default with $interactive and .i. filename support

johnlindquist · johnlindquist · commit 660a8fb22daf · 2025-12-08T14:02:02.000-07:00
- All CLI tools now default to print/non-interactive mode
- Add $interactive frontmatter field to enable interactive mode
- Add .i. filename marker (e.g., task.i.claude.md) for interactive mode
- Per-command behavior:
  - claude: --print (default) vs no flag (interactive)
  - copilot: --prompt (default) vs --interactive
  - codex: exec subcommand (default) vs no subcommand (interactive)
  - gemini: one-shot (default) vs --prompt-interactive
- Update README and CLAUDE.md with new documentation
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -41,24 +41,26 @@ bun run ma task.claude.md
 ```
 .md file → parseFrontmatter() → resolveCommand(filename/env)
         → loadGlobalConfig() → applyDefaults()
-        → expandImports() → substituteTemplateVars()
-        → buildArgs() → runCommand()
+        → applyInteractiveMode() → expandImports()
+        → substituteTemplateVars() → buildArgs() → runCommand()
 ```
 
 ### Key Modules
 
 - **`command.ts`** - Command resolution and execution
   - `parseCommandFromFilename()`: Infers command from `task.claude.md` → `claude`
+  - `hasInteractiveMarker()`: Detects `.i.` in filename (e.g., `task.i.claude.md`)
   - `resolveCommand()`: Priority: MA_COMMAND env var > filename
   - `buildArgs()`: Converts frontmatter to CLI flags
   - `extractPositionalMappings()`: Extracts $1, $2, etc. mappings
   - `runCommand()`: Spawns the command with positional args
 
 - **`config.ts`** - Global configuration
   - Loads defaults from `~/.markdown-agent/config.yaml`
-  - Built-in defaults: copilot maps $1 → prompt
+  - Built-in defaults: All commands default to print mode
   - `getCommandDefaults()`: Get defaults for a command
   - `applyDefaults()`: Merge defaults with frontmatter
+  - `applyInteractiveMode()`: Converts print defaults to interactive mode per command
 
 - **`types.ts`** - Core TypeScript interfaces
   - `AgentFrontmatter`: Simple interface with system keys + passthrough
@@ -92,6 +94,8 @@ Commands are resolved in priority order:
 - `args`: Named positional arguments for template vars
 - `env` (object form): Sets process.env before execution
 - `$1`, `$2`, etc.: Map positional args to flags
+- `$interactive`: Enable interactive mode (overrides print-mode defaults)
+- `$exec`: Used internally for codex exec subcommand
 
 **All other keys** are passed directly as CLI flags:
 
@@ -117,14 +121,27 @@ $1: prompt    # Body passed as --prompt <body> instead of positional
 ---
 ```
 
+### Print vs Interactive Mode
+
+All commands default to **print mode** (non-interactive). Use `.i.` filename marker or `$interactive: true` for interactive mode.
+
+```bash
+task.claude.md      # Print mode: claude --print "..."
+task.i.claude.md    # Interactive: claude "..."
+task.copilot.md     # Print mode: copilot --silent --prompt "..."
+task.i.copilot.md   # Interactive: copilot --silent --interactive "..."
+task.codex.md       # Print mode: codex exec "..."
+task.i.codex.md     # Interactive: codex "..."
+task.gemini.md      # Print mode: gemini "..." (one-shot)
+task.i.gemini.md    # Interactive: gemini --prompt-interactive "..."
+```
+
 ### Global Config (`~/.markdown-agent/config.yaml`)
 
 Set default frontmatter per command:
 
 ```yaml
 commands:
-  copilot:
-    $1: prompt    # Always map body to --prompt for copilot
   claude:
     model: sonnet # Default model for claude
 ```
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ Name your file `task.COMMAND.md` and the command is inferred:
 task.claude.md    # Runs claude
 task.gemini.md    # Runs gemini
 task.codex.md     # Runs codex
-task.copilot.md   # Runs copilot (body auto-mapped to --prompt)
+task.copilot.md   # Runs copilot (print mode by default)
 ```
 
 ### 2. Frontmatter → CLI Flags
@@ -195,19 +195,55 @@ p: true                               # → -p (single char = short flag)
 
 ---
 
+## Print vs Interactive Mode
+
+All commands run in **print mode by default** (non-interactive, exit after completion). Use the `.i.` filename marker or `$interactive: true` to enable interactive mode.
+
+### Print Mode (Default)
+
+```bash
+task.claude.md      # Runs: claude --print "..."
+task.copilot.md     # Runs: copilot --silent --prompt "..."
+task.codex.md       # Runs: codex exec "..."
+task.gemini.md      # Runs: gemini "..." (one-shot)
+```
+
+### Interactive Mode
+
+Add `.i.` before the command name in the filename:
+
+```bash
+task.i.claude.md    # Runs: claude "..." (interactive session)
+task.i.copilot.md   # Runs: copilot --silent --interactive "..."
+task.i.codex.md     # Runs: codex "..." (interactive session)
+task.i.gemini.md    # Runs: gemini --prompt-interactive "..."
+```
+
+Or use `$interactive: true` in frontmatter:
+
+```yaml
+---
+$interactive: true
+model: opus
+---
+Review this code with me interactively.
+```
+
+---
+
 ## Global Configuration
 
 Set default frontmatter per command in `~/.markdown-agent/config.yaml`:
 
 ```yaml
 commands:
-  copilot:
-    $1: prompt    # Always map body to --prompt for copilot
   claude:
     model: sonnet # Default model for claude
+  copilot:
+    silent: true  # Always use --silent for copilot
 ```
 
-**Built-in defaults:** Copilot automatically maps `$1: prompt` so you can use it without any frontmatter.
+**Built-in defaults:** All commands default to print mode with appropriate flags per CLI tool.
 
 ---
 
@@ -255,7 +291,16 @@ Analyze this codebase and suggest improvements.
 Explain this code.
 ```
 
-Thanks to the global config, this runs: `copilot --prompt "Explain this code."`
+This runs: `copilot --silent --prompt "Explain this code."` (print mode)
+
+For interactive mode, use `.i.` in the filename:
+
+```markdown
+# task.i.copilot.md
+Explain this code.
+```
+
+This runs: `copilot --silent --interactive "Explain this code."`
 
 ### Template Variables with Args
 
diff --git a/src/command.ts b/src/command.ts
@@ -59,14 +59,26 @@ function isPositionalKey(key: string): boolean {
  * Extract command from filename
  * e.g., "commit.claude.md" → "claude"
  * e.g., "task.gemini.md" → "gemini"
+ * e.g., "fix.i.claude.md" → "claude" (with interactive mode)
  */
 export function parseCommandFromFilename(filePath: string): string | undefined {
   const name = basename(filePath);
-  // Match pattern: name.command.md
+  // Match pattern: name.command.md or name.i.command.md
   const match = name.match(/\.([^.]+)\.md$/i);
   return match?.[1];
 }
 
+/**
+ * Check if filename has .i. marker for interactive mode
+ * e.g., "fix.i.claude.md" → true
+ * e.g., "fix.claude.md" → false
+ */
+export function hasInteractiveMarker(filePath: string): boolean {
+  const name = basename(filePath);
+  // Match pattern: name.i.command.md
+  return /\.i\.[^.]+\.md$/i.test(name);
+}
+
 /**
  * Resolve command from filename pattern
  * Note: --command flag is handled in index.ts before this is called
diff --git a/src/config.test.ts b/src/config.test.ts
@@ -22,13 +22,15 @@ describe("config", () => {
     const config = await loadGlobalConfig();
     expect(config.commands).toBeDefined();
     expect(config.commands?.copilot).toBeDefined();
-    expect(config.commands?.copilot.$1).toBe("interactive");
+    expect(config.commands?.copilot.$1).toBe("prompt");  // Print mode by default
+    expect(config.commands?.claude?.print).toBe(true);   // Print mode by default
+    expect(config.commands?.codex?.$exec).toBe(true);    // Exec mode by default
   });
 
   test("getCommandDefaults returns defaults for copilot", async () => {
     const defaults = await getCommandDefaults("copilot");
     expect(defaults).toBeDefined();
-    expect(defaults?.$1).toBe("interactive");
+    expect(defaults?.$1).toBe("prompt");  // Print mode by default
   });
 
   test("getCommandDefaults returns undefined for unknown command", async () => {
@@ -184,7 +186,7 @@ describe("loadFullConfig", () => {
 
   test("includes built-in defaults when no project config", async () => {
     const config = await loadFullConfig(testDir);
-    expect(config.commands?.copilot?.$1).toBe("interactive");
+    expect(config.commands?.copilot?.$1).toBe("prompt");  // Print mode by default
   });
 
   test("project config overrides global config", async () => {
@@ -212,7 +214,7 @@ describe("loadFullConfig", () => {
 
     const config = await loadFullConfig(testDir);
     // Built-in defaults preserved
-    expect(config.commands?.copilot?.$1).toBe("interactive");
+    expect(config.commands?.copilot?.$1).toBe("prompt");  // Print mode by default
     // New command added
     expect(config.commands?.["my-tool"]?.$1).toBe("body");
     expect(config.commands?.["my-tool"]?.verbose).toBe(true);
@@ -229,7 +231,7 @@ describe("loadFullConfig", () => {
 
     const config = await loadFullConfig(testDir);
     // Built-in default preserved
-    expect(config.commands?.copilot?.$1).toBe("interactive");
+    expect(config.commands?.copilot?.$1).toBe("prompt");  // Print mode by default
     // New setting added
     expect(config.commands?.copilot?.verbose).toBe(true);
   });
diff --git a/src/config.ts b/src/config.ts
@@ -25,16 +25,77 @@ const PROJECT_CONFIG_NAMES = ["ma.config.yaml", ".markdown-agent.yaml", ".markdo
 
 /**
  * Built-in defaults (used when no config file exists)
+ * All tools default to PRINT mode (non-interactive)
  */
 export const BUILTIN_DEFAULTS: GlobalConfig = {
   commands: {
     copilot: {
-      $1: "interactive",  // Map body to --interactive for copilot
+      $1: "prompt",       // Map body to --prompt for copilot (print mode)
       silent: true,       // Output only the agent response (no stats)
     },
+    claude: {
+      print: true,        // --print flag for non-interactive mode
+    },
+    codex: {
+      $exec: true,        // Use 'exec' subcommand for non-interactive mode
+    },
+    // gemini defaults to one-shot mode (no special flags needed)
   },
 };
 
+/**
+ * Apply $interactive mode transformations to frontmatter
+ * Converts print defaults to interactive mode per command
+ *
+ * @param frontmatter - The frontmatter after defaults are applied
+ * @param command - The resolved command name
+ * @param interactiveFromFilename - Whether .i. was detected in filename
+ * @returns Transformed frontmatter for interactive mode
+ */
+export function applyInteractiveMode(
+  frontmatter: AgentFrontmatter,
+  command: string,
+  interactiveFromFilename: boolean = false
+): AgentFrontmatter {
+  // Check if $interactive is enabled (truthy, empty string, or from filename)
+  const interactiveMode = frontmatter.$interactive ?? interactiveFromFilename;
+  if (!interactiveMode && interactiveMode !== "") {
+    return frontmatter;
+  }
+
+  // Remove $interactive from output (it's a meta-key, not a CLI flag)
+  const result = { ...frontmatter };
+  delete result.$interactive;
+
+  switch (command) {
+    case "copilot":
+      // copilot: Change from --prompt to --interactive
+      result.$1 = "interactive";
+      break;
+
+    case "claude":
+      // claude: Remove --print flag (interactive is default without it)
+      delete result.print;
+      break;
+
+    case "codex":
+      // codex: Remove $exec marker (interactive is default without exec subcommand)
+      delete result.$exec;
+      break;
+
+    case "gemini":
+      // gemini: Add --prompt-interactive flag
+      result.$1 = "prompt-interactive";
+      break;
+
+    default:
+      // Unknown command - just remove $interactive, no other changes
+      break;
+  }
+
+  return result;
+}
+
 let cachedGlobalConfig: GlobalConfig | null = null;
 let cachedProjectConfig: { cwd: string; config: GlobalConfig } | null = null;
 
diff --git a/src/context.test.ts b/src/context.test.ts
@@ -311,7 +311,7 @@ After import`;
 
     expect(config.commands?.claude?.model).toBe("project-model");
     // Built-in default for copilot should still be there
-    expect(config.commands?.copilot?.$1).toBe("interactive");
+    expect(config.commands?.copilot?.$1).toBe("prompt");  // Print mode by default
   });
 
   it("getCommandDefaultsFromConfig is pure function", () => {
diff --git a/src/index.ts b/src/index.ts
@@ -3,10 +3,10 @@ import { parseFrontmatter } from "./parse";
 import { parseCliArgs, handleMaCommands } from "./cli";
 import { substituteTemplateVars, extractTemplateVars } from "./template";
 import { isRemoteUrl, fetchRemote, cleanupRemote } from "./remote";
-import { resolveCommand, buildArgs, runCommand, extractPositionalMappings, extractEnvVars, killCurrentChildProcess } from "./command";
+import { resolveCommand, buildArgs, runCommand, extractPositionalMappings, extractEnvVars, killCurrentChildProcess, hasInteractiveMarker } from "./command";
 import { expandImports, hasImports } from "./imports";
 import { loadEnvFiles } from "./env";
-import { loadGlobalConfig, getCommandDefaults, applyDefaults } from "./config";
+import { loadGlobalConfig, getCommandDefaults, applyDefaults, applyInteractiveMode } from "./config";
 import { initLogger, getParseLogger, getTemplateLogger, getCommandLogger, getImportLogger, getCurrentLogPath } from "./logger";
 import { isDomainTrusted, promptForTrust, addTrustedDomain, extractDomain } from "./trust";
 import { dirname, resolve } from "path";
@@ -236,7 +236,13 @@ async function main() {
     // Load global config and apply command defaults
     await loadGlobalConfig();
     const commandDefaults = await getCommandDefaults(command);
-    const frontmatter = applyDefaults(baseFrontmatter, commandDefaults);
+    let frontmatter = applyDefaults(baseFrontmatter, commandDefaults);
+
+    // Check for .i. interactive marker in filename
+    const interactiveFromFilename = hasInteractiveMarker(localFilePath);
+
+    // Apply $interactive mode transformations (converts print defaults to interactive mode per command)
+    frontmatter = applyInteractiveMode(frontmatter, command, interactiveFromFilename);
 
     // Extract and apply environment variables (object form) to process.env
     // This must happen BEFORE import expansion so !`command` inlines can use them
@@ -377,21 +383,27 @@ async function main() {
       console.log("═══════════════════════════════════════════════════════════\n");
 
       // Build final args with positional mappings applied (same as runCommand)
-      const finalArgs = [...args];
+      let dryRunArgs = [...args];
+
+      // Handle codex $exec: prepend 'exec' to args
+      if (frontmatter.$exec && command === "codex") {
+        dryRunArgs = ["exec", ...dryRunArgs];
+      }
+
       for (let i = 0; i < positionals.length; i++) {
         const pos = i + 1;
         const value = positionals[i];
         if (positionalMappings.has(pos)) {
           const flagName = positionalMappings.get(pos)!;
           const flag = flagName.length === 1 ? `-${flagName}` : `--${flagName}`;
-          finalArgs.push(flag, `"${value.replace(/"/g, '\\"')}"`);
+          dryRunArgs.push(flag, `"${value.replace(/"/g, '\\"')}"`);
         } else {
-          finalArgs.push(`"${value.replace(/"/g, '\\"')}"`);
+          dryRunArgs.push(`"${value.replace(/"/g, '\\"')}"`);
         }
       }
 
       console.log("Command:");
-      console.log(`   ${command} ${finalArgs.join(" ")}\n`);
+      console.log(`   ${command} ${dryRunArgs.join(" ")}\n`);
 
       console.log("Final Prompt:");
       console.log("───────────────────────────────────────────────────────────");
@@ -443,11 +455,18 @@ async function main() {
       }
     }
 
-    getCommandLogger().info({ command, argsCount: args.length, promptLength: finalBody.length }, "Executing command");
+    // Handle codex $exec: prepend 'exec' to args (codex exec is the non-interactive subcommand)
+    let finalCommand = command;
+    let finalRunArgs = args;
+    if (frontmatter.$exec && command === "codex") {
+      finalRunArgs = ["exec", ...args];
+    }
+
+    getCommandLogger().info({ command: finalCommand, argsCount: finalRunArgs.length, promptLength: finalBody.length }, "Executing command");
 
     const runResult = await runCommand({
-      command,
-      args,
+      command: finalCommand,
+      args: finalRunArgs,
       positionals,
       positionalMappings,
       captureOutput: false,
