Skip to content

Theme Bridge and semantic terminal integration #304

Open
Open
Theme Bridge and semantic terminal integration#304
Labels
enhancementNew feature or request
Milestone
Future / Backlog

Description

@raiseCatError
raiseCatError
opened on Oct 4, 2026

Overview

Theme Bridge is a proposed, opt-in layer for carrying NMSh's semantic appearance into compatible terminal-native tools, alongside related terminal semantic protocols and contextual shell improvements. NMSh remains a frontend over a persistent real shell; terminal emulators and editors retain ownership of their themes.

This is the canonical design and implementation tracker. It is intentionally broader than one release-sized change. Revisit ordering after Phase 0 and implement in reviewable slices.

Motivation and product intent

NMSh already has a Native theme, prompt/UI roles, syntax styling, semantic command history, host capability information, and an owned transcript. Tools launched from NMSh have their own styling and host-integration surfaces. Users should be able to opt specific tools into colors derived from NMSh while preserving user ownership of terminal, editor, and tool configuration.

Example configuration:

Target Mode
NMSh Aurora
fzf Follow NMSh
tmux Choose theme: Gruvbox
Neovim Independent
less/man Follow NMSh

Switching NMSh from Aurora to Lavender updates fzf and pager colors in future managed invocations. tmux remains pinned to Gruvbox and Neovim remains unaffected.

Where technically meaningful, each integration supports:

  • Independent — no NMSh appearance injection or mutation for this target.
  • Follow NMSh — derive from the active NMSh theme and update when it changes.
  • Choose theme — derive from a selected NMSh theme, pinned independently of the active theme.

An integration should explain when a mode is unavailable for a target or runtime context. Do not claim live updates for an already-running process without a supported connection to that exact process.

Existing repository audit

Audit performed against the current checkout, feature/v016-platform-portability-agents, an unmerged development stack at the time of writing. Confirm details against the implementation branch before coding.

Already exists / reusable foundation

  • Appearance and palette: the Native prompt stores one palette id; theme families and variants resolve through src/appearance/themeFamilies.ts and themeSelection.ts. Custom themes use validated, declarative NMSh Theme JSON in src/appearance/customTheme.ts, with separate prompt-module roles and UI roles. UI roles include accent, primary, secondary, subtle, separator, selection, success, warning, failure, and info. Prompt roles include project, cwd, git branch, toolchain/context roles, success, and failure. This is richer and differently shaped than Base16; do not add a competing internal theme system or make Base16 its source of truth.
  • Theme interchange: customTheme.ts imports Base16 and Windows Terminal palette JSON into NMSh roles with an explicit non-lossless mapping warning. This is a useful foundation, not a complete Base16/Base24 interchange or target-adapter layer.
  • Appearance surfaces: /appearance, /prompt, /theme, Settings, and Theme Studio exist. docs/design/theme-families.md says NMSh themes currently color NMSh-owned prompt, syntax, and chrome only. Zed's appearance is reported as host-owned.
  • Syntax and transcript: lexical highlighting and asynchronous semantic command knowledge are separate from raw PTY output. Transcript presentation has historical prompt snapshots, folding, sticky command headers, Chat mode, search, and copy paths. Stored prompt snapshots contain more information than a compact rendering should display.
  • Terminal host: src/host/capabilities.ts and src/host/TerminalHost.ts provide a host/capability boundary, intended to keep host-specific functionality optional. Ghostty keyboard and appearance helpers exist. src/appearance/ghostty.ts writes a managed appearance fragment and can append an include line to Ghostty config for the existing opacity/blur feature. That is distinct from Theme Bridge and is not authority to change Ghostty base colors. Review its config mutation path before reuse.
  • OSC 8: authored Markdown can emit OSC 8 under capability/policy control. The output parser can preserve program-emitted OSC 8 payloads, and Hyperlinks.ts validates targets. However, a TerminalApp transcript path explicitly disables links because the cell/transcript representation cannot preserve OSC 8. Support exists in part but transcript integration is incomplete. Authored links and raw PTY links must remain distinct trust paths.
  • Shell semantic state: shell adapters use authenticated NMSh-owned OSC 777 markers for command lifecycle and completion metadata. This is private NMSh protocol, not OSC 133. No general OSC 7/133 terminal semantic integration was found in this audit.
  • Session/title state: the v0.16 stack includes persistent session identity/signatures and receives sanitized foreground program window-title evidence from OSC 0/2. Investigate ownership and lifecycle before emitting NMSh titles; do not overwrite a foreground application's active title.
  • History/intelligence: the v0.16 stack has a local bounded context-ranked command-history index and directory ranking using existing session/history facts. Native command-not-found evidence and deterministic correction exist, including typo correction and local executable/package support. Extend these only where missing; audit exact signals and UX before duplicating them.
  • Project environment: passive, consent-based mise awareness is documented/implemented in the current stack. It avoids trust, activation, config edits, and installation. direnv trust remains its own integration boundary.
  • Config safety: src/ask/fileEdit.ts has inspect/plan/preview/apply primitives, allowed-root checks, exact edits, hashes, and validation. supported-tool-configuration.md defines narrow per-tool adapters. Use or extend this verified config-edit infrastructure for permanent includes; do not create an ad hoc rewrite path.
  • Tools/providers: shared provider/picker architecture exists, including an optional fzf picker that hands off to the host terminal. This does not mean all NMSh-launched fzf invocations have a theme adapter. Tool discovery/catalog and setup surfaces can inform local detection.
  • Host/multiplexer constraints: fullscreen passthrough exists; tmux may run inside or outside NMSh. docs/architecture/multiplexer-interop.md documents interactions and host caveats.

