ajq — semantic jq for JSON streams on ajq — semantic jq

Your first ajq pipeline

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

Run a real jq query through ajq. You’ll process a small JSON document, filter it, and confirm ajq matches jq for ordinary queries. No model, API key, or configuration.

Time: 5 minutes. Requires ajq on your PATH.

Step 1 — Get ajq

Use the checksum-verifying install script, a manual release download, or build from source (see Install ajq for details):

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

Check that it works:

ajq --version

This tutorial uses only deterministic jq, so there’s nothing else to set up — no model download, no API key.

Command-line interface

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

Synopsis

ajq [query] [flags]
ajq [command]

ajq reads input from standard input, applies one jq/semantic query, and writes results to standard output. Errors are written to standard error and produce a non-zero exit code.

query is a single argument. ajq desugars =~/!~ to sem_match(...), parses with gojq, and executes through the selected backend only when semantic operators require one.

Global flags

Flag	Short	Description
`--backend <name>`		Select the semantic backend: `anthropic`, `local`, `mock`, `ollama`, `openai`, or `openrouter`.
`--base-url <url>`		Set the HTTP base URL for backends that use one (`local`, `ollama`, `openai`, `openrouter`). For `openai`/`openrouter`, custom URLs must use HTTPS unless the host is loopback (`127.0.0.1`, `localhost`, or `[::1]`).
`--backend-concurrency <N>`		Maximum in-flight semantic requests in one provider batch. Default `1`; maximum `2` for OpenAI-compatible/Anthropic and `4` for Ollama. Must be positive when set.
`--cloud`		Select the Anthropic cloud backend; equivalent to `--backend anthropic`.
`--compact-output`	`-c`	Emit compact JSON output.
`--exit-status`	`-e`	Set the exit status based on the last output value.
`--explain`		Print the deterministic/semantic execution plan and exit without executing the query.
`--max-calls <N>`		Maximum post-dedup backend judgements before aborting; `0` means unlimited. Paid backends default to `100`; local/Ollama/mock default to unlimited.
`--model <id-or-alias>`		Semantic model id or alias for the selected backend.
`--no-cache`		Disable persistent on-disk judgement cache reads and writes for this run.
`--null-input`	`-n`	Use a single `null` input value instead of reading stdin.
`--raw-input`	`-R`	Read each input line as a string.
`--raw-output`	`-r`	Emit strings without JSON quoting.
`--stats`		Print run statistics to stderr after a successful run.
`--stream`		Run supported semantic queries inline for low-latency frame output instead of window batching. Does not change backend, model, cache identity, or `--max-calls`; pure-jq and planner-required inline queries retain their existing behavior.
`--window-bytes <N>`		Maximum source bytes per supported three-phase semantic window; positive integer, default `262144`. Has no execution effect for pure-jq or inline queries, including `--stream`.
`--version`	`-v`	Print the version and exit.
`--help`	`-h`	Print usage and exit.

See Input and output modes for framing and formatting details, Backends for backend-specific defaults, and Configuration for env/config precedence.

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:

Split execution

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

The observation

A real-world “AI data” query is mostly not fuzzy. Consider triaging support tickets:

cat data.json | ajq --backend local '.users[] | select(.feedback =~ "angry/frustrated") | .id'
 └────────┬───────┘ └────────────┬────────────┘ └┬┘
 deterministic path semantic predicate proj
 (pure gojq) (LLM, per value) (pure gojq)

Iterating the array, projecting .id, shaping the output — all of that is exact, mechanical work that jq already does perfectly. Only one operator, =~, needs judgement. The insight behind ajq is to treat that asymmetry as a first-class execution strategy: run the deterministic majority through a real jq engine, and call a model only for the fuzzy operators, on the smallest possible slices of data.

See how ajq plans a semantic query

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

Write a fuzzy match and inspect the plan. --explain does not contact a model, so you can inspect and cost any query before running it for real.

Requires ajq on your PATH (see Install ajq).

Step 1 — Write a fuzzy predicate

Ordinary jq can test text with test() or ==, but only literally. ajq adds a fuzzy operator, =~, that asks a model “does this value match this description?”. Here’s a stream of three messages, and a query that keeps the ones that read as urgent:

