⚡ Open source · MIT

Measure the real impact of AI on your engineering team

Connect your JIRA epic and GitHub repo. Get hours saved, AI token costs, PR quality and risk score in one interactive dashboard — in under 30 seconds.

Install with pipx → ▶ Try live demo View on GitHub

Try it now with no credentials: ai-engineering-metrics analyze --mock

# install once

$ pipx install git+https://github.com/

$ engmetrics-ai/engmetrics-ai.git

# try with no credentials

$ ai-engineering-metrics analyze --mock

# real epic from your project folder

$ ai-engineering-metrics analyze -e KAN-4 --open

✓ Analysis complete: KAN-4

9.2h saved (40%) · 580k tokens · Risk: 19.5

reports/KAN-4/dashboard.html

How it works

From epic to insights in four steps

No data warehouse, no SaaS signup. One CLI command pulls everything and writes a self-contained bundle to your project folder.

📦

Step 1

Install once

One pipx command puts the CLI on your PATH, isolated from your project dependencies. Works on macOS, Linux and Windows.

pipx install git+https://github.com/
engmetrics-ai/engmetrics-ai.git

🔑

Step 2

Configure once

Run the interactive wizard once — credentials are saved globally, shared across all repos. GitHub uses the gh CLI you already have.

ai-engineering-metrics configure

🚀

Step 3

Run the analysis

Point it at any JIRA epic key. It fetches stories, linked pull requests and AI token usage automatically.

cd your-repo
ai-engineering-metrics analyze \
--epic PROJ-42 --open

📊

Step 4

Read the bundle

A reports/PROJ-42/ folder lands in your project with a dashboard, JSON and two CSVs ready to share.

reports/PROJ-42/
├── dashboard.html
├── metrics.json
├── stories.csv
└── pull_requests.csv

Live example

This is what you actually get

Real output from KAN-4 "Update Libs Fintechops" — pulled live from JIRA + GitHub.

engmetrics.ai · Interactive Demo — KAN-4 · Update Libs Fintechops

▶ Open interactive demo

Fully interactive — charts, PR details, DORA/MTTR — no login required · real data from fintech-pos-api-aisdd

Key	Status	Tokens	Saved	Risk
KAN-9	Done	210 k	3.2 h	mod
KAN-6	Done	142 k	2.0 h	mod
KAN-5	Done	85 k	1.2 h	mod
KAN-7	Done	60 k	1.2 h	mod
KAN-10	To Do	48 k	0.8 h	mod

#	Title	Status	+/−	Risk
#9	chore(KAN-10): bump to v0.2.0 and pin dev dependency versions	open	+4/−4	33.6
#8	fix(KAN-9): adjust env defaults for Node 22 compatibility	merged	+2/−2	33.6
#7	docs(KAN-8): update README to reflect new dependency versions	merged	+2/−2	33.6
#4	test(KAN-5): add post-upgrade smoke tests for env config	merged	+39/−0	33.6
#1	chore(deps): upgrade Node.js engine requirement to v22	open	+1/−1	8.6

Output

Four artifacts, every run

Every analyze run writes a complete bundle to reports/<EPIC>/.

🌐

dashboard.html

Interactive charts & tables.
Open in any browser —
no server required.

• Productivity timeline
• Hours saved per story
• PR quality scorecards
• Risk breakdown

📊

metrics.json

"productivity": {
  "hours_saved": 9.2,
  "savings_percent": 40.0
},
"ai_usage": {
  "total_tokens": 580000,
  "estimated_cost": 3.48
},
"risk": { "score": 19.5, "level": "low" }

📋

stories.csv

key,status,sp,ai_tokens,saved_h
KAN-9,Done,8,210000,3.2
KAN-6,Done,5,142000,2.0
KAN-5,Done,3,85000,1.2
KAN-7,Done,3,60000,1.2
KAN-10,To Do,2,48000,0.8
KAN-8,Done,2,35000,0.8

🔀

pull_requests.csv

linked_to,#,status,+,−,cycles
KAN-9,#8,merged,2,2,0
KAN-8,#7,merged,2,2,0
KAN-5,#4,merged,39,0,0
KAN-10,#9,open,4,4,0
KAN-4,#3,open,1,1,0
KAN-4,#1,open,1,1,0

Prerequisites

Two things you need before running

The CLI requires a JIRA API token and the GitHub CLI (gh). Here is exactly how to get both.

