▶ Zap

Run selected shell commands from any webpage directly into your active tmux session — with one click.

---

How it works

flowchart TB
    B e1@-->C
    C e2@-->a1
    subgraph ide1 [tmux]
    direction LR
        a1["tmux send keys"]
    end
    C["Python Host"]
    subgraph ide2 [Chrome]
    direction LR
    A["Chrome Extension"]-->B["Native Messaging"]
    end

   
    style C fill:#78A4CB,stroke:#333,stroke-width:1px  
    e1@{ animate: true }
    e2@{ animate: true }

Loading

• Select any command-like text on a page → a Run / Paste toolbar appears
• Right-click any selection → "Run in tmux" or "Copy to tmux"
• Run = sends the command + Enter (executes immediately)
• Paste = types the command without Enter (lets you review first)

---

Installation

Step 1 – Install the native host

cd native-host
chmod +x install.sh
./install.sh

This will:

• Copy the Python host to ~/.config/zap/
• Generate a secure auth token
• Install the native messaging manifest for Chrome/Chromium
• Print your auth token — copy it!

Step 2 – Load the Chrome extension

1. Open chrome://extensions
2. Enable Developer mode (top right toggle)
3. Click Load unpacked
4. Select the extension/ folder from this project

Step 3 – Link the extension ID

After loading, Chrome shows a 32-character extension ID. Run:

cd native-host
./update-extension-id.sh YOUR_EXTENSION_ID_HERE

Step 4 – Authenticate

1. Click the tmux Runner icon in Chrome toolbar
2. Paste the token from Step 1
3. Click Verify — you should see "Connected to native host"

---

Usage

Floating toolbar

Select any text that looks like a shell command on any page. A small toolbar appears:

• ▶ Run – executes the command in your tmux pane
• ⎘ Paste – types it without pressing Enter

Right-click menu

Right-click any selected text → Run in tmux or Copy to tmux (no enter)

Targeting a specific pane

By default, commands go to your currently active tmux pane.

To target a specific pane, open the extension popup and set a target like:

• main – a session named "main"
• 0:1.0 – session 0, window 1, pane 0
• work:code – session "work", window "code"

Run tmux list-sessions or tmux list-panes -a to find targets.

---

Security

• All commands require a token stored in ~/.config/zap/token
• The token uses hmac.compare_digest (constant-time comparison)
• The native host only accepts connections from your extension
• Token is never exposed to web pages — only the background script has it

To regenerate the token: re-run install.sh

---

File structure

zap/
├── extension/
│   ├── manifest.json      # Chrome extension manifest (MV3)
│   ├── background.js      # Service worker, native messaging
│   ├── content.js         # Floating toolbar, toast notifications
│   ├── content.css        # Toolbar & toast styles
│   ├── popup.html/js      # Extension popup (auth + settings)
│   └── icons/             # Extension icons
└── native-host/
    ├── tmux_runner_host.py  # Native messaging host (Python)
    ├── install.sh           # One-shot installer
    └── update-extension-id.sh  # Generated by install.sh

---

Troubleshooting

"Native host not found"
→ Run install.sh and update-extension-id.sh with the correct extension ID.

Commands go to the wrong pane
→ Set an explicit target in the popup, or ensure the right pane is active.

Token verification fails
→ Check ~/.config/zap/host.log for errors. Re-run install.sh to regenerate.

Toolbar doesn't appear
→ The heuristic filters for command-like text. Try right-click → "Run in tmux" instead.