feat: add auto-run folder support to CLI create-agent

[ksylvan]

feat: add auto-run folder support to CLI create-agent

Summary

This PR adds support for configuring an agent-specific Auto Run / playbooks folder from the CLI and fixes data-directory discovery so the CLI and Electron app consistently read/write files from the same Maestro user data directory.

The main functional changes are:

• Adds --auto-run-folder <path> to maestro-cli create-agent.
• Propagates autoRunFolderPath through CLI session creation, web server handling, and renderer session state.
• Introduces MAESTRO_USER_DATA as an override for CLI storage and CLI server discovery paths.
• Sets MAESTRO_USER_DATA from Electron’s resolved app.getPath('userData') so dev/prod data directories do not clobber each other.
• Updates docs, CLI prompt help, and tests.

Files Changed

docs/cli.md

Updated the create-agent documentation to include the new --auto-run-folder option.

The full config example now includes:

--auto-run-folder ~/playbooks/full-config

The options table now documents:

| `--auto-run-folder <path>` | Auto Run / playbooks folder for this agent | `<cwd>/.maestro/playbooks` |

src/cli/index.ts

Added a new CLI option to create-agent:

.option(
	'--auto-run-folder <path>',
	'Path to the agent Auto Run / playbooks folder (overrides the default <cwd>/.maestro/playbooks)'
)

This exposes the new agent configuration from the command line.

src/cli/commands/create-agent.ts

Extended CreateAgentOptions with autoRunFolder:

autoRunFolder?: string;

When provided, the path is resolved to an absolute path and sent in the create-session payload:

if (options.autoRunFolder) payload.autoRunFolderPath = path.resolve(options.autoRunFolder);

src/main/web-server/types.ts

Extended CreateSessionConfig to support an optional Auto Run folder path:

autoRunFolderPath?: string;

This allows the value to be passed through the existing session creation config pipeline.

src/main/web-server/WebServer.ts

Updated the createSession callback wiring to accept and forward the optional session config:

createSession: async (
	name: string,
	toolType: string,
	cwd: string,
	groupId?: string,
	config?: CreateSessionConfig
) => this.callbackRegistry.createSession(name, toolType, cwd, groupId, config),

Previously, the web server callback only forwarded name, toolType, cwd, and groupId, which would have dropped additional session configuration.

src/main/web-server/handlers/messageHandlers.ts

Added handling for autoRunFolderPath in create-agent/session messages:

if (message.autoRunFolderPath) config.autoRunFolderPath = message.autoRunFolderPath as string;

The comment explicitly notes that the Auto Run folder may live outside the agent cwd:

// autoRunFolderPath can be set outside of the agent's cwd (no confinement needed)

src/renderer/hooks/remote/useAppRemoteEventListeners.ts

Updated remote session creation handling so autoRunFolderPath is preserved in renderer state:

...(config?.autoRunFolderPath && {
	autoRunFolderPath: config.autoRunFolderPath as string,
}),

src/main/index.ts

Sets MAESTRO_USER_DATA to the Electron app’s resolved userData path:

process.env.MAESTRO_USER_DATA = app.getPath('userData');

This ensures shared CLI server discovery logic uses the same data directory that the app is actually using, including dev-mode paths such as maestro-dev.

src/cli/services/storage.ts

Updated CLI storage path resolution to honor MAESTRO_USER_DATA:

if (process.env.MAESTRO_USER_DATA) {
	return path.resolve(process.env.MAESTRO_USER_DATA);
}

This allows CLI storage to be redirected to the same configured app data directory instead of always using platform defaults.

src/shared/cli-server-discovery.ts

Updated CLI server discovery path resolution to also honor MAESTRO_USER_DATA:

if (process.env.MAESTRO_USER_DATA) {
	return path.resolve(process.env.MAESTRO_USER_DATA);
}

This keeps discovery file lookup aligned with CLI storage behavior.

src/__tests__/cli/services/storage.test.ts

Updated test setup to delete any inherited MAESTRO_USER_DATA value before each test:

delete process.env.MAESTRO_USER_DATA;

This prevents a shell-level environment variable from shadowing mocked platform and homedir values.

src/__tests__/shared/cli-server-discovery.test.ts

Added environment isolation around MAESTRO_USER_DATA and added tests verifying that:

• MAESTRO_USER_DATA overrides the platform-default config path.
• Relative MAESTRO_USER_DATA values are resolved to absolute paths.

Example assertion:

expect(mockFs.readFileSync).toHaveBeenCalledWith(
	path.join(path.resolve('./relative-data-dir'), 'cli-server.json'),
	'utf-8'
);

