How-to guides on ajq — semantic jq

Install ajq

Mon, 01 Jan 0001 00:00:00 +0000

ajq is a single Go binary. Pure jq queries work immediately after the binary is on your PATH. Semantic queries need an explicitly selected backend such as mock, local, ollama, openai, openrouter, or --cloud.

Install with the script

The install script downloads the matching release archive for your OS/architecture, verifies it against checksums.txt, and installs without sudo into ~/.local/bin (or $AJQ_INSTALL_DIR).

curl -fsSL https://raw.githubusercontent.com/ricardocabral/ajq/main/scripts/install.sh | sh

Pin a version or install directory if needed:

Make ajq available to a coding agent

Mon, 01 Jan 0001 00:00:00 +0000

Use this guide when a team wants its coding agents to consider ajq before writing a bespoke JSON-processing script. It assumes ajq is installed for the environment where the agent runs and that the team already has a project-instruction mechanism its agents read.

1. Install ajq where the agent can execute it

Install ajq in the same execution environment as the coding agent, then verify that the binary is visible on that environment’s PATH:

Process an NDJSON stream

Mon, 01 Jan 0001 00:00:00 +0000

ajq auto-detects input framing. The common shapes:

Single JSON value

A single top-level JSON value is processed as one input frame:

printf '{"a":1}\n' | ajq -c '.a + 1'
# 2

NDJSON / JSON Lines

A stream of top-level JSON values (one per line, or concatenated) is processed one frame at a time — each value flows through the query independently, and results are emitted as they’re produced:

printf '{"a":1}\n{"a":2}\n' | ajq -c '.a, (.a + 10)'
# 1
# 11
# 2
# 12

There’s no whole-stream buffering in this mode, so it handles inputs larger than memory.

Filter JSON by meaning

Mon, 01 Jan 0001 00:00:00 +0000

Use this when exact string matching is too brittle: support tickets that say the same thing in different words, log messages that imply the same failure, or records where the field name is known but the wording is messy.

ajq keeps the surrounding jq pipeline deterministic. Only the explicit semantic predicate (=~, !~, or sem_match) asks a backend for a judgement.

Try the query with no network

The mock backend is deterministic and in-process, so it needs no model, network, or API key. It is useful for checking the jq shape before paying for model calls:

Use ajq with other data formats

Mon, 01 Jan 0001 00:00:00 +0000

ajq’s core input modes stay small on purpose: JSON, NDJSON, raw strings, and null input. When the source data is another format, put a format adapter before ajq and let ajq work on the JSON it emits.

This keeps pure jq-compatible ajq pipelines deterministic while still letting you use the existing jq ecosystem around it. Tools such as jc, yq/xq, and fq are commonly used alongside jq for this kind of conversion.

Write a semantic filter

Mon, 01 Jan 0001 00:00:00 +0000

Use a semantic filter when literal matching with test() or == is too brittle. The examples below use --backend mock so you can verify the command shape without a model or API key; switch to --backend local, --cloud, or another backend for real judgement.

Fuzzy match with `=~`

The =~ operator asks the backend whether a value matches a description. Use it inside select:

printf '[{"id":1,"feedback":"urgent"},{"id":2,"feedback":"other"}]' \
 | ajq --backend mock -c '.[] | select(.feedback =~ "urgent") | .id'

Output with the mock backend:

Classify JSON and NDJSON streams

Mon, 01 Jan 0001 00:00:00 +0000

Use sem_classify when each record needs one label from a small list: support route, incident type, moderation bucket, or review theme. The output is bounded to the labels you write in the query, which makes it safer for downstream jq and shell pipelines than free text generation.

Classify a JSON array with no network

Start with --backend mock to validate the jq expression without a model, provider, or API key:

Estimate model calls before running

Mon, 01 Jan 0001 00:00:00 +0000

Semantic queries cost one backend judgement per distinct value they judge. Use --explain with representative input to estimate that number before you run a paid or slow backend.

Run `--explain` with real input

Pipe a sample of your data into --explain. ajq runs a deterministic mock harvest over the input to estimate work — it never contacts a provider or local model:

printf '[{"msg":"urgent"},{"msg":"urgent"},{"msg":"other"}]' \
 | ajq --explain '.[] | select(.msg =~ "urgent") | .msg'

Read the estimate block

estimates:
 estimate_status: available
 static_call_sites: 1
 input_frames: 1
 harvested_judgements: 3
 post_dedup_judgements: 2
 mock_judge_batches: 1

The fields you’ll budget against:

Use ajq safely from coding agents

Mon, 01 Jan 0001 00:00:00 +0000

Coding agents often discover ajq while trying to answer a concrete data-cleaning question: “find the records that mean X” or “route these JSON lines into labels”. Use this workflow when an agent, script, or CI job needs semantic matching while keeping the jq parts deterministic and reviewable.

1. Keep ordinary jq deterministic

First write the structural jq pipeline without semantic calls. This step should not need a backend:

printf '[{"id":1,"msg":"refund requested"},{"id":2,"msg":"profile updated"}]' \
 | ajq -c '.[] | {id, msg}'

