marcusquinn/aidevops

AI DevOps Framework

aidevops.sh is an OpenCode plugin and AI DevOps framework for people who want AI to do useful work across code, infrastructure, business, marketing, content, and creative projects without turning every job into another long, fragile chat.

Most AI tools still leave you doing the hard coordination yourself: finding the right context, choosing a model, protecting secrets, managing branches, watching CI, spotting stuck work, and remembering what went wrong last time. aidevops puts structure around that work so agents can share context, work safely in parallel, spend model budget where it matters, and leave the system better than they found it.

Recommended setup: OpenCode + 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 security, teamwork, token efficiency, and quality control built in.

Founded by Marcus Quinn on 9th November 2025 to help anyone level-up their AI & Open-Source game.

The Aim

Maximum value for your time and money. aidevops is built for the gap between “the model can probably do this” and “the work is actually done, verified, safe, and worth the cost.”

• Load the right context when it is needed, instead of stuffing every agent, skill, and tool into the prompt.
• Spend tokens and model budget deliberately. Cheap and fast models should handle routine work; stronger models should handle judgement, architecture, review, and risk.
• Keep secrets out of chat. Credentials, tenants, scans, confirmations, and audit logs are part of the workflow, not an afterthought.
• Let people and agents work across machines without trampling each other. Worktrees, branches, PRs, task IDs, mailbox state, and memory keep the work separated and traceable.
• Notice when the system is struggling. Stuck workers, orphaned PRs, stale assignments, CI failures, review-bot traps, and repeated mistakes should become visible signals.
• Improve the framework from real use. Imported skills, session learnings, quality findings, and better patterns should become better agents, hooks, scripts, and docs.
• Optimise for profitable outcomes: useful work shipped, lower supervision cost, safer operations, and decisions that make sense beyond the next prompt.

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 - including multi-layer action spaces, context isolation, and iterative execution loops.

Why This Framework?

Beyond single-task AI. A normal AI harness can be brilliant for one job and still weak at the work around the job. aidevops is for the surrounding discipline: context, routing, safety, git hygiene, collaboration, verification, memory, and follow-through.

What makes it different:

• Pulse supervision - scheduled checks can dispatch workers, merge ready PRs, close loops, and surface stuck work.
• Domain agents - code, automation, product, business, marketing, legal, content, research, SEO, health, reports, and framework work each get their own guidance.
• Cross-model checks - risky operations can be reviewed by a second provider to reduce shared failure modes.
• Service coverage - hosting, Git platforms, DNS, security, monitoring, deployment, payments, communications, and more are handled through repeatable helpers.
• Mission work - larger goals can be split into milestones with validation, budget tracking, and automatic advancement.

Attribution

aidevops is MIT licensed. Reuse is welcome, including commercial use, provided the copyright and license notices are retained. If you build a derivative framework, automation bot, workflow library, or commercial product from aidevops code or distinctive operating patterns, see ATTRIBUTION.md for the required notices and preferred credit text.

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
• Recent focus: OpenCode control-plane safety, local repo metrics, mobile simulator testing, self-hosted runner operations, and pulse/worker diagnostics

Key Commands

• aidevops init - Initialize in any project
• aidevops update - Update framework
• aidevops auto-update - Automatic update polling (enable/disable/status)
• aidevops runtime-bundle list - List retained validated runtime bundles; use rollback --bundle-id <id> --reason <text> for an explicit audited rollback
• aidevops gpt56-context [enable|disable|status] - Keep GPT-5.6 at a 300K advertised context window in OpenCode (enabled by default), so 80% auto-compaction runs near 240K before long-context pricing; status verifies plugin discovery, initialization, hook registration, and effective limits
• aidevops buzz [status|apply|rollback] - Inspect or manage Buzz Desktop OpenCode ACP compatibility
• ~/.aidevops/agents/scripts/team-interface-helper.sh [providers|detect|status|doctor|plan] - Inspect registered collaboration providers, persist read-only observations, or emit deterministic dry-run plans; no provider-write command is exposed
• aidevops opencode conversation --overlay FILE --dir PATH - Launch fixed-argv OpenCode ACP with a schema-validated ephemeral team-interface overlay and a final read-only capability guard; see .agents/reference/team-interface-opencode-overlays.md
• aidevops secret - Manage secrets (gopass encrypted, AI-safe)
• aidevops source-access - Manage exact-path, session-bound source-read approvals signed via sudo
• aidevops security - Full security assessment (posture, secrets, supply chain)
• aidevops lint audit - Audit native lint/format/typecheck commands and repo-verify hooks
• aidevops lint configure --dry-run - Preview safe evidence-based lint provisioning
• aidevops metrics generate - Generate local LOC, language, and dependency data for README badges or app about pages
• /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
• /report-token-use - Generate a local per-session token, model, compaction, and MCP-use report
• /pulse - Run the autonomous supervisor loop for dispatch, merge, diagnostics, and stuck-work recovery
• /serve-sim / serve-sim-helper.sh - Exercise mobile web flows in simulator-backed local previews

Agent Structure

• 14 primary agents (Build+, Automate, Product, SEO, Marketing-Sales, etc.) with specialist @subagents on demand
• 2,150+ agent and subagent markdown files organized by domain
• 1,630+ helper scripts in .agents/scripts/
• 185+ 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.

Recent framework upgrades

Since the last README feature refresh, aidevops has added or expanded:

