overcode 0.3.6__tar.gz → 0.4.0__tar.gz

{overcode-0.3.6/src/overcode.egg-info → overcode-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overcode
-Version: 0.3.6
+Version: 0.4.0
 Summary: A supervisor for managing multiple Claude Code instances in tmux
 Author: Mike Bond
 Project-URL: Homepage, https://github.com/mkb23/overcode
@@ -119,6 +119,15 @@ An optional Claude-powered orchestrator that:
 - Follows per-agent standing orders
 - Tracks interventions and steering decisions
 
+### Wrappers
+Run agents in custom environments — containers, VMs, or any setup your project needs:
+- **Devcontainer wrapper** - Launch agents inside Docker containers with a single flag
+- **Auto-install** - Bundled wrappers install themselves on first use
+- **Customisable** - Write your own wrapper script or modify the bundled ones
+- Set per-agent (`--wrapper devcontainer`) or as default in config
+
+See the [Wrappers Guide](docs/wrappers.md) for setup and customisation.
+
 ### Sister Integration
 Aggregate agents from multiple machines into one dashboard:
 - Configure sister machines in `~/.overcode/config.yaml`
@@ -153,6 +162,7 @@ See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
 - [CLI Reference](docs/cli-reference.md) - All commands and options
 - [TUI Guide](docs/tui-guide.md) - Keyboard shortcuts and display modes
 - [Configuration](docs/configuration.md) - Config file and environment variables
+- [Wrappers](docs/wrappers.md) - Run agents in containers and custom environments
 - [Advanced Features](docs/advanced-features.md) - Sleep mode, handover, remote monitoring
 
 ## License

{overcode-0.3.6 → overcode-0.4.0}/README.md

@@ -77,6 +77,15 @@ An optional Claude-powered orchestrator that:
 - Follows per-agent standing orders
 - Tracks interventions and steering decisions
 
+### Wrappers
+Run agents in custom environments — containers, VMs, or any setup your project needs:
+- **Devcontainer wrapper** - Launch agents inside Docker containers with a single flag
+- **Auto-install** - Bundled wrappers install themselves on first use
+- **Customisable** - Write your own wrapper script or modify the bundled ones
+- Set per-agent (`--wrapper devcontainer`) or as default in config
+
+See the [Wrappers Guide](docs/wrappers.md) for setup and customisation.
+
 ### Sister Integration
 Aggregate agents from multiple machines into one dashboard:
 - Configure sister machines in `~/.overcode/config.yaml`
@@ -111,6 +120,7 @@ See the [TUI Guide](docs/tui-guide.md) for all keyboard shortcuts.
 - [CLI Reference](docs/cli-reference.md) - All commands and options
 - [TUI Guide](docs/tui-guide.md) - Keyboard shortcuts and display modes
 - [Configuration](docs/configuration.md) - Config file and environment variables
+- [Wrappers](docs/wrappers.md) - Run agents in containers and custom environments
 - [Advanced Features](docs/advanced-features.md) - Sleep mode, handover, remote monitoring
 
 ## License

{overcode-0.3.6 → overcode-0.4.0}/pyproject.toml

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

overcode-0.4.0/src/overcode/__init__.py

@@ -0,0 +1,40 @@
+"""
+Overcode - A supervisor for managing multiple Claude Code instances.
+"""
+
+from pathlib import Path
+
+_toml = Path(__file__).resolve().parent.parent.parent / "pyproject.toml"
+if _toml.is_file():
+    import tomllib
+    with open(_toml, "rb") as _f:
+        __version__ = tomllib.load(_f)["project"]["version"]
+else:
+    from importlib.metadata import version as _version
+    __version__ = _version("overcode")
+
+
+def get_dev_version_suffix() -> str:
+    """Get ` (git-describe)` if running from an editable git install, else ''."""
+    try:
+        import subprocess
+        pkg_dir = Path(__file__).resolve().parent
+        result = subprocess.run(
+            ["git", "describe", "--always", "--dirty"],
+            capture_output=True, text=True, cwd=pkg_dir, timeout=2,
+        )
+        if result.returncode == 0:
+            return f" ({result.stdout.strip()})"
+    except Exception:
+        pass
+    return ""
+
+
+def get_full_version() -> str:
+    """Full version string used at launch: `<version>[ (git-describe)]`.
+
+    Recorded on each Session so we can see which overcode build spawned
+    each agent — useful for diagnosing feature-regression questions like
+    "was this agent launched before the --settings hook injection landed?"
+    """
+    return f"{__version__}{get_dev_version_suffix()}"

{overcode-0.3.6 → overcode-0.4.0}/src/overcode/cli/__init__.py

@@ -23,6 +23,8 @@ from . import sister  # noqa: F401
 from . import config  # noqa: F401
 from . import split  # noqa: F401
 from . import jobs  # noqa: F401
+from . import wrappers  # noqa: F401
+from . import doctor  # noqa: F401
 
 
 def main():

{overcode-0.3.6 → overcode-0.4.0}/src/overcode/cli/_shared.py

@@ -51,6 +51,14 @@ skills_app = typer.Typer(
 )
 app.add_typer(skills_app, name="skills")
 
+# Wrappers subcommand group
+wrappers_app = typer.Typer(
+    name="wrappers",
+    help="Manage agent launch wrapper scripts.",
+    no_args_is_help=True,
+)
+app.add_typer(wrappers_app, name="wrappers")
+
 # Perms subcommand group
 perms_app = typer.Typer(
     name="perms",

{overcode-0.3.6 → overcode-0.4.0}/src/overcode/cli/agent.py

@@ -216,6 +216,10 @@ def launch(
         Optional[str],
         typer.Option("--provider", "-P", help="API provider: 'web' (Claude.ai OAuth) or 'bedrock' (AWS Bedrock)"),
     ] = None,
+    wrapper: Annotated[
+        Optional[str],
+        typer.Option("--wrapper", "-w", help="Wrapper script (path or name from ~/.overcode/wrappers/)"),
+    ] = None,
     sister: Annotated[
         Optional[str],
         typer.Option("--sister", "-S", help="Launch on a remote sister machine (by name from config)"),
@@ -275,14 +279,21 @@ def launch(
     oversight_policy, oversight_timeout_seconds = _parse_oversight_policy(on_stuck, oversight_timeout)
 
     # Resolve provider: CLI flag > config default > "web"
+    from ..config import get_new_agent_defaults
+    agent_defaults = get_new_agent_defaults()
+
     resolved_provider = provider
     if resolved_provider is None:
-        from ..config import get_new_agent_defaults
-        resolved_provider = get_new_agent_defaults().get("provider", "web")
+        resolved_provider = agent_defaults.get("provider", "web")
     if resolved_provider not in ("web", "bedrock"):
         rprint(f"[red]Error: Invalid provider '{resolved_provider}'. Use: web, bedrock[/red]")
         raise typer.Exit(code=1)
 
+    # Resolve wrapper: CLI flag > config default > None
+    resolved_wrapper = wrapper
+    if resolved_wrapper is None:
+        resolved_wrapper = agent_defaults.get("wrapper") or None
+
     # Default to current directory if not specified
     working_dir = directory if directory else os.getcwd()
 
@@ -302,6 +313,7 @@ def launch(
         claude_agent=agent,
         model=model,
         provider=resolved_provider,
+        wrapper=resolved_wrapper,
     )
 
     if result:
@@ -318,6 +330,8 @@ def launch(
             rprint(f"  Agent: {agent}")
         if teams:
             rprint("  Agent teams: enabled")
+        if resolved_wrapper:
+            rprint(f"  Wrapper: {resolved_wrapper}")
         if resolved_provider != "web":
             rprint(f"  Provider: {resolved_provider}")
         if budget is not None and budget > 0:
@@ -440,7 +454,7 @@ def list_agents(
         get_status_symbol, get_git_diff_stats,
     )
     from ..monitor_daemon_state import get_monitor_daemon_state
-    from ..summary_columns import build_cli_context, render_summary_cells, align_summary_rows
+    from ..summary_columns import build_cli_context, render_summary_cells, compute_column_widths, pad_and_join_cells, render_header_cells
     from ..tui_logic import compute_tree_metadata, sort_sessions
     from rich.console import Console
 
@@ -630,7 +644,12 @@ def list_agents(
         activities.append(activity)
 
     # Auto-align columns across all rows, then append activity
-    aligned_lines = align_summary_rows(all_cells)
+    widths = compute_column_widths(all_cells)
+    col_filter = lambda col: detail in col.detail_levels
+    header = render_header_cells(column_filter=col_filter, column_widths=widths)
+    header.truncate(console.width, pad=False)
+    console.print(header, no_wrap=True)
+    aligned_lines = [pad_and_join_cells(row, widths) for row in all_cells]
     for line, activity in zip(aligned_lines, activities):
         line.append(" │ ", style="dim")
         line.append(activity)
@@ -696,51 +715,42 @@ def kill(
 @app.command()
 def restart(
     name: Annotated[str, typer.Argument(help="Name of agent to restart")],
+    fresh: Annotated[
+        bool,
+        typer.Option(
+            "--fresh",
+            help="Start a brand-new Claude session instead of resuming the prior conversation.",
+        ),
+    ] = False,
     session: SessionOption = "agents",
 ):
     """Restart a running agent with the same configuration.
 
-    Gracefully exits Claude (Ctrl-C + /exit), then relaunches with the
-    same permissions mode. Useful when MCP server configs change.
+    Gracefully exits Claude (Ctrl-C + /exit), then relaunches with the same
+    full launch environment as a fresh `overcode launch` — hooks/permissions
+    via --settings, wrapper script, env prefix, model, persona, allowed tools,
+    and extra CLI args.
+
+    By default, resumes the agent's prior Claude session so conversation
+    history is preserved. Pass --fresh to start a brand-new session (useful
+    when the old session is stuck or MCP configs have changed).
     """
-    import os
-    import time
-    from ..session_manager import SessionManager
-    from ..tmux_manager import TmuxManager
-    from ..tmux_utils import tmux_window_target, _build_tmux_cmd
+    from ..launcher import ClaudeLauncher
 
-    sm = SessionManager()
-    sess = sm.get_session_by_name(name)
+    launcher = ClaudeLauncher(session)
+    sess = launcher.sessions.get_session_by_name(name)
     if not sess:
         rprint(f"[red]Error: Agent '{name}' not found[/red]")
         raise typer.Exit(code=1)
 
-    tmux = TmuxManager(session)
-    if not tmux.window_exists(sess.tmux_window):
+    if not launcher.tmux.window_exists(sess.tmux_window):
         rprint(f"[red]Error: Tmux window for '{name}' no longer exists[/red]")
         raise typer.Exit(code=1)
 
-    # Build the claude command based on permissiveness mode
-    claude_command = os.environ.get("CLAUDE_COMMAND", "claude")
-    cmd_parts = [claude_command]
-    if sess.permissiveness_mode == "bypass":
-        cmd_parts.append("--dangerously-skip-permissions")
-    elif sess.permissiveness_mode == "permissive":
-        cmd_parts.extend(["--permission-mode", "dontAsk"])
-    cmd_str = " ".join(cmd_parts)
-
-    # Gracefully exit Claude: Ctrl-C + /exit
     rprint(f"[dim]Stopping '{name}'...[/dim]")
-    tmux.send_keys(sess.tmux_window, "C-c", enter=False)
-    time.sleep(0.5)
-    tmux.send_keys(sess.tmux_window, "/exit", enter=True)
-    time.sleep(3.0)
-
-    # Relaunch
-    if tmux.send_keys(sess.tmux_window, cmd_str, enter=True):
-        sm.update_stats(sess.id, current_task="Restarting...")
-        sm.update_session(sess.id, claude_session_ids=[])
-        rprint(f"[green]Restarted agent: {name}[/green]")
+    if launcher.restart(sess, fresh=fresh):
+        mode = "fresh" if fresh else "resumed"
+        rprint(f"[green]Restarted agent: {name} ({mode})[/green]")
     else:
         rprint(f"[red]Failed to restart agent: {name}[/red]")
         raise typer.Exit(code=1)
@@ -1121,6 +1131,10 @@ def show(
             print(f"{'Agent:':<{label_width + 1}} {sess.claude_agent}")
         if sess.agent_teams:
             print(f"{'Teams:':<{label_width + 1}} enabled")
+        if sess.wrapper:
+            print(f"{'Wrapper:':<{label_width + 1}} {sess.wrapper}")
+        if sess.launcher_version:
+            print(f"{'Launcher:':<{label_width + 1}} {sess.launcher_version}")
 
         print()
 

{overcode-0.3.6 → overcode-0.4.0}/src/overcode/cli/config.py

@@ -57,6 +57,15 @@ CONFIG_TEMPLATE = """\
 #   - name: "desktop"
 #     url: "http://192.168.1.10:5337"
 #     api_key: "shared-secret"
+
+# Custom emoticons for skills (overrides built-in defaults)
+# skill_emoji:
+#   overcode: 🐙           # Default: 🐙
+#   delegating-to-agents: 👥  # Default: 👥
+#   claude-api: 🔌         # Default: 🔌
+#   simplify: ✨            # Default: ✨
+#   shirka: 🔬             # Example: research project organization
+#   # Add your custom skills here with any emoji
 """
 
 
@@ -159,3 +168,19 @@ def config_path():
     """Show the config file path."""
     from ..config import CONFIG_PATH
     print(CONFIG_PATH)
+
+
+@config_app.command("tmux")
+def config_tmux():
+    """Change the tmux pane-toggle key.
+
+    Re-runs the toggle-key picker and (if overcode-tmux keybindings are
+    already installed) reinstalls them with the new key.
+    """
+    from ..config import get_tmux_toggle_key
+    from .split import run_toggle_key_picker
+
+    current = get_tmux_toggle_key()
+    if current:
+        rprint(f"[dim]Current toggle key: [cyan]{current}[/cyan][/dim]")
+    run_toggle_key_picker(current_key=current)

overcode-0.4.0/src/overcode/cli/doctor.py

@@ -0,0 +1,189 @@
+"""
+`overcode doctor` — diagnose agents with broken hook configuration (#435).
+
+Identifies agents whose claude process was started without the --settings
+injection (most commonly because the user manually relaunched claude inside
+the tmux window, bypassing `overcode restart`). Optionally auto-relaunches
+broken agents to reinject hooks.
+"""
+
+from typing import Annotated
+
+import typer
+from rich import print as rprint
+from rich.table import Table
+
+from ._shared import app, SessionOption
+
+
+@app.command()
+def doctor(
+    session: SessionOption = "agents",
+    fix: Annotated[
+        bool,
+        typer.Option("--fix", help="Restart agents whose claude process is missing --settings"),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Show full claude argv for each agent"),
+    ] = False,
+):
+    """Diagnose which agents have broken hook configuration.
+
+    An agent only emits hook-based state changes (PostToolUse, Stop, etc.)
+    if its claude process was launched with `--settings`. This command
+    inspects each live agent's claude process and flags ones that are
+    missing the injection — typically because they were relaunched
+    manually in the tmux pane.
+
+    Use --fix to `overcode restart` broken agents, which re-injects --settings.
+    """
+    from ..launcher import ClaudeLauncher
+    from ..doctor import (
+        inspect_agent,
+        snapshot_process_table,
+        SEVERITY_ERROR,
+        SEVERITY_WARNING,
+        VERDICT_OK,
+        VERDICT_MISSING_SETTINGS,
+        VERDICT_NO_CLAUDE,
+        VERDICT_WINDOW_GONE,
+        VERDICT_REMOTE,
+    )
+    from ..history_reader import get_session_stats
+    from ..monitor_daemon import is_monitor_daemon_running
+
+    launcher = ClaudeLauncher(session)
+    # detect_terminated=False — doctor inspects running state, doesn't mutate
+    sessions = [s for s in launcher.list_sessions(detect_terminated=False)
+                if s.status != "terminated"]
+
+    if not sessions:
+        rprint("[dim]No running agents in session '[bold]{}[/bold]'[/dim]".format(session))
+        return
+
+    # Single ps snapshot shared across all agents.
+    children, argv_by_pid = snapshot_process_table()
+    daemon_running = is_monitor_daemon_running(session)
+
+    results = []
+    for sess in sessions:
+        pane_pid = None
+        live_stats = None
+        if not getattr(sess, "is_remote", False):
+            pane_pid = launcher.tmux.get_pane_pid(sess.tmux_window)
+            try:
+                live_stats = get_session_stats(sess)
+            except Exception:
+                live_stats = None
+        results.append(inspect_agent(
+            sess, pane_pid, children, argv_by_pid,
+            live_stats=live_stats,
+            daemon_running=daemon_running,
+        ))
+
+    # Print table
+    table = Table(title=f"Agent hook health — session '{session}'")
+    table.add_column("Agent", style="bold")
+    table.add_column("Verdict")
+    table.add_column("Launcher")
+    table.add_column("PID")
+    table.add_column("Issues")
+    table.add_column("Details")
+
+    verdict_style = {
+        VERDICT_OK: "[green]✓ ok[/green]",
+        VERDICT_MISSING_SETTINGS: "[red]✗ no --settings[/red]",
+        VERDICT_NO_CLAUDE: "[yellow]? no claude[/yellow]",
+        VERDICT_WINDOW_GONE: "[dim]window gone[/dim]",
+        VERDICT_REMOTE: "[dim]remote[/dim]",
+    }
+
+    def _issues_cell(findings):
+        if not findings:
+            return "[dim]—[/dim]"
+        errors = sum(1 for f in findings if f.severity == SEVERITY_ERROR)
+        warnings = sum(1 for f in findings if f.severity == SEVERITY_WARNING)
+        parts = []
+        if errors:
+            parts.append(f"[red]{errors}✗[/red]")
+        if warnings:
+            parts.append(f"[yellow]{warnings}⚠[/yellow]")
+        return " ".join(parts)
+
+    for r in results:
+        table.add_row(
+            r.name,
+            verdict_style.get(r.verdict, r.verdict),
+            r.launcher_version or "[dim]—[/dim]",
+            str(r.claude_pid) if r.claude_pid else "[dim]—[/dim]",
+            _issues_cell(r.data_findings),
+            r.details,
+        )
+
+    rprint(table)
+
+    # Detail findings below the table
+    flagged = [r for r in results if r.data_findings]
+    if flagged:
+        rprint()
+        rprint("[bold]Data-quality findings:[/bold]")
+        for r in flagged:
+            rprint(f"  [bold]{r.name}[/bold]")
+            for f in r.data_findings:
+                badge = "[red]✗[/red]" if f.severity == SEVERITY_ERROR else "[yellow]⚠[/yellow]"
+                rprint(f"    {badge} [dim]{f.code}[/dim]: {f.message}")
+
+    if verbose:
+        rprint()
+        for r in results:
+            if r.claude_argv:
+                rprint(f"[bold]{r.name}[/bold] argv:")
+                rprint(f"  [dim]{r.claude_argv}[/dim]")
+
+    broken = [r for r in results if r.verdict == VERDICT_MISSING_SETTINGS]
+    ok_count = sum(1 for r in results if r.verdict == VERDICT_OK)
+    findings_count = sum(len(r.data_findings) for r in results)
+
+    rprint()
+    if broken:
+        rprint(f"[red]✗[/red] {len(broken)} broken, [green]{ok_count}[/green] ok, "
+               f"{len(results) - len(broken) - ok_count} other")
+        if not fix:
+            names = " ".join(r.name for r in broken)
+            rprint(f"[dim]Fix with: overcode restart {names}[/dim]")
+            rprint("[dim]Or: overcode doctor --fix[/dim]")
+    else:
+        rprint(f"[green]✓[/green] all {ok_count} agents have hooks injected")
+
+    if findings_count:
+        rprint(f"[yellow]⚠[/yellow] {findings_count} data-quality "
+               f"finding{'s' if findings_count != 1 else ''} across "
+               f"{len(flagged)} agent{'s' if len(flagged) != 1 else ''}")
+
+    # Global (not per-agent): bundled skills drifted from what's installed.
+    # Affects every agent, so it's surfaced once rather than duplicated per row.
+    try:
+        from ..bundled_skills import any_skills_stale
+        if any_skills_stale():
+            rprint("[yellow]⚠[/yellow] installed skills differ from bundled "
+                   "versions — run [bold]overcode skills install[/bold]")
+    except Exception:
+        pass
+
+    if fix and broken:
+        rprint()
+        rprint("[bold]Restarting broken agents...[/bold]")
+        from ..session_manager import SessionManager
+        sm = SessionManager()
+        for r in broken:
+            sess = sm.get_session_by_name(r.name)
+            if sess is None:
+                rprint(f"  [yellow]skip {r.name} — session vanished[/yellow]")
+                continue
+            # fresh=False → resume the existing Claude session so history is preserved;
+            # the new shell line rebuilt by the launcher will include --settings.
+            if launcher.restart(sess, fresh=False):
+                rprint(f"  [green]✓[/green] restarted {r.name}")
+            else:
+                rprint(f"  [red]✗[/red] failed to restart {r.name}")

{overcode-0.3.6 → overcode-0.4.0}/src/overcode/cli/hooks.py

@@ -1,5 +1,5 @@
 """
-Hooks commands: install, uninstall, status.
+Hooks commands: install (deprecated), uninstall, status.
 """
 
 from typing import Annotated
@@ -10,51 +10,27 @@ from rich import print as rprint
 from ._shared import hooks_app
 
 
-@hooks_app.command("install")
+DEPRECATION_NOTE = (
+    "[yellow]Note:[/yellow] Manual hook installation is deprecated.\n"
+    "  Hooks are now injected automatically when agents are launched via 'overcode launch'.\n"
+    "  Use 'overcode hooks uninstall' to remove legacy hooks from your settings."
+)
+
+
+@hooks_app.command("install", deprecated=True)
 def hooks_install(
     project: Annotated[
         bool,
         typer.Option("--project", "-p", help="Install to project-level .claude/settings.json instead of user-level"),
     ] = False,
 ):
-    """Install all overcode hooks into Claude Code settings.
+    """[Deprecated] Install overcode hooks into Claude Code settings.
 
-    Installs hooks for: UserPromptSubmit, PostToolUse, Stop,
-    PermissionRequest, SessionEnd. All use the unified 'overcode hook-handler'.
+    Hooks are now injected automatically at launch time via --settings.
+    This command is no longer needed for overcode-launched agents.
     """
-    from ..claude_config import ClaudeConfigEditor
-    from ..hook_handler import OVERCODE_HOOKS
-
-    if project:
-        editor = ClaudeConfigEditor.project_level()
-        level = "project"
-    else:
-        editor = ClaudeConfigEditor.user_level()
-        level = "user"
-
-    try:
-        editor.load()
-    except ValueError as e:
-        rprint(f"[red]Error:[/red] {e}")
-        raise typer.Exit(1)
-
-    # Install all overcode hooks (idempotent)
-    installed = 0
-    already = 0
-    for event, command in OVERCODE_HOOKS:
-        if editor.add_hook(event, command):
-            installed += 1
-        else:
-            already += 1
-
-    if installed > 0:
-        events = ", ".join(event for event, _ in OVERCODE_HOOKS)
-        rprint(f"[green]\u2713[/green] Installed {installed} hook(s) in {level} settings")
-        rprint(f"  [dim]{editor.path}[/dim]")
-        rprint(f"\n  Events: {events}")
-        rprint("  All hooks run 'overcode hook-handler' (reads event from stdin).")
-    elif already == len(OVERCODE_HOOKS):
-        rprint(f"[green]\u2713[/green] All {already} hooks already installed in {level} settings")
+    rprint(DEPRECATION_NOTE)
+    raise typer.Exit(0)
 
 
 @hooks_app.command("uninstall")
@@ -98,6 +74,8 @@ def hooks_status():
     from ..claude_config import ClaudeConfigEditor
     from ..hook_handler import OVERCODE_HOOKS
 
+    rprint(f"\n{DEPRECATION_NOTE}\n")
+
     for level_name, editor in [
         ("User-level", ClaudeConfigEditor.user_level()),
         ("Project-level", ClaudeConfigEditor.project_level()),

{overcode-0.3.6 → overcode-0.4.0}/src/overcode/cli/perms.py

@@ -1,5 +1,5 @@
 """
-Permissions commands: install, uninstall, status.
+Permissions commands: install (deprecated), uninstall, status.
 """
 
 from typing import Annotated
@@ -25,7 +25,14 @@ OVERCODE_PUNCHY_PERMS = [
 ]
 
 
-@perms_app.command("install")
+DEPRECATION_NOTE = (
+    "[yellow]Note:[/yellow] Manual permission installation is deprecated.\n"
+    "  Permissions are now injected automatically when agents are launched via 'overcode launch'.\n"
+    "  Use 'overcode perms uninstall' to remove legacy permissions from your settings."
+)
+
+
+@perms_app.command("install", deprecated=True)
 def perms_install(
     project: Annotated[
         bool,
@@ -36,47 +43,13 @@ def perms_install(
         typer.Option("--all", help="Include punchy permissions (launch, send, instruct)"),
     ] = False,
 ):
-    """Install overcode tool permissions into Claude Code settings.
-
-    By default installs safe (read-only) permissions. Use --all to also
-    include punchy permissions that can spawn or control agents.
+    """[Deprecated] Install overcode permissions into Claude Code settings.
 
-    Safe: report, show, list, follow, kill, budget
-    Punchy (--all): launch, send, instruct
+    Permissions are now injected automatically at launch time via --settings.
+    This command is no longer needed for overcode-launched agents.
     """
-    from ..claude_config import ClaudeConfigEditor
-
-    if project:
-        editor = ClaudeConfigEditor.project_level()
-        level = "project"
-    else:
-        editor = ClaudeConfigEditor.user_level()
-        level = "user"
-
-    try:
-        editor.load()
-    except ValueError as e:
-        rprint(f"[red]Error:[/red] {e}")
-        raise typer.Exit(1)
-
-    perms = OVERCODE_SAFE_PERMS + (OVERCODE_PUNCHY_PERMS if all_perms else [])
-
-    installed = 0
-    already = 0
-    for perm in perms:
-        if editor.add_permission(perm):
-            installed += 1
-        else:
-            already += 1
-
-    if installed > 0:
-        tier = "safe + punchy" if all_perms else "safe"
-        rprint(f"[green]\u2713[/green] Installed {installed} permission(s) in {level} settings ({tier})")
-        rprint(f"  [dim]{editor.path}[/dim]")
-        for perm in perms:
-            rprint(f"  {perm}")
-    elif already == len(perms):
-        rprint(f"[green]\u2713[/green] All {already} permissions already installed in {level} settings")
+    rprint(DEPRECATION_NOTE)
+    raise typer.Exit(0)
 
 
 @perms_app.command("uninstall")
@@ -119,6 +92,8 @@ def perms_status():
     """Show which overcode permissions are installed."""
     from ..claude_config import ClaudeConfigEditor
 
+    rprint(f"\n{DEPRECATION_NOTE}\n")
+
     all_perms = OVERCODE_SAFE_PERMS + OVERCODE_PUNCHY_PERMS
 
     for level_name, editor in [