# Adguard

> This skill should be used when the user asks about AdGuard Home status, DNS filtering, or blocked domains. Triggers include: "is adguard running", "how many queries did it block today", "show me recent DNS queries", "search the DNS log for a domain", "is example.com blocked", "AdGuard stats", or any question about DNS-level ad blocking or network filtering.

- Skill: `dinglebear-ai/adguard` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add dinglebear-ai/adguard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dinglebear-ai/adguard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dinglebear-ai (https://skillmd.com/u/dinglebear-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dinglebear-ai/adguard

---


# AdGuard

DNS-level ad blocking and network filtering. Talk to it directly over the AdGuard Home control API (served under `/control`, HTTP Basic auth).

## How to call it

Prefer `scripts/adguard-api.sh` for common read-only calls. It sources the
plugin-generated config first, then the environment and legacy `~/.lab/.env`,
keeps the Basic auth password out of output, and exposes
`status`, `stats`, `querylog`, `filtering`, and `check-host`.

Configure `adguard_url`, `adguard_username`, and the sensitive
`adguard_password` in Claude plugin settings or Gemini extension settings. The
SessionStart/ConfigChange hook writes
`${XDG_CONFIG_HOME:-~/.config}/lab-adguard/config.env` with mode `600`.

Read the base URL and credentials without printing secrets:

```bash
source "${XDG_CONFIG_HOME:-$HOME/.config}/lab-adguard/config.env" 2>/dev/null || source ~/.lab/.env

: "${ADGUARD_URL:?missing ADGUARD_URL}"
: "${ADGUARD_USERNAME:?missing ADGUARD_USERNAME}"
: "${ADGUARD_PASSWORD:?missing ADGUARD_PASSWORD}"
AUTH=(-u "$ADGUARD_USERNAME:$ADGUARD_PASSWORD")
```

Auth is HTTP Basic (`-u user:pass`). Never echo the password.

> Use `~/.lab/.env` only as a local migration fallback; prefer Claude/Gemini settings.

## Common operations

| Intent | Request |
|---|---|
| Server status + version + running state | `curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/status"` |
| DNS query statistics | `curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/stats"` |
| Search the query log | `curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/querylog?search=<term>&limit=50"` |
| Filtering status / rule lists | `curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/filtering/status"` |
| Check whether a host is blocked | `curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/filtering/check_host?name=<host>"` |

The version string and running state are fields inside `GET /control/status` (there is no separate version endpoint). Full API reference: <https://github.com/AdguardTeam/AdGuardHome/blob/master/openapi/openapi.yaml>.

## Configuration

`ADGUARD_URL`, `ADGUARD_USERNAME`, and `ADGUARD_PASSWORD` come from plugin
settings, environment variables, or the legacy `~/.lab/.env` fallback. Verify
connectivity:

```bash
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' "${AUTH[@]}" "$ADGUARD_URL/control/status"
```

## When NOT to use this skill

- The user is asking about a different homelab service — load that service's skill instead.
- The user wants to change filtering rules or protection settings — those are mutating `POST /control/*` endpoints; confirm intent first and consult the OpenAPI reference for the exact body.