AI DevOps Framework

aidevops.sh — Unleash your AI assistant's true potential with specialist DevOps agents, designed to manage all your infrastructure and services with security and reliability guidance on every decision.

"List all my servers and websites, and check each for theme and plugin update needs, SEO and page loading performance scores, and give me a list of recommended priorities" - One conversation, complete infrastructure management.

The Philosophy

Sane vibe-coding through git workflow best practices. aidevops brings structure to AI-assisted development:

• Git-first workflow - Protected branches, PR reviews, quality gates before merge
• Parallel agents - Multiple AI sessions running full Ralph loops on separate branches via git worktrees
• Progressive discovery - /slash commands and @subagent mentions load knowledge into context only when needed
• Guided development - Build your AI team incrementally, with specialists for every online need

The result: AI agents that work with your development process, not around it.

Built on proven patterns: aidevops implements industry-standard agent design patterns validated across Claude Code, Manus, and Cursor - including multi-layer action spaces, context isolation, and iterative execution loops.

aidevops knows what you need to know.

Why This Framework?

Beyond Single-Repo Limitations: VS Code and Web UIs work on one repo at a time. CLI AI assistants can manage your entire infrastructure when given the right tools, access, and guidance.

DevOps Superpowers for AI:

• Multi-Service Management: 30+ APIs (hosting, Git, security, monitoring, deployment)
• Real-Time Operations: SSH, domain management, database operations
• Cross-Service Intelligence: Connect patterns across your entire ecosystem
• Unlimited Scope: Full access to your development infrastructure for bug fixes and feature development

Quick Reference

• Purpose: AI-assisted DevOps automation framework
• Install: npm install -g aidevops && aidevops update
• Entry: aidevops CLI, ~/.aidevops/agents/AGENTS.md
• Stack: Bash scripts, TypeScript (Bun), MCP servers

Key Commands

• aidevops init - Initialize in any project
• aidevops update - Update framework
• /onboarding - Interactive setup wizard (in AI assistant)

Agent Structure

• Primary agents (Build+, SEO, Marketing, etc.) with @plan-plus subagent for planning-only mode
• 539+ subagent markdown files organized by domain
• 148 helper scripts in .agent/scripts/
• 16 slash commands for common workflows

Enterprise-Grade Quality & Security

Comprehensive DevOps framework with tried & tested services integrations, popular and trusted MCP servers, and enterprise-grade infrastructure quality assurance code monitoring and recommendations.

Security Notice

This framework provides agentic AI assistants with powerful infrastructure access. Use responsibly.

Capabilities: Execute commands, access credentials, modify infrastructure, interact with APIs Your responsibility: Use trusted AI providers, rotate credentials regularly, monitor activity

Quick Start

Installation Options

npm (recommended - verified provenance):

npm install -g aidevops && aidevops update

Note: npm suppresses postinstall output. The && aidevops update deploys agents to ~/.aidevops/agents/. The CLI will remind you if agents need updating.

Bun (fast alternative):

bun install -g aidevops && aidevops update

Homebrew (macOS/Linux):

brew install marcusquinn/tap/aidevops && aidevops update

Direct from source (aidevops.sh):

