vig-os · gerchowl · Feb 22, 2026 · Feb 22, 2026 · Feb 22, 2026 · Feb 22, 2026
@@ -18,12 +18,13 @@ scripts/build.sh                @c-vigo
 scripts/prepare-build.sh        @c-vigo
 scripts/clean.sh                @c-vigo
 scripts/sync_manifest.py        @c-vigo
-scripts/utils.py                @c-vigo
 
 # Developer tooling scripts
-scripts/gh_issues.py            @gerchowl
-scripts/setup-labels.sh         @gerchowl
-scripts/resolve-branch.sh       @gerchowl
+packages/vig-utils/src/vig_utils/gh_issues.py                   @gerchowl
+packages/vig-utils/src/vig_utils/setup_labels.py                @gerchowl
+packages/vig-utils/src/vig_utils/shell/setup-labels.sh          @gerchowl
+packages/vig-utils/src/vig_utils/resolve_branch.py              @gerchowl
+packages/vig-utils/src/vig_utils/shell/resolve-branch.sh        @gerchowl
 
 # Dev environment setup
 scripts/init.sh                 @c-vigo

@@ -97,7 +97,7 @@ runs:
       run: |
         uv run pytest \
           tests/test_utils.py \
-          tests/test_gh_issues.py \
+          tests/test_devc_remote_uri.py \
           packages/vig-utils/tests \
           --cov --cov-report=term-missing --cov-report=xml \
           $TEST_ARGS

diff --git a/.github/label-taxonomy.toml b/.github/label-taxonomy.toml
@@ -1,12 +1,12 @@
 # Canonical repository labels.
 # Single source of truth — referenced by:
-#   - scripts/setup-labels.sh               (provision labels on a repo)
+#   - uv run setup-labels                   (provision labels on a repo)
 #   - .cursor/skills/issue_triage/SKILL.md  (triage label check)
 #   - .cursor/skills/issue_create/SKILL.md  (agent label mapping)
 #   - .github/ISSUE_TEMPLATE/*.yml          (template label values)
 #
 # Label reconciliation:
-#   Run `scripts/setup-labels.sh` after repo creation to create/update labels
+#   Run `uv run setup-labels` after repo creation to create/update labels
 #   from this taxonomy. Use `--prune` to remove org-default labels that don't
 #   match the taxonomy. Use `--dry-run` to preview changes first.
 

@@ -42,4 +42,4 @@ jobs:
         env:
           PR_TITLE: ${{ github.event.pull_request.title }}
           PR_BODY: ${{ github.event.pull_request.body }}
-        run: uv run python scripts/check-pr-agent-fingerprints.py
+        run: uv run check-pr-agent-fingerprints
diff --git a/.gitignore b/.gitignore
@@ -223,5 +223,8 @@ __marimo__/
 # Pre-commit cache
 .pre-commit-cache/
 
+# Worktrees
+.worktrees/
+
 # Bats
 node_modules/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -150,7 +150,7 @@ repos:
     hooks:
       - id: bandit
         name: bandit (Python security linting)
-        entry: uv run bandit -r packages/vig-utils/src/ scripts/ assets/workspace/ -ll
+        entry: uv run bandit -r packages/vig-utils/src/ assets/workspace/ -ll
         language: system
         types: [python]
         pass_filenames: false
@@ -160,8 +160,8 @@ repos:
     hooks:
       - id: check-skill-names
         name: check-skill-names (enforce naming convention)
-        entry: scripts/check-skill-names.sh .cursor/skills
-        language: script
+        entry: uv run check-skill-names .cursor/skills
+        language: system
         files: ^\.cursor/skills/
         pass_filenames: false
 
@@ -170,7 +170,7 @@ repos:
     hooks:
       - id: prepare-commit-msg-strip-trailers
         name: strip agent trailers from commit message
-        entry: uv run python scripts/prepare-commit-msg-strip-trailers.py
+        entry: uv run prepare-commit-msg-strip-trailers
         language: system
         stages: [prepare-commit-msg]
         pass_filenames: true
@@ -180,7 +180,7 @@ repos:
     hooks:
       - id: check-agent-identity
         name: check agent identity
-        entry: uv run python scripts/check-agent-identity.py
+        entry: uv run check-agent-identity
         language: system
         pass_filenames: false
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md
@@ -169,9 +169,11 @@ Available recipes:
     update                                     # Update all dependencies
 
     [devcontainer]
+    devc-remote *args                          # just devc-remote --repo [email protected]:org/repo.git myserver
     down                                       # Stop and remove containers
     logs *args                                 # Tail container logs
     open                                       # Open Cursor/VS Code attached to the running container
+    remote-devc host *args                     # just remote-devc ksb-meatgrinder --open none
     restart *args                              # Restart service(s)
     shell                                      # Open bash in running devcontainer
     status                                     # Show container status
@@ -202,6 +204,7 @@ Available recipes:
     podman-prune                               # Prune unused containers, images, networks, and volumes [alias: pdm-prune]
     podman-prune-all                           # Full cleanup: prune including volumes [alias: pdm-prune-all]
     podman-ps *args                            # List containers/images (--all for all podman resources) [alias: pdm-ps]
+    podman-push-ssh image host                 # Push a local image to a remote machine over SSH (no registry needed) [alias: pdm-push-ssh]
     podman-rmi image                           # Remove an image by name, tag, or ID [alias: pdm-rmi]
     podman-rmi-all                             # Remove all images (with confirmation) [alias: pdm-rmi-all]
     podman-rmi-dangling                        # Remove dangling images (untagged) [alias: pdm-rmi-dangling]

@@ -53,6 +53,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
     git \
+    jq \
     openssh-client \
     locales \
     ca-certificates \
@@ -214,6 +215,9 @@ RUN set -eux; \
     tar -xzf "$FILE" -C /usr/local/bin --strip-components=1; \
     rm "$FILE";
 
+# Copy vig-utils package early so uv can resolve the workspace member
+COPY packages/vig-utils /root/packages/vig-utils
+
 # Install Python development tools from root pyproject.toml (SSoT)
 # and upgrade pip to fix CVE-2025-8869 (symbolic link extraction vulnerability)
 # vig-utils must be present before uv export because uv.lock references it as a workspace member

diff --git a/README.md b/README.md
@@ -120,9 +120,11 @@ Available recipes:
     update                                     # Update all dependencies
 
     [devcontainer]
+    devc-remote *args                          # just devc-remote --repo [email protected]:org/repo.git myserver
     down                                       # Stop and remove containers
     logs *args                                 # Tail container logs
     open                                       # Open Cursor/VS Code attached to the running container
+    remote-devc host *args                     # just remote-devc ksb-meatgrinder --open none
     restart *args                              # Restart service(s)
     shell                                      # Open bash in running devcontainer
     status                                     # Show container status
@@ -153,6 +155,7 @@ Available recipes:
     podman-prune                               # Prune unused containers, images, networks, and volumes [alias: pdm-prune]
     podman-prune-all                           # Full cleanup: prune including volumes [alias: pdm-prune-all]
     podman-ps *args                            # List containers/images (--all for all podman resources) [alias: pdm-ps]
+    podman-push-ssh image host                 # Push a local image to a remote machine over SSH (no registry needed) [alias: pdm-push-ssh]
     podman-rmi image                           # Remove an image by name, tag, or ID [alias: pdm-rmi]
     podman-rmi-all                             # Remove all images (with confirmation) [alias: pdm-rmi-all]
     podman-rmi-dangling                        # Remove dangling images (untagged) [alias: pdm-rmi-dangling]

diff --git a/assets/init-workspace.sh b/assets/init-workspace.sh
@@ -155,7 +155,7 @@ if [[ "$FORCE" == "true" ]]; then
                 CONFLICTS+=("$rel_path")
             fi
         fi
-    done < <(find "$TEMPLATE_DIR" -type f ! -path "*/.git/*" -print0)
+    done < <(find "$TEMPLATE_DIR" -type f ! -path "*/.git/*" ! -path "*/.venv/*" -print0)
 
     # Show preserved files
     if [[ ${#PRESERVED[@]} -gt 0 ]]; then

diff --git a/assets/workspace/.devcontainer/README.md b/assets/workspace/.devcontainer/README.md
@@ -71,6 +71,66 @@ Paths to other mounts can be absolute or relative to the main project folder.
    projects you want to see in the editor. The file is git-ignored, so your personal
    configuration stays local.
 
+## Tailscale SSH
+
+Connect to the devcontainer over Tailscale SSH instead of the devcontainer protocol.
+This enables tools like Cursor GUI to execute shell commands inside the container via SSH remote.
+
+### Prerequisites
+
+1. A [Tailscale](https://tailscale.com/) account with SSH enabled in your tailnet ACLs.
+2. An auth key (ephemeral + reusable recommended) from
+   [Tailscale Admin → Settings → Keys](https://login.tailscale.com/admin/settings/keys).
+
+### Setup
+
+1. Add the auth key to your local compose override (git-ignored):
+
+   ```yaml
+   # .devcontainer/docker-compose.local.yaml
+   services:
+     devcontainer:
+       environment:
+         - TAILSCALE_AUTHKEY=tskey-auth-XXXX
+         # Optional: override the auto-generated hostname
+         # - TAILSCALE_HOSTNAME=myproject-devc-mybox
+   ```
+
+2. Rebuild the devcontainer (`Cmd/Ctrl+Shift+P` → "Dev Containers: Rebuild Container").
+
+3. Tailscale installs on first create (~10 s) and connects on every start.
+   The container appears in your tailnet as `<project>-devc-<hostname>`.
+
+4. Connect via SSH from Cursor or any SSH client:
+
+   ```bash
+   ssh root@<tailscale-hostname>
+   ```
+
+### Tailscale ACL configuration
+
+Your tailnet must allow SSH access. Add a rule like this to your
+[ACL policy](https://login.tailscale.com/admin/acls):
+
+```json
+{
+  "ssh": [
+    {
+      "action": "accept",
+      "src": ["autogroup:members"],
+      "dst": ["autogroup:self"],
+      "users": ["root", "autogroup:nonroot"]
+    }
+  ]
+}
+```
+
+### How it works
+
+- `setup-tailscale.sh install` runs during `postCreateCommand` — installs Tailscale if `TAILSCALE_AUTHKEY` is set.
+- `setup-tailscale.sh start` runs during `postStartCommand` — starts `tailscaled` (userspace networking, no `/dev/net/tun` needed) and authenticates.
+- When `TAILSCALE_AUTHKEY` is unset, both hooks are silent no-ops.
+
 ## Updating the template
 
 If you synchronize with a newer release of the vigOS devcontainer image,

diff --git a/assets/workspace/.devcontainer/devcontainer.json b/assets/workspace/.devcontainer/devcontainer.json
@@ -18,6 +18,7 @@
                 "nefrob.vscode-just-syntax"
             ],
             "settings": {
+                "terminal.integrated.defaultProfile.linux": "bash",
                 "python.defaultInterpreterPath": "/root/assets/workspace/.venv/bin/python",
                 "[python]": {
                     "editor.defaultFormatter": "charliermarsh.ruff",
@@ -50,7 +51,7 @@
         "--group-add=0"
     ],
     "initializeCommand": ".devcontainer/scripts/initialize.sh",
-    "postStartCommand": "/workspace/{{SHORT_NAME}}/.devcontainer/scripts/post-start.sh",
-    "postAttachCommand": "/workspace/{{SHORT_NAME}}/.devcontainer/scripts/post-attach.sh",
-    "postCreateCommand": "/workspace/{{SHORT_NAME}}/.devcontainer/scripts/post-create.sh"
+    "postStartCommand": "/bin/bash /workspace/{{SHORT_NAME}}/.devcontainer/scripts/post-start.sh",
+    "postAttachCommand": "/bin/bash /workspace/{{SHORT_NAME}}/.devcontainer/scripts/post-attach.sh",
+    "postCreateCommand": "/bin/bash /workspace/{{SHORT_NAME}}/.devcontainer/scripts/post-create.sh"
 }
diff --git a/assets/workspace/.devcontainer/docker-compose.local.yaml b/assets/workspace/.devcontainer/docker-compose.local.yaml
@@ -22,4 +22,29 @@
 #       environment:
 #         - MY_API_KEY=secret123
 
+# Optional: Tailscale SSH for direct mesh access (e.g. Cursor GUI workaround)
+# Generate an auth key at https://login.tailscale.com/admin/settings/keys
+# Use an ephemeral + reusable key so stale containers auto-expire.
+# The device + cap_add entries are required for Tailscale SSH to work (real TUN).
+#
+#   services:
+#     devcontainer:
+#       devices:
+#         - /dev/net/tun:/dev/net/tun
+#       cap_add:
+#         - NET_ADMIN
+#         - NET_RAW
+#       environment:
+#         - TAILSCALE_AUTHKEY=tskey-auth-XXXX
+#         - TAILSCALE_HOSTNAME=myproject-devc-mybox  # optional override
+
+# Optional: Claude Code CLI (subscription OAuth token)
+# Run `claude setup-token` on your host to generate a long-lived token (1 year).
+# devc-remote.sh auto-injects from your local CLAUDE_CODE_OAUTH_TOKEN env var.
+#
+#   services:
+#     devcontainer:
+#       environment:
+#         - CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-XXXX
+
 services: {}
diff --git a/assets/workspace/.devcontainer/justfile.base b/assets/workspace/.devcontainer/justfile.base
@@ -366,4 +366,48 @@ sidecar name *args:
     fi
 
     # Execute the recipe in the sidecar
-    podman exec {{ name }} just {{ args }}
+    podman exec {{name}} just {{args}}
+
+# -------------------------------------------------------------------------------
+# REMOTE DEVCONTAINER
+# -------------------------------------------------------------------------------
+
+# Start a devcontainer on a remote host and open Cursor/VS Code
+# Auto-clones the repo and runs init-workspace if needed
+# Usage: just devc-remote myserver
+#        just devc-remote myserver:/home/user/repo
+#        just devc-remote --repo [email protected]:org/repo.git myserver
+[group('devcontainer')]
+devc-remote *args:
+    bash scripts/devc-remote.sh {{args}}
+
+# Deploy current project to a remote host (auto-detects repo + branch)
+# Pushes unpushed commits, clones/fetches on remote, starts devcontainer
+# Usage: just remote-devc <ssh-host>[:<path>] [extra-args...]
+# Example: just remote-devc ksb-meatgrinder
+#          just remote-devc ksb-meatgrinder --open none
+[group('devcontainer')]
+remote-devc host *args:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    SCRIPT_DIR="$(cd "{{source_directory()}}/scripts" && pwd)"
+    if [[ ! -f "$SCRIPT_DIR/devc-remote.sh" ]]; then
+        echo "[ERROR] devc-remote.sh not found at $SCRIPT_DIR"
+        exit 1
+    fi
+    # Auto-detect org/repo from git remote
+    remote_url=$(git remote get-url origin 2>/dev/null) || {
+        echo "[ERROR] No git remote 'origin' found. Run from inside a git repo."
+        exit 1
+    }
+    # Extract org/repo from SSH or HTTPS URL
+    # ssh: [email protected]:org/repo.git → org/repo
+    # https: https://github.com/org/repo.git → org/repo
+    gh_repo=$(echo "$remote_url" | sed -E 's#(git@|https://)([^:/]+)[:/]##; s/\.git$//')
+    # Auto-detect current branch
+    branch=$(git branch --show-current 2>/dev/null)
+    gh_target="gh:${gh_repo}"
+    if [[ -n "$branch" ]]; then
+        gh_target="gh:${gh_repo}:${branch}"
+    fi
+    bash "$SCRIPT_DIR/devc-remote.sh" --force "{{host}}" "$gh_target" {{args}}
diff --git a/assets/workspace/.devcontainer/justfile.gh b/assets/workspace/.devcontainer/justfile.gh
@@ -8,9 +8,7 @@
 
 alias gh-i := gh-issues
 
-_gh_scripts := source_directory() / "scripts"
-
 # List open issues and PRs grouped by milestone
 [group('github')]
 gh-issues:
-    uv run python {{ _gh_scripts }}/gh_issues.py
+    gh-issues