Agent skill

Bisect

Bisect a ClickHouse regression using pre-built master binaries from CI.

Apache-2.0Auto-check passedDatabases

Install Bisect

skills CLI

$ npx skills add ClickHouse/ClickHouse --skill bisect -a claude-code

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

GitHub CLI

$ gh skill install ClickHouse/ClickHouse bisect --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/ClickHouse/ClickHouse.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/bisect .claude/skills/bisect && 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/

Paste into Claude Code

Install the "bisect" agent skill from https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect into .claude/skills/bisect/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bisect", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add ClickHouse/ClickHouse --skill bisect -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install ClickHouse/ClickHouse bisect --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/ClickHouse/ClickHouse.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/bisect .agents/skills/bisect && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "bisect" agent skill from https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect into .agents/skills/bisect/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bisect", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add ClickHouse/ClickHouse --skill bisect -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install ClickHouse/ClickHouse bisect --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/ClickHouse/ClickHouse.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/bisect .cursor/skills/bisect && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "bisect" agent skill from https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect into .cursor/skills/bisect/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bisect", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/ClickHouse/ClickHouse.git --path .claude/skills/bisect

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add ClickHouse/ClickHouse --skill bisect -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install ClickHouse/ClickHouse bisect --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/ClickHouse/ClickHouse.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/bisect .gemini/skills/bisect && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "bisect" agent skill from https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect into .gemini/skills/bisect/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bisect", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install ClickHouse/ClickHouse bisect

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add ClickHouse/ClickHouse --skill bisect -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/ClickHouse/ClickHouse.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/bisect .github/skills/bisect && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "bisect" agent skill from https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect into .github/skills/bisect/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bisect", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add ClickHouse/ClickHouse --skill bisect -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install ClickHouse/ClickHouse bisect --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/ClickHouse/ClickHouse.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/bisect .opencode/skills/bisect && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "bisect" agent skill from https://github.com/ClickHouse/ClickHouse/tree/master/.claude/skills/bisect into .opencode/skills/bisect/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bisect", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: bisect
GitHub stars: 50k
Token cost: ~1.4k tokens
SKILL.md length: 505 words
Files: 1
Skills in repo: 24
Repo updated: Oct 8, 2026
First seen: Oct 8, 2026
Licence: Apache-2.0

At a glance

Bisect a ClickHouse regression using pre-built master binaries from CI.

Works in 5 steps: Validate inputs → Write the test script → Confirm the bug range → …
The user wants to find the commit that introduced a bug
SKILL.md covers Arguments, How the auto-bisect script works, Test script contract and Process, plus 1 more section
Calls git and clickhouse; needs CH_CI_PASSWORD

What it does

Bisect is an agent skill from ClickHouse/ClickHouse. Bisect a ClickHouse regression using pre-built master binaries from CI. Use when the user wants to find the commit that introduced a bug.

Its SKILL.md is about 1.4k 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, Git and SQL. The repository describes itself as: ClickHouse® is a real-time analytics database management system. The licence is Apache-2.0.

When your agent uses it

The user wants to find the commit that introduced a bug
Tasks that involve Data warehousing

Example prompts

“/bisect”

Requirements

