AI assistant

The AI assistant fixes broken queries for you — it sees what went wrong, understands your data shape, and offers working alternatives you apply with a single keystroke.

Without AI With AI

You get a syntax error. Now you're searching the web, reading jq docs, trying variations one by one.

$ jiq data.json Query: .users | group_by .role ^^^^^^^^^^^^^^^^^^^^^^^^^^ Syntax Error # Tab to browser... # Search: "jq group_by syntax" # Read docs... try group_by(.role)... no wait... # Try 5 more variations... # 10 minutes later: finally works

Press Ctrl+A. The AI sees your query, the error, and your data — then offers working fixes.

Query: .users | group_by .role Syntax Error # Press Ctrl+A... AI Suggestions: 1. .users | group_by(.role) 2. [.users[] | group_by(.role)] 3. .users | group_by(.role) | map({key: .[0].role, val: .}) # Press Alt+1 — done. 3 seconds.

How it works

Error appears

Press Ctrl+A

AI analyzes context

Pick a suggestion

Applied

The AI sends your current query, the error message, and a sample of your JSON to the configured provider. It returns 2-5 suggestions ranked by relevance. The entire round trip typically takes 1-3 seconds.

Get a fix for a failing query

Write a query that produces an error (the Syntax Error banner appears).
Press Ctrl+A to open the AI popup.
Wait for suggestions to appear (a loading indicator shows progress).
Press Alt+1 through Alt+5 to apply a suggestion directly — or use Alt+j/Alt+k to navigate, then Enter to apply.

AI suggestions popup

Query: .items | map(select(.price > 100) | .name, .price)

Syntax Error: unexpected ',' at line 1

AI Suggestions:

1. .items[] | select(.price > 100) | {name, price}

2. [.items[] | select(.price > 100) | {name: .name, price: .price}]

3. .items | map(select(.price > 100) | {name, price})

Alt+1..3 Apply | Alt+j/k Navigate | Enter Apply selected

Ask for help with a working query

The AI assistant is not limited to fixing errors. Even when your query works, press Ctrl+A and the AI may suggest improvements — a more concise form, a different approach, or natural language interpretation of what you typed.

Popup state	What it means
A numbered list of suggestions	The AI returned 2-5 jq queries you can apply.
No suggestions	The AI ran successfully but had nothing useful to add for this query (common for the bare `.` identity query). This is normal, not an error.
Could not parse AI response	The provider returned a response jiq could not read as suggestions. Re-run with `--debug` and check `/tmp/jiq-debug.log` to see the raw response.

Navigate and dismiss suggestions

Action	Key
Move between suggestions	Alt+Up / Alt+Down or Alt+j / Alt+k
Apply the highlighted suggestion	Enter
Apply suggestion N directly	Alt+1 through Alt+5
Close without applying	Ctrl+A or Esc

Configure the AI provider

The AI assistant requires a provider configuration in ~/.config/jiq/config.toml. jiq supports Anthropic, OpenAI, Gemini, AWS Bedrock, and any OpenAI-compatible API.

[ai]
enabled = true
provider = "anthropic"    # "anthropic", "openai", "gemini", or "bedrock"
max_context_length = 100000  # characters of JSON context sent to AI (default 100k)

Anthropic

[ai.anthropic]
api_key = "sk-ant-..."
model = "claude-haiku-4-5-20251001"

OpenAI

[ai.openai]
api_key = "sk-proj-..."
model = "gpt-4o-mini"

Gemini

[ai.gemini]
api_key = "AIza..."
model = "gemini-3-flash-preview"

AWS Bedrock

[ai.bedrock]
region = "us-east-1"
model = "global.anthropic.claude-haiku-4-5-20251001-v1:0"
profile = "default"  # optional: uses default credential chain if omitted

OpenAI-compatible APIs (Ollama, LM Studio, x.ai)

Any API that follows the OpenAI chat completions format works by setting provider = "openai" with a custom base_url:

# Ollama (local)
[ai.openai]
base_url = "http://localhost:11434/v1"
model = "llama3"

# LM Studio (local)
[ai.openai]
base_url = "http://localhost:1234/v1"
model = "local-model"

# x.ai Grok
[ai.openai]
api_key = "your-xai-api-key"
base_url = "https://api.x.ai/v1"
model = "grok-4-fast-non-reasoning"

For local providers that don’t require authentication, omit the api_key field entirely.

Tuning context size

The max_context_length setting controls how much of your JSON data is sent to the AI. Larger values give the AI more context for better suggestions but increase token usage and cost. Smaller values reduce cost and latency.

[ai]
max_context_length = 50000   # send less context (faster, cheaper)
max_context_length = 200000  # send more context (better suggestions for large files)

For sensitive data, a local model via Ollama or LM Studio keeps everything on your machine.

All keys

Key	Action
`Ctrl+A`	Toggle AI assistant popup
`Alt+1`..`Alt+5`	Apply suggestion 1-5 directly
`Alt+Up` / `Alt+Down`	Navigate suggestions
`Alt+j` / `Alt+k`	Navigate suggestions (vim style)
`Enter`	Apply selected suggestion
`Ctrl+A` / `Esc`	Close popup