DEV Community: Rob Ragan

Every component your Coding Agent builds or dependency it guesses becomes your tech debt

Rob Ragan — Wed, 24 Jun 2026 22:38:18 +0000

Ask Claude Code, Cursor, or Copilot to add a dependency and it names one — instantly, confidently. That confidence comes from training recall: a snapshot of scraped code frozen at a cutoff date. So the agent can't know your team already has an internal, audited library for this. It can't know the package it just named went unmaintained six months ago, or that a supply-chain advisory landed last week. It picks anyway, with identical confidence either way.

Here's the part that compounds: a wrong pick doesn't bounce off. It gets written into your codebase — a hand-rolled auth flow, a dependency on an abandoned package, a second module that duplicates something you already own. That's tech debt the agent created and you inherit. And it's debt with interest: the agent builds on the bad choice, the problem surfaces downstream, and then you pay again — in tokens, review time, and rework — to unwind and redo it.

That's not a prompt problem. You can't fix it by asking the model to "be careful." The model is doing recall where it should be doing evaluation, and recall is frozen.

What recall costs you

A few findings that should make you nervous about an agent picking dependencies unsupervised — and notice not one of these is only a security problem:

Nearly 1 in 5 packages an LLM names in generated code don't exist — 19.7% across 16 models and 576,000 samples, rising to ~22% for open-source models (Spracklen et al., USENIX Security 2025). A non-existent package is, at best, a failed build you have to diagnose and redo; at worst, an attacker has registered the popular hallucination and waited (the pattern now has a name, slopsquatting).
~45% of AI-generated code introduces a known security weakness — Veracode's 2025 review of 100+ models across 80 tasks (report).
For whole categories of functionality — auth most damningly, where a custom flow is both a liability and code you now own forever — the agent's default is often to hand-roll custom code rather than reach for a mature library. (That one's my own finding; I reproduce it below.)

Each is a place recall fails, and a smarter prompt can't fix a frozen snapshot. The fix is putting real, dated, structured facts in front of the model at the moment it decides.

It's not just security — what a wrong pick actually costs

When the agent chooses from memory instead of facts, you pay on four fronts. Security is the one everyone leads with; it's the smallest of the four for most teams.

Tech debt — the headline. A guessed dependency is a future migration with your name on it: hand-rolled code you now maintain, an abandoned package you'll eventually rip out, a redundant library because the agent didn't know you'd already standardized on another. The cheapest debt is the line that never gets written.
Wasted tokens and time. Reversing a bad pick isn't free. The agent writes code against it, the problem shows up later, and unwinding plus redoing is more model calls and more of your review. Facts at decision time cut that loop before it starts. (I haven't put a number on the token savings — it's a mechanism, not a measured stat; see limitations.)
License exposure. "Is this AGPL? Does this license survive our distribution model?" is a business question, and recall answers it unreliably. A license fact catches the surprise before it's load-bearing.
Security. The CVEs, the supply-chain incidents, the slopsquatting above. Real — but one axis of four.

All four share one cause: the decision got made without the facts. That's the thing Starlog targets.

Starlog: vet a package by name, at decision time

Starlog puts authoritative facts about a package in front of your agent — license, maintenance status, CVEs, supply-chain incidents — dated, local, no account:

npx starloghq facts ua-parser-js

You get the verified facts on file (here: the 2021 maintainer-account compromise), with an "as of" date. Sub-second, zero setup, no network call. It plugs into your agent three ways:

a CLI (starlog facts <pkg>),
an MCP tool (starlog_facts) the agent calls itself,
and a package-install hook that surfaces a library's facts the moment the agent runs npm install / pnpm add / pip install — before it builds on the package. Advisory, not blocking: it informs the next move.

One command wires all three into Claude Code (and drops instruction files for Cursor, Copilot, and Codex):

npx starloghq init

That's the pitch. The rest of this post is whether it actually works — because "give the model more context" is easy to claim and easy to fake.

Does the agent's decision actually change?

