Agent skill

Hardware Tuning

by chmonitor in chmonitor/chmonitor

Detect server cores/RAM/disk from system tables, then recommend ClickHouse settings sized to that hardware.

GPL-3.0Auto-check passedDatabases

Install Hardware Tuning

skills CLI
$ npx skills add chmonitor/chmonitor --skill hardware-tuning -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install chmonitor/chmonitor hardware-tuning --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/chmonitor/chmonitor.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/hardware-tuning .claude/skills/hardware-tuning && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
hardware-tuning
GitHub stars
299
Token cost
~2.1k tokens
SKILL.md length
777 words
Files
1
Skills in repo
53
Repo updated
First seen
Licence
GPL-3.0

At a glance

Detect server cores/RAM/disk from system tables, then recommend ClickHouse settings sized to that hardware.

  • Tasks that involve Data warehousing
  • SKILL.md covers Detect Hardware, Read Current Settings, Key Settings: Ratio-Based… and Disk Considerations, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Hardware Tuning is an agent skill from chmonitor/chmonitor. Detect server cores/RAM/disk from system tables, then recommend ClickHouse settings sized to that hardware.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases, covering Data warehousing. It works with ClickHouse. The repository describes itself as: Open-source operational advisor for ClickHouse — real-time monitoring plus AI-driven index/partition/materialized-view recommendations. The licence is GPL-3.0.

When your agent uses it

  • Tasks that involve Data warehousing

Example prompts

  • “/hardware-tuning”

What it can do on your machine

Read from SKILL.md and the folder at commit fc39ef0. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are sql).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Hardware Tuning loads about 2.1k tokens when it runs. Until then it costs about 31 tokens; SKILL.md has 777 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~31
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from chmonitor/chmonitor at commit fc39ef0, republished under its GPL-3.0 licence (© chmonitor). 777 words, ~2,106 tokens.