The determinism contract

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

ajq separates deterministic structure from semantic judgement.

The contract

The deterministic pipeline is byte-reproducible. Semantic judgements are structurally guaranteed, but their values are model- and cache-dependent.

Those are different promises.

Deterministic parts are byte-reproducible

Every part of a query that is not a semantic operator runs through pure gojq. Given the same input, it produces the same output bytes. There is no model, no sampling, and no network in that path.

Input and output modes

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

Input framing

ajq selects an input framing based on flags and the shape of stdin.

Mode	Flag	Behavior
Auto (default)	—	Auto-detects a single JSON value or a stream of top-level / NDJSON JSON values.
Null input	`-n`, `--null-input`	Ignores stdin; supplies one `null` input frame.
Raw input	`-R`, `--raw-input`	Reads each stdin line as a string, excluding the line terminator. `.` is the line.

In the default mode, a stream of multiple top-level JSON values (whitespace- or newline-separated, i.e. NDJSON/JSON Lines) is framed independently, with no whole-stream buffering. Pure-jq and planner-required interleaved semantic queries execute and emit one frame at a time. Supported three-phase semantic queries instead group complete frames into configured byte-budgeted windows, resolve each window once, then emit their frames in original order. The window retains only its frames plus bounded framing lookahead; a record larger than the budget forms one oversized window and is never split. This still allows inputs larger than available memory.

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:

Semantic functions

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

Semantic operators are registered as jq functions, so gojq parses them inside ordinary jq constructs. ajq adds only the =~ and !~ surface sugar before parsing.

Function vocabulary

Function	Form	Kind	Returns	Execution status
`sem_match`	`sem_match(value; "spec")`	predicate	boolean	Shipped
`sem_classify`	`sem_classify(value; "a"; "b"; …)`	bounded value	one label from the given labels	Shipped
`sem_extract`	`sem_extract(value; "what")`	unbounded value	string	Limited: supported only in gated/interleaved fallback contexts
`sem_score`	`sem_score(value; "spec")`	unbounded value	number	Limited: supported in `sort_by(...)` three-phase placeholder mode and in gated/interleaved fallback contexts
`sem_norm`	`sem_norm(value; "canonicalization spec")`	unbounded value	string	Limited: supported in `group_by(...)` three-phase placeholder mode and in gated/interleaved fallback contexts
`sem_redact`	`sem_redact(value; "redaction spec")`	unbounded value	string	Limited: supported only in gated/interleaved fallback contexts

The spec is a literal string in the query. Stream data is structurally fenced by the selected backend’s output constraints.

The three-phase executor

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

ajq runs supported semantic queries in three phases. For NDJSON and raw streams, the unit of work is a bounded window of complete frames rather than the complete stream.

The three phases

Phase 1 HARVEST pure gojq run; semantic ops in COLLECT mode gather every
 (op, spec, value) they observe. Permissive returns.
Phase 2 RESOLVE dedup collected values, consult/write the judgement cache,
 and resolve misses through the selected backend.
Phase 3 EXECUTE pure gojq run; semantic ops in LOOKUP mode return resolved
 values from cache. Deterministic given those cached values.

Phases 1 and 3 are pure gojq. Phase 2 is the isolated semantic boundary: it deduplicates, checks cache identity, and calls the backend only for misses.

--explain output

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

--explain prints a stable plan report and exits without executing the query. It does not contact a provider or local model.

Pure-jq report

ajq explain v1
query: ".users[] | select(.active) | .name"
execution: pure-jq deterministic
deterministic: yes
model_calls: 0
backend_calls: 0
byte_reproducible: yes
stdin: ignored

Field	Meaning
`query`	The query as parsed.
`execution`	`pure-jq deterministic` — no semantic call sites.
`deterministic`	`yes`.
`model_calls` / `backend_calls`	`0`.
`byte_reproducible`	`yes`.
`stdin`	`ignored` — pure-jq explain does not read input.

Semantic report