src/prompts/_maestro-cli.md

Updated the embedded Maestro CLI usage prompt to include the new option:

[--auto-run-folder <path>] [--json]

Code Changes

New --auto-run-folder CLI option

The CLI now accepts an optional Auto Run / playbooks folder when creating an agent:

.option(
	'--auto-run-folder <path>',
	'Path to the agent Auto Run / playbooks folder (overrides the default <cwd>/.maestro/playbooks)'
)

The value is normalized to an absolute path before being sent to the app:

if (options.autoRunFolder) payload.autoRunFolderPath = path.resolve(options.autoRunFolder);

Auto Run folder propagation through session creation

The session config type now includes:

autoRunFolderPath?: string;

The web server message handler reads it from incoming messages:

if (message.autoRunFolderPath) config.autoRunFolderPath = message.autoRunFolderPath as string;

The renderer stores it on newly-created sessions:

...(config?.autoRunFolderPath && {
	autoRunFolderPath: config.autoRunFolderPath as string,
}),

User data directory override via MAESTRO_USER_DATA

Both CLI storage and CLI server discovery now support a shared data directory override:

if (process.env.MAESTRO_USER_DATA) {
	return path.resolve(process.env.MAESTRO_USER_DATA);
}

The Electron main process publishes its resolved user data path to that variable:

process.env.MAESTRO_USER_DATA = app.getPath('userData');

This ensures that shared code writes files such as cli-server.json into the same directory the app is configured to use.

Reason for Changes

Agent-specific Auto Run folder support

Before this change, agents created through the CLI used the default Auto Run / playbooks folder derived from the agent cwd. This made it difficult to point an agent at a shared or external playbooks directory.

The new --auto-run-folder flag allows callers to explicitly configure the playbooks folder during agent creation.

Consistent dev/prod CLI server discovery

The shared CLI server discovery logic previously used hardcoded platform defaults. In development mode, the Electron app may use a different user data path such as maestro-dev, while the CLI discovery code would still look at the default production-like directory.

That could cause dev and prod sessions to clobber each other’s cli-server.json, or cause the CLI to fail to discover the running app server.

By setting and honoring MAESTRO_USER_DATA, the app and CLI now agree on the active data directory.

Impact of Changes

• CLI-created agents can now use custom Auto Run / playbooks directories.
• Relative --auto-run-folder values are resolved to absolute paths by the CLI before being sent to the app.
• Dev and prod data directories are better isolated.
• CLI server discovery should be more reliable when the app uses a non-default userData path.
• Tests are more robust in environments where MAESTRO_USER_DATA is set externally.

Test Plan

The following areas should be tested:

1. Create an agent with a custom Auto Run folder

   maestro-cli create-agent "Playbook Agent" \
     --cwd /tmp/project \
     --auto-run-folder ~/playbooks/project

   Verify that the created session has the expected autoRunFolderPath.

2. Create an agent without --auto-run-folder

   maestro-cli create-agent "Default Agent" --cwd /tmp/project

   Verify that the default playbooks folder behavior remains unchanged.

3. Relative Auto Run folder path

   maestro-cli create-agent "Relative Playbooks" \
     --cwd /tmp/project \
     --auto-run-folder ./playbooks

   Verify that the path is stored as an absolute path.

4. Development mode CLI discovery

   Start the app in development mode and verify that cli-server.json is written under the app’s resolved dev userData directory instead of the production/default directory.

5. Environment override

   Run CLI operations with MAESTRO_USER_DATA explicitly set and confirm storage and server discovery use that path.

6. Automated tests

   Run the affected test suites:

   npm test -- storage.test.ts
   npm test -- cli-server-discovery.test.ts

Additional Notes

• autoRunFolderPath is intentionally not confined to the agent cwd. This allows shared playbook directories and external automation folders.
• MAESTRO_USER_DATA is resolved with path.resolve, so relative overrides become absolute paths.
• Test setup now clears inherited MAESTRO_USER_DATA values to avoid nondeterministic behavior in CI or local shells.
• Potential issue to monitor: because autoRunFolderPath can point outside the agent cwd, any code that reads from or writes to that folder should continue to treat it as user-controlled input and avoid unsafe assumptions about path locality.

Summary by CodeRabbit

• New Features

  • New --auto-run-folder option for creating agents; sessions and launches can use a custom playbook folder.
  • App startup now exposes a unified user-data path so CLI and app share the same config/storage location.

• Behavior Changes

  • Remote batch launches use a default batch prompt when none provided.

• Documentation

  • CLI docs updated to document the new option.

• Tests

  • Added/updated tests for env-based config directory and auto-run behavior.