overcode 0.1.0__py3-none-any.whl

overcode/daemon_claude_skill.md

@@ -0,0 +1,180 @@
+# Overcode Supervisor Skill
+
+You are the Overcode supervisor agent. Your mission: **Make all RED sessions GREEN**.
+
+## Your Role
+
+You monitor and unblock Claude agent sessions running in tmux. When sessions get stuck (RED status), you help them make progress by:
+- Reading their output to understand what they're stuck on
+- Making decisions based on their autopilot instructions
+- Approving safe permission requests
+- Sending guidance or clarifying information
+- Having multi-turn conversations with agents
+
+**When all sessions are GREEN, your job is done - exit successfully.**
+
+## How to Control Sessions (Recommended)
+
+Use the `overcode` CLI commands - they're simpler than raw tmux:
+
+### Check Status
+```bash
+# List all agents with status
+overcode list
+
+# See what an agent is stuck on
+overcode show my-agent
+overcode show my-agent --lines 100  # more context
+```
+
+### Unblock Agents
+```bash
+# Send a text response (+ Enter)
+overcode send my-agent "yes"
+overcode send my-agent "Focus on the core feature first"
+
+# Approve a permission request (press Enter)
+overcode send my-agent enter
+
+# Reject a permission request (press Escape)
+overcode send my-agent escape
+```
+
+## Alternative: Direct Tmux Commands
+
+For fine-grained control, use tmux directly:
+
+### Read Session Output
+```bash
+# Read last 50 lines from a session's pane
+tmux capture-pane -t agents:{window_num} -p -S -50
+```
+
+### Send Text to Session
+```bash
+# Send text (no Enter)
+tmux send-keys -t agents:{window_num} "your text here"
+
+# Send text with Enter
+tmux send-keys -t agents:{window_num} "your text here" C-m
+```
+
+### Approve/Reject Permissions
+```bash
+# Approve (press Enter)
+tmux send-keys -t agents:{window_num} "" C-m
+
+# Reject (press Escape)
+tmux send-keys -t agents:{window_num} Escape
+```
+
+### List All Sessions
+```bash
+# See all windows and their status
+tmux list-windows -t agents
+```
+
+## Session State Information
+
+Session states are tracked in `~/.overcode/sessions/sessions.json`. Read this to understand:
+- Session name, window number, autopilot instructions
+- Current status (running/waiting)
+- Standing instructions for the session
+- Repo context and working directory
+
+```bash
+# View all session state
+cat ~/.overcode/sessions/sessions.json | jq
+```
+
+## Approval Rules
+
+You must follow these rules when deciding to approve operations:
+
+### ✅ Auto-Approve (Safe Operations)
+- Read, Write, Edit, Grep, Glob within the session's working directory
+- WebFetch (read-only web requests)
+- git add, git commit, git status, git diff
+- npm install, pip install (dependency management)
+- Running tests (pytest, npm test, etc.)
+
+### ⚠️ Use Judgment (Check Context)
+- git push (only if work is complete and tests pass)
+- Operations near but not in working directory
+- Creating files outside project structure
+
+### ❌ Reject (Unsafe/Out of Scope)
+- Operations outside the working directory entirely
+- rm -rf on large directories
+- Operations on user's personal files (/Users/{user}/Documents, etc.)
+- Network writes to external services (unless explicitly in autopilot goal)
+
+## Workflow Example
+
+```bash
+# 1. Read current session states
+cat ~/.overcode/sessions/sessions.json | jq '.[] | {name, tmux_window, standing_instructions, stats}'
+
+# 2. Find RED sessions
+# Check TUI or parse status
+
+# 3. For each RED session, read output
+tmux capture-pane -t agents:1 -p -S -100
+
+# 4. Make decision based on:
+#    - What they're stuck on
+#    - Their autopilot instruction
+#    - Approval rules
+
+# 5a. If permission request is safe, approve:
+tmux send-keys -t agents:1 "" C-m
+
+# 5b. If they need guidance, send message:
+tmux send-keys -t agents:1 "Focus on the core feature first, implement error handling later." C-m
+
+# 5c. If permission unsafe, reject:
+tmux send-keys -t agents:1 Escape
+
+# 6. Log your action
+echo "$(date): Approved Write permission for recipe-book session (within working dir)" >> ~/.overcode/supervisor.log
+
+# 7. Repeat for other RED sessions
+
+# 8. When all GREEN, exit
+exit 0
+```
+
+## Real Example
+
+**Session:** recipe-book
+**Window:** 1
+**Autopilot:** "Keep organizing recipes into categories"
+**Stuck on:** Permission to write `/home/user/recipes/desserts.md`
+
+```bash
+# Read output to see context
+tmux capture-pane -t agents:1 -p -S -100
+
+# Decision: File is within working directory (/home/user/recipes)
+# Decision: Aligns with "organizing recipes into categories"
+# Decision: APPROVE
+
+# Execute approval
+tmux send-keys -t agents:1 "" C-m
+
+# Log action
+echo "$(date): recipe-book - Approved write to desserts.md (within working dir, aligns with goal)" >> ~/.overcode/supervisor.log
+```
+
+## Your Process
+
+1. **Survey** - Read all session states from sessions.json
+2. **Identify** - Find RED sessions (waiting for user)
+3. **Investigate** - Read their tmux output to see what they're stuck on
+4. **Decide** - Apply approval rules and autopilot context
+5. **Act** - Send tmux commands to unblock them
+6. **Log** - Record your decisions
+7. **Repeat** - Check if more sessions need help
+8. **Exit** - When all GREEN, your job is complete
+
+Remember: You're a decision-making agent that helps other agents make progress. Be helpful but safe. When in doubt, err on the side of caution.