ajq explain v1
query: ".[] | select(sem_match(.msg; \"urgent\")) | .msg"
execution: semantic split plan
deterministic: no
model_calls: input-dependent
backend_calls: input-dependent
byte_reproducible: cache-dependent
stdin: harvested for estimates
planned_call_sites: 1
semantic_predicates: 1
semantic_values: 0
estimates:
 estimate_status: available
 static_call_sites: 1
 input_frames: 1
 harvested_judgements: 3
 post_dedup_judgements: 2
 mock_judge_batches: 1
 over_harvest_bound: post_dedup_judgements == mock distinct judgements; may be a safe superset of execute-needed judgements
subgraphs:
 deterministic: jq outside semantic call sites
 semantic: 1 planned call site(s)
semantic_plan:
 - call_id: 1
 op: "sem_match"
 kind: "predicate"
 value_expr: ".msg"
 specs: ["urgent"]
 source_range: 13:38
 gated: n/a
 execution: 3-phase
 subgraph: semantic

Header fields

Field	Meaning
`execution`	`semantic split plan` — the query has semantic call sites.
`deterministic`	`no`.
`model_calls` / `backend_calls`	`input-dependent`.
`byte_reproducible`	`cache-dependent` — deterministic phases are byte-reproducible; semantic answers depend on backend/cache state.
`stdin`	`harvested for estimates` when valid stdin is used for an estimate. With `--stream` on a supported plan, `not harvested`: inline execution has no cross-frame harvest estimate and explain leaves stdin untouched.
`planned_call_sites`	Total semantic call sites found in the static plan.
`semantic_predicates` / `semantic_values`	Counts of predicate-kind and value-kind ops.

`estimates` block

Present when valid stdin was supplied and the mock harvest path can estimate the query.

Architecture

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

ajq is a small pipeline of components.

Data flow

stdin → [Reader/Framer] → [Desugar] → [gojq.Parse] → [Planner] ──→ [Explain]
 │
 [3-phase Executor]
 ├─ gojq (deterministic)
 └─ Semantic Executor → [Backend iface]
 ├─ mock
 ├─ local daemon
 ├─ ollama
 ├─ openai / openrouter
 └─ anthropic cloud
[Grammar/Schema builder] → GBNF / json_schema ─────────────────────────────┘
stdout ← [Assembler / schema-invariance guard]

The components

Component	Responsibility
Reader / Framer	Stream framing: single JSON, NDJSON, and raw lines (awk-mode). Supported three-phase semantic input is grouped into complete-frame byte-budgeted windows; pure-jq and interleaved paths remain streaming.
Desugar	Rewrites `=~` / `!~` into `sem_match` calls with a jq-aware lexer.
Planner	Exhaustive AST walk that discovers every semantic call site → a `Plan` used for `--explain`, validation, and cost estimation.
Executor	Runs the plan in three phases (harvest / resolve / execute), with interleaved fallback for gated unbounded value ops.
Semantic Executor	Deduplicates judgements, consults the persistent judgement cache when enabled, builds each op’s prompt and schema, and records run stats.
Backend	Pluggable inference. Shipped backends: `mock`, `local` (llama-server daemon), `ollama`, `openai`, `openrouter`, and `anthropic`/`--cloud`.
Grammar / schema builder	Turns an op’s return type / enum into a JSON Schema and, for the local engine, GBNF grammar constraints.
Assembler	Reassembles the output stream and enforces schema invariance.

Windowed semantic execution

For supported three-phase semantic queries, the executor retains one complete-frame window at a time, harvests its semantic judgements, resolves deduplicated cache misses in one backend batch, then executes frames in source order. The default source-byte budget is 256 KiB and can be overridden with --window-bytes, AJQ_WINDOW_BYTES, or window_bytes in TOML. A record that exceeds the budget is a valid one-frame oversized window, so the budget is not a rejection limit. The executor does not retain the complete stream: it keeps the current window, one lookahead frame, and bounded framing buffers.

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.

Configuration

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

ajq resolves semantic-backend settings from flags, environment variables, a TOML config file, and backend defaults.

Precedence

Rank	Source	Notes
1	Command-line flags	`--backend`, `--model`, `--base-url`, `--backend-concurrency`, `--max-calls`, `--window-bytes`, and `--no-cache`.
2	Environment variables	`AJQ_BACKEND`, `AJQ_MODEL`, `AJQ_BASE_URL`, `AJQ_BACKEND_CONCURRENCY`, `AJQ_MAX_CALLS`, `AJQ_WINDOW_BYTES`.
3	TOML config	Default path or `AJQ_CONFIG`.
4	Backend defaults	For example, Anthropic’s default model and paid-backend call cap.

