docs(cli): clarify custom modes location for CLI #4599
Conversation
- Add comprehensive CUSTOM_MODES.md documentation - Clarify that CLI uses ~/.kilocode/cli/global/settings/custom_modes.yaml - Explain difference between CLI and VSCode extension paths - Provide migration instructions for copying modes from VSCode to CLI - Add quick start guide in README - Document that project-level modes work the same in both CLI and VSCode
|
![kiloconnect[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
There was a problem hiding this comment.
🚨 3 Critical Issues Found
| Severity | Issue | Location |
|---|---|---|
| CRITICAL | Documentation contradicts actual CLI code behavior | cli/README.md:238-241 |
| CRITICAL | Incorrect file path for global custom modes | cli/docs/CUSTOM_MODES.md:15-17 |
| CRITICAL | Unnecessary migration instructions | cli/docs/CUSTOM_MODES.md:103-130 |
Recommendation: Do not merge until the fundamental issue is resolved.
Summary
This PR's documentation states that the CLI uses ~/.kilocode/cli/global/settings/custom_modes.yaml for global custom modes. However, the actual CLI code in cli/src/config/customModes.ts reads from the VSCode extension's global storage path:
- macOS:
~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml - Windows:
%APPDATA%/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml - Linux:
~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml
This means the CLI already shares global custom modes with the VSCode extension, contrary to what this documentation claims.
Impact
If merged as-is, users will:
- Create custom modes files in the wrong location (
~/.kilocode/cli/...) - Wonder why their modes don't work
- Perform unnecessary "migration" steps that accomplish nothing
Resolution Options
- Update the code to actually use
~/.kilocode/cli/global/settings/custom_modes.yaml(requires code changes in addition to this documentation) - Update the documentation to reflect the actual behavior - that the CLI shares global modes with the VSCode extension (simpler fix, but changes the PR's intent)
Review Details (2 files)
Files: cli/README.md (1 issue), cli/docs/CUSTOM_MODES.md (2 issues)
Checked: Documentation accuracy against source code
| Kilo Code CLI supports custom modes that allow you to create specialized AI agents with specific roles and capabilities. Custom modes can be defined globally (available across all projects) or per-project. | ||
| **Important**: The CLI uses its own configuration directory for global custom modes: | ||
| - **CLI Global Modes**: `~/.kilocode/cli/global/settings/custom_modes.yaml` |
There was a problem hiding this comment.
🚨 CRITICAL: Documentation contradicts actual code behavior
The documentation states the CLI uses ~/.kilocode/cli/global/settings/custom_modes.yaml, but the actual code in cli/src/config/customModes.ts shows the CLI reads from the VSCode extension's global storage path:
- macOS:
~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml - Windows:
%APPDATA%/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml - Linux:
~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml
This means:
- Users following this documentation will create files in the wrong location
- The CLI actually does share global modes with the VSCode extension (contrary to what this PR claims)
- The migration instructions are unnecessary and misleading
Resolution options:
- Update the code to actually use
~/.kilocode/cli/global/settings/custom_modes.yaml(requires code changes) - Update this documentation to reflect the actual behavior (CLI shares global modes with VSCode extension)
|
|
||
| **Important**: The CLI uses its own configuration directory for global custom modes, separate from the VSCode extension. | ||
|
|
There was a problem hiding this comment.
🚨 CRITICAL: Incorrect file path - contradicts actual CLI code
This path ~/.kilocode/cli/global/settings/custom_modes.yaml does not match the actual code. The CLI code in cli/src/config/customModes.ts reads from the VSCode extension's global storage path, not this custom CLI path.
The entire premise of this documentation file is incorrect - the CLI does share global modes with the VSCode extension.
There was a problem hiding this comment.
This is incorrect, and the cause of this bug.
|
|
||
| ### Switch Modes During a Session | ||
|
|
||
| Use the `/mode` command within an active CLI session: | ||
|
|
||
| ``` | ||
| /mode my-custom-mode | ||
| ``` | ||
|
|
||
| ## Migrating Global Modes from VSCode to CLI | ||
|
|
||
| If you've created global custom modes in the VSCode extension and want to use them in the CLI: | ||
|
|
||
| ### macOS | ||
| ```bash | ||
| # Create CLI config directory | ||
| mkdir -p ~/.kilocode/cli/global/settings | ||
| # Copy from VSCode extension to CLI | ||
| cp ~/Library/Application\ Support/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml \ | ||
| ~/.kilocode/cli/global/settings/custom_modes.yaml | ||
| ``` | ||
|
|
||
| ### Linux | ||
| ```bash | ||
| # Create CLI config directory | ||
| mkdir -p ~/.kilocode/cli/global/settings | ||
There was a problem hiding this comment.
🚨 CRITICAL: Migration instructions are unnecessary and misleading
These migration instructions tell users to copy files from VSCode to a CLI-specific location. However, the actual CLI code reads directly from the VSCode extension's global storage path.
If the CLI code is correct, these migration instructions should be removed entirely - global modes created in VSCode should already work in the CLI without any migration.
Summary
This PR updates the CLI documentation to clarify the correct location for global custom modes in the CLI.
Problem
The CLI attempts to read global custom modes from
~/.kilocode/cli/global/settings/custom_modes.yaml, but the documentation didn't clearly explain this. Users who created global custom modes in the VSCode extension (which stores them at~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yamlon macOS) would find that those modes don't work in the CLI.Changes
New Documentation File: Added
cli/docs/CUSTOM_MODES.mdwith comprehensive documentation including:Updated README: Added a "Custom Modes" section to
cli/README.mdwith:Key Points
~/.kilocode/cli/global/settings/custom_modes.yaml~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yamlon macOS).kilocodemodes(works the same in both CLI and VSCode)Testing
Documentation changes only - no code changes required.
Related Issues
Addresses user confusion about why global custom modes created in VSCode don't appear in the CLI.