AIvan

jq meets GPT — programmable AI workflows for your terminal.

Transform, query, and orchestrate data using natural language. AIvan turns plain English into validated DSL pipelines, executes them safely, and lets you iterate interactively.

npm install -g aivan-cli

30-Second Demo

# Transform data with natural language
aivan transform sales.csv "filter where revenue > 1000, sort by revenue descending, take top 10"

# Interactive chat mode — iterate on your data
aivan chat customers.json
# > filter out inactive users
# > group by region
# > show
# > save active-by-region.json

# See the DSL without executing
aivan transform --dry-run data.json "group by category, sum revenue, pivot by quarter"
# → filter(status='active') | group_by(category) | aggregate(revenue, 'sum') | pivot(quarter, revenue)

What It Does

AIvan translates natural language instructions into a validated DSL pipeline, then executes it. You get the speed of jq with the flexibility of an LLM.

"group by region, sum revenue"
        ↓ LLM
  group_by(region) | aggregate(revenue, 'sum')
        ↓ validate
  [type-checked DSL pipeline]
        ↓ execute
  [transformed data]

DSL Operators

11 composable operators that chain into pipelines:

| Operator | Example | |----------|---------| | filter | filter(country='US') filter(revenue>1000) | | sort | sort(revenue, 'desc') | | limit | limit(10) | | select | select(name, email, status) | | group_by | group_by(category) | | aggregate | aggregate(revenue, 'sum') aggregate(salary, 'avg') | | pivot | pivot(quarter, revenue) | | flatten | flatten() flatten(2) | | reshape | reshape(region, quarter, revenue) | | join | join(user_id, id) | | join_sources | join_sources(products.csv, product_id, id, 'left') |

Chain them: filter(region='EU') | select(product, revenue) | group_by(product) | aggregate(revenue, 'sum')

Commands

| Command | Purpose | |---------|---------| | aivan transform <file> "<instruction>" | One-shot data transformation | | aivan chat <file> | Interactive transformation with undo/redo | | aivan agent -t "<task>" | Multi-agent task orchestration | | aivan workflow <file> | Execute structured workflows | | aivan mcp | Start MCP server (21 tools) | | aivan voice | Voice-driven interaction |

Transform Modes

# Default: shows plan, asks for confirmation
aivan transform data.json "remove duplicates by email"

# Silent: no output, good for scripts
aivan transform --mode silent data.json "sort by date" -o sorted.json

# Show code: displays generated JavaScript before executing
aivan transform --mode show-code data.json "top 5 by revenue"

# REPL: interactive refinement loop
aivan transform --mode repl data.json

# Dry run: see DSL without executing
aivan transform --dry-run data.json "filter active users"

Agent Orchestration

# Single task with multiple agents
aivan agent -t "analyze this repo for tech debt" -a 3

# Batch parallel tasks
aivan agent -b "analyze auth flow, document API, optimize queries"

# Capability-based routing
aivan agent --strategy capability-match -t "review security posture"

Built-in Patterns

5 reusable execution patterns for common workflows:

aivan pattern list
aivan pattern run coding-implement "add rate limiting to the API"
aivan pattern run repair-bug "users can't log in after password reset"
aivan pattern run review-risk-scan
aivan pattern run analysis-repo

LLM Providers

Works with any major provider. Switch with --provider:

aivan transform --provider claude data.json "summarize by category"
aivan transform --provider gemini data.json "find anomalies"
aivan transform --provider openai data.json "clean and normalize"
aivan transform --provider local data.json "filter duplicates"

Configure providers:

aivan auth login          # OAuth PKCE flow
aivan setup               # Interactive first-run wizard

Security

Every transformation runs through a security pipeline:

• confirm (default) — shows plan, asks before executing
• trust-confirm — trusts file reads, confirms writes
• sandbox — executes in isolated worker_threads + vm context
• unrestricted — full access (use with caution)

aivan transform --security sandbox untrusted-data.json "parse and clean"

Architecture

User ─→ CLI Parser ─→ LLM Adapter ─→ DSL Validator ─→ Executor
                          │                                │
                    ┌─────┴─────┐                    ┌─────┴─────┐
                    │ Anthropic │                    │  Security  │
                    │  Gemini   │                    │  Sandbox   │
                    │  OpenAI   │                    │  Pipeline  │
                    │   Local   │                    └───────────┘
                    └───────────┘

• 14 commands across CLI, MCP, and voice surfaces
• 4 LLM adapters with streaming support
• 11 DSL operators with type validation
• 21 MCP tools for Claude integration
• 5 built-in patterns for structured workflows
• Kernel sandbox with worker_threads isolation

Development

git clone https://github.com/KeGolk/AIvan.git
cd AIvan
npm install
npm run build
npm test          # 2237 tests

Documentation

• Architecture
• Repository Map
• Plugin Development
• Contributing
• Changelog

License

See LICENSE.