• OpenCode GUI/control-plane planning: ADRs, threat model, trust-boundary guidance, and containment rules for a future GUI that stays local-first, auditable, and explicitly separated from secret-bearing helpers (docs/gui/).
• Mobile and simulator workflows: app-development guidance, App Store Connect support, Expo/Xcode/Swift workflows, Maestro/minisim/iOS Simulator MCP references, and serve-sim mobile web testing support (.agents/tools/mobile/).
• Self-hosted runner operations: lifecycle and storage runbooks, Docker foreground-mode guidance, systemd timer freshness triage, and ExecStop race-guard documentation (.agents/reference/github-self-hosted-runners.md).
• Pulse diagnostics and reliability: compact API-budget diagnostics, pulse cadence/API diagnostics, GitHub read ramp pacing, configurable worker floors, Renovate dashboard skipping, and more defensive duplicate/blocked-by/rate-limit handling.
• Worker and PR observability: worker diagnostic failure families, runtime observability signals, review-thread response scanning, required-check validation, orphan-recovery base handling, and safer automated GitHub write guards.
• Runtime-neutral safety and evidence contracts: shared command decisions across supported runtimes, commit-pinned plugin provenance with explicit hook authorization, recognized-client network checks, causal worker lineage, and redacted state snapshots/deltas in the existing observability database.
• OpenCode runtime polish: versioned session title suffixes, session archive retention, OAuth pool hardening, debug-error preservation, and reusable shell-env version lookup in the OpenCode plugin.

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.

Vault security model: aidevops defines protected data classes, provider routing labels, trust boundaries, and phased encrypted sync architecture in .agents/reference/vault.md. Vault guidance is local-first: third-party AI providers can only reason over data that has been decrypted into their prompt or tool context, so provider-side logs/retention remain outside Vault's technical control. Future local LLM mode reduces provider exposure but not local host compromise risk.

Vault passphrase warning: aidevops cannot recover a lost Vault passphrase. Save it in a trusted password manager with backups; never paste it into AI chat, CLI arguments, environment variables, logs, issue comments, or test fixtures.

Report creation, previews, and PDF exports

Use aidevops to turn evidence bundles into decision-ready reports while keeping Markdown or JSON as the canonical source. Report agents can produce AI-search audits, SEO/GEO scorecards, delivery reviews, campaign reports, board packs, incident summaries, recurring client handoffs, and before/after remediation evidence.

New report capabilities include:

• Markdown-first report anatomy with cover pages, executive summaries, evidence ledgers, source cards, action prompts, appendix links, charts, Mermaid/LaTeX fallbacks, and verified, partial, inferred, or missing evidence badges.
• DESIGN.md-backed visual templates plus basic no-CSS output for lightweight handoff.
• Browser preview HTML with sticky contents, source-card links, copy buttons, and light/dark theme variants where a style supports them.
• PDF-ready profiles for A4, US Letter, and 16:9 slides. Generated PDF links use *-a4.pdf, *-usletter.pdf, and *-slides.pdf names.
• Versioned examples under _reports/examples/; open _reports/examples/index.html locally to browse the example reports, rendered styles, and PDF exports.

Create a report:

1. Load reports/general.md for structure, then the matching domain report doc such as reports/seo-geo.md, reports/development.md, reports/marketing.md, or reports/business.md.
2. Gather source evidence first. Use deterministic run: steps or service helpers for collection, then ask the domain agent plus agent:Reports to interpret and prioritise.
3. Save canonical source as report.md or report.json in _reports/drafts/<report-name>/ while working, or in _reports/examples/<example-name>/ only after privacy review.
4. Render with /report-render report.md or .agents/scripts/report-render-helper.sh render report.md --template <style> --theme auto --pdf-profile a4 --output report.html.
5. Export PDFs from Chrome/Chromium using the generated HTML and the A4, US Letter, or slides profiles. Regenerate derived HTML/PDF files instead of hand-editing them.

Create a repeatable report agent:

1. Read reports/routine-handoff.md and tools/build-agent/build-agent.md.
2. Define the report cadence, evidence collection commands, source IDs, privacy rules, target template/style, and verification gates.
3. Put deterministic collection in run: steps and reserve agent:Reports for narrative, evidence interpretation, recommendations, and handoff tasks.
4. Store reusable agent instructions in the appropriate agent tier (custom/ for local/client-specific agents; shared .agents/ only for broadly reusable framework agents).

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

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 <id> # Dismiss a security advisory after taking action
aidevops source-access status  # List temporary source-read approvals
sudo -k /usr/bin/python3 -I -B /etc/aidevops/source-access/source-access-helper.py revoke <approval-id>

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.

When a read guard identifies only a low-confidence source-code basename match, it emits a scoped request. A maintainer can run the displayed root-broker approval command. Approvals are bound to the exact runtime session, user, Git-tracked regular source path, approved content digest, and guard reason; they expire within 12 hours and never override private-key, environment-file, credential-store, hard-link, symlink, changed-content, or untracked-file denials. The plugin redirects the approved read to a root-controlled immutable snapshot of those bytes so the live path cannot be rebound after verification; revocation removes both receipt and snapshot.

setup.sh and interactive aidevops update provision this capability automatically. Setup verifies the published signed tag, asks for one sudo confirmation, has root fetch the exact reviewed broker bytes directly over TLS, compares those downloads byte-for-byte with the signed Git objects, and then creates a dedicated root-only signing key under /etc/aidevops/source-access. It never executes or copies the user-writable aidevops deployment as root. The plugin also rejects approvals whenever the installed broker bytes differ from the active release. Headless updates cannot request sudo, so they leave the capability fail-closed; the next terminal aidevops update completes provisioning without a separate bootstrap procedure.

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):

npm install -g aidevops && aidevops update

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