Missing or requiring fresh research

  • No general semantic-palette-to-application adapter/managed artifact service or per-target Independent/Follow/Choose setting exists.
  • No fzf invocation color adapter, pager bridge, generated LS_COLORS, bat/delta runtime mapping, or Theme Bridge detection/status surface exists.
  • No NMSh-owned tmux, Neovim, or Vim theme artifact/include lifecycle is established.
  • OSC 7 and OSC 133 emission through current ShellAdapter lifecycle is not implemented as host integration. OSC 8 needs transcript-model research/fix before claiming end-to-end support.
  • Session-signature-to-title ownership rules, historical prompt presentation levels, full-block pager action, and some environment status actions need a focused audit against current branch behavior.
  • Recheck implementation state before work; the feature branch may change after this issue is created.

Product boundaries and non-goals

Everything is opt-in. NMSh must not automatically take over Ghostty, Kitty, Zed, VS Code, macOS Terminal profiles, Vim/Neovim colorschemes, tmux themes/plugins, Git configuration, or shell startup files. A specifically enabled integration that requires persistent config mutation must show the exact managed file and exact patch and obtain confirmation using verified config editing.

NMSh is not becoming a terminal emulator. Scope is ANSI/text colors, application-native theme APIs/config, NMSh-owned generated fragments, scoped environment variables, semantic escape sequences, and documented reload APIs. Excluded: framebuffer, WebGL, Metal, image themes, wallpaper systems, audio/video, terminal skins/chassis, arbitrary hook runners, model-generated configuration, destructive rewrites, and runtime Tinty/Base16 dependencies.

Explicit non-goals:

  • Automatic editor or terminal emulator theme takeover.
  • A long first-run questionnaire.
  • Image/video/audio theming, wallpaper/shader systems, or terminal-emulator implementation.
  • Arbitrary user hook execution or model-generated configuration.
  • Destructive config rewriting or Git config changes without explicit user request.
  • Requiring Tinty/Base16 at runtime.
  • Removing Starship or Powerlevel10k compatibility.
  • Recreating every Starship module or shipping a large integration marketplace in the first slice.

UX and detection proposal

Setup Cat may eventually ask one optional question: Extend NMSh appearance to terminal tools? Default: No. If No, nothing changes. If Yes, inspect local factual state and show only detected or relevant integrations.

A later surface may be /theme-bridge, linked from /appearance → Theme Bridge. It can list detected targets (for example fzf, tmux, Neovim, bat, delta, less/man) with Independent as the initial mode. This issue documents intended UX; no UI is part of the research/design step.

Detection must be read-only, local, cached where useful, and make no network request or telemetry call. Distinguish at least: Unsupported, Not installed, Detected, Configured independently, NMSh managed, Conflict, Needs reload, Ready. Define precedence and surface conflicts without mutating them.

Architecture direction

Reuse the existing Native theme source and host/tool/config abstractions. First document how to resolve one immutable semantic palette snapshot from the active Native theme, including custom themes, family accents, dark/light state, vibrance/chroma interactions, color-depth/NO_COLOR rules, and accessibility constraints.

Likely flow:

