Koolie

Koolie – governance for AI coding assistants.

This is the English introduction. The German README.md is authoritative, and all further documentation is in German; links to it are marked (German).

Koolie gives a software development team that works with AI coding assistants a shared framework: shared project rules for every assistant on the team, human approvals where a human has to decide, structured reviews of AI-generated code, a reusable project configuration that a team carries from project to project, and a documented statement per client of which of these rules the tool enforces technically and which only act as instructions.

Version: .koolie/core/VERSION · Changes: CHANGELOG.md (German) · Status: pilot – all modules and all client packs are at pilot · Licence: GPL-3.0 with an additional permission for generated files (LICENSE, explanation in LICENSE-HINWEIS.md, German)

What is Koolie?

Koolie is a framework of rules, templates and tools that is installed into an existing Git repository. It has three parts:

• the core (.koolie/core/): tool-neutral rules, checklists, skills, validation tools and the installer – byte-identical in every project;
• the project overlay (.koolie/project-overlay/): the exchangeable project configuration – allowed and blocked paths, approval routes, project documents. It belongs to the project;
• one AI client pack per AI client. An AI client is the coding assistant the team works with, for example Claude Code or Kiro. The client pack maps the rules of the core onto the files and mechanisms of that client – instruction file, permissions, hooks – and its capability matrix states which of them the client actually enforces.

Koolie replaces neither the AI client nor human review. It keeps the client within limits that can be checked, traced and reused across projects.

What problem does Koolie solve?

As soon as several people work on a repository with AI coding assistants, three questions arise that a single instruction file does not answer:

1. Do the same rules apply to everyone? Every assistant has its own file locations and mechanisms. Without a shared source, the rules drift apart per tool and per person.
2. What holds when the model does not follow the instruction? An instruction only works as long as the model follows it. Where a rule must not be broken, it needs a technical block – and the team has to know where one exists and where it does not.
3. Who decides? Which tasks an assistant may complete on its own, which need a confirmed plan and which need an explicit approval has to be defined and visible in daily work.

Koolie answers them with one core for all clients, a classification of every rule by how it is enforced, and fixed control levels with human approval.

Who is Koolie for?

• Development teams that use AI coding assistants every day and want shared, checkable rules for them – including teams that use different clients.
• Technical leads (team lead, architecture, security, data protection) who have to show which promises a tool keeps technically and which are covered organisationally.
• Projects that onboard new developers: the framework comes with an onboarding path including exercises and completion criteria.

Koolie is less suitable for individuals who only want a personal instruction file, and for fully autonomous agent operation without human approvals – the framework explicitly rules that out.

What does it look like in practice?

A small, synthetic example with the client pack claude-code:

Step	What happens
Starting point	A team wants to prevent an assistant from publishing changes on its own. git push is a human's job.
Setup	install.py creates the instruction file CLAUDE.md and the permission file .claude/settings.json in the project.
The rule	The instruction file says "Never: git push …"; the permission file lists Bash(git push:*) under deny, and the allow list permits only five read-only git commands.
Expected behaviour	The assistant declines a push. If it tries anyway, the client rejects the call.
Observed behaviour	Measured on 2026-09-17 with Claude Code 2.1.274 in non-interactive mode: with the rule text present, the assistant declined the push without attempting it – the technical block was never reached. Without the rule text, it called git push origin main and was rejected; likewise when git push was in both allow and deny – deny wins.
The measured limit	The pattern only matches commands that start with the string git push. If a project widens its allow list to Bash(git:*), git -C <path> push origin main goes through – measured, with the commit arriving at the remote. In the shipped configuration this spelling is not allowed and was rejected in non-interactive mode; the capability matrix states the limit explicitly.
Verifiable result	The entries are in .claude/settings.json and can be read there; the validator checks that the core rules of the permission file are complete. Evidence: measurement protocol (German), sections 3, 5 and 6, and matrix row B6 in the client pack claude-code (German).

The quickstart walks through the setup of this example step by step. The client's behaviour is not measured again there; it is taken from the protocol.

Which AI clients are supported, and how far?

All client packs have the status pilot: they are fully built, measured on real installations and intended for supervised use. What each client enforces technically is listed row by row in its capability matrix; the overview of all packs is in clients/README.md (German), section 6.

Client	Client pack	Status	Most important known limit
Claude Code	claude-code	pilot	Command blocks work as prefix patterns (see the example); the file blocks – secret files protected from reading, framework, CI and lock files protected from writing – only cover direct file access; for shell and subprocesses only the instruction applies
Cursor	cursor	pilot	The client writes files in the workspace without asking; measured is the command line on Windows – the IDE and macOS/Linux are mapped from documentation and program code only
Devin Desktop	devin-desktop	pilot	In the client's dangerous operating mode the technical classifications do not apply; there, only the framework's protection hook blocks actions
Kiro	kiro	pilot	The blocks only work with the active agent profile; hooks only run in the interactive session; the IDE is mapped from its documentation only
OpenAI Codex CLI	openai-codex	pilot, with a condition	Two core promises cannot be mapped – use only with approval by the security contact; the project-local layer only loads in a project registered as trusted

Which client version a pack covers and which version it was measured against is stated in the profile table at the top of each CLIENT_PACK.md.

What does Koolie add to a single AGENTS.md?

