AI DevOps Framework - AI-assisted development workflows, code quality, and deployment automation
npm install aidevopsaidevops.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.
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 - including multi-layer action spaces, context isolation, and iterative execution loops.
aidevops knows what you need to know.
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
---
- 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
- aidevops init - Initialize in any project
- aidevops update - Update framework
- aidevops secret - Manage secrets (gopass encrypted, AI-safe)
- /onboarding - Interactive setup wizard (in AI assistant)
- Primary agents (Build+, SEO, Marketing, etc.) with @plan-plus subagent for planning-only mode
- 765+ subagent markdown files organized by domain
- 172 helper scripts in .agents/scripts/
- 28 slash commands for common workflows
Comprehensive DevOps framework with tried & tested services integrations, popular and trusted MCP servers, and enterprise-grade infrastructure quality assurance code monitoring and recommendations.
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
npm (recommended - verified provenance):
``bash`
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):
`bash`
bun install -g aidevops && aidevops update
Homebrew (macOS/Linux):
`bash`
brew install marcusquinn/tap/aidevops && aidevops update
Direct from source (aidevops.sh):
`bash`
bash <(curl -fsSL https://aidevops.sh/install)
Manual (git clone):
`bash`
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
- Install the CLI command
- Configure your AI assistants automatically
- Offer to install Oh My Zsh (optional, opt-in) for enhanced shell experience
- Guide you through recommended tools (Tabby, Zed, Git CLIs)
- Ensure all PATH and alias changes work in both bash and zsh
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:
`bash`
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.
Initialize aidevops features in any git repository:
`bash`
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.agents
- symlink → ~/.aidevops/agents/
- - Quick task tracking with time estimatestodo/PLANS.md
- - Complex execution plans.beads/
- - Task graph database (if beads enabled)
Available features: planning, git-workflow, code-quality, time-tracking, beads
When aidevops templates evolve, upgrade existing projects to the latest format:
`bash`
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.
Beads provides task dependency tracking and graph visualization:
`bash`
aidevops init beads # Enable beads (includes planning)
Task Dependencies:
`markdown`
- [ ] t001 First task
- [ ] t002 Second task blocked-by:t001
- [ ] t001.1 Subtask of t001
| Syntax | Meaning |
|--------|---------|
| blocked-by:t001 | Task waits for t001 to complete |blocks:t002
| | This task blocks t002 |t001.1
| | Subtask of t001 (hierarchical) |
Commands:
| Command | Purpose |
|---------|---------|
| /ready | Show tasks with no open blockers |/sync-beads
| | Sync TODO.md/PLANS.md with Beads graph |bd list
| | List all tasks in Beads |bd ready
| | Show ready tasks (Beads CLI) |bd graph
| | Show dependency graph for an issue |
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 analysisbeads-ui
- (Web) - Live updates in browserbdui
- (React/Ink TUI) - Modern terminal UIperles
- (Rust TUI) - BQL query language
See .agents/tools/task-management/beads.md for complete documentation and installation commands.
Your AI assistant now has agentic access to 30+ service integrations.
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:
`bash`
opencode auth loginSelect: 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-thinking / claude-opus-4-5-thinking
-
Multi-account load balancing: Add multiple Google accounts for automatic rate limit distribution and failover. See the plugin documentation for model configuration.
OpenCode v1.1.36+ includes Anthropic OAuth authentication natively. No external plugin is needed.
After setup, authenticate:
`bash`
opencode auth loginSelect: 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
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:
`bash1. Install the OpenCode GitHub App
Visit: https://github.com/apps/opencode-agent
The secure workflow is included at
.Usage:
| Context | Command | Result |
|---------|---------|--------|
| Issue (with
ai-approved label) | /oc fix this | Creates branch + PR |
| Issue | /oc explain this | AI analyzes and replies |
| PR | /oc review this PR | Code review feedback |
| PR Files tab | /oc add error handling here | Line-specific fix |See
.agents/tools/git/opencode-github-security.md for the full security documentation.Supported AI Assistant: OpenCode is the only tested and supported AI coding tool for aidevops. All features, agents, and workflows are designed and tested for OpenCode first. The claude-code CLI is used as a companion tool called from within OpenCode.
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).
$3
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
for customization options.Companion tool:
- claude-code CLI - Called from within OpenCode for sub-tasks and headless dispatch
Collaborator compatibility: Projects initialized with
aidevops init include pointer files (.cursorrules, .windsurfrules, etc.) that reference AGENTS.md, helping collaborators using other editors find project context. aidevops does not install into or configure those tools.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
Autonomous Orchestration:
- Supervisor - SQLite state machine dispatches tasks to parallel AI agents with retry cycles, batch management, and cron scheduling
- Runners - Named headless agent instances with persistent identity, instructions, and memory namespaces
-
/runners command - Batch dispatch from task IDs, PR URLs, or descriptions with concurrency control and progress monitoring
- Mailbox - SQLite-backed inter-agent messaging for coordination across parallel sessions
- Worktree isolation - Each agent works on its own branch in a separate directory, no merge conflictsUnified 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, WebPageTest, Core Web Vitals (
/performance command)
- SEO Toolchain: 13 SEO subagents including Semrush, Ahrefs, ContentKing, Screaming Frog, Bing Webmaster Tools, Rich Results Test, programmatic SEO, analytics tracking, schema validation
- 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 monitoringImported Skills
aidevops includes curated skills imported from external sources. Skills support automatic update tracking:
| Skill | Source | Description |
|-------|--------|-------------|
| cloudflare-platform | dmmulroy/cloudflare-skill | 60 Cloudflare products: Workers, Pages, D1, R2, KV, Durable Objects, AI, networking, security |
| heygen | heygen-com/skills | AI avatar video creation API: avatars, voices, video generation, streaming, webhooks |
| remotion | remotion-dev/skills | Programmatic video creation with React, animations, rendering |
| video-prompt-design | snubroot/Veo-3-Meta-Framework | AI video prompt engineering - 7-component meta prompt framework for Veo 3 |
| animejs | animejs.com | JavaScript animation library patterns and API (via Context7) |
| caldav-calendar | ClawdHub | CalDAV calendar sync via vdirsyncer + khal (iCloud, Google, Fastmail, Nextcloud) |
| proxmox-full | ClawdHub | Complete Proxmox VE hypervisor management via REST API |
CLI Commands:
`bash
aidevops skill add # Import a skill from GitHub
aidevops skill add clawdhub: # 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 scan [name] # Security scan skills (Cisco Skill Scanner)
aidevops skill remove # Remove an imported skill
`Skills are registered in
with upstream tracking for update detection.Security Scanning:
Imported skills are automatically security-scanned using Cisco Skill Scanner when installed. Scanning runs on both initial import and updates -- pulling a new version of a skill triggers the same security checks as the first import. CRITICAL/HIGH findings block the operation; MEDIUM/LOW findings warn but allow. Telemetry is disabled - no data is sent to third parties.
When a VirusTotal API key is configured (
aidevops secret set VIRUSTOTAL_MARCUSQUINN), an advisory second layer scans file hashes against 70+ AV engines and checks domains/URLs referenced in skill content. VT scans are non-blocking -- the Cisco scanner remains the security gate.| Scenario | Security scan runs? | CRITICAL/HIGH blocks? |
|----------|--------------------|-----------------------|
|
aidevops skill add | Yes | Yes |
| aidevops skill update [name] | Yes | Yes |
| aidevops skill add | Yes | Yes |
| aidevops skill add | Yes (reports only) | No (warns) |
| aidevops skill scan [name] | Yes (standalone) | Report only |The
--force flag only controls file overwrite behavior (replacing an existing skill without prompting). To bypass security blocking, use --skip-security explicitly -- this separation ensures that routine updates and re-imports never silently skip security checks..agents/SKILL-SCAN-RESULTS.md automatically on each batch scan and skill import, providing a transparent audit trail of security posture over time.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 (OpenClaw 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).
| Pattern | Description | aidevops Implementation |
|---------|-------------|------------------------|
| Give Agents a Computer | Filesystem + shell for persistent context |
~/.aidevops/.agent-workspace/, 172 helper scripts |
| Multi-Layer Action Space | Few tools, push actions to computer | Per-agent MCP filtering (~12-20 tools each) |
| Progressive Disclosure | Load context on-demand | Subagent routing with content summaries, YAML frontmatter, read-on-demand |
| Offload Context | Write results to filesystem | .agent-workspace/work/[project]/ for persistence |
| Cache Context | Prompt caching for cost | Stable instruction prefixes |
| Isolate Context | Sub-agents with separate windows | Subagent files with specific tool permissions |
| Multi-Agent Orchestration | Coordinate parallel agents | TOON mailbox, agent registry, stateless coordinator |
| Compaction Resilience | Preserve context across compaction | OpenCode plugin injects dynamic state at compaction time |
| Ralph Loop | Iterative execution until complete | ralph-loop-helper.sh, full-loop-helper.sh |
| Evolve Context | Learn from sessions | /remember, /recall with SQLite FTS5 + opt-in semantic search |
| Pattern Tracking | Learn what works/fails | pattern-tracker-helper.sh, /patterns command |
| Cost-Aware Routing | Match model to task complexity | model-routing.md with 5-tier guidance, /route command |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
.agents/aidevops/architecture.md for detailed implementation notes and references.$3
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:
`text
Coordinator (pulse loop)
├── Agent Registry (TOON format - who's active, what branch, idle/busy)
├── Mailbox System (SQLite WAL-mode, indexed queries)
│ ├── task_assignment → worker inbox
│ ├── status_report → coordinator outbox
│ └── broadcast → all agents
└── Model Routing (tier-based: haiku/sonnet/opus/flash/pro)
`Key components:
| Component | Script | Purpose |
|-----------|--------|---------|
| Mailbox |
| SQLite-backed inter-agent messaging (send, check, broadcast, archive) |
| Coordinator | coordinator-helper.sh | Stateless pulse loop: collect reports, dispatch tasks, track idle workers |
| Supervisor | supervisor-helper.sh | Autonomous multi-task orchestration with SQLite state machine, batches, retry cycles, cron scheduling, auto-pickup from TODO.md |
| Registry | mail-helper.sh register | Agent registration with role, branch, worktree, heartbeat |
| Model routing | model-routing.md, /route | Cost-aware 5-tier routing guidance (haiku/flash/sonnet/pro/opus) |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 mailbox
5. SQLite WAL mode + busy_timeout handles concurrent access (79x faster than previous file-based system)Compaction plugin (
.agents/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 (
.agents/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 (
.agents/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.Autonomous Orchestration & Parallel Agents
Why this matters: Long-running tasks -- batch PR reviews, multi-site SEO audits, large refactors -- are where AI agents deliver the most value. Instead of babysitting one task at a time, the supervisor dispatches work to parallel agents, each in its own git worktree, with automatic retry, progress tracking, and batch completion reporting.
$3
Run multiple AI sessions concurrently with isolated contexts. Named runners provide persistent agent identities with their own instructions and memory.
| Feature | Description |
|---------|-------------|
| Headless dispatch |
opencode run for one-shot tasks, opencode serve + --attach for warm server |
| Runners | Named agent instances with per-runner AGENTS.md, config, and run logs (runner-helper.sh) |
| Session management | Resume sessions with -s or -c, fork with SDK |
| Memory namespaces | Per-runner memory isolation with shared access when needed |
| SDK orchestration | @opencode-ai/sdk for TypeScript parallel dispatch via Promise.all |
| Matrix integration | Chat-triggered dispatch via self-hosted Matrix (optional) |`bash
Create a named runner
runner-helper.sh create code-reviewer --description "Reviews code for security and quality"Dispatch a task (one-shot)
runner-helper.sh run code-reviewer "Review src/auth/ for vulnerabilities"Dispatch against warm server (faster, no MCP cold boot)
opencode serve --port 4096 &
runner-helper.sh run code-reviewer "Review src/auth/" --attach http://localhost:4096Parallel dispatch via CLI
opencode run --attach http://localhost:4096 --title "Review" "Review src/auth/" &
opencode run --attach http://localhost:4096 --title "Tests" "Generate tests for src/utils/" &
waitList runners and status
runner-helper.sh list
runner-helper.sh status code-reviewer
`Architecture:
text
OpenCode Server (opencode serve)
├── Session 1 (runner/code-reviewer)
├── Session 2 (runner/seo-analyst)
└── Session 3 (scheduled-task)
↑
HTTP API / SSE Events
↑
┌────────┴────────┐
│ Dispatch Layer │ ← runner-helper.sh, cron, Matrix bot, SDK
└─────────────────┘
`Example runner templates: code-reviewer, seo-analyst - copy and customize for your own runners.
Matrix bot dispatch (optional): Bridge Matrix chat rooms to runners for chat-triggered AI.
bash
Setup Matrix bot (interactive wizard)
matrix-dispatch-helper.sh setupMap rooms to runners
matrix-dispatch-helper.sh map '!dev-room:server' code-reviewer
matrix-dispatch-helper.sh map '!seo-room:server' seo-analystStart bot (daemon mode)
matrix-dispatch-helper.sh start --daemonIn Matrix room: "!ai Review src/auth.ts for security issues"
`See: headless-dispatch.md for full documentation including parallel vs sequential decision guide, SDK examples, CI/CD integration, and custom agent configuration. matrix-bot.md for Matrix bot setup including Cloudron Synapse guide.
$3
Agents that learn from experience and contribute improvements:
| Phase | Description |
|-------|-------------|
| Review | Analyze memory for success/failure patterns (
) |
| Refine | Generate and apply improvements to agents |
| Test | Validate in isolated OpenCode sessions |
| PR | Contribute to community with privacy filtering |Safety guardrails:
- Worktree isolation for all changes
- Human approval required for PRs
- Mandatory privacy filter (secretlint + pattern redaction)
- Dry-run default, explicit opt-in for PR creation
- Audit log to memory
$3
Test agent behavior through isolated AI sessions with automated validation:
`bash
Create a test suite
agent-test-helper.sh create my-testsRun tests (auto-detects claude or opencode CLI)
agent-test-helper.sh run my-testsQuick single-prompt test
agent-test-helper.sh run-one "What tools do you have?" --expect "bash"Before/after comparison for agent changes
agent-test-helper.sh baseline my-tests # Save current behavior
... modify agents ...
agent-test-helper.sh compare my-tests # Detect regressions
`Test suites are JSON files with prompts and validation rules (
, expect_not_contains, expect_regex, min_length, max_length). Results are saved for historical tracking.See:
agent-testing.md subagent for full documentation and example test suites.$3
Speak naturally to your AI coding agent and hear it respond. The voice bridge connects your microphone to OpenCode via a fast local pipeline -- ask questions, give instructions, execute tasks, all by voice.
`text
Mic → Silero VAD → Whisper MLX (1.4s) → OpenCode (4-6s) → Edge TTS (0.4s) → Speaker
`Round-trip: ~6-8 seconds on Apple Silicon. The agent can edit files, run commands, create PRs, and confirm what it did -- all via voice.
Quick start:
bash
Start a voice conversation (installs deps automatically)
voice-helper.sh talkChoose engines and voice
voice-helper.sh talk whisper-mlx edge-tts en-GB-SoniaNeural
voice-helper.sh talk whisper-mlx macos-say # Offline modeUtilities
voice-helper.sh devices # List audio input/output devices
voice-helper.sh voices # List available TTS voices
voice-helper.sh benchmark # Test STT/TTS/LLM speeds
voice-helper.sh status # Check component availability
`Features:
| Feature | Details |
|---------|---------|
| Swappable STT | whisper-mlx (fastest on Apple Silicon), faster-whisper (CPU) |
| Swappable TTS | edge-tts (best quality), macos-say (offline), facebookMMS (local) |
| Voice exit | Say "that's all", "goodbye", "all for now" to end naturally |
| STT correction | LLM sanity-checks transcription errors before acting (e.g. "test.txte" → "test.txt") |
| Task execution | Full tool access -- edit files, git operations, run commands |
| Session handback | Conversation transcript output on exit for calling agent context |
| TUI compatible | Graceful degradation when launched from AI tool's Bash (no tty) |
How it works: The bridge uses
to connect to a running OpenCode server for low-latency responses (~4-6s vs ~30s cold start). It automatically starts opencode serve if not already running.Requirements: Apple Silicon Mac (for whisper-mlx), Python 3.10+, internet (for edge-tts). The voice helper installs Python dependencies automatically into the S2S venv.
$3
For advanced use cases (custom LLMs, server/client deployment, multi-language, phone integration), the full huggingface/speech-to-speech pipeline is also available:
`bash
speech-to-speech-helper.sh setup # Install pipeline
speech-to-speech-helper.sh start --local-mac # Run on Apple Silicon
speech-to-speech-helper.sh start --cuda # Run on NVIDIA GPU
speech-to-speech-helper.sh start --server # Server mode (remote clients)
`Supported languages: English, French, Spanish, Chinese, Japanese, Korean (auto-detect or fixed).
Additional voice methods:
| Method | Description |
|--------|-------------|
| VoiceInk + Shortcut | macOS: transcription → OpenCode API → response |
| iPhone Shortcut | iOS: dictate → HTTP → speak response |
| Pipecat STS | Full voice pipeline: Soniox STT → AI → Cartesia TTS |
See: speech-to-speech.md for full component options, CLI parameters, and integration patterns (Twilio phone, video narration, voice-driven DevOps).
$3
Cron-based agent dispatch for automated workflows:
bash
Example: Daily SEO report at 9am
0 9 * ~/.aidevops/agents/scripts/runner-helper.sh run "seo-analyst" "Generate daily SEO report"
`See: TODO.md tasks t109-t118 for implementation status.
Requirements
$3
aidevops itself is lightweight (shell scripts + markdown), but AI model workloads benefit from capable hardware:
| Tier | Machine | CPU | RAM | GPU | Best For |
|------|---------|-----|-----|-----|----------|
| Minimum | Any modern laptop | 4+ cores | 8GB | None | Framework only, cloud AI APIs |
| Recommended | Mac Studio / desktop | Apple M1+ or 8+ cores | 16GB+ | MPS (Apple) or NVIDIA 8GB+ | Local voice, browser automation, dev servers |
| Power User | Workstation | 8+ cores | 32GB+ | NVIDIA 24GB+ VRAM | Full voice pipeline, local LLMs, parallel agents |
| Server | Cloud GPU | Any | 16GB+ | A100 / H100 | Production voice, multi-user, batch processing |
Cloud GPU providers for on-demand GPU access: NVIDIA Cloud, Vast.ai, RunPod, Lambda.
Note: Most aidevops features (infrastructure management, SEO, code quality, Git workflows) require no GPU. GPU is only needed for local AI model inference (voice pipeline, vision models, local LLMs).
$3
bash
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/DebianGenerate SSH key
ssh-keygen -t ed25519 -C "your-email@domain.com"
`$3
AI agents use fast file discovery tools for efficient codebase navigation:
| Tool | Purpose | Speed |
|------|---------|-------|
|
| Fast file finder (replaces find) | ~10x faster |
| ripgrep | Fast content search (replaces grep) | ~10x faster |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 unavailableThe setup script offers to install these tools automatically.
Comprehensive Service Coverage
$3
- 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
$3
- 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
$3
- 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
$3
- 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)
$3
- 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
$3
- LocalWP: WordPress development environment with MCP database access
- MainWP: WordPress site management dashboard
Git CLI Enhancement Features:
- .agents/scripts/github-cli-helper.sh: Advanced GitHub repository, issue, PR, and branch management
- .agents/scripts/gitlab-cli-helper.sh: Complete GitLab project, issue, MR, and branch management
- .agents/scripts/gitea-cli-helper.sh: Full Gitea repository, issue, PR, and branch management
$3
- gopass: GPG-encrypted secret management with AI-native wrapper (
aidevops secret) - subprocess injection + output redaction keeps secrets out of AI context
- 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
- Socket: Dependency security and supply chain protection
- Sentry: Error monitoring and performance tracking
- Cisco Skill Scanner: Security scanner for AI agent skills (prompt injection, exfiltration, malicious code)
- VirusTotal: Advisory threat intelligence via VT API v3 -- file hash scanning (70+ AV engines), domain/URL reputation checks for imported skills
- Secretlint: Detect exposed secrets in code
- OSV Scanner: Google's vulnerability database scanner
- Qlty: Universal code quality platform (70+ linters, auto-fixes)
- Gemini Code Assist: Google's AI-powered code completion and review$3
- 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
$3
- LibPDF: PDF form filling, digital signatures (PAdES B-B/T/LT/LTA), encryption, merge/split, text extraction
- MinerU: Layout-aware PDF-to-markdown/JSON conversion with OCR (109 languages), formula-to-LaTeX, and table extraction (53k+ stars, AGPL-3.0)
- Unstract: LLM-powered structured data extraction from unstructured documents (PDF, images, DOCX)
- GLM-OCR: Local OCR via Ollama - purpose-built for document text extraction (tables, forms, complex layouts) with zero cloud dependency
PDF/OCR Tool Selection:
| Need | Tool | Why |
|------|------|-----|
| Complex PDF to markdown | MinerU | Layout-aware, formulas, tables, 109-language OCR |
| Quick text extraction | GLM-OCR | Local, fast, no API keys, privacy-first |
| Structured JSON output | Unstract | Schema-based extraction, complex documents |
| Screen/window OCR | Peekaboo + GLM-OCR |
peekaboo image --analyze --model ollama/glm-ocr |
| PDF text extraction | LibPDF | Native PDF parsing, no AI needed |
| Simple format conversion | Pandoc | Lightweight, broad format support |Quick start:
`bash
ollama pull glm-ocr
ollama run glm-ocr "Extract all text" --images /path/to/document.png
`See
for batch processing, PDF workflows, and Peekaboo integration.$3
- 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
- Matrix: Self-hosted chat with bot integration for AI runner dispatch (
matrix-dispatch-helper.sh)$3
- 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)
$3
- Voice Bridge: Talk to your AI coding agent via speech -- Silero VAD → Whisper MLX → OpenCode → Edge TTS (~6-8s round-trip)
- Speech-to-Speech: Open-source modular voice pipeline (VAD → STT → LLM → TTS) with local GPU and cloud GPU deployment
- Pipecat: Real-time voice agent framework with Soniox STT, Cartesia TTS, and multi-LLM support
$3
- PageSpeed Insights: Website performance auditing
- Lighthouse: Comprehensive web app analysis
- WebPageTest: Real-world performance testing from 40+ global locations with filmstrip, waterfall, and Core Web Vitals
- Updown.io: Website uptime and SSL monitoring
$3
- 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 for OpenCode (TUI, Desktop, and Extension for Zed/VSCode/AntiGravity).
$3
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.| MCP | Purpose | Tier | API Key Required |
|-----|---------|------|------------------|
| Augment Context Engine | Semantic codebase retrieval | Global | Yes (Augment account) |
| Claude Code MCP | Claude as sub-agent | Global | No |
| osgrep | Local semantic search | Global | No |
| Amazon Order History | Order data extraction | Per-agent | No |
| Chrome DevTools | Browser debugging & automation | Per-agent | No |
| Context7 | Library documentation lookup | Per-agent | No |
| Docker MCP | Container management | Per-agent | No |
| Google Analytics | Analytics data | Per-agent | Yes (Google API) |
| Google Search Console | Search performance data | Per-agent | Yes (Google API) |
| Grep by Vercel | GitHub code search | Per-agent | No |
| LocalWP | WordPress database access | Per-agent | No (local) |
| macOS Automator | macOS automation | Per-agent | No |
| Playwriter | Browser with extensions | Per-agent | No |
| QuickFile | Accounting API | Per-agent | Yes |
| Repomix | Codebase packing for AI context | Per-agent | No |
| Sentry | Error tracking | Per-agent | Yes |
| shadcn | UI component library | Per-agent | No |
| Socket | Dependency security | Per-agent | No |
| Unstract | Document data extraction | Per-agent | Yes |
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: MCPs load eagerly at startup or on-demand when their subagent is invoked. This reduces OpenCode startup time significantly.$3
These use direct API calls via curl, avoiding MCP server startup entirely:
| Integration | Purpose | API Key Required |
|-------------|---------|------------------|
| Ahrefs | SEO analysis & backlinks | Yes |
| DataForSEO | SERP, keywords, backlinks, on-page | Yes |
| Serper | Google Search API (web, images, news) | Yes |
| Semrush | Domain analytics, keywords, backlinks, competitor research | Yes |
| ContentKing | Real-time SEO monitoring, change tracking, issues | Yes |
| WebPageTest | Real-world performance testing from 40+ global locations | Yes |
| Hostinger | Hosting management | Yes |
| NeuronWriter | Content optimization & NLP analysis | Yes |
| Outscraper | Google Maps & business data extraction | Yes |
$3
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, iOS Simulator support (macOS)
- 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-targetingSEO & 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)
- SEO Audit - Comprehensive technical SEO auditing: crawlability, indexation, Core Web Vitals, on-page optimization, E-E-A-T signals (imported skill from marketingskills)
- 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 (curl subagent)
- curl-copy - Authenticated scraping via DevTools "Copy as cURL" (no browser automation needed)
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 & OCR:
- LibPDF - PDF form filling, digital signatures, encryption, merge/split (via helper script)
- Unstract - LLM-powered structured data extraction from PDFs, images, DOCX (MCP)
- GLM-OCR - Local OCR via Ollama for document text extraction (subagent)
$3
`bash
Install all MCP integrations
bash .agents/scripts/setup-mcp-integrations.sh allInstall specific integration
bash .agents/scripts/setup-mcp-integrations.sh stagehand # JavaScript version
bash .agents/scripts/setup-mcp-integrations.sh stagehand-python # Python version
bash .agents/scripts/setup-mcp-integrations.sh stagehand-both # Both versions
bash .agents/scripts/setup-mcp-integrations.sh chrome-devtools
`$3
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
for real-time diagnostics during editing:`json
{
"lsp": {
"markdownlint": {
"command": ["markdownlint-language-server", "--stdio"],
"extensions": [".md"]
},
"toon-lsp": {
"command": ["toon-lsp"],
"extensions": [".toon"]
}
}
}
`Install the servers:
bash
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 + device emulation, benchmarked and integrated for AI-assisted web automation, dev testing, mobile/responsive testing, data extraction, and bot detection evasion. Agents automatically select the optimal tool based on task requirements.
$3
Tested on macOS ARM64, all headless, warm daemon:
| Test | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand |
|------|-----------|----------------|-------------|---------------|----------|------------|-----------|
| Navigate + Screenshot | 1.43s | ~1.9s | 1.39s | 1.90s | 2.78s | 2.95s | 7.72s |
| Form Fill (4 fields) | 0.90s | ~1.4s | 1.34s | 1.37s | N/A | 2.24s | 2.58s |
| Data Extraction (5 items) | 1.33s | ~1.5s | 1.08s | 1.53s | 2.53s | 2.68s | 3.48s |
| Multi-step (click + nav) | 1.49s | ~2.0s | 1.49s | 3.06s | N/A | 4.37s | 4.48s |
| Parallel (3 sessions) | 1.6s | ~2.0s | N/A | 2.0s | 3.0s | N/A | Slow |
$3
| Feature | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand |
|---------|-----------|----------------|-------------|---------------|----------|------------|-----------|
| Headless | Yes | Yes (default) | Yes | Yes (default) | Yes | No (your browser) | Yes |
| Proxy/VPN | Full | No | Via args | No | Full | Your browser | Via args |
| Extensions | Yes (persistent) | No | Yes (profile) | No | No | Yes (yours) | Possible |
| Password managers | Partial (needs unlock) | No | Partial | No | No | Yes (unlocked) | No |
| Device emulation | Full (100+ devices) | No | No | No | No | No | Via Playwright |
| Parallel sessions | 5 ctx/2.1s | --session | Shared | 3 sess/2.0s | arun_many 1.7x | Shared | Per-instance |
| Session persistence | storageState | Profile dir | Profile dir | state save/load | user_data_dir | Your browser | Per-instance |
| Tracing | Full API | Built-in CLI | Via Playwright | Via Playwright | No | Via CDP | Via Playwright |
| Natural language | No | No | No | No | LLM extraction | No | Yes |
| Self-healing | No | No | No | No | No | No | Yes |
| iOS Simulator | No | No | No | Yes (macOS) | No | No | No |
| Maintainer | Microsoft | Microsoft | Community | Vercel | Community | Community | Browserbase |
$3
| Need | Tool | Why |
|------|------|-----|
| Fastest automation | Playwright | 0.9s form fill, parallel contexts |
| AI agent (CLI) | playwright-cli | Microsoft official,
isolation, built-in tracing |
| Stay logged in | dev-browser | Profile persists across restarts |
| Your extensions/passwords | Playwriter | Already unlocked in your browser |
| Bulk extraction | Crawl4AI | Purpose-built, parallel, LLM-ready output |
| Self-hosted crawling | WaterCrawl | Docker deployment, web search, sitemap generation |
| CLI/CI/CD | playwright-cli or agent-browser | No server needed, --session isolation |
| iOS mobile testing | agent-browser | Real Safari in iOS Simulator (macOS only) |
| Unknown pages | Stagehand | Natural language, self-healing |
| Performance debugging | Chrome DevTools MCP | Companion tool, pairs with any browser |
| Mobile/tablet emulation | Playwright | 100+ device presets, viewport, touch, geolocation, locale |
| Authenticated one-off scrape | curl-copy | DevTools "Copy as cURL" → paste to terminal/AI |
| Bot detection evasion | Anti-detect stack | Camoufox (full) or rebrowser-patches (quick) |
| Multi-account | Browser profiles | Persistent fingerprint + proxy per account |$3
Agents use lightweight methods instead of expensive vision API calls:
| Method | Speed | Token Cost | Use For |
|--------|-------|-----------|---------|
| ARIA snapshot | ~0.01s | 50-200 tokens | Forms, navigation, interactive elements |
| Text extraction | ~0.002s | Text length | Reading content |
| Element scan | ~0.002s | ~20/element | Form filling, clicking |
| Screenshot | ~0.05s | ~1K tokens (vision) | Visual debugging only |
.agents/tools/browser/browser-automation.md for the full decision tree and browser-benchmark.md for reproducible benchmark scripts.$3
Test responsive layouts and mobile-specific behavior using Playwright's built-in device emulation. Supports 100+ device presets with viewport, user agent, touch events, device scale factor, geolocation, locale/timezone, permissions, color scheme, offline mode, and network throttling.
Common device presets:
| Device | Viewport | Scale | Touch |
|--------|----------|-------|-------|
|
iPhone 15 | 393x852 | 3 | Yes |
| iPad Pro 11 | 834x1194 | 2 | Yes |
| Pixel 7 | 412x915 | 2.625 | Yes |
| Galaxy S9+ | 320x658 | 4.5 | Yes |
| Desktop Chrome | 1280x720 | 1 | No |Emulation capabilities:
| Feature | Example |
|---------|---------|
| Device presets |
devices['iPhone 13'] - viewport, UA, touch, scale |
| Viewport/HiDPI | viewport: { width: 2560, height: 1440 }, deviceScaleFactor: 2 |
| Geolocation | geolocation: { longitude: -74.006, latitude: 40.7128 } |
| Locale/timezone | locale: 'de-DE', timezoneId: 'Europe/Berlin' |
| Color scheme | colorScheme: 'dark' |
| Offline mode | offline: true |
| Permissions | permissions: ['geolocation', 'notifications'] |
| Network throttling | CDP-based Slow 3G / Fast 3G emulation |Recipes included: Responsive breakpoint testing, multi-device parallel testing, touch gesture testing, geolocation-dependent features, dark mode visual regression, and network condition emulation.
.agents/tools/browser/playwright-emulation.md for complete documentation with code examples.$3
Open-source alternative to AdsPower, GoLogin, and OctoBrowser for multi-account automation and bot detection evasion.
Architecture:
`text
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:
| Type | Cookies | Fingerprint | Use Case |
|------|---------|-------------|----------|
| Persistent | Saved | Fixed per profile | Account management, stay logged in |
| Clean | None | Random each launch | Scraping, one-off tasks |
| Warm | Saved | Fixed | Pre-warmed accounts (browsing history) |
| Disposable | None | Random | Single-use, maximum anony