Skip to content

Latest commit

 

History

History
158 lines (106 loc) · 19.4 KB

README.md

File metadata and controls

158 lines (106 loc) · 19.4 KB

Tokencat

A Carbonfox-derived dark theme for Hermes and companion apps, with an unchanged Carbonfox (Legacy) variant for switching back. Canonical repository: chrisluersen/tokencat-theme, formerly hermesfox-theme.

How it differs from Hermes default and Carbonfox

Choice Appearance and scope
Hermes built-in default Classic warm gold/bronze accents, cornsilk text, kawaii spinners and the caduceus banner. It comes with Hermes; this repository does not replace its source.
Carbonfox (Legacy) in this bundle Preserved local Carbonfox adaptation: dark charcoal background, blue/cyan/purple accents and token-cat artwork. It is derived from Nightfox Carbonfox, not an identical copy of every upstream app theme.
Tokencat Retains the Carbonfox base palette and token-cat, with explicit semantic aliases and readability overrides for selected suggestions, comments and word diffs. Adds dedicated dashboard, WezTerm and Zellij artifacts alongside Hermes, VS Code and Windows Terminal exports.

This changes appearance and displayed branding only, not models, reasoning, tools, permissions or agent capabilities. The shipped Windows Terminal schemes have identical color values and differ by name; most changes are surface-specific readability roles, not an entirely new ANSI palette.

This is a source-qualified theme bundle, not a claim of complete app/runtime acceptance. VS Code suggestion states were verified visually and by computed styles through switching and cold restart; WezTerm loaded and displayed the new native scheme. Native Hermes skin/normalizer/converter checks pass, while full CLI/TUI/dashboard/desktop, Windows Terminal and Zellij app acceptance remain outstanding. See the per-surface evidence matrix, palette lineage, validation, and rights/attribution.

Shipped variants

Surface Upgraded Tokencat Preserved Carbonfox
Palette palettes/tokencat.json palette.json
Hermes CLI / TUI / desktop skin hermes/skins/tokencat.yaml, name tokencat hermes/skins/carbonfox.yaml, name carbonfox
Dashboard hermes/dashboard-themes/tokencat.yaml No previous dashboard export existed
Windows Terminal windows-terminal/tokencat.scheme.json, name tokencat windows-terminal/scheme.json, name carbonfox
VS Code theme vscode/tokencat.vscode-theme.json, label Tokencat (the only contributed theme) vscode/carbonfox.vscode-theme.json, retained on disk but no longer contributed
Zed theme zed/tokencat.json, name Tokencat No previous Zed export existed
VS Code merge fragment vscode/tokencat-color-customizations.json vscode/vscode-color-customizations.json
WezTerm wezterm/tokencat.toml, scheme Tokencat No legacy companion export existed; preserve the user's prior choice
Zellij zellij/tokencat.kdl, theme tokencat No legacy companion export existed; preserve the user's prior choice

vscode/package.json contributes Tokencat alone in one minimal, code-free local extension. The earlier Hermesfox and Carbonfox (Legacy) VS Code labels both pointed at carbonfox.vscode-theme.json, so they were three menu entries for one appearance; the labels were removed and the payload retained on disk, unlisted. Carbonfox remains its own surface elsewhere (Hermes skin, Windows Terminal scheme). Its declared baseline is VS Code ^1.136.2; older versions are not claimed supported. Local construction does not establish Marketplace ownership or publishing rights.

zed/tokencat.json is the richest surface: 138 style keys and 57 syntax roles, including native window blur. docs/ssot-tokencat.csv and docs/ssot-tokencat.md are generated by scripts/ssot_table.py and list every colour and font key for every surface side by side, so cross-surface drift is visible rather than inferred. Regenerate them; do not hand-edit. The decision record, coverage counts and the one open drift item are in docs/ssot-decision.md; live editor font settings that the theme files do not carry are in docs/fonts.json.

All original base values, original exports and the cat sources are hash-guarded against revision 793dcd583c873a7512c6d2a5222d4d0b697f704c. New aliases and readability overrides exist only in the upgrade. Legacy intentionally retains its previous visual limitations; rollback does not mean it has passed new contrast targets.

Agent installation and setup quick-start

