Analyze log files with ctrlb-decompose — pattern clustering, anomaly detection, and severity scoring

version
1.0.0
GitHub stars
305

Install

/plugin install ctrlb-decompose@ctrlb-hq

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ctrlb-hq/ctrlb-decompose.

Contents

Discovered from source

Skills 1

ctrlb-decompose Log Analysis

Overview

Analyze log files or raw log text using ctrlb-decompose — a CLI that compresses millions of log lines into a handful of typed patterns with variable statistics, anomaly detection, and severity scoring. Output is optimized for LLM consumption via --llm.

Workflow

  1. Gate large pastes — redirect to file path if volume is high
  2. Check if ctrlb-decompose is installed; install if not
  3. Run analysis on the file or pasted content
  4. Interpret results — lead with problems, surface anomalies, suggest next steps

Large Paste Policy

If the user signals they are about to paste log content (e.g. "here are my logs", "let me paste some logs"), ask first:

About how many lines are you sharing? For more than ~100 lines, save to a file and share the path — it keeps context clean and ctrlb-decompose handles files directly:

ctrlb-decompose --llm --top 20 /path/to/your.log

Proceed with pasted content only if the user insists or the volume is clearly small (a handful of lines).

After processing pasted content: do not quote, repeat, or reference individual raw log lines. Work only from ctrlb-decompose output — the raw lines are consumed.


Step 1 — Verify Installation

which ctrlb-decompose

If found → skip to Step 2.

If not found → detect the OS:

uname -s

macOS (Darwin)

which brew

Homebrew found — install ctrlb-decompose:

brew tap ctrlb-hq/tap && brew install ctrlb-decompose

Homebrew not found — install Homebrew first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install ctrlb-decompose:

brew tap ctrlb-hq/tap && brew install ctrlb-decompose

Linux

cat /etc/os-release
DistroInstall command
Debian / Ubuntu (ID=debian, ID=ubuntu, or ID_LIKE contains debian)curl -LO https://github.com/ctrlb-hq/ctrlb-decompose/releases/latest/download/ctrlb-decompose_amd64.deb && sudo dpkg -i ctrlb-decompose_amd64.deb
RHEL / Fedora / CentOS (ID is rhel, fedora, or centos)curl -LO https://github.com/ctrlb-hq/ctrlb-decompose/releases/latest/download/ctrlb-decompose_amd64.rpm && sudo rpm -i ctrlb-decompose_amd64.rpm
Other Linuxcurl -LO https://github.com/ctrlb-hq/ctrlb-decompose/releases/latest/download/ctrlb-decompose-linux-x86_64 && chmod +x ctrlb-decompose-linux-x86_64 && sudo mv ctrlb-decompose-linux-x86_64 /usr/local/bin/ctrlb-decompose

Fallback — Build from Source

If any installation method fails (wrong architecture, missing binary, package manager error):

which git && which cargo

If cargo is missing, install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source "$HOME/.cargo/env"

Clone and build:

git clone https://github.com/ctrlb-hq/ctrlb-decompose.git /tmp/ctrlb-decompose-build \
  && cd /tmp/ctrlb-decompose-build \
  && cargo build --release \
  && sudo cp target/release/ctrlb-decompose /usr/local/bin/ctrlb-decompose \
  && cd / && rm -rf /tmp/ctrlb-decompose-build

Confirm with which ctrlb-decompose, then continue to Step 2.


Step 2 — Run Analysis

File path provided:

ctrlb-decompose --llm --top 20 "$FILE_PATH"

Pasted log text: Use the Write tool to save content to /tmp/ctrlb_input.log (handles multi-line text, special characters, and quotes correctly), then:

ctrlb-decompose --llm --top 20 /tmp/ctrlb_input.log && rm /tmp/ctrlb_input.log

Use --top 20 by default. Increase to --top 50 if the user wants more patterns. For all available flags and options, run ctrlb-decompose --help.


Step 3 — Interpret Results

Present findings in this priority order:

PriorityFocusWhat to cover
1stProblemsERROR, FATAL, WARN patterns — frequency, rate, associated variables
2ndAnomaliesFrequency spikes, high error rates, unexpectedly low-cardinality variables
3rdVariable summariesMost common IPs, slowest durations (p99), notable enum distributions
4thNext stepsWhich patterns to drill into, what filters or time ranges to investigate

Keep the response grounded in ctrlb-decompose output. Do not speculate about root causes beyond what the pattern data supports.

Sponsors

Details

Marketplace
ctrlb-hq/ctrlb-decompose
Source
plugin
Author
CtrlB
Category
Community
License
MIT
Keywords
logs, log-analysis, observability, patterns, anomaly-detection