claude-mpm 4.16.0__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/cli/README.md

@@ -0,0 +1,253 @@
+# Claude MPM CLI Architecture
+
+This document describes the refactored CLI architecture for claude-mpm.
+
+## Overview
+
+The CLI has been refactored from a single monolithic `cli.py` file into a modular structure that improves maintainability and code organization.
+
+## Directory Structure
+
+```
+cli/
+├── __init__.py       # Main entry point - orchestrates the CLI flow
+├── parser.py         # Argument parsing logic - single source of truth for CLI arguments
+├── utils.py          # Shared utility functions
+├── commands/         # Individual command implementations
+│   ├── __init__.py
+│   ├── run.py        # Default command - runs Claude sessions
+│   ├── tickets.py    # Comprehensive ticket management commands
+│   ├── info.py       # Shows system information
+│   ├── agents.py     # Manages agent deployments
+│   ├── memory.py     # Agent memory management
+│   ├── monitor.py    # System monitoring
+│   ├── config.py     # Configuration management
+│   └── aggregate.py  # Event aggregation
+└── README.md         # This file
+```
+
+## Key Design Decisions
+
+### 1. Modular Command Structure
+Each command is implemented in its own module under `commands/`. This makes it easy to:
+- Add new commands without touching existing code
+- Test commands in isolation
+- Understand what each command does
+
+### 2. Centralized Argument Parsing
+All argument definitions are in `parser.py`. This provides:
+- Single source of truth for CLI arguments
+- Reusable argument groups (common arguments, run arguments)
+- Clear separation of parsing from execution
+
+### 3. Shared Utilities
+Common functions are in `utils.py`:
+- `get_user_input()` - Handles input from files, stdin, or command line
+- `get_agent_versions_display()` - Formats agent version information
+- `setup_logging()` - Configures logging based on arguments
+- `ensure_directories()` - Creates required directories on first run
+
+### 4. Backward Compatibility
+The refactoring maintains full backward compatibility:
+- `__main__.py` still imports from `claude_mpm.cli`
+- The main `cli/__init__.py` exports the same `main()` function
+- All existing commands and arguments work exactly as before
+
+## Entry Points
+
+1. **Package execution**: `python -m claude_mpm`
+   - Uses `__main__.py` which imports from `cli/__init__.py`
+
+2. **Direct import**: `from claude_mpm.cli import main`
+   - Imports the main function from `cli/__init__.py`
+
+3. **Shell script**: `claude-mpm` command
+   - Calls `python -m claude_mpm` with proper environment setup
+
+## Adding New Commands
+
+To add a new command:
+
+1. Create a new module in `commands/`:
+```python
+# commands/mycommand.py
+def my_command(args):
+    """Execute my command."""
+    # Implementation here
+```
+
+2. Add the command to `commands/__init__.py`:
+```python
+from .mycommand import my_command
+```
+
+3. Add parser configuration in `parser.py`:
+```python
+# In create_parser()
+mycommand_parser = subparsers.add_parser(
+    "mycommand",
+    help="Description of my command"
+)
+# Add command-specific arguments
+```
+
+4. Add the command mapping in `cli/__init__.py`:
+```python
+# In _execute_command()
+command_map = {
+    # ... existing commands ...
+    "mycommand": my_command,
+}
+```
+
+## Command Reference
+
+### Core Commands
+
+**`run`** - Execute Claude sessions (default command)
+- Interactive and non-interactive modes
+- Hook service integration
+- Agent selection and deployment
+- Custom input processing
+
+**`tickets`** - Comprehensive ticket management system
+- Full CRUD operations for tickets
+- Hierarchical ticket organization (Epics → Issues → Tasks)
+- Search and filtering capabilities
+- Workflow state management
+- Integration with ai-trackdown-pytools
+
+**`agents`** - Manage agent deployments
+- List available agents by tier (PROJECT > USER > SYSTEM)
+- Deploy agents to Claude Code compatibility format
+- Validate agent configurations
+- Clean up deployment artifacts
+
+**`info`** - Display system information
+- Version details and environment status
+- Configuration validation
+- Agent availability and status
+- System health checks
+
+### Ticket Management Commands
+
+The `tickets` command provides a complete ticketing solution with the following subcommands:
+
+#### Core Ticket Operations
+- **`create`** - Create new tickets with proper classification
+  - Support for epics, issues, tasks, bugs, and features
+  - Priority assignment and hierarchical linking
+  - Tag management and assignee support
+  - Automatic ID generation and metadata
+
+- **`list`** - Display recent tickets with filtering
+  - Type and status filtering
+  - Configurable result limits
+  - Verbose mode for detailed information
+  - Visual status indicators with emoji
+
+- **`view`** - Show detailed ticket information
+  - Complete ticket metadata and description
+  - Parent/child relationship display
+  - Assignment and tag information
+  - Creation and update timestamps
+
+- **`update`** - Modify ticket properties
+  - Status and priority changes
+  - Description and tag updates
+  - Assignment management
+  - Fallback to aitrackdown CLI for complex operations
+
+#### Advanced Ticket Operations
+- **`search`** - Find tickets by content
+  - Full-text search in titles, descriptions, and tags
+  - Type and status filtering
+  - Context snippets for relevant matches
+  - Configurable result limits
+
+- **`close`** - Mark tickets as completed
+  - Resolution reason capture
+  - Automatic status transition
+  - Comment integration for closure notes
+
+- **`delete`** - Remove tickets permanently
+  - Confirmation prompts for safety
+  - Force option for batch operations
+  - Integration with aitrackdown cleanup
+
+- **`comment`** - Add discussion to tickets
+  - Progress updates and technical notes
+  - Team communication and coordination
+  - Rich text support through aitrackdown
+
+- **`workflow`** - Manage workflow states
+  - State transition validation
+  - Comment integration for change reasons
+  - Status mapping to aitrackdown workflow
+
+#### Ticket System Features
+
+**Hierarchical Organization:**
+```
+Epic (Strategic Level)      - EP-XXXX
+├── Issue (Feature Level)   - ISS-XXXX
+│   ├── Task (Implementation) - TSK-XXXX
+│   └── Task (Implementation) - TSK-XXXX
+└── Issue (Feature Level)   - ISS-XXXX
+    └── Task (Implementation) - TSK-XXXX
+```
+
+**Status Management:**
+- `open` - Ready to start work
+- `in_progress` - Currently being developed
+- `blocked` - Cannot proceed due to dependencies
+- `ready` - Awaiting review or testing
+- `tested` - QA approved
+- `done` - Completed successfully
+- `closed` - Finalized (completed or cancelled)
+
+**Priority Levels:**
+- `critical` (P0) - System down, data loss, security breach
+- `high` (P1) - Major feature broken, significant user impact
+- `medium` (P2) - Minor issues, workarounds available
+- `low` (P3) - Cosmetic issues, convenience features
+
+**Integration Points:**
+- **ai-trackdown-pytools**: Backend storage and advanced operations
+- **TicketManager**: Primary interface for ticket operations
+- **Claude Sessions**: Automatic ticket creation from patterns
+- **Hook System**: Event-driven ticket updates and notifications
+
+### Additional Management Commands
+
+**`memory`** - Agent memory system management
+- Initialize and configure agent memory
+- View and optimize memory stores
+- Cross-reference management
+- Memory routing and building
+
+**`monitor`** - System monitoring and health
+- Start/stop/restart monitoring services
+- Port management and status checks
+- Performance metrics and alerts
+
+**`config`** - Configuration management
+- Validate system configuration
+- View current settings
+- Status reporting and diagnostics
+
+**`aggregate`** - Event aggregation system
+- Session management and tracking
+- Event export and analysis
+- Historical data management
+
+## Removed Files
+
+- `cli_main.py` - Redundant entry point, functionality moved to `__main__.py`
+- Original `cli.py` - Split into the modular structure described above
+
+## Preserved Files
+
+- `cli_enhancements.py` - Experimental Click-based CLI with enhanced features
+  - Kept for reference and future enhancement ideas
+  - Not currently used in production

claude_mpm/cli/__init__.py

@@ -31,6 +31,7 @@ from .startup import (
     setup_mcp_server_logging,
     should_skip_background_services,
 )
+from .startup_display import display_startup_banner, should_show_banner
 from .utils import ensure_directories, setup_logging
 
 # Version resolution
@@ -65,10 +66,19 @@ def main(argv: Optional[list] = None):
 
     setup_configure_command_environment(args)
 
+    # CRITICAL: Setup logging BEFORE any initialization that creates loggers
+    # This ensures that ensure_directories() and run_background_services()
+    # respect the user's logging preference (default: OFF)
+    logger = setup_mcp_server_logging(args)
+
     ensure_directories()
     if not should_skip_background_services(args, processed_argv):
         run_background_services()
-    logger = setup_mcp_server_logging(args)
+
+    # Display startup banner (unless help/version/utility commands)
+    if should_show_banner(args):
+        logging_level = getattr(args, "logging", "OFF")
+        display_startup_banner(__version__, logging_level)
 
     if hasattr(args, "debug") and args.debug:
         logger.debug(f"Command: {args.command}")

claude_mpm/cli/commands/__init__.py

@@ -20,6 +20,7 @@ from .mcp import manage_mcp
 from .memory import manage_memory
 from .monitor import manage_monitor
 from .run import run_session