bash <(curl -fsSL https://aidevops.sh/install)

Manual (git clone):

git clone https://github.com/marcusquinn/aidevops.git ~/Git/aidevops
~/Git/aidevops/setup.sh

That's it! The setup script will:

• Clone/update the repo to ~/Git/aidevops
• Deploy agents to ~/.aidevops/agents/
• Install the aidevops CLI command
• Configure your AI assistants automatically
• Guide you through recommended tools (Tabby, Zed, Git CLIs)

New users: Start OpenCode and type /onboarding to configure your services interactively. OpenCode is the recommended tool for aidevops - all features, agents, and workflows are designed and tested for it first. The onboarding wizard will:

• Explain what aidevops can do
• Ask about your work to give personalized recommendations
• Show which services are configured vs need setup
• Guide you through setting up each service with links and commands

After installation, use the CLI:

aidevops status           # Check what's installed
aidevops update           # Update framework + check registered projects
aidevops init             # Initialize aidevops in any project
aidevops features         # List available features
aidevops repos            # List/add/remove registered projects
aidevops detect           # Scan for unregistered aidevops projects
aidevops upgrade-planning # Upgrade TODO.md/PLANS.md to latest templates
aidevops update-tools     # Check and update installed tools
aidevops uninstall        # Remove aidevops

Project tracking: When you run aidevops init, the project is automatically registered in ~/.config/aidevops/repos.json. Running aidevops update checks all registered projects for version updates.

Use aidevops in Any Project

Initialize aidevops features in any git repository:

cd ~/your-project
aidevops init                         # Enable all features
aidevops init planning                # Enable only planning
aidevops init planning,time-tracking  # Enable specific features

This creates:

• .aidevops.json - Configuration with enabled features
• .agent symlink → ~/.aidevops/agents/
• TODO.md - Quick task tracking with time estimates
• todo/PLANS.md - Complex execution plans
• .beads/ - Task graph database (if beads enabled)

Available features: planning, git-workflow, code-quality, time-tracking, beads

Upgrade Planning Files

When aidevops templates evolve, upgrade existing projects to the latest format:

aidevops upgrade-planning           # Interactive upgrade with backup
aidevops upgrade-planning --dry-run # Preview changes without modifying
aidevops upgrade-planning --force   # Skip confirmation prompt

This preserves your existing tasks while adding TOON-enhanced parsing, dependency tracking, and better structure.

Automatic detection: aidevops update now scans all registered projects for outdated planning templates (comparing TOON meta version numbers) and offers to upgrade them in-place with backups.

Task Graph Visualization with Beads

Beads provides task dependency tracking and graph visualization:

aidevops init beads              # Enable beads (includes planning)

Task Dependencies:

- [ ] t001 First task
- [ ] t002 Second task blocked-by:t001
- [ ] t001.1 Subtask of t001

Commands:

Architecture: aidevops markdown files (TODO.md, PLANS.md) are the source of truth. Beads syncs from them for visualization.

Optional Viewers: Beyond the bd CLI, there are community viewers for richer visualization:

• beads_viewer (Python TUI) - PageRank, critical path analysis
• beads-ui (Web) - Live updates in browser
• bdui (React/Ink TUI) - Modern terminal UI
• perles (Rust TUI) - BQL query language

See .agent/tools/task-management/beads.md for complete documentation and installation commands.

Your AI assistant now has agentic access to 30+ service integrations.

OpenCode Antigravity OAuth Plugin

The setup automatically installs the opencode-antigravity-auth plugin, enabling Google OAuth authentication for OpenCode. This gives you access to Antigravity rate limits and premium models.

After setup, authenticate:

opencode auth login
# Select: Google → OAuth with Google (Antigravity)
# Press Enter to skip Project ID prompt

Available models via Antigravity:

• gemini-3-pro-high / gemini-3-pro-low / gemini-3-flash
• claude-sonnet-4-5 / claude-sonnet-4-5-thinking / claude-opus-4-5-thinking
• gpt-oss-120b-medium

Multi-account load balancing: Add multiple Google accounts for automatic rate limit distribution and failover. See the plugin documentation for model configuration.

OpenCode Anthropic OAuth (Built-in)

OpenCode v1.1.36+ includes Anthropic OAuth authentication natively. No external plugin is needed.

After setup, authenticate:

opencode auth login
# Select: Anthropic → Claude Pro/Max
# Follow OAuth flow in browser

Benefits:

• Zero cost for Claude Pro/Max subscribers (covered by subscription)
• Automatic token refresh - No manual re-authentication needed
• Beta features enabled - Extended thinking modes and latest features

Oh-My-OpenCode Plugin (Optional)

The setup offers to install oh-my-opencode - a complementary plugin that adds coding productivity features:

How they complement each other:

• aidevops provides DevOps infrastructure (30+ services: hosting, DNS, WordPress, SEO, code quality)
• oh-my-opencode provides coding productivity (LSP, AST, background agents, hooks)

Usage after installation:

# Trigger maximum performance mode
> ultrawork implement the authentication system

# Use curated agents
> @oracle review this architecture
> @librarian find examples of this pattern on GitHub
> @explore search for authentication handling

See .agent/tools/opencode/oh-my-opencode.md for the full compatibility guide.

GitHub AI Agent Integration

Enable AI-powered issue resolution directly from GitHub. Comment /oc fix this on any issue and the AI creates a branch, implements the fix, and opens a PR.

Security-first design - The workflow includes:

• Trusted users only (OWNER/MEMBER/COLLABORATOR)
• ai-approved label required on issues before AI processing
• Prompt injection pattern detection
• Audit logging of all invocations
• 15-minute timeout and rate limiting

Quick setup:

# 1. Install the OpenCode GitHub App
# Visit: https://github.com/apps/opencode-agent

# 2. Add API key secret
# Repository → Settings → Secrets → ANTHROPIC_API_KEY

# 3. Create required labels
gh label create "ai-approved" --color "0E8A16" --description "Issue approved for AI agent"
gh label create "security-review" --color "D93F0B" --description "Requires security review"

The secure workflow is included at .github/workflows/opencode-agent.yml.

Usage:

See .agent/tools/git/opencode-github-security.md for the full security documentation.

Supported AI Assistants: OpenCode is the recommended and primary-tested tool. All 18 assistants below have MCP configuration support, but only OpenCode receives continual testing and first-class integration. Other tools are supported as a courtesy for users evaluating aidevops capabilities.

Recommended:

• OpenCode - The recommended AI coding agent. Powerful agentic TUI/CLI with native MCP support, Tab-based agent switching, LSP integration, plugin ecosystem, and excellent DX. All aidevops features are designed and tested for OpenCode first.
• Tabby - Recommended terminal. Colour-coded Profiles per project/repo, auto-syncs tab title with git repo/branch.
• Zed - Recommended editor. High-performance with AI integration (use with the OpenCode Agent Extension).

Terminal Tab Title Sync

Your terminal tab/window title automatically shows repo/branch context when working in git repositories. This helps identify which codebase and branch you're working on across multiple terminal sessions.

Supported terminals: Tabby, iTerm2, Windows Terminal, Kitty, Alacritty, WezTerm, Hyper, and most xterm-compatible terminals.

How it works: The pre-edit-check.sh script's primary role is enforcing git workflow protection (blocking edits on main/master branches). As a secondary, non-blocking action, it updates the terminal title via escape sequences. No configuration needed - it's automatic.

Example format: {repo}/{branch-type}/{description}

See .agent/tools/terminal/terminal-title.md for customization options.

Also Supported (community-tested):

IDE-Based:

• Cursor - AI-first IDE with MCP support
• Windsurf - Codeium's AI IDE
• Continue.dev - VS Code/JetBrains extension
• Cody - Sourcegraph's AI assistant

Claude Family:

• Claude Code - CLI version with claude mcp add
• Claude Desktop - GUI with MCP config

Enterprise & Professional:

• Factory AI Droid - Enterprise-grade agentic AI
• Augment Code - Deep codebase indexing
• GitHub Copilot - Agent mode for MCP

Specialized:

• Kilo Code - VS Code extension
• Kiro - AWS's AI assistant
• AntiGravity - AI coding tool
• Gemini CLI - Google's CLI

Terminal & CLI:

• Aider - CLI pair programmer with native MCP
• Warp AI - Terminal with AI (no native MCP, use OpenCode/Claude in Warp)
• Qwen - Alibaba's CLI (MCP support experimental)

Core Capabilities

AI-First Infrastructure Management:

• SSH server access, remote command execution, API integrations
• DNS management, application deployment, email monitoring
• Git platform management, domain purchasing, setup automation
• WordPress management, credential security, code auditing

Unified Interface:

• Standardized commands across all providers
• Automated SSH configuration and multi-account support for all services
• Security-first design with comprehensive logging, code quality reviews, and continual feedback-based improvement

Quality Control & Monitoring:

• Multi-Platform Analysis: SonarCloud, CodeFactor, Codacy, CodeRabbit, Qlty, Gemini Code Assist, Snyk
• Performance Auditing: PageSpeed Insights, Lighthouse, Core Web Vitals (/performance command)
• SEO Debugging: Open Graph validation, favicon checker, social preview testing
• Email Deliverability: SPF/DKIM/DMARC/MX validation, blacklist checking
• Uptime Monitoring: Updown.io integration for website and SSL monitoring

Imported Skills

aidevops includes curated skills imported from external sources. Skills support automatic update tracking:

CLI Commands:

aidevops skill add <owner/repo>    # Import a skill from GitHub
aidevops skill add clawdhub:<slug> # Import a skill from ClawdHub
aidevops skill list                # List imported skills
aidevops skill check               # Check for upstream updates
aidevops skill update [name]       # Update specific or all skills
aidevops skill remove <name>       # Remove an imported skill

Skills are registered in ~/.aidevops/agents/configs/skill-sources.json with upstream tracking for update detection. Telemetry is disabled - no data is sent to third parties.

Browse community skills: skills.sh | ClawdHub | Specification: agentskills.io

Reference:

• Agent Skills Specification - The open format for SKILL.md files
• skills.sh Leaderboard - Discover popular community skills
• ClawdHub - Skill registry with vector search (Moltbot ecosystem)
• vercel-labs/add-skill - The upstream CLI tool (aidevops uses its own implementation)
• anthropics/skills - Official Anthropic example skills
• agentskills/agentskills - Specification source and reference library

Agent Design Patterns

aidevops implements proven agent design patterns identified by Lance Martin (LangChain) and validated across successful agents like Claude Code, Manus, and Cursor.

Key insight: Context is a finite resource with diminishing returns. aidevops treats every token as precious - loading only what's needed, when it's needed.

See .agent/aidevops/architecture.md for detailed implementation notes and references.

Multi-Agent Orchestration

Run multiple AI agents in parallel on separate branches, coordinated through a lightweight mailbox system. Each agent works independently in its own git worktree while a stateless coordinator manages task distribution and status reporting.

Architecture:

Coordinator (pulse loop)
├── Agent Registry (TOON format - who's active, what branch, idle/busy)
├── Mailbox System (file-based, per-agent inbox/outbox)
│   ├── task_assignment → worker inbox
│   ├── status_report → coordinator outbox
│   └── broadcast → all agents
└── Model Routing (tier-based: haiku/sonnet/opus/flash/pro)

Key components:

How it works:

1. Each agent registers on startup (mail-helper.sh register --role worker)
2. Coordinator runs periodic pulses (coordinator-helper.sh pulse)
3. Pulse collects status reports, dispatches queued tasks to idle workers
4. Agents send completion reports back via outbox
5. File locking (noclobber + retry) prevents race conditions

Compaction plugin (.agent/plugins/opencode-aidevops/): When OpenCode compacts context (at ~200K tokens), the plugin injects current session state - agent registry, pending mailbox messages, git context, and relevant memories - ensuring continuity across compaction boundaries.

Custom system prompt (.agent/prompts/build.txt): Based on upstream OpenCode with aidevops-specific overrides for tool preferences, professional objectivity, and per-model reinforcements for weaker models.

Subagent index (.agent/subagent-index.toon): Compressed TOON routing table listing all agents, subagents, workflows, and scripts with model tier assignments - enables fast agent discovery without loading full markdown files.

Requirements

# Install dependencies (auto-detected by setup.sh)
brew install sshpass jq curl mkcert dnsmasq fd ripgrep  # macOS
sudo apt-get install sshpass jq curl dnsmasq fd-find ripgrep  # Ubuntu/Debian

# Generate SSH key
ssh-keygen -t ed25519 -C "your-email@domain.com"

File Discovery Tools

AI agents use fast file discovery tools for efficient codebase navigation:

Both tools respect .gitignore by default and are written in Rust for maximum performance.

Preference order for file discovery:

1. git ls-files '*.md' - Instant, git-tracked files only
2. fd -e md - Fast, respects .gitignore
3. rg --files -g '*.md' - Fast, respects .gitignore
4. Built-in glob tools - Fallback when bash unavailable

The setup script offers to install these tools automatically.

Comprehensive Service Coverage

Infrastructure & Hosting

• Hostinger: Shared hosting, domains, email
• Hetzner Cloud: VPS servers, networking, load balancers
• Closte: Managed hosting, application deployment
• Coolify Enhanced with CLI: Self-hosted PaaS with CLI integration
• Cloudron Enhanced with packaging guide: Server and app management platform with custom app packaging support
• Vercel Enhanced with CLI: Modern web deployment platform with CLI integration
• AWS: Cloud infrastructure support via standard protocols
• DigitalOcean: Cloud infrastructure support via standard protocols

Domain & DNS

• Cloudflare: DNS, CDN, security services
• Spaceship: Domain registration and management
• 101domains: Domain purchasing and DNS
• AWS Route 53: AWS DNS management
• Namecheap: Domain and DNS services

Development & Git Platforms with CLI Integration

• GitHub Enhanced with CLI: Repository management, actions, API, GitHub CLI (gh) integration
• GitLab Enhanced with CLI: Self-hosted and cloud Git platform with GitLab CLI (glab) integration
• Gitea Enhanced with CLI: Lightweight Git service with Gitea CLI (tea) integration
• Agno: Local AI agent operating system for DevOps automation
• Pandoc: Document conversion to markdown for AI processing

AI Orchestration Frameworks

• Langflow: Visual drag-and-drop builder for AI workflows (MIT, localhost:7860)
• CrewAI: Multi-agent teams with role-based orchestration (MIT, localhost:8501)
• AutoGen: Microsoft's agentic AI framework with MCP support (MIT, localhost:8081)

Video Creation

• Remotion: Programmatic video creation with React - animations, compositions, media handling, captions
• Video Prompt Design: AI video prompt engineering using the 7-component meta prompt framework for Veo 3 and similar models
• yt-dlp: YouTube video/audio/playlist/channel downloads, transcript extraction, and local file audio conversion via ffmpeg

WordPress Development

• LocalWP: WordPress development environment with MCP database access
• MainWP: WordPress site management dashboard

Git CLI Enhancement Features:

• .agent/scripts/github-cli-helper.sh: Advanced GitHub repository, issue, PR, and branch management
• .agent/scripts/gitlab-cli-helper.sh: Complete GitLab project, issue, MR, and branch management
• .agent/scripts/gitea-cli-helper.sh: Full Gitea repository, issue, PR, and branch management

Security & Code Quality

• Vaultwarden: Password and secrets management
• SonarCloud: Security and quality analysis (A-grade ratings)
• CodeFactor: Code quality metrics (A+ score)
• Codacy: Multi-tool analysis (0 findings)
• CodeRabbit: AI-powered code reviews
• Snyk: Security vulnerability scanning
• Qlty: Universal code quality platform (70+ linters, auto-fixes)
• Gemini Code Assist: Google's AI-powered code completion and review

AI Prompt Optimization

• Augment Context Engine: Semantic codebase retrieval with deep code understanding
• Repomix: Pack codebases into AI-friendly context (80% token reduction with compress mode)
• DSPy: Framework for programming with language models
• DSPyGround: Interactive playground for prompt optimization
• TOON Format: Token-Oriented Object Notation - 20-60% token reduction for LLM prompts

Document Processing

• LibPDF: PDF form filling, digital signatures (PAdES B-B/T/LT/LTA), encryption, merge/split, text extraction
• Unstract: LLM-powered structured data extraction from unstructured documents (PDF, images, DOCX)

Communications

• Twilio: SMS, voice calls, WhatsApp, phone verification (Verify API), call recording & transcription
• Telfon: Twilio-powered cloud phone system with iOS/Android/Chrome apps for end-user calling interface

Animation & Video

• Anime.js: Lightweight JavaScript animation library for CSS, SVG, DOM attributes, and JS objects
• Remotion: Programmatic video creation with React - create videos using code with 29 specialized rule files
• Video Prompt Design: Structured prompt engineering for AI video generation (Veo 3, 7-component framework, character consistency, audio design)

Performance & Monitoring

• PageSpeed Insights: Website performance auditing
• Lighthouse: Comprehensive web app analysis
• Updown.io: Website uptime and SSL monitoring

AI & Documentation

• Context7: Real-time documentation access for libraries and frameworks

MCP Integrations

Model Context Protocol servers for real-time AI assistant integration. The framework configures these MCPs primarily for OpenCode (recommended). Configuration support is also available for 17 other AI assistants including Cursor, Claude Code/Desktop, Windsurf, Continue.dev, Cody, Zed, GitHub Copilot, Kilo Code, Kiro, AntiGravity, Gemini CLI, Droid, Warp AI, Aider, and Qwen.

All Supported MCPs (19 active)

MCP packages are installed globally via bun install -g for instant startup (no npx registry lookups). Run setup.sh or aidevops update-tools to update to latest versions.

Tier explanation:

• Global - Tools always available (loaded into every session)
• Per-agent - Tools disabled globally, enabled per-agent via config (zero context overhead when unused)

Performance optimization: MCP packages are installed globally via bun install -g for instant startup (~0.1s vs 2-3s with npx). The framework uses a three-tier loading strategy: 7 MCPs load eagerly at startup, 13 MCPs load on-demand when their subagent is invoked. This reduces OpenCode startup time by 12-24 seconds.

SEO Integrations (curl subagents - no MCP overhead)

These use direct API calls via curl, avoiding MCP server startup entirely:

By Category

Context & Codebase:

• Augment Context Engine - Semantic codebase retrieval with deep code understanding
• llm-tldr - Semantic code analysis with 95% token savings (tree, structure, CFG, DFG, impact analysis)
• osgrep - Local semantic search (100% private, no cloud)
• Context7 - Real-time documentation access for thousands of libraries
• Repomix - Pack codebases into AI-friendly context

Browser Automation (8 tools + anti-detect stack, benchmarked):

• Playwright - Fastest engine (0.9s form fill), parallel contexts, extensions, proxy (auto-installed)
• playwright-cli - Microsoft official CLI for AI agents, --session isolation, built-in tracing
• dev-browser - Persistent profile, stays logged in, ARIA snapshots, pairs with DevTools
• agent-browser - CLI/CI/CD, --session parallel, ref-based element targeting
• Crawl4AI - Bulk extraction, arun_many parallel (1.7x), LLM-ready markdown
• WaterCrawl - Self-hosted crawling with web search, sitemap generation, JS rendering, proxy support
• Playwriter - Your browser's extensions/passwords/proxy, already unlocked
• Stagehand - Natural language automation, self-healing selectors
• Chrome DevTools MCP - Companion: Lighthouse, network throttling, CSS coverage (pairs with any tool)
• Cloudflare Browser Rendering - Server-side web scraping
• Peekaboo - macOS screen capture and GUI automation (pixel-accurate captures, AI vision analysis)
• Sweet Cookie - Browser cookie extraction for API calls without launching a browser
• Anti-Detect Stack (details):
  • Camoufox (4.9k stars) - Firefox anti-detect, C++ fingerprint injection, WebRTC/Canvas/WebGL spoofing
  • rebrowser-patches (1.2k stars) - Chromium CDP leak prevention, automation signal removal
  • Multi-profile management - Persistent/clean/warm/disposable profiles (like AdsPower/GoLogin)
  • Proxy integration - Residential, SOCKS5, VPN per profile with geo-targeting

SEO & Research:

• Google Search Console - Search performance insights (MCP)
• Grep by Vercel - Search code snippets across GitHub repositories (MCP)
• Ahrefs - SEO analysis, backlink research, keyword data (curl subagent)
• DataForSEO - Comprehensive SEO data APIs (curl subagent)
• Serper - Google Search API (curl subagent)
• Keyword Research - Strategic keyword research with SERP weakness detection (via DataForSEO + Serper + Ahrefs)
• Site Crawler - Screaming Frog-like SEO auditing: broken links, redirects, meta issues, structured data
• Domain Research - DNS intelligence via THC (4.51B records) and Reconeer APIs: rDNS, subdomains, CNAMEs
• NeuronWriter - Content optimization with NLP analysis, competitor research, and content scoring (curl subagent)

Data Extraction:

• Outscraper - Google Maps, business data, reviews extraction

Performance & Security:

• PageSpeed Insights - Website performance auditing
• Snyk - Security vulnerability scanning

WordPress & Development:

• LocalWP - Direct WordPress database access
• WordPress MCP Adapter - Official WordPress MCP for content management (STDIO, HTTP, and SSH transports)
• Next.js DevTools - React/Next.js development assistance

CRM & Marketing:

• FluentCRM - WordPress CRM: contacts, tags, lists, campaigns, automations, smart links, webhooks

Accounts & Finance:

• QuickFile - Accounting API integration (MCP)
• Amazon Order History - Order data extraction (MCP)

Document Processing:

• LibPDF - PDF form filling, digital signatures, encryption, merge/split (via helper script)
• Unstract - LLM-powered structured data extraction from PDFs, images, DOCX (MCP)

Quick Setup

# Install all MCP integrations
bash .agent/scripts/setup-mcp-integrations.sh all

# Install specific integration
bash .agent/scripts/setup-mcp-integrations.sh stagehand          # JavaScript version
bash .agent/scripts/setup-mcp-integrations.sh stagehand-python   # Python version
bash .agent/scripts/setup-mcp-integrations.sh stagehand-both     # Both versions
bash .agent/scripts/setup-mcp-integrations.sh chrome-devtools

OpenCode LSP Configuration

OpenCode includes built-in LSP servers for 35+ languages. For aidevops projects that use Markdown and TOON extensively, add these optional LSP servers to your opencode.json for real-time diagnostics during editing:

{
  "lsp": {
    "markdownlint": {
      "command": ["markdownlint-language-server", "--stdio"],
      "extensions": [".md"]
    },
    "toon-lsp": {
      "command": ["toon-lsp"],
      "extensions": [".toon"]
    }
  }
}

Install the servers:

npm install -g markdownlint-language-server  # Markdown diagnostics
cargo install toon-lsp                        # TOON syntax validation

These catch formatting and syntax issues during editing, reducing preflight/postflight fix cycles.

Browser Automation

8 browser tools + anti-detect stack, benchmarked and integrated for AI-assisted web automation, dev testing, data extraction, and bot detection evasion. Agents automatically select the optimal tool based on task requirements.

Performance Benchmarks

Tested on macOS ARM64, all headless, warm daemon:

Feature Matrix

Tool Selection

AI Page Understanding

Agents use lightweight methods instead of expensive vision API calls:

See .agent/tools/browser/browser-automation.md for the full decision tree and browser-benchmark.md for reproducible benchmark scripts.

Anti-Detect Browser

Open-source alternative to AdsPower, GoLogin, and OctoBrowser for multi-account automation and bot detection evasion.

Architecture:

Layer 4: CAPTCHA Solving    → CapSolver (existing)
Layer 3: Network Identity   → Proxies (residential/SOCKS5/VPN per profile)
Layer 2: Browser Identity   → Camoufox (C++ fingerprint injection)
Layer 1: Automation Stealth → rebrowser-patches (CDP leak prevention)
Layer 0: Browser Engine     → Playwright (existing)

Profile Types:

Quick Start:

# Setup
anti-detect-helper.sh setup

# Create profile with proxy
anti-detect-helper.sh profile create "my-account" --type persistent --os macos

# Launch (Camoufox with auto-generated fingerprint)
anti-detect-helper.sh launch --profile "my-account" --headless

# Test detection (BrowserScan, SannyBot)
anti-detect-helper.sh test --profile "my-account"

# Warm up profile with browsing history
anti-detect-helper.sh warmup "my-account" --duration 30m

Engine Selection:

See .agent/tools/browser/anti-detect-browser.md for the full decision tree and subagent index.

Repomix - AI Context Generation

Repomix packages your codebase into AI-friendly formats for sharing with AI assistants. This framework includes optimized Repomix configuration for consistent context generation.

Why Repomix?

Quick Usage

# Pack current repo with configured defaults
npx repomix

# Compress mode (~80% smaller, structure only)
npx repomix --compress

# Or use the helper script
.agent/scripts/context-builder-helper.sh pack      # Full context
.agent/scripts/context-builder-helper.sh compress  # Compressed

Configuration Files

Key Design Decisions

• No pre-generated files: Outputs are generated on-demand to avoid staleness
• Inherits .gitignore: Security patterns automatically respected
• Secretlint enabled: Scans for exposed credentials before output
• Symlinks excluded: Avoids duplicating .agent/ content

MCP Integration

Repomix runs as an MCP server for direct AI assistant integration:

{
  "repomix": {
    "type": "local",
    "command": ["repomix", "--mcp"],
    "enabled": true
  }
}

Install globally first: bun install -g repomix (done automatically by setup.sh)

See .agent/tools/context/context-builder.md for complete documentation.

Augment Context Engine - Semantic Codebase Search

Augment Context Engine provides semantic codebase retrieval - understanding your code at a deeper level than simple text search. It's the recommended tool for real-time interactive coding sessions.

Why Augment Context Engine?

Use it to:

• Find related code across your entire codebase
• Understand project architecture quickly
• Discover patterns and implementations
• Get context-aware code suggestions

Quick Setup

# 1. Install Auggie CLI (requires Node.js 22+)
npm install -g @augmentcode/auggie@prerelease

# 2. Authenticate (opens browser)
auggie login

# 3. Verify installation
auggie token print

MCP Integration

Add to your AI assistant's MCP configuration:

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "augment-context-engine": {
      "type": "local",
      "command": ["auggie", "--mcp"],
      "enabled": true
    }
  }
}

