overcode 0.3.0__tar.gz → 0.3.1__tar.gz

{overcode-0.3.0/src/overcode.egg-info → overcode-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overcode
-Version: 0.3.0
+Version: 0.3.1
 Summary: A supervisor for managing multiple Claude Code instances in tmux
 Author: Mike Bond
 Project-URL: Homepage, https://github.com/mkb23/overcode

{overcode-0.3.0 → overcode-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "overcode"
-version = "0.3.0"
+version = "0.3.1"
 description = "A supervisor for managing multiple Claude Code instances in tmux"
 authors = [
     {name = "Mike Bond"}

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/bundled_skills.py

@@ -82,6 +82,26 @@ overcode send my-agent escape    # Reject permission
 overcode send my-agent "yes"     # Send text response
 ```
 
+## Jobs (Long-Running Bash Commands)
+
+For long-running commands (10min+ \u2014 test suites, builds, deploys), use `overcode bash` to launch them as tracked jobs in a separate tmux session. This keeps the output visible and lets you monitor multiple concurrent jobs from the TUI.
+
+```bash
+# Launch a job
+overcode bash "pytest tests/ -x" --name unit-tests
+overcode bash "npm run build" -d ~/frontend
+overcode bash "make deploy-staging" --agent my-agent   # Link to an agent
+
+# Manage jobs
+overcode jobs list [--all]        # List running (or all) jobs
+overcode jobs kill <name>         # Kill a running job
+overcode jobs attach <name>       # Attach to job's tmux window
+overcode jobs clear               # Remove completed/failed/killed jobs
+
+# TUI: press J to toggle jobs view, j/k to navigate, x to kill, c to clear
+overcode monitor --jobs           # Start TUI directly in jobs view
+```
+
 ## Standing Instructions Presets
 
 `overcode instruct <name> <preset>` \u2014 available presets: `DO_NOTHING`, `STANDARD`, `PERMISSIVE`, `CAUTIOUS`, `RESEARCH`, `CODING`, `TESTING`, `REVIEW`, `DEPLOY`, `AUTONOMOUS`, `MINIMAL`.
@@ -194,6 +214,30 @@ Pass arbitrary Claude CLI flags with `--claude-arg` (repeatable):
 overcode launch -n fast --claude-arg "--model haiku" --claude-arg "--effort low" -p "Quick review"
 ```
 
+## Long-Running Shell Commands (Jobs)
+
+When a task involves a long-running shell command (10min+ \u2014 full test suites, builds, deploys, docker compose), use `overcode bash` instead of running it inline. This launches the command as a tracked job in a separate tmux session with its own window, so you can monitor it without blocking your agent session.
+
+```bash
+# Launch a test suite as a tracked job
+overcode bash "pytest tests/ -x --timeout=600" --name full-tests
+
+# Launch a build linked to the current agent
+overcode bash "npm run build" --name frontend-build --agent my-agent
+
+# Check on it later
+overcode jobs list
+overcode jobs attach full-tests    # Attach to see live output
+overcode jobs kill full-tests      # Kill if needed
+```
+
+**When to use `overcode bash` vs running inline:**
+- Inline (`Bash` tool): Quick commands (<2 min) where you need the result to continue
+- `overcode bash`: Long commands (10min+) \u2014 test suites, builds, deploys, docker operations
+- `overcode launch`: When you need a full Claude Code agent with AI reasoning
+
+Jobs are visible in the TUI jobs view (press `J`) and auto-clean after 24h (configurable via `jobs.retention_hours` in config).
+
 ## Rules
 
 - Parent auto-detected from `OVERCODE_SESSION_NAME` \u2014 no `--parent` needed inside an overcode agent

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/cli/__init__.py

@@ -22,6 +22,7 @@ from . import daemon  # noqa: F401
 from . import sister  # noqa: F401
 from . import config  # noqa: F401
 from . import split  # noqa: F401
+from . import jobs  # noqa: F401
 
 
 def main():

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/cli/_shared.py

@@ -76,6 +76,14 @@ sister_app = typer.Typer(
 )
 app.add_typer(sister_app, name="sister")
 
+# Jobs subcommand group
+jobs_app = typer.Typer(
+    name="jobs",
+    help="Manage overcode jobs.",
+    no_args_is_help=True,
+)
+app.add_typer(jobs_app, name="jobs")
+
 # Config subcommand group
 config_app = typer.Typer(
     name="config",

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/cli/agent.py

@@ -192,6 +192,10 @@ def launch(
         Optional[str],
         typer.Option("--allowed-tools", help="Comma-separated tools for Claude (e.g. 'Bash,Read,Write,Edit')"),
     ] = None,
+    model: Annotated[
+        Optional[str],
+        typer.Option("--model", "-m", help="Claude model (e.g. sonnet, opus, haiku, or full name)"),
+    ] = None,
     claude_args: Annotated[
         Optional[List[str]],
         typer.Option("--claude-arg", help="Extra Claude CLI flag (repeatable, e.g. '--model haiku')"),
@@ -283,6 +287,7 @@ def launch(
         agent_teams=teams,
         budget_usd=budget,
         claude_agent=agent,
+        model=model,
     )
 
     if result:
@@ -536,6 +541,9 @@ def list_agents(
             claude_stats = get_session_stats(sess)
         except Exception:
             pass
+        if claude_stats is None and getattr(sess, 'is_remote', False):
+            from ..history_reader import synthesize_remote_stats
+            claude_stats = synthesize_remote_stats(sess)
 
         git_diff = None
         if getattr(sess, 'is_remote', False):

overcode-0.3.1/src/overcode/cli/jobs.py

@@ -0,0 +1,156 @@
+"""
+CLI commands for managing overcode jobs.
+"""
+
+from typing import Annotated, Optional
+
+import typer
+from rich import print as rprint
+
+from ._shared import app, jobs_app
+
+
+@app.command()
+def bash(
+    command: Annotated[str, typer.Argument(help="Bash command to run as a tracked job")],
+    name: Annotated[Optional[str], typer.Option("--name", "-n", help="Job name (auto-derived if omitted)")] = None,
+    directory: Annotated[str, typer.Option("--directory", "-d", help="Working directory")] = ".",
+    agent: Annotated[Optional[str], typer.Option("--agent", "-a", help="Link to an agent session by name")] = None,
+    follow: Annotated[bool, typer.Option("--follow", "-f", help="Attach to the job's tmux window after launch")] = True,
+):
+    """Launch a bash command as a tracked job."""
+    import os
+    from ..job_launcher import JobLauncher
+    from ..session_manager import SessionManager
+
+    directory = os.path.abspath(directory)
+
+    agent_session_id = None
+    agent_name = None
+    # Auto-detect calling agent from env if --agent not specified
+    if not agent:
+        agent = os.environ.get("OVERCODE_SESSION_NAME")
+    if agent:
+        sm = SessionManager()
+        sess = sm.get_session_by_name(agent)
+        if sess:
+            agent_session_id = sess.id
+            agent_name = sess.name
+        else:
+            rprint(f"[yellow]Warning: Agent '{agent}' not found, launching without link[/yellow]")
+
+    launcher = JobLauncher()
+    job = launcher.launch(
+        command=command,
+        name=name,
+        directory=directory,
+        agent_session_id=agent_session_id,
+        agent_name=agent_name,
+    )
+
+    rprint(f"[green]✓[/green] Job '[bold]{job.name}[/bold]' launched")
+    rprint(f"  Command: {job.command}")
+    rprint(f"  Window: {job.tmux_session}:{job.tmux_window}")
+    if agent_name:
+        rprint(f"  Linked to agent: {agent_name}")
+
+    if follow:
+        launcher.attach(job.name)
+
+
+@jobs_app.command("list")
+def list_jobs(
+    all: Annotated[bool, typer.Option("--all", "-a", help="Include completed/failed/killed jobs")] = False,
+):
+    """List tracked jobs."""
+    from ..job_launcher import JobLauncher
+
+    launcher = JobLauncher()
+    jobs = launcher.list_jobs(include_completed=all)
+
+    if not jobs:
+        rprint("[dim]No jobs running[/dim]" if not all else "[dim]No jobs found[/dim]")
+        return
+
+    for job in sorted(jobs, key=lambda j: j.start_time, reverse=True):
+        status_icon = {
+            "running": "[green]●[/green]",
+            "completed": "[green]✓[/green]",
+            "failed": "[red]✗[/red]",
+            "killed": "[yellow]✗[/yellow]",
+        }.get(job.status, "?")
+
+        exit_str = ""
+        if job.exit_code is not None:
+            exit_str = f" ({job.exit_code})"
+
+        duration = ""
+        if job.start_time:
+            from datetime import datetime
+            try:
+                start = datetime.fromisoformat(job.start_time)
+                end = datetime.fromisoformat(job.end_time) if job.end_time else datetime.now()
+                dur_sec = (end - start).total_seconds()
+                mins, secs = divmod(int(dur_sec), 60)
+                duration = f"{mins}m{secs:02d}s"
+            except ValueError:
+                pass
+
+        agent_str = f" ← {job.agent_name}" if job.agent_name else ""
+        rprint(
+            f"  {status_icon} {job.name:<16} {job.command:<30} {duration:>8}   "
+            f"{job.status}{exit_str}{agent_str}"
+        )
+
+
+@jobs_app.command("kill")
+def kill_job(
+    name: Annotated[str, typer.Argument(help="Job name to kill")],
+):
+    """Kill a running job."""
+    from ..job_launcher import JobLauncher
+
+    launcher = JobLauncher()
+    if launcher.kill_job(name):
+        rprint(f"[green]✓[/green] Job '[bold]{name}[/bold]' killed")
+    else:
+        rprint(f"[red]✗[/red] Could not kill job '{name}' (not found or not running)")
+        raise typer.Exit(1)
+
+
+@jobs_app.command("attach")
+def attach_job(
+    name: Annotated[str, typer.Argument(help="Job name to attach to")],
+    bare: Annotated[bool, typer.Option("--bare", "-b", help="Attach with stripped tmux chrome")] = False,
+):
+    """Attach to a job's tmux window."""
+    from ..job_launcher import JobLauncher
+
+    launcher = JobLauncher()
+    try:
+        launcher.attach(name, bare=bare)
+    except ValueError as e:
+        rprint(f"[red]✗[/red] {e}")
+        raise typer.Exit(1)
+
+
+@jobs_app.command("clear")
+def clear_completed():
+    """Remove all completed/failed/killed jobs."""
+    from ..job_manager import JobManager
+
+    manager = JobManager()
+    manager.clear_completed()
+    rprint("[green]✓[/green] Cleared completed jobs")
+
+
+@jobs_app.command("_complete", hidden=True)
+def mark_complete(
+    job_id: Annotated[str, typer.Argument(help="Job ID")],
+    exit_code: Annotated[int, typer.Argument(help="Exit code")],
+):
+    """Internal: mark a job as complete (called by wrapper script)."""
+    from ..job_manager import JobManager
+
+    manager = JobManager()
+    manager.mark_complete(job_id, exit_code)

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/cli/monitoring.py

@@ -273,6 +273,9 @@ def monitor(
     sync_target: Annotated[
         str, typer.Option("--sync-target", hidden=True, help="Linked tmux session for pane sync (set by `overcode split`)")
     ] = "",
+    jobs: Annotated[
+        bool, typer.Option("--jobs", help="Start in jobs view")
+    ] = False,
 ):
     """Launch the standalone TUI monitor."""
     if restart:
@@ -299,7 +302,7 @@ def monitor(
 
     from ..tui import run_tui
 
-    run_tui(session, diagnostics=diagnostics, sync_target=sync_target or None)
+    run_tui(session, diagnostics=diagnostics, sync_target=sync_target or None, initial_jobs_mode=jobs)
 
 
 @app.command()

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/cli/split.py

@@ -191,7 +191,7 @@ def _remove_keybindings() -> None:
     from ..config import get_tmux_toggle_key
 
     toggle_key = get_tmux_toggle_key() or DEFAULT_TOGGLE_KEY
-    keys = [toggle_key, "M-j", "M-k", "PPage", "NPage", "WheelUpPane", "WheelDownPane"]
+    keys = [toggle_key, "M-j", "M-k", "M-b", "PPage", "NPage", "WheelUpPane", "WheelDownPane"]
     # Also unbind Tab if toggle_key changed away from it (stale binding)
     if toggle_key != "Tab":
         keys.append("Tab")
@@ -248,6 +248,13 @@ def _setup_keybindings(linked_session: str = "", toggle_key: str = "") -> None:
         f"send-keys -t overcode:{SPLIT_WINDOW_NAME}.0 k",
         "send-keys M-k",
     )
+    # Option+B: navigate to bell (next agent needing attention)
+    _tmux(
+        "bind-key", "-n", "M-b",
+        "if-shell", "-F", _in_bottom,
+        f"send-keys -t overcode:{SPLIT_WINDOW_NAME}.0 b",
+        "send-keys M-b",
+    )
 
     # --- Scrollback for the nested tmux in the bottom pane ---
     # The bottom pane runs a nested tmux client. The outer tmux

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/config.py

@@ -342,6 +342,19 @@ def save_new_agent_defaults(defaults: dict) -> None:
     save_config(config)
 
 
+def get_jobs_retention_hours() -> float:
+    """Get job retention period in hours.
+
+    Config format in ~/.overcode/config.yaml:
+        jobs:
+          retention_hours: 24
+
+    Returns:
+        Retention hours (default 24)
+    """
+    return float(_get_config_value("jobs.retention_hours", 24))
+
+
 def get_sisters_config() -> List[dict]:
     """Get sister instance configuration for cross-machine monitoring.
 

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/history_reader.py

@@ -99,6 +99,28 @@ class ClaudeSessionStats:
         return sorted_times[n // 2]
 
 
+def synthesize_remote_stats(session) -> "ClaudeSessionStats":
+    """Synthesize ClaudeSessionStats for a remote session from daemon_state.
+
+    Remote sessions carry a remote_daemon_state dict with all
+    SessionDaemonState fields. Extract what we need so that render
+    columns (cost, tokens, context %, model) display correctly.
+    """
+    rds = getattr(session, 'remote_daemon_state', None) or {}
+    stats = session.stats
+    mwt = getattr(session, 'remote_median_work_time', None) or rds.get('median_work_time', 0.0)
+    return ClaudeSessionStats(
+        interaction_count=stats.interaction_count,
+        input_tokens=rds.get('input_tokens', stats.total_tokens),
+        output_tokens=rds.get('output_tokens', 0),
+        cache_creation_tokens=rds.get('cache_creation_tokens', 0),
+        cache_read_tokens=rds.get('cache_read_tokens', 0),
+        work_times=[mwt] if mwt > 0 else [],
+        current_context_tokens=rds.get('current_context_tokens', 0),
+        model=rds.get('model'),
+    )
+
+
 @dataclass
 class HistoryEntry:
     """A single interaction from Claude Code history."""

{overcode-0.3.0 → overcode-0.3.1}/src/overcode/implementations.py

@@ -235,6 +235,16 @@ class RealTmux:
         from .tmux_utils import attach_bare
         attach_bare(session, window)
 
+    def get_pane_pid(self, session: str, window: str) -> Optional[int]:
+        """Get the PID of the shell process in a window's first pane."""
+        try:
+            pane = self._get_pane(session, window)
+            if pane is None:
+                return None
+            return int(pane.pane_pid)
+        except (LibTmuxException, ValueError, TypeError):
+            return None
+
     def select_window(self, session: str, window: str) -> bool:
         """Select a window in a tmux session (for external pane sync)."""
         try:
@@ -246,6 +256,33 @@ class RealTmux:
         except LibTmuxException:
             return False
 
+    def resize_window(self, session: str, window: str, width: int, height: int) -> bool:
+        """Resize a tmux window to match terminal dimensions.
+
+        Used to fix window size mismatches when switching between sessions
+        after terminal resize (#245).
+
+        Args:
+            session: Session name
+            window: Window name/index
+            width: Target width in columns
+            height: Target height in rows
+
+        Returns:
+            True if resize succeeded, False otherwise
+        """
+        try:
+            # Use tmux resize-window command
+            # Format: session:window.pane
+            target = f"{session}:{window}"
+            result = self.run(
+                ["tmux", "resize-window", "-t", target, "-x", str(width), "-y", str(height)],
+                timeout=2
+            )
+            return result is not None and result.get("returncode") == 0
+        except Exception:
+            return False
+
 
 class RealFileSystem:
     """Production implementation of FileSystemInterface"""

overcode-0.3.1/src/overcode/job_launcher.py

@@ -0,0 +1,211 @@
+"""
+Job launcher for Overcode.
+
+Launches bash commands as tracked jobs in a dedicated "jobs" tmux session.
+"""
+
+import os
+import shlex
+import subprocess
+import uuid as _uuid
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from .job_manager import Job, JobManager, _slugify_command
+from .tmux_manager import TmuxManager
+
+
+class JobLauncher:
+    """Launches and manages bash jobs in a dedicated tmux session."""
+
+    def __init__(
+        self,
+        tmux_session: str = "jobs",
+        tmux_manager: Optional[TmuxManager] = None,
+        job_manager: Optional[JobManager] = None,
+    ):
+        self.tmux_session = tmux_session
+        self.tmux = tmux_manager or TmuxManager(session_name=tmux_session)
+        self.jobs = job_manager or JobManager()
+
+    def launch(
+        self,
+        command: str,
+        name: Optional[str] = None,
+        directory: Optional[str] = None,
+        agent_session_id: Optional[str] = None,
+        agent_name: Optional[str] = None,
+    ) -> Job:
+        """Launch a bash command as a tracked job.
+
+        Creates a tmux window, sends a wrapper script that reports completion,
+        and persists the job to state.
+        """
+        directory = directory or os.getcwd()
+        base_name = name or _slugify_command(command)
+        auto_name = f"{base_name}-{_uuid.uuid4().hex[:4]}"
+
+        # Create job first to get the ID
+        job = self.jobs.create_job(
+            command=command,
+            name=auto_name,
+            start_directory=directory,
+            agent_session_id=agent_session_id,
+            agent_name=agent_name,
+        )
+
+        # Create tmux window
+        window_name = job.name
+        self.tmux.ensure_session()
+        result = self.tmux.create_window(window_name, start_directory=directory)
+        if result is None:
+            # Cleanup on failure
+            self.jobs.delete_job(job.id)
+            raise RuntimeError(f"Failed to create tmux window for job '{job.name}'")
+
+        # Update job with actual window name
+        self.jobs.update_job(job.id, tmux_window=result)
+        job.tmux_window = result
+
+        # Build wrapper script that runs the command and reports completion.
+        # The exit code is written to a file as a fallback — if the _complete
+        # call doesn't run, the process monitor can still read it.
+        escaped_cmd = command.replace("'", "'\\''")
+        escaped_dir = shlex.quote(directory)
+        exit_file = self._exit_code_path(job.id)
+        wrapper = (
+            f"echo '╭─── Job: {job.name}' && "
+            f"echo '│ Command: {command}' && "
+            f"echo '│ Directory: {directory}' && "
+            f"echo '│ Started: {job.start_time}' && "
+            f"echo '╰───────────────────────────────────' && "
+            f"echo '' && "
+            f"cd {escaped_dir} && "
+            f"eval '{escaped_cmd}'; "
+            f"__oc_exit=$?; "
+            f"echo $__oc_exit > {exit_file}; "
+            f"echo ''; "
+            f"echo '╭─── Job finished ───'; "
+            f"echo \"│ Exit code: $__oc_exit\"; "
+            f"echo '╰───────────────────'; "
+            f"overcode jobs _complete {job.id} $__oc_exit; "
+            f"exec bash"
+        )
+
+        # Send the wrapper to tmux
+        self.tmux.send_keys(result, wrapper)
+
+        return job
+
+    def list_jobs(self, include_completed: bool = False, detect_killed: bool = True) -> List[Job]:
+        """List jobs, cross-referencing tmux to detect killed/completed jobs.
+
+        Detection layers for running jobs:
+        1. Window gone + no _complete call → killed
+        2. Window alive but shell has no child processes → command finished,
+           read exit code from file and mark completed/failed
+        """
+        jobs = self.jobs.list_jobs(include_completed=include_completed)
+
+        if not detect_killed:
+            return jobs
+
+        # Get list of actual tmux windows
+        windows = self.tmux.list_windows()
+        window_names = {w['name'] for w in windows}
+
+        for job in jobs:
+            if job.status != "running":
+                continue
+
+            if job.tmux_window not in window_names:
+                # Window gone but no _complete called → killed
+                self.jobs.update_job(
+                    job.id,
+                    status="killed",
+                    end_time=datetime.now().isoformat(),
+                )
+                job.status = "killed"
+                job.end_time = datetime.now().isoformat()
+                continue
+
+            # Window still alive — check if the command has finished by
+            # looking for child processes of the pane's shell.
+            pane_pid = self.tmux.get_pane_pid(job.tmux_window)
+            if pane_pid is not None and not _has_child_processes(pane_pid):
+                exit_code = self._read_exit_code(job.id)
+                status = "completed" if exit_code == 0 else "failed"
+                now = datetime.now().isoformat()
+                self.jobs.mark_complete(job.id, exit_code)
+                job.status = status
+                job.exit_code = exit_code
+                job.end_time = now
+                self._cleanup_exit_code_file(job.id)
+
+        return jobs
+
+    def kill_job(self, name: str) -> bool:
+        """Kill a job by name."""
+        job = self.jobs.get_job_by_name(name)
+        if not job:
+            return False
+
+        if job.status != "running":
+            return False
+
+        # Kill the tmux window
+        killed = self.tmux.kill_window(job.tmux_window)
+
+        # Update state
+        self.jobs.update_job(
+            job.id,
+            status="killed",
+            end_time=datetime.now().isoformat(),
+        )
+
+        return killed
+
+    def attach(self, name: str, bare: bool = False):
+        """Attach terminal to a job's tmux window."""
+        job = self.jobs.get_job_by_name(name)
+        if not job:
+            raise ValueError(f"Job '{name}' not found")
+
+        self.tmux.attach_session(window=job.tmux_window, bare=bare)
+
+    @staticmethod
+    def _exit_code_path(job_id: str) -> Path:
+        """Path to the exit code file for a job."""
+        env_state_dir = os.environ.get("OVERCODE_STATE_DIR")
+        base = Path(env_state_dir) / "jobs" if env_state_dir else Path.home() / ".overcode" / "jobs"
+        return base / f"exit-{job_id}"
+
+    def _read_exit_code(self, job_id: str) -> int:
+        """Read exit code from file, defaulting to 0 if missing/unreadable."""
+        path = self._exit_code_path(job_id)
+        try:
+            return int(path.read_text().strip())
+        except (FileNotFoundError, ValueError, OSError):
+            return 0
+
+    def _cleanup_exit_code_file(self, job_id: str):
+        """Remove the exit code file after reading it."""
+        try:
+            self._exit_code_path(job_id).unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def _has_child_processes(pid: int) -> bool:
+    """Check if a process has any child processes."""
+    try:
+        result = subprocess.run(
+            ["pgrep", "-P", str(pid)],
+            capture_output=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        # If we can't check, assume still running
+        return True