KooLink
Start free
← Blog
Guides2 min read

Short links in commit messages and READMEs: how to keep them clean

Long URLs make commit messages and READMEs ugly. A shortener with a stable slug keeps them readable and permanent. KooLink gives you short links from your terminal or AI agent.

A long URL in a commit message or a README is a small but real quality problem. It wraps, it truncates, it pushes the actual commit message off the line, and it looks unfinished. A short, stable link does the job better.

Here is how to keep your repo's links clean without adding a chore to your workflow.

Why short links belong in code

  • They do not wrap. A long deploy URL breaks markdown rendering and git commit display. A kool.ink/xyz link fits on one line.
  • They are permanent. A commit message is a record. If you shorten a link, it should still work years later, not expire after a month.
  • They are readable. kool.ink/xyz tells a reader nothing about the path, which is fine, because the point of a commit message is the message — not a wall of URL.
  • You can track them. When you link a deployed artifact or an image in a README, a trackable short link tells you whether anyone is actually seeing it.

Shorten from your terminal

The fastest way to shorten a URL without leaving your shell is the KooLink CLI:

npx @koolink/koolink https://example.com/very/long/path
# → https://kool.ink/xyz

Pipe the long URL in:

echo "https://example.com/long/path" | npx @koolink/koolink
# → https://kool.ink/xyz

You can then paste the output straight into a commit message or a README line. No account, no API key, free and unlimited.

Shorten with an AI agent

If you work in Claude Code, Cursor, Windsurf, or any MCP client, add the KooLink MCP server and the agent shortens the URL itself:

https://mcp.kool.ink

Then just ask: "shorten this for the commit message." The agent does it and you never leave the editor.

The rules I use

  1. Shorten anything a human will read but not click in a browser. A deploy URL, an artifact link, an image URL in a README.
  2. Keep the message primary. The commit message explains why. The URL just needs to be findable. A short link keeps that balance.
  3. Never shorten links that must be inspectable. If a reviewer needs to see the full URL to audit it, leave it long. Short links are for sharing and tidiness, not for obscuring an origin.
  4. Use a permanent shortener. A link that expires breaks every commit message that references it. KooLink links do not expire.

Wrap up

Long URLs are an easy win to clean up. Shorten them from your terminal with npx @koolink/koolink, or let your AI agent do it via https://mcp.kool.ink. Either way you get clean, permanent, trackable links in your repo.

Shorten a link →