AI-Repo-Commander/README.md

AI Repo Commander

A safety-first userscript that lets AI assistants securely interact with git repositories using YAML-style commands. It provides strong guardrails, persistent de-duplication, a draggable debug panel with tools and settings, and robust paste/autosubmit for get_file.

Highlights

• Code-block only execution (only fenced YAML with the bridge header runs)
• Safety-first: STOP switch, strict validation, debounce + settle
• Resume-safe scanning: resuming marks on-screen commands as processed and shows Run again instead of auto-executing
• Persistent de-duplication per conversation (30-day TTL)
• Streaming-safe: waits for final text before executing
• Clear feedback: inline status and desktop notifications
• Cross-platform: ChatGPT, Claude, Gemini
• Tools & Settings panel: bridge key editor, config JSON, clear history
• Robust paste & auto-submit with fallbacks for get_file

Quick Start

1. Install Tampermonkey or Violentmonkey.
2. Create a new userscript and paste src/ai-repo-commander.user.js.
3. Ask the assistant to produce a YAML block beginning with @bridge@ and ending with @end@.
4. Enter your bridge key when prompted (you can store it in the panel).
5. Adjust settings in Tools & Settings as needed.

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
DEDUPE_TTL_MS: 2592000000
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

Supported Actions (required fields)

• get_file: action, repo, path
• list_files: action, repo, path
• create_file: action, repo, path, content
• update_file: action, repo, path, content
• delete_file: action, repo, path
• create_repo: action, repo
• create_branch: action, repo, branch (source_branch defaults to main)
• create_pr: action, repo, title, head, base
• merge_pr: action, repo, pr_number
• close_pr: action, repo, pr_number
• create_issue: action, repo, title
• comment_issue: action, repo, issue_number, body
• close_issue: action, repo, issue_number
• create_tag: action, repo, tag, target
• create_release: action, repo, tag_name, name
• rollback: action, repo, commit_sha

* owner defaults to config or repository prefix

Operation Summary

1. Monitor assistant messages
2. Detect a complete YAML command: header plus terminator
3. Debounce and settle, then re-validate
4. Execute via the bridge with retries and timeouts
5. Show inline status and store dedupe record
6. Expose a Run Again button for intentional re-execution

Diagrams (PlantUML)

The following PlantUML diagrams provide a high-level overview of the codebase:

• Architecture Overview: Docs/diagrams/architecture-overview.puml
• Command Execution Sequence: Docs/diagrams/sequence-command-execution.puml
• Command Processing State Machine: Docs/diagrams/state-machine.puml

How to view:

• Use any PlantUML renderer (IntelliJ/VSCode plugin, plantuml.com/plantuml, or local PlantUML jar)
• Copy the contents of a .puml file into your renderer to generate the diagram image

New in v1.6.2

• Resume-Safe Guard: On resume, treat like a cold start and mark visible commands as processed, preventing accidental re-execution.
• Example Field Support: Add example: true to any command block to make it inert. It’s silently skipped (no error UI).
• Paste Quality: Added padding around pasted content to preserve triple-backtick fences in ProseMirror fields.
• Debounce Timing Notes: If you see “debouncing → error,” try DEBOUNCE_DELAY: 5000–7000 and SETTLE_CHECK_MS: 1200–1500.
• Version: Bumped to 1.6.2.

Examples

Runnable - Not an example - (example: false (or absence) is runnable):

@bridge@
action: list_files
repo: rob/AI-Repo-Commander
path: .
@end@

Inert example (skipped silently):

@bridge@
action: update_file
repo: rob/AI-Repo-Commander
path: EXAMPLE.md
content: |
  This is just an example
  It won't execute  
example: true
@end@

Runtime Helpers

• AI_REPO_STOP(): emergency stop
• AI_REPO.clearHistory: clear dedupe history
• window.AI_REPO_COMMANDER: monitor, config, tests, history

Security Model

• Bridge key stored locally and masked, never logged
• Field validation including path safety and typed values
• Assistant-only and code-block-only execution by default
• STOP immediately halts scanning and API calls

Changelog

v1.6.2

Resume-safe guard; example: true support; ProseMirror paste padding; timing docs; version bump.

v1.4.1 (previous)

Tools/Settings panel, parser hardening, new routes (PRs, Issues, Releases, Tags, Rollback), per-convo dedupe + Run Again UI, streaming settle improvements, auto-submit/paste fallback, configurable timeouts/retries.