{ "markdown": "

\n \"Claude\n \"dbt\n \"Version\n \"License\"\n

\n\n# dbt-toolkit\n\n**Stop guessing at dbt.** A Claude Code plugin that makes dbt development safe, systematic, and mistake-proof.\n\nOne command — `/dbt-toolkit:dbt` — gives your team smart model selection, execution across local/SSH/Docker, automatic error diagnosis, lineage analysis, test coverage tracking, and freshness monitoring. No more hunting through logs, memorizing CLI flags, or forgetting which models to run.\n\n---\n\n## Install\n\n```bash\n# From the Claude Code official marketplace\n/plugin install dbt-toolkit\n\n# Or install directly from GitHub\n/plugin install github:rishavchatterjee/dbt-toolkit\n```\n\n**Prerequisites:** Python 3.9+ and [Claude Code](https://claude.ai/code) with plugin support.\n\n---\n\n## How It Works\n\n```\nYou say: dbt-toolkit does:\n───────────────────────────────────── ──────────────────────────────────────\n/dbt-toolkit:dbt run Config → Selector → Execute → Parse results\n/dbt-toolkit:dbt test Run tests → Analyze failures → Coverage report\n/dbt-toolkit:dbt freshness Check sources → Track history → Warn on stale\n/dbt-toolkit:dbt debug Error patterns → Root cause → Suggested fix\n/dbt-toolkit:dbt \"run my revenue NLP routing → Same safe workflow\n models\"\n```\n\n### The Execution Flow\n\n```mermaid\ngraph LR\n U[\"User: /dbt run\"] --> R[\"Router Skill\"]\n R --> S[\"Smart Selector\"]\n S --> E{\"Execution Method\"}\n E -->|local| L[\"Local CLI\"]\n E -->|ssh| SSH[\"SSH Runner\"]\n E -->|docker| D[\"Docker Runner\"]\n L & SSH & D --> P[\"Parse Results\"]\n P --> A[\"Artifact Analysis\"]\n A -->|failures| DX[\"Error Diagnosis\"]\n A -->|success| OK[\"Coverage Report\"]\n \n style R fill:#6366f1,color:#fff\n style S fill:#f59e0b,color:#000\n style DX fill:#ef4444,color:#fff\n style OK fill:#22c55e,color:#fff\n```\n\n```\n ┌─────────────────────────────────────────┐\n │ /dbt-toolkit:dbt run │\n └────────────────┬────────────────────────┘\n │\n ┌────────────────▼────────────────────────┐\n │ 1. Load config (.dbt-toolkit/config.yaml│\n │ 2. Build selector (tag:, path:, config:)│\n │ 3. Detect execution method │\n └────────────────┬────────────────────────┘\n │\n ┌──────────┴──────────┐\n │ │\n ┌─────▼──────┐ ┌───────────▼──┐ ┌──────▼─────┐\n │ Local │ │ SSH │ │ Docker │\n │ (direct) │ │ (remote) │ │ (container)│\n └─────┬──────┘ └──────┬───────┘ └──────┬─────┘\n │ │ │\n ┌─────▼────────────────▼──────────────────▼─────┐\n │ 4. Parse run_results.json │\n │ 5. Match errors against 17 patterns │\n │ 6. Report: successes, failures, slowest model │\n └───────────────────────────────────────────────┘\n```\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install the plugin\n/plugin install dbt-toolkit\n\n# 2. Navigate to your dbt project\ncd my-dbt-project\n\n# 3. Run the toolkit\n/dbt-toolkit:dbt\n```\n\nSetup auto-detects your `dbt_project.yml` and walks you through configuration: execution method, profile, target, and defaults.\n\n---\n\n## Features\n\n| Feature | What it does |\n|---------|-------------|\n| **Smart routing** | `/dbt-toolkit:dbt` + anything — natural language or direct commands |\n| **3 execution methods** | Local, SSH (auto-handles venv + env vars), Docker (auto-mounts volumes) |\n| **17 error patterns** | Auto-match errors across 8 categories with suggested fixes |\n| **DAG lineage** | Traverse upstream/downstream, calculate impact radius |\n| **Test coverage** | Track test-to-model ratios, flag undocumented models |\n| **Freshness tracking** | Monitor source staleness with history and warnings |\n| **Secret sanitization** | Passwords, tokens, and keys never appear in logs |\n| **Audit health checks** | Sort/dist keys, materialization, test coverage, tags |\n| **Scaffolding templates** | Model, test, unit test, config templates |\n\n---\n\n## Skills (16)\n\n| # | Skill | Invoke with | Purpose |\n|---|-------|-------------|---------|\n| 1 | Router | `/dbt-toolkit:dbt` | Interactive menu + NLP routing |\n| 2 | Setup | `/dbt-toolkit:dbt-setup` | First-time configuration wizard |\n| 3 | Run | `/dbt-toolkit:dbt-run` | Execute models with smart selection |\n| 4 | Test | `/dbt-toolkit:dbt-test` | Run tests, analyze failures, coverage |\n| 5 | Freshness | `/dbt-toolkit:dbt-freshness` | Source data freshness checks |\n| 6 | Debug | `/dbt-toolkit:dbt-debug` | Systematic troubleshooting |\n| 7 | Audit | `/dbt-toolkit:dbt-audit` | Proactive health checks |\n| 8 | Develop | `/dbt-toolkit:dbt-develop` | Scaffold, compile, preview, lineage |\n| 9 | Docs | `/dbt-toolkit:dbt-docs` | Generate and audit documentation |\n| 10 | Artifacts | `/dbt-toolkit:dbt-artifacts` | Parse and compare run outputs |\n| 11 | Seed & Snapshot | `/dbt-toolkit:dbt-seed-snapshot` | Seed loading, SCD snapshots |\n| 12 | Deps | `/dbt-toolkit:dbt-deps` | Package management |\n| 13 | Run Operation | `/dbt-toolkit:dbt-run-operation` | Execute dbt macros |\n| 14 | Brainstorm | `/dbt-toolkit:dbt-brainstorming` | Model design exploration |\n| 15 | Execute Plans | `/dbt-toolkit:dbt-executing-plans` | Step-by-step with dbt checkpoints |\n| 16 | Code Review | `/dbt-toolkit:dbt-code-review` | SQL quality and best practices |\n\nOr just describe what you want:\n\n```\n/dbt-toolkit:dbt run my revenue models\n/dbt-toolkit:dbt why did my test fail?\n/dbt-toolkit:dbt what depends on stg_orders?\n```\n\n---\n\n## Execution Methods\n\n**Local** — dbt installed on your machine. Runs directly.\n\n**SSH** — dbt on a remote server. Auto-handles:\n- SSH key authentication\n- Virtual environment activation\n- Environment variable forwarding\n- Remote project path resolution\n\n**Docker** — dbt in a container. Auto-handles:\n- Volume mounting for project files\n- Image management\n- Adapter-specific images\n\n---\n\n## Error Patterns\n\n17 patterns across 8 categories with auto-matching and suggested fixes:\n\n| Category | Patterns | Example |\n|----------|----------|---------|\n| Connection | 3 | Refused, timeout, authentication failure |\n| Compilation | 3 | Undefined ref, missing node, circular dependency |\n| Runtime SQL | 4 | Relation not found, duplicate key, missing column, disk full |\n| Permission | 2 | Access denied, insufficient privileges |\n| Performance | 2 | Statement timeout, serializable isolation |\n| Parse | 1 | YAML/Jinja syntax errors |\n| Redshift | 1 | Spectrum CTAS, MERGE not supported |\n| Incremental | 1 | Schema change, full refresh needed |\n\n---\n\n## Lineage\n\nTraverse the DAG from `manifest.json`:\n\n- **Upstream:** What does this model depend on?\n- **Downstream:** What breaks if I change this model?\n- **Impact radius:** How many models are affected?\n\nUsed by the run, develop, and audit skills to build smart selectors and assess change impact.\n\n---\n\n## Configuration\n\nCreated by `/dbt-toolkit:dbt-setup` at `.dbt-toolkit/config.yaml`:\n\n```yaml\nversion: 1\n\nexecution:\n method: \"local\" # or \"ssh\" or \"docker\"\n\nprofile:\n name: \"my_profile\"\n target: \"dev\"\n\ndefaults:\n threads: 4\n full_refresh: false\n fail_fast: false\n log_format: \"json\"\n\nfreshness:\n enabled: true\n warn_after_hours: 24\n\naudit:\n check_sort_dist: true\n check_test_coverage: true\n min_test_coverage: 0.8\n```\n\nSee `templates/config.yaml` for all options including SSH and Docker configuration.\n\n
\nTelemetry (optional)\n\nAnonymous, opt-in usage telemetry via PostHog. Inert unless configured:\n\n```bash\nexport POSTHOG_API_KEY=\"your-posthog-project-key\"\n```\n\nAlso requires `telemetry.enabled: true` in config. No data is ever sent without both conditions met.\n\n
\n\n---\n\n## Architecture\n\n```\ndbt-toolkit/\n├── .claude-plugin/ Plugin metadata (plugin.json, marketplace.json)\n├── hooks/ Session auto-detection\n├── skills/ 16 skills (each with SKILL.md)\n│ ├── dbt/ Router — single entry point\n│ ├── dbt-setup/ First-time wizard\n│ ├── dbt-run/ Execute models with smart selection\n│ ├── dbt-test/ Run tests, analyze failures, coverage\n│ ├── dbt-freshness/ Source data freshness checks\n│ ├── dbt-debug/ Systematic troubleshooting\n│ ├── dbt-audit/ Proactive health checks\n│ ├── dbt-develop/ Scaffold, compile, preview, lineage\n│ ├── dbt-docs/ Generate and audit documentation\n│ ├── dbt-artifacts/ Parse and compare run outputs\n│ ├── dbt-seed-snapshot/ Seed loading, SCD snapshots\n│ ├── dbt-deps/ Package management\n│ ├── dbt-run-operation/ Execute dbt macros\n│ ├── dbt-brainstorming/ Model design exploration\n│ ├── dbt-executing-plans/ Plan execution with checkpoints\n│ └── dbt-code-review/ SQL quality and best practices\n├── agents/ Lineage + test-failure analysis agents\n├── references/ dbt knowledge base (7 docs)\n├── scripts/ Python automation (13 modules)\n│ ├── config.py Config discovery and typed access\n│ ├── runner.py Execute dbt via local/SSH/Docker\n│ ├── artifacts.py Parse manifest, run_results, sources\n│ ├── lineage.py DAG traversal from manifest\n│ ├── freshness.py Freshness tracking with history\n│ ├── coverage.py Test and doc coverage analysis\n│ ├── audit.py Health checks (coverage, sort/dist, tags)\n│ ├── selector.py Build node selection strings\n│ ├── error_patterns.py 17 patterns across 8 categories\n│ ├── state.py State comparison for CI/CD slim runs\n│ ├── cli.py Unified CLI entry point\n│ ├── logger.py Structured logging + secret sanitization\n│ ├── telemetry.py Anonymous opt-in telemetry\n│ └── bootstrap.sh Environment detection script\n├── templates/ Project scaffolding files\n└── tests/ Test suite (unit + integration)\n```\n\n### Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `PyYAML` | YAML parsing |\n| `paramiko` | SSH execution |\n| `click` | CLI framework |\n| `rich` | Terminal formatting |\n| `posthog` | Anonymous opt-in telemetry |\n\n---\n\n## For Contributors\n\n### Running tests\n\n```bash\npip install -e \".[dev]\"\npython -m pytest tests/ -v\n```\n\n### Design Principles\n\n- **Business questions only** — skills never ask CLI flags, config syntax, or YAML formatting\n- **Auto-resolve** — derive everything from config + project state\n- **Fail safe** — every external call has retries, timeouts, and error handling\n- **3 execution methods** — local, SSH, Docker — same skill logic regardless\n- **Secret sanitization** — passwords and tokens never reach logs\n\n### Adding a skill\n\n1. Create `skills/your-skill/SKILL.md` with `name` and `description` frontmatter\n2. Follow the Conversation Principles (never ask technical questions)\n3. Add routing logic to `skills/dbt/SKILL.md`\n4. Reference relevant `references/*.md` docs\n\n---\n\n## Related Projects\n\n| Project | Relationship | Link |\n|---------|-------------|------|\n| **soul** | AI platform that hosts dbt-toolkit as a product server | [github.com/rishav1305/soul](https://github.com/rishav1305/soul) |\n| **preset-toolkit** | Sister plugin for Preset/Superset dashboards (same architecture) | [github.com/rishav1305/preset-toolkit](https://github.com/rishav1305/preset-toolkit) |\n| **soul-team** | Multi-agent runtime that uses dbt-toolkit for data workflows | [github.com/rishav1305/soul-team](https://github.com/rishav1305/soul-team) |\n| **soul-bench** | CARS benchmark — LLM evaluation framework | [github.com/rishav1305/soul-bench](https://github.com/rishav1305/soul-bench) |\n| **SoulGraph** | Multi-agent RAG framework (LangGraph + ChromaDB) | [github.com/rishav1305/soulgraph](https://github.com/rishav1305/soulgraph) |\n\n## Author\n\n**Rishav Chatterjee** — Senior AI Architect\n\n- Portfolio: [rishavchatterjee.com](https://rishavchatterjee.com)\n- GitHub: [github.com/rishav1305](https://github.com/rishav1305)\n- LinkedIn: [linkedin.com/in/rishavchatterjee](https://linkedin.com/in/rishavchatterjee)\n\n---\n\n## License\n\nBusiness Source License 1.1 — see [LICENSE](LICENSE) for details.\nConverts to Apache License 2.0 on 2030-03-15.\n", "bytes": 13146, "sha": "db4364765b4b6bfc60ea3c3d31a3b72178e9b510da0536e49ed4966dbc811c5a", "repo_slug": "rishav1305/dbt-toolkit", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_rishav1305_dbt_toolkit_dbt_toolkit_cb9372ca/readme" }