damn-my-slow-kt: automating a Korean ISP's SLA refund claims

The refund is per day, and the tool exists because of that

The premise is a Korean ISP quality guarantee rather than a technical problem. KT is required to credit the fee for a given day when the measured speed falls below the SLA threshold, which is set at 50 percent of the contracted speed. The detail that matters is that one measurement gives one day of credit, not one month: to be credited for a whole month you have to fail the measurement every day for thirty days.

The README makes the arithmetic explicit. A single measurement results in a one-day credit, whereas measuring every day results in a credit for one day each time, up to a full month at thirty consecutive failures.

And the reason the tool exists is the friction. Who logs into the KT homepage every day, waits twenty-five minutes, and presses the objection button? The README's answer is that nobody does, and this tool does it instead. The example output shows the shape of a run: a contracted speed of 1,000 Mbps, a measured speed of 64 Mbps, which is 6.4 percent of the contract, an SLA failure, the objection claim submitted, and the month's fee credited.

So the value proposition is not clever measurement. It is showing up every single day on your own behalf, which is exactly the task a scheduled script is good at and a person is bad at.

The measurement is only valid if KT's own program runs

The rule that makes this work is that the measurement must be taken with the speed test program supplied by KT, and the server must be KT's own SLA server at speed.kt.com. That is not a technical preference, it is the contractual condition, and it is what the tool has to satisfy.

The consequence for installation is that a second piece of software is required. The KT speed test program is installed separately: on macOS from a ktspeed.pkg download, on Windows by going to speed.kt.com, entering the quality guarantee SLA test, and following the instructions. On Linux the program is not supported and therefore the tool cannot be used at all.

The README is also explicit that Windows is not yet tested, and that only macOS has been verified. The macOS install has a wrinkle that the README documents in detail, because ktspeed.pkg is an official KT file that is not Apple notarized, so macOS shows a security warning. The documented path is to open System Settings, go to Privacy and Security, find the message saying that ktspeed.pkg was blocked in the Security section, click Open Anyway, and authenticate with a password or Touch ID. The README also notes that the Ctrl-click override was removed in macOS Sequoia 15 and later, so the System Settings route is now the only one.

This is the single biggest constraint in the project. A tool that automates a contractual claim has to reproduce the exact conditions the contract requires, and on Linux it cannot.

Setup, the schedule, and the daily loop

The tool runs through npx, so the first requirement is Node.js 20 or newer, checked with the three version commands the README lists:

node -v
npm -v
npx -v

If node -v reports v20 or above you can continue, and if the command is missing or the version is too low you install Node.js 20 or newer, with the latest LTS recommended. The README gives the official installer for the general case, plus brew install node for macOS users who already have Homebrew and winget install OpenJS.NodeJS.LTS for Windows users in PowerShell.

Initialisation is a single npx invocation, and after you enter your KT account details that is the end of the setup:

npx -y damn-my-slow-kt@latest init

What that installs is a schedule that measures up to ten times a day at two-hour intervals and files the credit claim immediately when a measurement falls short, skipping the rest once one succeeds. The daily rhythm in the README looks like this: at 04:00 it measures, the speed is normal, and it stops; at 06:00 it measures again, the SLA is missed, and the claim succeeds; at 08:00 it reports that the credit has already been claimed today and skips; at 10:00 it skips, and so on.

You can also run it once by hand without waiting for the schedule:

npx -y damn-my-slow-kt@latest run

That takes about twenty-five minutes for five measurements, and it goes on to file the credit claim if the SLA was missed. There are three flags worth knowing: --dry-run measures without filing the claim, --force runs again even if today is already done, and --debug opens a browser window so you can watch the process directly, which is described as being for diagnosing problems.

Configuration is a YAML file, and the schedule is separate from it

The configuration lives in a YAML file at ~/.damn-my-slow-isp/config-kt.yaml, and you edit it directly. The schedule block sets max_attempts, the maximum number of measurements per day, and retry_interval_minutes, the gap between measurements. The notification block holds an optional Discord webhook and an optional Telegram bot token.

After changing the configuration you re-register the schedule:

npx -y damn-my-slow-kt@latest schedule install

That two-step arrangement is worth noting, because the schedule is an operating system level registration while the settings are a file. A change to the YAML does not take effect on its own, and the tool does not appear to have a command that edits the file for you, which means the notification credentials are typed into a file by hand. Treat that file as a secret.

To remove the schedule entirely:

npx -y damn-my-slow-kt@latest schedule remove

The README also notes that running the init command again is how you update, and that if a new version changes the configuration the tool tells you and asks whether to apply it. That is a slightly unusual update path for an npx tool, since normally npx simply fetches the newest version at each invocation, and it implies the version is pinned somewhere after the first init.

The configuration is also where a headless setting lives, because the browser-driven parts of the flow are what make debugging possible at all.

Debugging means opening a browser and watching it break

When a run fails, the terminal asks whether you would like to open a browser window and check directly where it got stuck, and pressing Y re-runs the same flow in debug mode. To start in debug mode from the beginning:

npx -y damn-my-slow-kt@latest run --debug

Debug mode ignores the headless setting in config-kt.yaml for that one run, opens the browser, applies a slowMo of 250ms so you can see each step, and opens DevTools automatically. On an error the browser does not close straight away, it waits for you to press Enter. The measurement results and the credit claim are still saved and processed the same way as in a normal run, which is the detail that makes this usable: debug mode is a view onto the same run, not a different one.