active NMSh theme
  -> resolved semantic palette snapshot
  -> enabled adapter + target capabilities/mode
  -> validated target artifact or invocation-scoped environment
  -> atomic managed-file apply when needed
  -> typed, supported reload action when enabled

An adapter boundary may need operations equivalent to detection, supported modes, rendering, validation, ownership/provenance, application, and typed reload. This is a design hypothesis, not a mandate to create another framework. Compare with existing provider, host capability/action, configuration, and tool adapter abstractions first.

Use per-target mappings from NMSh roles to roles actually supported by the target. Base16/Base24/Tinted is an import/export/interchange mapping, never NMSh's internal source of truth. Tinty is reference only and is not required at runtime.

Managed output should follow established NMSh data/config path conventions; inspect path helpers before choosing a final path. Prefer generated NMSh-owned files over repeatedly editing user config. Track artifact paths, integration id/version, exact include or marker NMSh inserted, expected content/hash where useful, and safe removal plans. Removal may remove only a verified NMSh-owned include; never delete user config.

Evaluate transactional generation: resolve palette; render enabled artifacts into staging; validate all; atomically replace the NMSh-managed artifact set; then invoke only typed adapter-owned reload actions. A failed reload must not corrupt other outputs or roll back the active NMSh theme. Report partial failure truthfully. Never execute arbitrary user hooks.

Theme changes should use pure mappings, cached detection, atomic writes only for enabled file-based adapters, and targeted reloads. No permanent polling, heavyweight process fan-out, network, or AI.

Integration matrix

Target First strategy Config mutation Priority
fzf Pass colors to each NMSh-owned invocation None High
less/man Scoped pager/color environment where supported None High
LS_COLORS consumers vivid-derived output if present; small safe fallback otherwise Shell environment only High
bat BAT_THEME mapping, later generated tmTheme research None initially Medium
delta Runtime/environment settings coordinated with bat None initially Medium
tmux NMSh-managed fragment and one confirmed include; targeted reload Yes, opt-in Later
Neovim Managed colorscheme loaded by opted-in new instances Yes, opt-in Later
Vim Vim-compatible managed colorscheme for opted-in new instances Yes, opt-in Later
Ghostty / Kitty Host/capability recognition only; never set base palette Never for base theme Excluded target
Zed / VS Code No editor theme changes Never Excluded target

fzf

High priority and low risk. When NMSh itself launches fzf, inject supported --color roles for that invocation only: foreground/background, selected foreground/background, highlights, prompt, pointer, marker, border, spinner, info, and other currently supported roles. Preserve caller options and define precedence deliberately. Do not write FZF_DEFAULT_OPTS, edit shell rc, or alter unrelated fzf invocations. Investigate picker/provider launch plumbing so the adapter reaches the right launches.

less / man

Theme only supported controls in the detected pager/man pipeline. Research LESS_TERMCAP_*, current less color options, MANPAGER/pager behavior, and passthrough constraints. Scope environment to the NMSh-managed shell where possible. Do not edit .zshrc to color man pages, claim syntax-editor features for less, or assume OSC 8 is a pager feature.

LS_COLORS and file-listing tools

Research vivid's theme formats, mappings, and supported consumers (ls, tree, fd, bfs, dust, others). Prefer vivid when present or compatible generated output. Without it, implement a deliberately small safe LS_COLORS fallback rather than recreating a large extension database. This is shell environment behavior, not host color mutation.

bat

Research BAT_THEME, built-in dark/light selection, generated .tmTheme support, theme-cache requirements, and reload behavior. First slice may map an NMSh theme to a built-in bat theme; generated syntax colors can come later. Avoid global bat config edits.

delta

Research delta themes/syntax settings, relationship with bat/BAT_THEME, DELTA_FEATURES, config layering, and environment/runtime overrides. Prefer scoped runtime behavior; never modify ~/.gitconfig without explicit user request/confirmation.

tmux

Opt-in only. Prefer an NMSh-owned fragment under the inspected NMSh data directory covering status style, window status, pane borders, and message style. Do not alter keybindings, layouts, plugins, commands, shell, or behavior; do not blindly replace a theme/plugin. Detect conflicts. If one permanent include is needed, show its exact patch and use verified config editing. Follow NMSh may regenerate and source the fragment in active sessions only through a supported targeted mechanism. Choose theme stays pinned. A failed reload must not corrupt files or the NMSh theme.

Neovim and Vim