This guide helps another agent install the theme only after that workstation's user explicitly authorizes the target app/profile and the requested effect. This README is not permission to install or activate anything. Installing files and changing an app's selected theme are separate actions.

Start with a clean checkout in a user-approved workspace (Hermes agents should keep their own checkout under the active HERMES_HOME):

git clone https://github.com/chrisluersen/tokencat-theme.git
cd tokencat-theme
git rev-parse HEAD

The examples below use Bash/POSIX syntax, including Git Bash on Windows. Use the target machine's actual paths; do not copy paths from another workstation. On Windows, pass native C:/... paths to native executables if MSYS path conversion is disabled. Do not install optional tooling without the target user's applicable approval.

  1. Use the intended source revision. Record git rev-parse HEAD, inspect its changes and CI, and confirm it is the revision the user asked to install. A pushed feature branch is not automatically merged, released, or suitable for installation; do not silently substitute master or another branch.
  2. Inventory and preserve the target. Identify the exact app, version, profile/config directory and current theme selection. Back up only the files/settings that will be changed, preserve existing Carbonfox and unrelated settings, and use each app's supported install/selection method. Never replace an entire app configuration file or profile.
  3. Follow the matching surface procedure below. These exports are separate formats; do not copy every file into every application's config directory. No font installation or Hermes source patch is required.
  4. Read back and verify in the real app. Confirm the installed files and selected theme, inspect the target surface's meaningful visual states, and state which surfaces were and were not verified. Parser, schema, or unit-test results are not live-app acceptance.
  5. Stop safely on a blocked target. If the exact app/window cannot be inspected safely, leave that surface pending. Do not force input to another window, restart an active app, close user tabs, or claim success from a settings write alone. Roll back by restoring the recorded prior selection and only the files/keys changed.
Surface Artifact Setup instructions
Hermes CLI / TUI / desktop hermes/skins/tokencat.yaml Hermes procedure; set HERMES_HOME explicitly and use hermes config set display.skin tokencat.
Hermes dashboard hermes/dashboard-themes/tokencat.yaml Follow the separate Dashboard procedure below; install independently from the Hermes skin, then select in its picker.
Windows Terminal windows-terminal/tokencat.scheme.json Windows Terminal procedure; merge the scheme by unique name and change only the intended profile's colorScheme.
VS Code vscode/ theme-only extension VS Code procedure; with an already available/approved @vscode/vsce CLI, run vsce package from vscode/, install the VSIX with the VS Code CLI, then select Tokencat (the only contributed theme).
Zed zed/tokencat.json Copy to the user themes directory (~/.config/zed/themes/ on Linux/macOS, %APPDATA%\Zed\themes\ on Windows), then select Tokencat in the theme picker. The theme declares background.appearance: blurred; set it to opaque if you do not want native window blur.
WezTerm wezterm/tokencat.toml WezTerm procedure; integrate the standalone color scheme into the existing Lua config without replacing it.
Zellij zellij/tokencat.kdl Zellij procedure; install the named theme and validate with the target's native Zellij version before selecting it.

The detailed steps below include per-surface rollback and known qualification limits. In particular, no native Zellij runtime was available during this bundle's qualification, and Windows Terminal's visual states still require verification on the target installation.

Safe installation and rollback — only when separately authorized

Source qualification did not itself activate a live theme selection; any downstream deployment is a separate, user-authorized operation. VS Code used separate settings/extension directories, and WezTerm used a separate config/process. VS Code also opened existing app-global shared storage; without a before-image, its integrity or unchanged state cannot be asserted. Captured fingerprint matches establish preservation only for the specifically measured files at the time of comparison, not the entire profile or an ongoing guarantee. A later comparison detected configuration drift; its cause was not established or reversed, and the legacy theme remained selected. Rendered-state evidence is not proof of whole-profile isolation. First qualify the exact app/version and all relevant storage boundaries before a future preview. Back up only the target files/keys, record prior selections, and never replace a whole profile, config.yaml, VS Code User Settings, or Windows Terminal settings.json. Use artifacts from an explicitly reviewed revision; a branch upload is not a release or proof of full runtime acceptance.