Bun (fast alternative):

bun install -g aidevops && aidevops update

Homebrew (macOS/Linux):

brew install marcusquinn/tap/aidevops && aidevops update

Direct from source (aidevops.sh):

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

Updater recovery for v3.32.213: If aidevops update stops because the official framework source checkout is not in the project registry, run the direct installer above once, then rerun aidevops update. Do not add the framework checkout to the downstream project registry or bypass canonical remote validation.

Manual (git clone):

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

That's it! The setup script will:

• Clone/update the repo to ~/Git/aidevops
• Deploy agents to ~/.aidevops/agents/
• Install the aidevops CLI command
• Configure your AI assistants automatically
• 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 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 can do
• Ask about your work to give personalized recommendations
• Show which services are configured vs need setup
• Guide you through setting up each service with links and commands

After installation, use the CLI:

aidevops status           # Check what's installed
aidevops 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 runtime-bundle list # Inspect retained validated runtime bundles
aidevops init             # Initialize aidevops in any project
aidevops features         # List available features
aidevops repos            # List/add/remove registered projects
aidevops design           # DESIGN.md detection + brand guideline HTML/PDF exports
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).
• Init-aware design files: aidevops init records has_interface and seeds root DESIGN.md for standard repos plus minimal-scope repos with detected GUI/interface markers.
• Brand guideline exports: aidevops design guidelines . --pdf generates _reports/brand-guidelines/brand-guidelines.md, HTML, and A4/US Letter/slides PDFs from DESIGN.md.
• Repo rollout: aidevops design survey --json audits owned initialized GUI repos; aidevops design issues --apply files worker-ready auto-dispatch issues for missing DESIGN.md/brand-guideline artifacts.
• 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 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.

# 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 features in any git repository:

cd ~/your-project
aidevops init                         # Enable the default feature set
aidevops init planning                # Enable only planning
aidevops init planning,time-tracking  # Enable specific features
aidevops init deployment-context   # Scaffold a deployment manifest
aidevops init wordpress-context    # Scaffold WordPress + deployment manifests

This creates:

• .aidevops.json - Configuration with enabled features
• .agents/AGENTS.md - Project-specific agent context
• TODO.md - Quick task tracking with time estimates
• todo/PLANS.md - Complex execution plans
• .beads/ - Task graph database (if beads enabled)
• .aidevops/deployments.yaml - Deployment instance inventory (opt-in)
• .aidevops/wordpress.yaml - WordPress and LocalWP context (opt-in)

Available features: planning, git-workflow, code-quality, time-tracking, database, beads, sops, security, deployment-context, wordpress-context. hosting-context is an alias for deployment-context; wordpress-context implies deployment context. The default all set intentionally excludes both project-instance context features.

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:

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

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

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

Task Graph Visualization with Beads

Beads provides task dependency tracking and graph visualization:

aidevops init beads              # Enable beads (includes planning)

Task Dependencies:

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

Commands:

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

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

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

See .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:

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):

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:

# 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:

# 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:

# 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:

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

Supported AI tool: OpenCode 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 models (Anthropic) remain fully supported, and other providers are tested as their capabilities change.

The native ai_research tool uses OpenCode's configured providers and canonical simple, standard, and thinking workload tiers; it does not require a specific provider credential.

Recommended stack:

• OpenCode - The recommended AI coding agent. Powerful agentic TUI/CLI with native MCP support, Tab-based agent switching, LSP integration, plugin ecosystem, and excellent DX. All aidevops features are designed and tested for OpenCode first.
• OpenCode Zen - 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 (Anthropic) - Fully supported alternative provider. Claude models remain useful for fallback, cross-provider verification, and users with Claude Pro/Max OAuth access.
• Tabby - Recommended terminal. Colour-coded Profiles per project/repo, auto-syncs tab titles with git/session context and marks OpenCode turns from the first submitted message as ⚪, 🔴, 🟡, or 🟢.
• Zed - Recommended editor. High-performance with AI integration (use with the OpenCode Agent Extension).

Buzz Desktop OpenCode ACP compatibility

Buzz Desktop 0.5.4 can save an OpenCode managed agent without the required acp runtime argument, causing ACP initialization to time out. On macOS, aidevops init and aidevops update automatically reconcile affected records after deploying the current helper. Close Buzz first; if it is running, setup defers the change and reports the manual command.

aidevops buzz status    # Inspect compatibility state without changing it
aidevops buzz apply     # Add "acp" only to eligible empty argument lists
aidevops buzz rollback  # Restore only fields changed by aidevops

The migration preserves custom runtime arguments and unknown record fields, uses private backups and rollback state, and fails closed for unsupported Buzz versions or unsafe store paths. It never prints the managed-agent store, which can contain fallback credentials.

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

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

Step 3 — If still broken, re-add the account

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

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 <p># Assign stranded pending token
aidevops model-accounts-pool remove <p> <email># 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:

@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. Interactive OpenCode tabs add ⚪ as soon as the first root-session message is submitted and keep it when the initial title becomes descriptive, 🔴 while retrying after an error, 🟡 while awaiting permission, and 🟢 when finished and awaiting input. This helps identify both the work context and session state across multiple terminal sessions.

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

How it works: The pre-edit-check.sh script's primary role is enforcing git workflow protection (blocking edits on main/master branches). As a secondary, non-blocking action, it updates the terminal title via escape sequences. The OpenCode plugin listens for root-session user-message, status, and permission events and updates the same title without changing the stored OpenCode session name. No configuration is needed when dynamic terminal titles are enabled.

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

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

