mainai 0.1.0__py3-none-any.whl

mainai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mainai/cli.py

@@ -0,0 +1,148 @@
+"""mainai -- pick which coding agent to continue a project with."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from mainai import __version__, llm
+from mainai.llm_picker import llm_pick
+from mainai.picker import Pick, heuristic_pick
+from mainai.readers import all_sessions_for
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mainai",
+        description=(
+            "Find which coding agent (Claude Code, Codex, ...) last did real "
+            "work in a project folder, and show which one to continue with. "
+            "Run with no arguments to process the current directory."
+        ),
+    )
+    parser.add_argument(
+        "folder",
+        nargs="?",
+        default=".",
+        help="project folder to inspect (default: current directory)",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help=(
+            "show the sessions found and a quick file-evidence guess, nothing "
+            "else (no file written, no LLM call)"
+        ),
+    )
+    parser.add_argument(
+        "--agent",
+        metavar="NAME",
+        help="override the pick, e.g. --agent codex (no LLM call)",
+    )
+    parser.add_argument(
+        "--handoff",
+        action="store_true",
+        help="also summarize the other agents' sessions into HANDOFF.md (uses an LLM)",
+    )
+    parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help=(
+            "don't ask for confirmation before an LLM call that would bill "
+            "ANTHROPIC_API_KEY directly (no claude.ai subscription login found)"
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def _confirm_api_key_billing(yes: bool) -> bool:
+    print(
+        "mainai: no claude.ai subscription login found; the LLM pick would bill "
+        "ANTHROPIC_API_KEY directly (pay-per-token), not a subscription.",
+        file=sys.stderr,
+    )
+    if yes:
+        return True
+    if not sys.stdin.isatty():
+        print(
+            "mainai: not an interactive terminal; re-run with --yes to proceed anyway, "
+            "or use --list / --agent to avoid the LLM call.",
+            file=sys.stderr,
+        )
+        return False
+    reply = input("Proceed and bill ANTHROPIC_API_KEY for this call? [y/N] ").strip().lower()
+    return reply in ("y", "yes")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    folder = Path(args.folder).expanduser()
+    if not folder.is_dir():
+        print(f"mainai: {folder} is not a directory", file=sys.stderr)
+        return 1
+
+    sessions = all_sessions_for(folder)
+
+    if not sessions:
+        print(f"No sessions found for {folder.resolve()}")
+        return 0
+
+    if args.agent:
+        chosen = next((s for s in sessions if s.agent == args.agent), None)
+        if chosen is None:
+            print(f"mainai: no session found for agent '{args.agent}'", file=sys.stderr)
+            return 1
+        result = Pick(session=chosen, reasons=[f"overridden with --agent {args.agent}"])
+    elif args.list:
+        result = heuristic_pick(sessions, folder)
+    else:
+        auth_mode = llm.determine_auth_mode()
+        if auth_mode == llm.AuthMode.UNAVAILABLE:
+            print(
+                "mainai: no usable `claude` auth found (no claude.ai login, no "
+                "ANTHROPIC_API_KEY). Run `claude login`, or use --list / --agent "
+                "to avoid the LLM call.",
+                file=sys.stderr,
+            )
+            return 1
+        if auth_mode == llm.AuthMode.API_KEY and not _confirm_api_key_billing(args.yes):
+            print("mainai: aborted.", file=sys.stderr)
+            return 1
+        result = llm_pick(sessions, folder)
+
+    chosen = result.session
+
+    print(f"Found {len(sessions)} session(s) in {folder.resolve()}")
+    for session in sessions:
+        marker = "  <- latest work" if session is chosen else ""
+        print(f'  {session.agent:<8} {session.end.date()}  "{session.summary}"{marker}')
+
+    if args.list:
+        return 0
+
+    if chosen is None:
+        return 0
+
+    print()
+    print(f"Continue with: {chosen.agent} ({'; '.join(result.reasons)})")
+    print(f"  Advice: cd {chosen.cwd} && {chosen.agent}")
+
+    if args.handoff:
+        print()
+        print("mainai: --handoff (LLM summarizer) is not implemented yet.", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mainai/llm.py

@@ -0,0 +1,112 @@
+"""Thin wrapper around calling an LLM in headless/non-interactive mode.
+
+Default backend is `claude -p` (Claude Code headless mode): no separate API
+key needed when the user has a claude.ai login, since it draws on that
+login's included usage. Kept behind this small interface so `codex exec` or
+`grok -p` can be swapped in later (see mainai.md).
+
+Many developers keep ANTHROPIC_API_KEY set for their own API projects, and
+`claude -p` prefers that key over a claude.ai login when both are present.
+mainai must not silently bill someone's personal API key for a background
+utility call, so every call here strips ANTHROPIC_API_KEY from the
+subprocess environment whenever a claude.ai login is available
+(`determine_auth_mode` -> AuthMode.SUBSCRIPTION). When no claude.ai login
+exists, the caller (mainai.cli) must get explicit confirmation before a call
+that will bill the API key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from enum import Enum
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+class AuthMode(Enum):
+    SUBSCRIPTION = "subscription"  # claude.ai login available; API key (if any) is stripped
+    API_KEY = "api_key"  # no claude.ai login; a call would bill ANTHROPIC_API_KEY
+    UNAVAILABLE = "unavailable"  # claude CLI missing, or no usable auth at all
+
+
+def determine_auth_mode() -> AuthMode:
+    if shutil.which("claude") is None:
+        return AuthMode.UNAVAILABLE
+
+    env = dict(os.environ)
+    env.pop("ANTHROPIC_API_KEY", None)
+    status: dict = {}
+    try:
+        result = subprocess.run(
+            ["claude", "auth", "status"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+            env=env,
+        )
+        status = json.loads(result.stdout)
+    except (subprocess.SubprocessError, OSError, json.JSONDecodeError):
+        status = {}
+
+    if status.get("loggedIn") and status.get("authMethod") == "claude.ai":
+        return AuthMode.SUBSCRIPTION
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return AuthMode.API_KEY
+    return AuthMode.UNAVAILABLE
+
+
+def call(prompt: str, *, model: str = "sonnet", timeout: int = 180) -> str:
+    """Run `prompt` through `claude -p` and return the text result.
+
+    Raises LLMError on anything that keeps the caller from getting a usable
+    answer: missing CLI, process failure, timeout, or unparseable output.
+    """
+    if shutil.which("claude") is None:
+        raise LLMError("the `claude` CLI is not on PATH")
+
+    env = dict(os.environ)
+    if determine_auth_mode() == AuthMode.SUBSCRIPTION:
+        env.pop("ANTHROPIC_API_KEY", None)
+
+    try:
+        result = subprocess.run(
+            [
+                "claude",
+                "-p",
+                prompt,
+                "--model",
+                model,
+                "--output-format",
+                "json",
+                "--no-session-persistence",
+                "--tools",
+                "",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.SubprocessError as exc:
+        raise LLMError(f"failed to run claude -p: {exc}") from exc
+
+    if result.returncode != 0:
+        raise LLMError(f"claude -p exited {result.returncode}: {result.stderr.strip()}")
+
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise LLMError(f"could not parse claude -p output as JSON: {exc}") from exc
+
+    if payload.get("is_error"):
+        raise LLMError(f"claude -p reported an error: {payload.get('result')}")
+
+    text = payload.get("result")
+    if not text:
+        raise LLMError("claude -p returned no text result")
+    return text

mainai/llm_picker.py

@@ -0,0 +1,92 @@
+"""LLM-based picker: this is mainai's default decision maker.
+
+Instead of only the file-evidence heuristic in `picker.py`, this asks an LLM
+to actually read each session's content -- the summary/title, a capped
+excerpt of turns, the files it touched that still exist on disk, and the
+commands it ran -- and recommend which agent to continue with, in its own
+words. Falls back to `picker.heuristic_pick` when the LLM call fails (CLI
+missing, timeout, bad output) or there's only one session to begin with.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mainai import llm
+from mainai.models import Session
+from mainai.picker import Pick, heuristic_pick
+
+MAX_TURN_CHARS = 400
+MAX_TURNS_PER_SESSION = 6
+
+
+def llm_pick(sessions: list[Session], folder: Path) -> Pick:
+    if not sessions:
+        return Pick(session=None, reasons=["no sessions found for this folder"])
+    if len(sessions) == 1:
+        return Pick(session=sessions[0], reasons=["only one session found"])
+
+    try:
+        raw = llm.call(_build_prompt(sessions, folder))
+        data = json.loads(raw)
+        agent = data["agent"]
+        reason = str(data.get("reason", "")).strip()
+    except (llm.LLMError, json.JSONDecodeError, KeyError, TypeError) as exc:
+        fallback = heuristic_pick(sessions, folder)
+        fallback.reasons.insert(
+            0, f"LLM pick unavailable ({exc}); used file-evidence heuristic instead"
+        )
+        return fallback
+
+    matches = [s for s in sessions if s.agent == agent]
+    if not matches:
+        fallback = heuristic_pick(sessions, folder)
+        fallback.reasons.insert(
+            0,
+            f"LLM named unrecognized agent '{agent}'; used file-evidence heuristic instead",
+        )
+        return fallback
+
+    chosen = max(matches, key=lambda s: s.end)
+    return Pick(session=chosen, reasons=[reason] if reason else ["LLM pick"])
+
+
+def _session_excerpt(session: Session) -> dict:
+    existing_files = sorted(f for f in session.files_touched if Path(f).exists())
+    turns = [
+        f"{turn.role}: {turn.text[:MAX_TURN_CHARS]}"
+        for turn in session.turns[:MAX_TURNS_PER_SESSION]
+        if turn.text.strip()
+    ]
+    return {
+        "agent": session.agent,
+        "start": session.start.isoformat(),
+        "end": session.end.isoformat(),
+        "title": session.title,
+        "files_touched_still_on_disk": existing_files,
+        "commands_run": session.commands_run[:10],
+        "turns_excerpt": turns,
+    }
+
+
+def _build_prompt(sessions: list[Session], folder: Path) -> str:
+    data = [_session_excerpt(s) for s in sessions]
+    agents = sorted({s.agent for s in sessions})
+    return (
+        "A developer worked on the same project folder using several different "
+        "coding agents (Claude Code, Codex, Grok, ...), at different times. Below "
+        "are summaries of each agent's most recent session in this folder. Decide "
+        "which session represents the most recent REAL work worth continuing from. "
+        "A session's newest message timestamp alone can be misleading -- e.g. a "
+        "trivial side question can be the newest message in an otherwise stale "
+        "session. Weigh the actual conversation content, the files it touched that "
+        "still exist on disk, and the commands it ran.\n\n"
+        f"Project folder: {folder}\n"
+        f"Candidate agents: {', '.join(agents)}\n\n"
+        "Sessions (JSON):\n"
+        f"{json.dumps(data, indent=2)}\n\n"
+        "Reply with ONLY a JSON object and nothing else, in this exact shape:\n"
+        '{"agent": "<one of the candidate agents above>", '
+        '"reason": "<one or two sentence explanation a developer would find useful>"}'
+    )

mainai/models.py

@@ -0,0 +1,35 @@
+"""Common record types every per-agent reader converts its log format into."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Turn:
+    role: str  # "user" | "assistant"
+    text: str
+    timestamp: datetime | None = None
+
+
+@dataclass
+class Session:
+    agent: str  # "claude", "codex", "grok", ...
+    session_id: str
+    cwd: str
+    start: datetime
+    end: datetime
+    title: str | None = None
+    turns: list[Turn] = field(default_factory=list)
+    files_touched: set[str] = field(default_factory=set)
+    commands_run: list[str] = field(default_factory=list)
+
+    @property
+    def summary(self) -> str:
+        if self.title:
+            return self.title
+        for turn in self.turns:
+            if turn.role == "user" and turn.text.strip():
+                return turn.text.strip().splitlines()[0][:80]
+        return "(no prompt text found)"

mainai/picker.py

@@ -0,0 +1,80 @@
+"""Heuristic, LLM-free picker: file evidence + git history only.
+
+This is no longer mainai's default decision maker -- see `llm_picker` for
+that, which asks an LLM to read the actual session content. This module is
+kept as the free, instant path for `--list`, and as the fallback when the
+LLM call fails or isn't available.
+
+Raw "latest message" can mislead -- a trivial side question can be the
+newest turn. The stronger signal is file evidence: does a file the session
+touched still exist on disk, matching what the session wrote. Git history is
+used as a secondary cross-check when the folder is a repo.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from mainai.models import Session
+
+
+@dataclass
+class Pick:
+    session: Session | None
+    reasons: list[str]
+
+
+def heuristic_pick(sessions: list[Session], folder: Path) -> Pick:
+    if not sessions:
+        return Pick(session=None, reasons=["no sessions found for this folder"])
+
+    folder = folder.resolve()
+    latest_commit_ts = _latest_git_commit_timestamp(folder)
+
+    scored = []
+    for session in sessions:
+        existing = {f for f in session.files_touched if Path(f).exists()}
+        scored.append((session, bool(existing), len(existing)))
+
+    scored.sort(key=lambda item: (item[1], item[2], item[0].end), reverse=True)
+    best_session, has_evidence, existing_count = scored[0]
+
+    reasons = []
+    if has_evidence:
+        reasons.append(f"{existing_count} file(s) it touched still exist on disk")
+    else:
+        reasons.append("no session has file evidence on disk; picked by latest activity")
+    reasons.append(f"most recent turn {best_session.end.isoformat()}")
+
+    if latest_commit_ts is not None:
+        if best_session.start <= latest_commit_ts <= best_session.end:
+            reasons.append("its time range contains the latest git commit")
+        else:
+            reasons.append(f"latest git commit was at {latest_commit_ts.isoformat()}")
+
+    return Pick(session=best_session, reasons=reasons)
+
+
+def _latest_git_commit_timestamp(folder: Path) -> datetime | None:
+    if not (folder / ".git").exists():
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(folder), "log", "-1", "--format=%cI"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=True,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    value = result.stdout.strip()
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None

mainai/readers/__init__.py

@@ -0,0 +1,25 @@
+"""One reader per coding agent. Each exposes `sessions_for(folder)` and returns
+a list of `mainai.models.Session`, filtered to sessions whose cwd is the given
+folder or a subfolder of it. Readers must never crash on a malformed or
+unrecognized log line -- skip it and move on.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mainai.models import Session
+from mainai.readers import claude_code, codex
+
+READERS = {
+    "claude": claude_code.sessions_for,
+    "codex": codex.sessions_for,
+}
+
+
+def all_sessions_for(folder: Path) -> list[Session]:
+    sessions: list[Session] = []
+    for reader in READERS.values():
+        sessions.extend(reader(folder))
+    sessions.sort(key=lambda s: s.end, reverse=True)
+    return sessions

mainai/readers/claude_code.py

@@ -0,0 +1,141 @@
+"""Reader for Claude Code's own transcripts.
+
+Format: JSONL under ~/.claude/projects/<cwd-slug>/<session-id>.jsonl, one
+event per line. `cwd`, `timestamp`, `sessionId` appear on most event types.
+The format is undocumented and has grown new event types across versions
+(mode, permission-mode, file-history-snapshot, attachment, ai-title, ...);
+this reader only looks at the few types it understands and skips the rest.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from mainai.models import Session, Turn
+
+PROJECTS_DIR = Path.home() / ".claude" / "projects"
+
+EDIT_TOOLS = {"Edit", "Write", "NotebookEdit", "MultiEdit"}
+
+
+def sessions_for(folder: Path) -> list[Session]:
+    folder = folder.resolve()
+    if not PROJECTS_DIR.is_dir():
+        return []
+
+    sessions = []
+    for project_dir in PROJECTS_DIR.iterdir():
+        if not project_dir.is_dir():
+            continue
+        for jsonl_path in project_dir.glob("*.jsonl"):
+            session = _read_session(jsonl_path, folder)
+            if session is not None:
+                sessions.append(session)
+    return sessions
+
+
+def _read_session(path: Path, folder: Path) -> Session | None:
+    session_id = path.stem
+    cwd: str | None = None
+    title: str | None = None
+    start: datetime | None = None
+    end: datetime | None = None
+    turns: list[Turn] = []
+    files_touched: set[str] = set()
+    commands_run: list[str] = []
+
+    try:
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict):
+            continue
+
+        event_cwd = event.get("cwd")
+        if event_cwd:
+            cwd = event_cwd
+
+        ts = _parse_timestamp(event.get("timestamp"))
+        if ts is not None:
+            if start is None or ts < start:
+                start = ts
+            if end is None or ts > end:
+                end = ts
+
+        event_type = event.get("type")
+
+        if event_type == "ai-title":
+            title = event.get("aiTitle") or title
+            continue
+
+        if event_type not in ("user", "assistant"):
+            continue
+
+        message = event.get("message")
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role", event_type)
+        content = message.get("content")
+
+        if isinstance(content, str):
+            if not event.get("isMeta") and content.strip():
+                turns.append(Turn(role=role, text=content, timestamp=ts))
+        elif isinstance(content, list):
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                block_type = block.get("type")
+                if block_type == "text" and not event.get("isMeta"):
+                    text = block.get("text", "")
+                    if text.strip():
+                        turns.append(Turn(role=role, text=text, timestamp=ts))
+                elif block_type == "tool_use":
+                    name = block.get("name")
+                    tool_input = block.get("input") or {}
+                    if name in EDIT_TOOLS:
+                        file_path = tool_input.get("file_path")
+                        if file_path:
+                            files_touched.add(file_path)
+                    elif name == "Bash":
+                        command = tool_input.get("command")
+                        if command:
+                            commands_run.append(command)
+
+    if cwd is None or start is None or end is None:
+        return None
+
+    cwd_path = Path(cwd).resolve()
+    if cwd_path != folder and folder not in cwd_path.parents:
+        return None
+
+    return Session(
+        agent="claude",
+        session_id=session_id,
+        cwd=cwd,
+        start=start,
+        end=end,
+        title=title,
+        turns=turns,
+        files_touched=files_touched,
+        commands_run=commands_run,
+    )
+
+
+def _parse_timestamp(value: object) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None

mainai/readers/codex.py

@@ -0,0 +1,144 @@
+"""Reader for Codex CLI session logs.
+
+Format: JSONL under ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl (or, when
+Codex is installed via snap, ~/snap/codex/<rev>/sessions/YYYY/MM/DD/). First
+line is `type: session_meta` with `payload.cwd`, `payload.id`,
+`payload.timestamp`. Then `response_item` (message, function_call,
+function_call_output, reasoning), `event_msg`, `turn_context`. Undocumented
+and version-dependent; unrecognized line types and payload shapes are
+skipped.
+
+Codex has no dedicated "edit file" tool call in the sessions seen so far --
+file edits happen via shell commands run through `exec_command` -- so
+`files_touched` is left empty here; only `commands_run` is populated.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from mainai.models import Session, Turn
+
+
+def _session_bases() -> list[Path]:
+    bases = [Path.home() / ".codex" / "sessions"]
+    snap_root = Path.home() / "snap" / "codex"
+    if snap_root.is_dir():
+        for rev_dir in snap_root.iterdir():
+            candidate = rev_dir / "sessions"
+            if candidate.is_dir():
+                bases.append(candidate)
+    return bases
+
+
+def sessions_for(folder: Path) -> list[Session]:
+    folder = folder.resolve()
+    sessions = []
+    for base in _session_bases():
+        if not base.is_dir():
+            continue
+        for jsonl_path in base.glob("*/*/*/rollout-*.jsonl"):
+            session = _read_session(jsonl_path, folder)
+            if session is not None:
+                sessions.append(session)
+    return sessions
+
+
+def _read_session(path: Path, folder: Path) -> Session | None:
+    session_id: str | None = None
+    cwd: str | None = None
+    start: datetime | None = None
+    end: datetime | None = None
+    turns: list[Turn] = []
+    commands_run: list[str] = []
+
+    try:
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict):
+            continue
+
+        ts = _parse_timestamp(event.get("timestamp"))
+        if ts is not None:
+            if start is None or ts < start:
+                start = ts
+            if end is None or ts > end:
+                end = ts
+
+        event_type = event.get("type")
+        payload = event.get("payload")
+        if not isinstance(payload, dict):
+            continue
+
+        if event_type == "session_meta":
+            session_id = payload.get("id") or payload.get("session_id") or session_id
+            cwd = payload.get("cwd") or cwd
+            continue
+
+        if event_type != "response_item":
+            continue
+
+        item_type = payload.get("type")
+
+        if item_type == "message":
+            role = payload.get("role")
+            if role not in ("user", "assistant"):
+                continue
+            content = payload.get("content")
+            if not isinstance(content, list):
+                continue
+            text = "".join(
+                block.get("text", "")
+                for block in content
+                if isinstance(block, dict)
+                and block.get("type") in ("input_text", "output_text", "text")
+            ).strip()
+            if not text or text.startswith("<environment_context>"):
+                continue
+            turns.append(Turn(role=role, text=text, timestamp=ts))
+        elif item_type == "function_call" and payload.get("name") == "exec_command":
+            try:
+                arguments = json.loads(payload.get("arguments") or "{}")
+            except json.JSONDecodeError:
+                arguments = {}
+            command = arguments.get("cmd")
+            if command:
+                commands_run.append(command)
+
+    if session_id is None or cwd is None or start is None or end is None:
+        return None
+
+    cwd_path = Path(cwd).resolve()
+    if cwd_path != folder and folder not in cwd_path.parents:
+        return None
+
+    return Session(
+        agent="codex",
+        session_id=session_id,
+        cwd=cwd,
+        start=start,
+        end=end,
+        turns=turns,
+        commands_run=commands_run,
+    )
+
+
+def _parse_timestamp(value: object) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None

mainai-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: mainai
+Version: 0.1.0
+Summary: Pick the right coding agent to continue a project with, across Claude Code, Codex, and Grok sessions.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mainai
+
+A CLI that figures out which coding agent (Claude Code, Codex, Grok, ...)
+last did real work in a project folder, and hands off cleanly to the one you
+pick next.
+
+## The problem
+
+Working the same project folders with several coding agents means that
+coming back months later, it's unclear which agent did the most recent real
+work, and what the other agents did in the meantime.
+
+## What it does
+
+```
+$ mainai .
+Found 6 sessions in ~/Dropbox/inflammatix/projects/endotypes
+  codex   2026-09-25  "fix the endotype clustering..."   <- latest work
+  claude  2026-09-18  "add the GSE cohort loader..."
+  ...
+Continue with: Codex (its edits match the current files)
+Wrote HANDOFF.md (summaries of the 4 Claude sessions)
+Launching: codex "Read HANDOFF.md, then continue where we left off."
+```
+
+1. Reads every agent's stored conversations, keeps the ones for the current
+   folder.
+2. Decides which agent to continue with, based on which session's edits
+   match the files actually on disk (not just the newest timestamp).
+3. Summarizes the relevant parts of the *other* agents' sessions into
+   `HANDOFF.md`.
+4. Starts the chosen agent, pointed at `HANDOFF.md`.
+
+`mainai` with no arguments prints help and does nothing, so a stray bare
+invocation never spends LLM usage. Flags: `--list` (sessions + pick only, no
+LLM, no write), `--agent NAME` (override the pick), `--no-launch` (write
+`HANDOFF.md` but don't start the agent).
+
+See `mainai.md` for the full design notes (reader architecture, per-agent log
+formats, picker logic, summarizer, scope/build order).
+
+## Status
+
+Not yet built. Design only.
+
+## Development
+
+uv-managed project.
+
+```bash
+uv sync
+uv run mainai --list .
+```

mainai-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mainai/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+mainai/cli.py,sha256=JbzrtdVqIdT9T58B_Gket3xe2aW5CBKy0Qe5VmJXxsA,4622
+mainai/llm.py,sha256=nm1eiLJ0SjygS8qxviJ5jm1dXKAASVlLFHI6w3sJNTo,3715
+mainai/llm_picker.py,sha256=k0KQLpA4DD8ljApW6QOnXJHPu8gUSQnutQMgONLVYok,3713
+mainai/models.py,sha256=yhCSaG49IvSUTnRFSce5sI9fYZAhzYZ4IdEunxxIc9o,936
+mainai/picker.py,sha256=Wbb0qkFqMezQdpCS9SERGS0psafkfhJnihp91E7gN_E,2678
+mainai/readers/__init__.py,sha256=FYpN7QN8XXoZlSV8PaFhI2yNpkriWs8gAgoIxhk7TX4,749
+mainai/readers/claude_code.py,sha256=hUKHen3jQI0fbriUMKOar0cjglYR23hduWOzWdq5N4A,4408
+mainai/readers/codex.py,sha256=w0_GbbcSCiwzs6HXym1bR2eGBC5F_iJnfuT2ttzpFY4,4571
+mainai-0.1.0.dist-info/METADATA,sha256=xqwzhDQ_MaFCE1RGZ3Z5WlIyPYS1DitKTgWk1k8RRb4,1913
+mainai-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mainai-0.1.0.dist-info/entry_points.txt,sha256=ly6pPJfBEU9FBvlWgKHBfvfbJPH0fgures8s7JaweD4,43
+mainai-0.1.0.dist-info/RECORD,,

mainai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mainai-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mainai = mainai.cli:main