feat(cli): add copaw health command for system diagnostics

[Zhangfengmo]

Summary

Add copaw health command that performs comprehensive system health checks and configuration validation, helping users quickly diagnose setup issues.

Changes

• src/copaw/config/health.py — HealthChecker with 10 system checks:

  • Config files existence
  • LLM provider configuration and optional connection test
  • Skills directory availability
  • Python dependencies
  • Environment tools (git, node, etc.)
  • Disk space
  • Channel credentials completeness
  • MCP client reachability
  • Required files (AGENTS.md, etc.)
  • Directory permissions

• src/copaw/config/validator.py — ConfigValidator for semantic validation of config.json:

  • Channel configuration checks
  • MCP client transport/URL/command validation
  • Agent settings bounds checking

• src/copaw/cli/health_cmd.py — CLI command with human-readable and JSON output

• src/copaw/cli/main.py — Register health command

• src/copaw/cli/init_cmd.py — Run health check automatically after copaw init

Usage

# Basic health check
copaw health

# Verbose output with details
copaw health --verbose

# JSON output for scripting
copaw health --json

Example Output

🐾 CoPaw System Health Check

✅ config:       Config file exists
✅ providers:    Active LLM: claude-sonnet / claude-sonnet-4-6
⚠️  skills:      No skills directory found
  → Create ~/.copaw/skills/ to add custom skills
✅ dependencies: All required packages installed
...

Overall: HEALTHY (9 passed, 1 warning, 0 errors)

Test Plan

• copaw health — basic output
• copaw health --verbose — detailed output
• copaw health --json | python -m json.tool — valid JSON
• pre-commit (black, flake8, pylint, mypy) — all pass

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the diagnostic capabilities of the CoPaw CLI by introducing a dedicated health command. It allows users to quickly identify and troubleshoot common setup and configuration issues, ensuring a smoother initial experience and easier maintenance. The new command provides detailed insights into various system components and configurations, offering clear suggestions for resolving any detected problems.

Highlights

• New copaw health CLI Command: Introduced a new command-line interface command, copaw health, to perform comprehensive system health checks and configuration validation. This command supports human-readable output, verbose details, and JSON output for scripting.
• Comprehensive System Health Checks: Implemented a HealthChecker class that performs 10 distinct system checks, including configuration file existence, LLM provider setup and connection testing, skills directory availability, Python dependencies, environment tools, disk space, channel credentials, MCP client reachability, required files, and directory permissions.
• Semantic Configuration Validation: Added a ConfigValidator class responsible for semantically validating the config.json file. This includes checks for channel configurations, MCP client settings (transport, URL, command), and agent settings like max_iters and max_input_length.
• Automated Health Check on Initialization: Integrated an automatic health check to run immediately after the copaw init command completes, providing instant feedback on the system's setup status to the user.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/copaw/cli/health_cmd.py
  • Added the health_cmd function, implementing the new copaw health CLI command.
  • Included logic for displaying health check results in both human-readable and JSON formats.
  • Defined helper functions _print_checks and _print_validation for formatted output.
• src/copaw/cli/init_cmd.py
  • Modified the init_cmd to automatically run a system health check after successful initialization.
  • Added logic to display a summary of the health check results, including next steps or error messages.
• src/copaw/cli/main.py
  • Imported the new health_cmd from health_cmd.py.
  • Registered health_cmd with the main CLI application, making it accessible via copaw health.
• src/copaw/config/health.py
  • Added the HealthChecker class to encapsulate all system health check logic.
  • Defined HealthStatus, HealthCheckResult, and SystemHealth data structures for consistent reporting.
  • Implemented various checks for config files, LLM providers, skills, dependencies, environment, disk space, channels, MCP clients, required files, and permissions.
• src/copaw/config/utils.py
  • Updated import statements for Config related classes.
  • Modified load_config to assign the result of Config.model_validate(data) to a variable before returning.
• src/copaw/config/validator.py
  • Added the ConfigValidator class for semantic validation of the config.json file.
  • Defined ValidationLevel, ValidationIssue, and ValidationResult data structures for structured validation reporting.
  • Implemented validation methods for channels (DingTalk, Feishu, QQ, Discord, Telegram), MCP clients, agent settings, and heartbeat configuration.

Activity

• The author, Zhangfengmo, implemented a new copaw health command.
• The health command was tested for basic output, verbose output, and valid JSON output.
• Pre-commit hooks (black, flake8, pylint, mypy) were run and passed, ensuring code quality.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable copaw health command for system diagnostics, which is a great addition for user support and debugging. The implementation is comprehensive, covering a wide range of system checks and configuration validations. My review focuses on improving the efficiency of the health checks by avoiding redundant operations and enhancing code maintainability with better type hinting. The core logic is sound, and these changes will make the new feature more robust and performant.

[Zhangfengmo]

🔍 Self Code Review — Findings & Fixes Applied

Summary

Three specialized review agents (code-reviewer, silent-failure-hunter, pr-test-analyzer) analyzed this PR. All critical and important issues have been addressed in the latest commit (11a6f81).

Fixes Applied

✅ Critical Issues (all resolved)

• health.py — Added logger.exception() to all broad except blocks (check_config_files, check_providers, check_channels, check_mcp_clients) so full tracebacks are preserved in logs
• health.py — Changed check_providers, check_channels, check_mcp_clients failure status from DEGRADED → UNHEALTHY for accurate severity
• health.py:428 — Added timeout=30 to future.result() to prevent indefinite hang when LLM endpoint is unreachable
• health_cmd.py — Wrapped ConfigValidator() construction in try/except to show user-friendly error instead of raw Python traceback

✅ Important Issues (all resolved)

• health.py — Narrowed check_disk_space to catch OSError only instead of broad Exception
• health_cmd.py — Added if issue.suggestion guard for errors display branch (consistent with warnings branch)
• utils.py — Removed redundant config = ...; return config variable assignment

Known Limitations (out of scope for this PR)

⚠️ No test coverage

The PR adds ~1,100 lines of production code with zero tests. This is the largest gap. Key behaviors to test in a follow-up:

• _safe_check isolation (one failing check must not abort others)
• check_all status aggregation priority (UNHEALTHY > DEGRADED > HEALTHY)
• _validate_channels credential detection per channel type
• JSON output schema stability

⚠️ Duplicate display logic

init_cmd.py duplicates the health check display loop from health_cmd.py. Should be extracted to a shared helper in a follow-up.

⚠️ Triple config load

check_channels, check_mcp_clients, and health_cmd each call load_config() + validate_all() independently. Minor inefficiency, safe to refactor later.

---

Self-reviewed by Claude • Ready for human review