Skip to content

feat(agents): install jq in the Claude Code image - #750

Open
kaihackney-scale wants to merge 1 commit into
mainfrom
kai/claude-code-image-jq
Open

kaihackney-scale wants to merge 1 commit into
mainfrom
kai/claude-code-image-jq

Conversation

@kaihackney-scale

@kaihackney-scale kaihackney-scale commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

What

Install jq in the Claude Code agent image.

Why

When an MCP tool result is over Claude Code's token cap, the CLI writes it to a file under tool-results/ and tells the model how to read it:

Error: result (N characters) exceeds maximum allowed tokens. Output has been saved to …/tool-results/mcp-….txt.
Format: JSON with schema: {result: string}
Use jq to make structured queries (find a value, filter by field).

That text is the CLI's own, not the agent wrapper's (claude_bridge.py and the rest of the folder add nothing to it), and it suggests jq in several places, such as jq 'type, length, keys?' as a first probe. The image doesn't have jq, so in runs whose MCP tools return large results the model's first jq call fails with jq: command not found, and it falls back to reading the file in chunks with Python. That costs the run a wasted tool call and makes the agent work against what the CLI tells it.

jq is about 1 MB with its library on Debian slim, from the same apt-get layer that already installs poppler-utils.

Changes

  • Dockerfile: add jq to the apt install.
  • README.md: list jq among what the image gives the model's scripts.
  • test_image_contract.py: assert the image installs jq (and still poppler-utils).

Out of scope: install.sh (install/v1) uses the target's own tools, as it does for Python packages, so it doesn't add jq to a task container or VM host.

Testing

  • tst/unit/agents/claude_code/: 254 passed, 30 skipped (existing capability gates). The new test fails with jq taken out of the Dockerfile. ruff check is clean, and tst/unit/bundle/shipped_bundles_test.py passes.
  • End to end, real image builds: I built the image from main and from this branch (linux/arm64, Docker 29.9.2). Each container ran as the image's agent user in /app, the CLI's cwd, and was given a ~110 KB file in the CLI's spill format ({"result": "<JSON string>"}). The probe ran the jq queries the CLI's message suggests:
    • main: every jq call fails with jq: command not found.
    • this branch: jq-1.7; jq 'type, length, keys?' → "object" 1 ["result"]; one jq '.result | fromjson | …' call counts the records and filters them by field.
    • In both images the bundled CLI binary contains the "Use jq to make structured queries" hint, and pypdf and pdftotext are present.
  • Not run: a model-in-the-loop turn that triggers a real spill. The CLI's behaviour isn't changed here; only the tool it points at now exists.
Probe output, main vs this branch

main

## image: user=agent cwd=/app claude=2.1.322 (Claude Code)
## does this CLI build tell the model to use jq on spilled MCP results?
2
## spill file: 116969 bytes
## jq --version
/e2e/probe.sh: line 18: jq: command not found
## jq 'type, length, keys?'  (the CLI's suggested first probe)
/e2e/probe.sh: line 20: jq: command not found
## jq: count messages and pick alice's subjects in one call
/e2e/probe.sh: line 22: jq: command not found
/e2e/probe.sh: line 23: jq: command not found
## document tooling already in the image
pypdf 6.21.3
pdftotext version 25.03.0

this branch

## image: user=agent cwd=/app claude=2.1.322 (Claude Code)
## does this CLI build tell the model to use jq on spilled MCP results?
2
## spill file: 116969 bytes
## jq --version
jq-1.7
## jq 'type, length, keys?'  (the CLI's suggested first probe)
"object"
1
["result"]
## jq: count messages and pick alice's subjects in one call
200
Invoice ENG-0
Invoice ENG-7
Invoice ENG-14
Invoice ENG-21
Invoice ENG-28
## document tooling already in the image
pypdf 6.21.3
pdftotext version 25.03.0

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

This PR appears safe to merge.

Summary

Adds jq to the Claude Code image so the model can query large MCP results saved to files.

  • Claude Code's image now includes jq for querying saved MCP results.

Reviews (1) · Last reviewed commit: "feat(agents): install jq in the Claude C..." · Reviewed by Greptile

The CLI saves an MCP result over its token cap to a file and tells the
model to query it with jq, which the image didn't have.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kaihackney-scale
kaihackney-scale requested a review from a team as a code owner November 17, 2026 22:02

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant