claude-session-manager

Instructions

Implementation Reference

• src/claude_session_manager_mcp/server.py:403-436 (handler)

  The core handler function that implements the logic for the 'clear_sessions' tool. It identifies cleanable sessions (empty or invalid API key) and deletes them, returning a summary of actions taken.

  def clear_sessions(project_name: str | None = None, clear_empty: bool = True, clear_invalid: bool = True) -> dict:
      """Clear empty and invalid sessions."""
      cleanable = find_cleanable_sessions(project_name)
      deleted = {
          'empty_sessions': [],
          'invalid_api_key_sessions': [],
          'total_deleted': 0,
          'errors': []
      }
  
      sessions_to_delete = []
  
      if clear_empty:
          sessions_to_delete.extend([(s, 'empty') for s in cleanable['empty_sessions']])
      if clear_invalid:
          sessions_to_delete.extend([(s, 'invalid_api_key') for s in cleanable['invalid_api_key_sessions']])
  
      for session_info, reason in sessions_to_delete:
          try:
              success = delete_session(session_info['project_name'], session_info['session_id'])
              if success:
                  if reason == 'empty':
                      deleted['empty_sessions'].append(session_info)
                  else:
                      deleted['invalid_api_key_sessions'].append(session_info)
                  deleted['total_deleted'] += 1
          except Exception as e:
              deleted['errors'].append({
                  'session': session_info,
                  'error': str(e)
              })
  
      return deleted

• src/claude_session_manager_mcp/server.py:634-655 (registration)

  Registration of the 'clear_sessions' tool in the MCP list_tools() function, including its name, description, and input schema.

  Tool(
      name="clear_sessions",
      description="Delete all empty sessions and invalid API key sessions",
      inputSchema={
          "type": "object",
          "properties": {
              "project_name": {
                  "type": "string",
                  "description": "Optional: filter by project name"
              },
              "clear_empty": {
                  "type": "boolean",
                  "description": "Clear empty sessions (default: true)"
              },
              "clear_invalid": {
                  "type": "boolean",
                  "description": "Clear invalid API key sessions (default: true)"
              }
          },
          "required": []
      }
  ),

• src/claude_session_manager_mcp/server.py:637-654 (schema)

  Input schema defining the parameters for the clear_sessions tool: optional project_name (string), clear_empty (boolean, default true), clear_invalid (boolean, default true).

  inputSchema={
      "type": "object",
      "properties": {
          "project_name": {
              "type": "string",
              "description": "Optional: filter by project name"
          },
          "clear_empty": {
              "type": "boolean",
              "description": "Clear empty sessions (default: true)"
          },
          "clear_invalid": {
              "type": "boolean",
              "description": "Clear invalid API key sessions (default: true)"
          }
      },
      "required": []
  }

• src/claude_session_manager_mcp/server.py:722-727 (handler)

  Tool dispatch handler in the MCP call_tool() function that extracts arguments and invokes the clear_sessions handler.

  elif name == "clear_sessions":
      project_name = arguments.get("project_name")
      clear_empty = arguments.get("clear_empty", True)
      clear_invalid = arguments.get("clear_invalid", True)
      result = clear_sessions(project_name, clear_empty, clear_invalid)

• src/claude_session_manager_mcp/server.py:363-401 (helper)

  Helper function used by clear_sessions to identify empty and invalid API key sessions across projects.

  def find_cleanable_sessions(project_name: str | None = None) -> dict:
      """Find sessions that can be cleaned."""
      base_path = get_base_path()
      result = {
          'empty_sessions': [],
          'invalid_api_key_sessions': [],
          'total_count': 0
      }
  
      if project_name:
          project_dirs = [base_path / project_name]
      else:
          project_dirs = [d for d in base_path.iterdir() if d.is_dir() and not d.name.startswith('.')]
  
      for project_path in project_dirs:
          if not project_path.exists():
              continue
  
          for jsonl_file in project_path.glob("*.jsonl"):
              if jsonl_file.name.startswith("agent-"):
                  continue
  
              session_id = jsonl_file.stem
              status = check_session_status(jsonl_file)
  
              session_info = {
                  'project_name': project_path.name,
                  'session_id': session_id,
                  'file_size': status['file_size']
              }
  
              if status['has_invalid_api_key'] and not status['has_messages']:
                  result['invalid_api_key_sessions'].append(session_info)
              elif status['is_empty'] or status['file_size'] == 0:
                  result['empty_sessions'].append(session_info)
  
      result['total_count'] = len(result['empty_sessions']) + len(result['invalid_api_key_sessions'])
      return result