Opt-in only. Research official highlight/colorscheme APIs and existing Tinted/Base16 implementations for syntax, Tree-sitter, LSP diagnostics, and common UI groups. Generate NMSh-owned colorscheme artifacts loaded only by opted-in launches; never overwrite the user's current colorscheme. Cover Normal, Comment, String, Number, Keyword, Function, Type, Operator, Visual, CursorLine, Pmenu/PmenuSel, StatusLine, separators, diagnostics, and common Tree-sitter captures where supported. Account for Vim/Neovim differences. Do not claim an already-running editor updates live without explicit supported RPC/socket ownership of that process. Follow applies to future launches and artifact updates; Choose stays pinned.

Terminal emulators and editors

Ghostty/Kitty may be identified for capability/status but their terminal base themes are outside this adapter set. Cursor shader/effect integration is separate work. Zed and VS Code editor themes are excluded; their integrated terminals may still host NMSh and scoped tools normally.

Semantic terminal integration

This is host cooperation, not theming. NMSh's transcript and behavior remain authoritative; host support adds convenience only. Test through the host capability boundary and multiplexer passthrough rules.

  • OSC 133: map NMSh's known prompt, input/command start, output, and completion/status boundaries to the subset and lifecycle expected by Ghostty, Kitty, WezTerm, Windows Terminal, and applicable iTerm-compatible hosts. Compare with private OSC 777 and avoid duplicate or contradictory markers. Handle interrupted commands, multiline input, passthrough/fullscreen apps, shell handoff, and status. NMSh must not depend on host support.
  • OSC 7: emit factual current working directory as a correctly encoded file URI at safe lifecycle points where host/policy permits. Consider remote/SSH and mux behavior. Do not expose arbitrary filesystem data.
  • OSC 8: complete authored NMSh links for documentation, localhost dev servers, GitHub issues/PRs, and safely represented explicit file links. Never reinterpret arbitrary PTY output as trusted links; raw shell output remains raw.
  • Host title/signature: optionally render sanitized, bounded session identity such as “Mango · notMyShell” or “Plum · website” with OSC 0/2. Respect foreground program title ownership, avoid alternate-screen fights, and restore NMSh identity only when ownership returns. Inspect current signature/title state first.

Contextual shell and transcript work in this cooperation pass

These are related, deterministic improvements. Audit existing behavior before proposing duplicate work; they need not ship alongside an adapter.

  • Transient historical prompt: presentation-only Full / Compact / Minimal option. Compact may retain project, branch, and prompt marker; Minimal a small marker/context. Keep full stored semantic snapshots. Check Block Seal, Chat, sticky headers, search, right context, resize, and /copy. Never mutate shell/session history.
  • Context-aware history: Atuin and similar systems are references. Audit the existing bounded local ranking first; the current v0.16 stack already ranks history by context. Consider same repository/project/cwd, successful/failed exit, frequency, recency, session, and shell only when factual and privacy-safe. No AI, secrets, or arbitrary environment capture.
  • Command-not-found recovery: build on actual post-execution failure evidence, existing deterministic typo correction, local executable catalog, and factual package mappings. Do not intercept before execution, replace shell output, or invent package names. Install uses normal explicit confirmation.
  • Environment awareness: audit existing passive mise/project awareness and investigate .envrc, .venv, mise.toml, .tool-versions, .nvmrc, pyproject.toml, and package-manager files. Show factual status/actions; never silently source .envrc or execute project files. Respect direnv trust.
  • Open block in pager: safe action for large historical output using the complete stored output and owned temporary/input mechanism. Never interpolate arbitrary output into shell. Coordinate with pager bridge.
  • Session title/signature: obey host ownership constraints and existing session identity lifecycle.

Future scope clarification — Native imports and host cooperation

Planned for v0.18 / this tracker in focused slices; this does not expand v0.17 Compatibility & Discovery. Shared shell/plugin inventory and richer module integration belong to #305, planned for v0.19.

Product ownership

NMSh remains a terminal frontend → real persistent shell → CLI/TUI programs, hosted by Ghostty, Kitty, WezTerm, iTerm2, Terminal.app, Windows Terminal, or Zed/VS Code integrated terminals. Learn from mature hosts' interoperable protocols, without absorbing GPU/font rendering, native window chrome, framebuffer ownership, emulator-native panes/tabs, host scrollback storage, shaders/background images, native SSH/mux implementation, or terminal renderer implementation. NMSh's owned transcript remains distinct from host scrollback.

