Klaussy-Agents

Write once, align everyone. Keep your conventions in one central CLAUDE.md and let klaussy compile it into native rules, settings, and skills for Claude, Gemini, Cursor, Copilot, Codex (OpenAI), Google Antigravity, Cline, Aider, OpenCode, and Kimi across GitHub, GitLab, and Bitbucket repositories.

Designed by an ex-GitHub, ex-Twitch, and ex-Microsoft engineer, klaussy is a multi-agent repository boilerplate generator. With a single command, it scaffolds conventions, repo-namespaced skills, stack-appropriate settings, and interactive guardrails for ten major AI coding environments across GitHub, GitLab, and Bitbucket—matching each agent's native file formats and capability profiles.

📣 Out of stealth. klaussy has been six months in the making — developed in private and hardened by a hands-on group of testers wiring it into their own repos and daily agent workflows. After months of iteration and real-world use, it's now open to everyone.

⚡ Quick Start

Two ways in. Both end with a klaussified repo.

Let your agent do it. gh skill install drops the entry-point skills into whichever agent you already use, and they install the CLI for you if it isn't there:

gh skill install steph-dove/klaussy-agents --all --agent claude-code

Then run /klaussy-init in your repo. --agent also takes cursor, codex, gemini-cli, github-copilot, opencode, kimi-cli and others — see gh skill install --help for the full list.

Or drive the CLI yourself:

pip install klaussy-agents
cd your-repo
klaussy init

Auto-detects your base branch and stack, then scaffolds all targets. To target specific agents, run klaussy init --agents claude,cursor.

Then use the skills. Every one is namespaced to your repo, so in a repo called payments-service you'd hand a whole task to the owl:

/payments-service-rest-of-the-owl https://linear.app/acme/issue/PAY-1234
/payments-service-rest-of-the-owl add a --dry-run flag to the reconciler CLI

A ticket link or a plain description both work. See Using the skills for the naming rule and the rest of the set.

👀 See the actual output

Two real repos, scaffolded and committed so you can read what klaussy init writes before running it on your own code — no install required:

Worth opening: a generated review skill with the repo's own rules injected into it, the Copilot instructions with applyTo matchers, and the commit guard as it lands in a repo. Every supported agent's directory is in there — see examples/README.md for the full map and how to reproduce it.

🤖 Supported Agents & Targets

klaussy translates your canonical repository conventions (CLAUDE.md) and workflows into native formats optimized for each agent's directory placement, scoping mechanisms, and capability boundaries:

