Skip to content

feat(cli): group icon/color flags and a new update-group verb #1427

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pedramamini wants to merge 2 commits into
base: rc
Choose a base branch
from
Open

feat(cli): group icon/color flags and a new update-group verb #1427

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
28a2fde
feat(cli): group icon/color flags and a new update-group verb
Aug 25, 2026
6eefcb9
fix(remote): stop the create-group flush from writing the group twice
pedramamini Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/agent-guides/CLI-UI-PARITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ of taking a second round trip or trusting a value the caller guessed.
| SSH remote execution config | `update-agent --ssh-remote / --ssh-cwd`, `create-ssh-remote` |
| Focus an agent, switch AI/Shell mode | `focus-agent`, `switch-mode` |
| Create / rename / remove a group | `create-group`, `rename-group`, `remove-group` |
| Group icon, color, and nesting | `create-group --icon/--color/--parent`, `update-group` |
| Create a worktree agent | `create-worktree` |
| New / close / rename a tab | `tab new`, `tab close`, `tab rename` |
| Star a tab (Cmd+Shift+S) | `tab star` / `tab unstar` |
Expand Down
26 changes: 26 additions & 0 deletions docs/agent-guides/SHARED-UTILS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,32 @@ span so a platform that DID fire a hide/show pair can't subtract the same sleep

---

## Group Appearance (`src/shared/groupAppearance.ts` - Both)

The one catalog of Left Bar group icon IDs and label colors, plus the
normalization and validation over them. Three consumers read it: the renderer's
picker (`renderer/components/ui/groupAppearanceOptions.ts`, which adds the only
renderer-owned piece, the icon-ID -> Lucide mapping), the WebSocket
`create_group` / `update_group` handlers, and the `create-group` /
`update-group` CLI commands. Do NOT write a second icon-ID list: the CLI would
happily accept an icon the picker cannot draw.

Values are normalized, not merely checked, so `#ef4444` and `#EF4444` persist
identically and a readback comparison is a plain string equal.

| Export | Signature | Purpose |
| -------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `GROUP_ICON_CATALOG` | `readonly { id, label }[]` | Built-in icons, in picker order. |
| `GROUP_ICON_IDS` | `readonly string[]` | Just the IDs, for validation and error text. |
| `GROUP_LABEL_COLORS` | `readonly { value, label }[]` | Built-in label colors; `value` is the persisted uppercase `#RRGGBB`. |
| `normalizeGroupIconId(raw)` | `(string) => string \| null` | Canonical icon ID (built-in or `plugin/pack/local`), or `null` if unrecognized. |
| `normalizeGroupColor(raw)` | `(string) => string \| null` | Uppercased `#RRGGBB` or a namespaced plugin color ID, or `null`. |
| `validateGroupAppearance(input)` | `(GroupAppearanceInput) => GroupAppearanceValidation` | Enforces emoji/icon exclusivity and normalizes. Run BEFORE mutating any state. |
| `validateGroupUpdate(request)` | `(GroupUpdateRequest) => GroupUpdateValidation` | The above plus the clear-list rules and "an update must change something". |
| `GROUP_CLEARABLE_FIELDS` | `readonly ['emoji','icon','color','parent']` | What an update may clear. Clearing is explicit, never a `null` value over the wire. |

---

## Git Utilities (`src/shared/gitUtils.ts` - Both)

| Function | Signature | Purpose |
Expand Down
67 changes: 43 additions & 24 deletions docs/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -613,35 +613,37 @@ Print the full command reference (Markdown, or --format json)

Create a new agent in the Maestro desktop app