+from .skills import manage_skills
 from .tickets import list_tickets, manage_tickets
 
 __all__ = [
@@ -36,6 +37,7 @@ __all__ = [
     "manage_mcp",
     "manage_memory",
     "manage_monitor",
+    "manage_skills",
     # 'run_guarded_session',  # Excluded from default exports (experimental)
     "manage_tickets",
     "run_doctor",

claude_mpm/cli/commands/aggregate.py

@@ -365,7 +365,7 @@ def view_command_legacy(args):
             print(f"   Tools: {len(delegation.tool_operations)}")
             print(f"   Files: {len(delegation.file_changes)}")
             if delegation.duration_ms:
-                print(f"   Duration: {delegation.duration_ms/1000:.1f}s")
+                print(f"   Duration: {delegation.duration_ms / 1000:.1f}s")
             print(f"   Status: {'✅ Success' if delegation.success else '❌ Failed'}")
             if delegation.error:
                 print(f"   Error: {delegation.error}")

claude_mpm/cli/commands/analyze.py

@@ -350,7 +350,7 @@ class AnalyzeCommand(BaseCommand):
 
         for i, match in enumerate(matches):
             # Try to extract title from preceding line
-            title = f"diagram_{i+1}"
+            title = f"diagram_{i + 1}"
 
             # Look for a title pattern before the diagram
             title_pattern = r"(?:#+\s*)?([^\n]+)\n+```mermaid"
@@ -456,7 +456,7 @@ class AnalyzeCommand(BaseCommand):
             return output
 
         # text format
-        output = f"Code Analysis Report\n{'='*50}\n\n"
+        output = f"Code Analysis Report\n{'=' * 50}\n\n"
         output += f"Target: {result_data['target']}\n"
 
         if diagrams:
@@ -469,7 +469,7 @@ class AnalyzeCommand(BaseCommand):
             for filepath in result_data["saved_diagrams"]:
                 output += f"  • {filepath}\n"
 
-        output += f"\n{'-'*50}\nAnalysis Results:\n{'-'*50}\n"
+        output += f"\n{'-' * 50}\nAnalysis Results:\n{'-' * 50}\n"
         output += result_data.get("analysis", "No analysis results")
 
         return output

claude_mpm/cli/commands/cleanup.py

@@ -436,7 +436,7 @@ def _cleanup_memory_original(args):
 
     # Analyze current state
     print("\n📊 Analyzing current conversation history...")
-    stats, issues = analyze_claude_json(claude_json)
+    stats, _issues = analyze_claude_json(claude_json)
 
     # Display current status
     print(f"\n📁 File: {claude_json}")

claude_mpm/cli/commands/configure_agent_display.py

@@ -228,8 +228,8 @@ class AgentDisplay:
 [bold]Model:[/bold] {model}
 [bold]Agent Version:[/bold] {agent_version}
 [bold]Schema Version:[/bold] {schema_version}
-[bold]Tags:[/bold] {', '.join(tags) if tags else 'None'}
-[bold]Tools:[/bold] {', '.join(tools[:5]) if tools else 'None'}{'...' if len(tools) > 5 else ''}
+[bold]Tags:[/bold] {", ".join(tags) if tags else "None"}
+[bold]Tools:[/bold] {", ".join(tools[:5]) if tools else "None"}{"..." if len(tools) > 5 else ""}
 """
                     except Exception:
                         pass
@@ -237,9 +237,9 @@ class AgentDisplay:
                 # Create detail panel
                 detail_text = f"""
 [bold]Name:[/bold] {agent.name}
-[bold]Status:[/bold] {'[green]Enabled[/green]' if self.agent_manager.is_agent_enabled(agent.name) else '[red]Disabled[/red]'}
+[bold]Status:[/bold] {"[green]Enabled[/green]" if self.agent_manager.is_agent_enabled(agent.name) else "[red]Disabled[/red]"}
 [bold]Template Path:[/bold] {template_path}
-[bold]Is System Template:[/bold] {'Yes' if str(template_path).startswith(str(self.agent_manager.templates_dir)) else 'No (Custom)'}
+[bold]Is System Template:[/bold] {"Yes" if str(template_path).startswith(str(self.agent_manager.templates_dir)) else "No (Custom)"}
 {extra_info}
                 """
 

claude_mpm/cli/commands/debug.py

@@ -693,9 +693,9 @@ def debug_hooks(args, logger):
                     max_time = max(times)
 
                     print(f"\n   {hook.name}:")
-                    print(f"     Average: {avg_time*1000:.2f}ms")
-                    print(f"     Min: {min_time*1000:.2f}ms")
-                    print(f"     Max: {max_time*1000:.2f}ms")
+                    print(f"     Average: {avg_time * 1000:.2f}ms")
+                    print(f"     Min: {min_time * 1000:.2f}ms")
+                    print(f"     Max: {max_time * 1000:.2f}ms")
 
         else:
             # Default: show summary
@@ -767,7 +767,7 @@ def debug_cache(args, logger):
             print(f"   Location: {cache_dir}")
             print(f"   Total Files: {file_count}")
             print(
-                f"   Total Size: {total_size:,} bytes ({total_size/1024/1024:.2f} MB)"
+                f"   Total Size: {total_size:,} bytes ({total_size / 1024 / 1024:.2f} MB)"
             )
 
             print("\n📁 Categories:")
@@ -871,7 +871,7 @@ def debug_cache(args, logger):
 
                 print(f"Location: {cache_dir}")
                 print(f"Files: {file_count}")
-                print(f"Size: {total_size:,} bytes ({total_size/1024/1024:.2f} MB)")
+                print(f"Size: {total_size:,} bytes ({total_size / 1024 / 1024:.2f} MB)")
             else:
                 print("No cache found")
 
@@ -998,22 +998,22 @@ def debug_performance(args, logger):
             # Memory info
             mem = psutil.virtual_memory()
             print("\n💾 Memory:")
-            print(f"   Total: {mem.total/1024/1024/1024:.2f} GB")
-            print(f"   Used: {mem.used/1024/1024/1024:.2f} GB ({mem.percent}%)")
-            print(f"   Available: {mem.available/1024/1024/1024:.2f} GB")
+            print(f"   Total: {mem.total / 1024 / 1024 / 1024:.2f} GB")
+            print(f"   Used: {mem.used / 1024 / 1024 / 1024:.2f} GB ({mem.percent}%)")
+            print(f"   Available: {mem.available / 1024 / 1024 / 1024:.2f} GB")
 
             # Disk info
             disk = psutil.disk_usage("/")
             print("\n💿 Disk:")
-            print(f"   Total: {disk.total/1024/1024/1024:.2f} GB")
-            print(f"   Used: {disk.used/1024/1024/1024:.2f} GB ({disk.percent}%)")
-            print(f"   Free: {disk.free/1024/1024/1024:.2f} GB")
+            print(f"   Total: {disk.total / 1024 / 1024 / 1024:.2f} GB")
+            print(f"   Used: {disk.used / 1024 / 1024 / 1024:.2f} GB ({disk.percent}%)")
+            print(f"   Free: {disk.free / 1024 / 1024 / 1024:.2f} GB")
 
             # Process info
             process = psutil.Process()
             print("\n📦 Current Process:")
             print(f"   PID: {process.pid}")
-            print(f"   Memory: {process.memory_info().rss/1024/1024:.2f} MB")
+            print(f"   Memory: {process.memory_info().rss / 1024 / 1024:.2f} MB")
             print(f"   CPU: {process.cpu_percent()}%")
             print(f"   Threads: {process.num_threads()}")