epunkine

Your rules. Your standards. Your code health.

What is epunkine?

epunkine is a CLI tool that evaluates your codebase against your design philosophy — not against generic "best practices" or industry conventions.

The "code health" that epunkine measures is how well your code conforms to your own architectural decisions and design principles. It is not about clean code in the abstract sense. It is not about what the internet says is good. It is about whether your code follows the rules you have defined.

You write a health-policy.md in plain language — describing your team's conventions, layer boundaries, naming rules, complexity thresholds, or anything else you care about. epunkine sends that policy and your actual source code to an LLM, which then evaluates the codebase and generates findings.

epunkine inspect

🔍 Scanning repository...
🤖 Running inspector agent (this may take a while)...

Score: 72/100
Findings: 2 high, 3 medium, 1 low

✅ Report saved to .epunkine/results/report.md

---

Table of Contents

• Installation
• Prerequisites
• Quick Start
• Command Reference
• Configuration
• health-policy.md
• GitHub Actions
• Model Providers
• License

---

Installation

npm install -g @ken11/code-epunkine

Or run without installing:

npx @ken11/code-epunkine inspect

After global installation, the epunkine command is available:

epunkine --version

---

Prerequisites

• Node.js 20 or later
• Credentials for one of the supported model providers:
  • Amazon Bedrock: AWS credentials (IAM role / AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY / AWS CLI profile)
  • OpenAI: OPENAI_API_KEY environment variable

---

Quick Start

1. Initialize global configuration

epunkine init

Creates ~/.config/epunkine/config.yaml and ~/.config/epunkine/health-policy.md.
An AI agent interviews you about your code quality preferences and generates a policy tailored to your answers.

2. Initialize repository configuration

cd /path/to/your-repo
epunkine init-repo

Creates .epunkine/config.yaml and .epunkine/health-policy.md.
The agent references your global policy and helps you define repository-specific additions or overrides.

3. Run a code audit

epunkine inspect

The following files are written under .epunkine/results/:

File	Contents
latest.json	Structured findings data (latest run)
report.md	Human-readable Markdown report (latest run)
dashboard-data.json	Data for the dashboard (latest run)
logs/<timestamp>.json	Per-run history log

4. View results in the dashboard

epunkine dashboard

Opens a browser with an interactive dashboard showing scores, findings, file statistics, and run history.

---

Command Reference

epunkine init

Initializes global configuration.

epunkine init

• Creates ~/.config/epunkine/config.yaml (select model provider interactively)
• Generates ~/.config/epunkine/health-policy.md through a conversation with the AI agent

epunkine init-repo

Initializes repository-specific configuration.

epunkine init-repo

• Creates .epunkine/config.yaml
• Generates .epunkine/health-policy.md through a conversation with the AI agent
• References the global policy; you can define repository-specific additions or overrides

epunkine inspect

Runs a full code audit on the repository.

epunkine inspect

• Scans files according to the scan settings in config.yaml
• The AI agent reads the code and evaluates it against health-policy.md
• Outputs a report to .epunkine/results/

epunkine ci

Audit command designed for CI environments. Exits with a non-zero code when findings exceed the configured severity threshold.

epunkine ci [options]

Option	Default	Description
--fail-on <severity>	high	Exit with code 1 if findings at or above this severity exist
--output <format>	text	Output format: text or json
--report-dir <path>	.epunkine/reports	Directory to write report files

Severity levels (highest to lowest): high › medium › low › info

# Fail on high or above (default)
epunkine ci

# Fail on medium or above
epunkine ci --fail-on medium

# Output in JSON format
epunkine ci --output json

# Custom report directory
epunkine ci --report-dir ./reports

epunkine dashboard

Starts a local dashboard server.

epunkine dashboard [options]

Option	Default	Description
--port <number>	3761	Port number
--data-dir <path>	.epunkine/results	Data directory

Note: Run epunkine inspect first to generate dashboard-data.json.

The dashboard has six tabs:

