Add Codex session catchup support

Teach session-catchup.py to read Codex rollout JSONL, skip the current Codex thread, filter subagent/tiny sessions, and detect structured planning updates. Update tests and docs for the new behavior.

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Eugene Brevdo
2026-04-07 11:10:44 -07:00
co-authored by Codex
parent 59edf7bb11
commit 5df903e05c
10 changed files with 1852 additions and 465 deletions
+239 -64
View File
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
+239 -64
View File
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
+239 -64
View File
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
+239 -64
View File
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
+6
View File
@@ -2,6 +2,12 @@
All notable changes to this project will be documented in this file.
## Unreleased
### Fixed
- **Codex session catchup** — `session-catchup.py` now reads Codex rollout JSONL from `~/.codex/sessions`, prefers `CODEX_THREAD_ID` when skipping the current thread, filters subagent and tiny sessions, and detects planning-file updates from structured Codex `patch_apply_end` events.
## [2.29.0] - 2026-03-24
### Added
+1 -1
View File
@@ -82,7 +82,7 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
When your context fills up and you run `/clear`, this skill **automatically recovers** your previous session.
**How it works:**
1. Checks for previous session data in `~/.claude/projects/`
1. Checks for previous session data in the active IDE's session store (`~/.claude/projects/` for Claude Code, `~/.codex/sessions/` for Codex)
2. Finds when planning files were last updated
3. Extracts conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync
@@ -12,9 +12,35 @@ import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from typing import Any, Dict, Iterable, List, Optional, Tuple
try:
import orjson
except ImportError:
orjson = None
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
MIN_SESSION_BYTES = 5000
def json_loads(line: str) -> Optional[Dict[str, Any]]:
"""Prefer optional orjson while keeping the hook dependency-free."""
try:
if orjson is not None:
data = orjson.loads(line)
else:
data = json.loads(line)
except (ValueError, TypeError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def normalize_for_compare(path_value: str) -> str:
expanded = os.path.expanduser(path_value)
try:
return str(Path(expanded).resolve())
except (OSError, ValueError):
return os.path.abspath(expanded)
def normalize_path(project_path: str) -> str:
@@ -43,8 +69,8 @@ def normalize_path(project_path: str) -> str:
return p
def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
"""Resolve session storage path for the current runtime variant."""
def get_claude_project_dir(project_path: str) -> Path:
"""Resolve Claude Code's project-specific session storage path."""
normalized = normalize_path(project_path)
# Claude Code's sanitization: replace path separators and : with -
@@ -54,44 +80,138 @@ def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
if sanitized.startswith('-'):
sanitized = sanitized[1:]
claude_path = Path.home() / '.claude' / 'projects' / sanitized
# Codex stores sessions in ~/.codex/sessions with a different format.
# Avoid silently scanning Claude paths when running from Codex skill folder.
script_path = Path(__file__).as_posix().lower()
is_codex_variant = '/.codex/' in script_path
codex_sessions_dir = Path.home() / '.codex' / 'sessions'
if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
return None, (
"[planning-with-files] Session catchup skipped: Codex stores sessions "
"in ~/.codex/sessions and native Codex parsing is not implemented yet."
)
return claude_path, None
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
return sorted(main_sessions, key=safe_stat_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
def safe_stat_mtime(path: Path) -> float:
try:
return path.stat().st_mtime
except OSError:
return 0.0
def is_substantial_session(session: Path) -> bool:
try:
return session.stat().st_size > MIN_SESSION_BYTES
except OSError:
return False
def read_codex_meta(session_file: Path) -> Optional[Dict[str, Any]]:
"""Read the first session_meta; later meta records may be copied parent context."""
try:
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line in f:
data = json_loads(line)
if not data or data.get('type') != 'session_meta':
continue
payload = data.get('payload')
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def codex_meta_cwd(meta: Dict[str, Any]) -> Optional[str]:
cwd = meta.get('cwd')
return cwd if isinstance(cwd, str) else None
def find_current_codex_session(sessions: List[Path]) -> Optional[Path]:
thread_id = os.getenv('CODEX_THREAD_ID', '').strip()
if not thread_id:
return None
for session in sessions:
if thread_id in session.name:
return session
return None
def get_codex_sessions(project_path: str) -> Iterable[Path]:
sessions_dir = Path(os.path.expanduser(os.getenv('CODEX_SESSIONS_DIR', '~/.codex/sessions')))
if not sessions_dir.exists():
return
project_cmp = normalize_for_compare(project_path)
sessions = sorted(sessions_dir.rglob('rollout-*.jsonl'), key=safe_stat_mtime, reverse=True)
current = find_current_codex_session(sessions)
current_meta = read_codex_meta(current) if current else None
current_cwd = codex_meta_cwd(current_meta) if current_meta else None
skip_current = bool(current_cwd and normalize_for_compare(current_cwd) == project_cmp)
for session in sessions:
if not is_substantial_session(session):
continue
if skip_current and session == current:
continue
meta = read_codex_meta(session)
if not meta:
continue
source = meta.get('source')
if isinstance(source, dict) and 'subagent' in source:
continue
cwd = codex_meta_cwd(meta)
if cwd and normalize_for_compare(cwd) == project_cmp:
yield session
def get_session_candidates(project_path: str) -> Tuple[str, Iterable[Path]]:
if '/.codex/' in Path(__file__).resolve().as_posix().lower():
return 'codex', get_codex_sessions(project_path)
claude_project_dir = get_claude_project_dir(project_path)
if claude_project_dir.exists():
return 'claude', get_sessions_sorted(claude_project_dir)
return 'claude', []
def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data = json_loads(line)
if data is not None:
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
matches = {pf for path in paths if (pf := planning_file_from_path(path))}
for pf in PLANNING_FILES:
if pf in matches:
return pf
return None
def codex_planning_update(payload: Dict[str, Any]) -> Optional[str]:
"""Use Codex's structured apply_patch result instead of parsing tool text."""
if payload.get('type') != 'patch_apply_end' or payload.get('success') is not True:
return None
changes = payload.get('changes')
return planning_file_from_paths(changes.keys()) if isinstance(changes, dict) else None
def find_last_planning_update(messages: List[Dict[str, Any]]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
@@ -109,18 +229,59 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(tool_input.get('file_path', ''))
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
elif msg_type == 'event_msg':
payload = msg.get('payload')
if isinstance(payload, dict):
planning_file = codex_planning_update(payload)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
def text_content(content: Any) -> str:
if isinstance(content, str):
return content
if not isinstance(content, list):
return ''
return '\n'.join(
item.get('text', '')
for item in content
if isinstance(item, dict) and isinstance(item.get('text'), str)
)
def parse_codex_tool_args(payload: Dict[str, Any]) -> Tuple[Dict[str, Any], str]:
raw_args = payload.get('arguments', payload.get('input', ''))
if isinstance(raw_args, dict):
return raw_args, json.dumps(raw_args, ensure_ascii=True)
if not isinstance(raw_args, str):
return {}, ''
decoded = json_loads(raw_args)
return (decoded, raw_args) if isinstance(decoded, dict) else ({}, raw_args)
def summarize_codex_tool(payload: Dict[str, Any]) -> str:
tool_name = payload.get('name', 'tool')
tool_args, raw_args = parse_codex_tool_args(payload)
if tool_name == 'exec_command':
command = tool_args.get('cmd', raw_args)
if isinstance(command, str):
return f"exec_command: {command[:80]}"
return 'apply_patch' if tool_name == 'apply_patch' else str(tool_name)
def extract_messages_after(messages: List[Dict[str, Any]], after_line: int) -> List[Dict[str, Any]]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
@@ -131,16 +292,9 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
content = text_content(msg.get('message', {}).get('content', ''))
if content and isinstance(content, str):
if content:
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
@@ -148,18 +302,16 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
text = text_content(msg_content)
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
if isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
if isinstance(item, dict) and item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if not isinstance(tool_input, dict):
tool_input = {}
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
@@ -170,14 +322,45 @@ def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
if text or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'content': text[:600] if text else '',
'tools': tool_uses,
'line': msg['_line_num']
})
elif msg_type == 'response_item':
payload = msg.get('payload')
if not isinstance(payload, dict):
continue
payload_type = payload.get('type')
if payload_type == 'message':
role = payload.get('role')
if role not in ('user', 'assistant'):
continue
content = text_content(payload.get('content'))
if role == 'user':
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif content:
result.append({
'role': 'assistant',
'content': content[:600],
'tools': [],
'line': msg['_line_num']
})
elif payload_type in ('function_call', 'custom_tool_call'):
result.append({
'role': 'assistant',
'content': '',
'tools': [summarize_codex_tool(payload)],
'line': msg['_line_num']
})
return result
@@ -192,25 +375,15 @@ def main():
# No planning files in this project; skip catchup to avoid noise.
return
project_dir, skip_reason = get_project_dir(project_path)
if skip_reason:
print(skip_reason)
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
runtime_name, sessions = get_session_candidates(project_path)
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if runtime_name == 'claude' and not is_substantial_session(session):
continue
target_session = session
break
if not target_session:
return
@@ -231,17 +404,19 @@ def main():
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Runtime: {runtime_name}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
assistant_label = 'CODEX' if runtime_name == 'codex' else 'CLAUDE'
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"{assistant_label}: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
+172 -16
View File
@@ -1,7 +1,11 @@
import importlib.util
import io
import json
import os
import shutil
import tempfile
import unittest
from contextlib import redirect_stdout
from pathlib import Path
from unittest import mock
@@ -27,7 +31,11 @@ class SessionCatchupCodexTests(unittest.TestCase):
def setUp(self):
self.tempdir = tempfile.TemporaryDirectory()
self.root = Path(self.tempdir.name)
self.project_path = "/tmp/project"
self.project_dir = self.root / "project"
self.project_dir.mkdir()
self.project_path = str(self.project_dir)
self.sessions_dir = self.root / ".codex/sessions"
self.sessions_dir.mkdir(parents=True)
self.codex_script = (
self.root / ".codex/skills/planning-with-files/scripts/session-catchup.py"
)
@@ -38,26 +46,174 @@ class SessionCatchupCodexTests(unittest.TestCase):
def tearDown(self):
self.tempdir.cleanup()
def test_codex_variant_skips_when_only_codex_sessions_exist(self):
(self.root / ".codex/sessions").mkdir(parents=True, exist_ok=True)
def write_codex_session(
self,
name,
*,
cwd=None,
source="codex",
records=(),
substantial=True,
mtime=100,
):
path = self.sessions_dir / name
path.parent.mkdir(parents=True, exist_ok=True)
session_records = [
{
"timestamp": "2026-04-07T00:00:00.000Z",
"type": "session_meta",
"payload": {"cwd": cwd or self.project_path, "source": source},
}
]
if substantial:
session_records.append(
{
"timestamp": "2026-04-07T00:00:01.000Z",
"type": "response_item",
"payload": {
"type": "message",
"role": "assistant",
"content": [
{"type": "output_text", "text": "x" * 6000},
],
},
}
)
session_records.extend(records)
with path.open("w", encoding="utf-8") as f:
for record in session_records:
f.write(json.dumps(record) + "\n")
os.utime(path, (mtime, mtime))
return path
with mock.patch("pathlib.Path.home", return_value=self.root):
project_dir, skip_reason = self.module.get_project_dir(self.project_path)
def codex_candidates(self, *, thread_id=None):
updates = {"CODEX_SESSIONS_DIR": str(self.sessions_dir)}
if thread_id is not None:
updates["CODEX_THREAD_ID"] = thread_id
with mock.patch.dict(os.environ, updates, clear=False):
if thread_id is None:
os.environ.pop("CODEX_THREAD_ID", None)
with mock.patch("pathlib.Path.home", return_value=self.root):
runtime, sessions = self.module.get_session_candidates(self.project_path)
return runtime, list(sessions)
self.assertIsNone(project_dir)
self.assertIn("~/.codex/sessions", skip_reason)
self.assertIn("not implemented yet", skip_reason)
def test_codex_variant_finds_matching_project_sessions(self):
session = self.write_codex_session(
"rollout-2026-04-07T00-00-00-previous-thread.jsonl"
)
def test_codex_variant_uses_claude_path_when_project_exists(self):
(self.root / ".codex/sessions").mkdir(parents=True, exist_ok=True)
expected = self.root / ".claude/projects/-tmp-project"
expected.mkdir(parents=True, exist_ok=True)
runtime, sessions = self.codex_candidates()
with mock.patch("pathlib.Path.home", return_value=self.root):
project_dir, skip_reason = self.module.get_project_dir(self.project_path)
self.assertEqual("codex", runtime)
self.assertEqual([session], sessions)
self.assertEqual(expected, project_dir)
self.assertIsNone(skip_reason)
def test_codex_variant_skips_current_thread_for_same_project(self):
previous = self.write_codex_session(
"rollout-2026-04-07T00-00-00-previous-thread.jsonl",
mtime=100,
)
self.write_codex_session(
"rollout-2026-04-07T01-00-00-current-thread.jsonl",
mtime=200,
)
runtime, sessions = self.codex_candidates(thread_id="current-thread")
self.assertEqual("codex", runtime)
self.assertEqual([previous], sessions)
def test_codex_variant_skips_small_sessions_and_subagents(self):
valid = self.write_codex_session(
"rollout-2026-04-07T00-00-00-valid-thread.jsonl",
mtime=100,
)
self.write_codex_session(
"rollout-2026-04-07T01-00-00-small-thread.jsonl",
substantial=False,
mtime=200,
)
self.write_codex_session(
"rollout-2026-04-07T02-00-00-subagent-thread.jsonl",
source={"subagent": "worker"},
mtime=300,
)
runtime, sessions = self.codex_candidates()
self.assertEqual("codex", runtime)
self.assertEqual([valid], sessions)
def test_codex_structured_patch_event_marks_planning_update(self):
messages = [
{
"_line_num": 7,
"type": "event_msg",
"payload": {
"type": "patch_apply_end",
"success": True,
"changes": {"progress.md": {"operation": "modified"}},
},
}
]
self.assertEqual(
(7, "progress.md"),
self.module.find_last_planning_update(messages),
)
def test_codex_main_prints_catchup_from_matching_session(self):
for filename in self.module.PLANNING_FILES:
(self.project_dir / filename).write_text("# test\n", encoding="utf-8")
self.write_codex_session(
"rollout-2026-04-07T00-00-00-previous-thread.jsonl",
records=[
{
"timestamp": "2026-04-07T00:00:02.000Z",
"type": "event_msg",
"payload": {
"type": "patch_apply_end",
"success": True,
"changes": {"task_plan.md": {"operation": "modified"}},
},
},
{
"timestamp": "2026-04-07T00:00:03.000Z",
"type": "response_item",
"payload": {
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Codex summary after planning update",
}
],
},
},
],
)
stdout = io.StringIO()
with mock.patch.dict(
os.environ,
{"CODEX_SESSIONS_DIR": str(self.sessions_dir)},
clear=False,
):
os.environ.pop("CODEX_THREAD_ID", None)
with mock.patch("pathlib.Path.home", return_value=self.root):
with mock.patch.object(
self.module.sys,
"argv",
["session-catchup.py", self.project_path],
):
with redirect_stdout(stdout):
self.module.main()
output = stdout.getvalue()
self.assertIn("SESSION CATCHUP DETECTED", output)
self.assertIn("Runtime: codex", output)
self.assertIn("Last planning update: task_plan.md", output)
self.assertIn("CODEX: Codex summary after planning update", output)
if __name__ == "__main__":