# Setup > Install or verify the ade-bench harness, the Python project that actually runs the benchmark tasks this plugin generates. Use when ade-bench isn't yet on the user's machine, when a generated task fails because the harness is missing, or when the user explicitly asks to set up ade-bench. Also invoked automatically by plan-tasks and create-task when they detect ade-bench is missing. - Skill: `typedef-ai/setup` (Agent Skill) - Install (CLI): `npx skillmds@latest add typedef-ai/setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/typedef-ai/setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: typedef-ai (https://skillmd.com/u/typedef-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/typedef-ai/setup --- # ADE-Bench Setup The plugin generates task definitions. ade-bench (a separate Python project) is what actually executes them inside Docker against the user's data. This skill makes ade-bench available so generated tasks can be run. Default install location: `~/.ade-bench`. The skill `git clone`s ade-bench there, runs `uv sync` to install Python deps, and `uv tool install .` to put the `ade` CLI on PATH. --- ## Step 1: Parse Arguments - `--path `: Where to install ade-bench. Default: `~/.ade-bench`. Resolve `~` to the user's home directory. Use the resolved absolute path in every step below. --- ## Step 2: Check Prerequisites Run these in parallel and collect the results: 1. **git**: `command -v git` 2. **uv**: `command -v uv` 3. **docker**: `command -v docker` If any of the three is missing, stop and tell the user what's missing and how to install it: - **git**: Use the system package manager (`brew install git`, `apt install git`, etc.). - **uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh` (then restart the shell or `source ~/.zshrc`). - **docker**: Recommend Docker Desktop, Colima, or OrbStack. Don't try to install or start Docker. The user must do this. If `docker` is installed but not running, that's fine for setup — flag it but proceed. Docker only needs to be running when tasks actually execute. --- ## Step 3: Detect Existing Installation Two checks, in order: 1. **Already installed via this skill?** ```bash test -f /pyproject.toml && grep -q 'name = "ade-bench"' /pyproject.toml ``` 2. **Already on PATH from somewhere else?** ```bash command -v ade ``` If either succeeds: - Run `ade --help` to confirm the CLI works. - Tell the user where ade-bench was found and that no install is needed. - Skip to Step 7 (DuckDB database download — still verify it's been done) and continue from there. If `` exists but is **not** a valid ade-bench checkout (different repo, partial clone, leftover files), stop and ask the user whether to remove and reinstall or pick a different path. Do not silently overwrite. If nothing is installed, proceed to Step 4. --- ## Step 4: Clone the Repository ```bash git clone https://github.com/dbt-labs/ade-bench.git ``` If the clone fails, report the error verbatim and stop. The most common reasons are no network, GitHub auth issues, or `` already existing as a non-empty directory. --- ## Step 5: Install Python Dependencies ```bash cd && uv sync ``` This builds a local virtualenv at `/.venv` and installs all Python deps. Expect this to take 30 seconds to a couple of minutes depending on network speed. --- ## Step 6: Install the `ade` CLI Globally ```bash cd && uv tool install . ``` `uv tool install` puts the `ade` entry point on the user's PATH (under `~/.local/bin` by default). After this, `ade run …` works from any directory. Verify: ```bash command -v ade && ade --help ``` If `ade` is not found after `uv tool install`, the user's `~/.local/bin` is probably not on PATH. Tell them: > "`ade` was installed but isn't on PATH. Add `~/.local/bin` to your PATH — for zsh, run: `echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc && source ~/.zshrc`" Don't modify the user's shell config yourself. --- ## Step 7: Download Bundled DuckDB Databases ade-bench ships several bundled dbt projects (`airbnb`, `f1`, `quickbooks`, …) along with reference DuckDB files used as the source database for those projects. The `.duckdb` files live in a GitHub release (`dbt-labs/ade-bench:databases`), not in the repo itself — `/shared/databases/duckdb/` is empty after `git clone`. Without these files, any task targeting a bundled project fails at `setup_duckdb` with "DuckDB database '' not found at ". The release currently totals ~225 MB. Skip this step only if the user has explicitly said they'll exclusively use their own dbt projects with their own DuckDB files (the generators write `db_dir` into `task.yaml` for those — bundled databases aren't consulted). ### 7.1 Check if already populated Compare the number of `.duckdb` files locally present against the expected count from the GitHub release. Skip the download only when they match exactly — a partial state (e.g., 10 of 11 files) should fall through to Step 7.2 so `gh release download` can fetch the missing file(s). ```bash present=$(ls /shared/databases/duckdb/*.duckdb 2>/dev/null | wc -l | tr -d ' ') if [ "$present" -gt 0 ]; then expected=$(gh release view databases --repo dbt-labs/ade-bench \ --json assets \ --jq '[.assets[] | select(.name | endswith(".duckdb"))] | length' 2>/dev/null) if [ -n "$expected" ] && [ "$present" -eq "$expected" ]; then # All files present — skip the rest of Step 7 and report "databases already present" : fi fi ``` Notes: - Costs one extra `gh release view` API call only when *some* files are already present, so the first-run path is unaffected. - If `gh` isn't installed or isn't authenticated, the `expected` lookup returns empty and the check falls through to Step 7.2 (which has its own gh-missing branch with manual-download instructions). Consistent. - This makes the check survive future ade-bench bundled-project additions without touching the skill — the threshold is whatever the release says it is. Stash the `expected` value if you got one — Step 7.4 uses it for the user-facing report. ### 7.2 Check `gh` availability and auth ```bash command -v gh && gh auth status ``` - **`gh` missing** → tell the user to either install it (`brew install gh`) or download the release assets manually from `https://github.com/dbt-labs/ade-bench/releases/tag/databases` into `/shared/databases/duckdb/`. Skip the download and continue to Step 8. - **`gh` present but not authenticated** → tell the user to run `gh auth login` and re-invoke `/ade-bench:setup`. Skip the download and continue to Step 8. ### 7.3 Download ```bash gh release download databases \ --repo dbt-labs/ade-bench \ --pattern "*.duckdb" \ --dir /shared/databases/duckdb ``` If the command fails partway through (network, auth expiry), report the error verbatim and continue. The user can rerun the same command later — `gh release download` skips files that already exist. Do **not** block the rest of setup on a download failure. Snowflake-only users don't need these, and a partial download can be completed manually later. ### 7.4 Verify ```bash present=$(ls /shared/databases/duckdb/*.duckdb 2>/dev/null | wc -l | tr -d ' ') size=$(du -sh /shared/databases/duckdb 2>/dev/null | cut -f1) ``` Use the `expected` value from Step 7.1 if you have it. Report the count as `/` so a partial state is visually obvious — e.g.: - All present: `DuckDB DBs: 11/11 files (224 MB)` - Partial: `DuckDB DBs: 10/11 files (210 MB) — re-run /ade-bench:setup to fetch the missing file` - Expected-count unknown (gh missing/unauthed): `DuckDB DBs: 11 files (224 MB)` — fall back to just the count. --- ## Step 8: Verify Docker ```bash docker ps ``` If it fails: - "Cannot connect to the Docker daemon" → Docker isn't running. Tell the user to start it. - "command not found" → Already handled in Step 2. If Docker isn't running, that's fine for now — flag it but don't block. The user only needs it when running tasks. --- ## Step 9: Initialize Snowflake `.env` (Conditional) Only if the user has indicated they'll be running Snowflake-targeted tasks (or if the calling skill detected a Snowflake project). Skip for DuckDB-only users. ```bash test -f /.env || cp /.env.example /.env ``` Tell the user: > "I copied `.env.example` to `.env` at `/.env`. Open it and fill in your Snowflake credentials before running Snowflake tasks. Required vars: `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_USER`, `SNOWFLAKE_PASSWORD`, `SNOWFLAKE_ROLE`, `SNOWFLAKE_WAREHOUSE`." **Do not prompt for credentials. Do not write credential values to any file.** The user fills in `.env` themselves. --- ## Step 10: Report Results Summarize for the user: ``` ade-bench setup complete. Install path: CLI on PATH: ade (verified with `ade --help`) DuckDB DBs: / files () | files () if expected unknown | not downloaded — install `gh` and rerun, or download manually Docker: Snowflake env: <.env created at , fill in credentials | not initialized — DuckDB-only> Next: run `/ade-bench:plan-tasks ` or `/ade-bench:create-task ` to generate your first benchmark tasks. ``` --- ## Important Guidelines - **Don't install dependencies the user already has.** Step 3 short-circuits if a working ade-bench is already on the system. - **Don't write credentials anywhere.** The Snowflake setup ends at copying `.env.example` to `.env`. The user fills it in. - **Don't start Docker.** If Docker isn't running, tell the user. Don't run `open -a Docker` or anything similar — it's surprising and sometimes wrong. - **Don't modify the user's shell config.** If PATH adjustment is needed, tell the user the command to run; don't run it. - **Default install location is `~/.ade-bench`.** Honor `--path` if provided, but don't invent alternative defaults.