Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Theme customization docs missing named custom themes and plugin `themes/` directories [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52190•Fetched 2026-04-23 07:34:12
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3subscribed ×1
RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/commands

Section/Topic

/theme custom theme management, theme file locations, and plugin theme packaging

Current Documentation

No documentation currently exists for named custom themes, JSON theme files in ~/.claude/themes/, or plugin-shipped themes in a themes/ directory.

The nearest current docs only say:

/theme | Change the color theme. Includes light and dark variants, colorblind-accessible (daltonized) themes, and ANSI themes that use your terminal's color palette

  • Other configuration is stored in ~/.claude.json. This file contains your preferences (theme, notification settings, editor mode), OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches.

Plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.

DirectoryLocationPurpose
.claude-plugin/Plugin rootContains plugin.json manifest (optional if components use default locations)
skills/Plugin rootSkills as <name>/SKILL.md directories
commands/Plugin rootSkills as flat Markdown files. Use skills/ for new plugins
agents/Plugin rootCustom agent definitions
hooks/Plugin rootEvent handlers in hooks.json
.mcp.jsonPlugin rootMCP server configurations
.lsp.jsonPlugin rootLSP server configurations for code intelligence
bin/Plugin rootExecutables added to the Bash tool's PATH while the plugin is enabled
settings.jsonPlugin rootDefault settings applied when the plugin is enabled

What's Wrong or Missing?

Changelog v2.1.118 added a new user-facing theme workflow: "Create and switch between named custom themes from /theme, or hand-edit JSON files in ~/.claude/themes/; plugins can also ship themes via a themes/ directory".

The current docs only cover selecting built-in themes and mention that general theme preferences live in ~/.claude.json. They do not document:

A. Named custom themes in /theme

There is no explanation of how users create, save, rename, or switch between named custom themes from the /theme picker.

B. Theme file storage and manual editing

There is no documentation for the ~/.claude/themes/ directory, what files belong there, or how manual JSON edits relate to the /theme UI.

C. Plugin-shipped themes

The plugin docs and plugin reference do not mention a themes/ directory at all, so plugin authors have no documentation for shipping themes and users have no documentation for how those themes appear in Claude Code.

Suggested Improvement

Add a dedicated "Custom themes" subsection in the theme-related docs that covers:

  1. How to create and switch named custom themes from /theme
  2. The purpose and location of ~/.claude/themes/
  3. A minimal valid JSON theme example and any schema/field reference
  4. How manual JSON edits are picked up by Claude Code
  5. How plugins can ship themes via a themes/ directory, including where that directory lives in the plugin root and how shipped themes become available to users

Also update the plugin structure tables in both plugin docs pages to include themes/ alongside the other supported plugin components.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageLine(s)Context
https://code.claude.com/docs/en/commands91/theme is documented only as a built-in theme selector
https://code.claude.com/docs/en/interactive-mode56-60Mentions only Ctrl+T inside the /theme picker
https://code.claude.com/docs/en/settings117, 224Mentions theme preferences in ~/.claude.json, but not ~/.claude/themes/ or custom theme files
https://code.claude.com/docs/en/plugins176-193Plugin structure table omits themes/
https://code.claude.com/docs/en/plugins-reference15-16, 17-25Plugin component reference omits themes as a supported component

Total scope: 5 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Create and switch between named custom themes from /theme, or hand-edit JSON files in ~/.claude/themes/; plugins can also ship themes via a themes/ directory

extent analysis

TL;DR

Add a "Custom themes" subsection to the theme-related documentation to cover named custom themes, theme file storage, and plugin-shipped themes.

Guidance

Example

A minimal valid JSON theme example could be added to the documentation, such as:

{
  "name": "My Custom Theme",
  "colors": {
    "background": "#ffffff",
    "foreground": "#000000"
  }
}

This example would help users understand the format of theme files in ~/.claude/themes/.

Notes

The suggested improvement should be applied to the affected pages, and the changes should be verified to ensure that the documentation is accurate and complete.

Recommendation

Apply the suggested improvement to add a dedicated "Custom themes" subsection to the theme-related documentation, as it will provide users with clear guidance on using named custom themes, theme file storage, and plugin-shipped themes.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#model download#tokenizer error#prompt formatting

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Theme customization docs missing named custom themes and plugin `themes/` directories [1 participants]