Hermes CLI, TUI and desktop

  1. Explicitly identify the target Hermes home; do not assume ~/.hermes on Windows or change another profile. Back up any existing skins/tokencat.yaml, skins/carbonfox.yaml, and the prior display.skin value.
  2. Copy the repository skin files into that home's skins directory. Keep all names. Do not overwrite an existing customized file without preserving it.
  3. After authorization, in a shell with TARGET_HERMES_HOME explicitly set, use the supported writer:
: "${TARGET_HERMES_HOME:?Choose the explicit approved target home first}"
mkdir -p "$TARGET_HERMES_HOME/skins"
# Only after preserving any existing files with these names:
cp hermes/skins/tokencat.yaml hermes/skins/carbonfox.yaml "$TARGET_HERMES_HOME/skins/"
env HERMES_HOME="$TARGET_HERMES_HOME" hermes skin list
env HERMES_HOME="$TARGET_HERMES_HOME" hermes config set display.skin tokencat
env HERMES_HOME="$TARGET_HERMES_HOME" hermes config get display.skin

Verify the actual CLI, TUI and desktop independently. Desktop Appearance may have its own selection flow; shared skin parsing alone is not proof that it rendered. Keep the active single-span-per-row token-cat. banner_logo: " " is a renderer workaround, not a general hide API; startup artwork may require a restart. Do not enable the alternate two-tone cat until its exact TUI renderer passes the documented gate.

Switch back to the retained Carbonfox selection when desired:

: "${TARGET_HERMES_HOME:?Choose the explicit approved target home first}"
env HERMES_HOME="$TARGET_HERMES_HOME" hermes config set display.skin carbonfox
env HERMES_HOME="$TARGET_HERMES_HOME" hermes config get display.skin

For complete rollback, restore the recorded prior selection (which may not have been Carbonfox) and only the specific overwritten files from the backup. No Hermes source patch or plugin is needed or supplied.

Dashboard — a separate format and selection

Copy hermes/dashboard-themes/tokencat.yaml to the explicitly selected home's dashboard-themes directory only after authorization. Refresh and choose Tokencat in the dashboard theme picker. Verify /api/dashboard/themes and the browser's computed colors: a backend that drops colorOverrides or palette.warmGlow blocks full-fidelity acceptance. Merely seeing a named theme in the picker is insufficient.

The skin file in skins/ does not theme the dashboard. Roll back to the exact previous dashboard selection; no legacy Carbonfox dashboard entry is promised. This artifact ships no CSS injection, remote fonts, external assets or dashboard plugin, and does not invent a token-cat slot.

Windows Terminal

Back up the settings file, then merge the desired scheme objects into its existing schemes array by unique name: windows-terminal/tokencat.scheme.json is named tokencat and windows-terminal/scheme.json is named carbonfox. Do not replace the whole array or create duplicate names; preserve any existing customized scheme before updating it. Change only the intended profile's colorScheme: tokencat for the upgrade or carbonfox for the archived legacy name. Verify all 16 ANSI colors, truecolor, selection/cursor and glyphs in that profile. For full rollback restore its prior colorScheme and only keys changed by the merge. No font change is required.

VS Code

For normal installation, first confirm VS Code meets the manifest's ^1.136.2 baseline and that the theme selection/profile is authorized. From the repository root, with an available approved @vscode/vsce CLI:

(cd vscode && vsce package)
code --install-extension vscode/tokencat-theme-0.0.1.vsix --force

Use the installed VS Code command-line launcher (code / code.cmd), not the Electron GUI executable as a substitute. --force updates the same theme extension ID; back up an existing package before replacing it. This builds a local VSIX, not a Marketplace publication. Select Tokencat through Preferences: Color Theme, then verify the selected workbench.colorTheme, actual suggestion and word-diff states, and Carbonfox switch-back. Existing per-user/workspace color customizations can override the theme: inspect and preserve them rather than deleting them wholesale. For another VS Code profile, use that installation's supported profile option explicitly. Do not install into every profile.

Use the supplied theme-only extension manifest with fresh user-data/extensions directories. Those directories separate settings and extensions but do not by themselves isolate shared storage or OS integrations; inspect those boundaries before launch and do not claim the entire normal profile is untouched. An Extension Development Host is useful for initial loading; verify ordinary status-bar behavior separately in a normal window with a private passive extension copy and a synthetic folder open. A no-folder window can use different fallback colors. Select Tokencat and verify the actual workbench, syntax, diff, status bar and integrated terminal states.

