🧠 AI Repo Commander

A safety-first userscript that lets AI assistants securely interact with your Git repositories using YAML-style commands.
It enforces strict validation, persistent de-duplication, and a command-queue pipeline that prevents overloads while staying streaming-safe and cross-assistant compatible.

🚀 Highlights

🧩 Code-block-only execution – only fenced YAML blocks beginning with @bridge@ and ending with @end@ run.

🛡️ Safety-first – master STOP switch, strict schema checks, per-message caps, rate-limited command queue.

🔄 Persistent de-duplication – remembers executed commands for 30 days and exposes Run Again for manual re-runs.

🕒 Streaming-safe – waits for full assistant output and composer readiness before pasting or submitting.

🧭 Queue manager – serializes multiple commands from one response, limits per-minute rate, allows clear/cancel.

💬 Inline feedback – status chips, console logs, and desktop notifications for every stage.

🧰 Debug Panel – draggable / collapsible UI with:

Tools & Settings tab (bridge key editor, config JSON, clear history, queue controls)

Real-time log viewer with copy buttons

Pause/Resume toggle and emergency STOP

🌐 Cross-platform – works with ChatGPT, Claude, Gemini, and others.

⚙️ Quick Start

Install Tampermonkey or Violentmonkey.

Create a new userscript and paste src/ai-repo-commander.user.js.

In chat, have the assistant output YAML like:

@bridge@
action: list_files
owner: rob
repo: ai-workflow-test
path: .
@end@


When prompted, enter your bridge key (stored locally, masked).

Use the debug panel → Tools & Settings to adjust behavior, clear history, or manage the queue.

🧩 Default Configuration (excerpt)
ENABLE_API: true
DEBUG_MODE: true
ASSISTANT_ONLY: true
PROCESS_EXISTING: false
DEBOUNCE_DELAY: 3000
REQUIRE_TERMINATOR: true
SETTLE_CHECK_MS: 800
SETTLE_POLL_MS: 200
API_TIMEOUT_MS: 60000
MAX_RETRIES: 2
DEDUP_TTL_MS: 2592000000   # 30 days
COLD_START_MS: 2000
SHOW_EXECUTED_MARKER: true
CLEANUP_AFTER_MS: 30000
CLEANUP_INTERVAL_MS: 60000
APPEND_TRAILING_NEWLINE: true
AUTO_SUBMIT: true
POST_PASTE_DELAY_MS: 250
SUBMIT_MODE: button_first
STUCK_AFTER_MS: 600000
SCAN_DEBOUNCE_MS: 250
FAST_WARN_MS: 50
SLOW_WARN_MS: 60000
QUEUE_MIN_DELAY_MS: 800
QUEUE_MAX_PER_MINUTE: 15
QUEUE_MAX_PER_MESSAGE: 5
QUEUE_WAIT_FOR_COMPOSER_MS: 6000

🧰 Supported Actions (required fields)
Category	Action	Required fields
Files	get_file, list_files, create_file, update_file, delete_file	repo, path (+ content for create/update)
Branch & PR	create_branch, create_pr, merge_pr, close_pr	see branch, head, base, pr_number
Issues	create_issue, comment_issue, close_issue	issue_number or title, body
Tags & Releases	create_tag, create_release	tag / tag_name, target, name
Maintenance	rollback	commit_sha
🧮 Operation Summary

Monitor assistant messages in real time.

Detect every complete YAML block (@bridge@ → @end@).

Queue all valid commands – rate-limited and serialized.

Debounce + Settle, re-validate, and call your bridge API.

Paste or submit responses back into chat once the composer is ready.

Show feedback inline + notifications and persist dedupe history.

Allow re-execution via the Run Again button or queue controls.

🧠 Runtime Helpers
Function	Purpose
AI_REPO_STOP()	Emergency stop – kills scanning + clears the queue.
AI_REPO_CLEAR_HISTORY()	Forget all dedupe records for this conversation.
window.AI_REPO_QUEUE.clear()	Manually empty the command queue.
window.AI_REPO_COMMANDER	Exposes monitor, config, history, tests, etc.
🔐 Security Model

Bridge key stored locally, masked, never logged or transmitted beyond the bridge call.

Field-level validation for paths, types, and required keys.

Assistant-only + code-block-only execution by default.

Hard STOP halts scanning, clears queue, and disables API immediately.

Optional ASSISTANT_ONLY and PROCESS_EXISTING flags protect against replay.

🧾 Changelog Highlights
v1.6 series

🔁 Multi-command execution with rate-limited queue

🕐 Per-message and per-minute caps

📦 Queue UI controls + size indicator + clear button

✨ Improved paste pipeline (wait for composer ready, re-enqueue if busy)

🧩 Index-aware dedupe and retry for multi-block messages

🧱 Cleaner Debug Panel buttons with click feedback (flash + toast)

v1.5 series

🪟 Draggable Debug Panel with Tools & Settings tab

⚙️ Persistent config storage and JSON editor

🧹 Clear History button and pause/resume toggle

🔍 Enhanced logging and structured debug levels

v1.4 series

Parser hardening for multiline content and body/message fields

New routes: PRs, Issues, Releases, Tags, Rollback

Per-conversation dedupe with Run Again UI

Streaming settle improvements and auto-submit fallbacks

🧪 Example Usage
@bridge@
action: update_file
owner: rob
repo: ai-workflow-test
path: roles/mission_control.md
content: |
  Updated mission protocol — verified.
@end@


You can also send several commands in one reply:

@bridge@
action: update_file
repo: ai-workflow-test
path: tmp/a.md
content: First file
@end@

@bridge@
action: update_file
repo: ai-workflow-test
path: tmp/b.md
content: Second file
@end@


AI Repo Commander will queue both, run them safely in order, and display progress and results.