overcode 0.2.6__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overcode
-Version: 0.2.6
+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
@@ -51,21 +51,16 @@ Launch autonomous coding agents, monitor their progress in real-time, track cost
 Running multiple Claude Code agents is powerful, but managing them gets chaotic fast. Overcode solves this by giving you:
 
 - **Unified visibility** - See all agents at a glance: what they're working on, whether they need input, and how much they're costing you
+- **Native tmux integration** - A split layout with your dashboard on top and the focused agent's live terminal below—full speed, full color, full scrollback
 - **Smart orchestration** - An optional supervisor daemon can approve prompts and keep agents moving without constant attention
-- **Efficiency metrics** - Track "green time" (Claude actively working) vs idle time to understand where time goes
+- **Multi-machine monitoring** - Sister integration aggregates agents from multiple machines into one view
 - **Session persistence** - Agents run in tmux, surviving terminal disconnects. Pick up where you left off
 
-## Screenshots
+## Screenshot
 
-**Split-screen with tmux sync** - Monitor agents in the top pane while viewing live agent output below. Press `p` to enable pane sync, then navigate with `j/k` to switch the bottom pane to the selected agent's window.
+**Tmux split layout** — Monitor all agents in the top pane. The bottom pane shows the selected agent's live terminal. Navigate with `j/k` and the bottom pane follows. Press `Tab` to switch focus between panes.
 
-![Overcode split-screen with tmux sync](docs/images/overcode-split-screen.png)
-
-> **iTerm2 setup**: Use `Cmd+Shift+D` to split horizontally. Run `overcode monitor` in the top pane and `tmux attach -t agents` in the bottom pane.
-
-**Preview mode** - Press `m` to toggle List+Preview mode. Shows collapsed agent list with detailed terminal output preview for the selected agent.
-
-![Overcode preview mode](docs/images/overcode-preview-mode.png)
+![Overcode v0.3.0 tmux split layout](docs/screenshots/overcode-v0p3p0.jpg)
 
 ## Quick Start
 