Companion tool:

• claude-code CLI - Called from within OpenCode for sub-tasks and headless dispatch

Collaborator compatibility: Projects initialized with aidevops init include pointer files (.cursorrules, .windsurfrules, etc.) that reference AGENTS.md, helping collaborators using other editors find project context. aidevops does not install into or configure those tools.

Repo courtesy files: aidevops init scaffolds standard repo files if they don't exist: DESIGN.md for GUI/interface repos, 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 management, credential security, code auditing

Autonomous Orchestration:

• Pulse supervisor - 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 - 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 - 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
• Self-hosted runner operations - GitHub runner lifecycle, storage, Docker foreground mode, systemd timers, and cleanup race guidance for reliable local/hosted worker capacity
• 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/tool capture plus append-only, redacted runtime lifecycle/state evidence with worker correlation and causal lineage in the existing local SQLite database
• Rate limits and API budget diagnostics - Per-provider rate-limit configuration, secondary cooldown capture, reset-aware pacing, and compact API budget summaries for pulse and worker decisions

Project Intelligence:

• Bundles - 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)
• Unified review - /review applies one evidence and finding contract to issues, PRs, local patches, branches, and commits. Workflow-owned findings are verified and repaired autonomously; ad-hoc human reviews can remain report-only
• 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
• Mobile app guidance - Expo, Swift/Xcode, App Store Connect, simulator automation, push/onboarding/monetisation/testing, and mobile web previews through serve-sim
• GUI control plane planning - Local-first product scope, stack and repo-layout ADRs, GUI trust boundaries, and threat model for future aidevops UI surfaces

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)
• Account knowledge and approval-bound social operations - Bounded account collection uses guarded X, named PRAW Reddit, and youtube.readonly user-OAuth YouTube adapters with stable identity, independent checkpoints, and explicit unsupported coverage. Owner-only immediate/scheduled posts, replies, likes/upvotes, bookmarks/saves, receipts, reconciliation, and mention/reply workflow state remain a separate fixed-provider subsystem. Model-provider auth such as OpenCode xAI/Grok remains separate from social API OAuth (content/social-xurl.md, content/social-reddit.md, content/social-youtube.md, knowledge-social-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, 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:

CLI Commands:

aidevops skill add <owner/repo>    # Import a skill from GitHub
aidevops skill add clawdhub:<slug> # Import a skill from ClawdHub
aidevops skill list                # List imported skills
aidevops skill check               # Check for upstream updates
aidevops skill update [name]       # Update specific or all skills
aidevops skill scan [name]         # Security scan skills (Cisco Skill Scanner)
aidevops skill remove <name>       # 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 when installed. Scanning runs on both initial import and updates -- pulling a new version of a skill triggers the same security checks as the first import. CRITICAL/HIGH findings block the operation; MEDIUM/LOW findings warn but allow. Telemetry is disabled - no data is sent to third parties.

When a VirusTotal API key is configured (aidevops secret set VIRUSTOTAL_MARCUSQUINN), an advisory second layer scans file hashes against 70+ AV engines and checks domains/URLs referenced in skill content. VT scans are non-blocking -- the Cisco scanner remains the security gate.

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 automatically on each batch scan and skill import, providing a transparent audit trail of security posture over time.

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

Reference:

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

Agent 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.

aidevops sources add ~/Git/my-private-agents     # Register a local repo
aidevops sources add-remote [email protected]: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).

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:

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:

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:

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
• API budget diagnostics — compact reports show GitHub core/search usage, cooldown provenance, cached PR metadata freshness, and pacing decisions before pulse burns through API quota
• Worker failure families — headless runtime errors, local runtime diagnostics, blocked-by lookup gaps, provider quota/credit exhaustion, and review-thread remediation issues are classified for targeted redispatch
• 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
• Repository campaign shadow — an opt-in, default-off projection preserves an oldest-ready frontier, semantic work state, and device-aware runner lanes without changing legacy dispatch or GitHub authority. See .agents/reference/repository-campaigns.md

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.

# 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.

# 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:

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:

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:

Resolution priority: Explicit bundle field in repos.json > .aidevops.json project config > auto-detection from marker files.

CLI:

bundle-helper.sh detect <repo-path>    # Auto-detect bundle type
bundle-helper.sh resolve <repo-path>   # Show resolved config (with overrides)
bundle-helper.sh show <bundle-name>    # 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.

# 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"

# Queue one delayed execution and inspect its lifecycle
aidevops schedule once --after 2h --name "Review authentication" \
  --dir ~/Git/example --prompt-file ~/.config/aidevops/prompts/auth-review.md
aidevops schedule status

# 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:

OpenCode Server (opencode serve)
├── Session 1 (runner/code-reviewer)
├── Session 2 (runner/seo-analyst)
└── Session 3 (scheduled-task)
         ↑
    HTTP API / SSE Events
         ↑
┌────────┴────────┐
│  Dispatch Layer │ ← runner-helper.sh, cron, Matrix bot, SDK
└─────────────────┘

Example runner templates: code-reviewer, seo-analyst - copy and customize for your own runners.

Matrix bot dispatch (optional): Bridge Matrix chat rooms to runners for chat-triggered AI. Accepted text events normalize through the provider-neutral contract and are durably claimed before dispatch. SQLite context is isolated by room and actor; idle sessions compact to summaries without deleting immutable interaction history.

# Setup Matrix bot (interactive wizard)
matrix-dispatch-helper.sh setup

# Map rooms to runners (mutable context is isolated by room and actor)
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 for full documentation including parallel vs sequential decision guide, SDK examples, CI/CD integration, and custom agent configuration. matrix-bot.md for Matrix bot setup including Cloudron Synapse guide and session persistence.