Pre-approved tools (allowed-tools): Task, Bash(git:*), Bash(curl:*), Bash(chmod:*), Bash(mkdir:*), Bash(ls:*), Bash(/tmp/*), Bash(cat:*), Bash(utils/auto-bisect/*), Read, Write, Glob, Grep, WebFetch, LSP

Workflow steps

5 steps, taken from the step headings in SKILL.md.

Validate inputs
Write the test script
Confirm the bug range
Run bisect
Report findings

What it can do on your machine

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

Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
- Task
- Bash(git:*)
- Bash(curl:*)
- Bash(chmod:*)
- Bash(mkdir:*)
- Bash(ls:*)
- Bash(/tmp/*)
- Bash(cat:*)
- Bash(utils/auto-bisect/*)
- Read
…and 5 more on the same allowed-tools line.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- git
- clickhouse
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
- CH_CI_PASSWORD
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Bisect loads about 1.4k tokens when it runs. Until then it costs about 36 tokens; SKILL.md has 505 words of instructions outside code blocks.

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

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 ClickHouse/ClickHouse at commit cd023af, republished under its Apache-2.0 licence (© ClickHouse). 505 words, ~1,374 tokens.

Download SKILL.mdSave it as .claude/skills/bisect/SKILL.md (or your agent's skills folder).

name: bisect
description: Bisect a ClickHouse regression using pre-built master binaries from CI. Use when the user wants to find the commit that introduced a bug.
allowed-tools: Task, Bash(git:*), Bash(curl:*), Bash(chmod:*), Bash(mkdir:*), Bash(ls:*), Bash(/tmp/*), Bash(cat:*), Bash(utils/auto-bisect/*), Read, Write, Glob, Grep, WebFetch, LSP
argument-hint: <repro.sql> [good-ref] [bad-ref]
disable-model-invocation: false

ClickHouse Bisect Skill

Bisect a ClickHouse regression using utils/auto-bisect/bisect.sh, which downloads pre-built CI binaries and manages the bisect loop automatically.

Arguments

$0 (required): Path to a SQL repro file (e.g., /tmp/repro.sql)
$1 (optional): Good ref — a git tag, branch, or SHA known to be good (default: latest v*.1.1-* tag)
$2 (optional): Bad ref — a git tag, branch, or SHA known to be bad (default: HEAD)

How the auto-bisect script works

utils/auto-bisect/bisect.sh orchestrates the full bisect:

For each commit, helpers/download.sh fetches the release binary from CI S3
env/<option>.sh installs configs and starts a ClickHouse server (configs go to utils/auto-bisect/data/etc/, never to /etc/)
Your test script is called with $COMMIT_SHA, $CH_PATH (binary), and $GIT_WORK_TREE in the environment
Exit code from your test determines good/bad/skip

The working tree is never checked out — BISECT_HEAD is written for each step so git history is untouched.

Test script contract

The test script receives these environment variables:

$COMMIT_SHA — full SHA of the commit being tested
$CH_PATH — path to the downloaded binary (e.g., utils/auto-bisect/data/clickhouse)
$GIT_WORK_TREE — path to the ClickHouse repository

Exit codes:

0 — good (bug not present)
1 — bad (bug present)
125 — skip (handled upstream by download.sh, not typically needed in the test itself)

Process

1. Validate inputs

Read and understand the repro SQL
Resolve good/bad refs to full SHAs: git rev-parse <ref>
If no good ref given, find the previous release branch point:
bash
```
git tag -l 'v*' --sort=-creatordate | grep '\.1\.1-' | head -5
```
Pick the nearest v<MAJOR>.<MINOR>.1.1-* tag before the bad ref.

2. Write the test script

Create /tmp/bisect_test.sh. Use $CH_PATH for the binary — do not download it yourself, the framework handles that.

For clickhouse local repros (no server needed — use --env nothing):

bash

#!/bin/bash
set -e

OUTPUT=$("$CH_PATH" local --multiquery 2>&1 <<'SQL'
-- paste repro SQL here
SQL
)

if echo "$OUTPUT" | grep -q "FAILURE_PATTERN"; then
    exit 1  # bad
else
    exit 0  # good
fi

For server-based repros (use --env single, the default):

bash

#!/bin/bash
# Server is already running when this script is called.
# Use clickhouse-client on the default port (9000).
set -e

OUTPUT=$("$CH_PATH" client --multiquery 2>&1 <<'SQL'
-- paste repro SQL here
SQL
)

if echo "$OUTPUT" | grep -q "FAILURE_PATTERN"; then
    exit 1
else
    exit 0
fi

Failure pattern examples:

Exception: grep -q "LOGICAL_ERROR\|Code: [0-9]"
Wrong result: compare OUTPUT to expected string
Segfault: [ "${PIPESTATUS[0]}" = "139" ]

Show full SKILL.md (209 more words)Show less

3. Confirm the bug range

Before running the full bisect, verify the repro:

bash

GOOD_SHA=$(git rev-parse <good-ref>)
BAD_SHA=$(git rev-parse <bad-ref>)

Optionally do a quick walker sanity check over just the two endpoints:

bash

CH_PATH=/usr/local/bin/clickhouse /tmp/bisect_test.sh  # should exit 0 on good

4. Run bisect

bash

cd utils/auto-bisect
./bisect.sh \
  --good <good-sha> \
  --bad  <bad-sha> \
  --path /path/to/ClickHouse \
  --test /tmp/bisect_test.sh \
  --env  nothing          # or: single (default), replicateddb, sharedcatalog

Use --env nothing when the test uses clickhouse local (no server). Use --env single (default) when the test needs a running server.

Walker mode — walk every commit linearly instead of bisecting (useful when you want to see the progression or the range is small):

bash

./bisect.sh --good <sha> --bad <sha> --path ... --test ... --walker
# Or provide explicit commits:
./bisect.sh --path ... --test ... --walker --walker-commits "sha1 sha2 sha3"
# Or limit to N evenly-spaced steps:
./bisect.sh --good <sha> --bad <sha> --path ... --test ... --walker --walker-steps 10

Set a generous timeout (up to 10 min) — each step downloads ~200 MB.

5. Report findings

After bisect completes, the output contains <sha> is the first bad commit.

bash

git show --stat <bad-sha>

Report:

First bad commit SHA and message
PR number from message (e.g., "Merge pull request #NNNNN") → link to https://github.com/ClickHouse/ClickHouse/pull/<N>
Brief description from git show --stat
Any skipped commits (no CI binary) that fall in the range

Notes

Binaries are downloaded to utils/auto-bisect/data/clickhouse and overwritten each step (not cached between steps — use walker if you want to re-test)
Only first-parent merge commits on master have CI binaries; bisect.sh uses --first-parent automatically
Configs are installed to utils/auto-bisect/data/etc/clickhouse-server/ — the host's /etc/clickhouse-* is never touched
The working tree is never modified during bisect or walker runs; BISECT_HEAD is used instead of git checkout
For private CI builds, set CH_CI_USER / CH_CI_PASSWORD and pass --private

Files

Just SKILL.md in .claude/skills/bisect of ClickHouse/ClickHouse.

Open the folder on GitHubat commit cd023af

Compare with similar skills

Bisect 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.

Bisect compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Bisect this skillClickHouse/ClickHouse	50k	—	~1.4k	Automated safety check: Pass	Apache-2.0	today
Clickhouse Logs Queriessupabase/supabase	111k	—	~2.4k	Automated safety check: Pass	Apache-2.0	today
Chdb SQLvemetric/vemetric	394	1 repos	~1.2k	Automated safety check: Pass	Apache-2.0	yesterday
Clickhouse System QueriesFrankChen021/datastoria	327	—	~731	Automated safety check: Pass	Custom licence	2 mo ago
Webapp Buildersidequery/sidemantic	129	—	~5.5k	Automated safety check: Pass	AGPL-3.0	yesterday
Modelersidequery/sidemantic	129	—	~4.2k	Automated safety check: Pass	Apache-2.0	yesterday

Similar skills

Clickhouse Logs Queries
supabase/supabase
Official
Write, review, and migrate Supabase logs queries against the ClickHouse-backed logs table (the logs.all.otel analytics endpoint).
111k GitHub stars~2.4k tokensUpdated today
DatabasesAuto-check passed
Chdb SQL
vemetric/vemetric
A skill your agent uses when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse…
394 GitHub starsUsed in 1 repo~1.2k tokens
DatabasesAuto-check passed
Clickhouse System Queries
FrankChen021/datastoria
Query ClickHouse system tables to inspect query logs, monitor cluster health, check replication status, and analyze slow queries.
327 GitHub stars~731 tokensUpdated 2 mo ago
DatabasesAuto-check passed
Webapp Builder
sidequery/sidemantic
Build interactive analytics webapps, demos, dashboards, or embedded app surfaces from Sidemantic semantic models using copyable component primitives and deterministic query inspection.
129 GitHub stars~5.5k tokensUpdated yesterday
DatabasesAuto-check passed
Modeler
sidequery/sidemantic
Build, validate, and manage semantic models using Sidemantic.
129 GitHub stars~4.2k tokensUpdated yesterday
DatabasesAuto-check passed
Querying Tempo
tempoxyz/tidx
Query indexed Tempo chain data via tidx HTTP API and CLI. An agent skill from tempoxyz/tidx.
107 GitHub stars~3.1k tokensUpdated today
DatabasesAuto-check passed

Questions about Bisect

What does Bisect do?

Bisect a ClickHouse regression using pre-built master binaries from CI. Bisect is an agent skill from ClickHouse/ClickHouse. Bisect a ClickHouse regression using pre-built master binaries from CI.

When should I use Bisect?

Bisect fits situations like: the user wants to find the commit that introduced a bug; tasks that involve Data warehousing.

How do I install Bisect in Claude Code?

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

How do I install Bisect in Codex?

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

Can I use Bisect 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 ClickHouse/ClickHouse --skill bisect -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bisect, .gemini/skills/bisect, .github/skills/bisect and .opencode/skills/bisect in your project.

What does Bisect need to run?

Going by SKILL.md and its folder, Bisect needs the command-line tools its instructions call (git and clickhouse) and credentials named CH_CI_PASSWORD. Its frontmatter pre-approves these tools: Task, Bash(git:*), Bash(curl:*), Bash(chmod:*), Bash(mkdir:*), Bash(ls:*), Bash(/tmp/*), Bash(cat:*), Bash(utils/auto-bisect/*), Read, Write, Glob, Grep, WebFetch, LSP.

Does Bisect access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Bisect 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 Bisect use?

Bisect is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Bisect use?

About 1.4k tokens (SKILL.md is roughly 5.5k 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 Bisect?

Skills that share tags, products or a category with Bisect: Clickhouse Logs Queries (supabase/supabase, 111k stars), Chdb SQL (vemetric/vemetric, 394 stars), Clickhouse System Queries (FrankChen021/datastoria, 327 stars) and Webapp Builder (sidequery/sidemantic, 129 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Bisect?

ClickHouse (a GitHub organization) maintains it in ClickHouse/ClickHouse, which has 50,288 GitHub stars. The repository holds 24 skills in this directory. The repository was last updated on October 8, 2026.

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

Install Bisect

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

ClickHouse Bisect Skill

Arguments

How the auto-bisect script works

Test script contract

Process

1. Validate inputs

2. Write the test script

3. Confirm the bug range

4. Run bisect

5. Report findings

Notes

Files

Compare with similar skills

Similar skills

More from ClickHouse/ClickHouse

Related

Questions about Bisect