Alternatively, merge the selected *-color-customizations.json fragment into a backed-up settings object. Merge the two named customization objects, preserving unrelated existing keys. Explicit customization keys override a selected theme, so selecting Carbonfox alone will not undo a Tokencat merge: restore the recorded prior values (or remove only keys that did not exist before). Do not replace complete User Settings or assume the generated fragment is a comment-bearing JSONC parser.

WezTerm

wezterm/tokencat.toml is a standalone native color scheme, not a replacement wezterm.lua. It includes default text/background, cursor, selection, all 16 ANSI colors, pane separators, scrollbar and tab states. It was parsed and rendered by WezTerm 20240203-110809-5046fc22; newer versions still require their own validation.

After backing up the relevant existing keys, copy wezterm/tokencat.toml into a colors subdirectory beside the actual loaded WezTerm configuration file. Determine that directory on the target machine; it is not necessarily the repository or the shell's working directory. Integrate these lines after the existing config object is created and before return config, preserving its shell, fonts, keys, domains and other choices:

local wezterm = require 'wezterm'
local colors = wezterm.color.load_scheme(wezterm.config_dir .. '/colors/tokencat.toml')
config.color_schemes = config.color_schemes or {}
config.color_schemes.Tokencat = colors
config.color_scheme = 'Tokencat'

The persistent scheme path works for GUI launches without a shell environment variable. Do not duplicate an existing local wezterm declaration or overwrite an existing customized Tokencat scheme without preserving it. Validate the integrated configuration using wezterm --config-file <actual-config-file> show-keys, then inspect a fresh launch only when safe and authorized; a successful parse is not visual acceptance. For an isolated preview, use --config-file and start --always-new-process --no-auto-connect with a task-owned config; a new window alone does not prevent loading the real config. Restore the recorded prior color_scheme, the prior scheme entry and only the copied file/config lines changed by this integration for rollback. No shell/font/keybinding changes are shipped.

Zellij

zellij/tokencat.kdl targets the modern role schema shipped in Zellij v0.45.1: text, ribbons, tables, lists, frames, exit statuses and all ten multiplayer colors. It themes Zellij's UI; pane/application ANSI colors still belong to the hosting terminal. It does not ship a session layout, keybindings or plugins.

Copy the file into the explicitly selected Zellij configuration directory's themes subdirectory, preserving any existing file. In a backed-up configuration, select theme "tokencat". Validate with the real target Zellij version in an isolated configuration/session first; no native Zellij executable was available during this qualification. The repository reader validates only the emitted nested-block/RGB subset and palette mappings, not all KDL or native rendering. Restore the recorded prior theme and only the copied file for rollback.

Artwork, optional fonts and scope

Both skins retain the 29×11 cat outline from ascii-art. Tokencat labels the box Lucky / with / Agency, centered within each row's available space; legacy Carbonfox retains $TOKENS. The owner reports verbal permission to use/modify Hayley Jane Wakenshaw's artwork; see NOTICE. An Internet archive is not a blanket redistribution license.

fonts/install-hack-nerd-font.sh remains optional and unchanged. It targets Nerd Fonts v3.5.1, verifies its pinned digest before extraction, and installs only Mono TTFs. Do not run it merely to use the palette. If registry registration fails, copied fonts remain and require deliberate recovery. The test suite uses temporary supplied ZIPs and a fail-closed fake-reg guard; it never invokes real registration or downloads fonts.

The named Hermes surfaces, VS Code, Windows Terminal, WezTerm and Zellij have dedicated artifacts or the shared native skin listed above. Neovim and arbitrary other apps are not claimed supported; no whole-workstation configuration is shipped. The retired gist 16349ada05bdf04399aa328fd0231184 is historical, not a current artifact or settings migration.

Rights

No blanket license is granted for original repository material. Upstream-derived Nightfox material retains its complete MIT notice. The local VS Code package remains UNLICENSED; no font binaries are vendored. See NOTICE.md for the unchanged artwork permission boundary.