NMSh Native is recommended/default, provides the deepest integration, and owns its semantic roles, modules, and imported themes. Starship, Powerlevel10k, and a possible future Oh My Posh provider are compatibility paths. Shell frameworks are detected/interoperated with in the real shell, not replaced wholesale. Terminal hosts are capability/protocol partners, not owners of NMSh theme rendering or runtime.

Preferred theme destination: NMSh Native

The preferred workflow is import compatible external theme → translate into NMSh semantic roles → preview → save as an NMSh Native custom theme → render natively thereafter. Keeping an external theme engine permanently responsible for appearance is a secondary compatibility choice. Reuse the existing Native custom-theme model; do not create another theme system.

Extend the existing Theme Studio / /theme Import surface (or its current equivalent): NMSh Theme JSON, Base16/Base24, Windows Terminal palette, Oh My Posh, and subsequently researched safe declarative host palette formats. Existing interchange requirements remain in force.

Oh My Posh → Native import

Oh My Posh is a prompt/theme engine, not a shell framework. It is a high-value structured import source, distinct from the optional installed-OMP rendering provider tracked in #305. Prefer Native import whenever safe deterministic mapping is possible.

  • Read a user-selected local JSON, YAML, or TOML config (.omp.json or documented equivalent). Research/recheck current documented formats and local interfaces before implementation; define supported schema/config versions and bounded parsing.
  • Parse declarative palette, literal colors, and supported block/segment appearance facts; map them into NMSh semantic roles. Do not run OMP, templates, segment commands, or shell code merely to extract appearance.
  • Preview using NMSh rendering, explicitly list approximations/omissions, and save a normal Native custom theme only after confirmation. Unsupported dynamic templates, layouts, segment behavior, or other concepts with no NMSh equivalent must not be represented as perfect conversion.
  • No silent downloads, remote inheritance/schema/theme fetching, mutable upstream theme URL at runtime, or OMP runtime dependency after import. Define conservative handling of extends: unsupported/remote references are disclosed; any supported local inheritance is explicitly selected/approved and bounded for depth, cycles, paths, and size.
  • Preserve useful provenance (importedFrom, source type, original config/theme name, import version) without a runtime dependency. Import copies/maps supported appearance; it does not activate external prompt behavior or enable Native modules automatically.

Official research references checked for this clarification: configuration formats, blocks/segments and inheritance, local configuration/export workflow, palette/color references, and templates. The docs describe JSON/YAML/TOML, local config paths and export, literal/palette colors plus dynamic templates, and local/remote inheritance. These interfaces are research inputs; rendering/export/template execution is not the import algorithm.

Declarative terminal theme imports

Research Ghostty palette/theme files, Kitty theme/conf fragments, iTerm2 color schemes, and WezTerm declarative exported color schemes. Support only documented, safely parseable palette subsets; explicitly ignore/reject unrelated settings, executable directives, unsafe includes, and unsupported fields. Never evaluate arbitrary WezTerm Lua, shell code, or user program configuration to obtain colors. A safe exported scheme may be imported even when the host's general configuration is executable.

Import means copying/mapping a palette into NMSh Native, not taking ownership of the terminal emulator's theme. Host base themes stay user-owned; Theme Bridge remains opt-in.

Oh My Zsh theme boundary

Oh My Zsh is a shell framework loaded into real zsh, not a theme-engine service or daemon/API. Its .zsh-theme files are executable zsh code. Do not promise arbitrary automatic or lossless conversion; never source unknown theme scripts to extract colors, execute them in Theme Studio, or pretend arbitrary shell code is declarative.

Support factual framework/theme detection (for example Oh My Zsh / robbyrussell) through #305's shared facts. Compatibility rendering is eligible only where an existing safe isolated-provider mechanism genuinely supports that specific configuration. Native import is limited to safely deterministic declarative data; individually audited adapters for well-known themes may be considered separately, without making arbitrary script translation the general design.

Additional host cooperation acceptance criteria