The README then lists the common causes, with a link to issue number 3. They are all things that can only be diagnosed by looking at the page: logging in with an account that does not hold a KT line, the speed test program not being installed, a new device registration screen appearing, and an address selection screen appearing additionally for accounts with multiple lines.

That last one is the sort of thing that makes a browser-driven approach necessary rather than convenient. The flow goes through pages only a human would see, and it changes depending on the account, so there is no fixed API to call.

The rules the tool is automating, as stated in the contract

The README reproduces the eligibility criteria, and they are more specific than the headline suggests.

The judgement is five measurements over thirty minutes, with 60 percent or more, meaning three or more, failing the minimum speed, and that qualifies for the credit. The compensation is that day's usage fee. The line that is easy to miss is the termination right: if you receive a credit on five or more days in a month, you can cancel without any rebate. The target is wired LAN connections only, with Wi-Fi excluded. And the measurement requires KT's official SLA server plus the KT speed test program.

The contract excerpt reproduced in the README matches these points. The measurement server is speed.kt.com, the compensation criterion is five or more transmission speed measurements over thirty minutes with 60 percent or more falling below the minimum speed, and the measurement must use the program supplied by KT. The compensation amount is that day's usage fee, and a customer who wants to cancel because of an SLA shortfall can do so without a rebate.

The product tier table adds the part that determines whether you qualify at all. Each product has a contracted speed and a minimum guaranteed speed, and the minimum is always half the contracted value: 10Gbps becomes 5Gbps, 5Gbps becomes 2.5Gbps, 2.5Gbps becomes 1.25Gbps, 1Gbps becomes 500Mbps, 500Mbps becomes 250Mbps, 200Mbps becomes 100Mbps, and 100Mbps becomes 50Mbps.

So the arithmetic is simple, and the only variable is whether your line actually delivers half of what you pay for. A tool like this is worth writing precisely when the contract is that specific.

Why the Docker and NAS path is struck through

There is a section in the README titled NAS / Docker execution, and it is struck through and marked as currently unusable, because the KT speed test program only supports macOS and Windows, which makes SLA measurement impossible in a Linux based Docker or NAS environment.

The details of the previous approach are preserved in a collapsed section, and they are worth reading because they show the shape of the automation even though the path is closed. On a system such as a Synology NAS that lacks system libraries, the official Playwright Docker image was used, with the configuration generated on the host first, and the container run with the config directory mounted.

docker run --rm \
  -v ~/.damn-my-slow-isp:/root/.damn-my-slow-isp \
  mcr.microsoft.com/playwright:v1.52.0-noble \
  npx -y damn-my-slow-kt@latest run

For cron, the entries went into /etc/crontab directly, one line per scheduled run at two-hour intervals through the day.

Keeping this in the documentation is honest rather than misleading, because the tool is a browser driver and the browser driver is the part that needs the real operating system. The project also documents its tested environments: macOS on Apple Silicon running natively, Windows untested, and GitHub Actions on Ubuntu with Node 20, 22 and 24 where the CI can load the web page but cannot run the speed test because the program cannot be installed there.

That CI limitation is a fair summary of the whole project. The flow is automatable, but only on a desktop with the vendor's program installed.

How it is built, and what that tells you

The developer documentation section lists the stack, and it is a good description of what the tool actually is.

The language is TypeScript with ES2020, CommonJS and strict mode. The CLI is Commander with Inquirer and Chalk v4. The browser work is Playwright with headless Chromium, which is the automation layer. Storage is node:sqlite on Node 22 and newer with a JSON fallback. Configuration is YAML in the config-kt.yaml file. Linting is ESLint with typescript-eslint, tests run under Vitest, and CI is GitHub Actions on a Node 20 and 22 matrix.

Playwright with headless Chromium being the core dependency is the architectural fact that explains the platform limits. A headless browser cannot drive a native speed test program, and the tool's job is to make the vendor's program do the measurement, so a real desktop session is required. The JSON fallback in storage is a sensible accommodation for the Node 20 floor, and the README notes that Node 22 or newer is recommended for native SQLite support.

The package metadata shows the delivery shape. The package is damn-my-slow-kt at version 0.5.28, with a single binary entry point at bin/damn-my-slow-kt, the dist directory and the README published, and Node 20 or newer required. The runtime dependencies are axios, chalk, cli-table3, commander, inquirer, js-yaml and playwright, and the development dependencies include typescript-eslint, vitest, ts-node and an action validator.

The release cadence is brisk: v0.5.28, v0.5.27 and v0.5.26 landed between May and June 2026, and the last push was on 2026-06-06. For a tool whose real dependency is a vendor program and a browser, that is a project being maintained close to its users.

Editorial conclusion

Adopt damn-my-slow-kt if you are on a KT line whose delivered speed sits under the contractual minimum and you want the daily service credit claim filed without logging into the portal every morning, because the credit is per measured day and the tool is essentially a scheduled browser session that does the boring part. Do not adopt it on Linux, in Docker or on a NAS, since the KT speed test program is only available for macOS and Windows and the README marks that path as currently unusable, and do not treat it as a way to reduce a bill that was never going to qualify. Before you commit, check the minimum guaranteed speed for your product tier, which is always half the contracted speed, and run a single npx -y damn-my-slow-kt@latest run with --dry-run first to see whether your line actually fails the threshold at all.

Frequently asked questions

Official sources

1. Issues
2. kargnas/damn-my-slow-kt on GitHub
3. README
4. Releases