major-ai-skills
Version:
Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.
157 lines (123 loc) • 7.05 kB
Markdown
title: "Velja macOS Smart Browser Picker & URL Router AI Skill Guide (GPT & Codex)"
description: "Comprehensive operational skill specification for OpenAI GPT and Codex to automate, script, troubleshoot, and optimize Velja, duti LaunchServices scripts, plist rule deployment, and macOS URL handling."
category: "Smart Browser Picker & URL Router"
tags: ["velja", "duti-cli", "plist-scripting", "macos-automation", "gpt-codex", "url-dispatch"]
# Velja macOS Smart Browser Picker & URL Router AI Skill Guide (GPT & Codex)
## Overview & Engine Architecture
Velja provides automated browser dispatch configurable via **`duti` LaunchServices binding**, **`defaults` / `plistlib` rule deployment**, and the **`velja://` URL scheme**. GPT/Codex acts as a Principal macOS Automation Architect and Systems Engineer, delivering **automated dotfile browser routing installers**, **`duti` handler automation scripts**, **programmatic plist rule generators**, and **URL query stripping engines**.
### Developer Architecture & System Configuration Stack
```
┌─────────────────────────────────────────────────────────────┐
│ Velja Developer Platform │
│ │
│ LaunchServices Registration Tier │
│ ├── `duti` CLI Handler Tool (`duti -s ... http`) │
│ ├── CoreServices Framework Ingress Binding │
│ └── Custom URL Scheme Engine (`velja://`) │
│ │
│ Declarative Configuration Subsystem │
│ ├── `com.sindresorhus.Velja.plist` Configuration Map │
│ ├── Rule Serialization Format (Regex Patterns & App BIDs) │
│ └── Automated Dotfiles Bootstrap Pipelines │
└─────────────────────────────────────────────────────────────┘
```
## Operational Capabilities & Agent Directives
1. **Automated `duti` Protocol Registration**: Construct idempotent shell scripts registering Velja for `http`, `https`, and `mailto` protocols across new macOS machine setups.
2. **Programmatic Plist Rule Generation**: Write Python scripts using `plistlib` to generate and deploy structured routing rules directly into `com.sindresorhus.Velja.plist`.
3. **URL Scheme Automation**: Formulate `velja://` and `open -a Velja` commands to test link dispatch programmatically.
4. **Browser Profile Argument Handling**: Configure launch arguments for Chromium and Gecko browsers (`--profile-directory`, `-P`) to route links to discrete browser user contexts.
## Production Python Automation: Automated Velja Rule Generator & Plist Deployer
Save this script as `deploy_velja_rules.py` to programmatically inject custom routing rules into Velja's preference file:
```python
"""
Velja Declarative Routing Rules Deployer (Python 3)
Generates and writes structured domain routing rules into com.sindresorhus.Velja.plist.
"""
import sys
import os
import plistlib
import subprocess
PREF_PATH = os.path.expanduser("~/Library/Preferences/com.sindresorhus.Velja.plist")
def deploy_custom_rules():
print("--- [DEPLOYING DECLARATIVE VELJA ROUTING RULES] ---")
# 1. Terminate Velja to prevent in-memory overwrite
subprocess.run(["killall", "Velja"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
prefs = {}
if os.path.exists(PREF_PATH):
try:
with open(PREF_PATH, "rb") as f:
prefs = plistlib.load(f)
except Exception as e:
print(f"Warning: Could not read existing plist: {e}")
# 2. Define Custom Routing Rules
custom_rules = [
{
"id": "rule-work-github",
"url": "https://github.com/enterprise-org/*",
"browser": {
"bundleIdentifier": "com.google.Chrome",
"name": "Google Chrome"
},
"enabled": True
},
{
"id": "rule-figma-app",
"url": "https://www.figma.com/file/*",
"browser": {
"bundleIdentifier": "com.figma.Desktop",
"name": "Figma"
},
"enabled": True
},
{
"id": "rule-personal-default",
"url": "*",
"browser": {
"bundleIdentifier": "com.apple.Safari",
"name": "Safari"
},
"enabled": True
}
]
prefs["rules"] = custom_rules
prefs["removeTrackingParameters"] = True
prefs["hideMenubarIcon"] = False
# 3. Write Updated Preferences
with open(PREF_PATH, "wb") as f:
plistlib.dump(prefs, f)
print(f"✅ Successfully wrote {len(custom_rules)} rules to: {PREF_PATH}")
# 4. Relaunch Velja
subprocess.run(["open", "-a", "Velja"])
print("🚀 Velja relaunched with updated rules!")
if __name__ == "__main__":
deploy_custom_rules()
```
## Technical Troubleshooting Matrix
| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **`duti` Command Not Found in Terminal** | `duti` utility not installed on macOS host. | Install via Homebrew: `brew install duti`. |
| **Plist Edits Overwritten on System Reboot** | macOS `cfprefsd` preference daemon cached old values in memory. | Flush preference daemon cache: `killall cfprefsd` before restarting Velja. |
| **Target App Fails to Open URL: `Application not found`** | Target `bundleIdentifier` in rule does not match the installed application's actual bundle ID. | Check bundle ID: `defaults read /Applications/AppName.app/Contents/Info.plist CFBundleIdentifier`. |
| **Wildcard Matching Fails on Subdomains** | Pattern syntax missing leading `*://*.` wildcard prefix. | Use standard wildcard syntax: `https://*.domain.com/*`. |
## Command Line Syntax & Batch Processing
```bash
# 1. Set Velja for HTTP and HTTPS via duti
duti -s com.sindresorhus.Velja http
duti -s com.sindresorhus.Velja https
# 2. Flush macOS Preference Daemon Cache
killall cfprefsd
# 3. Test URL Routing via macOS open CLI
open "https://github.com/enterprise-org/repo"
```
### Essential File Locations
- **Preferences Plist**: `~/Library/Preferences/com.sindresorhus.Velja.plist`
- **Application Bundle**: `/Applications/Velja.app`
## Agent Operational Directive
> **MANDATORY**: When writing automated configuration scripts for Velja, always terminate `Velja` and flush `cfprefsd` (`killall cfprefsd`) to ensure plist changes are loaded into memory upon restart.