Claude Code:

claude mcp add-json auggie-mcp --scope user '{"type":"stdio","command":"auggie","args":["--mcp"]}'

Cursor: Settings → Tools & MCP → New MCP Server:

{
  "mcpServers": {
    "augment-context-engine": {
      "command": "bash",
      "args": ["-c", "auggie --mcp -m default -w \"${WORKSPACE_FOLDER_PATHS%%,*}\""]
    }
  }
}

Verification

Test with this prompt:

What is this project? Please use codebase retrieval tool to get the answer.

The AI should provide a semantic understanding of your project architecture.

Repomix vs Augment Context Engine

See .agent/tools/context/augment-context-engine.md for complete documentation including configurations for Zed, GitHub Copilot, Kilo Code, Kiro, AntiGravity, Gemini CLI, and Factory.AI Droid.

osgrep - Local Alternative (Experimental)

osgrep provides 100% local semantic search with no cloud dependency:

npm install -g osgrep && osgrep setup
osgrep "where is authentication handled?"

See .agent/tools/context/osgrep.md for complete documentation and AI tool configurations.

llm-tldr - Semantic Code Analysis

llm-tldr extracts code structure and semantics, saving ~95% tokens compared to raw code. From the Continuous-Claude project.

# Install
pip install llm-tldr

