Agent skill

Houndarr Architecture

Houndarr's source layout and architectural patterns at file granularity.

AGPL-3.0Auto-check passedBackend & APIs

Install Houndarr Architecture

skills CLI

$ npx skills add av1155/houndarr --skill houndarr-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install av1155/houndarr houndarr-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/av1155/houndarr.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/houndarr-architecture .claude/skills/houndarr-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "houndarr-architecture" agent skill from https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture into .claude/skills/houndarr-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "houndarr-architecture", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add av1155/houndarr --skill houndarr-architecture -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install av1155/houndarr houndarr-architecture --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/av1155/houndarr.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/houndarr-architecture .agents/skills/houndarr-architecture && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "houndarr-architecture" agent skill from https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture into .agents/skills/houndarr-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "houndarr-architecture", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add av1155/houndarr --skill houndarr-architecture -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install av1155/houndarr houndarr-architecture --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/av1155/houndarr.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/houndarr-architecture .cursor/skills/houndarr-architecture && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "houndarr-architecture" agent skill from https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture into .cursor/skills/houndarr-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "houndarr-architecture", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/av1155/houndarr.git --path .agents/skills/houndarr-architecture

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add av1155/houndarr --skill houndarr-architecture -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install av1155/houndarr houndarr-architecture --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/av1155/houndarr.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/houndarr-architecture .gemini/skills/houndarr-architecture && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "houndarr-architecture" agent skill from https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture into .gemini/skills/houndarr-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "houndarr-architecture", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install av1155/houndarr houndarr-architecture

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add av1155/houndarr --skill houndarr-architecture -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/av1155/houndarr.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/houndarr-architecture .github/skills/houndarr-architecture && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "houndarr-architecture" agent skill from https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture into .github/skills/houndarr-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "houndarr-architecture", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add av1155/houndarr --skill houndarr-architecture -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install av1155/houndarr houndarr-architecture --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/av1155/houndarr.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/houndarr-architecture .opencode/skills/houndarr-architecture && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "houndarr-architecture" agent skill from https://github.com/av1155/houndarr/tree/main/.agents/skills/houndarr-architecture into .opencode/skills/houndarr-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "houndarr-architecture", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: houndarr-architecture
GitHub stars: 292
Token cost: ~2k tokens
SKILL.md length: 437 words
Files: 1
Skills in repo: 9
Repo updated: Oct 5, 2026
First seen: Oct 7, 2026
Licence: AGPL-3.0

At a glance

Houndarr's source layout and architectural patterns at file granularity.

Tasks that involve OpenAPI specifications
SKILL.md covers Source layout, Wire models vs domain models, Auth composition and Encryption, plus 4 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Houndarr Architecture is an agent skill from av1155/houndarr. Houndarr's source layout and architectural patterns at file granularity. Loads when reading or editing src/houndarr/. Covers the per-file purpose for auth/, clients/, engine/, routes/, services/; the wire-models vs domain-models split; the arr API spec snapshots under docs/api/; and pointers to the more specific database / engine skills for narrower scopes.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering OpenAPI specifications. It works with Python. The repository describes itself as: Self-hosted arr companion for controlled missing, cutoff, and upgrade searches. The licence is AGPL-3.0.

When your agent uses it

Tasks that involve OpenAPI specifications

Example prompts

“/houndarr-architecture”

Requirements

Python 3
Docker

What it can do on your machine

Read from SKILL.md and the folder at commit 9b39fdb. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Houndarr Architecture loads about 2k tokens when it runs. Until then it costs about 96 tokens; SKILL.md has 437 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~96
When it runs · the whole SKILL.md, loaded when a task matches: ~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from av1155/houndarr at commit 9b39fdb, republished under its AGPL-3.0 licence (© av1155). 437 words, ~2,016 tokens.

