intentrun

v1.0.2

Published

23 days ago

Intent-driven creative execution runtime. Describe outcomes, not tools.

Downloads

273

IntentRun

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

The Universal Creative Agent Runtime

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

Installation • Quick Start • Documentation • License

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 | | intentrun health monitoring | Monitor monitoring systems health |

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

Health Monitoring

Monitor system health, provider status, and rate limits in real-time.

Quick Health Check

# Check current system health
intentrun health status

# Monitor monitoring systems themselves
intentrun health monitoring

# 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

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

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:

Support

License

This software is provided under a proprietary license. See LICENSE for details.

This is not open source software. The source code is not available for modification or redistribution.

Credits

Built by Ori Iscovici with Claude.

Read the Docs →