# CLI usage
tldr tree ./src                    # File structure with line counts
tldr structure src/auth.py         # Code skeleton (classes, functions)
tldr context src/auth.py           # Full semantic analysis
tldr search "authentication" ./src # Semantic code search
tldr impact src/auth.py validate   # What would change affect?

MCP Integration:

{
  "llm-tldr": {
    "command": "tldr-mcp",
    "args": ["--project", "${workspaceFolder}"]
  }
}

See .agent/tools/context/llm-tldr.md for complete documentation.

Cross-Tool Compatibility

Agent Skills Standard

aidevops implements the Agent Skills standard for cross-tool compatibility. Skills are auto-discovered by compatible AI assistants.

Generated SKILL.md files in ~/.aidevops/agents/ provide skill metadata for:

• Cursor
• Claude Code
• VS Code (GitHub Copilot)
• Other Agent Skills-compatible tools

Claude Code Plugin Marketplace

aidevops is registered as a Claude Code plugin marketplace. Install with two commands:

/plugin marketplace add marcusquinn/aidevops
/plugin install aidevops@aidevops

This installs the complete framework: 15 primary agents, 552+ subagents, and 147 helper scripts.

Importing External Skills

Import skills from GitHub or ClawdHub using the aidevops skill CLI:

# Import from GitHub (auto-detects format)
aidevops skill add owner/repo

