Make your codebase safe for AI agents in one command

The problem isn't that agents are bad. It's that they fail the same way every time.

AI coding agents are fast. If you've reviewed enough agent-written diffs, though, you've seen the same short list of failures show up again and again:

• A dropped await that turns an async call into a race you only find in production.
• as any sprinkled in wherever the types didn't line up.
• An import from a package that isn't in package.json.
• A try/except: pass wrapped around failing code to make a red test go green.
• Once in a while, a git reset --hard that eats uncommitted work.

You can keep catching these in review, one diff at a time, forever. Or you can make the codebase itself push back the moment the agent writes them. That second option is what agent-starter sets up, and most of it lands in one command.

One command

/plugin marketplace add sneg55/agent-starter
/plugin install agent-starter@agent-starter

That wires five enforcement hooks and loads eight slash commands. Then you point it at a codebase: /new-project for a fresh repo, /adopt-project to retrofit an existing one (it audits first, everything is opt-in, nothing gets overwritten).

The rest of this post is what that command actually does, and why each piece is there.

Guardrails that fire while the agent works

Claude Code hooks run shell scripts at defined points in the agent's loop: before a Bash command, after a file write, at session start. agent-starter ships them as small, dependency-light bash scripts. The ones that earn their keep:

Block the commands you can't undo

block-dangerous-commands.sh runs before any Bash command executes. It blocks the short list of things that destroy work you can't get back:

• git push --force (it points you at --force-with-lease instead)
• git reset --hard / --merge
• git clean -f, git checkout -- ., git restore .
• recursive rm on /, ~, or $HOME
• chmod -R 777 /

When it fires, the agent sees this on stderr and stops:

Blocked dangerous command:
  git push --force origin main

Why: 'git push --force' rewrites remote history - use --force-with-lease.

There's an escape hatch (CLAUDE_ALLOW_DANGEROUS=1) for the rare time you actually mean it. The goal isn't to babysit. It's to make the destructive path require a deliberate override instead of a stray token in a long autonomous run.

Refuse silent error handling

check-silent-errors.sh runs after every write. LLMs reach for try/except to make a failing test pass, but the code still breaks, just quietly, in a way nobody notices until later. The hook blocks the patterns that swallow errors:

• bare except:, except: pass, except: ... in Python
• empty catch {} in JS/TS
• a catch block whose only body is console.log (logging an error at info severity is still swallowing it)

Every handler has to do something real: re-raise, return a sentinel, or log with context via console.error. One-off exceptions are explicit. You drop a // silent-ok (or # silent-ok) comment and the hook leaves that site alone. Because the exemption lives in the diff, it shows up in review instead of hiding.

Lint as a feedback channel, not a gate

This is the idea worth stealing even if you take nothing else from the repo.

Most projects treat lint as a CI gate: the agent writes a whole feature, opens a PR, CI goes red, and by then the agent has moved on to something else. The correction is expensive and out of context.

agent-starter runs lint on every single edit. lint-on-edit.sh runs biome check --write then eslint --fix on just the file the agent touched, and pipes any remaining errors back on stderr. The agent reads them on its next turn and fixes them while the context is still warm. Python gets the same treatment with ruff check then ruff format.

The ruleset is tuned for the mistakes agents actually make, not for taste:

• Async correctness is Tier 1, error-level: no-floating-promises, no-misused-promises, await-thenable. That's the dropped-await class, caught at write time.
• Import resolution catches hallucinations: import/no-unresolved flags an import from a package that doesn't exist; import/no-extraneous-dependencies flags one that isn't declared.
• no-explicit-any plus the no-unsafe-* family close the as any escape hatch, so the agent has to fix the type shape instead of routing around it.
• Suppressing a rule requires a written reason (require-description), so an eslint-disable can't quietly become the path of least resistance.