The existing OSC 133, factual OSC 7, complete safe OSC 8, and foreground-aware session/window-title requirements above remain authoritative; do not duplicate their implementation.

  • Preserve Kitty keyboard protocol compatibility through NMSh editor ownership, negotiation and terminal-mode restoration. Do not re-enable competing ZLE UI.
  • Audit/reuse existing image paths for Kitty graphics and iTerm2 inline images, including WezTerm/iTerm-compatible behavior and mux/passthrough limitations. This is protocol interoperability, not image theming or framebuffer/renderer ownership. Do not rebuild already-supported image features.
  • Keep behavior capability-driven behind the host boundary. Host-specific new-window helpers may be offered only where supported through optional host actions; they do not imply owning native panes/tabs/windows or SSH/mux infrastructure.
  • Unsupported/embedded terminals must degrade transparently to supported text/input behavior. No host brand may become a structural core dependency. Cover Ghostty, Kitty, WezTerm and iTerm2 protocol ideas while preserving Terminal.app, Windows Terminal and integrated/unknown-host baselines.

Tracker boundary and verification

#304 owns theme import, Native appearance translation, Theme Bridge target adapters and semantic terminal cooperation. #305 owns shared bounded shell/framework/plugin/CLI facts, surface-ownership metadata, module probes and any optional OMP provider. #304 consumes those facts for detection/status instead of building a second inventory. OMP provider selection and Native theme import remain separate choices.

Future acceptance evidence must include local import fixtures (malformed/unsupported input, lossy mapping, confirmation, no execution/network/runtime dependency), capability fallback/protocol tests, and separate physical terminal validation where relevant. This clarification authorizes no implementation or v0.17 scope change.

Native prompt vs compatibility providers

  • NMSh Native: recommended/default provider for deep NMSh integration and theme-aware prompt roles.
  • Starship: compatibility provider for existing configurations and its broader module ecosystem.
  • Powerlevel10k: compatibility provider for existing users/configurations.

This does not make Starship obsolete globally. NMSh need not reproduce every Starship module. Gruvbox, Catppuccin, Tokyo Night, and similar palettes are broad theme families, not inherently Starship themes; NMSh can maintain native mappings and interpretations.

Upstream research and provenance

Use official docs and canonical repositories. Record exact repository, file/component/revision, license for the component (not just repository badge), whether reuse is compatible with NMSh's GPL-3.0-only license, inspiration-only status, and attribution/notice obligations. These initial notes are not permission to copy. Recheck the revision actually used. Theme values/templates may have separate provenance. No upstream code is copied by this issue.

Project/reference What to learn Initial license/provenance note
tinty Scheme/template/apply flow; staging and hooks after generation Repository declares GPL-3.0; likely compatible only after file/revision and notice review. Inspiration; no runtime dependency.
tinted-theming/home Base16/Base24/Tinted specs and template conventions Verify current repository/component license and generated-data provenance before reuse; prefer specification/inspiration.
tinted-theming/schemes Scheme metadata and palette formats Verify repository and individual scheme license/copyright; do not infer data license from tooling.
tinted-tmux tmux roles and fragments Repository currently identifies MIT; inspect template and palette provenance separately; attribution required for adapted MIT material.
tinted-fzf Invocation/environment role mapping and generated templates Repository currently identifies MIT; inspect templates and theme provenance separately.
tinted-nvim Base16/Base24 to Neovim, Tree-sitter and LSP groups Repository points to a LICENSE; confirm current license text and exact files before reuse.
vivid LS_COLORS generation and file-type database strategy Verify current dual-license terms and database provenance; prefer optional tool use over copying its database.
fzf Official --color controls and invocation model MIT; docs reference does not imply code reuse.
bat BAT_THEME, built-ins, .tmTheme, cache MIT OR Apache-2.0; verify theme assets individually.
delta Theme, syntax and Git config/environment controls Verify current repo and bundled theme licenses/revision; prefer documented runtime interface.
Starship Provider positioning and module breadth ISC; compatibility/inspiration research.
Powerlevel10k Existing user compatibility and transient prompt MIT at repository level; inspect dependencies/assets separately.
Atuin Local/contextual history UX and ranking Verify current license and relevant component; inspiration only.
Ghostty integration, OSC docs OSC 7/133 semantics, lifecycle, host behavior Check current license and each shell integration source at target revision.
Kitty integration, docs OSC support and host-specific shell behavior Kitty project is GPL-3.0-or-later; verify files and compatibility implications before adaptation.
WezTerm integration OSC 7/133 and mux passthrough patterns Verify current license files and exact script provenance; scanners may not identify repository license uniformly.
direnv Explicit trust model for project environment MIT; do not duplicate trust/activation behavior.
Neovim docs, highlight docs, Vim help Official highlight and colorscheme APIs Docs reference; generated artifact format and any source still need license review.
Crush UX and semantic-theme ideas only Review current source license at examined revision; inspiration-only until compatibility is established. Do not copy/adapt source.
Warp Licensing/provenance reference and example of a modern terminal project with mixed open/proprietary architecture Most client code is AGPL v3; warpui_core and warpui crates are MIT. The server, Warp Drive backend, hosted authentication, and Oz orchestration are outside this repo and proprietary today. AGPL client is source-reference/inspiration-only; MIT crates are audit-only if a relevant low-level detail emerges.

