 ___       _             _   ____
|_ _|_ __ | |_ ___ _ __ | |_|  _ \ _   _ _ __
 | || '_ \| __/ _ \ '_ \| __| |_) | | | | '_ \
 | || | | | ||  __/ | | | |_|  _ <| |_| | | | |
|___|_| |_|\__\___|_| |_|\__|_| \_\\__,_|_| |_|

The Universal Creative Agent Runtime

Describe outcomes, not tools. Intent-driven AI image generation.

Installation • Quick Start • Documentation • Providers • Contributing

Why IntentRun?

Traditional AI image generation requires you to:

Choose specific providers and models
Understand API parameters
Manage different authentication methods
Handle rate limits and errors manually
Lose track of what worked and what didn't

IntentRun introduces intent-driven execution:

Intent → Strategy → Capability Graph → Execution → Snapshot

You describe what you want. The system determines how to achieve it.

Features

Intent-Driven - Describe goals, not tools. Say "product photography for a watch" instead of "call DALL-E with these parameters"
Provider-Agnostic - Same intents work across Freepik, OpenAI, Replicate, and more
Reproducible - Every execution produces a snapshot. Replay, share, and audit with confidence
Agent-Ready - Designed for AI agents as much as humans. Deterministic execution infrastructure
Resilient - Built-in retry, circuit breakers, and rate limiting

Installation

npm install -g intentrun

Or use directly with npx:

npx intentrun "A serene mountain lake at sunset"

Quick Start

1. Set up a provider

export FREEPIK_API_KEY="your-api-key"
# or
export OPENAI_API_KEY="your-api-key"

2. Generate an image

intentrun "A serene mountain lake at sunset"

3. Use an intent file for more control

Create intent.json:

{
  "schema_version": "intent.v1",
  "domain": "visual",
  "goal": "Professional product photography for a luxury watch",
  "constraints": {
    "quality": "premium"
  }
}

Then execute:

intentrun execute intent.json

CLI Commands

Command	Description
`intentrun "<prompt>"`	Quick generation from a text prompt
`intentrun execute <intent>`	Execute an intent file
`intentrun plan <intent>`	Preview execution plan without running
`intentrun estimate <intent>`	Get cost and time estimates
`intentrun strategies <intent>`	View available strategies
`intentrun snapshot list`	List saved snapshots
`intentrun snapshot inspect <id>`	View snapshot details
`intentrun snapshot replay <id>`	Re-execute from snapshot
`intentrun providers list`	List available providers
`intentrun providers status`	Check provider configuration
`intentrun health status`	Show current health status
`intentrun health watch`	Real-time health monitoring
`intentrun health circuits`	Show circuit breaker status
`intentrun health rate-limits`	Show rate limiter status

Examples

# Quick generation
intentrun "Minimalist desk setup with laptop"

# Preview what will happen
intentrun plan intent.json

# Check costs first
intentrun estimate intent.json

# Execute with specific provider
intentrun execute intent.json --provider openai

# Dry run (plan but don't execute)
intentrun execute intent.json --dry-run

# JSON output for scripts
intentrun execute intent.json --json

# List recent snapshots
intentrun snapshot list --limit 10

# Replay a successful generation
intentrun snapshot replay snap_abc123 --mode exact

Intent Schema

Intents describe what you want, not how to achieve it:

{
  "schema_version": "intent.v1",
  "domain": "visual",
  "goal": "Social media content pack for coffee brand launch",
  "output": {
    "type": "pack",
    "count": 4,
    "aspect_ratios": ["1:1", "16:9", "9:16"]
  },
  "preferences": {
    "style_tags": ["minimalist", "warm_tones", "lifestyle"]
  },
  "constraints": {
    "quality": "premium",
    "budget_level": "medium"
  }
}

Required Fields

Field	Description
`schema_version`	Always `"intent.v1"`
`domain`	Always `"visual"` for image generation
`goal`	Natural language description of what you want

Optional Fields

Field	Description
`output`	Output specifications (type, count, formats, aspect ratios)
`preferences`	Style preferences (tags, composition, color palette)
`constraints`	Quality, budget, and speed constraints

Providers

IntentRun supports multiple AI image generation providers:

Provider	Capabilities	Environment Variable
Freepik	generate_image	`FREEPIK_API_KEY`
OpenAI	generate_image, edit_image	`OPENAI_API_KEY`
Replicate	generate_image, upscale	`REPLICATE_API_TOKEN`

Check provider status:

intentrun providers status

Configure a provider:

intentrun providers configure freepik

Health Monitoring

Monitor provider health, circuit breakers, and rate limits in real-time.

Quick Health Check

# Check current system health
intentrun health status

# View detailed provider information
intentrun health status --detailed

# Get JSON output for scripts
intentrun health status --json

Example Output:

● System Health: HEALTHY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Providers: 3
  Healthy:   2
  Degraded:  1
  Unhealthy: 0
  Unknown:   0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Provider Status:

  ● freepik
      ✓ CLOSED | Success: 95.2% | Latency: 1247ms
  ● openai
      ✓ CLOSED | Success: 98.7% | Latency: 892ms
  ● stability
      ◐ HALF_OPEN | Success: 78.3% | Latency: 2341ms