overcode/daemon_state.py

@@ -0,0 +1,113 @@
+"""
+Daemon state management.
+
+Tracks and persists daemon state for communication with the TUI.
+"""
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from .settings import PATHS, DAEMON
+
+
+# Daemon operation modes
+MODE_OFF = "off"           # Daemon not running
+MODE_MONITOR = "monitor"   # Track stats/state but never launch supervisor claude
+MODE_SUPERVISE = "supervise"  # Full supervision (monitor + launch claude when needed)
+
+
+@dataclass
+class DaemonState:
+    """Tracks daemon state for TUI display.
+
+    This class is used by:
+    - The daemon to persist its current state
+    - The TUI to read and display daemon status
+    """
+
+    loop_count: int = 0
+    current_interval: int = field(default_factory=lambda: DAEMON.interval_fast)
+    last_loop_time: Optional[datetime] = None
+    started_at: Optional[datetime] = None
+    status: str = "starting"  # starting, active, idle, sleeping, waiting, supervising, no_agents, stopped
+    last_activity: Optional[datetime] = None
+    daemon_claude_launches: int = 0
+    mode: str = MODE_SUPERVISE  # off, monitor, supervise
+
+    def to_dict(self) -> dict:
+        """Convert state to dictionary for JSON serialization."""
+        return {
+            "loop_count": self.loop_count,
+            "current_interval": self.current_interval,
+            "last_loop_time": self.last_loop_time.isoformat() if self.last_loop_time else None,
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "status": self.status,
+            "last_activity": self.last_activity.isoformat() if self.last_activity else None,
+            "daemon_claude_launches": self.daemon_claude_launches,
+            "mode": self.mode,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "DaemonState":
+        """Create state from dictionary."""
+        state = cls()
+        state.loop_count = data.get("loop_count", 0)
+        state.current_interval = data.get("current_interval", DAEMON.interval_fast)
+        state.status = data.get("status", "unknown")
+        state.daemon_claude_launches = data.get("daemon_claude_launches", 0)
+        state.mode = data.get("mode", MODE_SUPERVISE)
+
+        if data.get("last_loop_time"):
+            state.last_loop_time = datetime.fromisoformat(data["last_loop_time"])
+        if data.get("started_at"):
+            state.started_at = datetime.fromisoformat(data["started_at"])
+        if data.get("last_activity"):
+            state.last_activity = datetime.fromisoformat(data["last_activity"])
+
+        return state
+
+    def save(self, state_file: Optional[Path] = None) -> None:
+        """Save state to file for TUI to read.
+
+        Args:
+            state_file: Optional path override (for testing)
+        """
+        path = state_file or PATHS.daemon_state
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def load(cls, state_file: Optional[Path] = None) -> Optional["DaemonState"]:
+        """Load state from file (used by TUI).
+
+        Args:
+            state_file: Optional path override (for testing)
+
+        Returns:
+            DaemonState if file exists and is valid, None otherwise
+        """
+        path = state_file or PATHS.daemon_state
+        if not path.exists():
+            return None
+
+        try:
+            with open(path) as f:
+                data = json.load(f)
+            return cls.from_dict(data)
+        except (json.JSONDecodeError, KeyError, ValueError):
+            return None
+
+
+def get_daemon_state() -> Optional[DaemonState]:
+    """Get the current daemon state from file.
+
+    Convenience function for TUI and other consumers.
+
+    Returns:
+        DaemonState if daemon is running and state file exists, None otherwise
+    """
+    return DaemonState.load()

overcode/data_export.py

@@ -0,0 +1,257 @@
+"""
+Data export functionality for Overcode.
+
+Exports session data to Parquet format for analysis in Jupyter notebooks.
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+from .session_manager import SessionManager
+from .status_history import read_agent_status_history
+from .presence_logger import read_presence_history
+
+
+def export_to_parquet(
+    output_path: str,
+    include_archived: bool = True,
+    include_timeline: bool = True,
+    include_presence: bool = True,
+) -> Dict[str, Any]:
+    """Export overcode data to Parquet format.
+
+    Creates a multi-table parquet file suitable for pandas analysis.
+
+    Args:
+        output_path: Path to output parquet file
+        include_archived: Include archived sessions
+        include_timeline: Include agent status timeline
+        include_presence: Include user presence data
+
+    Returns:
+        Dict with counts of exported data
+
+    Raises:
+        ImportError: If pyarrow is not installed
+    """
+    try:
+        import pyarrow as pa
+        import pyarrow.parquet as pq
+    except ImportError:
+        raise ImportError(
+            "pyarrow is required for parquet export. "
+            "Install it with: pip install pyarrow"
+        )
+
+    sessions = SessionManager()
+    result = {
+        "sessions_count": 0,
+        "archived_count": 0,
+        "timeline_rows": 0,
+        "presence_rows": 0,
+    }
+
+    # Collect session data
+    session_records = []
+
+    # Active sessions
+    for s in sessions.list_sessions():
+        record = _session_to_record(s, is_archived=False)
+        session_records.append(record)
+
+    result["sessions_count"] = len(session_records)
+
+    # Archived sessions
+    if include_archived:
+        archived = sessions.list_archived_sessions()
+        for s in archived:
+            record = _session_to_record(s, is_archived=True)
+            record["end_time"] = getattr(s, "_end_time", None)
+            session_records.append(record)
+        result["archived_count"] = len(archived)
+
+    # Build sessions table
+    sessions_table = _build_sessions_table(session_records)
+
+    # Build timeline table
+    timeline_table = None
+    if include_timeline:
+        timeline_records = _build_timeline_records()
+        if timeline_records:
+            timeline_table = _build_timeline_table(timeline_records)
+            result["timeline_rows"] = len(timeline_records)
+
+    # Build presence table
+    presence_table = None
+    if include_presence:
+        presence_records = _build_presence_records()
+        if presence_records:
+            presence_table = _build_presence_table(presence_records)
+            result["presence_rows"] = len(presence_records)
+
+    # Write to parquet
+    # Use a directory-based approach for multiple tables
+    output = Path(output_path)
+    if output.suffix != ".parquet":
+        output = output.with_suffix(".parquet")
+
+    # For simplicity, write sessions as the main table
+    # with timeline and presence as separate files if requested
+    pq.write_table(sessions_table, output)
+
+    # Write additional tables as separate files
+    if timeline_table is not None:
+        timeline_path = output.with_stem(output.stem + "_timeline")
+        pq.write_table(timeline_table, timeline_path)
+
+    if presence_table is not None:
+        presence_path = output.with_stem(output.stem + "_presence")
+        pq.write_table(presence_table, presence_path)
+
+    return result
+
+
+def _session_to_record(session, is_archived: bool) -> Dict[str, Any]:
+    """Convert a Session to a flat dictionary record."""
+    stats = session.stats
+    return {
+        "id": session.id,
+        "name": session.name,
+        "tmux_session": session.tmux_session,
+        "tmux_window": session.tmux_window,
+        "start_directory": session.start_directory,
+        "start_time": session.start_time,
+        "end_time": None,  # Set for archived
+        "repo_name": session.repo_name,
+        "branch": session.branch,
+        "status": session.status,
+        "is_archived": is_archived,
+        "permissiveness_mode": session.permissiveness_mode,
+        "standing_instructions": session.standing_instructions,
+        "standing_instructions_preset": session.standing_instructions_preset,
+        # Stats
+        "interaction_count": stats.interaction_count,
+        "estimated_cost_usd": stats.estimated_cost_usd,
+        "total_tokens": stats.total_tokens,
+        "input_tokens": stats.input_tokens,
+        "output_tokens": stats.output_tokens,
+        "cache_creation_tokens": stats.cache_creation_tokens,
+        "cache_read_tokens": stats.cache_read_tokens,
+        "steers_count": stats.steers_count,
+        "last_activity": stats.last_activity,
+        "current_task": stats.current_task,
+        "current_state": stats.current_state,
+        "state_since": stats.state_since,
+        "green_time_seconds": stats.green_time_seconds,
+        "non_green_time_seconds": stats.non_green_time_seconds,
+        "last_stats_update": stats.last_stats_update,
+    }
+
+
+def _build_sessions_table(records):
+    """Build a PyArrow table from session records."""
+    import pyarrow as pa
+
+    if not records:
+        # Return empty table with schema
+        schema = pa.schema([
+            ("id", pa.string()),
+            ("name", pa.string()),
+            ("start_time", pa.string()),
+            ("end_time", pa.string()),
+            ("is_archived", pa.bool_()),
+            ("interaction_count", pa.int64()),
+            ("total_tokens", pa.int64()),
+            ("estimated_cost_usd", pa.float64()),
+            ("green_time_seconds", pa.float64()),
+            ("non_green_time_seconds", pa.float64()),
+        ])
+        # Create empty arrays for each column
+        empty_arrays = {field.name: pa.array([], type=field.type) for field in schema}
+        return pa.table(empty_arrays, schema=schema)
+
+    # Build arrays from records
+    arrays = {}
+    for key in records[0].keys():
+        values = [r.get(key) for r in records]
+        arrays[key] = values
+
+    return pa.table(arrays)
+
+
+def _build_timeline_records():
+    """Build timeline records from agent status history."""
+    records = []
+
+    # Read last 24 hours of timeline data
+    # Returns List[Tuple[datetime, agent, status, activity]]
+    history = read_agent_status_history(hours=24.0)
+
+    for ts, agent_name, status, activity in history:
+        records.append({
+            "timestamp": ts.isoformat() if isinstance(ts, datetime) else str(ts),
+            "agent": agent_name,
+            "status": status,
+        })
+
+    return records
+
+
+def _build_timeline_table(records):
+    """Build a PyArrow table from timeline records."""
+    import pyarrow as pa
+
+    if not records:
+        schema = pa.schema([
+            ("timestamp", pa.string()),
+            ("agent", pa.string()),
+            ("status", pa.string()),
+        ])
+        empty_arrays = {field.name: pa.array([], type=field.type) for field in schema}
+        return pa.table(empty_arrays, schema=schema)
+
+    arrays = {}
+    for key in records[0].keys():
+        values = [r.get(key) for r in records]
+        arrays[key] = values
+
+    return pa.table(arrays)
+
+
+def _build_presence_records():
+    """Build presence records from presence log."""
+    records = []
+
+    # Read last 24 hours of presence data
+    history = read_presence_history(hours=24.0)
+
+    for ts, state in history:
+        records.append({
+            "timestamp": ts.isoformat() if isinstance(ts, datetime) else str(ts),
+            "state": state,
+            "state_name": {1: "locked", 2: "inactive", 3: "active"}.get(state, "unknown"),
+        })
+
+    return records
+
+
+def _build_presence_table(records):
+    """Build a PyArrow table from presence records."""
+    import pyarrow as pa
+
+    if not records:
+        schema = pa.schema([
+            ("timestamp", pa.string()),
+            ("state", pa.int64()),
+            ("state_name", pa.string()),
+        ])
+        empty_arrays = {field.name: pa.array([], type=field.type) for field in schema}
+        return pa.table(empty_arrays, schema=schema)
+
+    arrays = {}
+    for key in records[0].keys():
+        values = [r.get(key) for r in records]
+        arrays[key] = values
+
+    return pa.table(arrays)