https://github.com/marcusquinn/aidevops
Vibe-Coding is easy. DevOps is hard. OpenCode & Git token-efficient AI agent automation for your app, business, and personal development. Opinionated tools, services, CLI & API stack for speed, security, and 24/7 results. Open-source first. SOTA everything. Try on your repos for money-making magic.
https://github.com/marcusquinn/aidevops
agents agents-md ai ai-agents ai-assistant ai-assistants ai-assisted-development ai-code-review ai-coding ai-dev-ops ai-devops ai-system-admin claude devops devops-tools git-workflow git-worktrees opencode opencode-plugin
Last synced: 1 day ago
JSON representation
Vibe-Coding is easy. DevOps is hard. OpenCode & Git token-efficient AI agent automation for your app, business, and personal development. Opinionated tools, services, CLI & API stack for speed, security, and 24/7 results. Open-source first. SOTA everything. Try on your repos for money-making magic.
- Host: GitHub
- URL: https://github.com/marcusquinn/aidevops
- Owner: marcusquinn
- License: mit
- Created: 2025-11-09T05:15:11.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-23T23:39:55.000Z (4 days ago)
- Last Synced: 2026-05-24T01:22:26.185Z (4 days ago)
- Topics: agents, agents-md, ai, ai-agents, ai-assistant, ai-assistants, ai-assisted-development, ai-code-review, ai-coding, ai-dev-ops, ai-devops, ai-system-admin, claude, devops, devops-tools, git-workflow, git-worktrees, opencode, opencode-plugin
- Language: Shell
- Homepage: https://www.aidevops.sh
- Size: 88.8 MB
- Stars: 250
- Watchers: 3
- Forks: 47
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# AI DevOps Framework
**[aidevops.sh](https://aidevops.sh)** — An [OpenCode](https://opencode.ai/) plugin and AI operations platform for launching and managing development, business, marketing, and creative projects. 11 primary agents handle automatable work across every domain so your time is preserved for real-world discovery and decisions that AI cannot yet reach.
> **Recommended setup:** [OpenCode](https://opencode.ai/) + OpenAI models. GPT-5.5 is the preferred high-capability model for complex agent work; GPT-5.4 mini is the preferred fast, lower-cost model for triage and routine implementation. Claude models (Anthropic) remain fully supported, and other model providers are evaluated from time to time as their quality, latency, and cost profiles change.
*"Scope a mission to redesign the landing pages — break it into milestones, dispatch workers in parallel, validate each milestone, and track budget across the whole project"*
**One conversation, autonomous project delivery — with enterprise-level security & quality-control.**
Founded by [Marcus Quinn](https://github.com/marcusquinn) on 9th November 2025 to help anyone level-up their AI & Open-Source game.
## **The Philosophy**
**Maximum value for your time and money.** **[aidevops](https://aidevops.sh)** is built on these principles:
- **Autonomous orchestration** - An AI supervisor runs every 2 minutes, dispatching parallel workers, merging PRs, detecting stuck processes, and advancing multi-day missions — no human babysitting required
- **Multi-domain agents** - 11 primary agents covering code, automation, product, SEO, marketing/sales, content/video/social, legal, research, business/accounts, health, and framework operations with 900+ subagents loaded on demand
- **Multi-model safety** - High-stakes operations (force push, production deploy, data migration) are verified by a second cross-provider model before execution — different providers have different failure modes, so correlated hallucinations are rare
- **Resource efficiency** - Cost-aware model routing across OpenAI, Anthropic, Gemini, Cursor, and local models; project-type bundles auto-configure quality gates and model tiers, with budget tracking and burn-rate analysis
- **Self-healing** - When something breaks, diagnose the root cause, create tasks, and fix it. Every error is a live test case for a permanent solution
- **Self-improving** - When patterns of failure or inefficiency emerge, improve the framework itself. Session mining extracts learnings from past sessions automatically
- **Gap awareness** - Every session is an opportunity to identify what's missing — gaps in automation, documentation, coverage, or processes — and create tasks to fill them
- **Git-first workflow** - Protected branches, PR reviews, quality gates before merge. Sane vibe-coding through structure
- **Parallel agents** - Multiple AI sessions running full [Ralph loops](#ralph-loop---iterative-ai-development) on separate branches via [git worktrees](#git-worktrees---parallel-branch-development)
- **Progressive discovery** - `/slash` commands and `@subagent` mentions load knowledge into context only when needed
- **Open-source ready** - Contribute to any project the same way you work on your own. Clone a repo, develop solutions to issues locally, and submit pull requests — the same full-loop workflow works everywhere
The result: an AI operations platform that manages projects across every business domain — absorbing everything automatable so you can focus on what matters.
**Built on proven patterns**: aidevops implements [industry-standard agent design patterns](#agent-design-patterns) - including multi-layer action spaces, context isolation, and iterative execution loops.
## **Why This Framework?**
**Beyond single-task AI.** Most AI coding tools handle one conversation, one repo, one task at a time. aidevops manages your entire operation — dispatching parallel AI agents across multiple repos, routing tasks to domain-specialist agents, and running autonomously for days on multi-milestone projects.
**What makes it different:**
- **Autonomous supervisor** - AI pulse runs every 2 minutes: merges ready PRs, dispatches workers, kills stuck processes, advances missions, triages quality findings — no human in the loop
- **Cross-domain intelligence** - 11 primary agents spanning code, automation, product, business, marketing/sales, legal, content/video/social, research, SEO, health, and framework operations — each with domain expertise and specialist subagents
- **Multi-model safety** - Destructive operations verified by a second AI model from a different provider before execution
- **30+ service integrations** - Hosting, Git platforms, DNS, security, monitoring, deployment, payments, communications
- **Mission orchestration** - Multi-day autonomous projects broken into milestones with validation, budget tracking, and automatic advancement
---
[](https://github.com/marcusquinn/aidevops/actions)
[](https://sonarcloud.io/summary/new_code?id=marcusquinn_aidevops)
[](https://www.codefactor.io/repository/github/marcusquinn/aidevops)
[](https://qlty.sh/gh/marcusquinn/projects/aidevops)
[](https://app.codacy.com/gh/marcusquinn/aidevops/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://coderabbit.ai)
[](https://opensource.org/licenses/MIT)
[](https://github.com/marcusquinn)
[](https://github.com/marcusquinn/aidevops/stargazers)
[](https://github.com/marcusquinn/aidevops/network)
[](https://github.com/marcusquinn/aidevops/watchers)
[](https://github.com/marcusquinn/aidevops/releases)
[](https://www.npmjs.com/package/aidevops)
[](https://github.com/marcusquinn/homebrew-tap)
[](https://github.com/marcusquinn/aidevops/releases)
[](https://github.com/marcusquinn/aidevops/commits/main)
[](https://github.com/marcusquinn/aidevops)
[](https://github.com/marcusquinn/aidevops)
[](https://github.com/marcusquinn/aidevops)
[](https://github.com/marcusquinn/aidevops/issues)
[](https://github.com/marcusquinn/aidevops/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/marcusquinn/aidevops/pulls)
[](https://github.com/marcusquinn/aidevops/graphs/contributors)
[](#comprehensive-service-coverage)
[](https://agents.md/)
[](https://github.com/marcusquinn/aidevops/blob/main/AGENTS.md)
[](#mcp-integrations)
[](#comprehensive-service-coverage)
## Quick Reference
- **Purpose**: AI-assisted DevOps automation framework
- **Install**: `npm install -g aidevops && aidevops update`
- **Recommended runtime/models**: OpenCode + OpenAI GPT-5.5 / GPT-5.4 mini
- **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
- `aidevops auto-update` - Automatic update polling (enable/disable/status)
- `aidevops secret` - Manage secrets (gopass encrypted, AI-safe)
- `aidevops security` - Full security assessment (posture, secrets, supply chain)
- `/onboarding` - Interactive setup wizard (in AI assistant)
- `/design-artifact` - Route artifact-first UI, deck, email, poster, and mobile mockup work
- `/open-design` - Manage the optional Open Design companion studio
- `/auto-browse` - Learn, optimize, and graduate repeatable browser operations and web data-mining workflows
- `/report-render` - Render report-ready Markdown or JSON to HTML with sticky TOC, print CSS, evidence badges, and source cards for PDF export
### Agent Structure
- 11 primary agents (Build+, Automate, Product, SEO, Marketing-Sales, etc.) with specialist @subagents on demand
- 900+ subagent markdown files organized by domain
- 1,200+ helper scripts in `.agents/scripts/`
- 90+ slash commands and workflow guides for common operations
### What You Can Ask aidevops To Do
- Build, fix, review, release, and maintain software with worktrees, PRs, tests, and quality gates.
- Run infrastructure, hosting, DNS, monitoring, security, and deployment workflows.
- Plan products, PRDs, onboarding, monetisation, growth, analytics, and UI direction.
- Operate business, finance, receipts, invoices, marketing, outreach, SEO, content, video, and personal-productivity routines.
- Discover the right capability with `/skills recommend "TASK"`, `/onboarding`, or the OpenCode agent picker.
## **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.**
### Report-ready AI search workflow
Use aidevops to turn AI search readiness work into a client-ready report without making HTML the source of truth:
1. Run `/seo-ai-readiness example.com` for the domain or priority URLs.
2. Request report-ready output with executive summary, method, scorecard, page-type findings, evidence ledger, roadmap, verification, and source IDs.
3. Save the Markdown or JSON report, then render it with `/report-render report.md` or `report-render-helper.sh render report.md --output report.html`.
4. Review the generated HTML for sticky table of contents, source cards, print CSS, and `verified`, `partial`, `inferred`, or `missing` evidence badges.
5. Export or print the HTML to PDF from the browser print dialog.
6. After remediation, rerun `/seo-ai-readiness` and render the updated report for before/after comparison.
## **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
### Security Commands
```bash
aidevops security # Run ALL checks (posture + hygiene + supply chain)
aidevops security posture # Interactive security posture setup (gopass, gh auth, SSH)
aidevops security status # Combined posture + hygiene summary
aidevops security scan # Secret hygiene & supply chain scan only
aidevops security scan-pth # Python .pth file audit (supply chain attack vector)
aidevops security scan-secrets # Plaintext credential locations only
aidevops security scan-deps # Unpinned dependency check
aidevops security check # Per-repo security posture assessment
aidevops security dismiss # Dismiss a security advisory after taking action
```
Running `aidevops security` with no arguments is the single command that covers everything — user security posture, plaintext secret detection, supply chain IoC scanning, and active advisories.
**Security advisories** are delivered via `aidevops update` and shown in the session greeting until dismissed. The scanner never exposes secret values — only file locations and key names. All remediation commands should be run in a separate terminal, not inside AI chat sessions.
**Supply chain hardening:** All Python dependencies are pinned to exact versions (`==`) to prevent malicious package upgrades. The `.pth` file auditor detects known supply chain attack indicators (e.g., the LiteLLM March 2026 PyPI compromise).
## **Quick Start**
### Installation Options
**npm** (recommended - [verified provenance](https://docs.npmjs.com/generating-provenance-statements)):
```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 `~/.aidevops/agents/`
- Install the `aidevops` CLI command
- Configure your AI assistants automatically
- Offer to install Oh My Zsh (optional, opt-in) for enhanced shell experience
- Install recommended token-efficiency tooling by default, including RTK for compact `git`/`gh`/test/lint command summaries before output reaches AI context
- Guide you through recommended tools (Tabby, Zed, Git CLIs)
- Ensure all PATH and alias changes work in both bash, zsh, and fish
- When Claude Code is installed, add a `claude` alias that runs `claude --dangerously-skip-permissions` (skips per-tool permission prompts). Re-running setup updates the alias automatically. To grant permissions per-session instead, press **Shift-Tab** inside Claude Code to cycle through permission modes (default → skip permissions → auto-approve).
**New users: Start [OpenCode](https://opencode.ai/) and type `/onboarding`** to configure your services interactively. OpenCode is the recommended tool for aidevops; pair it with OpenAI GPT-5.5 and GPT-5.4 mini for the best current results across agent tiers. The onboarding wizard will:
- Explain what **[aidevops](https://aidevops.sh)** 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 doctor # Detect duplicate installs and PATH conflicts
aidevops update # Update framework + check registered projects
aidevops auto-update # Manage automatic update polling (every 10 min)
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
```
### Optional Design Artifact Studio
aidevops now treats design as a self-contained stack with optional peripherals:
- **Google `DESIGN.md` standard**: AI-readable design systems with YAML tokens, linting, previews, and brand/style libraries (`.agents/tools/design/design-md.md`).
- **Design agents and skills**: brand identity, palettes, UI inspiration, product UI rules, shadcn/Tailwind/UI skills, Nothing-style design, email rendering, Remotion/video, and browser-based UI verification.
- **Artifact routing commands**: `/design-artifact` decides whether to use aidevops-native implementation or a companion artifact studio; `/open-design` manages optional Open Design workflows.
- **Verification gates**: Playwright screenshots, accessibility/contrast checks, email rendering, deck export/fidelity checks, and media smoke tests before generated artifacts are accepted.
Optional companion: [Open Design](https://github.com/nexu-io/open-design) by nexu-io (Apache-2.0) is supported as a **peripheral** for live sandboxed previews, design-skill pickers, `.od/` artifact workspaces, and HTML/PDF/PPTX/ZIP-style exports. aidevops remains canonical for agents, skill ingestion, Google `DESIGN.md`, local hosting, and verification.
```bash
# Inspect optional companion status
open-design-helper.sh status
# Print safe install plan only
open-design-helper.sh install
# Install alongside aidevops only after opting in
open-design-helper.sh install --execute
# Start through aidevops local HTTPS if Open Design only prints localhost
open-design-helper.sh start --https-local open-design
# → https://open-design.local when localdev is configured
```
Imported Open Design skills are not copied verbatim. They are evaluated through aidevops build-agent methodology, deduplicated against existing agents, flattened into aidevops `*-skill.md` structure, attributed to upstream, and given verification commands. See `.agents/tools/design/open-design-ingestion.md` for the full skill-value matrix.
**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](https://aidevops.sh)** 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/`
- `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`
### Per-repo platform setup
After `aidevops init` registers a new repo, run `/setup-git` in your AI assistant
to apply per-repo platform secrets. Most notably, this sets `SYNC_PAT` — a
GitHub Actions secret that lets `issue-sync.yml` push TODO.md auto-completion
past branch protection.
This is distinct from `/onboarding` (per-account credentials like `gh auth login`):
GitHub Actions secrets are scoped per-repo, so each repo needs its own. You need
`gh auth login` to succeed before any per-repo helper can run, so `/onboarding`
comes first, `/setup-git` second.
Run `/setup-git` again whenever you register a new repo with `aidevops repos add`
or when a `SYNC_PAT` advisory appears in the session greeting toast. If you skip
this step, `issue-sync.yml` will post a remediation comment when it hits branch
protection — `/setup-git` walks through the fix.
### Upgrade Planning Files
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.
### Task Graph Visualization with Beads
[Beads](https://github.com/steveyegge/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 |
| `/list-verify` | List verification queue (pending, passed, failed) |
| `/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](https://aidevops.sh)** 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 `.agents/tools/task-management/beads.md` for complete documentation and installation commands.
**Your AI assistant now has agentic access to 30+ service integrations.**
### OpenAI Models in OpenCode (Recommended)
OpenCode with OpenAI is the current recommended aidevops setup. Use GPT-5.5 for complex reasoning, architecture, security-sensitive review, and hard agent tiers; use GPT-5.4 mini for fast triage, routine implementation, retries, and lower-cost worker throughput.
**Authenticate via the pool:**
```bash
aidevops model-accounts-pool add openai
# Restart OpenCode after adding
```
**Why this is the default:**
- **Best current cross-tier results** — strongest observed balance across interactive Build+, workers, review, and dispatch tiers
- **Good cost/latency split** — GPT-5.5 for depth, GPT-5.4 mini for high-volume routine work
- **Provider isolation** — OpenAI accounts rotate independently from Anthropic, Google, Cursor, and local providers
- **Fallback-friendly** — Claude, Gemini, Cursor, and local models remain available when a task or rate-limit profile calls for them
### OpenCode Anthropic OAuth (Supported)
OpenCode includes Anthropic OAuth authentication natively — no API key needed. OAuth is covered by your Claude Pro/Max subscription at zero additional cost.
**Authenticate via the pool (recommended):**
```bash
aidevops model-accounts-pool add anthropic
# Opens browser OAuth flow — no API key required
# Restart OpenCode after adding
```
**Or via the OpenCode TUI:**
Open OpenCode → `Ctrl+A` → Select **Anthropic** → **Login with Claude.ai** → follow browser OAuth flow.
> **Note:** `opencode auth login` prompts for an API key, not OAuth. Use the commands above for subscription-based OAuth access.
**Benefits:**
- **Still fully supported** for users who prefer Claude models or already have Claude Pro/Max
- **Zero marginal cost** for Claude Pro/Max subscribers (covered by subscription)
- **Automatic token refresh** — no manual re-authentication needed
- **Multiple accounts** — add more accounts to the pool for automatic rotation when one hits rate limits
- **Beta features enabled** — extended thinking modes and latest features
### Cursor Models via Pool Proxy
Access Cursor Pro models (Composer 2, Claude 4.6 Opus/Sonnet, GPT-5.x, Gemini 3.1 Pro) in OpenCode through a local gRPC proxy that translates OpenAI-compatible requests to Cursor's protobuf/HTTP2 protocol.
**Setup:**
```bash
# Add your Cursor account to the pool (reads from local Cursor IDE)
oauth-pool-helper.sh add cursor
# Restart OpenCode — Cursor models appear in Ctrl+T model picker
```
**How it works:**
- Reads Cursor credentials from the local IDE state database
- Starts a gRPC proxy that speaks Cursor's native protocol (not the cursor-agent CLI)
- Discovers available models via gRPC and registers them as an OpenCode provider
- Supports true streaming, tool calling, and automatic token refresh
- Falls back gracefully if no Cursor accounts are in the pool
**Benefits:**
- **Zero additional cost** for Cursor Pro subscribers
- **True streaming** — responses stream as they arrive (not buffered)
- **Tool calling** — Cursor's native MCP tool protocol works through the proxy
- **Model discovery** — automatically detects all models available to your account
- **Pool rotation** — multiple accounts with LRU rotation and 429 failover
### Google AI Pool (Gemini CLI / Vertex AI)
Use your Google AI Pro, AI Ultra, or Workspace subscription for Gemini models. Tokens are injected as ADC bearer tokens that Gemini CLI, Vertex AI SDK, and the Gemini API pick up automatically.
**Setup:**
```bash
# Add your Google account to the pool (browser OAuth flow)
aidevops model-accounts-pool add google
# Restart OpenCode — token is injected as GOOGLE_OAUTH_ACCESS_TOKEN
```
**Supported plans:**
- **Google AI Pro** (~$25/mo) — daily Gemini CLI limits
- **Google AI Ultra** (~$65/mo) — higher daily limits
- **Google Workspace** with Gemini add-on — enterprise daily limits
**Isolation guarantee:** Google auth failures never affect Anthropic/OpenAI/Cursor providers. A Google 429 or auth error only puts the Google pool into cooldown.
### 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:**
```bash
# 1. Install the OpenCode GitHub App
# Visit: https://github.com/apps/opencode-agent
# 2. Add API key secret for your chosen provider
# Repository → Settings → Secrets → OPENAI_API_KEY or 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:**
| 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 tool:** [OpenCode](https://opencode.ai/) is the recommended and tested AI coding tool for aidevops. All features, agents, and workflows are designed and tested for OpenCode first. We recommend OpenAI models for the best current results across all agent tiers: GPT-5.4 mini for fast triage/routine work and GPT-5.5 for complex implementation, review, and reasoning. [Claude](https://claude.ai/) models (Anthropic) remain fully supported, and other providers are tested as their capabilities change.
**Recommended stack:**
- **[OpenCode](https://opencode.ai/)** - 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.
- **[OpenCode Zen](https://opencode.ai/)** - Free tier of OpenCode with included models. Start working with AI straight away at no cost -- no API keys or subscriptions required.
- **OpenAI GPT-5.5 / GPT-5.4 mini** - Recommended model pair for aidevops today. Use GPT-5.5 for complex reasoning and high-impact agent tiers; use GPT-5.4 mini for triage, routine implementation, and cost-efficient parallel workers.
- **[Claude](https://claude.ai/)** (Anthropic) - Fully supported alternative provider. Claude models remain useful for fallback, cross-provider verification, and users with Claude Pro/Max OAuth access.
- **[Tabby](https://tabby.sh/)** - Recommended terminal. Colour-coded Profiles per project/repo, **auto-syncs tab title with git repo/branch.**
- **[Zed](https://zed.dev/)** - Recommended editor. High-performance with AI integration (use with the OpenCode Agent Extension).
### Troubleshooting Auth
If you see **"Anthropic Key Missing"**, **"OpenAI Key Missing"**, or the model stops responding, run these commands from any terminal — no working model session required.
**Step 1 — Check pool health**
```bash
aidevops model-accounts-pool status # counts: available / rate-limited / auth-error
aidevops model-accounts-pool check # live token validity test per account
```
**Step 2 — Fix based on what you see**
| Symptom | Command |
|---------|---------|
| OpenAI account shows `rate-limited` | `aidevops model-accounts-pool rotate openai` |
| Anthropic account shows `rate-limited` | `aidevops model-accounts-pool rotate anthropic` |
| All accounts in cooldown | `aidevops model-accounts-pool reset-cooldowns` |
| OpenAI account shows `auth-error` | `aidevops model-accounts-pool add openai` (re-auth) |
| Anthropic account shows `auth-error` | `aidevops model-accounts-pool add anthropic` (re-auth) |
| Pool is empty (no accounts) | `aidevops model-accounts-pool add openai` |
| Recently re-authenticated, still broken | `aidevops model-accounts-pool assign-pending openai` |
| Google Gemini CLI rate-limited | `aidevops model-accounts-pool rotate google` |
| Google token expired | `aidevops model-accounts-pool add google` (re-auth) |
**Step 3 — If still broken, re-add the account**
```bash
aidevops model-accounts-pool add openai # ChatGPT Plus/Pro
aidevops model-accounts-pool add anthropic # Claude Pro/Max — opens browser OAuth
aidevops model-accounts-pool add cursor # Cursor Pro (reads from local IDE)
aidevops model-accounts-pool add google # Google AI Pro/Ultra/Workspace — browser OAuth
aidevops model-accounts-pool import claude-cli # Import from existing Claude CLI auth
```
Restart OpenCode after any `add`, `rotate`, or `reset-cooldowns` to pick up the new credentials.
**Full command reference**
```bash
aidevops model-accounts-pool status # Pool health at a glance
aidevops model-accounts-pool list # Per-account detail + expiry
aidevops model-accounts-pool check # Live API validity test
aidevops model-accounts-pool rotate [provider] # Switch to next available account NOW
aidevops model-accounts-pool reset-cooldowns # Clear all rate-limit cooldowns
aidevops model-accounts-pool assign-pending
# Assign stranded pending token
aidevops model-accounts-pool remove
# Remove an account
```
> **Note:** `reset-cooldowns` clears cooldowns in the pool file. If OpenCode is already running, the in-memory token endpoint cooldown is only cleared when OpenCode restarts or when you use the `/model-accounts-pool reset-cooldowns` slash command inside an active session.
**If you prefer guided help:** Open OpenCode with a free model (OpenCode Zen includes free models that don't require any API key or subscription) and run the auth troubleshooting agent by typing:
```text
@auth-troubleshooting
```
The agent contains the full recovery flow and symptom table. Free models work fine for this — no paid subscription needed.
### 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](https://tabby.sh/), [cmux](https://cmux.dev/), [iTerm2](https://iterm2.com/), [Kitty](https://sw.kovidgoyal.net/kitty/), [Alacritty](https://alacritty.org/), [WezTerm](https://wezfurlong.org/wezterm/), [Hyper](https://hyper.is/), 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 `.agents/tools/terminal/terminal-title.md` for customization options.
**Companion tool:**
- **[claude-code CLI](https://claude.ai/)** - 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.
**Repo courtesy files:** `aidevops init` scaffolds standard repo files if they don't exist: `README.md`, `LICENCE` (MIT), `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`. Author name and email are auto-detected from git config. Existing files are never overwritten.
## **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](https://wordpress.org/) management, credential security, code auditing
**Autonomous Orchestration:**
- **[Pulse supervisor](#pulse-supervisor-autonomous-ai-operations)** - Autonomous AI supervisor runs every 2 minutes via launchd — merges ready PRs, dispatches workers, kills stuck processes, detects orphaned PRs, syncs TODO state with GitHub, triages quality findings, and advances missions. No human in the loop
- **[Missions](#missions-multi-day-autonomous-projects)** - Multi-day autonomous projects: `/mission` scopes a high-level goal into milestones and features. The pulse dispatches workers, validates milestones, tracks budget, and advances through the project automatically (`mission-dashboard-helper.sh`)
- **[Multi-model verification](#multi-model-verification-cross-provider-safety)** - Destructive operations (force push, production deploy, data migration) are verified by a second AI model from a different provider before execution. Different providers have different failure modes, so correlated hallucinations are rare
- **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 conflicts
- **Budget tracking** - Append-only cost log (`budget-tracker-helper.sh`) with burn-rate analysis and `/budget-analysis` command for model routing decisions
- **Observability** - LLM request capture plugin (`observability.mjs`) for cost tracking, performance analysis, and debugging
- **Rate limits** - Per-provider rate limit configuration (`rate-limits.json`) with throttle-risk warnings
**Project Intelligence:**
- **[Bundles](#project-bundles-auto-configuration)** - Project-type presets that auto-configure model tiers, quality gates, and agent routing per repo. 7 built-in bundles (web-app, library, cli-tool, content-site, infrastructure, agent, schema) with auto-detection from marker files (`bundle-helper.sh`)
- **TTSR rules** - Soft rule engine (`ttsr-rule-loader.sh`) with `.agents/rules/` directory for AI output correction (e.g., no-edit-on-main, no-glob-for-discovery)
- **Cross-review** - `/cross-review` dispatches the same prompt to multiple AI models in parallel, diffs results, and optionally auto-scores via a judge model
- **Local models** - Run AI models locally via llama.cpp for free, private, offline inference (`local-model-helper.sh`) with HuggingFace GGUF model management
- **Tech stack lookup** - `/tech-stack` detects technology stacks of URLs or finds sites using specific technologies (Wappalyzer, httpx, nuclei, BuiltWith)
- **IP reputation** - `ip-reputation-helper.sh` checks IP addresses against multiple reputation databases (Spamhaus, ProxyCheck, AbuseIPDB) before VPS purchase or deployment
**Conversational Memory & Entity System:**
- **Entity memory** - Cross-channel relationship continuity (`entity-helper.sh`): people, agents, and services tracked across Matrix, SimpleX, email, and CLI with versioned profiles
- **Conversational memory** - Per-conversation context management (`conversation-helper.sh`): idle detection, immutable summaries, tone profile extraction
- **Three-layer architecture** - Layer 0 (immutable raw log), Layer 1 (tactical summaries), Layer 2 (strategic entity profiles) in shared SQLite
**Communications:**
- **SimpleX bot** - Channel-agnostic gateway with SimpleX Chat as first adapter for AI agent dispatch (`simplex-bot/`)
- **Matterbridge** - Multi-platform chat bridge connecting 20+ platforms including Matrix, Discord, Telegram, Slack, IRC, WhatsApp, XMPP (`matterbridge-helper.sh`)
- **X API via xurl** - Official X/Twitter API operations through guarded `xurl` workflows for search, timelines, bookmarks, posting, replies, DMs, media, and raw API reads. Supports multiple X developer apps/subscription tiers with `--app` and multiple authenticated accounts with `--username`; model-provider auth such as OpenCode xAI/Grok remains separate from X API OAuth (`content/social-xurl.md`, `xurl-helper.sh`)
- **Localdev** - Local development environment manager with dnsmasq, Traefik, mkcert for production-like `.local` domains with HTTPS (`localdev-helper.sh`)
**MCP Toolkit:**
- **MCPorter** - Discover, call, compose, and generate CLIs/typed clients for MCP servers (`mcporter` npm package)
- **OpenAPI Search** - Search and explore any OpenAPI specification via MCP (zero install, Cloudflare Worker)
- **Cloudflare Code Mode** - Full Cloudflare API (2,500+ endpoints) via 2 tools in ~1,000 tokens
**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
- **Review gate preferences**: choose whether true review-bot rate limits block merges (`aidevops review-gate owner/repo wait`) or allow merge with follow-up quality coverage (`aidevops review-gate owner/repo pass`, the default). Per-tool overrides are supported, for example `aidevops review-gate owner/repo --tool coderabbitai wait`. Failed, skipped, or placeholder bot states are not treated as rate limits and continue to block until a real review/status appears or a human resolves them.
- **Performance Auditing**: PageSpeed Insights, Lighthouse, WebPageTest, Core Web Vitals (`/performance` command)
- **SEO Toolchain**: 40+ SEO subagents including Semrush, Ahrefs, ContentKing, Screaming Frog, Bing Webmaster Tools, Rich Results Test, programmatic SEO, analytics tracking, schema validation, content analysis, keyword mapping, and AI readiness
- **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:
| Skill | Source | Description |
|-------|--------|-------------|
| **cloudflare-platform** | [dmmulroy/cloudflare-skill](https://github.com/dmmulroy/cloudflare-skill) | 60 Cloudflare products: Workers, Pages, D1, R2, KV, Durable Objects, AI, networking, security |
| **heygen** | [heygen-com/skills](https://github.com/heygen-com/skills) | AI avatar video creation API: avatars, voices, video generation, streaming, webhooks |
| **remotion** | [remotion-dev/skills](https://github.com/remotion-dev/skills) | Programmatic video creation with React, animations, rendering |
| **video-prompt-design** | [snubroot/Veo-3-Meta-Framework](https://github.com/snubroot/Veo-3-Meta-Framework) | AI video prompt engineering - 7-component meta prompt framework for Veo 3 |
| **animejs** | [animejs.com](https://animejs.com) | JavaScript animation library patterns and API (via Context7) |
| **caldav-calendar** | [ClawdHub](https://clawdhub.com/Asleep123/caldav-calendar) | CalDAV calendar sync via vdirsyncer + khal (iCloud, Google, Fastmail, Nextcloud) |
| **proxmox-full** | [ClawdHub](https://clawdhub.com/mSarheed/proxmox-full) | 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 `~/.aidevops/agents/configs/skill-sources.json` with upstream tracking for update detection.
**Security Scanning:**
Imported skills are automatically security-scanned using [Cisco Skill Scanner](https://github.com/cisco-ai-defense/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](https://www.virustotal.com/) 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 --force` | Yes | Yes |
| `aidevops skill add --skip-security` | 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.
Scan results are logged to [`.agents/SKILL-SCAN-RESULTS.md`](.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](https://skills.sh) | [ClawdHub](https://clawdhub.com) | **Specification:** [agentskills.io](https://agentskills.io)
**Reference:**
- [Agent Skills Specification](https://agentskills.io/specification) - The open format for SKILL.md files
- [skills.sh Leaderboard](https://skills.sh) - Discover popular community skills
- [ClawdHub](https://clawdhub.com) - Skill registry with vector search (OpenClaw ecosystem)
- [vercel-labs/add-skill](https://github.com/vercel-labs/add-skill) - The upstream CLI tool (aidevops uses its own implementation)
- [anthropics/skills](https://github.com/anthropics/skills) - Official Anthropic example skills
- [agentskills/agentskills](https://github.com/agentskills/agentskills) - Specification source and reference library
## **Agent Sources (Private Repos)**
Sync agents from private Git repositories into the framework. Private repos keep their own agents, helper scripts, and slash commands — `aidevops sources sync` deploys them alongside the core agents.
```bash
aidevops sources add ~/Git/my-private-agents # Register a local repo
aidevops sources add-remote git@github.com:u/r.git # Clone and register a remote repo
aidevops sources list # List configured sources
aidevops sources sync # Sync all sources
aidevops sources remove my-private-agents # Remove a source
```
**How it works:** Private repos contain a `.agents/` directory with agent subdirectories. Agents with `mode: primary` in their frontmatter are symlinked to the agents root for auto-discovery as primary agent tabs. Markdown files with `agent:` frontmatter are deployed as `/slash` commands. All sources sync automatically during `aidevops update`.
**Reference:** `.agents/aidevops/agent-sources.md`
## **Agent Design Patterns**
aidevops implements proven agent design patterns identified by [Lance Martin (LangChain)](https://x.com/RLanceMartin/status/2009683038272401719).
| Pattern | Description | aidevops Implementation |
|---------|-------------|------------------------|
| **Give Agents a Computer** | Filesystem + shell for persistent context | `~/.aidevops/.agent-workspace/`, 1,200+ helper scripts |
| **Multi-Layer Action Space** | Few tools, push actions to computer | Per-agent MCP filtering (~12-20 tools each) |
| **Knowledge Graph Routing** | Indexed, cross-referenced agents instead of isolated skills | `subagent-index.toon` maps 900+ agents by domain, purpose, and dependency — agents discover related context through the graph, not just their own file |
| **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, supervisor dispatch |
| **Compaction Resilience** | Preserve context across compaction | OpenCode plugin injects dynamic state at compaction time |
| **Ralph Loop** | Iterative execution until complete | `/full-loop`, `full-loop-helper.sh` |
| **Evolve Context** | Learn from sessions | `/remember`, `/recall` with SQLite FTS5 + opt-in semantic search |
| **Pattern Tracking** | Learn what works/fails | `/patterns` command, `memory-helper.sh` |
| **Token-Efficient Serialisation** | Minimise context overhead for structured data | [TOON format](https://github.com/marcusquinn/aidevops/blob/main/.agents/toon-format.md) — 20-60% token reduction vs JSON/YAML for agent indexes, registries, and data exchange |
| **Token-Efficient Tool Output** | Summarise noisy terminal output without hiding evidence | RTK is installed by default during setup; start with `rtk-helper.sh` for compact supported summaries, then rerun raw/direct commands when filtered output is insufficient; bypass compression for file reads, JSON assertions, exact diffs, security scans, and other verbatim evidence |
| **Cost-Aware Routing** | Match model to task complexity | `model-routing.md` with provider-aware tier guidance, `/route` command |
| **Model Comparison** | Compare models side-by-side | `/compare-models` (live data), `/compare-models-free` (offline) |
| **Response Scoring** | Evaluate actual model outputs | `/score-responses` with structured criteria |
**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.
### 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 the supervisor manages task distribution and status reporting.
**Architecture:**
```text
Supervisor (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: GPT-5.4 mini / GPT-5.5 / provider fallbacks)
```
**Key components:**
| Component | Script | Purpose |
|-----------|--------|---------|
| Mailbox | `mail-helper.sh` | SQLite-backed inter-agent messaging (send, check, broadcast, archive) |
| 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 routing across OpenAI, Anthropic, Gemini, Cursor, Grok, and local providers |
| Budget tracking | `budget-tracker-helper.sh` | Append-only cost log for model routing decisions |
| Observability | `observability.mjs` plugin | LLM request capture for cost tracking and performance analysis |
**How it works:**
1. Each agent registers on startup (`mail-helper.sh register --role worker`)
2. Supervisor runs periodic pulses (`supervisor-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 audits, large refactors, multi-day feature projects -- 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.
### Pulse Supervisor: Autonomous AI Operations
The pulse is the heartbeat of aidevops — an autonomous AI supervisor that runs every 2 minutes via launchd. There is no human at the terminal. It manages the entire development pipeline across all repos registered with `pulse: true`.
**What it does each cycle:**
| Phase | Action |
|-------|--------|
| **Capacity check** | Circuit breaker, dynamic worker slots calculated from available RAM |
| **Merge ready PRs** | Green CI + no blocking reviews → squash merge (free — no worker slot needed) |
| **Fix failing PRs** | Dispatch a worker to fix CI failures or address review feedback |
| **Detect stuck work** | PRs open 6+ hours with no activity → flag or close and re-file |
| **Dispatch workers** | Route open issues to available worker slots, respecting priority and `blocked-by:` dependencies |
| **Advance missions** | Check active multi-day missions, dispatch features, validate milestones, track budget |
| **Triage quality** | Read daily quality sweep findings (ShellCheck, SonarCloud, Codacy, CodeRabbit), create issues for actionable findings |
| **Sync TODOs** | Create GitHub issues for unsynced TODO entries, commit ref changes |
| **Kill stuck workers** | Workers running 3+ hours with no PR are killed to free slots |
| **Detect orphaned PRs** | Open PRs with no active worker and no activity for 6+ hours are flagged for re-dispatch |
**Operational intelligence:**
- **Struggle-ratio** — computes `messages / max(1, commits)` for each active worker. High ratio (>30) with >30 min elapsed and zero commits flags the worker as "struggling". Ratio >50 after 1 hour flags "thrashing". Informational signal — the supervisor LLM decides the action (kill, wait, re-dispatch with more context)
- **Circuit breaker** — prevents cascading failures by tracking success/failure rates and tripping when error rate exceeds threshold
- **Dynamic concurrency** — worker slot count adapts to available RAM, not a hardcoded constant
- **Stale assignment recovery** — tasks assigned to workers that died (no active process, no PR, 3+ hours stale) are automatically unassigned and made available for re-dispatch
- **Priority ordering** — green PRs (free merge) > failing PRs (closer to done) > high-priority/bug issues > active mission features > product repos > smaller tasks > oldest
**The pulse is an LLM, not a script.** It reads issue bodies, assesses context, and uses judgment. When it encounters something unexpected — an issue body that says "completed", a task with no clear description, a label that doesn't match reality — it handles it the way a competent human manager would.
```bash
# Pulse runs automatically via launchd (every 2 minutes)
# Manual trigger:
opencode run "/pulse"
```
**See:** `.agents/scripts/commands/pulse.md` for the full supervisor specification.
### Missions: Multi-Day Autonomous Projects
Missions are the highest-level orchestration primitive — autonomous multi-day projects that break a high-level goal into milestones, features, and validation criteria. The pulse supervisor advances them automatically.
```bash
# Scope a mission interactively
/mission "Redesign the landing pages for mobile-first with A/B testing"
```
**How missions work:**
1. `/mission` scopes the goal into milestones with features and acceptance criteria
2. Each feature becomes a TODO entry tagged `mission:mNNN` with a GitHub issue
3. The pulse dispatches features as regular workers (respecting `MAX_WORKERS`)
4. When all features in a milestone complete, the pulse dispatches a **validation worker** to verify integration
5. Passed milestones advance automatically — the next milestone's features are dispatched
6. Budget tracking pauses the mission if any category exceeds the alert threshold (default 80%)
**Two execution modes:**
| Mode | Workflow | Best for |
|------|----------|----------|
| **Full** | Worktree + PR per feature, standard review flow | Production code, collaborative projects |
| **POC** | Direct commits, skip ceremony | Prototypes, experiments, proof-of-concept |
**Mission state** is tracked in a JSON file committed to the repo. Each pulse cycle reads the state, acts on it, and commits updates — so any session (or the next pulse) can pick up where the last one left off.
**See:** `.agents/workflows/mission-orchestrator.md` for the full orchestrator specification, `.agents/scripts/commands/dashboard.md` for the mission progress dashboard.
### Multi-Model Verification: Cross-Provider Safety
High-stakes operations are verified by a second AI model from a different provider before execution. This catches single-model hallucinations before destructive operations cause irreversible damage.
**When verification triggers:**
| Risk Level | Examples | Action |
|------------|----------|--------|
| **Critical** | `git push --force` to main, `DROP DATABASE`, production deploy | Blocked unless second model agrees |
| **High** | Force push to task ref, data migration, secret exposure | Warned, verification recommended |
| **Medium** | Bulk file deletion, config changes | Logged |
| **Low** | Normal edits, test runs | No verification |
**How it works:**
1. `pre-edit-check.sh` screens operations against the high-stakes taxonomy
2. For critical/high operations, `verify-operation-helper.sh` sends the operation context to a second model (different provider than the primary)
3. The verifier independently assesses whether the operation is safe
4. On disagreement, the operation is blocked (critical) or warned (high)
5. All verification decisions are logged for audit
**Why cross-provider?** Same-provider models share training data and failure modes. A GPT hallucination is unlikely to be reproduced by Claude or Gemini, and vice versa. The verifier uses the cheapest suitable model tier, so cost is minimal per check.
**Configuration:** Per-repo via `.agents/reference/high-stakes-operations.md`. Opt-out with `VERIFY_ENABLED=false` (not recommended).
**See:** `.agents/tools/verification/parallel-verify.md` for the verification agent specification.
### Project Bundles: Auto-Configuration
Bundles are project-type presets that auto-configure model tiers, quality gates, and agent routing per repo. Instead of manually configuring each project, bundles detect what kind of project you're working on and apply sensible defaults.
**Built-in bundles:**
| Bundle | Auto-detected by | Model default | Quality gates | Agent routing |
|--------|-----------------|---------------|---------------|---------------|
| `web-app` | `package.json` + framework markers | standard | Full (lint, test, build, a11y) | Build+ default |
| `library` | `package.json` with `main`/`exports` | standard | Full + API docs check | Build+ default |
| `cli-tool` | `bin` field in package.json | standard | ShellCheck, test | Build+ default |
| `content-site` | CMS markers, `wp-config.php` | fast | Lighthouse, SEO | Marketing for content tasks |
| `infrastructure` | `Dockerfile`, `terraform/`, `ansible/` | standard | ShellCheck, security scan | Build+ default |
| `agent` | `AGENTS.md`, `.agents/` | thinking | Agent review, prompt quality | Build+ default |
**Resolution priority:** Explicit `bundle` field in `repos.json` > `.aidevops.json` project config > auto-detection from marker files.
**CLI:**
```bash
bundle-helper.sh detect # Auto-detect bundle type
bundle-helper.sh resolve # Show resolved config (with overrides)
bundle-helper.sh show # Show bundle defaults
bundle-helper.sh list # List all available bundles
```
**See:** `.agents/bundles/` for bundle definitions, `.agents/scripts/bundle-helper.sh` for the CLI.
### Parallel Agents & Headless Dispatch
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:4096
# Parallel 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/" &
wait
# List 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](.agents/tools/ai-assistants/runners/code-reviewer.md), [seo-analyst](.agents/tools/ai-assistants/runners/seo-analyst.md) - copy and customize for your own runners.
**Matrix bot dispatch** (optional): Bridge Matrix chat rooms to runners for chat-triggered AI. Each room maintains persistent conversation context via SQLite -- on idle timeout, the session is compacted (summarised) and stored, so the next message resumes with full context.
```bash
# Setup Matrix bot (interactive wizard)
matrix-dispatch-helper.sh setup
# Map rooms to runners (each room = separate session)
matrix-dispatch-helper.sh map '!dev-room:server' code-reviewer
matrix-dispatch-helper.sh map '!seo-room:server' seo-analyst
# Start bot (daemon mode)
matrix-dispatch-helper.sh start --daemon
# In Matrix room: "!ai Review src/auth.ts for security issues"
# Manage sessions
matrix-dispatch-helper.sh sessions list
matrix-dispatch-helper.sh sessions stats
```
**See:** [headless-dispatch.md](.agents/tools/ai-assistants/headless-dispatch.md) for full documentation including parallel vs sequential decision guide, SDK examples, CI/CD integration, and custom agent configuration. [matrix-bot.md](.agents/services/communications/matrix-bot.md) for Matrix bot setup including Cloudron Synapse guide and session persistence.
### Self-Improving Agent System
Agents that learn from experience and contribute improvements:
| Phase | Description |
|-------|-------------|
| **Review** | Analyze memory for success/failure patterns (`memory-helper.sh`) |
| **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
### Agent Testing Framework
Test agent behavior through isolated AI sessions with automated validation:
```bash
# Create a test suite
agent-test-helper.sh create my-tests
# Run tests (auto-detects claude or opencode CLI)
agent-test-helper.sh run my-tests
# Quick 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_contains`, `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.
### Voice Bridge - Talk to Your AI Agent
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 talk
# Choose engines and voice
voice-helper.sh talk whisper-mlx edge-tts en-GB-SoniaNeural
voice-helper.sh talk whisper-mlx macos-say # Offline mode
# Utilities
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 `opencode run --attach` 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.
### Speech-to-Speech Pipeline (Advanced)
For advanced use cases (custom LLMs, server/client deployment, multi-language, phone integration), the full [huggingface/speech-to-speech](https://github.com/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](.agents/tools/voice/speech-to-speech.md) for full component options, CLI parameters, and integration patterns (Twilio phone, video narration, voice-driven DevOps).
### Scheduled Agent Tasks
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](TODO.md) tasks t109-t118 for implementation status.
## **Requirements**
### **Recommended Hardware**
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](https://www.nvidia.com/en-us/gpu-cloud/), [Vast.ai](https://vast.ai/), [RunPod](https://www.runpod.io/), [Lambda](https://lambdalabs.com/). See `.agents/tools/infrastructure/cloud-gpu.md` for the full deployment guide (SSH setup, Docker, model caching, cost optimization).
**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).
### **Software Dependencies**
```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/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:
| Tool | Purpose | Speed |
|------|---------|-------|
| `fd` | 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 unavailable
The setup script offers to install these tools automatically.
## **Comprehensive Service Coverage**
### **Infrastructure & Hosting**
- **[Hostinger](https://www.hostinger.com/)**: Shared hosting, domains, email
- **[Hetzner Cloud](https://www.hetzner.com/cloud)**: VPS servers, networking, load balancers
- **[Closte](https://closte.com/)**: Managed hosting, application deployment
- **[Coolify](https://coolify.io/)** *Enhanced with CLI*: Self-hosted PaaS with CLI integration
- **[Cloudron](https://www.cloudron.io/)** *Enhanced with packaging guide*: Server and app management platform with custom app packaging support
- **[Vercel](https://vercel.com/)** *Enhanced with CLI*: Modern web deployment platform with CLI integration
- **[AWS](https://aws.amazon.com/)**: Cloud infrastructure support via standard protocols
- **[DigitalOcean](https://www.digitalocean.com/)**: Cloud infrastructure support via standard protocols
### **Domain & DNS**
- **[Cloudflare](https://www.cloudflare.com/)**: DNS, CDN, security services
- **[Spaceship](https://www.spaceship.com/)**: Domain registration and management
- **[101domains](https://www.101domain.com/)**: Domain purchasing and DNS
- **[AWS Route 53](https://aws.amazon.com/route53/)**: AWS DNS management
- **[Namecheap](https://www.namecheap.com/)**: Domain and DNS services
### **Development & Git Platforms with CLI Integration**
- **[GitHub](https://github.com/)** *Enhanced with CLI*: Repository management, actions, API, GitHub CLI (gh) integration
- **[GitLab](https://gitlab.com/)** *Enhanced with CLI*: Self-hosted and cloud Git platform with GitLab CLI (glab) integration
- **[Gitea](https://gitea.io/)** *Enhanced with CLI*: Lightweight Git service with Gitea CLI (tea) integration
- **[Agno](https://agno.com/)**: Local AI agent operating system for DevOps automation
- **[Pandoc](https://pandoc.org/)**: Document conversion to markdown for AI processing
### **AI Orchestration Frameworks**
- **[Langflow](https://langflow.org/)**: Visual drag-and-drop builder for AI workflows (MIT, localhost:7860)
- **[CrewAI](https://crewai.com/)**: Multi-agent teams with role-based orchestration (MIT, localhost:8501)
- **[AutoGen](https://microsoft.github.io/autogen/)**: Microsoft's agentic AI framework with MCP support (MIT, localhost:8081)
### **Design, UI & Artifact Creation**
- **Google `DESIGN.md` standard**: Canonical AI-readable design systems with YAML tokens, Markdown rationale, linting, Tailwind/DTCG export, and preview generation. aidevops keeps `DESIGN.md` as the source of truth for UI agents.
- **Design library**: 54 brand examples and 12 original style archetypes for agent-ready visual direction, plus palette, brand identity, and UI inspiration workflows.
- **Artifact commands**: `/design-artifact` routes prototype, deck, email, poster, social carousel, and mobile mockup requests; `/open-design` manages optional Open Design companion workflows.
- **[Open Design](https://github.com/nexu-io/open-design)** *Optional peripheral*: Local-first design artifact studio by nexu-io (Apache-2.0) for sandboxed previews, design-skill pickers, `.od/` workspaces, and exports. It installs alongside aidevops only when requested; selected skills are ingested via aidevops build-agent optimisation, not imported verbatim.
- **Local HTTPS previews**: `localdev-helper.sh` can wrap Open Design or other dev servers with mkcert-backed `.local` routes when tools only expose localhost.
- **Verification**: `workflows/ui-verification.md`, `email-design-test-helper.sh`, design preview screenshots, and deck/media smoke tests provide evidence before generated artifacts ship.
### **Video Creation**
- **[Remotion](https://remotion.dev/)**: Programmatic video creation with React - animations, compositions, media handling, captions
- **[Video Prompt Design](https://github.com/snubroot/Veo-3-Meta-Framework)**: AI video prompt engineering using the 7-component meta prompt framework for Veo 3 and similar models
- **[MuAPI](https://muapi.ai/)**: Multimodal AI API for image/video/audio/VFX generation, workflows, agents, music (Suno), and lip-sync - unified creative orchestration platform
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**: YouTube video/audio/playlist/channel downloads, transcript extraction, and local file audio conversion via ffmpeg
### **WordPress Development**
- **[LocalWP](https://localwp.com)**: WordPress development environment with MCP database access
- **[MainWP](https://mainwp.com/)**: 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
### **Security & Code Quality**
- **[gopass](https://github.com/gopasspw/gopass)**: GPG-encrypted secret management with AI-native wrapper (`aidevops secret`) - subprocess injection + output redaction keeps secrets out of AI context
- **[Vaultwarden](https://github.com/dani-garcia/vaultwarden)**: Password and secrets management
- **[SonarCloud](https://sonarcloud.io/)**: Security and quality analysis (A-grade ratings)
- **[CodeFactor](https://www.codefactor.io/)**: Code quality metrics (A+ score)
- **[Codacy](https://www.codacy.com/)**: Multi-tool analysis (0 findings)
- **[CodeRabbit](https://coderabbit.ai/)**: AI-powered code reviews
- **[Snyk](https://snyk.io/)**: Security vulnerability scanning
- **[Socket](https://socket.dev/)**: Dependency security and supply chain protection
- **[Sentry](https://sentry.io/)**: Error monitoring and performance tracking
- **[Cisco Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner)**: Security scanner for AI agent skills (prompt injection, exfiltration, malicious code)
- **[VirusTotal](https://www.virustotal.com/)**: Advisory threat intelligence via VT API v3 -- file hash scanning (70+ AV engines), domain/URL reputation checks for imported skills
- **[Secretlint](https://github.com/secretlint/secretlint)**: Detect exposed secrets in code
- **[OSV Scanner](https://google.github.io/osv-scanner/)**: Google's vulnerability database scanner
- **[Qlty](https://qlty.sh/)**: Universal code quality platform (70+ linters, auto-fixes)
- **[Gemini Code Assist](https://cloud.google.com/gemini/docs/codeassist/overview)**: Google's AI-powered code completion and review
### **AI Prompt Optimization**
- **[Augment Context Engine](https://docs.augmentcode.com/context-services/mcp/overview)**: Semantic codebase retrieval with deep code understanding
- **[Repomix](https://repomix.com/)**: Pack codebases into AI-friendly context (80% token reduction with compress mode)
- **[DSPy](https://dspy.ai/)**: Framework for programming with language models
- **[DSPyGround](https://dspyground.com/)**: Interactive playground for prompt optimization
- **[TOON Format](https://github.com/marcusquinn/aidevops/blob/main/.agents/toon-format.md)**: Token-Oriented Object Notation - 20-60% token reduction for LLM prompts
### **Document Processing & OCR**
- **Document Creation Agent** (`document-creation-helper.sh`): Unified document format conversion, template-based creation, and OCR for scanned PDFs/images. Routes to the best available tool (pandoc, odfpy, LibreOffice, Tesseract, EasyOCR, GLM-OCR) based on format pair and availability. Supports 13+ formats (ODT, DOCX, PDF, MD, HTML, EPUB, PPTX, ODP, XLSX, ODS, RTF, CSV, TSV).
- **[LibPDF](https://libpdf.dev/)**: PDF form filling, digital signatures (PAdES B-B/T/LT/LTA), encryption, merge/split, text extraction
- **[MinerU](https://github.com/opendatalab/MinerU)**: Layout-aware PDF-to-markdown/JSON conversion with OCR (109 languages), formula-to-LaTeX, and table extraction (53k+ stars, AGPL-3.0)
- **[Unstract](https://github.com/Zipstack/unstract)**: LLM-powered structured data extraction from unstructured documents (PDF, images, DOCX)
- **[GLM-OCR](https://ollama.com/library/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 |
|------|------|-----|
| **Format conversion** | Document Creation Agent | Auto-selects best tool, 13+ formats |
| **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 |
| **Scanned PDF OCR** | Document Creation Agent | Auto-detects, routes to Tesseract/EasyOCR/GLM-OCR |
**Quick start:**
```bash
# Document creation agent
document-creation-helper.sh status # Check available tools
document-creation-helper.sh install --standard # Install core tools
document-creation-helper.sh convert report.pdf --to odt # Convert formats
document-creation-helper.sh convert scan.pdf --to md --ocr # OCR scanned PDF
document-creation-helper.sh template draft --type letter # Generate template
# GLM-OCR direct
ollama pull glm-ocr
ollama run glm-ocr "Extract all text" --images /path/to/document.png
```
See `.agents/tools/ocr/glm-ocr.md` for batch processing, PDF workflows, and Peekaboo integration.
### **Communications**
- **[Twilio](https://www.twilio.com/)**: SMS, voice calls, WhatsApp, phone verification (Verify API), call recording & transcription
- **[Telfon](https://mytelfon.com/)**: Twilio-powered cloud phone system with iOS/Android/Chrome apps for end-user calling interface
- **[Matrix](https://matrix.org/)**: Self-hosted chat with bot integration for AI runner dispatch (`matrix-dispatch-helper.sh`)
- **[SimpleX Chat](https://simplex.chat/)**: Privacy-first messaging with AI bot gateway for agent dispatch (`simplex-bot/`)
- **[Matterbridge](https://github.com/42wim/matterbridge)**: Multi-platform chat bridge connecting 20+ platforms (Matrix, Discord, Telegram, Slack, IRC, WhatsApp, XMPP) with SimpleX adapter (`matterbridge-helper.sh`)
### **Animation & Video**
- **[Anime.js](https://animejs.com/)**: Lightweight JavaScript animation library for CSS, SVG, DOM attributes, and JS objects
- **[Remotion](https://remotion.dev/)**: Programmatic video creation with React - create videos using code with 29 specialized rule files
- **[Video Prompt Design](https://github.com/snubroot/Veo-3-Meta-Framework)**: Structured prompt engineering for AI video generation (Veo 3, 7-component framework, character consistency, audio design)
### **Voice AI**
- **Voice Bridge**: Talk to your AI coding agent via speech -- Silero VAD → Whisper MLX → OpenCode → Edge TTS (~6-8s round-trip)
- **[Speech-to-Speech](https://github.com/huggingface/speech-to-speech)**: Open-source modular voice pipeline (VAD → STT → LLM → TTS) with local GPU and cloud GPU deployment
- **[Pipecat](https://github.com/pipecat-ai/pipecat)**: Real-time voice agent framework with Soniox STT, Cartesia TTS, and multi-LLM support
### **Performance & Monitoring**
- **[PageSpeed Insights](https://pagespeed.web.dev/)**: Website performance auditing
- **[Lighthouse](https://developer.chrome.com/docs/lighthouse/)**: Comprehensive web app analysis
- **[WebPageTest](https://www.webpagetest.org/)**: Real-world performance testing from 40+ global locations with filmstrip, waterfall, and Core Web Vitals
- **[Updown.io](https://updown.io/)**: Website uptime and SSL monitoring
### **AI & Documentation**
- **[Context7](https://context7.io/)**: Real-time documentation access for libraries and frameworks
- **Context7 CLI mode**: `npx ctx7 setup --opencode --cli` for docs lookup without MCP transport (useful fallback in shell-first workflows)
- **[Local Models](https://github.com/ggml-org/llama.cpp)**: Run AI models locally via llama.cpp for free, private, offline inference with HuggingFace GGUF model management (`local-model-helper.sh`)
### **Local Development**
- **[Localdev](https://mkcert.dev/)**: Local development environment manager with dnsmasq, Traefik, and mkcert for production-like `.local` domains with HTTPS on port 443 (`localdev-helper.sh`)
## **MCP Integrations**
**Model Context Protocol servers for real-time AI assistant integration.** The framework configures these MCPs for **[OpenCode](https://opencode.ai/)** (TUI, Desktop, and Extension for Zed/VSCode).
### **All Supported MCPs (20 available)**
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](https://docs.augmentcode.com/context-services/mcp/overview) | Semantic codebase retrieval | Global | Yes (Augment account) |
| [Claude Code MCP](https://github.com/steipete/claude-code-mcp) | Claude as sub-agent | Global | No |
| [Amazon Order History](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp) | Order data extraction | Per-agent | No |
| [Chrome DevTools](https://chromedevtools.github.io/devtools-protocol/) | Browser debugging & automation | Per-agent | No |
| [Context7](https://context7.com/) | Library documentation lookup | Per-agent | No |
| [Docker MCP](https://docs.docker.com/ai/mcp-catalog/) | Container management | Per-agent | No |
| [Google Analytics](https://developers.google.com/analytics) | Analytics data | Per-agent | Yes (Google API) |
| [Google Search Console](https://developers.google.com/webmaster-tools) | Search performance data | Per-agent | Yes (Google API) |
| [Grep by Vercel](https://grep.app/) | GitHub code search | Per-agent | No |
| [LocalWP](https://localwp.com/) | WordPress database access | Per-agent | No (local) |
| [macOS Automator](https://github.com/steipete/macos-automator-mcp) | macOS automation | Per-agent | No |
| [Playwriter](https://github.com/nicholasgriffintn/playwriter) | Browser with extensions | Per-agent | No |
| [QuickFile](https://github.com/marcusquinn/quickfile-mcp) | Accounting API | Per-agent | Yes |
| [Repomix](https://github.com/yamadashy/repomix) | Codebase packing for AI context | Per-agent | No |
| [Sentry](https://sentry.io/) | Error tracking | Per-agent | Yes |
| [shadcn](https://ui.shadcn.com/) | UI component library | Per-agent | No |
| [Socket](https://socket.dev/) | Dependency security | Per-agent | No |
| [Unstract](https://github.com/Zipstack/unstract) | Document data extraction | Per-agent | Yes |
| [OpenAPI Search](https://openapi-mcp.openapisearch.com/mcp) | Search and explore any OpenAPI spec | Per-agent | No |
| [Cloudflare Code Mode](https://mcp.cloudflare.com/mcp) | Full Cloudflare API (2,500+ endpoints via 2 tools) | Per-agent | Yes (Cloudflare) |
**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.
### **SEO Integrations (curl subagents - no MCP overhead)**
These use direct API calls via curl, avoiding MCP server startup entirely:
| Integration | Purpose | API Key Required |
|-------------|---------|------------------|
| [Ahrefs](https://ahrefs.com/api) | SEO analysis & backlinks | Yes |
| [DataForSEO](https://dataforseo.com/) | SERP, keywords, backlinks, on-page | Yes |
| [Serper](https://serper.dev/) | Google Search API (web, images, news) | Yes |
| [Semrush](https://www.semrush.com/api-documentation/) | Domain analytics, keywords, backlinks, competitor research | Yes |
| [ContentKing](https://www.contentkingapp.com/) | Real-time SEO monitoring, change tracking, issues | Yes |
| [WebPageTest](https://www.webpagetest.org/) | Real-world performance testing from 40+ global locations | Yes |
| [Hostinger](https://developers.hostinger.com/) | Hosting management | Yes |
| [NeuronWriter](https://neuronwriter.com/) | Content optimization & NLP analysis | Yes |
| [Outscraper](https://outscraper.com/) | Google Maps & business data extraction | Yes |
### **By Category**
**Context & Codebase:**
- [Augment Context Engine](https://docs.augmentcode.com/context-services/mcp/overview) - Semantic codebase retrieval with deep code understanding
- [llm-tldr](https://github.com/parcadei/llm-tldr) - Semantic code analysis with 95% token savings ([details below](#llm-tldr---semantic-code-analysis))
- [Context7](https://context7.com/) - Real-time documentation access for thousands of libraries
- [Repomix](https://github.com/yamadashy/repomix) - Pack codebases into AI-friendly context
- [OpenAPI Search](https://openapi-mcp.openapisearch.com/mcp) - Search and explore any OpenAPI specification (zero install, Cloudflare Worker)
- [MCPorter](https://github.com/steipete/mcporter) - Discover, call, compose, and generate CLIs/typed clients for MCP servers
**Browser Automation** (8 tools + anti-detect stack, [benchmarked](#browser-automation)):
- **Auto-browse workflow** - `/auto-browse` orchestrates the tools below to learn messy browser tasks, choose the cheapest reliable path, preserve private profile/session state under `~/.aidevops/`, and graduate reusable private agents or sanitized `todo/` plans
- [Playwright](https://playwright.dev/) - Fastest engine (0.9s form fill), parallel contexts, extensions, proxy (auto-installed)
- [playwright-cli](https://github.com/microsoft/playwright-cli) - Microsoft official CLI for AI agents, `--session` isolation, built-in tracing
- [dev-browser](https://github.com/nicholasgriffintn/dev-browser) - Persistent profile, stays logged in, ARIA snapshots, pairs with DevTools
- [agent-browser](https://github.com/vercel-labs/agent-browser) - CLI/CI/CD, `--session` parallel, ref-based element targeting, **iOS Simulator support** (macOS)
- [Crawl4AI](https://github.com/unclecode/crawl4ai) - Bulk extraction, `arun_many` parallel (1.7x), LLM-ready markdown
- [WaterCrawl](https://github.com/watercrawl/watercrawl) - Self-hosted crawling with web search, sitemap generation, JS rendering, proxy support
- [Playwriter](https://github.com/nicholasgriffintn/playwriter) - Your browser's extensions/passwords/proxy, already unlocked
- [Stagehand](https://github.com/browserbase/stagehand) - Natural language automation, self-healing selectors
- [Chrome DevTools MCP](https://github.com/nicholasgriffintn/chrome-devtools-mcp) - Companion: Lighthouse, network throttling, CSS coverage (pairs with any tool)
- [Cloudflare Browser Rendering](https://developers.cloudflare.com/browser-rendering/) - Server-side web scraping
- [Peekaboo](https://github.com/steipete/Peekaboo) - macOS screen capture and GUI automation (pixel-accurate captures, AI vision analysis)
- [Sweet Cookie](https://github.com/steipete/sweet-cookie) - Browser cookie extraction for API calls without launching a browser
- **Anti-Detect Stack** ([details](#anti-detect-browser)):
- [Camoufox](https://github.com/daijro/camoufox) (4.9k stars) - Firefox anti-detect, C++ fingerprint injection, WebRTC/Canvas/WebGL spoofing
- [rebrowser-patches](https://github.com/nicedayfor/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](https://developers.google.com/webmaster-tools) - Search performance insights (MCP)
- [Grep by Vercel](https://grep.app/) - Search code snippets across GitHub repositories (MCP)
- [Ahrefs](https://ahrefs.com/api) - SEO analysis, backlink research, keyword data (curl subagent)
- [DataForSEO](https://dataforseo.com/) - Comprehensive SEO data APIs (curl subagent)
- [Serper](https://serper.dev/) - 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](https://github.com/coreyhaines31/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](https://neuronwriter.com/) - Content optimization with NLP analysis, competitor research, and content scoring (curl subagent)
**Data Extraction:**
- [Outscraper](https://outscraper.com/) - Google Maps, business data, reviews extraction (curl subagent)
- [curl-copy](.agents/tools/browser/curl-copy.md) - Authenticated scraping via DevTools "Copy as cURL" (no browser automation needed)
**Performance & Security:**
- [PageSpeed Insights](https://developers.google.com/speed/docs/insights/v5/get-started) - Website performance auditing
- [Snyk](https://snyk.io/) - Security vulnerability scanning
- [Cloudflare Code Mode](https://mcp.cloudflare.com/mcp) - Full Cloudflare API (2,500+ endpoints) via 2 tools in ~1,000 tokens (DNS, WAF, DDoS, R2, Workers, Zero Trust)
- **IP Reputation** - Multi-provider IP reputation checking (Spamhaus, ProxyCheck, AbuseIPDB) for VPS/proxy vetting (`ip-reputation-helper.sh`)
**WordPress & Development:**
- [LocalWP](https://localwp.com/) - Direct WordPress database access
- [WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter) - Official WordPress MCP for content management (STDIO, HTTP, and SSH transports)
- [Next.js DevTools](https://nextjs.org/docs) - React/Next.js development assistance
**CRM & Marketing:**
- [FluentCRM](https://fluentcrm.com/) - WordPress CRM: contacts, tags, lists, campaigns, automations, smart links, webhooks
**Accounts & Finance:**
- [QuickFile](https://github.com/marcusquinn/quickfile-mcp) - Accounting API integration (MCP)
- [Amazon Order History](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp) - Order data extraction (MCP)
**Document Processing & OCR:**
- [LibPDF](https://libpdf.dev/) - PDF form filling, digital signatures, encryption, merge/split (via helper script)
- [Unstract](https://github.com/Zipstack/unstract) - LLM-powered structured data extraction from PDFs, images, DOCX (MCP)
- [GLM-OCR](https://ollama.com/library/glm-ocr) - Local OCR via Ollama for document text extraction (subagent)
### **Quick Setup**
```bash
# Install all MCP integrations
bash .agents/scripts/setup-mcp-integrations.sh all
# Install 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
```
### OpenCode LSP Configuration
OpenCode includes [built-in LSP servers](https://opencode.ai/docs/lsp/) 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:
```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.
For repeatable browser operations and web data mining, use `/auto-browse`. It runs an intake and learning loop that starts with cheap fetch/API/crawler options, escalates to deterministic or high-agency browser tools only when needed, and then graduates the workflow into a private custom agent, helper, schema, or sanitized `todo/` plan. Account-specific workflows, cookies, profile state, downloads, and traces stay in private aidevops user data; only generalized plans should be committed to the repo.
### Performance Benchmarks
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 |
### Feature Matrix
| 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 |
### Tool Selection
| Need | Tool | Why |
|------|------|-----|
| **Repeatable browser workflow** | `/auto-browse` | Learns, optimizes, preserves private profile state, and graduates reusable workflows |
| **Fastest automation** | Playwright | 0.9s form fill, parallel contexts |
| **AI agent (CLI)** | playwright-cli | Microsoft official, `--session` 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 |
### AI Page Und