Only add semantic operators once the field selection and output shape are correct.

Use cloud backends

Mon, 01 Jan 0001 00:00:00 +0000

Use a cloud backend when you want hosted inference instead of the local llama-server backend. Each provider needs an API key in the environment; ajq does not read API keys from config.toml.

Use Anthropic Claude

Export an Anthropic API key:
```
export ANTHROPIC_API_KEY="sk-ant-..."
```
Run a semantic query with --cloud:
```
printf '{"msg":"urgent billing issue"}' \
 | ajq --cloud --model haiku '.msg =~ "urgent"'
```
--cloud is the same as --backend anthropic. If you omit --model, ajq uses claude-haiku-4-5. The shipped aliases are haiku, sonnet, and opus.

Control semantic costs

Mon, 01 Jan 0001 00:00:00 +0000

Use this workflow before running semantic queries on a paid backend.

1. Estimate calls with `--explain`

Run the query with representative input and --explain:

printf '[{"msg":"urgent"},{"msg":"other"}]' \
 | ajq --explain '.[] | select(.msg =~ "urgent") | .msg'

Read post_dedup_judgements in the estimate block:

estimates:
 estimate_status: available
 static_call_sites: 1
 input_frames: 1
 harvested_judgements: 2
 post_dedup_judgements: 2

That number is the count to budget against. Repeated values are deduplicated before the backend is called.

Install the ajq coding-agent skill

Mon, 01 Jan 0001 00:00:00 +0000

Install the ajq skill when an agent should route semantic JSON or NDJSON filtering and bounded classification work to ajq. Install ajq itself first so the skill can run its safe discovery and mock checks.

Install for Codex

Add the public ajq marketplace and install its plugin:

codex plugin marketplace add ricardocabral/ajq
codex plugin add ajq@ajq

For a reproducible environment, pin the marketplace to an ajq release tag that contains this plugin. Replace vX.Y.Z with that release tag:

Manage the judgement cache

Mon, 01 Jan 0001 00:00:00 +0000

ajq stores successful semantic judgements on disk so repeated runs over the same op/spec/model/value identity can skip backend calls.

See where the cache lives

Run:

ajq cache status

Example output:

location: /Users/you/Library/Caches/ajq/judgements
entries: 0
bytes: 0

Set AJQ_CACHE_DIR when you want an isolated cache for a project or test:

AJQ_CACHE_DIR="$PWD/.ajq-cache" ajq cache status

Inspect cache state from an agent

Use the versioned JSON probe instead of parsing the human table-like output:

Configure defaults

Mon, 01 Jan 0001 00:00:00 +0000

Use a config file when you do not want to repeat the same semantic-backend flags on every command.

1. Create the config file

ajq reads this path by default:

${XDG_CONFIG_HOME:-~/.config}/ajq/config.toml

Create the directory and file:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/ajq"
cat > "${XDG_CONFIG_HOME:-$HOME/.config}/ajq/config.toml" <<'EOF'
backend = "mock"
max_calls = 25
no_cache = false
EOF

For a one-off location, set AJQ_CONFIG to an explicit file path.

2. Add semantic defaults

Recognized keys are:

backend = "local" # mock, local, ollama, openai, openrouter, anthropic
model = "qwen2.5-1.5b"
base_url = "http://127.0.0.1:8081"
max_calls = 100 # 0 = unlimited
no_cache = false

For example, to default to the deterministic mock backend with a small call cap:

Use a larger local model

Mon, 01 Jan 0001 00:00:00 +0000

The local backend defaults to qwen2.5-1.5b. Use ajq models when you want one of the larger shipped catalog models.

1. List catalog models

Run:

ajq models list

Example output before any downloads:

NAME ACTIVE INSTALLED SIZE RAM
qwen2.5-1.5b * no 1.2GiB ~4 GiB RAM
qwen2.5-3b no 2.0GiB ~6 GiB RAM
qwen3-4b no 2.3GiB ~8 GiB RAM

ACTIVE shows the model selected by config/env/defaults. INSTALLED shows whether the GGUF file exists in the ajq cache.

How-to guides on ajq — semantic jq

Install ajq

Install with the script

Make ajq available to a coding agent

1. Install ajq where the agent can execute it

Process an NDJSON stream

Single JSON value

NDJSON / JSON Lines

Filter JSON by meaning

Try the query with no network

Use ajq with other data formats

Write a semantic filter

Fuzzy match with =~

Classify JSON and NDJSON streams

Classify a JSON array with no network

Estimate model calls before running

Run --explain with real input

Read the estimate block

Use ajq safely from coding agents

1. Keep ordinary jq deterministic

Use cloud backends

Use Anthropic Claude

Control semantic costs

1. Estimate calls with --explain

Install the ajq coding-agent skill

Install for Codex

Manage the judgement cache

See where the cache lives

Inspect cache state from an agent

Configure defaults

1. Create the config file

2. Add semantic defaults

Use a larger local model

1. List catalog models

Fuzzy match with `=~`

Run `--explain` with real input

1. Estimate calls with `--explain`