# Import from ClawdHub (skill registry with vector search)
aidevops skill add clawdhub:caldav-calendar
aidevops skill add https://clawdhub.com/owner/slug

# More examples
aidevops skill add anthropics/skills/pdf           # Specific skill from multi-skill repo
aidevops skill add vercel-labs/agent-skills         # All skills from a repo
aidevops skill add expo/skills --name expo-dev      # Custom name
aidevops skill add owner/repo --dry-run             # Preview without changes

Supported sources:

• GitHub repos (owner/repo or full URL) — fetched via git clone
• ClawdHub (clawdhub:slug or full URL) — fetched via Playwright browser automation

Supported formats:

• SKILL.md - Agent Skills standard (preferred)
• AGENTS.md - Claude Code agents format
• .cursorrules - Cursor rules (auto-converted)

Features:

• Auto-detection of skill format and category placement
• Conflict detection with merge/replace/rename options
• Upstream commit tracking for update detection (aidevops skill check)
• Conversion to aidevops subagent format with YAML frontmatter
• Registry stored in .agent/configs/skill-sources.json
• Telemetry disabled (no data sent to skills.sh or other services)

How it differs from npx add-skill:

See .agent/scripts/add-skill-helper.sh for implementation details.

AI Agents & Subagents

Agents are specialized AI personas with focused knowledge and tool access. Instead of giving your AI assistant access to everything at once (which wastes context tokens), agents provide targeted capabilities for specific tasks.