Download SKILL.mdSave it as .claude/skills/hardware-tuning/SKILL.md (or your agent's skills folder).
name
hardware-tuning
description
Detect server cores/RAM/disk from system tables, then recommend ClickHouse settings sized to that hardware.

Hardware Tuning

Load this skill when the user asks "what settings should I change given my server's hardware?" or similar. The workflow is always: detect first, recommend second. Never recommend a specific byte value as a universal truth — give ratios and explain the reasoning.

Detect Hardware

Metric names vary by ClickHouse version. Use broad ILIKE patterns and inspect what is actually returned before drawing conclusions.

sql
-- Step 1: Discover what CPU/memory metrics are available on this server
SELECT metric, value
FROM system.asynchronous_metrics
WHERE metric ILIKE '%CPU%'
   OR metric ILIKE '%Memory%'
   OR metric ILIKE '%core%'
ORDER BY metric

Key metrics to look for (names differ across versions):

What you needLikely metric names
Logical CPU coresCGroupMaxCPU, OSCPUVirtualTimeMicroseconds (indirect), check also system.metrics CPUUsage*
Total RAMOSMemoryTotal, CGroupMemoryLimit
Available RAMOSMemoryAvailable, OSMemoryFreeWithoutCache
Used RAMOSMemoryUsed, MemoryResident

If neither CGroupMaxCPU nor an obvious cores metric appears, fall back to counting CPU entries from /proc/cpuinfo via SELECT count() FROM system.asynchronous_metrics WHERE metric ILIKE '%CPU%User%' or ask the user directly. Do not fabricate a core count.

sql
-- Step 2: Disk layout — free space and total per disk
SELECT name, path, type,
       formatReadableSize(free_space)  AS free,
       formatReadableSize(total_space) AS total,
       round((1 - free_space / total_space) * 100, 1) AS used_pct
FROM system.disks
ORDER BY total_space DESC

Read Current Settings

Pull the most hardware-sensitive settings so you can compare current vs. recommended:

sql
SELECT name, value, changed, default AS default_value, description
FROM system.settings
WHERE name IN (
    'max_threads',
    'max_insert_threads',
    'max_memory_usage',
    'max_memory_usage_for_user',
    'max_server_memory_usage',
    'max_server_memory_usage_to_ram_ratio',
    'max_bytes_before_external_group_by',
    'max_bytes_before_external_sort',
    'max_bytes_before_external_join',
    'background_pool_size',
    'background_merge_pool_size',
    'background_fetches_pool_size',
    'mark_cache_size',
    'uncompressed_cache_size',
    'max_concurrent_queries',
    'max_connections'
)
ORDER BY name

Note: background_pool_size and background_merge_pool_size are server-level settings (set in config.xml or config.d/). They will appear in system.settings but changing them requires a server restart. Session-level settings take effect immediately with SET.

Key Settings: Ratio-Based Guidance

Use the detected hardware values from the queries above and apply these ratios. Replace <cores> and <RAM_bytes> with the actual numbers you found.

CPU-bound settings
SettingScopeGuidance
max_threadssession≈ number of logical cores. Default is auto (0). Only lower it if queries compete with each other at high concurrency.
max_insert_threadssession1–4 for normal inserts; up to half of cores for bulk loads.
background_pool_sizeserver (restart)16 is the default; for merge-heavy workloads raise toward cores / 2. Don't exceed cores.
background_merge_pool_sizeserver (restart)Same guidance as background_pool_size. Default 16.
max_concurrent_queriesserverStart at cores * 2. Lower if queries are large and memory-bound.
Memory-bound settings

Leave genuine headroom — never allocate 100 % of RAM to ClickHouse. The OS, kernel buffers, and other processes need room.

SettingScopeGuidance
max_server_memory_usageserverSet to 0 (auto) to use max_server_memory_usage_to_ram_ratio instead. If hardcoding: ≤ 80 % of OSMemoryTotal.
max_server_memory_usage_to_ram_ratioserverDefault 0.9; consider lowering to 0.8 on shared hosts or when running replicas with ZooKeeper on the same box.
max_memory_usagesessionPer-query cap. A common starting point is RAM × 0.3 for OLAP queries, but tune per workload.
max_memory_usage_for_usersessionPer-user sum cap. Useful when multiple users share the server; set to RAM × 0.5 as a starting point.
max_bytes_before_external_group_bysessionSpill threshold for GROUP BY. Typically half of max_memory_usage. If set to 0, spilling is disabled.
max_bytes_before_external_sortsessionSame pattern as external group by. Setting this too low causes unnecessary disk spilling; too high causes OOM.
max_bytes_before_external_joinsessionApplies to hash joins. Same ratio guidance.
Show full SKILL.md (340 more words)Show less
Cache settings (server-level, config.xml or <cache> section)

These affect how much RAM is reserved for ClickHouse's internal caches. Changing them requires restart.

SettingGuidance
mark_cache_sizeDefault 5 GiB. For servers with lots of RAM (≥ 64 GiB) and many columns, raise to 10–20 GiB. Do not exceed ≈ 10 % of RAM.
uncompressed_cache_sizeDefault 0 (disabled). Only enable if you have a read-heavy workload with repeated small queries on the same columns. Cap at ≈ 5–10 % of RAM.

Disk Considerations

After running the disk query above:

  • Single spinning disk: reduce background_pool_size and background_merge_pool_size to avoid I/O saturation during merges. Values of 4–8 are common.
  • NVMe / SSD array: defaults or higher pool sizes are fine.
  • Tiered storage (hot/cold): ensure the hot tier has enough free space for active merges (ClickHouse needs ≈ 2× the size of the parts being merged).
  • Disk nearly full (> 90 % used): inserts will stall. Investigate via system.parts and consider OPTIMIZE … FINAL or archiving old partitions before tuning anything else.

Caution

  • Change one setting at a time and measure before moving to the next.
  • Defaults are often correct. ClickHouse auto-detects cores and sets max_threads = 0 (auto). Only override when you have a concrete reason.
  • Server-level vs. session-level: background_pool_size, mark_cache_size, max_server_memory_usage, and max_concurrent_queries require editing config.xml (or a file in config.d/) and restarting the server. Session-level settings (max_threads, max_memory_usage, etc.) apply immediately with SET or in the query profile.
  • Replicated environments: changing server-level settings must be applied consistently to all replicas. Inconsistent pool sizes can cause one replica to fall behind on merges.
  • ClickHouse Keeper / ZooKeeper on the same host: the coordination process can consume significant RAM under load. Budget at least 4–8 GiB for it and reduce max_server_memory_usage_to_ram_ratio accordingly.

Verification

After applying changes, confirm they took effect and watch for regressions:

sql
-- Confirm the setting is now the value you set (session-level)
SELECT name, value, changed
FROM system.settings
WHERE name IN ('max_threads', 'max_memory_usage', 'max_bytes_before_external_group_by')

-- Watch for OOM or memory-allocation errors after a change
SELECT name, value AS error_count, last_error_time, last_error_message
FROM system.errors
WHERE name ILIKE '%Memory%' OR name ILIKE '%Alloc%'
ORDER BY last_error_time DESC
LIMIT 20

-- Monitor peak memory usage on currently running queries
SELECT query_id, user, memory_usage, peak_memory_usage,
       formatReadableSize(memory_usage)      AS mem,
       formatReadableSize(peak_memory_usage) AS peak_mem,
       elapsed,
       substring(query, 1, 120)              AS query
FROM system.processes
WHERE query NOT LIKE '%processes%'
ORDER BY peak_memory_usage DESC

If system.errors shows MEMORY_LIMIT_EXCEEDED spikes after a change, roll back that setting before adjusting others.

Cross-references

  • clickhouse-best-practices — production insert, cache, and connection-pool guidance
  • schema-design-advisor — part counts and merge behavior affect background pool sizing
  • troubleshooting — error-code-driven diagnosis including OOM and disk-full incidents
  • query-tuning-advisor — per-query memory and parallelism knobs once server settings are stable

© chmonitor, GPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/hardware-tuning of chmonitor/chmonitor.

Open the folder on GitHubat commit fc39ef0

Compare with similar skills

Hardware Tuning next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Hardware Tuning compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Hardware Tuning this skillchmonitor/chmonitor299—~2.1kAutomated safety check: PassGPL-3.0
Keeper Stress AnalysisClickHouse/ClickHouse50k—~4.7kAutomated safety check: PassApache-2.0
Perf ComparisonClickHouse/ClickHouse50k—~3.9kAutomated safety check: NotesApache-2.0
Patch Release CheckClickHouse/ClickHouse50k—~4kAutomated safety check: NotesApache-2.0
Clickhouse Architecture Advisorvemetric/vemetric3942 repos~791Automated safety check: PassApache-2.0
Decompress BinaryClickHouse/ClickHouse50k—~1.1kAutomated safety check: PassApache-2.0

Similar skills

  • Keeper Stress Analysis

    ClickHouse/ClickHouse

    Analyze ClickHouse Keeper stress-test results from play.clickhouse.com / keeperstresstests data warehouse.

    50k GitHub stars~4.7k tokensUpdated today
    DatabasesAuto-check passed
  • Perf Comparison

    ClickHouse/ClickHouse

    Evaluate ClickHouse performance test results from existing CI/dashboard data or local perf.py runs.

    50k GitHub stars~3.9k tokensUpdated today
    DatabasesAuto-check: notes
  • Patch Release Check

    ClickHouse/ClickHouse

    Check whether ClickHouse's supported versions (last 3 majors + latest LTS) have recent stable patch releases, diagnose why the scheduled AutoReleases pipeline failed, and identify which releases…

    50k GitHub stars~4k tokensUpdated today
    DatabasesAuto-check: notes
  • MUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system designs.

    394 GitHub starsUsed in 2 repos~791 tokens
    DatabasesAuto-check passed
  • Decompress Binary

    ClickHouse/ClickHouse

    Extract the inner ELF from a ClickHouse self-extracting clickhouse binary, including when its architecture differs from the host (e.g.

    50k GitHub stars~1.1k tokensUpdated today
    DatabasesAuto-check passed
  • Good PRs

    ClickHouse/ClickHouse

    Show a report of open ClickHouse PRs whose only non-green CI check is "CH Inc sync" (or that are fully green) — i.e.

    50k GitHub stars~1.8k tokensUpdated today
    DatabasesAuto-check passed

More from chmonitor/chmonitor

All 53 skills in this repo
  • Hyperframes Creative

    chmonitor/chmonitor

    Non-animation creative direction for HyperFrames videos. An agent skill from chmonitor/chmonitor.

    299 GitHub starsUsed in 5 repos~1.3k tokens
    Auto-check passed
  • Hyperframes Media

    chmonitor/chmonitor

    Audio and media assets for HyperFrames compositions, produced by one shared audio engine (scripts/audio.mjs) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound…

    299 GitHub starsUsed in 1 repo~2.8k tokens
    Auto-check: notes
  • Remotion To Hyperframes

    chmonitor/chmonitor

    Port an existing Remotion (React) composition to HyperFrames HTML.

    299 GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Music To Video

    chmonitor/chmonitor

    A skill your agent uses when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting.

    299 GitHub starsUsed in 1 repo~4k tokens
    Auto-check: notes
  • Hyperframes Animation

    chmonitor/chmonitor

    All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus…

    299 GitHub starsUsed in 2 repos~1.8k tokens
    Auto-check passed
  • Faceless Explainer

    chmonitor/chmonitor

    turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video, up to ~3 min (sweet spot 30-90s), where every visual is invented (typography, abstract graphics…

    299 GitHub stars~4.5k tokensUpdated 2 days ago
    Auto-check: notes

Works with

Categories

Questions about Hardware Tuning

What does Hardware Tuning do?

Detect server cores/RAM/disk from system tables, then recommend ClickHouse settings sized to that hardware. Hardware Tuning is an agent skill from chmonitor/chmonitor. Detect server cores/RAM/disk from system tables, then recommend ClickHouse settings sized to that hardware.

When should I use Hardware Tuning?

Hardware Tuning fits situations like: tasks that involve Data warehousing.

How do I install Hardware Tuning in Claude Code?

Run `npx skills add chmonitor/chmonitor --skill hardware-tuning -a claude-code`. Or copy the skill folder (.agents/skills/hardware-tuning in chmonitor/chmonitor) into .claude/skills/hardware-tuning in your project. Claude Code loads it when a task matches its description.

How do I install Hardware Tuning in Codex?

Run `npx skills add chmonitor/chmonitor --skill hardware-tuning -a codex`. Or copy the skill folder (.agents/skills/hardware-tuning in chmonitor/chmonitor) into .agents/skills/hardware-tuning in your project. Codex loads it when a task matches its description.

Can I use Hardware Tuning in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add chmonitor/chmonitor --skill hardware-tuning -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/hardware-tuning, .gemini/skills/hardware-tuning, .github/skills/hardware-tuning and .opencode/skills/hardware-tuning in your project.

What does Hardware Tuning need to run?

SKILL.md names no scripts, command-line tools or credentials: Hardware Tuning is instructions for the agent only.

Does Hardware Tuning access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Hardware Tuning safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Hardware Tuning use?

Hardware Tuning is published under the GPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Hardware Tuning use?

About 2.1k tokens (SKILL.md is roughly 8.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Hardware Tuning?

Skills that share tags, products or a category with Hardware Tuning: Keeper Stress Analysis (ClickHouse/ClickHouse, 50k stars), Perf Comparison (ClickHouse/ClickHouse, 50k stars), Patch Release Check (ClickHouse/ClickHouse, 50k stars) and Clickhouse Architecture Advisor (vemetric/vemetric, 394 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Hardware Tuning?

chmonitor (a GitHub organization) maintains it in chmonitor/chmonitor, which has 299 GitHub stars. The repository holds 53 skills in this directory. The repository was last updated on October 5, 2026.

Source: chmonitor/chmonitor on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.