Skip to main content

​
Install ap-query

The fastest way to install ap-query is using the install script: 
curl -fsSL https://raw.githubusercontent.com/jerrinot/ap-query/master/install.sh | sh
This downloads the latest release binary for your platform and installs it to /usr/local/bin/ap-query (or ~/.local/bin/ap-query if you don’t have sudo access).
After installation, verify it works:
ap-query version

​
Alternative installation methods

If you have Go 1.23+ installed:
go install github.com/jerrinot/ap-query@latest
The binary will be installed to $GOPATH/bin/ap-query (usually ~/go/bin/ap-query).
Download the latest release from GitHub Releases:
  1. Download the appropriate archive for your platform:
    • Linux x64: ap-query_linux_amd64.tar.gz
    • Linux ARM64: ap-query_linux_arm64.tar.gz
    • macOS: ap-query_darwin_amd64.tar.gz or ap-query_darwin_arm64.tar.gz
  2. Extract and move to your PATH: 
    tar -xzf ap-query_*.tar.gz
sudo mv ap-query /usr/local/bin/

​
Install async-profiler

ap-query analyzes profiles created by async-profiler. You’ll need to install async-profiler to capture profiles.
1

Download async-profiler

The easiest way is to let ap-query init handle this automatically (see next section). Alternatively, download it manually:Linux:
wget https://github.com/async-profiler/async-profiler/releases/latest/download/async-profiler-3.0-linux-x64.tar.gz
tar -xzf async-profiler-3.0-linux-x64.tar.gz
sudo mv async-profiler-3.0-linux-x64 /opt/async-profiler
macOS:
wget https://github.com/async-profiler/async-profiler/releases/latest/download/async-profiler-3.0-macos.zip
unzip async-profiler-3.0-macos.zip
sudo mv async-profiler-3.0-macos /opt/async-profiler
2

Add to PATH

Add the bin directory to your PATH:
export PATH="/opt/async-profiler/bin:$PATH"
Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.
3

Verify installation

asprof --version
async-profiler requires Linux perf events or macOS DTrace. On Linux, you may need to adjust kernel settings:
# Allow non-root users to profile
sudo sysctl kernel.perf_event_paranoid=1
sudo sysctl kernel.kptr_restrict=0
See the async-profiler documentation for details.

​
Install agent skill

The agent skill teaches coding agents (Claude Code, Codex, etc.) how to profile Java applications and analyze results with ap-query.
1

Run ap-query init

Run the init command to install the agent skill:
# Global installation (recommended)
ap-query init
This command:
  • Auto-detects your asprof installation (or offers to download it)
  • Detects which agents you use (Claude Code, Codex)
  • Installs the skill to the appropriate directories
  • Embeds the exact paths to asprof and ap-query on your system
2

Verify skill installation

The skill will be installed to one or both of these locations:
  • Claude Code (global): ~/.claude/skills/jfr/SKILL.md
  • Codex (global): ~/.codex/skills/jfr/SKILL.md (or $CODEX_HOME/skills/jfr/SKILL.md)
Verify the skill file exists:
ls -l ~/.claude/skills/jfr/SKILL.md
3

Test with your agent

Ask your agent to profile something:
“Profile this Java program with async-profiler and analyze the result with ap-query. Start with hotspot triage.”
The agent should automatically use the skill to run the correct commands.

​
Installation modes

ap-query init supports two installation modes:

​
Advanced init options

​
--asprof PATH
string
Explicit path to the asprof binary. Skips auto-detection.
ap-query init --asprof /opt/async-profiler/bin/asprof
​
--project
boolean
Install to the current directory instead of home directory.
​
--force
boolean
Overwrite existing skill files.
​
--claude
boolean
Install only for Claude Code (creates .claude if needed).
​
--codex
boolean
Install only for Codex (creates .codex or .agents if needed).
​
--stdout
boolean
Print the rendered skill to stdout instead of installing. Useful for custom agents or debugging.

​
Updating ap-query

ap-query can self-update to the latest release: 
ap-query update
This command:
  1. Checks for the latest GitHub release
  2. Downloads and verifies the new binary
  3. Replaces the current binary atomically
  4. Auto-updates any globally installed agent skills
If you installed via go install, use go install github.com/jerrinot/ap-query@latest instead.

​
Next steps

Quickstart

Profile and analyze your first application

Agent Integration Guide

Learn how agents use the skill

Build docs developers (and LLMs) love

Get started for freeTalk to us