🔑

JIRA API Token

Read epics and stories from your Atlassian workspace

Open your Atlassian account settings

Go to id.atlassian.com → Security → API tokens and log in with your JIRA email.

Create a new API token

Click Create API token, give it a label like "engmetrics-ai" and click Create.

Important: copy the token immediately — it is displayed only once and cannot be recovered later.

Find your JIRA base URL

It is the domain you see in the browser when logged in, e.g. https://yourco.atlassian.net

Run the configure wizard

The wizard saves credentials globally — no .env file needed.

ai-engineering-metrics configure
# JIRA Base URL: https://yourco.atlassian.net
# JIRA Email: [email protected]
# JIRA API Token: ************

🐙

GitHub CLI (gh)

Discover and enrich pull requests linked to each epic

Install the GitHub CLI

Choose your OS:

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Ubuntu / Debian
sudo apt install gh

All installers: cli.github.com

Authenticate with GitHub

gh auth login

Follow the prompts:
1. Choose GitHub.com
2. Choose HTTPS
3. Choose Login with a web browser
4. Paste the one-time code shown in your browser

Verify the authentication

gh auth status
# → ✓ Logged in to github.com

Repo is auto-detected

The CLI reads the GitHub remote from your current directory automatically — no extra config needed. Override with --repo owner/name if needed.

ai-engineering-metrics analyze -e PROJ-42 --open
# repo detected from git remote automatically

Setup guide

Up and running in 5 minutes

Requires Python 3.12+, pipx, a JIRA API token and the GitHub CLI.

Install Python 3.12+

Download from python.org or use your package manager. Check with python --version.

Install pipx

pipx installs CLI tools in isolated environments so they never conflict with your project dependencies.

Install engmetrics-ai

One command installs the CLI and adds ai-engineering-metrics to your PATH.

Try the demo (zero config)

Run with --mock to see a full dashboard with synthetic data. No JIRA or GitHub required.

Analyze your real epic

Run from inside your repo. The tool picks up the saved credentials and detects the GitHub remote automatically.

Terminal

# 1. Install pipx
$ pip install --user pipx
$ python -m pipx ensurepath

# 2. Install the CLI
$ pipx install git+https://github.com/engmetrics-ai/engmetrics-ai.git

# 3. Try the demo
$ ai-engineering-metrics analyze --mock

# 4. Configure credentials (once, saved globally — no .env needed)
$ ai-engineering-metrics configure
JIRA Base URL: https://yourco.atlassian.net
JIRA Email: [email protected]
JIRA API Token: ************
✓ Configuration saved to ~/.config/ai-engineering-metrics/config.yaml

# 5. Analyze your epic
$ cd your-repo
$ ai-engineering-metrics analyze -e PROJ-42 --open

✓ Analysis complete: PROJ-42
  9.2h saved (40%)  ·  580k tokens  ·  Risk: 19.5 (low)
  reports/PROJ-42/dashboard.html ← opening...

CLI Reference

All flags

Flag	Default	Description
`--epic` / `-e`	DEMO-1 (mock)	JIRA epic key to analyze, e.g. `PROJ-123`
`--mock`	off	Use synthetic data — no credentials required
`--output` / `-o`	`reports/`	Base output directory. A sub-folder named after the epic is created inside
`--format` / `-f`	`all`	`all` · `html` · `json` · `csv`
`--open`	off	Open the generated dashboard in your browser when done
`--stdout`	off	Print metrics JSON to stdout — pipe to `jq`
`--repo` / `-r`	auto	Override GitHub repo as `owner/name`
`--verbose` / `-v`	off	Show every API call and PR-matching decision
`--version`	—	Print installed version and exit

ai-engineering-metrics configure — interactive wizard to set up or update JIRA credentials. Saved to ~/.config/ai-engineering-metrics/config.yaml (Linux/macOS) or %APPDATA%\ai-engineering-metrics\config.yaml (Windows). Shared across all repos.

Recipes

# Pipe metrics to jq
ai-engineering-metrics analyze -e PROJ-123 --stdout | jq .ai_usage

# HTML only, to a custom folder
ai-engineering-metrics analyze -e PROJ-123 -f html -o ./out

# Override GitHub repo
ai-engineering-metrics analyze -e PROJ-123 --repo acme/backend

# Update to the latest version
pipx upgrade ai-engineering-metrics