CLI Colors

[tony]

Summary

Port vcspull's intuitive color practices into tmuxp CLI, incorporating CPython best practices.

• Add _colors.py module with ColorMode enum and Colors class
• Add global --color flag (auto/always/never) to CLI root parser
• Support NO_COLOR and FORCE_COLOR environment variables (CPython-style)
• Update load.py with semantic colors (info, success, error, highlight, etc.)
• Update ls.py and debug_info.py to use Colors class
• Add comprehensive test suite (25 tests) for color system

Design

The Colors class wraps tmuxp's existing style() function with semantic methods:

• success() - green, for successful operations
• warning() - yellow, for warnings
• error() - red, for errors
• info() - cyan, for informational messages
• highlight() - magenta (bold), for important text
• muted() - blue, for secondary text

Usage

# Automatic color detection (default)
tmuxp load myworkspace

# Force colors on (useful for piping to less -R)
tmuxp --color=always load myworkspace

# Disable colors
tmuxp --color=never load myworkspace

# Environment variables also work
NO_COLOR=1 tmuxp load myworkspace

Test plan

• All 25 new color tests pass
• All 81 existing CLI tests pass
• ruff checks pass
• mypy type checking passes
• Doctests pass

[codecov]

Codecov Report

❌ Patch coverage is 82.74174% with 141 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.11%. Comparing base (df78a17) to head (8b41806).
⚠️ Report is 100 commits behind head on master.

Files with missing lines	Patch %	Lines
src/tmuxp/cli/search.py	74.03%	58 Missing and 16 partials ⚠️
src/tmuxp/_internal/colors.py	84.00%	13 Missing and 11 partials ⚠️
src/tmuxp/cli/ls.py	90.50%	10 Missing and 7 partials ⚠️
src/tmuxp/cli/load.py	72.72%	9 Missing ⚠️
src/tmuxp/cli/import_config.py	71.42%	2 Missing and 2 partials ⚠️
src/tmuxp/cli/debug_info.py	92.68%	2 Missing and 1 partial ⚠️
src/tmuxp/cli/edit.py	50.00%	3 Missing ⚠️
src/tmuxp/_internal/private_path.py	93.54%	1 Missing and 1 partial ⚠️
src/tmuxp/cli/freeze.py	80.00%	1 Missing and 1 partial ⚠️
src/tmuxp/cli/shell.py	87.50%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1006      +/-   ##
==========================================
+ Coverage   77.35%   80.11%   +2.76%     
==========================================
  Files          25       28       +3     
  Lines        1722     2409     +687     
  Branches      328      457     +129     
==========================================
+ Hits         1332     1930     +598     
- Misses        287      356      +69     
- Partials      103      123      +20     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

Found 1 issue:

1. Infinite loop in prompt_choices() on invalid input - The function has a while True: loop (lines 229-238) but no handling when user input doesn't match any valid choice. When input is: (1) not empty, (2) not the default, (3) not in no_choice, and (4) not in choices_, the loop continues silently forever without feedback or re-prompting.

https://github.com/tmux-python/tmuxp/blob/a1ddbd3494131b4bdeebf2e072e1223a3af249a9/src/tmuxp/cli/utils.py#L228-L239

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[tony]

Code review

Found 1 issue:

1. Functions _render_global_workspace_dirs(), _output_flat(), and _output_tree() in ls.py have no doctest examples. CLAUDE.md says "All functions and methods MUST have working doctests."

tmuxp/src/tmuxp/cli/ls.py

Lines 333 to 372 in 72b76f6

	def _render_global_workspace_dirs(
	formatter: OutputFormatter,
	colors: Colors,
	global_dir_candidates: list[dict[str, t.Any]],
	) -> None:
	"""Render global workspace directories section.
	Parameters
	----------
	formatter : OutputFormatter
	Output formatter.
	colors : Colors
	Color manager.
	global_dir_candidates : list[dict[str, Any]]
	List of global workspace directory candidates with metadata.
	"""
	formatter.emit_text("")
	formatter.emit_text(colors.heading("Global workspace directories:"))
	for candidate in global_dir_candidates:
	path = candidate["path"]
	source = candidate.get("source", "")
	source_prefix = f"{source}: " if source else ""
	if candidate["exists"]:
	count = candidate["workspace_count"]
	status = f"{count} workspace{'s' if count != 1 else ''}"
	if candidate["active"]:
	status += ", active"
	formatter.emit_text(
	f" {colors.muted(source_prefix)}{colors.info(path)} "
	f"({colors.success(status)})"
	)
	else:
	formatter.emit_text(
	f" {colors.muted(source_prefix)}{colors.info(path)} ({status})"
	)
	else:
	formatter.emit_text(
	f" {colors.muted(source_prefix)}{colors.info(path)} "
	f"({colors.muted('not found')})"
	)

https://github.com/tmux-python/tmuxp/blob/72b76f632d1bea23142da1c1d55ee44f532bc13e/CLAUDE.md#L99-L101

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[tony]

Code review (fresh)

No issues found. Checked for bugs and AGENTS.md compliance.

Notes: Several potential issues were identified but scored below threshold:

• Missing newline in .tmuxp.json (linter should catch)
• heading()/info() use same color (design choice, not code bug)
• workspace→CLI import dependency (architectural, not a bug)

🤖 Generated with Claude Code

[tony]

Code Review Summary

Review completed - 5 parallel agents examined:

1. CLAUDE.md/AGENTS.md compliance
2. Shallow bug scanning
3. Git history analysis
4. Previous PRs patterns
5. Code comment analysis

Issues Analyzed

Issue	Score	Verdict
Functional tests guideline contradiction	5/100	❌ False positive - tests are already function-based (139 functions, 0 classes)
args=None AttributeError in debug_info.py	15/100	❌ False positive - code safely uses args.color if args else None
RGB validation missing in style()	72/100	⚠️ Valid but low priority - terminals handle gracefully
ls output format breaking change	62/100	⚠️ Documented in CHANGES, JSON changed from array to object
style() bold=False behavior change	25/100	❌ False positive - actually a bug fix (code 22 interfered with dim)

Result

No blocking issues found. All scored below 80 threshold.

The PR is well-structured with proper test coverage and documentation. The output format changes are disclosed in CHANGES.

[tony]

Code review

Found 1 issue:

1. Inconsistent color semantics in search.py vs ls.py (CLAUDE.md says "L1 Primary content = highlight() for Workspace names" and "L2 Supplementary info = info() for Paths")

In search.py, workspace names use colors.info() and paths use colors.muted(), but ls.py correctly uses colors.highlight() for names and colors.info() for paths per the documented hierarchy.

tmuxp/src/tmuxp/cli/search.py

Lines 986 to 989 in 945a6cb

	name_display = highlight_matches(fields["name"], patterns, colors=colors)
	path_info = f" {colors.muted(fields['path'])}" if show_path else ""
	formatter.emit_text(f" {colors.info(name_display)}{path_info}")

Compare with the correct implementation in ls.py:

tmuxp/src/tmuxp/cli/ls.py

Lines 438 to 441 in 945a6cb

	formatter.emit(ws)
	path_info = f" {colors.info(ws['path'])}" if show_path else ""
	formatter.emit_text(f" {colors.highlight(ws['name'])}{path_info}")

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}