Flags override environment variables; environment variables override config values; config values override backend defaults.

Project status

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

ajq has shipped its deterministic jq spine, semantic planning and supported semantic execution, local inference, bounded-parallel local daemon transport, Phase 3 backend/cloud controls, first-run local asset provisioning, local model management, the persistent judgement cache, byte-budgeted semantic windows, an explicit low-latency semantic stream mode, and checksummed release archives with a no-sudo install script. Further streaming optimizations remain planned. The iterative-harvest experiment is an internal-only no-go prototype, not a shipped mode; default windowed execution is unchanged.

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.

Backends

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

Semantic operators require a backend. Pure jq queries do not construct a backend, spawn a daemon, or make network calls unless a semantic operator is present and a backend is selected by flags, environment, or config.

Backend summary

Backend	Select with	Model default / requirement	Base URL	Credentials	Default `max_calls`
`mock`	`--backend mock`	Built-in `ajq-default-model` identity	none	none	`0` (unlimited)
`local`	`--backend local`	`qwen2.5-1.5b` unless overridden	Managed loopback `http://127.0.0.1:8081`; explicit `--base-url` for user-trusted servers	managed bearer key (internal)	`0` (unlimited)
`ollama`	`--backend ollama`	Required `--model` / config / env	`OLLAMA_HOST` or `http://127.0.0.1:11434`	none	`0` (unlimited)
`openai`	`--backend openai`	Required `--model` / config / env	`https://api.openai.com/v1`	`OPENAI_API_KEY`	`100`
`openrouter`	`--backend openrouter`	Required `--model` / config / env	`https://openrouter.ai/api/v1`	`OPENROUTER_API_KEY`	`100`
`anthropic`	`--backend anthropic` or `--cloud`	`claude-haiku-4-5`; aliases `haiku`, `sonnet`, `opus`	provider default; no user base URL	`ANTHROPIC_API_KEY`	`100`

max_calls counts post-dedup backend judgements. 0 means unlimited. For a machine-readable static projection of these registered backends, use ajq capabilities --json; it does not resolve configured credentials or runtime asset state. In that projection Ollama has no default_base_url, because its runtime URL may come from OLLAMA_HOST before the documented loopback fallback.

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.

Iterative-harvest prototype evaluation

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

Decision: no-go for productionization

The iterative-harvest implementation is an internal test and benchmark prototype. It is not a CLI mode, is not selected by default, and must not be enabled for users. The existing three-phase-windowed executor remains the default and unsupported query shapes continue to use their existing windowed or planner-required interleaved fallback.

This is a no-go even though the pruning workload clears its judgement-saving target. A reachable error case found during characterization has different behavior from the current windowed executor: after an earlier gate rejects a value, a backend result/schema/transport error for that pruned descendant is dispatched and returned by permissive windowed harvest, but is intentionally not dispatched by iterative harvest or interleaved execution. That changes the reachable error, cache, and exit contract. Reducing calls by dispatching the unreachable descendant would defeat the prototype’s purpose. Until a separate design resolves that semantic/error boundary, the required current-window parity gate is not met.

ajq — semantic jq for JSON streams on ajq — semantic jq

Your first ajq pipeline

Step 1 — Get ajq

Command-line interface

Synopsis

Global flags

Install ajq

Install with the script

Split execution

The observation

See how ajq plans a semantic query

Step 1 — Write a fuzzy predicate

The determinism contract

The contract

Deterministic parts are byte-reproducible

Input and output modes

Input framing

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 =~

Semantic functions

Function vocabulary

The three-phase executor

The three phases

--explain output

Pure-jq report

Semantic report

Header fields

estimates block

Architecture

Data flow

The components

Windowed semantic execution

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

Configuration

Precedence

Project status

Use cloud backends

Use Anthropic Claude

Backends

Backend summary

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

Iterative-harvest prototype evaluation

Decision: no-go for productionization

Fuzzy match with `=~`

`estimates` block

Run `--explain` with real input

1. Estimate calls with `--explain`