Call them in your AI assistant conversation with a simple @mention

How Agents Work

Main Agents

Ordered as they appear in OpenCode Tab selector and other AI assistants (15 total):

Example Subagents with MCP Integration

These are examples of subagents that have supporting MCPs enabled. See .agent/ for the full list of 552+ subagents organized by domain.

Setup for OpenCode

# Install aidevops agents for OpenCode
.agent/scripts/generate-opencode-agents.sh

# Check status
.agent/scripts/generate-opencode-agents.sh  # Shows status after generation

Setup for Other AI Assistants

Claude Code (recommended):

/plugin marketplace add marcusquinn/aidevops
/plugin install aidevops-all@aidevops

Agent Skills-compatible tools (Cursor, VS Code, etc.): Skills are auto-discovered from ~/.aidevops/agents/ via SKILL.md files after running setup.sh.

Manual configuration (other tools): Add to your AI assistant's system prompt:

Before any DevOps operations, read ~/git/aidevops/AGENTS.md for authoritative guidance.

When working with specific services, read the corresponding .agent/[service].md file
for focused guidance. Available services: hostinger, hetzner, wordpress, seo,
code-quality, browser-automation, git-platforms.

Continuous Improvement with @agent-review

End every session by calling @agent-review to analyze what worked and what didn't:

@agent-review analyze this session and suggest improvements to the agents used

The review agent will:

1. Identify which agents were used
2. Evaluate missing, incorrect, or excessive information
3. Suggest specific improvements to agent files
4. Generate ready-to-apply edits
5. Optionally compose a PR to contribute improvements back to aidevops

This creates a feedback loop:

Session → @agent-review → Improvements → Better Agents → Better Sessions
                ↓
         PR to aidevops repo (optional)

Contributing improvements:

@agent-review create a PR for improvement #2

The agent will create a branch, apply changes, and submit a PR to marcusquinn/aidevops with a structured description. Your real-world usage helps improve the framework for everyone.

Code quality learning loop:

The @code-quality agent also learns from issues. After fixing violations from SonarCloud, Codacy, ShellCheck, etc., it analyzes patterns and updates framework guidance to prevent recurrence:

Quality Issue → Fix Applied → Pattern Identified → Framework Updated → Issue Prevented

Slash Commands (OpenCode)

Slash commands provide quick access to common workflows directly from the OpenCode prompt. Type / to see available commands.

Available Commands

Planning & Task Management:

Plans are tracked in TODO.md (all tasks) and todo/PLANS.md (complex execution plans). Task dependencies are visualized with Beads.

/list-todo options:

Time Tracking: Tasks support time estimates as active session time (excluding AFK gaps) with the format ~4h started:2025-01-15T10:30Z. The session-time-helper.sh analyses real session data to calibrate estimates vs actuals.

Risk Levels: Tasks support risk:low/med/high indicating human oversight needed:

Configure time tracking per-repo via .aidevops.json.

Development Workflow (typical order):

Content Workflow:

Media:

SEO Workflow:

SEO Debugging (subagents in seo/):

Email Deliverability:

Release Workflow (in order):

Auto-Task Completion: The release workflow automatically marks tasks as complete when commit messages reference them (e.g., Closes t037, Fixes t042). Tasks in TODO.md are updated with completed: timestamps.

Documentation:

Meta/Improvement:

