feat: support remote Claude Code sessions via BUDDI_HOST env var

[shadowsaber16]

Adds optional BUDDI_HOST and BUDDI_SOCKET environment variables to buddi-hook.py. When BUDDI_HOST is set (e.g. "localhost:9999"), the hook connects over TCP instead of the Unix socket, enabling Claude Code on a remote VM to forward hook events to Buddi on a local Mac via SSH reverse port-forwarding (typically bridged with socat on the Mac).

Behavior is unchanged when neither variable is set.

Description

Type of change

• Bug fix
• New feature
• Enhancement
• Documentation
• Chore (build, CI, refactor)

Checklist

• I have tested this on a macOS device
• My code follows the existing style of this project
• I have updated documentation if needed
• This PR is focused on a single change

Screenshots

[shadowsaber16]

Please feel free to discard the PR and take it up as a feature request to support remote SSH connections for buddi. I realley liked to concept and built this for personal use and felt this could be shared with the community!

[cubic-dev-ai]

1 issue found across 1 file

Confidence score: 3/5

• Unhandled exceptions on invalid BUDDI_HOST port values in buddi/Buddi/Resources/buddi-hook.py could crash the hook and affect user workflows.
• Score reflects a concrete, user-impacting failure mode with medium severity, but limited to input validation.
• Pay close attention to buddi/Buddi/Resources/buddi-hook.py - add port validation or error handling to avoid crashes.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="buddi/Buddi/Resources/buddi-hook.py">

<violation number="1" location="buddi/Buddi/Resources/buddi-hook.py:34">
P2: Invalid `BUDDI_HOST` port values can raise uncaught exceptions and crash the hook.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

@cubic-dev-ai

@grayashh I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 issue found across 1 file

Confidence score: 4/5

• This PR looks safe to merge overall, with one moderate portability concern rather than a broad functional break.
• In buddi/Buddi/Resources/buddi-hook.py, the BUDDI_HOST connect path uses IPv4-only AF_INET; in IPv6-only or some dual-stack setups this can fail and silently drop events.
• Because the issue is environment-specific (severity 5/10, high confidence) and not a universal runtime failure, the merge risk appears limited but worth addressing soon.
• Pay close attention to buddi/Buddi/Resources/buddi-hook.py - IPv4-only socket handling may cause missed event delivery on IPv6-capable networks.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="buddi/Buddi/Resources/buddi-hook.py">

<violation number="1" location="buddi/Buddi/Resources/buddi-hook.py:38">
P2: `BUDDI_HOST` TCP connect path is IPv4-only (`AF_INET`), which can fail in IPv6-only/dual-stack environments and silently drop events.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[grayashh]

Thanks for the contribution — the TCP fallback is clean and the input validation is solid.

One small ask before merge: a non-loopback guard for BUDDI_HOST.

If someone accidentally sets BUDDI_HOST=0.0.0.0:9999 or a public IP, every prompt, tool input, and file path gets sent in plaintext over that link. The docstring already says "Always tunnel over SSH", but a runtime check catches the footgun even when users skim.

Suggested guard (stderr warning, non-blocking — keeps the env var as an advanced escape hatch):

if BUDDI_HOST:
    _host = BUDDI_HOST.rpartition(":")[0].strip("[]")
    if _host not in ("localhost", "127.0.0.1", "::1"):
        print(
            f"buddi-hook: warning: BUDDI_HOST={BUDDI_HOST!r} is not a loopback "
            "address; events contain prompts and tool inputs — only use over "
            "an SSH tunnel.",
            file=sys.stderr,
        )

Place it once at module load (right after the BUDDI_HOST = os.environ.get(...) line) so it fires once per hook invocation rather than per connection.