| Option | Description | Default |
| --------------------------------- | ------------------------------------------------------------------------------------------------ | --------------- |
| `-d, --cwd <path>` | Working directory for the agent | - |
| `-t, --type <type>` | Agent type (claude-code, codex, opencode, factory-droid, copilot-cli, gemini-cli, qwen3-coder) | `"claude-code"` |
| `-g, --group <id>` | Group ID to assign the agent to | - |
| `--nudge <message>` | Nudge message appended to every user message | - |
| `--new-session-message <message>` | Message prefixed to first message in new sessions | - |
| `--custom-path <path>` | Custom binary path for the agent | - |
| `--custom-args <args>` | Custom CLI arguments for the agent | - |
| `--env <KEY=VALUE>` | Environment variable (repeatable) | `[]` |
| `--model <model>` | Model override (e.g., sonnet, opus) | - |
| `--effort <level>` | Effort/reasoning level override | - |
| `--context-window <size>` | Context window size in tokens | - |
| `--provider-path <path>` | Custom provider path | - |
| `--ssh-remote <id>` | SSH remote ID for remote execution | - |
| `--ssh-cwd <path>` | Working directory override on SSH remote | - |
| `--sync-history-to-remote <bool>` | Sync history entries to .maestro/history/ on the remote host (true/false; requires --ssh-remote) | - |
| `--auto-run-folder <path>` | Path to the agent Auto Run / playbooks folder (overrides the default <cwd>/.maestro/playbooks) | - |
| `--json` | Output as JSON (for scripting) | - |
| Option | Description | Default |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------- |
| `-d, --cwd <path>` | Working directory for the agent | - |
| `-t, --type <type>` | Agent type (claude-code, codex, opencode, factory-droid, copilot-cli, antigravity, gemini-cli, qwen3-coder) | `"claude-code"` |
| `-g, --group <id>` | Group ID to assign the agent to | - |
| `--nudge <message>` | Nudge message appended to every user message | - |
| `--new-session-message <message>` | Message prefixed to first message in new sessions | - |
| `--custom-path <path>` | Custom binary path for the agent | - |
| `--custom-args <args>` | Custom CLI arguments for the agent | - |
| `--env <KEY=VALUE>` | Environment variable (repeatable) | `[]` |
| `--model <model>` | Model override (e.g., sonnet, opus) | - |
| `--effort <level>` | Effort/reasoning level override | - |
| `--context-window <size>` | Context window size in tokens | - |
| `--provider-path <path>` | Custom provider path | - |
| `--ssh-remote <id>` | SSH remote ID for remote execution | - |
| `--ssh-cwd <path>` | Working directory override on SSH remote | - |
| `--sync-history-to-remote <bool>` | Sync history entries to .maestro/history/ on the remote host (true/false; requires --ssh-remote) | - |
| `--auto-run-folder <path>` | Path to the agent Auto Run / playbooks folder (overrides the default <cwd>/.maestro/playbooks) | - |
| `--json` | Output as JSON (for scripting) | - |

## `maestro-cli create-group <name>`

Create a new group in the Maestro desktop app

| Option | Description | Default |
| --------------------- | ------------------------------ | ------- |
| `-e, --emoji <emoji>` | Emoji icon for the group | - |
| `--parent <group-id>` | Create inside this root group | - |
| `--json` | Output as JSON (for scripting) | - |
| Option | Description | Default |
| --------------------- | ------------------------------------------------------------------------------------------------------ | ------- |
| `-e, --emoji <emoji>` | Emoji icon for the group | - |
| `--icon <icon-id>` | Built-in icon ID (folder, briefcase, rocket, ...) or a plugin icon ID. Mutually exclusive with --emoji | - |
| `--color <color>` | Label color as #RRGGBB, or a plugin color ID | - |
| `--parent <group-id>` | Create inside this root group | - |
| `--json` | Output as JSON (for scripting) | - |

## `maestro-cli remove-group <group-id>`

Expand All @@ -660,6 +662,23 @@ Rename a group in the Maestro desktop app
| -------- | ------------------------------ | ------- |
| `--json` | Output as JSON (for scripting) | - |

## `maestro-cli update-group <group-id>`

Update a group's name, icon, color, or parent in the Maestro desktop app

| Option | Description | Default |
| --------------------- | ------------------------------------------------------------------------------------------------------ | ------- |
| `-n, --name <name>` | New group name | - |
| `-e, --emoji <emoji>` | Emoji icon for the group. Mutually exclusive with --icon | - |
| `--icon <icon-id>` | Built-in icon ID (folder, briefcase, rocket, ...) or a plugin icon ID. Mutually exclusive with --emoji | - |
| `--color <color>` | Label color as #RRGGBB, or a plugin color ID | - |
| `--parent <group-id>` | Move the group inside this root group | - |
| `--clear-emoji` | Reset the emoji to the default folder | - |
| `--clear-icon` | Remove the icon | - |
| `--clear-color` | Remove the label color | - |
| `--clear-parent` | Promote the group to the top level | - |
| `--json` | Output as JSON (for scripting) | - |

## `maestro-cli create-worktree`

Create a new agent in a git worktree branched off an existing parent agent
Expand Down
Loading
Loading