Power BI Codex Plugin

Codex-first Power BI workflows, built on top of pbi-cli.
Inspect semantic models, validate PBIR reports, and build safer dashboards from Codex.

Why • Quickstart • Features • Trust • Proven workflow

---

Why This Exists

pbi-cli is the Power BI automation engine. This repository is intentionally smaller: it packages the Codex-facing guidance and workflow conventions that make Power BI work safer and more repeatable from an agent session.

Power BI Codex does not replace pbi-cli. It sits beside it as a focused Codex plugin for:

• checking readiness before touching a Power BI project;
• using JSON-first commands so Codex can reason from structured output;
• editing PBIR report files with guardrails;
• validating reports before Power BI Desktop reloads them;
• preserving lessons learned from real dashboard work.

Quickstart

Install a pbi-cli-tool build that includes the Codex additions:

pbi-cli agent install --target codex
pbi-cli agent status --target codex --json
pbi --json doctor
pbi --json capabilities

Install this plugin locally:

$plugin = Join-Path (Get-Location) "plugins\power-bi-codex"
Copy-Item -Recurse -Force $plugin "$env:USERPROFILE\.codex\plugins\power-bi-codex"

Verify a PBIP project:

.\scripts\verify-power-bi-codex.ps1 -ProjectPath "C:\path\to\project"

The verification script runs doctor, capabilities, report validation, and report info.

What This Plugin Adds

• Codex guidance for pbi --json doctor and pbi --json capabilities.
• Safe PBIR editing rules learned while building the Table1 Overview dashboard.
• Dashboard-building steps for report pages, visuals, slicers, and measures.
• Guardrails for Unicode Windows paths, Desktop reload behavior, PBIR page IDs, UTF-8 without BOM, and validation before opening Power BI Desktop.
• A small validation workflow for plugin packaging.

Required CLI Support

This plugin expects a pbi-cli-tool build with Codex-aware commands. From a local pbi-cli checkout, install it for testing:

py -m venv $env:TEMP\pbi-cli-codex-venv
& $env:TEMP\pbi-cli-codex-venv\Scripts\python.exe -m pip install -e .
& $env:TEMP\pbi-cli-codex-venv\Scripts\pbi.exe --json doctor

Trust Boundaries

Power BI Codex is a local plugin. It contains instructions, skills, docs, and a verification script. It does not run a service, store credentials, or send data to a remote endpoint.

The actual Power BI operations are performed by pbi-cli on the local machine. That means connection metadata, PBIR files, and Power BI Desktop state remain under the same local trust model as pbi-cli.

Proven Workflow

We tested the workflow on a Power BI project named Nupco-cli:

• Opened nupco.pbip.
• Detected Power BI Desktop with pbi --json doctor.
• Read model metadata: 3 tables, 36 columns, 1 relationship.
• Created four measures on Table1.
• Built a PBIR dashboard page named Table1 Overview.
• Added 9 visuals: 4 cards, 2 charts, 2 slicers, and 1 matrix.
• Validated the PBIR report with zero errors and zero warnings.

The dashboard page was ultimately stored under a PBIR-safe internal page ID:

nupco.Report/definition/pages/a1b2c3d4e5f60718293a/

Repository Layout

.codex-plugin/plugin.json       Plugin metadata
skills/                         Codex skills for Power BI work
scripts/verify-power-bi-codex.ps1
docs/what-we-built.md           Notes from the original build and trial
.github/workflows/validate.yml  Lightweight packaging validation

Publish To GitHub

Use this plugin folder as the root of a standalone repository:

git init
git add .
git commit -m "feat: add Power BI Codex plugin"
git branch -M main
git remote add origin https://github.com/Aymn74/power-bi-codex.git
git push -u origin main

Relationship To pbi-cli

This project is an independent companion plugin inspired by, and designed to work with, pbi-cli. Core Power BI automation belongs in pbi-cli; this repository keeps Codex-specific workflow guidance and packaging separate.

License

MIT, matching the plugin metadata. The underlying pbi-cli package and Microsoft client libraries may include their own license terms.