Real-Time Monitoring

# Watch health metrics in real-time
intentrun health watch

# Custom refresh interval (default: 5 seconds)
intentrun health watch --interval 10

# Table format for easier reading
intentrun health watch --format table

Circuit Breakers

Check circuit breaker status to understand provider availability:

# View all circuit breakers
intentrun health circuits

# Detailed circuit information
intentrun health circuits --detailed

# JSON output
intentrun health circuits --json

What are circuit breakers?

Circuit breakers prevent cascading failures by temporarily blocking requests to failing providers. They have three states:

CLOSED (✓): Provider is healthy, requests flow normally
HALF_OPEN (◐): Provider recovering, testing with limited requests
OPEN (✗): Provider is failing, requests are blocked

Rate Limits

Monitor API rate limit usage and capacity:

# Check rate limiter status
intentrun health rate-limits

# Detailed rate limit information
intentrun health rate-limits --detailed

# Table format
intentrun health rate-limits --format table

Example Output:

Rate Limiters
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 3
Rate Limited: 1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ freepik
      Capacity: ████████████████░░░░ 82.3%
      Available: 49/60

  ✓ openai
      Capacity: ███████████████████░ 95.0%
      Available: 57/60

  ✗ stability
      Capacity: ░░░░░░░░░░░░░░░░░░░░ 0.0%
      Available: 0/150
      Wait Time: 12.4s

Output Formats

All health commands support multiple output formats:

# Human-readable text (default)
intentrun health status --format text

# JSON for scripts and automation
intentrun health status --format json

# Table format for comparison
intentrun health status --format table

# Prometheus metrics for monitoring systems
intentrun health status --format prometheus

Prometheus Integration

Export health metrics in Prometheus format for monitoring:

# Generate Prometheus metrics
intentrun health status --format prometheus

# Example: Expose metrics via HTTP (requires simple wrapper)
while true; do
  intentrun health status --format prometheus > /tmp/metrics.txt
  sleep 15
done

Metrics Exported:

aiart_system_health - Overall system health (0-3)
aiart_provider_success_rate - Per-provider success rate (0-1)
aiart_provider_latency_ms - Average latency per provider
aiart_provider_requests_total - Total recent requests
aiart_provider_failures_total - Total recent failures

Troubleshooting

Provider showing as "degraded":

Check --detailed output for success rate and error patterns
View circuit breaker status: intentrun health circuits
Provider may be experiencing temporary issues

Rate limit warnings:

# Check which provider is rate limited
intentrun health rate-limits

# Wait time shown tells you when capacity will be available
# Example: "Wait Time: 12.4s" means requests can resume in ~12 seconds

Circuit breaker is OPEN:

Provider has failed multiple consecutive requests
Circuit will automatically transition to HALF_OPEN to test recovery
Check provider API status page for outages
Verify API key is valid: intentrun providers status

No providers tracked:

Health tracking begins after first execution
Run intentrun execute intent.json to populate metrics
Metrics are ephemeral (lost between CLI sessions)

Snapshots

Every execution creates a snapshot - a complete record for reproducibility:

# List snapshots
intentrun snapshot list

# Inspect a snapshot
intentrun snapshot inspect snap_abc123

# Validate integrity
intentrun snapshot validate snap_abc123

# Replay with exact same parameters
intentrun snapshot replay snap_abc123 --mode exact

# Compare two snapshots
intentrun snapshot diff snap_abc123 snap_def456

# Export for sharing (sanitized)
intentrun snapshot export snap_abc123

Claude Code Integration

Use IntentRun as a Claude Code skill for AI-assisted image generation.

One-Command Installation

npx intentrun-skill

This installs the skill for Claude Code on any platform (macOS, Linux, Windows).

Uninstall

npx intentrun-skill --uninstall

Usage with Claude

Once installed, simply ask Claude to generate images:

"Generate an image of a sunset over mountains"

"Create product photos for my headphones"

"/ai-art A cyberpunk city street at night"

Claude will use IntentRun to generate images with full snapshot support for reproducibility.

Documentation

Full documentation is available at intentrun.art:

Development

# Clone the repo
git clone https://github.com/oriiscovici/ai-art-cli.git
cd ai-art-cli

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Run docs site
npm run docs:dev

Contributing

Contributions are welcome! See our Contributing Guide for details.

Adding a New Provider

Implement the ProviderV2 interface in src/providers/
Register in src/providers/registry.ts
Add tests in tests/unit/providers/
Submit a PR!

See Building a Provider for details.

License

Apache License 2.0 - see LICENSE for details.

Credits

Built by Ori Iscovici with Claude.

Read the Docs →

If you find this useful, please star the repo!

Keywords

FAQs

What is intentrun?

Is intentrun popular?

Is intentrun well maintained?

Package last updated on 01 Mar 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

intentrun

IntentRun