I ran a controlled before/after. Control = a fresh agent answering from recall only. Treatment = the same agent, same prompt, given the package's Starlog facts. The only variable is the facts.

The experiment I had to throw out

My first private-package test gave the agent a fact that said "POLICY: you must use @acme/flags, do not build custom." The agent used @acme/flags 2/2. Clean flip!

It's also worthless as evidence. A fact that says "you must use X" only proves the agent follows instructions — not that the information changed its mind. (A reviewer caught this; it's a tautology trap, and exactly the kind of thing a vendor demo quietly leans on.)

So I re-ran it with an informational-only fact: it states that an active internal package exists, with no "must use," no "don't build custom." Then I let the agent use its own judgment.

Need	Control (recall only)	Treatment (informational-only fact)	Δ
feature flags	build custom	`@acme/flags`	DIY → internal
auth / session	build custom	`@acme/session-core`	DIY → internal

With no facts, the agent reaches for build custom on both — including a hand-rolled, unaudited auth layer, the textbook tech-debt-and-security liability in one object. Given only the information that an active internal library exists — with no instruction to prefer it — it chooses the internal library over building custom, 2/2, on its own judgment.

That's a hand-rolled module that never gets written: debt avoided at the exact moment it would have been created, plus consistency with whatever the rest of your team already ships. And it's the case the model structurally cannot recall — it has never seen your private @acme/* packages. Facts are the only way it learns they exist.

The public side, honestly

Public packages are a weak venue for this — and saying so is more useful than hiding it. Claude's public recall is genuinely good, so most of the time the facts just agree with what it already knew:

Package	Control	Treatment (+facts)	Read
`zod`, `fastify`	ADOPT	ADOPT	healthy decoys — no spurious flip ✅
`posthog-node`	ADOPT	ADOPT + "pin away from the malicious 4.18.1 / 5.11.3 / 5.13.3"	action changed — a post-cutoff supply-chain advisory (`MAL-2025-190925`) the model provably can't know
`node-cache`	AVOID	ADOPT	changed, but ambiguous — "maintenance-only" is a longevity/debt signal, not a clean security verdict; no ground truth, so not counted as a win

The one clean, information-carrying public change is posthog-node: a supply-chain pin from after the training cutoff. That's the thesis in one row — facts matter precisely where recall can't reach. And the decoys didn't flip, so the agent isn't just rubber-stamping whatever the tool says.

Honest by design

The thing I'm proudest of is node-cache not counting as a win. The fact ("maintenance-only") is ambiguous, there's no ground truth, so it doesn't go in the tally. A tool that books every change as a victory is lying to you. Same reason starlog facts some-unknown-pkg returns an honest "no facts on file" instead of a confident guess — telling the agent "I don't know this one" is a feature, not a gap.

The bigger number behind the demo

The before/after above confirms the mechanism on real model calls. The statistical backbone is a prior powered benchmark across four model vendors, measuring the one thing that drives all four payoffs — decision correctness: correct adopt/avoid decisions moved from ~20% to ~78%, with 100% unprompted adoption — when the facts are available, agents reach for them every time. They want this signal; they just don't have it by default. Every correct decision is debt not taken on, rework not paid for, and the occasional CVE caught.

Honest limitations

The curated corpus is 42 packages today — a foundation, not all of npm. Out-of-domain lookups return an honest miss, not a forced answer.
The before/after is a single-rep confirmation of direction; the statistical claim is the prior powered benchmark, not re-run here.
Token and tech-debt savings are argued from mechanism, not separately benchmarked. A wrong pick demonstrably costs rework to reverse; I haven't put a controlled number on how much Starlog saves there. The measured claim is decision correctness — treat the cost savings as the logical consequence, not a tested figure.
Public packages are the weak case — by design. The value lives where the model can't recall: your private libraries, and anything that happened after the cutoff.
The install hook is advisory. If you want a hard PreToolUse approval gate, that's a deliberate non-default — nudging beats blocking for adoption.

Try it

# vet a package — nothing installed, no account
npx starloghq facts event-stream

# wire facts into your agent (Claude Code, Cursor, Copilot, Codex)
npx starloghq init

Source-available under BUSL-1.1 (free to use, modify, and self-host; converts to Apache-2.0 in 2030), listed in the official MCP Registry as io.github.starloghq/starlog.

Repo, the 42-package corpus, and the full validation runbook: https://github.com/starloghq/index

If you build agents, the takeaway generalizes past dependency choice: anywhere the model is doing recall where it should be doing evaluation — anything time-sensitive, anything private — a small local index of dated, honest facts (one willing to say "I don't know") beats asking the model to try harder. The debt it never takes on, and the rework you never pay for, is the quiet win sitting right next to the CVE it catches. It can't recall what it never saw.

I Built a Skin System for Claude Code — Here's How It Works

Rob Ragan — Tue, 12 May 2026 01:24:27 +0000

Claude Code is genuinely remarkable. But if you've been using it for more than a week, you've noticed something: everyone's terminal looks identical. Same colors, same layout, same feel. You could screenshot my session or yours and there'd be no way to tell them apart.

That bothered me more than it probably should have.

So I built a skin system for it. Nine themes, each with terminal colors, ASCII art banners, tool sounds, and — the part I'm most proud of — a personality voice that changes how Claude actually narrates its work.

View the gallery

What It Does

A skin transforms the full Claude Code experience across five layers:

Layer	What changes
Terminal colors	Background, foreground, cursor, full ANSI palette
ASCII banner	Braille art + block-letter logo on session start
Status line	Themed icon, accent colors, progress bar
Personality voice	How Claude narrates its work
Tool sounds	macOS system sounds on file writes, commands, errors

The nine included themes range from "Nebula" (offensive security scanner aesthetic, purple-to-orange gradient) to "Brutalist" (the anti-skin — pure monochrome, zero decoration, maximum terseness). There's also Noir, Netrunner, Mythos, Sensei, Mission Control, Retro86, and Grimoire.

The Architecture

The engine is pure bash. No Node, no Python runtime dependency beyond PyYAML for initial skin parsing. Here's how everything fits together:

YAML skin configs define all the visual and behavioral properties for a theme. They live in ~/.claude/skins/ and missing values fall back to default.yaml automatically.

Claude Code hooks are the integration point. Claude Code supports lifecycle hooks — SessionStart, SessionEnd, and PostToolUse — that run shell commands at specific moments. The skin system uses all three:

"hooks": {
  "SessionStart": [{"type": "command", "command": "~/.claude/skins/engine/activate.sh"}],
  "SessionEnd":   [{"type": "command", "command": "~/.claude/skins/engine/deactivate.sh"}],
  "PostToolUse": [{
    "matcher": "Bash|Write|Edit|MultiEdit|Grep|Glob",
    "hooks": [{"type": "command", "command": "~/.claude/skins/engine/skin-tool-hook.sh"}]
  }]
}

OSC escape sequences do the terminal color work. When activate.sh runs, it writes directly to /dev/tty — bypassing stdout so it reaches the actual terminal emulator rather than getting swallowed by Claude Code's output capture. The sequences look like this:

printf '\033]11;#0D0D0D\007'  # Set background
printf '\033]10;#F5E6C8\007'  # Set foreground
printf '\033]12;#D4A857\007'  # Set cursor
printf '\033]4;3;#D4A857\007' # Set ANSI color 3 (yellow slot)

On deactivation, the terminal is restored to its default state. This works across iTerm2, Kitty, WezTerm, Ghostty, and Terminal.app.

The personality voice is activated by symlinking a personality file into Claude Code's ~/.claude/output-styles/ directory. Claude Code automatically loads any markdown files it finds there as output style instructions. On skin activation:

ln -sf "$personality_file" "$output_styles_dir/skin-${skin_name}.md"

On deactivation, the symlink is removed. The previous skin's symlink is also cleaned up when switching themes — only one skin personality loads at a time.

The Personality Voice System

This is the part that makes a skin feel like an actual character rather than just a color scheme.

Each skin optionally ships with a personalities/<name>.md file that gets loaded as a Claude Code output style. The key frontmatter field is keep-coding-instructions: true — this tells Claude Code to stack the personality on top of its core engineering behavior rather than replacing it. You get the flavor without losing the function.

Here's what happens when the Noir skin is active. Without any skin:

The test is failing because the mock isn't returning the expected value. I'll update the fixture and re-run.

With the Noir personality loaded:

A witness who won't talk. The mock's returning the wrong value — someone doctored the fixture. I'll set it straight.

The full Noir personality file:

---
name: Noir
description: Hardboiled detective narration — terse, world-weary, Raymond Chandler cadence
keep-coding-instructions: true
---

Narrate like a private eye who's seen too much and billed too little. Your tone is 
world-weary but precise — Raymond Chandler by way of a terminal window. Keep it subtle: 
a sentence of flavor, then get on with the work.

Errors are dead ends. A failing test is a witness who won't talk. A successful build 
checks out clean. Files are evidence. Directories are crime scenes. Dependencies are 
informants — useful, but never fully trusted.

Keep descriptions short. The best metaphors arrive once and leave. Don't repeat the bit. 
You're seasoning, not the main course.

The instruction "You're seasoning, not the main course" is load-bearing. Without it, Claude leans hard into the character and it gets exhausting fast. With it, you get one good line per interaction and then the code gets written.

Other personalities take different approaches. Grimoire uses patient wizard energy — measured, archival, like consulting a very old book. Retro86 channels enthusiastic early-computer-magazine voice. Brutalist has no personality file at all — no voice, no sounds, nothing. Sometimes that's the right call.

Creating Your Own Skin

Copy template.yaml to skins/<name>.yaml and you're most of the way there.

The structure has four main sections:

name: myskin
description: "One-line description"

terminal:
  background: "#0D0D0D"
  foreground: "#F5E6C8"
  cursor: "#D4A857"
  palette:
    black: "#0D0D0D"
    yellow: "#D4A857"
    # ... 8 ANSI color slots total

statusline:
  accent: "#D4A857"
  icon: "◆"
  # bar_fill, bar_empty, dim

branding:
  banner: |
    \033[38;2;212;168;87m██╗  ██╗██╗\033[0m
    # block-letter art with 24-bit ANSI codes
  hero: |
    # braille art (U+2800–U+28FF range)
  welcome: "Message shown on activation"
  goodbye: "Message shown on deactivation"

tools:
  sounds: true
  events:
    file_written: { sound: "Tink", icon: "◆" }
    command_run: { sound: "Pop", icon: "▸" }
    error: { sound: "Basso", icon: "✗" }

Inheritance is the key feature here. You don't need to define every key. If you only care about terminal colors and want to keep the default banner, just define the terminal block. Everything else falls back to default.yaml. A minimal skin that just swaps the color palette is ~15 lines.

For the banner art, I use 24-bit ANSI sequences (\033[38;2;R;G;Bm) so colors can precisely match the palette. The braille art in the hero field uses Unicode braille characters (U+2800–U+28FF) — tools like image-to-braille can convert any image if you want something custom.

To add a personality, create personalities/<name>.md with the frontmatter shown above and write whatever voice you want Claude to adopt.

Test it directly without restarting Claude Code:

~/.claude/skins/engine/activate.sh myskin

What's Next

A few things on the roadmap:

Skin creator toolkit — an interactive CLI that walks you through picking colors, previewing banner art, and writing a personality without hand-editing YAML.

Package manager — a way to install community skins with a single command, something like /skin install @username/myskin.

Composable layers — the ability to mix a personality from one skin with the colors of another. Right now it's all-or-nothing per skin; layering would let you run Noir narration with Nebula colors if that's your thing.

Try It

git clone https://github.com/basicScandal/claude-skins.git
cd claude-skins
./install.sh

Then in Claude Code:

/skin nebula
/skin noir
/skin brutalist

Switching is instant — no restart required.

Gallery | GitHub

The whole thing is MIT licensed. If you build a skin, I'd genuinely like to see it — open a PR or drop it in the issues.