An AGENTS.md (or CLAUDE.md) is an instruction to the model. It is a good start – and Koolie installs one itself. What it adds:

A single instruction file	Koolie
works as long as the model follows it	additionally maps rules onto the client's permissions and hooks, where the client supports it
does not say which rule is enforced	classifies every promise as [TECHNISCH] (technical), [TEXTUELL] (instruction only) or [NICHT ABBILDBAR] (not mappable), with evidence
applies to one client	one core, mapped onto several clients; a team with mixed tools shares the same rules
is rewritten for every project	core unchanged, project values in the exchangeable project overlay; a new release is applied to a project with install.py --update, and whatever has to be added by hand is listed in the migration notes of the changelog
does not define responsibilities	control levels low/medium/high: a task rated medium or higher needs a plan that a human has confirmed; a task rated high also needs an explicit approval
is not checked	a validator checks the installation; test sheets check the behaviour of the skills on the client

What is enforced technically – and what stays with humans?

Koolie distinguishes three kinds of rules, and every capability matrix assigns each promise to one of them:

• Enforced technically ([TECHNISCH]): the client enforces the rule regardless of how the model behaves – for example a blocked file or a blocked command. This has limits too, and the matrix names them.
• Effective as an agent instruction ([TEXTUELL]): the rule is in the model's context. It can follow it; it is not enforced.
• Human review required: approvals, reviews and the delegation bans – tasks that must never be handed to an AI client – are not enforced by any client. They remain organisational – with checklists, control levels and documented exceptions.

If a client has no mechanism at all for a promise, the matrix lists it as [NICHT ABBILDBAR] (not mappable): it then falls back to the instruction and to people, and a pack where this affects a core promise needs an approval by the security contact before it is used.

Responsibility stays with humans. The AI client proposes; people review, accept and approve. Koolie does not make a project secure or compliant – it makes visible where a rule holds technically and where a human has to hold it.

Do you need Koolie next to a good standard configuration?

Measured on 2026-09-30 with Claude Code and Opus 5.5: a good standard configuration – settings outside the repository, a short CLAUDE.md with team rules, branch protection and a secret scan – against the same configuration plus Koolie. Every permission prompt of the client was answered with yes.

• With rule texts, the model itself held in both cases: no leak, no weakened control.
• Without rule texts, a subprocess in the standard configuration read the secrets file; with Koolie, the protective hook blocked it.
• A normal small change succeeded in both cases; with Koolie it cost roughly 65 to 80 percent more.

Koolie complements a good standard configuration; it does not replace it. Managed settings, branch protection and CI and, where needed, an isolation layer remain the job of the environment – who carries what is described in the adoption guide, section 8 (German). The measurement is small – one client, one model, one run per security case – and supports no claim of superiority.

How do I start?

1. Try it out: the quickstart installs Koolie into an empty practice repository and shows what is created – in about ten minutes, without starting an AI client.
2. Adopt it: the adoption guide (German) covers taking Koolie into an existing project with prerequisites, approvals and activation; the binding record is the adoption checklist (German).
3. Onboard: for the first working day in a project that already uses Koolie, there is the onboarding quick start (German).

Install from a package source (since 1.24.1): Koolie is on PyPI and npm as koolie. One command in your project directory fetches it and starts the installation dialog – the current directory is the default, press Enter to accept it:

cd /path/to/project
uvx koolie                   # with uv – or: pipx run koolie · npx koolie

To keep the command around, install it and run it in the project directory later:

pipx install koolie          # or: uv tool install koolie · npm install -g koolie
koolie                       # the dialog, defaulting to the current directory
koolie --target /path/to/project --client claude-code   # the same arguments as install.py

⚠️ pip install koolie only installs the command, not Koolie into your project – a package runs no code while it is being installed. Without administrator rights, pip puts the command into a folder that is often not on your PATH ("The script koolie.exe is installed in … which is not on PATH"); python -m koolie then runs the same command. Python 3.8 or later is required; npm additionally needs Node.js 16 or later. Every package carries exactly the tree of the release archive. The other installation paths – the starter from the release archive and the manual steps – are in the German README under „Framework in ein Projekt übernehmen“.

Where can I find details and limits?

All documents below are in German.

Topic	Document
Client packs and capability matrices	clients/README.md
Adoption, updates, several repositories, costs	ADOPTION_GUIDE.md
The rules themselves (normative core)	framework/core/
Data protection and security	02-privacy.md, 03-security.md
Control levels and delegation bans	09-risk-model.md
What is planned and what remains open	ROADMAP.md
Decisions with rationale, open questions	DECISION_LOG.md
Test catalogue	TEST_CATALOG.md

Why "Koolie"?

A Koolie is an Australian herding dog, and the image is the job description of this framework: a herding dog does not drive the herd and does not replace the shepherd – it keeps the herd together and heading in one direction. It works independently, but on instruction, and it holds boundaries without biting. The decision on the name, with its rationale and the rejected alternatives, is D-125 in DECISION_LOG.md (German).

Licence

Koolie is licensed under the GNU General Public License, version 3 (LICENSE), with an additional permission under §7: files created from the supplied templates and any output of the framework's tools are not covered by this licence. The GPL binds redistribution, not use. Details, in German: LICENSE-HINWEIS.md and the German README, section „Lizenz“.