overcode 0.4.1__tar.gz → 0.5.1__tar.gz

overcode-0.5.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include src/overcode *.md *.sh *.js

{overcode-0.4.1/src/overcode.egg-info → overcode-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overcode
-Version: 0.4.1
+Version: 0.5.1
 Summary: A supervisor for managing multiple Claude Code instances in tmux
 Author: Mike Bond
 Project-URL: Homepage, https://github.com/mkb23/overcode
@@ -42,13 +42,13 @@ Dynamic: license-file
 
 # overcode
 
-A TUI supervisor for managing multiple Claude Code agents in tmux.
+A TUI supervisor for managing multiple coding agents (Claude Code, opencode, Codex, Grok) in tmux.
 
 Launch autonomous coding agents, monitor their progress in real-time, track costs and activity, and coordinate work across your projects—all from a single dashboard.
 
 ## Why overcode?
 
-Running multiple Claude Code agents is powerful, but managing them gets chaotic fast. Overcode solves this by giving you:
+Running multiple coding 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
@@ -81,7 +81,7 @@ 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)
+**Requirements:** Python 3.12+, tmux, and an agent CLI — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [opencode](https://opencode.ai), [Codex CLI](https://github.com/openai/codex), or [Grok Build](https://x.ai)
 
 See the [Getting Started Guide](docs/getting-started.md) for a complete walkthrough.
 
@@ -128,6 +128,18 @@ Run agents in custom environments — containers, VMs, or any setup your project
 
 See the [Wrappers Guide](docs/wrappers.md) for setup and customisation.
 
+### Agent Backends
+Overcode is not Claude-Code-only. It supports four agent CLIs today: Claude Code, opencode,
+Codex, and Grok. Launch a non-default one with `overcode launch -n my-agent --backend
+opencode` (or `codex` / `grok`) and it appears in the same dashboard with live hook-grade
+status, previews, AI summaries, send-instruction, restart, kill, resume, fork, and
+token/cost/context columns. Backends declare their capabilities, so the Claude-only
+subsystems — skills, the sandbox badge, the subscription-usage widget, agent teams — are
+hidden rather than shown as misleading zeros. A backend badge column appears only when your
+fleet actually mixes backends, so a Claude-only setup looks exactly as it did. See the
+[Backends Guide](docs/backends.md) for the full support matrix, flag mapping, and current
+limitations.
+
 ### Sister Integration
 Aggregate agents from multiple machines into one dashboard:
 - Configure sister machines in `~/.overcode/config.yaml`
@@ -165,6 +177,21 @@ See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
 - [Wrappers](docs/wrappers.md) - Run agents in containers and custom environments
 - [Advanced Features](docs/advanced-features.md) - Sleep mode, handover, remote monitoring
 
+## Testing
+
+Unit tests run on the host (`make test-unit`). End-to-end tests run inside a
+disposable Docker container so daemons, tmux servers and (mock or real) Claude
+processes can never leak onto your machine:
+
+```bash
+make e2e         # workflow + visual tiers (mock Claude, no credentials)
+make e2e-real    # real-LLM smoke tier (needs CLAUDE_CODE_OAUTH_TOKEN)
+make e2e-shell   # debug shell inside the test container
+```
+
+See [docs/design/e2e-devcontainer-testing.md](docs/design/e2e-devcontainer-testing.md)
+for the architecture, coverage matrix, and CI setup.
+
 ## License
 
 MIT

{overcode-0.4.1 → overcode-0.5.1}/README.md

@@ -1,12 +1,12 @@
 # overcode
 
-A TUI supervisor for managing multiple Claude Code agents in tmux.
+A TUI supervisor for managing multiple coding agents (Claude Code, opencode, Codex, Grok) in tmux.
 
 Launch autonomous coding agents, monitor their progress in real-time, track costs and activity, and coordinate work across your projects—all from a single dashboard.
 
 ## Why overcode?
 
-Running multiple Claude Code agents is powerful, but managing them gets chaotic fast. Overcode solves this by giving you:
+Running multiple coding 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
@@ -39,7 +39,7 @@ 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)
+**Requirements:** Python 3.12+, tmux, and an agent CLI — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [opencode](https://opencode.ai), [Codex CLI](https://github.com/openai/codex), or [Grok Build](https://x.ai)
 
 See the [Getting Started Guide](docs/getting-started.md) for a complete walkthrough.
 
@@ -86,6 +86,18 @@ Run agents in custom environments — containers, VMs, or any setup your project
 
 See the [Wrappers Guide](docs/wrappers.md) for setup and customisation.
 
+### Agent Backends
+Overcode is not Claude-Code-only. It supports four agent CLIs today: Claude Code, opencode,
+Codex, and Grok. Launch a non-default one with `overcode launch -n my-agent --backend
+opencode` (or `codex` / `grok`) and it appears in the same dashboard with live hook-grade
+status, previews, AI summaries, send-instruction, restart, kill, resume, fork, and
+token/cost/context columns. Backends declare their capabilities, so the Claude-only
+subsystems — skills, the sandbox badge, the subscription-usage widget, agent teams — are
+hidden rather than shown as misleading zeros. A backend badge column appears only when your
+fleet actually mixes backends, so a Claude-only setup looks exactly as it did. See the
+[Backends Guide](docs/backends.md) for the full support matrix, flag mapping, and current
+limitations.
+
 ### Sister Integration
 Aggregate agents from multiple machines into one dashboard:
 - Configure sister machines in `~/.overcode/config.yaml`
@@ -123,6 +135,21 @@ See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
 - [Wrappers](docs/wrappers.md) - Run agents in containers and custom environments
 - [Advanced Features](docs/advanced-features.md) - Sleep mode, handover, remote monitoring
 
+## Testing
+
+Unit tests run on the host (`make test-unit`). End-to-end tests run inside a
+disposable Docker container so daemons, tmux servers and (mock or real) Claude
+processes can never leak onto your machine:
+
+```bash
+make e2e         # workflow + visual tiers (mock Claude, no credentials)
+make e2e-real    # real-LLM smoke tier (needs CLAUDE_CODE_OAUTH_TOKEN)
+make e2e-shell   # debug shell inside the test container
+```
+
+See [docs/design/e2e-devcontainer-testing.md](docs/design/e2e-devcontainer-testing.md)
+for the architecture, coverage matrix, and CI setup.
+
 ## License
 
 MIT

{overcode-0.4.1 → overcode-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "overcode"
-version = "0.4.1"
+version = "0.5.1"
 description = "A supervisor for managing multiple Claude Code instances in tmux"
 authors = [
     {name = "Mike Bond"}
@@ -68,7 +68,15 @@ tui-eye = "overcode.testing.tui_eye:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-overcode = ["*.md", "*.sh", "*.tcss", "web/templates/*.html"]
+overcode = [
+    "*.md",
+    "*.sh",
+    "*.tcss",
+    "web/templates/*.html",
+    # Bundled opencode telemetry plugin — copied into a project's
+    # .opencode/plugins/ at launch, so it has to ship with the wheel.
+    "opencode_plugin/*.js",
+]
 
 [tool.black]
 line-length = 100

{overcode-0.4.1 → overcode-0.5.1}/src/overcode/__init__.py

@@ -1,5 +1,5 @@
 """
-Overcode - A supervisor for managing multiple Claude Code instances.
+Overcode - A supervisor for managing multiple coding agents (Claude Code, opencode).
 """
 
 from pathlib import Path

overcode-0.5.1/src/overcode/backends/__init__.py

@@ -0,0 +1,170 @@
+"""Agent backend registry.
+
+``get_backend(name)`` resolves a ``Session.backend`` discriminator to the
+adapter that owns that CLI's argv grammar and gestures.
+"""
+
+from typing import Any, Dict, List
+
+from .base import (
+    AgentBackend,
+    BackendCapability,
+    DialogRule,
+    KeyPress,
+    LaunchSpec,
+    supports,
+)
+from .claude_code import ClaudeCodeBackend
+from .codex import CodexBackend
+from .grok import GrokBackend
+from .opencode import OpencodeBackend
+
+DEFAULT_BACKEND = "claude-code"
+
+_BACKENDS: Dict[str, AgentBackend] = {
+    ClaudeCodeBackend.name: ClaudeCodeBackend(),
+    OpencodeBackend.name: OpencodeBackend(),
+    CodexBackend.name: CodexBackend(),
+    GrokBackend.name: GrokBackend(),
+}
+
+
+class UnknownBackendError(ValueError):
+    """Raised when a Session names a backend overcode doesn't have."""
+
+
+def get_backend(name: str = DEFAULT_BACKEND) -> AgentBackend:
+    """Resolve a backend by name.
+
+    Empty/None resolves to the default so pre-backend sessions and
+    partially-populated dicts keep working.
+    """
+    key = name or DEFAULT_BACKEND
+    try:
+        return _BACKENDS[key]
+    except KeyError:
+        known = ", ".join(sorted(_BACKENDS))
+        raise UnknownBackendError(
+            f"Unknown agent backend '{key}'. Known backends: {known}"
+        ) from None
+
+
+def list_backends() -> List[str]:
+    """Names of every registered backend."""
+    return sorted(_BACKENDS)
+
+
+def register_backend(backend: AgentBackend) -> None:
+    """Register (or replace) a backend. Used by tests to install doubles."""
+    _BACKENDS[backend.name] = backend
+    _invalidate_derived_caches()
+
+
+def unregister_backend(name: str) -> None:
+    """Remove a backend. Silent when it isn't registered."""
+    _BACKENDS.pop(name, None)
+    _invalidate_derived_caches()
+
+
+def _invalidate_derived_caches() -> None:
+    """Drop per-backend objects other modules cache by backend name."""
+    from ..stats_reader import clear_reader_cache
+    from ..status_patterns import clear_patterns_cache
+    clear_reader_cache()
+    clear_patterns_cache()
+
+
+def session_backend_name(session: Any) -> str:
+    """Backend name recorded on a session, defaulting for legacy sessions."""
+    name = getattr(session, "backend", None)
+    if isinstance(name, str) and name:
+        return name
+    return DEFAULT_BACKEND
+
+
+def capability_names(capabilities: BackendCapability) -> List[str]:
+    """Serialize a capability flag set to sorted member names.
+
+    This is the wire form: ``SessionDaemonState.backend_capabilities`` and
+    therefore the sister protocol carry these strings, so a newer sister can
+    tell an older TUI what its backends can do.
+    """
+    return sorted(
+        member.name
+        for member in BackendCapability
+        if member.name and member.value and (capabilities & member)
+    )
+
+
+def capabilities_from_names(names: Any) -> BackendCapability:
+    """Parse serialized capability names back into a flag set.
+
+    Unknown names are ignored: a sister running a newer overcode may report
+    capabilities this build has never heard of.
+    """
+    result = BackendCapability.NONE
+    if not isinstance(names, (list, tuple, set)):
+        return result
+    for name in names:
+        member = getattr(BackendCapability, name, None) if isinstance(name, str) else None
+        if isinstance(member, BackendCapability):
+            result |= member
+    return result
+
+
+def session_capabilities(session: Any) -> BackendCapability:
+    """Capabilities of the backend behind a session.
+
+    Remote (sister) agents are answered from the capability list their own
+    daemon published, so a sister can run a backend this host doesn't have.
+    Sisters predating Phase 6 report nothing; they are assumed to be
+    claude-code with the full capability set (design §3, consequence 5).
+    """
+    # Strict bool check: callers hand us duck-typed stand-ins whose every
+    # attribute is truthy, and misreading one as remote would silently swap
+    # in another host's capability answer.
+    is_remote = getattr(session, "is_remote", False)
+    if isinstance(is_remote, bool) and is_remote:
+        remote_state = getattr(session, "remote_daemon_state", None)
+        if isinstance(remote_state, dict) and remote_state.get("backend_capabilities"):
+            return capabilities_from_names(remote_state["backend_capabilities"])
+        return get_backend(DEFAULT_BACKEND).capabilities
+    try:
+        backend = get_backend(session_backend_name(session))
+    except UnknownBackendError:
+        return BackendCapability.NONE
+    return backend.capabilities
+
+
+def session_supports(session: Any, capability: BackendCapability) -> bool:
+    """True when the session's backend declares ``capability``.
+
+    An unknown backend name answers False — an adapter overcode doesn't
+    have can't be assumed to support anything.
+    """
+    return bool(session_capabilities(session) & capability)
+
+
+__all__ = [
+    "AgentBackend",
+    "BackendCapability",
+    "ClaudeCodeBackend",
+    "CodexBackend",
+    "GrokBackend",
+    "OpencodeBackend",
+    "DEFAULT_BACKEND",
+    "DialogRule",
+    "KeyPress",
+    "LaunchSpec",
+    "UnknownBackendError",
+    "capabilities_from_names",
+    "capability_names",
+    "get_backend",
+    "list_backends",
+    "register_backend",
+    "session_backend_name",
+    "session_capabilities",
+    "session_supports",
+    "unregister_backend",
+    "supports",
+]

overcode-0.5.1/src/overcode/backends/base.py

@@ -0,0 +1,189 @@
+"""Backend seam: the protocol every agent CLI adapter implements.
+
+An ``AgentBackend`` owns everything that is specific to one agent CLI —
+argv grammar, env vars, startup-dialog handshake, key gestures — so the
+rest of overcode can stay backend-neutral. See
+``docs/design/agent-agnostic-backends-opencode.md`` §2.1.
+"""
+
+from dataclasses import dataclass, field
+from enum import Flag, auto
+from typing import (
+    TYPE_CHECKING,
+    Dict,
+    List,
+    Optional,
+    Protocol,
+    Sequence,
+    Set,
+    Tuple,
+    Type,
+)
+
+if TYPE_CHECKING:
+    from ..stats_reader import StatsReader
+    from ..status_patterns import StatusPatterns
+
+
+class BackendCapability(Flag):
+    """What an agent CLI can do. Used to gate UI actions and telemetry."""
+
+    NONE = 0
+    RESUME = auto()                   # relaunch continuing a prior conversation
+    FORK = auto()                     # branch a conversation into a new agent
+    SESSION_ID_PRESCRIPTION = auto()  # overcode chooses the session id up front
+    HOOK_EVENTS = auto()              # push telemetry (hook-state files) available
+    TRANSCRIPT_STATS = auto()         # tokens/cost/context readable from disk
+    PERMISSION_INJECTION = auto()     # per-launch permission allowlist
+    SKILLS = auto()                   # skills/persona file discovery
+    SANDBOX_PROBE = auto()
+    SUBSCRIPTION_USAGE = auto()
+    AGENT_TEAMS = auto()
+
+
+@dataclass(frozen=True)
+class KeyPress:
+    """One tmux send-keys gesture, with the pause that must follow it."""
+
+    keys: str
+    enter: bool = False
+    delay_after: float = 0.0
+
+
+@dataclass(frozen=True)
+class DialogRule:
+    """A startup dialog to dismiss while waiting for the input prompt.
+
+    ``marker`` is matched against captured pane content; ``presses`` are
+    sent in order, then the poller sleeps ``settle_seconds``.
+    """
+
+    marker: str
+    presses: Sequence[KeyPress]
+    settle_seconds: float = 1.0
+
+
+@dataclass
+class LaunchSpec:
+    """Everything a backend needs to render one launch invocation.
+
+    Carries the launch-time knobs recorded on a ``Session`` plus the
+    backend-neutral OVERCODE_* identity fields, so a backend can inject
+    them into its own env/config if it needs to.
+    """
+
+    # Session identity (exported into the child process env)
+    name: str = ""
+    session_id: str = ""
+    tmux_session: str = ""
+    parent_session_id: Optional[str] = None
+    parent_name: Optional[str] = None
+
+    # Conversation selection
+    resume_session_id: Optional[str] = None
+    fork: bool = False
+    prescribed_session_id: Optional[str] = None
+
+    # Permissions
+    permissiveness_mode: Optional[str] = None
+    skip_permissions: bool = False
+    dangerously_skip_permissions: bool = False
+    include_punchy_perms: bool = False
+
+    # Agent configuration
+    model: Optional[str] = None
+    agent: Optional[str] = None
+    allowed_tools: Optional[str] = None
+    extra_args: List[str] = field(default_factory=list)
+    agent_teams: bool = False
+    provider: str = "web"
+
+    # Execution environment
+    start_directory: Optional[str] = None
+    wrapper: Optional[str] = None
+    mock_scenario: Optional[str] = None
+
+
+class AgentBackend(Protocol):
+    """Adapter for one agent CLI."""
+
+    name: str                       # "claude-code" | "opencode" | "codex" | "grok"
+    display_name: str
+    binary: str                     # for dependency_check + doctor process matching
+    version_args: Sequence[str]
+    install_hint: str
+    process_basenames: Sequence[str]
+    not_found_error: Type[Exception]
+    capabilities: BackendCapability
+
+    # True when the backend's fork grammar takes an explicit new session id
+    # (--session-id alongside --fork-session) AND the prescribed id is
+    # authoritative for the forked session; False when the CLI mints its own
+    # fork id and discovery must fill it in. Only meaningful alongside
+    # SESSION_ID_PRESCRIPTION — launcher.py's fork branch mints a fresh uuid
+    # to bind eagerly only when both are true. Both grok (Phase 3) and Claude
+    # Code (#466, 2026-08-28) declare this True: Claude Code was originally
+    # assumed to mint its own, different fork id, but a live check of
+    # `claude --resume <id> --fork-session --session-id <new>` found the
+    # prescribed id IS honored — the CLI writes the fork's transcript under
+    # the prescribed uuid. That wrong assumption was #466's root cause:
+    # without eager binding, a fork's id was discovered via directory+time
+    # matching, which is ambiguous whenever another agent shares the same
+    # start_directory (the fork's record could bind to a sibling's id
+    # instead of its own). (The default backends don't literally inherit
+    # this Protocol, so launcher.py reads it via
+    # ``getattr(backend, "fork_prescribes_new_session_id", False)`` — this
+    # default documents the fallback, it isn't inherited automatically.)
+    fork_prescribes_new_session_id: bool = False
+
+    def build_command(self, spec: LaunchSpec) -> List[str]: ...
+
+    def prepare_launch(self, spec: LaunchSpec) -> None:
+        """Side effects the CLI needs in place before the process starts.
+
+        Called once per launch/restart/revive/fork, after the binary check and
+        before the shell line is sent. Claude Code needs nothing here — its
+        telemetry rides on ``--settings`` — but opencode installs its
+        telemetry plugin into the project directory. Must be idempotent and
+        must never raise: a failure costs telemetry, not the launch.
+        """
+        ...
+
+    def env_prefix(self, spec: LaunchSpec) -> Dict[str, str]: ...
+
+    def resume_args(self, session_id: str, fork: bool) -> List[str]: ...
+
+    def graceful_exit_keys(self) -> List[KeyPress]: ...
+
+    def clear_conversation_keys(self) -> List[KeyPress]: ...
+
+    def approve_keys(self) -> List[KeyPress]: ...
+
+    def reject_keys(self) -> List[KeyPress]: ...
+
+    def startup_dialog_rules(self) -> List[DialogRule]: ...
+
+    def prompt_ready_chars(self) -> Set[str]: ...
+
+    def status_patterns(self) -> "StatusPatterns": ...
+
+    def make_stats_reader(self) -> "StatsReader": ...
+
+    def health_verdict(self, argv: str) -> Optional[Tuple[str, str]]:
+        """Doctor's "is observability wired up?" answer for a live process.
+
+        Returns ``(verdict, details)`` from the ``doctor.VERDICT_*``
+        vocabulary, given the agent process's full argv.
+
+        A backend whose telemetry leaves no trace on the command line may
+        also define an *optional* ``refine_health_verdict(session, verdict,
+        details) -> (verdict, details)``. ``doctor`` calls it via ``getattr``
+        with the session in hand — opencode uses it to check for its
+        telemetry plugin in the project directory.
+        """
+        ...
+
+
+def supports(backend: AgentBackend, capability: BackendCapability) -> bool:
+    """True when ``backend`` declares ``capability``."""
+    return bool(backend.capabilities & capability)