Ralph Loop - Iterative AI Development

The Ralph Loop (named after Ralph Wiggum's persistent optimism) enables autonomous iterative development. The AI keeps working on a task until it's complete, automatically resolving issues that arise.

How it works:

Task → Implement → Check → Fix Issues → Re-check → ... → Complete
         ↑                    ↓
         └────────────────────┘ (loop until done)

Usage:

# Run quality checks iteratively until all pass
.agent/scripts/quality-loop-helper.sh preflight --auto-fix --max-iterations <MAX_ITERATIONS>

# Or use the slash command
/preflight-loop --auto-fix --max-iterations <MAX_ITERATIONS>

Note: Store any API credentials securely via environment variables or .env files (never commit credentials to version control).

Key features:

• Automatic issue detection and resolution
• Configurable max iterations (prevents infinite loops)
• Works with any quality check (linting, tests, builds)
• Detailed logging of each iteration

See .agent/workflows/ralph-loop.md for the full workflow guide.

Full Loop - End-to-End Development Automation

The Full Loop chains all development phases into a single automated workflow:

Task Development → Preflight → PR Create → PR Review → Postflight → Deploy

Usage:

# Start a full development loop
/full-loop "Implement feature X with tests"

# With options
/full-loop "Fix bug Y" --max-task-iterations 30 --skip-postflight

Options:

The loop pauses for human input at merge approval, rollback decisions, and scope changes.

See .agent/scripts/commands/full-loop.md for complete documentation.

Git Worktrees - Parallel Branch Development

Work on multiple branches simultaneously without stashing or switching. Each branch gets its own directory.

Recommended: Worktrunk (wt) - Git worktree management with shell integration, CI status, and PR links:

# Install (macOS/Linux)
brew install max-sixty/worktrunk/wt && wt config shell install
# Restart your shell for shell integration to take effect

# Create worktree + cd into it
wt switch -c feature/my-feature

# Create worktree + start any AI CLI (-x runs command after switch)
wt switch -c -x claude feature/ai-task

# List worktrees with CI status and PR links
wt list

# Merge + cleanup (squash/rebase options)
wt merge

Fallback (no dependencies):

~/.aidevops/agents/scripts/worktree-helper.sh add feature/my-feature
# Creates: ~/Git/{repo}-feature-my-feature/ (cd there manually)
~/.aidevops/agents/scripts/worktree-helper.sh list
~/.aidevops/agents/scripts/worktree-helper.sh clean

Benefits:

• Run tests on one branch while coding on another
• Compare implementations side-by-side
• No context switching or stash management
• Each AI session can work on a different branch

Worktree-first workflow: The pre-edit check now enforces worktrees as the default when creating branches, keeping your main directory on main. This prevents uncommitted changes from blocking branch switches and ensures parallel sessions don't inherit wrong branch state.

See .agent/workflows/worktree.md for the complete guide and .agent/tools/git/worktrunk.md for Worktrunk documentation.

Session Management - Parallel AI Sessions

Spawn new AI sessions for parallel work or fresh context. The framework detects natural session completion points and suggests next steps.

Completion signals:

Spawning options:

# Background session (same terminal)
opencode --non-interactive --prompt "Continue with feature X" &

# New terminal tab (macOS)
osascript -e 'tell application "Terminal" to do script "cd ~/Git/project && opencode"'

# Worktree-based (isolated branch) - recommended
wt switch -c -x opencode feature/next-feature  # Worktrunk: create + start AI CLI
# Or fallback:
# ~/.aidevops/agents/scripts/worktree-helper.sh add feature/next-feature
# cd ~/Git/{repo}-feature-next-feature && opencode

Session handoff pattern:

When ending a session, the AI provides a continuation prompt for the next session:

## Continuation Prompt
[Copy this to start a new session with full context]

See .agent/workflows/session-manager.md for the complete guide.

Cross-Session Memory System

"Compound, then clear" - Sessions should build on each other. The memory system stores knowledge, patterns, and learnings for future sessions using SQLite FTS5 for fast full-text search.

Slash commands:

Memory types:

CLI usage:

# Store a memory
~/.aidevops/agents/scripts/memory-helper.sh store "WORKING_SOLUTION" "Fixed CORS with nginx headers" "cors,nginx"

# Recall memories
~/.aidevops/agents/scripts/memory-helper.sh recall "cors"

# View statistics
~/.aidevops/agents/scripts/memory-helper.sh stats

# Maintenance
~/.aidevops/agents/scripts/memory-helper.sh validate   # Check for stale entries
~/.aidevops/agents/scripts/memory-helper.sh prune      # Remove stale memories

Storage: ~/.aidevops/.agent-workspace/memory/memory.db

See .agent/memory/README.md for complete documentation.

Installation

Slash commands are automatically installed by setup.sh:

# Commands are deployed to:
~/.config/opencode/commands/

# Regenerate commands manually:
.agent/scripts/generate-opencode-commands.sh

Usage

In OpenCode, type the command at the prompt:

/preflight
/release minor
/feature add-user-authentication

Commands invoke the corresponding workflow subagent with appropriate context.

Creating Custom Agents

Create a markdown file in ~/.config/opencode/agent/ (OpenCode) or reference in your AI's system prompt:

---
description: Short description of what this agent does
mode: subagent
temperature: 0.2
tools:
  bash: true
  specific-mcp_*: true
---

# Agent Name

Detailed instructions for the agent...

See .agent/opencode-integration.md for complete documentation.

Usage Examples

Server Management

# List all servers across providers
./.agent/scripts/servers-helper.sh list

# Connect to specific servers
./.agent/scripts/hostinger-helper.sh connect example.com
./.agent/scripts/hetzner-helper.sh connect main web-server

# Execute commands remotely
./.agent/scripts/hostinger-helper.sh exec example.com "uptime"

Monitoring & Uptime (Updown.io)

# List all monitors
./.agent/scripts/updown-helper.sh list

# Add a new website check
./.agent/scripts/updown-helper.sh add https://example.com "My Website"

Domain & DNS Management

# Purchase and configure domain
./.agent/scripts/spaceship-helper.sh purchase example.com
./.agent/scripts/dns-helper.sh cloudflare add-record example.com A 192.168.1.1

# Check domain availability
./.agent/scripts/101domains-helper.sh check-availability example.com

Strategic Keyword Research

# Basic keyword research with volume, CPC, difficulty
./.agent/scripts/keyword-research-helper.sh research "seo tools" --limit 20

# Google autocomplete long-tail discovery
./.agent/scripts/keyword-research-helper.sh autocomplete "how to" --provider both

# Extended research with SERP weakness detection
./.agent/scripts/keyword-research-helper.sh extended "keywords" --quick

# Competitor keyword research
./.agent/scripts/keyword-research-helper.sh extended --competitor ahrefs.com --limit 50

# Keyword gap analysis (find keywords competitor ranks for but you don't)
./.agent/scripts/keyword-research-helper.sh extended --gap semrush.com,ahrefs.com

# Domain research (all keywords a domain ranks for)
./.agent/scripts/keyword-research-helper.sh extended --domain example.com --limit 100

Features:

• 6 Research Modes: Keyword expansion, autocomplete, domain research, competitor research, keyword gap, extended SERP analysis
• 17 SERP Weaknesses: Low domain score, no backlinks, thin content, UGC-heavy, non-HTTPS, and more
• KeywordScore Algorithm: 0-100 score based on weakness count, volume, and difficulty
• Multi-Provider: DataForSEO (primary), Serper (autocomplete), Ahrefs (domain ratings)
• Locale Support: US/UK/CA/AU/DE/FR/ES with saved preferences
• Output Formats: Markdown tables (TUI) and CSV export to ~/Downloads

Quality Control & Performance

# Run quality analysis with auto-fixes
bash .agent/scripts/qlty-cli.sh check 10
bash .agent/scripts/qlty-cli.sh fix

# Run chunked Codacy analysis for large repositories
bash .agent/scripts/codacy-cli-chunked.sh quick    # Fast analysis
bash .agent/scripts/codacy-cli-chunked.sh chunked # Full analysis

# AI coding assistance
bash .agent/scripts/ampcode-cli.sh scan ./src
bash .agent/scripts/continue-cli.sh review

# Audit website performance
./.agent/scripts/pagespeed-helper.sh wordpress https://example.com

Documentation & Resources

Wiki Guides:

• Getting Started - Installation and setup
• CLI Reference - aidevops command documentation
• MCP Integrations - MCP servers setup
• Providers - Service provider configurations
• Workflows Guide - Development workflows
• The Agent Directory - Agent file structure
• Understanding AGENTS.md - How agents work

Agent Guides (in .agent/):

• API Integrations - Service APIs
• Browser Automation - 6 tools + anti-detect stack: decision tree, parallel, extensions, fingerprinting
• Anti-Detect Browser - Multi-profile management, fingerprint rotation, proxy integration
• Web Performance - Core Web Vitals, network dependencies, accessibility (Chrome DevTools MCP)
• PageSpeed - Lighthouse CLI and PageSpeed Insights API
• Pandoc - Document format conversion
• Security - Enterprise security standards

Provider-Specific Guides: Hostinger, Hetzner, Cloudflare, WordPress, Git platforms, Vercel CLI, Coolify CLI, and more in .agent/

Architecture

aidevops/
├── setup.sh                       # Main setup script
├── AGENTS.md                      # AI agent guidance (dev)
├── .agent/                        # Agents and documentation
│   ├── AGENTS.md                  # User guide (deployed to ~/.aidevops/agents/)
│   ├── *.md                       # 15 primary agents
│   ├── scripts/                   # 146 helper scripts
│   ├── tools/                     # Cross-domain utilities (video, browser, git, etc.)
│   ├── services/                  # External service integrations
│   └── workflows/                 # Development process guides
├── configs/                       # Configuration templates
├── ssh/                           # SSH key management
└── templates/                     # Reusable templates

Configuration & Setup

# 1. Copy and customize configuration templates
cp configs/hostinger-config.json.txt configs/hostinger-config.json
cp configs/hetzner-config.json.txt configs/hetzner-config.json
# Edit with your actual credentials

# 2. Test connections
./.agent/scripts/servers-helper.sh list

# 3. Install MCP integrations (optional)
bash .agent/scripts/setup-mcp-integrations.sh all

Security & Best Practices

Credential Management:

• Store API tokens in separate config files (never hardcode)
• Use Ed25519 SSH keys (modern, secure, fast)
• Set proper file permissions (600 for configs)
• Regular key rotation and access audits

Multi-Tenant Credential Storage

Manage multiple accounts/clients per service with isolated credential sets:

# Create a new tenant
credential-helper.sh create client-acme

# Switch active tenant
credential-helper.sh switch client-acme

# Set credentials for current tenant
credential-helper.sh set GITHUB_TOKEN ghp_xxx

# Per-project override (gitignored)
echo "client-acme" > .aidevops-tenant

# Export for scripts
eval $(credential-helper.sh export)

Resolution priority: Project .aidevops-tenant → Global active tenant → Default

See .agent/tools/credentials/multi-tenant.md for complete documentation.

Quality Assurance:

• Multi-platform analysis (SonarCloud, CodeFactor, Codacy, CodeRabbit, Qlty, Snyk, Gemini Code Assist)
• Automated security monitoring and vulnerability detection

Contributing & License

Contributing:

1. Fork the repository
2. Create feature branch
3. Add provider support or improvements
4. Test with your infrastructure
5. Submit pull request

License: MIT License - see LICENSE file for details Created by Marcus Quinn - Copyright © 2025-2026

What This Framework Achieves

For You:

• Unified infrastructure management across all services
• AI-powered automation with standardized commands
• Enterprise-grade security and quality assurance
• Time savings through consistent interfaces

For Your AI Assistant:

• Structured access to entire DevOps ecosystem
• Real-time documentation via Context7 MCP
• Quality control with automated fixes
• Performance monitoring with and continual improvement of agents' token efficiency, tool use, and file location consistency

Get Started:

# npm (recommended)
npm install -g aidevops && aidevops update

# Bun (fast alternative)
bun install -g aidevops && aidevops update

# Homebrew
brew install marcusquinn/tap/aidevops && aidevops update

# Direct from source
bash <(curl -fsSL https://aidevops.sh/install)

Transform your AI assistant into a powerful infrastructure management tool with seamless access to all your servers and services.