184 lines
5.2 KiB
Markdown
184 lines
5.2 KiB
Markdown
🧠 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.
|