AI Repo Commander

A safety-first userscript that lets AI assistants securely interact with your git repos using YAML-style commands — with strong guardrails, persistent de-duplication, and clear feedback.

Highlights

🧱 Execute only inside code blocks — discuss freely in plain text; only fenced blocks run

🛡️ Safety-first: master kill switch, schema validation, per-command debouncing

♻️ Persistent de-duplication (30-day localStorage) — prevents re-runs on reload

⏳ Bot typing protection: 5-second debounce (streams settle before execution)

🧪 Clear status UI: Processing / Success / Error banners in the chat

🔌 Cross-platform: ChatGPT, Claude, Gemini

📋 Robust paste for get_file (DataTransfer → execCommand → ProseMirror → clipboard fallback)

Quick Start

Install Tampermonkey or Violentmonkey in your browser.

Add the userscript: src/ai-repo-commander.user.js (create a new script and paste the file contents).

(Optional) Open the script and review the CONFIG defaults.

In chat, ask the AI to return a code-fenced YAML command (```yaml … ```) that begins with ^%$bridge.

On first API call, you’ll be prompted for your bridge key (stored in memory for this session).

Defaults:

ASSISTANT_ONLY: true — only assistant messages are processed.

PROCESS_EXISTING: false — avoids sweeping old messages on load.

Commands must appear inside a <pre><code> / fenced code block to execute.

Example Commands

Wrap commands in a code block and start with ^%$bridge. The block ends at --- or end-of-code-block.

^%$bridge
action: update_file
repo: my-project
path: README.md
content: |
  Updated content
  with multiple lines
---

^%$bridge
action: get_file
repo: my-project
path: src/index.js
---

Supported Actions & Required Fields
action	required fields	notes
get_file	action, repo, path	Pastes content into the chat input (or copies to clipboard if paste is blocked).
list_files	action, repo, path	Lists files under a path.
create_repo	action, repo	Creates a repo (backend must support it).
create_file	action, repo, path, content	Auto-adds a commit_message if omitted.
update_file	action, repo, path, content	Auto-adds a commit_message if omitted.
delete_file	action, repo, path	Deletes a file.

Optional fields: owner (defaults to rob), url (bridge URL), branch, ref, commit_message.

Configuration (excerpt)
const CONFIG = {
  ENABLE_API: true,              // master kill switch
  DEBUG_MODE: true,
  DEBOUNCE_DELAY: 5000,
  MAX_RETRIES: 2,
  VERSION: '1.2.1',

  PROCESS_EXISTING: false,       // skip old messages on load
  ASSISTANT_ONLY: true,          // process assistant messages by default

  DEDUPE_TTL_MS: 30*24*60*60*1000, // 30d persistent dedupe
  CLEANUP_AFTER_MS: 30000,
  CLEANUP_INTERVAL_MS: 60000
};

How It Works

Detect new assistant messages.

Require a code-fenced block containing ^%$bridge.

Extract & parse YAML; validate required fields and formats.

Debounce for 5 seconds (prevents partial/streaming execution).

Execute against your bridge (with retries & timeouts) or mock if disabled.

Feedback: show a status banner (Processing / Success / Error).

Persist a hash of the executed block for 30 days (prevents re-runs on reload).

Status Messages

[action: Processing…] — making the API request

[action: Success] — operation completed (bridge message shown when available)

[action: Error] — network/timeout/validation error (details included)

Troubleshooting

Command didn’t run

Ensure it’s inside a code block and begins with ^%$bridge.

With defaults, only assistant messages execute (ASSISTANT_ONLY: true).

It may be deduped (already executed). Clear with AI_REPO_CLEAR_HISTORY() or edit the block.

If the AI streamed and then edited the block, the script waits for the final version before running.

get_file didn’t paste

Some editors block synthetic paste. The script falls back to copying to the clipboard and notifies you to paste manually.

Re-running on purpose

Edit any part of the code block (whitespace included) or clear history: AI_REPO_CLEAR_HISTORY().

Emergency stop

Call AI_REPO_STOP() (sets ENABLE_API=false, halts observers).

Runtime Helpers

Emergency stop: AI_REPO_STOP()

Clear persistent history: AI_REPO_CLEAR_HISTORY()

Inspect at runtime: window.AI_REPO_COMMANDER (monitor, config, test, history)

Security Model

Local use: Bridge key is kept in memory for the session (prompted on first API call).

Command validation: required fields, path traversal guards, action whitelist.

Safe defaults: assistant-only, code-block-only, persistent dedupe.

Changelog
v1.2.1

Execute only inside code blocks

Persistent dedupe (30-day localStorage)

Streaming-safe debounce & re-parse

Robust get_file paste with clipboard fallback

Safer assistant detection; initial delayed scan to catch first render

© Your Name. Licensed as you prefer.