@@ -75,16 +70,32 @@ Try it instantly with [uvx](https://docs.astral.sh/uv/):
 uvx overcode monitor
 ```
 
-This opens the dashboard. Press `n` to create your first agent—give it a name, point it at a project directory, and optionally provide an initial prompt. Create a few agents to see them work in parallel.
+This opens the standalone dashboard. Press `n` to create your first agent.
 
-**Requirements:** Python 3.12+, tmux, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+For the full tmux-native experience (recommended):
 
-For permanent installation: `pip install overcode`
+```bash
+pip install overcode
+overcode tmux
+```
+
+This creates a split layout: the overcode dashboard on top, the focused agent's live terminal on the bottom. Navigate agents with `j/k` — the bottom pane follows automatically. Press `Tab` to toggle focus between panes.
+
+**Requirements:** Python 3.12+, tmux, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 
 See the [Getting Started Guide](docs/getting-started.md) for a complete walkthrough.
 
 ## Features
 
+### Tmux Split Layout (`overcode tmux`)
+The recommended way to use overcode. Creates a two-pane layout in tmux:
+- **Top pane**: Compact agent dashboard with live status
+- **Bottom pane**: The focused agent's native terminal — no emulation, real tmux
+- `j/k` navigates agents, bottom pane follows
+- `Tab` toggles focus between dashboard and terminal
+- `Option+J/K` navigates agents from the terminal pane
+- `PageUp/Down` and mouse scroll work in the bottom pane
+
 ### Real-time Dashboard
 The TUI displays all agents with live status updates, showing:
 - Current activity and AI-generated summaries
@@ -97,8 +108,9 @@ The TUI displays all agents with live status updates, showing:
 - **Launch agents** with custom prompts and permission settings
 - **Send instructions** directly from the dashboard
 - **Standing orders** - persistent instructions that guide agent behavior
+- **Agent hierarchy** - parent/child delegation with follow mode and reporting
+- **Cost budgets** - per-agent spending limits with automatic enforcement
 - **Sleep mode** - pause agents and exclude them from stats
-- **Priority sorting** - organize agents by importance
 
 ### Supervisor Daemon
 An optional Claude-powered orchestrator that:
@@ -107,26 +119,31 @@ An optional Claude-powered orchestrator that:
 - Follows per-agent standing orders
 - Tracks interventions and steering decisions
 
+### Sister Integration
+Aggregate agents from multiple machines into one dashboard:
+- Configure sister machines in `~/.overcode/config.yaml`
+- Remote agents appear alongside local ones
+- In tmux split mode, selecting a sister agent auto-zooms the dashboard with a preview pane
+
 ### Analytics & Export
 - **Web dashboard** - mobile-friendly monitoring from any device
 - **Historical analytics** - browse session history with charts
 - **Parquet export** - analyze data in Jupyter notebooks
-- **Presence tracking** - correlate activity with your availability (macOS)
+- **Presence tracking** - correlate activity with your availability
 
 ## TUI Controls
 
 | Key | Action |
 |-----|--------|
 | `j/k` or `↑/↓` | Navigate agents |
+| `Tab` | Toggle dashboard/terminal focus (tmux split) |
 | `Enter` | Approve/send Enter to agent |
 | `i` or `:` | Send instruction |
-| `m` | Toggle list+preview mode |
-| `t` | Toggle timeline |
-| `z` | Toggle sleep mode |
+| `n` | Create new agent |
 | `x` | Kill agent (double-press) |
 | `b` | Jump to next agent needing attention |
 | `h` or `?` | Show all shortcuts |
-| `q` | Quit |
+| `q` | Quit (or detach in tmux split) |
 
 See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
 

{overcode-0.2.6 → overcode-0.3.1}/README.md

@@ -9,21 +9,16 @@ Launch autonomous coding agents, monitor their progress in real-time, track cost
 Running multiple Claude Code agents is powerful, but managing them gets chaotic fast. Overcode solves this by giving you:
 
 - **Unified visibility** - See all agents at a glance: what they're working on, whether they need input, and how much they're costing you
+- **Native tmux integration** - A split layout with your dashboard on top and the focused agent's live terminal below—full speed, full color, full scrollback
 - **Smart orchestration** - An optional supervisor daemon can approve prompts and keep agents moving without constant attention
-- **Efficiency metrics** - Track "green time" (Claude actively working) vs idle time to understand where time goes
+- **Multi-machine monitoring** - Sister integration aggregates agents from multiple machines into one view
 - **Session persistence** - Agents run in tmux, surviving terminal disconnects. Pick up where you left off
 
-## Screenshots
+## Screenshot
 
-**Split-screen with tmux sync** - Monitor agents in the top pane while viewing live agent output below. Press `p` to enable pane sync, then navigate with `j/k` to switch the bottom pane to the selected agent's window.
+**Tmux split layout** — Monitor all agents in the top pane. The bottom pane shows the selected agent's live terminal. Navigate with `j/k` and the bottom pane follows. Press `Tab` to switch focus between panes.
 
-![Overcode split-screen with tmux sync](docs/images/overcode-split-screen.png)
-
-> **iTerm2 setup**: Use `Cmd+Shift+D` to split horizontally. Run `overcode monitor` in the top pane and `tmux attach -t agents` in the bottom pane.
-
-**Preview mode** - Press `m` to toggle List+Preview mode. Shows collapsed agent list with detailed terminal output preview for the selected agent.
-
-![Overcode preview mode](docs/images/overcode-preview-mode.png)
+![Overcode v0.3.0 tmux split layout](docs/screenshots/overcode-v0p3p0.jpg)
 
 ## Quick Start
 
@@ -33,16 +28,32 @@ Try it instantly with [uvx](https://docs.astral.sh/uv/):
 uvx overcode monitor
 ```
 
-This opens the dashboard. Press `n` to create your first agent—give it a name, point it at a project directory, and optionally provide an initial prompt. Create a few agents to see them work in parallel.
+This opens the standalone dashboard. Press `n` to create your first agent.
 
-**Requirements:** Python 3.12+, tmux, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+For the full tmux-native experience (recommended):
 
-For permanent installation: `pip install overcode`
+```bash
+pip install overcode
+overcode tmux
+```
+
+This creates a split layout: the overcode dashboard on top, the focused agent's live terminal on the bottom. Navigate agents with `j/k` — the bottom pane follows automatically. Press `Tab` to toggle focus between panes.
+
+**Requirements:** Python 3.12+, tmux, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 
 See the [Getting Started Guide](docs/getting-started.md) for a complete walkthrough.
 
 ## Features
 
+### Tmux Split Layout (`overcode tmux`)
+The recommended way to use overcode. Creates a two-pane layout in tmux:
+- **Top pane**: Compact agent dashboard with live status
+- **Bottom pane**: The focused agent's native terminal — no emulation, real tmux
+- `j/k` navigates agents, bottom pane follows
+- `Tab` toggles focus between dashboard and terminal
+- `Option+J/K` navigates agents from the terminal pane
+- `PageUp/Down` and mouse scroll work in the bottom pane
+
 ### Real-time Dashboard
 The TUI displays all agents with live status updates, showing:
 - Current activity and AI-generated summaries
@@ -55,8 +66,9 @@ The TUI displays all agents with live status updates, showing:
 - **Launch agents** with custom prompts and permission settings
 - **Send instructions** directly from the dashboard
 - **Standing orders** - persistent instructions that guide agent behavior
+- **Agent hierarchy** - parent/child delegation with follow mode and reporting
+- **Cost budgets** - per-agent spending limits with automatic enforcement
 - **Sleep mode** - pause agents and exclude them from stats
-- **Priority sorting** - organize agents by importance
 
 ### Supervisor Daemon
 An optional Claude-powered orchestrator that:
@@ -65,26 +77,31 @@ An optional Claude-powered orchestrator that:
 - Follows per-agent standing orders
 - Tracks interventions and steering decisions
 
+### Sister Integration
+Aggregate agents from multiple machines into one dashboard:
+- Configure sister machines in `~/.overcode/config.yaml`
+- Remote agents appear alongside local ones
+- In tmux split mode, selecting a sister agent auto-zooms the dashboard with a preview pane
+
 ### Analytics & Export
 - **Web dashboard** - mobile-friendly monitoring from any device
 - **Historical analytics** - browse session history with charts
 - **Parquet export** - analyze data in Jupyter notebooks
-- **Presence tracking** - correlate activity with your availability (macOS)
+- **Presence tracking** - correlate activity with your availability
 
 ## TUI Controls
 
 | Key | Action |
 |-----|--------|
 | `j/k` or `↑/↓` | Navigate agents |
+| `Tab` | Toggle dashboard/terminal focus (tmux split) |
 | `Enter` | Approve/send Enter to agent |
 | `i` or `:` | Send instruction |
-| `m` | Toggle list+preview mode |
-| `t` | Toggle timeline |
-| `z` | Toggle sleep mode |
+| `n` | Create new agent |
 | `x` | Kill agent (double-press) |
 | `b` | Jump to next agent needing attention |
 | `h` or `?` | Show all shortcuts |
-| `q` | Quit |
+| `q` | Quit (or detach in tmux split) |
 
 See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
 

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

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

{overcode-0.2.6 → 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.2.6 → overcode-0.3.1}/src/overcode/claude_config.py

@@ -54,6 +54,14 @@ class ClaudeConfigEditor:
         self.path.parent.mkdir(parents=True, exist_ok=True)
         self.path.write_text(json.dumps(settings, indent=2) + "\n")
 
+    def _modify_settings(self, mutator_fn):
+        """Load settings, deepcopy, apply mutator_fn, save. Returns mutator's result."""
+        settings = self.load()
+        settings = copy.deepcopy(settings)
+        result = mutator_fn(settings)
+        self.save(settings)
+        return result
+
     def has_hook(self, event: str, command: str) -> bool:
         """Check if a command hook exists for the given event."""
         settings = self.load()
@@ -68,25 +76,20 @@ class ClaudeConfigEditor:
 
         Returns True if the hook was added, False if it already exists.
         """
-        settings = self.load()
-        # Check existing
-        for entry in settings.get("hooks", {}).get(event, []):
-            for hook in entry.get("hooks", []):
-                if hook.get("command") == command:
-                    return False
-
-        updated = copy.deepcopy(settings)
-        if "hooks" not in updated:
-            updated["hooks"] = {}
-        if event not in updated["hooks"]:
-            updated["hooks"][event] = []
-
-        updated["hooks"][event].append({
-            "matcher": matcher,
-            "hooks": [{"type": "command", "command": command}],
-        })
+        if self.has_hook(event, command):
+            return False
 
-        self.save(updated)
+        def _add(settings):
+            if "hooks" not in settings:
+                settings["hooks"] = {}
+            if event not in settings["hooks"]:
+                settings["hooks"][event] = []
+            settings["hooks"][event].append({
+                "matcher": matcher,
+                "hooks": [{"type": "command", "command": command}],
+            })
+
+        self._modify_settings(_add)
         return True
 
     def remove_hook(self, event: str, command: str) -> bool:
@@ -112,18 +115,14 @@ class ClaudeConfigEditor:
         if index_to_remove is None:
             return False
 
-        updated = copy.deepcopy(settings)
-        del updated["hooks"][event][index_to_remove]
-
-        # Clean up empty event array
-        if not updated["hooks"][event]:
-            del updated["hooks"][event]
-
-        # Clean up empty hooks dict
-        if not updated["hooks"]:
-            del updated["hooks"]
+        def _remove(settings):
+            del settings["hooks"][event][index_to_remove]
+            if not settings["hooks"][event]:
+                del settings["hooks"][event]
+            if not settings["hooks"]:
+                del settings["hooks"]
 
-        self.save(updated)
+        self._modify_settings(_remove)
         return True
 
     def list_hooks_matching(self, command_prefix: str) -> list[tuple[str, str]]:
@@ -147,13 +146,14 @@ class ClaudeConfigEditor:
         if tool_pattern in allow_list:
             return False
 
-        updated = copy.deepcopy(settings)
-        if "permissions" not in updated:
-            updated["permissions"] = {}
-        if "allow" not in updated["permissions"]:
-            updated["permissions"]["allow"] = []
-        updated["permissions"]["allow"].append(tool_pattern)
-        self.save(updated)
+        def _add(settings):
+            if "permissions" not in settings:
+                settings["permissions"] = {}
+            if "allow" not in settings["permissions"]:
+                settings["permissions"]["allow"] = []
+            settings["permissions"]["allow"].append(tool_pattern)
+
+        self._modify_settings(_add)
         return True
 
     def remove_permission(self, tool_pattern: str) -> bool:
@@ -163,18 +163,14 @@ class ClaudeConfigEditor:
         if tool_pattern not in allow_list:
             return False
 
-        updated = copy.deepcopy(settings)
-        updated["permissions"]["allow"].remove(tool_pattern)
-
-        # Clean up empty allow list
-        if not updated["permissions"]["allow"]:
-            del updated["permissions"]["allow"]
-
-        # Clean up empty permissions dict
-        if not updated["permissions"]:
-            del updated["permissions"]
+        def _remove(settings):
+            settings["permissions"]["allow"].remove(tool_pattern)
+            if not settings["permissions"]["allow"]:
+                del settings["permissions"]["allow"]
+            if not settings["permissions"]:
+                del settings["permissions"]
 
-        self.save(updated)
+        self._modify_settings(_remove)
         return True
 
     def list_permissions_matching(self, prefix: str) -> list[str]:

overcode-0.3.1/src/overcode/claude_pid.py

@@ -0,0 +1,38 @@
+"""
+Session ID ownership guard for Claude Code sessions.
+
+Prevents cross-contamination when multiple agents share the same working
+directory by checking that a discovered sessionId isn't already owned by
+another agent.
+
+The primary mechanism is --session-id prescribed at launch (#373).
+This module provides the ownership guard used by sync_session_id's
+history.jsonl fallback for post-/clear detection.
+"""
+
+
+def is_session_id_owned_by_others(
+    session_id: str,
+    own_agent_id: str,
+    all_sessions: list,
+) -> bool:
+    """Check if a Claude session ID is already owned by another agent.
+
+    Prevents cross-contamination when the directory-based lookup discovers
+    a sessionId that belongs to a different agent.
+
+    Args:
+        session_id: The Claude sessionId to check.
+        own_agent_id: The overcode agent ID doing the check.
+        all_sessions: All active overcode sessions to check against.
+
+    Returns:
+        True if another agent already owns this sessionId.
+    """
+    for session in all_sessions:
+        if session.id == own_agent_id:
+            continue
+        owned_ids = getattr(session, 'claude_session_ids', None) or []
+        if session_id in owned_ids:
+            return True
+    return False

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

@@ -21,6 +21,8 @@ from . import monitoring  # noqa: F401
 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.2.6 → 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",