Self-Improving Agent System

Agents that learn from experience and contribute improvements:

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:

# 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.

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:

# 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:

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 pipeline is also available:

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:

See: 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:

# Example: Daily SEO report at 9am
0 9 * * * ~/.aidevops/agents/scripts/runner-helper.sh run "seo-analyst" "Generate daily SEO report"

See: TODO.md tasks t109-t118 for implementation status.

Requirements

Recommended Hardware

aidevops itself is lightweight (shell scripts + markdown), but AI model workloads benefit from capable hardware:

Cloud GPU providers for on-demand GPU access: NVIDIA Cloud, Vast.ai, RunPod, Lambda. 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

# 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 "[email protected]"

File Discovery Tools

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

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

Preference order for file discovery:

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

The setup script offers to install these tools automatically.

Comprehensive Service Coverage

Infrastructure & Hosting

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

Domain & DNS

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

Development & Git Platforms with CLI Integration

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

AI Orchestration Frameworks

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

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 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.

Mobile App & Simulator Testing

• Mobile app stack guidance: Expo, Swift/Xcode, backend, analytics, monetisation, onboarding, notification, publishing, and test strategy references for mobile delivery (.agents/tools/mobile/).
• Simulator-backed web testing: serve-sim guidance and helpers cover local/mobile preview flows, prompt failure handling, and simulator smoke tests before mobile UI changes ship.
• Device and automation options: agent-device, App Store Connect, Maestro, minisim, iOS Simulator MCP, Xcodebuild MCP, and accessibility tooling references help agents choose the right mobile verification path.
• Mobile-first artifact routing: /design-artifact can route mobile mockups and app screens through the design stack, then hand implementation to mobile/testing specialists.

Video Creation

• Remotion: Programmatic video creation with React - animations, compositions, media handling, captions
• Video Prompt Design: AI video prompt engineering using the 7-component meta prompt framework for Veo 3 and similar models
• Kie.ai: Unified asynchronous Market API and kie-helper.sh workflow for image, video, audio, uploads, callbacks, and credit checks with model-specific JSON pass-through
• MuAPI: Multimodal AI API for image/video/audio/VFX generation, workflows, agents, music (Suno), and lip-sync - unified creative orchestration platform
• yt-dlp: YouTube video/audio/playlist/channel downloads, transcript extraction, and local file audio conversion via ffmpeg

WordPress Development

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

Git CLI Enhancement Features:

• .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: GPG-encrypted secret management with AI-native wrapper (aidevops secret) - subprocess injection + output redaction keeps secrets out of AI context
• Vaultwarden: Password and secrets management
• SonarCloud: Security and quality analysis (A-grade ratings)
• CodeFactor: Code quality metrics (A+ score)
• Codacy: Multi-tool analysis (0 findings)
• CodeRabbit: AI-powered code reviews
• Snyk: Security vulnerability scanning
• Socket: Dependency security and supply chain protection
• Sentry: Error monitoring and performance tracking
• Cisco Skill Scanner: Security scanner for AI agent skills (prompt injection, exfiltration, malicious code)
• VirusTotal: Advisory threat intelligence via VT API v3 -- file hash scanning (70+ AV engines), domain/URL reputation checks for imported skills
• Secretlint: Detect exposed secrets in code
• OSV Scanner: Google's vulnerability database scanner
• Qlty: Universal code quality platform (70+ linters, auto-fixes)
• Retired review compatibility: Historical Gemini Code Assist GitHub reviews remain readable, but the sunset integration is no longer advertised or configurable

AI Prompt Optimization

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

Document Processing & 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: PDF form filling, digital signatures (PAdES B-B/T/LT/LTA), encryption, merge/split, text extraction
• MinerU: Layout-aware PDF-to-markdown/JSON conversion with OCR (109 languages), formula-to-LaTeX, and table extraction (53k+ stars, AGPL-3.0)
• Unstract: LLM-powered structured data extraction from unstructured documents (PDF, images, DOCX)
• GLM-OCR: Local OCR via Ollama - purpose-built for document text extraction (tables, forms, complex layouts) with zero cloud dependency

PDF/OCR Tool Selection:

Quick start:

# 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: SMS, voice calls, WhatsApp, phone verification (Verify API), call recording & transcription
• Telfon: Twilio-powered cloud phone system with iOS/Android/Chrome apps for end-user calling interface
• Matrix: Self-hosted chat with bot integration for AI runner dispatch (matrix-dispatch-helper.sh)
• SimpleX Chat: Privacy-first messaging with AI bot gateway for agent dispatch (simplex-bot/)
• 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: Lightweight JavaScript animation library for CSS, SVG, DOM attributes, and JS objects
• Remotion: Programmatic video creation with React - create videos using code with 29 specialized rule files
• Video Prompt Design: Structured prompt engineering for AI video generation (Veo 3, 7-component framework, character consistency, audio design)

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: Open-source modular voice pipeline (VAD → STT → LLM → TTS) with local GPU and cloud GPU deployment
• Pipecat: Real-time voice agent framework with Soniox STT, Cartesia TTS, and multi-LLM support

Performance & Monitoring

• PageSpeed Insights: Website performance auditing
• Lighthouse: Comprehensive web app analysis
• WebPageTest: Real-world performance testing from 40+ global locations with filmstrip, waterfall, and Core Web Vitals
• Updown.io: Website uptime and SSL monitoring

AI & Documentation

