@tsuzuku/arise 1.0.0 → 1.0.1

package/README.md

@@ -38,8 +38,12 @@ arise --branch feature/login
 # Explicitly specify a preset
 arise --branch feature/login --preset laravel
 
-# Specify base branch or custom workspace name
-arise --branch feature/login --source develop --focus agy
+# Choose your AI CLI agent (e.g. Claude Code, Aider, Antigravity, or Copilot)
+arise --branch feature/login --agent claude
+arise --branch feature/login -a aider
+
+# Specify base branch, custom workspace name, or focus pane
+arise --branch feature/login --source develop --focus claude
 ```
 
 ### 2. Nuke / Clean Up a Worktree
@@ -82,7 +86,8 @@ Place a `.ariserc.json` in your repository root, worktrees base directory, or `~
   },
   "workspace": {
     "labelPrefix": "[API] ",
-    "defaultFocus": "agy"
+    "agent": "claude",
+    "defaultFocus": "claude"
   },
   "scaffold": {
     "envSource": "/path/to/shared/.env",

package/arise.schema.json

@@ -34,15 +34,29 @@
     },
     "workspace": {
       "type": "object",
-      "description": "Herdr workspace naming and focus configuration",
+      "description": "Herdr workspace naming, agent, and focus configuration",
       "properties": {
         "labelPrefix": {
           "type": "string",
           "description": "Prefix added to Herdr workspace labels (e.g. '[BE] ')"
         },
+        "agent": {
+          "type": ["string", "object", "null"],
+          "description": "CLI AI agent to run in the workspace pane ('agy', 'claude', 'aider', 'copilot', 'none', or custom command object)",
+          "properties": {
+            "cmd": {
+              "type": ["string", "null"],
+              "description": "Command to execute the agent"
+            },
+            "title": {
+              "type": "string",
+              "description": "Display title for the agent pane in Herdr"
+            }
+          }
+        },
         "defaultFocus": {
           "type": "string",
-          "description": "Default pane to focus upon creation ('agy', 'vim', 'logs', 'server', 'shell')"
+          "description": "Default pane to focus upon creation ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell')"
         }
       },
       "additionalProperties": false
@@ -83,6 +97,10 @@
           "focus": {
             "type": "boolean",
             "description": "Whether this pane should receive focus by default"
+          },
+          "isAgent": {
+            "type": "boolean",
+            "description": "Whether this pane is designated as the AI CLI agent pane"
           }
         },
         "additionalProperties": false

package/lib/cli.js

@@ -15,7 +15,8 @@ Creation Arguments:
   --workspace, -w <name>      (Optional) Custom Herdr workspace name.
   --source, -s, --base <src>  (Optional) Base branch if creating a new branch. Defaults to preset default (e.g. 'develop' / 'prod').
   --preset, -p <preset>       (Optional) Project preset ('node', 'laravel', 'generic', or custom). Auto-detected if omitted.
-  --focus, -f <pane>          (Optional) Pane to focus ('agy', 'vim', 'logs', 'server', 'shell'). Defaults to 'agy'.
+  --agent, -a <agent>         (Optional) AI CLI agent to run in workspace ('agy', 'claude', 'aider', 'copilot', etc.).
+  --focus, -f <pane>          (Optional) Pane to focus ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell'). Defaults to active agent or 'agy'.
 
 Nuke / Cleanup Arguments:
   --nuke, -n [<target>]       Nuke the worktree: closes Herdr workspace, removes worktree directory,