Download SKILL.mdSave it as .claude/skills/houndarr-architecture/SKILL.md (or your agent's skills folder).

name: houndarr-architecture
description: Houndarr's source layout and architectural patterns at file granularity. Loads when reading or editing src/houndarr/. Covers the per-file purpose for auth/, clients/, engine/, routes/, services/; the wire-models vs domain-models split; the *arr API spec snapshots under docs/api/; and pointers to the more specific database / engine skills for narrower scopes.
paths: src/houndarr/**

Houndarr architecture reference

For narrower scopes:

Database schema and migrations: see houndarr-database skill (loads on src/houndarr/database.py).
Algorithmic verification: see verify-algorithms skill (loads on src/houndarr/engine/**).

Source layout

src/houndarr/
  __main__.py          # CLI entry point (Click), logging setup, uvicorn.run
  app.py               # create_app(), lifespan, middleware registration
  auth/                # AuthMiddleware, bcrypt, CSRF, rate limiter (seam package)
    password.py        # bcrypt verify / hash helpers
    rate_limit.py      # in-memory login rate limiter
    session.py         # signed session cookie encode / decode
    setup.py           # first-run admin setup + password policy
    csrf.py            # CSRF double-submit token rotation
    proxy_auth.py      # reverse-proxy trust gate and header extraction
    identity.py        # current-user resolution from session or proxy header
    middleware.py      # AuthMiddleware dispatch (builtin vs proxy path)
  config.py            # AppSettings dataclass, get_settings() singleton
  crypto.py            # Fernet encrypt/decrypt, master key management
  database.py          # get_db() context manager, schema migrations
  enums.py             # StrEnum consolidation (SearchKind, SearchAction, CycleTrigger, ItemType)
  errors.py            # HoundarrError hierarchy (Client/Engine/Service/Route)
  value_objects.py     # Frozen value objects shared across layers (ItemRef)
  clients/             # httpx-based *arr API clients
    base.py            # ArrClient ABC with _get()/_post() + raise_for_status() + get_queue_status()
    sonarr.py          # SonarrClient (episode/season search, v3 API)
    radarr.py          # RadarrClient (movie search, v3 API)
    lidarr.py          # LidarrClient (album/artist search, v1 API)
    readarr.py         # ReadarrClient (book/author search, v1 API)
    whisparr_v2.py     # WhisparrV2Client (Sonarr-based, episode/season search)
    whisparr_v3.py     # WhisparrV3Client (v3, Radarr-based, movie/scene search)
  engine/
    candidates.py      # SearchCandidate dataclass, ItemType re-export, date helpers
    search_loop.py     # run_instance_search(): unified search pipeline (missing/cutoff/upgrade passes, queue-backpressure gate)
    supervisor.py      # Supervisor: one asyncio.Task per enabled instance
    adapters/
      __init__.py      # AppAdapter dataclass, ADAPTERS registry, get_adapter()
      protocols.py     # AppAdapterProto: runtime_checkable Protocol matching the AppAdapter shape
      sonarr.py        # Sonarr adapter: candidate conversion + dispatch
      radarr.py        # Radarr adapter: candidate conversion + dispatch
      lidarr.py        # Lidarr adapter: candidate conversion + dispatch
      readarr.py       # Readarr adapter: candidate conversion + dispatch
      whisparr_v2.py   # Whisparr v2 adapter: candidate conversion + dispatch
      whisparr_v3.py   # Whisparr v3 adapter: movie/scene candidate conversion + dispatch
  routes/
    _htmx.py           # is_hx_request() shared helper for partial vs full renders
    pages.py           # Setup, Login, Dashboard, Logs, Settings page routes
    health.py          # GET /api/health (Docker HEALTHCHECK)
    settings/          # Settings surface split by concern
      __init__.py      # composes the sub-routers into a single settings_router
      _helpers.py      # template render, client build, connection check, validators
      page.py          # GET /settings
      account.py       # POST /settings/account/password
      instances.py     # /settings/instances/* (CRUD, test-connection, toggle)
    api/
      logs.py          # GET /api/logs (JSON, with cursor-based pagination)
      status.py        # GET /api/status (JSON, dashboard polling)
  services/
    instances.py       # Instance CRUD, InstanceType StrEnum
    cooldown.py        # Per-item search cooldown tracking
    url_validation.py  # SSRF guard for instance URLs

Wire models vs domain models

Wire models (clients/_wire_models/): every *arr HTTP response is validated with a Pydantic model from this package before it reaches a parser. PaginatedResponse[T] (generic, PEP 695 syntax) covers the shared /wanted/* envelope; SystemStatus and QueueStatus back ArrClient.ping() and ArrClient.get_queue_status(); per-app *WantedEpisode / *WantedMovie / *WantedAlbum / *WantedBook and *LibraryEpisode / *LibraryMovie / *LibraryAlbum / *LibraryBook models name the record shapes. ArrSeries / ArrArtist / ArrAuthor type the parent-aggregate fetches. All wire models extend an internal _ArrModel that sets populate_by_name=True + extra="ignore" so unknown fields from new *arr versions never raise. Field names are snake_case in Python and alias to the camelCase the APIs serialise.
Domain models (parsed result types): MissingEpisode, LibraryMovie, etc. are frozen dataclasses, one per client file next to the client that builds them. Every frozen dataclass uses slots=True. Instance composes seven frozen sub-structs (core, missing, cutoff, upgrade, schedule, snapshot, timestamps) and is itself frozen and slotted; callers evolve it through dataclasses.replace. AppSettings is the only deliberately-mutable dataclass (env overrides applied in-place on the lazy singleton).

Auth composition

Global AuthMiddleware (Starlette BaseHTTPMiddleware) routes every request through one of three path buckets; no per-route auth decorators:

_API_KEY_PATHS (currently /api/v1/widget): the top-level dispatch() sends the request straight to _dispatch_api_key, which verifies X-Api-Key against the widget_api_key table (constant-time compare on the SHA-256 digest) and applies a per-IP attempt rate limit. Bypasses session and CSRF.
_PUBLIC_PATHS (/setup, /login, /api/health, /static): no auth. Each of _dispatch_builtin and _dispatch_proxy short-circuits these before any session or proxy-header check.
Everything else: mode-dependent. _dispatch_builtin enforces the session cookie + CSRF (default); _dispatch_proxy enforces the proxy-trust gate + CSRF when HOUNDARR_AUTH_MODE=proxy.

Proxy-auth trust and header reads flow through two primitives in auth.py: _is_trusted_proxy(request) (IP gate) and _extract_proxy_username(request) (header read, assumes trust already verified). The middleware's _dispatch_proxy and the standalone _validate_proxy_auth both compose these so the gate logic lives in one place.

Show full SKILL.md (115 more words)Show less

Encryption

Master key in request.app.state.master_key; passed explicitly to service functions as master_key= kwarg; never imported globally.

HTMX

SPA-like shell navigation; nav links use hx-target="#app-content" with hx-swap="innerHTML" and hx-push-url="true". Routes check is_hx_request(request) from routes/_htmx.py and return either partial or full template. Templates are lazily initialised via a module-level singleton.

Supervisor

One asyncio.Task per enabled instance; 10s shutdown timeout.

search_log

Every search attempt writes a row with action searched / skipped / error / info.

*arr API reference (local)

Full upstream OpenAPI specs vendored under docs/api/ (one per app: sonarr, radarr, whisparr_v2, whisparr_v3, lidarr, readarr). Source of truth when touching clients/ code; see docs/api/README.md. Refreshed weekly (Mon 10:00 UTC) by api-snapshot-refresh.yml, so specs are never more than a week stale.

Files

Just SKILL.md in .agents/skills/houndarr-architecture of av1155/houndarr.

Open the folder on GitHubat commit 9b39fdb

Compare with similar skills

Houndarr Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Houndarr Architecture compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Houndarr Architecture this skillav1155/houndarr	292	—	~2k	Automated safety check: Pass	AGPL-3.0	4 days ago
Land TS MonoUKGovernmentBEIS/inspect_ai	3k	—	~3k	Automated safety check: Pass	MIT	today
Assisted Service Dev Modeopenshift/assisted-service	138	—	~1.3k	Automated safety check: Pass	Apache-2.0	today
Kingdee MCP DevWaHaiLong/KingdeeMCP	105	—	~853	Automated safety check: Pass	MIT	2 mo ago
API Documenteralirezarezvani/claude-code-tresor	777	—	~1.5k	Automated safety check: Pass	MIT	3 mo ago
Ns APINethServer/nethsecurity	192	—	~2.8k	Automated safety check: Pass	Custom licence	yesterday

Similar skills

Land TS Mono
UKGovernmentBEIS/inspect_ai
Land a PR that requires a coordinated ts-mono submodule change.
3k GitHub stars~3k tokensUpdated today
Backend & APIsAuto-check passed
Assisted Service Dev Mode
openshift/assisted-service
Build and code-generate assisted-service using skipper with podman.
138 GitHub stars~1.3k tokensUpdated today
Backend & APIsAuto-check passed
Kingdee MCP Dev
WaHaiLong/KingdeeMCP
Knowledge base for the Kingdee MCP Dev Squad. An agent skill from WaHaiLong/KingdeeMCP.
105 GitHub stars~853 tokensUpdated 2 mo ago
Backend & APIsAuto-check passed
API Documenter
alirezarezvani/claude-code-tresor
Auto-generate API documentation from code and comments. An agent skill from alirezarezvani/claude-code-tresor.
777 GitHub stars~1.5k tokensUpdated 3 mo ago
Backend & APIsAuto-check passed
Ns API
NethServer/nethsecurity
Write or modify a NethSecurity Python RPCD API script or hook.
192 GitHub stars~2.8k tokensUpdated yesterday
Backend & APIsAuto-check passed
FastAPI Expert
Jeffallan/claude-skills
Builds async Python APIs with FastAPI and Pydantic V2, covering endpoints, JWT authentication, async SQLAlchemy, WebSockets and pytest checks against the OpenAPI docs.
12k GitHub stars~1.8k tokensUpdated 6 days ago
Backend & APIsAuto-check passed

Questions about Houndarr Architecture

What does Houndarr Architecture do?

Houndarr's source layout and architectural patterns at file granularity. Houndarr Architecture is an agent skill from av1155/houndarr. Houndarr's source layout and architectural patterns at file granularity.

When should I use Houndarr Architecture?

Houndarr Architecture fits situations like: tasks that involve OpenAPI specifications.

How do I install Houndarr Architecture in Claude Code?

Run `npx skills add av1155/houndarr --skill houndarr-architecture -a claude-code`. Or copy the skill folder (.agents/skills/houndarr-architecture in av1155/houndarr) into .claude/skills/houndarr-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Houndarr Architecture in Codex?

Run `npx skills add av1155/houndarr --skill houndarr-architecture -a codex`. Or copy the skill folder (.agents/skills/houndarr-architecture in av1155/houndarr) into .agents/skills/houndarr-architecture in your project. Codex loads it when a task matches its description.

Can I use Houndarr Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add av1155/houndarr --skill houndarr-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/houndarr-architecture, .gemini/skills/houndarr-architecture, .github/skills/houndarr-architecture and .opencode/skills/houndarr-architecture in your project.

What does Houndarr Architecture need to run?

SKILL.md names no scripts, command-line tools or credentials: Houndarr Architecture is instructions for the agent only. Our summary lists: Python 3; Docker.

Does Houndarr Architecture access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Houndarr Architecture safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Houndarr Architecture use?

Houndarr Architecture is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Houndarr Architecture use?

About 2k tokens (SKILL.md is roughly 8.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Houndarr Architecture?

Skills that share tags, products or a category with Houndarr Architecture: Land TS Mono (UKGovernmentBEIS/inspect_ai, 3k stars), Assisted Service Dev Mode (openshift/assisted-service, 138 stars), Kingdee MCP Dev (WaHaiLong/KingdeeMCP, 105 stars) and API Documenter (alirezarezvani/claude-code-tresor, 777 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Houndarr Architecture?

av1155 (a GitHub user) maintains it in av1155/houndarr, which has 292 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 5, 2026.

Source: av1155/houndarr on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Houndarr Architecture

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Houndarr architecture reference

Source layout

Wire models vs domain models

Auth composition

Encryption

HTMX

Supervisor

search_log

*arr API reference (local)

Files

Compare with similar skills

Similar skills

More from av1155/houndarr

Related

Questions about Houndarr Architecture