• Context7: 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: Run AI models locally via llama.cpp for free, private, offline inference with HuggingFace GGUF model management (local-model-helper.sh)

Local Development

• Localdev: 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 (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.

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:

By Category

Context & Codebase:

• Augment Context Engine - Semantic codebase retrieval with deep code understanding
• llm-tldr - Semantic code analysis with 95% token savings (details below)
• Context7 - Real-time documentation access for thousands of libraries
• Repomix - Pack codebases into AI-friendly context
• OpenAPI Search - Search and explore any OpenAPI specification (zero install, Cloudflare Worker)
• MCPorter - Discover, call, compose, and generate CLIs/typed clients for MCP servers

Browser Automation (browser tool suite + anti-detect stack, benchmarked):

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

Mobile & Simulator Testing:

• serve-sim - Apple Simulator browser preview/control for iOS, iPad, and Apple Watch simulators (setup offers global install on supported Macs)
• agent-device - AI-driven mobile app interaction across iOS and Android
• Maestro - Repeatable YAML E2E flows for mobile apps

SEO & Research:

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

Data Extraction:

• Outscraper - Google Maps, business data, reviews extraction (curl subagent)
• curl-copy - Authenticated scraping via DevTools "Copy as cURL" (no browser automation needed)

Performance & Security:

• PageSpeed Insights - Website performance auditing
• Snyk - Security vulnerability scanning
• Cloudflare Code Mode - 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 - Direct WordPress database access
• WordPress MCP Adapter - Official WordPress MCP for content management (STDIO, HTTP, and SSH transports)
• Next.js DevTools - React/Next.js development assistance

CRM & Marketing:

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

Accounts & Finance:

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

Document Processing & OCR:

• LibPDF - PDF form filling, digital signatures, encryption, merge/split (via helper script)
• Unstract - LLM-powered structured data extraction from PDFs, images, DOCX (MCP)
• GLM-OCR - Local OCR via Ollama for document text extraction (subagent)

Quick Setup

# 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 for 35+ languages. For aidevops projects that use Markdown and TOON extensively, add these optional LSP servers to your opencode.json for real-time diagnostics during editing:

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

Install the servers:

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

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

Browser Automation

Browser tool suite + 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:

Feature Matrix

Tool Selection

AI Page Understanding

Agents use lightweight methods instead of expensive vision API calls:

See .agents/tools/browser/browser-automation.md for the full decision tree, browser-use.md for Browser Use CLI 3.0 guidance, and browser-benchmark.md for reproducible benchmark scripts.

Device Emulation

Test responsive layouts and mobile-specific behavior using Playwright's built-in device emulation. Supports 100+ device presets with viewport, user agent, touch events, device scale factor, geolocation, locale/timezone, permissions, color scheme, offline mode, and network throttling.

Common device presets:

Emulation capabilities:

Recipes included: Responsive breakpoint testing, multi-device parallel testing, touch gesture testing, geolocation-dependent features, dark mode visual regression, and network condition emulation.

See .agents/tools/browser/playwright-emulation.md for complete documentation with code examples.

Anti-Detect Browser

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

Architecture:

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

Profile Types:

Quick Start:

# Setup
anti-detect-helper.sh setup

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

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

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

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

Engine Selection:

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

Repomix - AI Context Generation

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

Why Repomix?

Quick Usage

# Pack current repo with configured defaults
npx repomix

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

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

Configuration Files

Key Design Decisions

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

MCP Integration

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

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

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

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

Augment Context Engine - Semantic Codebase Search

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

Why Augment Context Engine?

Use it to:

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

Quick Setup

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

# 2. Authenticate (opens browser)
auggie login

# 3. Verify installation
auggie token print

MCP Integration

Add to your AI assistant's MCP configuration:

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

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

claude-code CLI:

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

Verification

Test with this prompt:

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

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

Repomix vs Augment Context Engine

See .agents/tools/context/augment-context-engine.md for complete documentation.

llm-tldr - Semantic Code Analysis

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

# Install
pip install llm-tldr

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

MCP Integration:

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

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

Cross-Tool Compatibility

Agent Skills Standard

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

Generated SKILL.md files in ~/.aidevops/agents/ provide skill metadata following the Agent Skills standard. These are discoverable by any compatible tool.

Claude Code Plugin Marketplace

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

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

This installs the complete framework: 14 primary agents, 2,150+ subagents, and 1,630+ helper scripts.

Importing External Skills

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

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

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

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

Supported sources:

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

Supported formats:

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

Features:

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

How it differs from npx add-skill:

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

AI Agents & Subagents

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

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

How Agents Work

Main Agents

Primary agents live at .agents/<name>.md. Each is a domain expert with its own system prompt, tool permissions, and subagent roster. MCPs are loaded on-demand per subagent, not per primary agent.

Specialist subagents (e.g. @wordpress, @seo, Build-Agent, Build-MCP, etc.) live under .agents/tools/ or as mode: subagent files and are invoked via @mention when domain expertise is needed. See subagent-index.toon for the full roster. For read-only macOS Activity Monitor and background-efficiency audits, use @macos-activity-cleaner or /aidevops-macos-activity-cleaner.

How to invoke a main agent

The aidevops- prefix differentiates framework commands from each client's native slash commands and groups them alphabetically in the command picker. It applies to every aidevops slash command — not just main agents — so /aidevops-preflight, /aidevops-release, /aidevops-commit etc. all sort together in your / menu.

Supported AI clients (14)

The framework installs itself across these clients. Slash commands, agent definitions, and (optionally) session-memory mining are wired up per-client by setup.sh, gated on per-client feature flags in .agents/scripts/runtime-registry.sh.

Feature flags per client (agents / commands / memory) live in runtime-registry.sh and can be overridden at install time via environment variables:

AIDEVOPS_FEATURE_MEMORY_CLAUDE_CODE=no setup.sh
AIDEVOPS_FEATURE_COMMANDS_CURSOR=no setup.sh

Memory mining defaults are deliberately conservative: only OpenCode, Claude Code, Codex, and Cursor are opted in by default. All other clients default to off — enable them case-by-case after reviewing what the mining job will read.

Endgame: progressive disclosure

The long-term direction is to make slash commands and @mentions unnecessary altogether. A progressive disclosure layer should load the right domain agents and tools into context based on the nature of the conversation — you should never have to remember agent names or prefix commands. The aidevops- slash commands documented above are a stepping stone: they standardise routing across every client we support, and will eventually be auto-invoked by the router rather than typed by hand.

Example Subagents with MCP Integration

These are examples of subagents that have supporting MCPs enabled. See .agents/ for the full list of 2,150+ subagents organized by domain.

Setup for OpenCode

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

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

Claude Marketplace

aidevops is available in the Claude marketplace:

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

Agent Skills (SKILL.md): Auto-discovered from ~/.aidevops/agents/ after running setup.sh. Compatible with any tool that supports the Agent Skills standard.

Continuous Improvement with @agent-review

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

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

The review agent will:

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

This creates a feedback loop:

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

Contributing improvements:

@agent-review create a PR for improvement #2

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

Code quality learning loop:

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

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

Slash Commands (OpenCode)

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

Available Commands

Planning & Task Management:

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

/list-todo options:

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

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

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

Development Workflow (typical order):

Content Workflow:

Media:

SEO Workflow:

SEO Debugging & Auditing (subagents in seo/):

Email Deliverability:

Release Workflow (in order):

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

Documentation:

Meta/Improvement:

AI Model Comparison:

Ralph Loop - Iterative AI Development

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

How it works:

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

Usage:

# Run quality checks iteratively until all pass
/preflight-loop --auto-fix --max-iterations <MAX_ITERATIONS>

# Or run changed-file checks directly (the default)
.agents/scripts/linters-local.sh

# Run every broad gate at a release boundary
.agents/scripts/linters-local.sh --full

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

Key features:

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

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

Full Loop - End-to-End Development Automation

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

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

Usage:

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

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

Options:

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

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

Git Worktrees - Parallel Branch Development

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

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

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

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

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

# List worktrees with CI status and PR links
wt list

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

Fallback (no dependencies):

~/.aidevops/agents/scripts/worktree-helper.sh add feature/my-feature
# Creates: ~/Git/{repo}-feature-my-feature/ (cd there manually)
~/.aidevops/agents/scripts/worktree-helper.sh list
~/.aidevops/agents/scripts/worktree-helper.sh clean
# Read-only count/byte inventory of retained recovery archives
~/.aidevops/agents/scripts/worktree-helper.sh recovery

Recovery inventory classifies attributable archives as protected or unknown and never deletes them. OpenCode session history can aid reconstruction, but it does not replace archive integrity evidence or authorize cleanup.

Benefits:

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

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

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

Session Management - Parallel AI Sessions

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

Completion signals:

Spawning options:

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

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

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

Session handoff pattern:

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

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

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

Cross-Session Memory System

"Compound, then clear" - Sessions should build on each other. The memory system stores knowledge, patterns, and learnings for future sessions using SQLite FTS5 for fast full-text search, with opt-in semantic similarity search via vector embeddings.

Slash commands:

Memory types:

Semantic search (opt-in):

# Enable semantic similarity search (~90MB model download)
memory-embeddings-helper.sh setup

# Search by meaning, not just keywords
memory-helper.sh recall "how to optimize queries" --semantic

Pattern tracking:

# Record what worked (via memory system)
memory-helper.sh store --type SUCCESS_PATTERN --content "Structured debugging found root cause" --tags "bugfix,standard"

# Record what failed
memory-helper.sh store --type FAILURE_PATTERN --content "Blind refactor without tests caused regressions" --tags "refactor"

# Get suggestions for a new task
memory-helper.sh recall "refactor auth middleware" --semantic

Auto-capture: AI agents automatically store memories using --auto flag when they detect working solutions, failed approaches, or decisions. Privacy filters strip <private> tags and reject secret patterns.

CLI usage:

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

# Store auto-captured memory (from AI agent)
~/.aidevops/agents/scripts/memory-helper.sh store --auto --content "Fixed CORS with nginx headers" --type WORKING_SOLUTION

# Recall memories (keyword search - default)
~/.aidevops/agents/scripts/memory-helper.sh recall "cors"

# Recall memories (semantic similarity - opt-in)
~/.aidevops/agents/scripts/memory-helper.sh recall "cors" --semantic

# Show auto-capture log
~/.aidevops/agents/scripts/memory-helper.sh log

# View statistics (includes auto-capture counts)
~/.aidevops/agents/scripts/memory-helper.sh stats

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

# Namespaces (per-runner memory isolation)
~/.aidevops/agents/scripts/memory-helper.sh --namespace my-runner store --content "Runner learning"
~/.aidevops/agents/scripts/memory-helper.sh --namespace my-runner recall "query" --shared
~/.aidevops/agents/scripts/memory-helper.sh namespaces  # List all namespaces

Storage: ~/.aidevops/.agent-workspace/memory/memory.db (+ optional embeddings.db for semantic search, namespaces/ for per-runner isolation)

Session mining (cross-client)

Beyond explicit /remember calls, aidevops can harvest structured session data from each supported AI client's on-disk conversation history. This turns every prior session — regardless of which tool you were using — into searchable context for future sessions.

Per-client storage paths and formats (see runtime-registry.sh):

Defaults are deliberately conservative. Only the four tier-1 clients — OpenCode, Claude Code, Codex, and Cursor — have memory mining enabled by default. They have the most mature, stable, documented formats and are the ones most likely to contain the full interactive history you'd want to search.

For every other client, memory mining is opt-in per runtime. Enable it with:

AIDEVOPS_FEATURE_MEMORY_GEMINI_CLI=yes setup.sh
AIDEVOPS_FEATURE_MEMORY_CONTINUE=yes setup.sh

Privacy note. Session files contain everything you typed — including secrets, credentials, and file contents pasted into prompts. The mining pipeline runs secretlint-style scrubbing at ingestion and defaults to local-only storage. Never sync the memory DB to a shared or cloud location without reviewing what's in it.

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

Installation

Slash commands are automatically installed by setup.sh for both OpenCode and Claude Code:

# OpenCode commands deployed to:
~/.config/opencode/command/

# Claude Code commands deployed to:
~/.claude/commands/

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

Both generators read from the same source (.agents/scripts/commands/*.md), ensuring command parity across tools.

Usage

In OpenCode or Claude Code, type the command at the prompt:

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

Commands invoke the corresponding workflow subagent with appropriate context.

Agent Lifecycle (Three Tiers)

User-created agents survive aidevops update. Agents progress through tiers as they mature:

Promotion workflow: Draft agents that prove useful can be promoted to custom (private) or shared (open-source via PR). Orchestration agents can create drafts in draft/ for reusable parallel processing context.

Creating Custom Agents

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

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

# Agent Name

Detailed instructions for the agent...

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

Usage Examples

Server Management

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

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

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

Monitoring & Uptime (Updown.io)

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

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

Domain & DNS Management

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

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

Strategic Keyword Research

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

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

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

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

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

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

Features:

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

Quality Control & Performance

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

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

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

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

Documentation & Resources

Wiki Guides:

• Getting Started - Installation and setup
• Configuration Reference - All JSONC/JSON config options, types, defaults, and examples
• CLI Reference - aidevops command documentation
• MCP Integrations - MCP servers setup
• Providers - Service provider configurations
• Workflows Guide - Development workflows
• The Agent Directory - Agent file structure
• Understanding AGENTS.md - How agents work

Agent Guides (in .agents/):

• API Integrations - Service APIs
• Browser Automation - 8 tools + anti-detect stack: decision tree, parallel, extensions, fingerprinting
• Device Emulation - Mobile/tablet testing: 100+ device presets, viewport, geolocation, locale, dark mode
• serve-sim - Apple Simulator browser preview/control for mobile app QA
• Anti-Detect Browser - Multi-profile management, fingerprint rotation, proxy integration
• Web Performance - Core Web Vitals, network dependencies, accessibility (Chrome DevTools MCP)
• PageSpeed - Lighthouse CLI and PageSpeed Insights API
• Pandoc - Document format conversion
• Security - Enterprise security standards

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

Architecture

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

Configuration & Setup

aidevops is configured through two JSONC/JSON files that control framework behaviour, model routing, quality gates, and user preferences. Both are optional -- sensible defaults apply out of the box.

Quick examples:

# Disable automatic updates
aidevops config set updates.auto_update false

# Use thinking-tier verification for destructive operations
aidevops config set safety.verification_tier thinking

# View all current config values
aidevops config list

# Validate config against schema
aidevops config validate

Precedence: Environment variables (AIDEVOPS_*) > config file > built-in defaults. See the full configuration reference for every option, type, default, and example.

Service Credentials

Service-specific credentials (hosting, DNS, Git platforms, etc.) use a separate template system:

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

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

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

See .agents/reference/configuration.md for details on the template system and credential security.

Security & Best Practices

Credential Management:

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

Multi-Tenant Credential Storage

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

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

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

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

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

# Export for scripts
source <(credential-helper.sh export)

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

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

Quality Assurance:

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

Contributing & License

Contributing:

1. Fork the repository
2. Create safe linked worktree for your contribution
3. Add provider support or improvements
4. Test with your infrastructure
5. Submit pull request

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

What This Framework Achieves

For You:

• Autonomous project management — dispatch a mission and let AI agents handle milestones, validation, and delivery across days
• Cross-domain operations — code, automation, business, marketing, legal, sales, content, video, research, SEO, social media, health, and accounts managed through one platform
• Multi-model safety — destructive operations verified by a second AI provider before execution
• Enterprise-grade quality — multi-platform analysis, automated security monitoring, continual improvement loops
• Infrastructure management — 30+ service integrations with standardized commands across all providers

For Your AI Agents:

• Autonomous supervisor — pulse runs every 2 minutes, merging PRs, dispatching workers, killing stuck processes, advancing missions
• Operational intelligence — struggle-ratio detection, orphaned PR recovery, circuit breaker, dynamic concurrency
• Cost-aware routing — provider-aware model selection across OpenAI, Anthropic, Gemini, Cursor, Grok, and local models with budget tracking
• Progressive context — 2,150+ subagents loaded on demand, project bundles auto-configuring quality gates and model tiers
• Self-improving — session mining extracts learnings, quality findings auto-create tasks, patterns feed back into agent prompts

Get Started:

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

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

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

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

An AI operations platform for launching and managing projects across every business domain — from code to content, infrastructure to invoicing.

Star History