list_sessions
Retrieve all sessions within a specific project to manage and organize Claude Code sessions effectively.
Instructions
List all sessions in a project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_name | Yes | Project folder name (e.g., '-Users-young-works-myproject') |
Implementation Reference
- Core handler function that lists all sessions for the given project by scanning JSONL files (excluding agent-), parsing summaries with parse_session_summary, and sorting by updated_at descending.def get_sessions(project_name: str) -> list[dict]: """Get all sessions for a project.""" base_path = get_base_path() project_path = base_path / project_name sessions = [] if not project_path.exists(): return sessions for jsonl_file in project_path.glob("*.jsonl"): if jsonl_file.name.startswith("agent-"): continue session_info = parse_session_summary(jsonl_file) if session_info: sessions.append(session_info) return sorted(sessions, key=lambda s: s.get("updated_at", ""), reverse=True)
- Tool schema definition including name, description, and input schema requiring 'project_name'.Tool( name="list_sessions", description="List all sessions in a project", inputSchema={ "type": "object", "properties": { "project_name": { "type": "string", "description": "Project folder name (e.g., '-Users-young-works-myproject')" } }, "required": ["project_name"] } ),
- Dispatch handler in call_tool function that extracts project_name from arguments and invokes get_sessions.elif name == "list_sessions": project_name = arguments.get("project_name", "") result = get_sessions(project_name)
- Helper function used by get_sessions to extract session metadata like title, message_count, timestamps from JSONL files by parsing entries.def parse_session_summary(file_path: Path) -> dict | None: """Parse session file for summary info.""" session_id = file_path.stem info = { "session_id": session_id, "title": f"Session {session_id[:8]}", "message_count": 0, "created_at": None, "updated_at": None, } try: with open(file_path, 'r', encoding='utf-8') as f: first_user_content = None for line in f: line = line.strip() if not line: continue try: entry = json.loads(line) entry_type = entry.get('type') if entry_type in ('user', 'assistant'): info["message_count"] += 1 timestamp = entry.get('timestamp', '') if timestamp: if not info["created_at"] or timestamp < info["created_at"]: info["created_at"] = timestamp if not info["updated_at"] or timestamp > info["updated_at"]: info["updated_at"] = timestamp if entry_type == 'user' and first_user_content is None: message = entry.get('message', {}) content_list = message.get('content', []) for item in content_list: if isinstance(item, dict) and item.get('type') == 'text': text = item.get('text', '').strip() text = re.sub(r'<ide_[^>]*>.*?</ide_[^>]*>', '', text, flags=re.DOTALL).strip() if text: first_user_content = text break except json.JSONDecodeError: continue if first_user_content: if '\n\n' in first_user_content: info["title"] = first_user_content.split('\n\n')[0][:100] elif '\n' in first_user_content: info["title"] = first_user_content.split('\n')[0][:100] else: info["title"] = first_user_content[:100] except Exception: return None return info if info["message_count"] > 0 else None