Also consult fzf doc/fzf.txt; current less/man docs; vivid, bat and delta docs; tmux style/config docs; official Neovim/Vim help; and primary terminal-host OSC references. OSC support varies by host/version and through multiplexers; record versions and primary sources.

Suggested phases

Phase 0 — architecture/research

  • Audit resolved Native theme data and color modifiers.
  • Define adapter boundaries using existing abstractions where suitable.
  • Define capability/detection states and mode persistence.
  • Choose managed path using NMSh path helpers.
  • Define provenance, exact include mutation/removal, validation, staging, atomic replacement, typed reloads, and partial failure.
  • Research Base16/Base24/Tinted interoperability without changing NMSh's semantic source model.
  • Research target capabilities, environment scope, conflict behavior, and licensing.
  • Add deterministic fixtures for adapter output and config-edit plans.

Phase 1 — low-mutation adapters

  • fzf invocation-only colors.
  • less/man scoped environment.
  • LS_COLORS via vivid if available, small fallback otherwise.
  • bat mapping and custom-theme feasibility.
  • delta runtime/environment mapping coordinated with bat.

Phase 2 — terminal semantic protocols

  • host-aware OSC 7 cwd.
  • OSC 133 command-zone lifecycle.
  • structured authored OSC 8 links and transcript preservation.
  • capability, passthrough, mux, and unsupported-host behavior.

Phase 3 — managed-config adapters

  • tmux fragment, exact confirmed include, conflict detection, supported reload.
  • Neovim generated colorscheme and opted-in future launches.
  • Vim generated colorscheme using supported APIs.
  • transactional generation, ownership ledger, safe removal, partial reload reporting.

Phase 4 — contextual shell/transcript polish

  • transient historical prompt levels.
  • extend context-ranked history only where audit finds a gap.
  • post-failure command-not-found improvements.
  • passive environment awareness improvements.
  • open full historical command block in pager.
  • session signature/title bridge.

Phase ordering may change after Phase 0, while preserving opt-in and ownership boundaries.

Acceptance criteria

  1. Every integration is opt-in.
  2. Independent means zero target-specific NMSh injection or mutation.
  3. Follow NMSh reflects future theme changes within the adapter's supported lifecycle.
  4. Choose theme remains pinned when the main NMSh theme changes.
  5. User configs, editor themes, terminal themes, tmux plugins, and Git config are preserved.
  6. Permanent config edits use verified inspect/plan/preview/apply, show exact path/diff, and require explicit confirmation.
  7. Managed artifacts are clearly NMSh-owned, validated, safely replaceable, and safely removable without deleting user files.
  8. No editor or terminal emulator base-theme takeover.
  9. NMSh works normally with all integrations disabled or unsupported.
  10. Host semantic escapes improve capable hosts but are never required for NMSh correctness.
  11. Existing NO_COLOR, color-depth, safe-glyph, and accessibility behavior remains respected.
  12. No Local Understanding or AI model is required.
  13. A failed adapter/reload does not roll back NMSh's active theme or leave half-valid artifacts; partial success is reported accurately.
  14. Theme switching does not cause broad process fan-out, network calls, or permanent polling.
  15. Physical terminal behavior is validated separately on relevant hosts/multiplexers; automated tests are not reported as physical QA.

Work checklist

Architecture and research

Adapters

Terminal semantics and identity

Contextual shell/transcript

  • Historical prompt Full/Compact/Minimal presentation-only setting. — v0.18 Theme Studio, Native theme library, Theme Bridge and Prompt None #315
  • Audit/extend local context-ranked history and review privacy.
  • Post-execution command-not-found recovery and factual package mapping.
  • Passive environment awareness and direnv trust boundary.
  • Open complete historical block in pager through safe input/temp handling.

Product, docs, QA