• 🤖 Claude Code: Native .claude/skills/, .claude/settings.json allow/deny-lists, and active local read/fetch hooks.
• 🌌 Google Antigravity: Cross-agent AGENTS.md project-level rules, plugin-based path rules with glob triggers (rules/*.md), native hooks, and IDE-compatible permissions.
• 💻 Cursor: Interactive MDC rules (.cursor/rules/*.mdc) with auto-apply matching, terminal permissions allow-list, and .cursorignore read blocks.
• 🐙 GitHub Copilot: Instructions with custom applyTo file matchers (.instructions.md), and skills nested in .github/skills/.
• ♊ Gemini CLI: Hierarchical GEMINI.md scoping (loaded only when touching subdirectories), settings tool allow-lists, and .geminiignore filtering.
• 📜 Codex CLI (OpenAI): Structured AGENTS.md root-and-nesting rules, generic skills, and .codex/config.toml sandbox configurations. This is OpenAI's coding agent — if you work in GPT-5.x through Codex, this is your target.
• 🧬 Cline: .clinerules/ Markdown rules with paths: glob activation, event-named .clinerules/hooks/ guards (commit, read/web-injection, plan guidance), and .clineignore read blocks.
• 🛩️ Aider: Flat CONVENTIONS.md wired in via .aider.conf.yml's read: key, auto-lint/lint-cmd + test-cmd gating, and .aiderignore read blocks. Model-agnostic — point it at any model, including a local Ollama one. (No skills/hooks: aider has neither mechanism.)
• 🔓 OpenCode: Root AGENTS.md conventions plus modular .opencode/rules/*.md path rules wired via opencode.json's instructions glob, .opencode/skills/, last-match-wins permission read/bash rules in opencode.json, and a Bun plugin (.opencode/plugins/klaussy.js) that bridges tool hooks to the shared Python guards.
• 🌙 Kimi Code CLI (Moonshot / Kimi K2): Flat .kimi-code/AGENTS.md conventions (Kimi reads no nested AGENTS.md, so path rules are inlined under their globs, with the pre-plan guidance appended) and .kimi-code/skills/. Hooks and permissions are a special case: Kimi loads [[hooks]] and [[permission.rules]] only from the user-level ~/.kimi-code/config.toml, so klaussy commits the guards to .kimi-code/hooks/ and writes paste-in snippets (klaussy-hooks.toml, klaussy-permissions.toml) beside them. Paste once and the guards run against whichever repo the session is in.

A note on models vs. agents. These targets are agent tools, not model vendors — klaussy writes the files each tool reads, so what matters is which CLI or IDE you drive, not which model answers. OpenAI's agent is Codex CLI, so that's where GPT users point klaussy. Aider and OpenCode are model-agnostic and will happily run GPT, Claude, Gemini, Kimi, or a local Ollama model behind the same scaffolding.

🛡️ Supercharged Hooks & Guardrails

klaussy installs cross-agent, dialect-tolerant guard scripts that intercept agent tool actions (terminal runs, file reads, web requests) at the boundary. They block unsafe commands via exit 2 and stderr, which all supported agents respect:

1. Prompt-Injection Guard (read_guard.py)

Intercepts and neutralizes prompt injection. Scans the content of any file being read locally or fetched from the web (on supported agents like Claude and Antigravity) for malicious instructions. Stops external data from hijacking your agent's current task context.

2. Comment Humanizer (comment_guard.py)

Keeps commits and pull/merge request comments clean. Intercepts outgoing comments on GitHub (gh pr comment, gh pr review, gh issue create, …) and GitLab (glab mr note, glab mr create, glab issue update, …), scrubbing AI filler words, robotic formatting, and chatty openers before they post. On Claude the body is rewritten in place and the command runs cleaned; every other agent gets the post blocked once with the humanized command handed back to re-issue.

The scrubber only removes mechanical tells, so it says so and points at the <repo>-humanize skill for anything that needs actual rewriting. Bitbucket is not covered: it has no comment CLI, so posts go through curl against the REST API, and a guard that silently missed half of those would be worse than none. Scrub with <repo>-humanize before posting there.

3. Pre-Plan Guidance (plan_guidance.py)

Injects strict guardrails (e.g., minimal lines changed, no over-engineering, write tests first) directly into the agent's plan step before it begins modifying files, preventing scope creep.

4. Git Commit Guard (commit_guard.py)

The last gate before an agent writes to your history. Not a linter wrapper — these run in order, and the first failure blocks the commit:

Nothing outside your staged files is ever judged, and klaussy's own checks — secrets, comments, imports — narrow further to the lines you changed, so a pre-existing secret or comment block elsewhere in a file you touched won't block you. Your project's own format and lint run against the whole staged file, as they would anywhere. The formatter never rewrites the tree outside your diff.

It fails open, deliberately. A missing tool, an unparseable payload, or any unexpected error allows the commit rather than blocking it — a guard that crashes shut would deny every tool call on some agents. git commit --no-verify skips the gate outright, same as git's own hooks.

5. Dependency Speed Bump (dependency_guard.py)

Catches package-manager commands that add a new named dependency (pip install requests, npm install lodash, poetry add x, …) and blocks once, asking the agent to confirm the package is actually needed and not coverable by the stdlib or an existing dep. Ignores manifest syncs (npm ci, pip install -r, uv sync) that add nothing new.

6. Self-Review Nudge (self_review_guard.py)

Prompts the agent to run a last-pass self-review of its own diff before declaring an implementation done, closing the loop with the <repo>-self-review skill.

🚀 Advanced Repository-Scoped Skills

Every generated skill is namespaced to your repo, carries an auto-trigger description, and is adapted to the agent's capability profile (such as mapping Claude's parallel subagent tools to Codex/Cursor/Antigravity equivalents). Skills that touch a ticket, a pull/merge request, or CI are also adapted to your hosting provider, detected from origin: a GitHub repo uses gh pr commands, a GitLab repo ships glab mr commands and discussion semantics, and a Bitbucket repo uses REST API endpoints and pipeline checks. A provider klaussy can't identify (a self-hosted install on a neutral hostname) gets a block that tells the agent to ask rather than guess at an API.

Also bundles skills for commit, pr, implement, refactor, explain, test, new-worktree, worktree-cleanup, fix, deps, address-review, document, release, session-context, and adr-generator.

_{🥚 And <repo>-slop-coded — the evil twin of humanize that turns clean prose into maximal AI slop. For laughs and stress-testing the scrubber; never run it on a deliverable.}

⚙️ How it Works under the Hood

1. Discover: Wraps klaussy-repo-conventions to auto-analyze your codebase and compile CLAUDE.md.
2. Translate: Parses rules and dynamically injects them into the <repo>-review skill so reviews check path-scoped rules.
3. Scaffold: Detects your stack (Python, Go, Node, Rust, Make) to generate custom permissions (settings.json, config.toml) and allowed tool prefixes, and detects your hosting provider from origin to substitute the matching forge commands into the skills that need them.
4. Isolate: Writes .cursorignore, .geminiignore, .clineignore, and .aiderignore with secret-excluding patterns, alongside the deny rules in each agent's settings — agents vary in how much they respect .gitignore, so klaussy does both.

🖥️ Cross-Platform Support

klaussy runs on macOS, Linux, and Windows, and its hooks are built so you never have to think about the OS. The guard scripts read stdin as UTF-8 (so a Windows cp1252 locale never chokes on an em-dash) and resolve tools via PATH honoring Windows PATHEXT (so .cmd shims like npm/eslint run).

The tricky part is that a committed hook command can't portably name a Python interpreter — python3 is absent on a stock python.org Windows install, and python isn't guaranteed on Linux/macOS. So the guards are launched through klaussy-hook, a pip console script installed on PATH on every OS (klaussy-hook.exe on Windows) that runs the guard under klaussy's own interpreter. The committed command names no interpreter at all, so it works the same regardless of which machine scaffolded the repo — no per-OS config, nothing to adjust. (klaussy is already needed at runtime by the comment and commit guards, so this adds nothing to install.)

• Cursor / Antigravity run guards via the interpreter/shebang their docs describe; their Windows hook execution isn't documented, so treat it as best-effort until confirmed.
• Codex's Windows variant resolves the repo root via the same git rev-parse the POSIX command uses; it assumes a POSIX-compatible or PowerShell hook shell.
• Kimi's hooks live in the user's global config, so the command can't hardcode a repo path — and its four-field hook schema (an unknown key fails the whole config load) leaves no room for a per-OS override or a shell one-liner. klaussy-hook --repo-relative <path> resolves the enclosing repo inside the launcher instead, and fails open in repos klaussy hasn't scaffolded, so one global entry stays correct everywhere and inert where it doesn't apply.

🔧 Installation & Usage

As a CLI

pip install klaussy-agents
klaussy init

Using the skills

After klaussy init, the skills are in your repo and invoked by name. The name is always <your repo name>-<skill>, lowercased with anything that isn't a letter or digit turned into a hyphen — so My_App becomes my-app-review, and Payments Service becomes payments-service-review.

You don't have to remember which repo you're in: every skill also answers to klaussy-<skill>, so "run klaussy-review" works the same as /my-app-review. The agent resolves the alias; the slash command itself is still the repo-namespaced one, since agents take it from the directory name.

/<your repo name>-rest-of-the-owl <task link or description>

Hand it a ticket URL or type the task out, and it runs the whole loop: plan, implement, test, self-review, QA with evidence, open a humanized PR, then poll CI and review until the PR is green. It stops before merging, so you keep that button.

The ones you'll reach for daily:

/<repo>-review                      # senior-level review of the branch
/<repo>-debug the checkout total is wrong for EU orders
/<repo>-restack                     # rebase a stack of dependent PRs
/<repo>-split-pr                    # carve a too-big branch into a reviewable stack
/<repo>-grant-permissions           # stop the agent asking about routine commands

Most skills also trigger on their own when the work matches — describe a bug and debug picks it up. The ones that touch anything outside your working tree (commit, pr, release, restack, split-pr, new-worktree, worktree-cleanup) confirm the plan with you before they act, so naming one in prose reaches it without it running off on its own.

On other agents the same skills land in that agent's own directory (.cursor/skills/, .gemini/skills/, .opencode/skills/, .github/skills/, .agents/skills/) and you invoke them however that agent invokes skills. The slash form above is Claude Code's.

With gh skill install

Covered in the Quick Start. It installs two skills, klaussy-init and klaussy-update; ask for either by name instead of --all.

The 28 repo-scoped skills aren't published this way on purpose: each one is namespaced to your repo and carries your conventions, base branch, and forge commands, so klaussy init generates them rather than copying them in.

As a Claude Code Plugin

/plugin marketplace add steph-dove/klaussy-agents
/plugin install klaussy@klaussy

This brings the klaussy-init and klaussy-update skills plus the MCP server. The plugin needs no prior klaussy install — its server starts through a launcher that prefers an install you already have and otherwise resolves klaussy-agents[mcp] through uvx or pipx. The launcher runs under python3; python.org's Windows installs expose that as python, so install klaussy directly there.

As an MCP Server

The server lives behind the optional mcp extra, so ask for that rather than the bare package. A plain install puts klaussy-mcp on PATH but leaves out what it imports, and the client reports the crash only as a closed connection:

pip install 'klaussy-agents[mcp]'

Then add to your project's .mcp.json:

{
  "mcpServers": {
    "klaussy": {
      "command": "klaussy-mcp",
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

Nothing installed at all? Point the config at a runner and it resolves the package on first use:

{
  "mcpServers": {
    "klaussy": {
      "command": "uvx",
      "args": ["--from", "klaussy-agents[mcp]", "klaussy-mcp"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

The Claude Code plugin already does this for you.

Removing it again

klaussy uninstall --dry-run   # show what would go
klaussy uninstall             # do it, after confirming

Removes the generated skills, guards, hooks and ignore files. .gitignore and each agent's settings are edited rather than deleted, because klaussy merges into those and they usually hold your own entries too — anything klaussy can't prove is its own is reported and left alone. Conventions docs (CLAUDE.md, GEMINI.md, AGENTS.md, CONVENTIONS.md) survive by default since they get hand-edited; --all takes those too and returns the repo to its pre-klaussy state. The package stays installed either way — pipx uninstall klaussy-agents removes that.

There's a /klaussy-uninstall skill that drives the whole flow, including the preview and the optional package removal.

Programmatic Python API

from klaussy import toolkit

# Scaffold a repo programmatically
toolkit.init(repo=".", agents=["claude", "cursor"])

📋 Requirements

• Python 3.10+
• klaussy-repo-conventions >= 1.6.0
• Claude Code CLI (optional, for --init enrichment)
• mcp (optional, for MCP server support — the klaussy-agents[mcp] extra)

📜 Changelog

See CHANGELOG.md for the full release history, including what landed in the current release.

⚖️ License & Governance

• License: MIT
• Governance: klaussy is an open-source project owned and maintained by Dovatech LLC (founded and owned by Stephanie Dover).