@@ -49,6 +50,7 @@ function parseArgs(argv = process.argv.slice(2)) {
     workspaceName: null,
     source: null,
     presetName: null,
+    agent: null,
     focusTarget: null,
     installSkill: false,
     skillScope: 'global',
@@ -97,6 +99,11 @@ function parseArgs(argv = process.argv.slice(2)) {
     } else if (arg === '--preset' || arg === '-p') {
       flags.presetName = argv[i + 1];
       i++;
+    } else if (arg === '--agent' || arg === '-a') {
+      flags.agent = argv[i + 1];
+      i++;
+    } else if (arg.startsWith('--agent=')) {
+      flags.agent = arg.slice(8);
     } else if (arg === '--focus') {
       flags.focusTarget = argv[i + 1];
       i++;

package/lib/config.js

@@ -91,18 +91,56 @@ function resolveConfiguration(flags = {}, cwd = process.cwd()) {
     protectedBranches: (fileConfig.repo && fileConfig.repo.protectedBranches) || (preset.repo && preset.repo.protectedBranches) || ['main', 'master', 'develop', 'prod', 'staging'],
   };
 
-  // 3. Merge Workspace Settings
+  // 3. Resolve AI CLI Agent
+  const resolvedAgent = flags.agent
+    || process.env.ARISE_AGENT
+    || (fileConfig.workspace && fileConfig.workspace.agent)
+    || (preset.workspace && preset.workspace.agent)
+    || 'agy';
+
+  // 4. Merge Workspace Settings
+  const defaultFocus = (fileConfig.workspace && fileConfig.workspace.defaultFocus)
+    || (preset.workspace && preset.workspace.defaultFocus)
+    || 'agy';
+
   const workspaceConfig = {
     labelPrefix: (fileConfig.workspace && fileConfig.workspace.labelPrefix !== undefined)
       ? fileConfig.workspace.labelPrefix
       : (preset.workspace && preset.workspace.labelPrefix !== undefined ? preset.workspace.labelPrefix : ''),
-    defaultFocus: (fileConfig.workspace && fileConfig.workspace.defaultFocus)
-      || (preset.workspace && preset.workspace.defaultFocus)
-      || 'agy',
+    agent: resolvedAgent,
+    defaultFocus,
   };
 
-  // 4. Merge Layout
-  const layout = fileConfig.layout || preset.layout || [];
+  // 5. Merge & Customize Layout for Active Agent
+  const baseLayout = fileConfig.layout || preset.layout || [];
+  const layout = baseLayout.map((pane) => {
+    const isAgentPane = pane.isAgent || pane.id === 'agy' || pane.id === 'agent' || pane.id === 'ai';
+    if (!isAgentPane) return { ...pane };
+
+    let agentCmd = pane.cmd;
+    let agentTitle = pane.title;
+
+    if (typeof resolvedAgent === 'string') {
+      const lower = resolvedAgent.toLowerCase().trim();
+      if (lower === 'none' || lower === 'false' || lower === 'null' || lower === 'disabled') {
+        agentCmd = null;
+        agentTitle = 'shell';
+      } else {
+        agentCmd = resolvedAgent;
+        agentTitle = resolvedAgent;
+      }
+    } else if (typeof resolvedAgent === 'object' && resolvedAgent !== null) {
+      agentCmd = resolvedAgent.cmd !== undefined ? resolvedAgent.cmd : (resolvedAgent.command || null);
+      agentTitle = resolvedAgent.title || resolvedAgent.cmd || pane.title;
+    }
+
+    return {
+      ...pane,
+      cmd: agentCmd,
+      title: agentTitle,
+      isAgent: true,
+    };
+  });
 
   // 5. Merge Scaffolding Settings
   const scaffoldConfig = {

package/lib/git.js

@@ -72,17 +72,47 @@ function getWorktrees(options = {}) {
   }
 }
 
+function fetchOrigin(options = {}) {
+  const gitCmd = getGitPrefix(options);
+  try {
+    const remotes = execSync(`${gitCmd} remote`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().split(/\s+/);
+    if (!remotes.includes('origin')) return;
+
+    // In bare repos, remote.origin.fetch is often not set by default.
+    // Setting or fetching with the standard refspec ensures refs/remotes/origin/* are populated.
+    try {
+      const fetchRefspec = execSync(`${gitCmd} config --get remote.origin.fetch`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      if (!fetchRefspec) {
+        execSync(`${gitCmd} config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"`, { stdio: 'ignore' });
+      }
+    } catch (e) {
+      try {
+        execSync(`${gitCmd} config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"`, { stdio: 'ignore' });
+      } catch (err) {}
+    }
+
+    execSync(`${gitCmd} fetch origin`, { stdio: 'inherit' });
+  } catch (e) {
+    // Network or remote fetch error - continue gracefully with local refs
+  }
+}
+
 function branchExistsLocally(branch, options = {}) {
   const gitCmd = getGitPrefix(options);
   try {
-    execSync(`${gitCmd} rev-parse --verify "${branch}"`, { stdio: 'ignore' });
+    execSync(`${gitCmd} rev-parse --verify "refs/heads/${branch}"`, { stdio: 'ignore' });
     return true;
   } catch (e) {
     try {
-      const list = execSync(`${gitCmd} branch --list "${branch}"`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-      return list !== '';
+      execSync(`${gitCmd} rev-parse --verify "${branch}"`, { stdio: 'ignore' });
+      return true;
     } catch (err) {
-      return false;
+      try {
+        const list = execSync(`${gitCmd} branch --list "${branch}"`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return list !== '';
+      } catch (err2) {
+        return false;
+      }
     }
   }
 }
@@ -90,16 +120,21 @@ function branchExistsLocally(branch, options = {}) {
 function branchExistsRemotely(branch, options = {}) {
   const gitCmd = getGitPrefix(options);
   try {
-    execSync(`${gitCmd} rev-parse --verify "origin/${branch}"`, { stdio: 'ignore' });
+    execSync(`${gitCmd} rev-parse --verify "refs/remotes/origin/${branch}"`, { stdio: 'ignore' });
     return true;
   } catch (e) {
     try {
-      const remoteList = execSync(`${gitCmd} branch -r --list "origin/${branch}"`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-      if (remoteList) return true;
-      const lsRemote = execSync(`${gitCmd} ls-remote --heads origin "${branch}"`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-      return Boolean(lsRemote);
+      execSync(`${gitCmd} rev-parse --verify "origin/${branch}"`, { stdio: 'ignore' });
+      return true;
     } catch (err) {
-      return false;
+      try {
+        const remoteList = execSync(`${gitCmd} branch -r --list "origin/${branch}"`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (remoteList) return true;
+        const lsRemote = execSync(`${gitCmd} ls-remote --heads origin "${branch}"`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return Boolean(lsRemote);
+      } catch (err2) {
+        return false;
+      }
     }
   }
 }
@@ -108,6 +143,9 @@ function createWorktree({ worktreePath, branch, source = 'develop', repoDir, bar
   const options = { repoDir, bareRepo };
   const gitCmd = getGitPrefix(options);
 
+  console.log('Fetching latest from origin...');
+  fetchOrigin(options);
+
   const localExists = branchExistsLocally(branch, options);
   const remoteExists = branchExistsRemotely(branch, options);
 
@@ -116,16 +154,32 @@ function createWorktree({ worktreePath, branch, source = 'develop', repoDir, bar
     execSync(`${gitCmd} worktree add "${worktreePath}" "${branch}"`, { stdio: 'inherit' });
   } else if (remoteExists) {
     console.log(`Branch "${branch}" exists on remote. Checking out and adding worktree...`);
-    execSync(`${gitCmd} worktree add "${worktreePath}" -b "${branch}" "origin/${branch}"`, { stdio: 'inherit' });
+    let startPoint = `origin/${branch}`;
+    try {
+      execSync(`${gitCmd} rev-parse --verify "${startPoint}"`, { stdio: 'ignore' });
+    } catch (e) {
+      startPoint = branch;
+    }
+    if (bareRepo) {
+      execSync(`${gitCmd} branch --track "${branch}" "${startPoint}"`, { stdio: 'inherit' });
+      execSync(`${gitCmd} worktree add "${worktreePath}" "${branch}"`, { stdio: 'inherit' });
+    } else {
+      execSync(`${gitCmd} worktree add "${worktreePath}" -b "${branch}" "${startPoint}"`, { stdio: 'inherit' });
+    }
   } else {
     // Creating a brand new branch off source
-    console.log('Fetching latest from origin...');
+    let startPoint = null;
     try {
-      execSync(`${gitCmd} fetch origin`, { stdio: 'inherit' });
-    } catch (e) {}
-
-    const remoteSourceExists = branchExistsRemotely(source, options);
-    const startPoint = remoteSourceExists ? `origin/${source}` : source;
+      execSync(`${gitCmd} rev-parse --verify "origin/${source}"`, { stdio: 'ignore' });
+      startPoint = `origin/${source}`;
+    } catch (e) {
+      try {
+        execSync(`${gitCmd} rev-parse --verify "${source}"`, { stdio: 'ignore' });
+        startPoint = source;
+      } catch (err) {
+        throw new Error(`Cannot create branch "${branch}" off "${source}": Base branch or ref "${source}" does not exist locally or on remote.`);
+      }
+    }
 
     console.log(`Creating branch "${branch}" off "${startPoint}" and adding worktree...`);
     if (bareRepo) {
@@ -156,7 +210,7 @@ function syncPrimaryBranch({ branch, worktreePath, repoDir, bareRepo, protectedB
       console.warn(`==> Please commit, stash, or discard your changes if you want to sync with origin.`);
     } else {
       console.log(`==> Syncing ${branch} with origin/${branch}...`);
-      execSync(`${gitCmd} fetch origin ${branch}`, { stdio: 'inherit' });
+      fetchOrigin(options);
       const resetCmd = bareRepo
         ? `${gitCmd} --work-tree="${worktreePath}" reset --hard origin/${branch}`
         : `git -C "${worktreePath}" reset --hard origin/${branch}`;
@@ -215,6 +269,7 @@ module.exports = {
   getGitPrefix,
   getRepoRootDir,
   getWorktrees,
+  fetchOrigin,
   branchExistsLocally,
   branchExistsRemotely,
   createWorktree,

package/lib/layout.js

@@ -7,7 +7,7 @@ const DEFAULT_QUADRANT_LAYOUT = [
   { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
   { id: 'server', title: 'server', cmd: null, split: 'right', from: 'vim' },
   { id: 'shell', title: 'shell', cmd: null, split: 'down', from: 'vim' },
-  { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'server', focus: true },
+  { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'server', focus: true, isAgent: true },
 ];
 
 /**
@@ -17,7 +17,7 @@ const DEFAULT_QUADRANT_LAYOUT = [
  * @param {Array} options.layout Array of pane definitions
  * @param {string} options.rootPaneId ID of the root pane created with workspace
  * @param {string} options.cwd Working directory for panes
- * @param {string} options.focusTarget Name or ID of pane to focus (e.g. 'agy', 'vim', 'logs', 'shell')
+ * @param {string} options.focusTarget Name or ID of pane to focus (e.g. 'agent', 'agy', 'claude', 'vim', 'logs', 'shell')
  */
 function renderLayout({ layout = DEFAULT_QUADRANT_LAYOUT, rootPaneId, cwd, focusTarget = 'agy' }) {
   const paneMap = new Map(); // id -> paneId
@@ -31,7 +31,10 @@ function renderLayout({ layout = DEFAULT_QUADRANT_LAYOUT, rootPaneId, cwd, focus
     if (!normalizedFocus) return false;
     const idMatch = paneDef.id && paneDef.id.toLowerCase() === normalizedFocus;
     const titleMatch = paneDef.title && paneDef.title.toLowerCase() === normalizedFocus;
-    return idMatch || titleMatch;
+    const cmdMatch = paneDef.cmd && paneDef.cmd.toLowerCase().split(/\s+/)[0] === normalizedFocus;
+    const agentAlias = (normalizedFocus === 'agent' || normalizedFocus === 'agy' || normalizedFocus === 'ai') &&
+      (paneDef.id === 'agy' || paneDef.id === 'agent' || paneDef.isAgent);
+    return Boolean(idMatch || titleMatch || cmdMatch || agentAlias);
   }
 
   // 2. Iterate through pane definitions

package/lib/lifecycle/nuke.js

@@ -108,19 +108,7 @@ async function executeNuke(flags, config, cwd = process.cwd()) {
     await config.hooks.onPreNuke(ctx);
   }
 
-  // 1. Close Herdr Workspace if running
-  const prefix = config.workspace.labelPrefix || '';
-  const matchTargets = [
-    targetSessionName,
-    targetDirname,
-    targetBranch,
-    prefix ? `${prefix}${targetSessionName}` : null,
-    prefix ? `${prefix}${targetDirname}` : null,
-  ].filter(Boolean);
-
-  herdr.closeWorkspacesMatching(matchTargets);
-
-  // 2. Remove Worktree & Directory
+  // 1. Remove Worktree & Directory
   console.log(`\n==> [1/3] Removing git worktree and directory...`);
   const isRegisteredWorktree = worktrees.some(wt => path.resolve(wt.path) === path.resolve(targetWorktreePath));
 
@@ -148,27 +136,46 @@ async function executeNuke(flags, config, cwd = process.cwd()) {
     console.log(`Worktree directory is clean.`);
   }
 
-  // 3. Delete Local Branch
+  // Helper for final cleanup steps (Herdr workspace close + Post-Nuke hook)
+  const finishCleanup = async () => {
+    // Post-Nuke Hook
+    if (typeof config.hooks.onPostNuke === 'function') {
+      await config.hooks.onPostNuke(ctx);
+    }
+
+    // Close Herdr Workspace if running (performed last so active pane is not terminated mid-cleanup)
+    const prefix = config.workspace.labelPrefix || '';
+    const matchTargets = [
+      targetSessionName,
+      targetDirname,
+      targetBranch,
+      prefix ? `${prefix}${targetSessionName}` : null,
+      prefix ? `${prefix}${targetDirname}` : null,
+    ].filter(Boolean);
+
+    herdr.closeWorkspacesMatching(matchTargets);
+
+    console.log(`\nCleanup complete!`);
+  };
+
+  // 2. Delete Local Branch
   if (flags.dirOnly) {
     console.log(`\n==> Skipping branch deletion (--dir-only / --keep-branch).`);
-    if (typeof config.hooks.onPostNuke === 'function') await config.hooks.onPostNuke(ctx);
-    console.log(`\nCleanup complete!`);
-    process.exit(0);
+    await finishCleanup();
+    return;
   }
 
   const protectedBranches = config.repo.protectedBranches || ['main', 'master', 'develop', 'prod', 'staging', 'production'];
   if (targetBranch && protectedBranches.includes(targetBranch)) {
     console.warn(`\n==> WARNING: "${targetBranch}" is a protected branch. Skipping local and remote branch deletion.`);
-    if (typeof config.hooks.onPostNuke === 'function') await config.hooks.onPostNuke(ctx);
-    console.log(`\nCleanup complete!`);
-    process.exit(0);
+    await finishCleanup();
+    return;
   }
 
   if (!targetBranch) {
     console.log(`\n==> No branch associated with "${target}". Skipping branch deletion.`);
-    if (typeof config.hooks.onPostNuke === 'function') await config.hooks.onPostNuke(ctx);
-    console.log(`\nCleanup complete!`);
-    process.exit(0);
+    await finishCleanup();
+    return;
   }
 
   console.log(`\n==> [2/3] Deleting local branch "${targetBranch}"...`);
@@ -181,12 +188,11 @@ async function executeNuke(flags, config, cwd = process.cwd()) {
     console.log(`Local branch "${targetBranch}" does not exist or was already deleted.`);
   }
 
-  // 4. Delete Remote Branch
+  // 3. Delete Remote Branch
   if (flags.keepRemote) {
     console.log(`\n==> Skipping remote branch deletion (--keep-remote / --local-only).`);
-    if (typeof config.hooks.onPostNuke === 'function') await config.hooks.onPostNuke(ctx);
-    console.log(`\nCleanup complete!`);
-    process.exit(0);
+    await finishCleanup();
+    return;
   }
 
   console.log(`\n==> [3/3] Deleting remote branch "${targetBranch}" from origin...`);
@@ -198,12 +204,7 @@ async function executeNuke(flags, config, cwd = process.cwd()) {
     console.log(`Remote branch "${targetBranch}" does not exist on origin or was already deleted.`);
   }
 
-  // Post-Nuke Hook
-  if (typeof config.hooks.onPostNuke === 'function') {
-    await config.hooks.onPostNuke(ctx);
-  }
-
-  console.log(`\nCleanup complete!`);
+  await finishCleanup();
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@tsuzuku/arise",
-  "version": "1.0.0",
+  "version": "1.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Arise - Unified workplace-agnostic Git worktree and Herdr workspace orchestrator with pluggable project presets",
   "main": "index.js",
   "bin": {

package/presets/generic.js

@@ -21,7 +21,7 @@ module.exports = {
   layout: [
     { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
     { id: 'shell', title: 'shell', cmd: null, split: 'right', from: 'vim' },
-    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'shell', focus: true },
+    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'shell', focus: true, isAgent: true },
   ],
 
   hooks: {

package/presets/laravel.js

@@ -23,7 +23,7 @@ module.exports = {
     { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
     { id: 'logs', title: 'logs', cmd: 'tail -f storage/logs/laravel.log', split: 'right', from: 'vim' },
     { id: 'shell', title: 'shell', cmd: null, split: 'down', from: 'vim' },
-    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'logs', focus: true },
+    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'logs', focus: true, isAgent: true },
   ],
 
   hooks: {

package/presets/node.js

@@ -22,7 +22,7 @@ module.exports = {
     { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
     { id: 'server', title: 'npm server', cmd: 'npm run dev', split: 'right', from: 'vim' },
     { id: 'shell', title: 'shell', cmd: null, split: 'down', from: 'vim' },
-    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'server', focus: true },
+    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'server', focus: true, isAgent: true },
   ],
 
   hooks: {

package/types.d.ts

@@ -16,6 +16,7 @@ export interface CliFlags {
   workspaceName: string | null;
   source: string | null;
   presetName: string | null;
+  agent: string | null;
   focusTarget: string | null;
   installSkill: boolean;
   skillScope: 'global' | 'local' | null;
@@ -41,6 +42,8 @@ export interface PaneDefinition {
   split?: SplitDirection;
   /** Whether to focus this pane by default */
   focus?: boolean;
+  /** Whether this pane is designated as the AI CLI agent pane */
+  isAgent?: boolean;
 }
 
 export interface RepoConfig {
@@ -57,7 +60,9 @@ export interface RepoConfig {
 export interface WorkspaceConfig {
   /** Prefix added to Herdr workspace labels (e.g. '[BE] ') */
   labelPrefix?: string;
-  /** Default pane to focus ('agy', 'vim', 'logs', 'server', 'shell') */
+  /** CLI AI agent to run in the workspace pane ('agy', 'claude', 'aider', 'copilot', 'none', etc.) */
+  agent?: string | { cmd: string; title?: string; [key: string]: any } | null;
+  /** Default pane to focus ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell') */
   defaultFocus?: string;
 }
 

package/worktree.schema.json

@@ -34,15 +34,29 @@
     },
     "workspace": {
       "type": "object",
-      "description": "Herdr workspace naming and focus configuration",
+      "description": "Herdr workspace naming, agent, and focus configuration",
       "properties": {
         "labelPrefix": {
           "type": "string",
           "description": "Prefix added to Herdr workspace labels (e.g. '[BE] ')"
         },
+        "agent": {
+          "type": ["string", "object", "null"],
+          "description": "CLI AI agent to run in the workspace pane ('agy', 'claude', 'aider', 'copilot', 'none', or custom command object)",
+          "properties": {
+            "cmd": {
+              "type": ["string", "null"],
+              "description": "Command to execute the agent"
+            },
+            "title": {
+              "type": "string",
+              "description": "Display title for the agent pane in Herdr"
+            }
+          }
+        },
         "defaultFocus": {
           "type": "string",
-          "description": "Default pane to focus upon creation ('agy', 'vim', 'logs', 'server', 'shell')"
+          "description": "Default pane to focus upon creation ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell')"
         }
       },
       "additionalProperties": false
@@ -83,6 +97,10 @@
           "focus": {
             "type": "boolean",
             "description": "Whether this pane should receive focus by default"
+          },
+          "isAgent": {
+            "type": "boolean",
+            "description": "Whether this pane is designated as the AI CLI agent pane"
           }
         },
         "additionalProperties": false