Open research questions

  • What resolved palette snapshot best represents theme family, accent, custom theme, vibrance/chroma, and accessibility without losing useful roles?
  • Which targets can receive colors only for NMSh-owned launches without overriding user flags/config?
  • What precedence applies across fzf flags, environment, provider options, and shell integration?
  • Which less/man controls are portable across macOS/BSD/GNU and current pager versions? Is OSC 8 relevant to pager or only authored links?
  • Does vivid have a stable theme format that NMSh can generate, and which consumers honor the same LS_COLORS dialect?
  • Can bat use generated tmTheme without a cache rebuild, and can delta consume it safely at runtime?
  • What smallest tmux include patch can be added/removed exactly while preserving formatting/comments? How can plugin/theme conflicts be identified?
  • Should editor startup opt-in use a managed include, wrapper/environment selector, or existing supported-tool mechanism?
  • Which OSC 133 subset/lifecycle suits NMSh shell adapters across multiline input, rejection, cancellation, handoff, mux passthrough, and status?
  • Which hosts support OSC 7/133/8 natively versus through shell integration, and how can duplicate signals be avoided?
  • How should structured file links be represented safely across local/remote sessions?
  • What current v0.16 work already covers historical prompts, history ranking, signatures, command-not-found, and mise awareness?
  • Which history facts exist with adequate privacy guarantees? Is new metadata needed?
  • Which package mappings are authoritative and locally factual enough for recovery suggestions?
  • What ownership metadata allows artifact updates/removal across versions without false-positive cleanup?
  • How do transient prompts and compact titles interact with Block Seal, Chat, sticky headers, and copy?
  • Which upstream code/templates/theme data can be reused under GPL-3.0-only with notices, and which should remain inspiration-only?

Upstream resilience / self-containment

NMSh license invariant

NMSh remains GPL-3.0-only.

No dependency, copied implementation, translated/adapted source, bundled component, generated artifact, or vendored code may require changing NMSh's project license or impose AGPL/network-use obligations on NMSh as a whole.

If a desirable feature exists only in source whose reuse would violate this invariant, study public behavior/specifications and implement the concept independently.

Theme Bridge integrations must not depend on an upstream GitHub source repository remaining available to keep an already-supported integration working. Classify dependencies as:

  • Native / vendored NMSh functionality: adapter and required runtime mapping/template/data ship with NMSh where licensing permits.
  • Optional external application integration: an application such as fzf, tmux, Neovim, bat, or delta remains optional; adapter/protocol code ships with NMSh, uses documented local interfaces/config formats, and becomes unavailable gracefully when the application is absent.
  • Optional downloadable component: any future large binary/model/asset requires explicit installation, an exact pinned version, integrity verification, and graceful failure.

For Theme Bridge, do not clone an upstream repository during ordinary install or use, fetch mutable main content at runtime, or require a remote template to render. Pin the exact upstream revision for any adapted compatible template/data, preserve required notices, store the actual adapted/generated runtime material in NMSh, and record provenance. Record tested application versions/capabilities and keep local fixtures for supported config/protocol formats. The disappearance or abandonment of an upstream source repository must not break NMSh core.

Do not vendor entire target applications. A Git submodule is still an external availability dependency; for runtime-critical source/data NMSh must preserve, prefer a local vendored snapshot or subtree where licensing permits.

Warp research note

Canonical Warp repository licensing and its FAQ currently state that the Warp client and most crates are AGPL v3, while warpui_core and warpui are MIT. The server, Warp Drive backend, hosted authentication, and Oz orchestration are outside the open-source client repository and remain proprietary today.

Warp is retained only as a licensing/provenance reference and as an example of a modern terminal project with a mixed open/proprietary architecture. NMSh is not currently planning to copy or emulate Warp-style blocks, completion UX, session/workspace UI, or command-entry behavior. Do not use Warp as a primary product-design source for NMSh. Its AGPL client remains source-reference/inspiration-only under NMSh's current GPL-3.0-only licensing invariant. Under NMSh's current GPL-3.0-only policy, the AGPL client is architecture/behavior reference only. GPLv3 and AGPLv3 provide a compatibility path for combined works, but AGPL network interaction/source-offer requirements can apply to the combined work; including AGPL client code would be a material licensing-policy decision. Do not translate AGPL Rust into TypeScript to avoid source-license obligations. The MIT warpui crates may be audited only if a genuinely relevant low-level implementation detail arises; there is no planned dependency or feature based on them. Credit alone is not license compliance.

Related repository references

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions