v0.1.3 — guiport init + reliable TCC enrolment

guiport v0.1.3 — guiport init + reliable TCC enrolment

Headline

guiport init (or guiport doctor --fix) now reliably adds guiport to System Settings → Privacy & Security → Screen Recording on first run, under its own name — no more "where is it in the list?".

The fix: CGRequestScreenCaptureAccess() alone was not always enough on recent macOS to register the binary into TCC's UI list. Doctor now also forces an actual capture attempt (CGDisplayCreateImage), which is what macOS uses to decide whether to surface the entry.

New

• guiport init — friendly first-run command. Same effect as doctor --fix but with human-friendly output:

  $ guiport init
  guiport 0.1.3  (macOS)
    ✓ accessibility: trusted
    ✗ screen_recording: not granted
  ...
  → System Settings was opened for any missing permissions.
  → Look for `guiport` in the list, toggle it on.
  → Then re-run `guiport doctor` to confirm.
  

Upgrade

brew upgrade guiport
guiport --version    # 0.1.3
guiport init

After toggling guiport on in System Settings, the grant works from any terminal — Ghostty, Terminal.app, iTerm, opencode, etc. (Carries over from v0.1.2's embedded Info.plist.)

v0.1.2 — embedded Info.plist (TCC works from any terminal)

guiport v0.1.2 — embedded Info.plist for stable TCC identity

Headline fix

Granting Screen Recording or Accessibility for guiport now works once, from any terminal.

Before this release, the binary had no embedded Info.plist with usage descriptions — so macOS TCC fell through to the parent terminal (Ghostty, Terminal.app, iTerm, opencode, …), meaning each terminal needed its own grant. With v0.1.2, guiport carries CFBundleIdentifier dev.guiport.cli plus NSAccessibilityUsageDescription, NSScreenCaptureUsageDescription, and NSAppleEventsUsageDescription in its __TEXT,__info_plist section — so TCC tracks guiport as its own subject regardless of how it was launched.

Upgrade

brew upgrade guiport
guiport --version    # 0.1.2

# Trigger TCC enrollment + open Settings
guiport doctor --fix

guiport should now appear under System Settings → Privacy & Security → Accessibility and Screen Recording. Toggle once and you're set across every terminal.

What changed in code

• Resources/Info.plist ships with the binary.
• SwiftPM linker flags (-sectcreate __TEXT __info_plist Resources/Info.plist) inject it into the universal Mach-O at link time. No app bundle required.

v0.1.1 — auto visual fallback

guiport v0.1.1 — auto visual fallback

Headline change

guiport click and guiport find now apply visual fallback automatically. When an AX selector misses and Screen Recording is granted, guiport falls back to on-screen text matching using the selector's name= / text= predicate.

If Screen Recording isn't granted, the fallback is silently skipped and the original no_match error surfaces with a hint pointing to doctor --fix. No surprise mid-action permission prompts.

CLI

• --fallback <enum> removed.
• --strict flag added — opt out of visual fallback (AX-only, fail loud on miss).
• Result reports "path": "ax" or "path": "ocr" so callers know which won.

YAML runner

- click: 'AXButton[name="Save"]'                          # auto-fallback
- click: { selector: 'AXButton[name="Save"]', strict: true }  # opt-out

Legacy fallback: none still maps to strict for back-compat.

MCP

click tool gains strict: bool (defaults to false). Legacy fallback: "none" still mapped to strict.

Other

• examples/calculator-smoke.yaml: AllClear → Clear to match macOS 26 Calculator AX.

Install

brew upgrade guiport
# or
curl -fsSL https://github.com/edihasaj/guiport/releases/download/v0.1.1/guiport-0.1.1-macos-universal.tar.gz | tar xz
sudo cp guiport-0.1.1-macos-universal/guiport /usr/local/bin/guiport

Site: https://guiport.dev

v0.1.0 — first public release

guiport v0.1.0 — first public release

Playwright for desktop apps, built for coding agents.

guiport is a fast CLI/MCP control layer that lets agents like Claude, Codex, opencode, and Gemini inspect and operate macOS apps through structured UI data, then save successful flows as replayable tests.

What's in this release

• macOS support (13+, universal arm64 + x86_64).
• 16 commands covering inspect / control / capture / replay / serve.
• MCP server over stdio for direct agent integration.
• YAML test runner with auto-saved failure artifacts.
• Live recorder (CGEventTap) to capture flows into YAML.
• Selector engine: role[attr=value][attr~=substring][index].
• Visual fallback for canvas / Electron apps where structure is sparse.
• Tree cache with sub-millisecond cached find.
• One-protocol DesktopAdapter ready for Linux + Windows adapters.

Install

# Homebrew
brew tap edihasaj/guiport
brew install guiport

# Install script
curl -fsSL https://raw.githubusercontent.com/edihasaj/guiport/main/scripts/install.sh | sh

# Manual (universal binary)
curl -fsSL https://github.com/edihasaj/guiport/releases/download/v0.1.0/guiport-0.1.0-macos-universal.tar.gz | tar xz
sudo cp guiport-0.1.0-macos-universal/guiport /usr/local/bin/guiport
guiport doctor --fix

Verified

• Calculator end-to-end: 10/10 passes back-to-back.
• Bench on Finder: observe p50 1.8 ms · tree p50 81 ms · cached find p50 60 µs.

Site + docs

https://guiport.dev

Roadmap

• Linux adapter (AT-SPI2)
• Windows adapter (UI Automation)
• LLM-vision fallback layer
• Cloudflare Pages migration of the landing