And a deliberate omission: no max-lines. Line caps punish coherent long code (a reducer, a parser, a JSX-heavy component) and reward the agent for shredding logic into single-use helpers that only make sense read together. Cognitive complexity, capped at 15, measures the thing you actually care about.

Biome owns formatting and the fast syntactic rules (it's 10 to 100 times faster than ESLint); ESLint owns the type-aware rules that need the compiler. You get the speed on every keystroke and the depth where it counts.

The quieter two

check-file-size.sh warns when a file crosses a size target, since oversized files are where agents lose the thread. check-codebase-health.sh runs at session start so the agent opens with context instead of discovering problems mid-task. There's also an opt-in read-before-edit guard (./install.sh --with-read-guard) for older setups; recent Claude Code enforces read-before-edit natively, so it's left out of the default install on purpose.

Durable context: CLAUDE.md and the memory taxonomy

Guardrails stop bad writes. Context prevents them. The CLAUDE.md template ships a 4-type memory system so what the agent knows about your project is structured, not a scratchpad:

Type	Holds
user	who you are: role, preferences, level
feedback	how to work: corrections and confirmations, with the reason why
project	what's happening: ongoing work, decisions, deadlines
reference	where to look: pointers to Linear, Grafana, Slack

Two rules keep it honest. Never store what's derivable from code or git, because that copy goes stale and starts lying. And convert relative dates to absolute, because "last week" is meaningless three sessions later. feedback memories carry a Why and a How to apply, so a correction you give once keeps applying itself.

The part that's actually new: the codebase learns from itself

Everything above is a good frozen setup. The reason I built this instead of copying a pile of dotfiles is the loop on top.

Most starters are a snapshot. Every project begins from the same rules and never gets smarter about how this codebase is actually used. agent-starter captures that signal and turns it into better rules. Four steps:

 ① signal → ② store → ③ promote → ④ measure → (back to ①)
   ▲                                              │
   └──────────────────────────────────────────────┘

• Signal. Every time a hook blocks or warns (file too big, dropped await, swallowed error, dangerous command), it appends one JSON line to .harness/ledger.jsonl. Logging is best-effort and always exits 0, so it can never break the hook that called it. Your explicit corrections are already captured as feedback memories, which are the highest-value signal of all.
• Store. The append-only ledger holds structured events; the memory files hold prose. The raw ledger is gitignored (local and noisy); only distilled learnings get committed.
• Promote. The /reflect skill reads the ledger and your feedback memories, clusters the recurring mistakes, and proposes concrete changes: a new project rule, a hook-threshold tweak, a lint rule, an ADR. Nothing auto-applies. You approve every change.
• Measure. A stats script computes a recurring_events metric, and each reflection snapshots it to .harness/reflections/. The next reflection can check whether a rule you added last time actually reduced the mistake it targeted, so the loop closes instead of just piling up well-meaning rules nobody validated.

The principle underneath it: signal is private (the gitignored ledger), wisdom is shared (the committed reflections and the rules they produce). A project scaffolded with /new-project is born with this wired in.

Where the patterns come from

The base patterns aren't invented. A lot of them are reverse-engineered from the Claude Code CLI's own source: the file-size targets, the tool-per-directory layout, the lint tiering. Those are marked "derived from Anthropic's Claude Code source" in the repo. The self-improvement loop and the extra tooling are added on top.

Try it

Pick the entry point that matches what you want:

• Everything, one step: the plugin install at the top of this post.
• Just the skills, globally: npx skills add sneg55/agent-starter -a claude-code -g
• Just the hooks in ~/.claude: clone the repo and run ./install.sh. It merges its settings wiring idempotently, so re-runs never duplicate entries.
• No install at all: point an agent at the repo. Give it the URL and say "read this repo and set up my project." It reads the entry file and drives the setup interactively.

Repo: github.com/sneg55/agent-starter, MIT licensed.

If you already work with an AI agent every day, the single highest-leverage piece is lint-on-edit. Move your linter out of CI and into the agent's write loop, and watch how much never reaches review in the first place.