• Overview — Score, findings summary, and per-category breakdown
• Findings — Findings list filterable by severity and category
• Files — Statistics for scanned files (line count, TODO/FIXME counts)
• Policy — Contents of the currently active health-policy.md
• Runs — Past inspect run history
• Trend — Score trend graph over time

You can also trigger an inspect run directly from the Run Inspect button; progress is streamed to the browser in real time.

---

Configuration

epunkine merges two levels of configuration.

File	Scope	Priority
~/.config/epunkine/config.yaml	Global (all repositories)	Lower
.epunkine/config.yaml	Repository-specific	Higher (overrides global)

config.yaml

model:
  provider: bedrock          # bedrock | openai
  name: us.anthropic.claude-sonnet-4-20250514-v1:0

scan:
  include:
    - src
  exclude:
    - node_modules
    - dist
    - build
    - .git
    - .epunkine

ci:
  fail_on: high              # high | medium | low | info
  warn_on: medium

dashboard:
  port: 3761

Merge behaviour

• Repository config.yaml overrides the global configuration property-by-property (shallow merge on nested objects)
• If neither file exists, built-in defaults are used

.epunkine/ directory layout

.epunkine/
├── config.yaml          # Repository-specific configuration
├── health-policy.md     # Repository-specific health policy
└── results/             # Generated by epunkine inspect (exclude from git)
    ├── latest.json
    ├── report.md
    ├── dashboard-data.json
    └── logs/
        └── <timestamp>.json

Recommended .gitignore

# Exclude generated results; keep config and policy
.epunkine/results/

Commit .epunkine/config.yaml and .epunkine/health-policy.md so that CI uses the same settings as local development.

git add .epunkine/config.yaml .epunkine/health-policy.md
git commit -m "chore: add epunkine config and policy"

CI note: epunkine ci evaluates findings directly without reading .epunkine/results/, so CI works correctly even when results are not committed.

---

health-policy.md

health-policy.md is the heart of epunkine. The AI agent reads this file to decide what counts as healthy or unhealthy code in your project.

Policy priority

1. .epunkine/health-policy.md (repository-specific)
2. ~/.config/epunkine/health-policy.md (global)
3. When both exist, they are combined — global as the base, repository-specific as additions or overrides

Writing a policy

Write in plain natural language. Any format the LLM can understand works.

# Health Policy

## File size
Split files that exceed 300 lines.
Auto-generated files and configuration files are exceptions.

## Tests
All functions containing business logic must have unit tests.
Coverage target: 80% or above.

## Duplication
Consolidate logic that appears in three or more places.
Avoid over-abstraction — readability matters more than DRY.

---

GitHub Actions

Basic CI workflow

name: epunkine CI

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  epunkine:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # Required for OIDC (Bedrock)
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install epunkine
        run: npm install -g @ken11/code-epunkine

      - name: Configure AWS credentials (Bedrock)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - name: Run epunkine CI
        run: epunkine ci --fail-on high --output json --report-dir ./epunkine-reports

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: epunkine-report
          path: ./epunkine-reports/

Using OpenAI

      - name: Run epunkine CI
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: epunkine ci --fail-on high

---

Model Providers

Amazon Bedrock (recommended)

model:
  provider: bedrock
  name: us.anthropic.claude-sonnet-4-20250514-v1:0

All standard AWS authentication methods are supported:

• IAM role (EC2 / ECS / Lambda / GitHub Actions OIDC)
• Environment variables (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
• AWS CLI profile (~/.aws/credentials)

OpenAI

model:
  provider: openai
  name: gpt-4o

Set the OPENAI_API_KEY environment variable:

export OPENAI_API_KEY=sk-...
epunkine inspect

⚠️ Anthropic Direct API

The Anthropic Direct API (provider: anthropic) is not currently supported by the Strands Agents TypeScript SDK used internally.
To use Claude models, choose provider: bedrock.

---

License

MIT License — see LICENSE for details.