Tools
Clawness
By A Claude Code (and OpenClaw) plugin that injects the right rules relevant to each prompt. Aimed at full stack coding, security, scientific computing, ML and research method (currently 214 rules across 29 domains). Includes: an automated handoff generation process, an access guard, an efficient project memory method, automatic review agents & more!
Install
pip install pyyaml`,Configuration Example
applies_to: {"Next.js": "13-15"} # the versions this was established against
verified: "2026-08" # when someone actually checked
sources: ["https://nextjs.org/docs/app/building-your-application/routing"]README
# Clawness
[](https://github.com/fullymiddleaged/Clawness/actions/workflows/ci.yml)
[](https://github.com/fullymiddleaged/Clawness/releases)
[](LICENSE)
[](https://www.python.org/downloads/)
**Install once. Your coding agent gets the right rules for every task, without you having to mention them.**
Clawness is a plugin for **Claude Code and OpenClaw**, for people who work across many codebases. It puts the relevant rules into context on every prompt โ shipping code or doing research โ so you never have to mention them. What's in the box:
- **214 rules** across 29 domains: coding, plus scientific computing, machine learning, research method, and building with LLMs. Only the ones matching your task get injected.
- **7 adversarial review sub-agents**: security red/blue team, code critic, architecture challenger.
- **A plan-approval gate** before the first edit of a session, on by default.
- **Session security**: an access guard on dangerous tool calls, plus a trust ledger for skills, agents and MCP servers.
- **Session continuity**: a per-project lessons memory, a warning when your context window is filling up, and a handoff the next session picks up on its own.
- **Low token cost.** Only the matching rules are injected, never the whole set, so a typical turn costs about 1,700 tokens instead of the ~35,800 that dumping all 214 rules into CLAUDE.md would cost *every turn*. [How the cost breaks down โ](#retrieval-engine)
Install it once and it works across every project on your machine. Under 1 MB, no services, no models, about 3 ms per prompt.
> **Not just for shipping code.** Clawness also covers scientific computing, machine learning and research method โ 61 rules spanning `science`, `research`, `ml`, CFD, Julia, Fortran, MATLAB and R, injected the same automatic way. See [For Researchers and Scientists](#for-researchers-and-scientists).
Inspired by [infinri/Writ](https://github.com/infinri/Writ), rebuilt from ~2GB of infrastructure to pure Python.
---
## 30-Second Version
Installing the plugin takes **two commands plus a restart**. The plugin downloads its Python backend on first launch, so it isn't fully live until step 3.
**1. Install** (from any Claude Code session):
```bash
claude plugin marketplace add fullymiddleaged/clawness
claude plugin install clawness@clawness
```
**2. Restart Claude Code** (or run `/reload-plugins`) so the hooks actually load.
**3. Let first-run setup finish.** On the first session, a background hook installs Clawness's one dependency (**PyYAML**) into your environment. This needs **Python 3.10+ on your PATH** and takes a few seconds. Retrieval is pure-Python lexical and concept matching, so there are no models to download.
**4. Verify** by asking Claude:
```
what clawness rules do you see in your context?
```
If it describes the injected rule block, you're live. (`/clawness:status` also works.)
> `clawness@clawness` isn't a typo. It's `plugin@marketplace`, and both happen to be named *clawness*. No Python 3.10+? See [Installing Python](#installing-python-if-you-dont-have-it). Without it, the plugin installs but injects nothing โ Claude will say so on your first session.
---
## What Problem Does This Solve?
Clawness makes your agent work the way you do: **the right rules in context on every prompt, without you mentioning them, and without paying for the ones that don't apply.** The same retrieval surfaces your project's recorded lessons, so that file can grow for years at no extra per-prompt cost, and the plan gate, guard and review agents ride the same hook. One install, ~2 ms overhead, no infrastructure โ code and research alike.
None of that is built in: on its own, the agent forgets your conventions between turns, trusts every tool call you've allow-listed, and gives you no cheap way to enforce a standard or rein in a runaway edit. Clawness fills each gap, per prompt.
Take coding rules: *"parameterized SQL only," "async I/O end-to-end," "API responses use the envelope format."* Without Clawness you either dump them all into CLAUDE.md (wastes tokens, dilutes attention every turn) or mention them by hand (you forget, Claude forgets). Clawness scores every rule against your task and injects only the few that fit, plus an always-on mandatory set โ so a full-stack developer moving between frontend, backend and SQL in one session always has the right rules and never the rest.
The same hook carries the rest of what's [in the box](#clawness): a lessons memory that's **searched, not dumped**, a plan-first gate, session-security guards, output compression, context-and-handoff continuity, adversarial review agents, and a model-tier check. Each is covered in detail under [Using It](#using-it) below.
**Make them *your* standards.** The 214 built-in rules are a starting point. Add your own in seconds: run `/clawness:add describe your rule` and Clawness writes the tagged YAML for you (asking before it saves), or drop `.yml` files in `.clawness/rules/`. Commit `.clawness/rules/` and `.clawness/memory.md` and your whole team shares the same rules and lessons. โ [Per-Project Setup](#per-project-setup) ยท [Writing Rules](#writing-rules)
> **Tripwire, not a sandbox.** The guard works by pattern-matching the agent's own tool calls. It catches honest mistakes, copy-pasted `curl โฆ | sh`, reads of secrets outside your project, and data sent to a server that appears nowhere in your code, and it breaks the habit of approving everything without reading it. Someone determined can still disguise a command to get past it. The real protection is a container with a list of servers it's allowed to reach. It stays out of normal work: reading your own `.env`, plain API GETs, and traffic to your own machine aren't prompted. A call to an outside server that carries data or a token asks once per server. Disable with `CLAW_NO_ACCESS_GUARD=1`.
---
## How It Works
```
You type a prompt in Claude Code
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Hook: UserPromptSubmit โ fires automatically before Claude sees your prompt
โ hooks/claude_hook.py โ
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โโโโโโโดโโโโโโโ
โผ โผ
โโโโโโโโโโโ โโโโโโโโโโโโ
โ GLOBAL โ โ PROJECT โ global rules from ~/.claude/clawness/rules/
โ rules โ โ rules โ project rules from <project>/.clawness/rules/
โโโโโโฌโโโโโ โโโโโโฌโโโโโโ
โโโโโโโโฌโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ BM25 + TF-IDF + RRF โ hybrid lexical retrieval + concept expansion
โ + concept expansion โ picks the top rules in ~3ms (pure Python)
โ context budget: 4000 โ stops adding rules when token budget is full
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Claude Code โ sees: mandatory rules (always)
โ (your agent) โ + relevant ranked rules (per-prompt)
โ โ + your original prompt
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**In plain terms:** for each prompt, Clawness scores every rule by how well it matches your task, using shared keywords *and* concepts (login โ auth โ jwt bridges synonyms), then adds the few that fit plus the always-on mandatory ones. No models, no downloads, about 2 ms, and you never touch any of it.
**Two layers of rules:**
- **Global** (`~/.claude/clawness/rules/`): installed once, applies to every project.
- **Project** (`<your-project>/.clawness/rules/`): optional, layers on top for project-specific conventions. Commit to git so your whole team shares them.
### Retrieval engine
Pure Python, one dependency (PyYAML). No ML models, no embeddings, no services, nothing to download at query time:
- **BM25-Okapi and TF-IDF cosine, combined with Reciprocal Rank Fusion.** Two well-established word-matching methods that fail in different places, so a rule gets found whether your prompt shares its exact terms or just its general vocabulary.
- **Concept expansion (26 concept groups)** maps synonyms onto shared markers: `login โ auth โ jwt โ session`, `postgres โ db โ query`, `unwrap โ error โ exception`, applied to both the rules and your prompt. This is the "different words, same idea" reach a vector model gives, but instant and dependency-free. (Extend `_CONCEPT_GROUPS` in `clawness/core.py` to widen it.)
- **Light stemming** collapses plural and verb forms (`caches` โ `cache`, `maintained` โ `maintain`).
- **Mandatory rules** are always injected; the rest are ranked and capped by a token budget.
- **Your project memory is searched the same way.** `.clawness/memory.md` isn't pasted into context. It goes through the same search described above, so only the lessons that match your prompt are injected and a long log stays a few lines per turn. See [Project Memory](#project-memory-lessons-learned).
**Measured quality.** Run `clawness eval`: against 246 test questions with known right answers, **MRR@5 = 0.990** and **hit-rate = 1.000**, meaning every question found its expected rule, usually as the first result. CI enforces minimums on both, so search quality can't get worse unnoticed as rules are added.
**Cost.** About **2 ms per prompt**, and roughly 850 tokens of always-on mandatory rules, plus the few matched rules. The mandatory ones are written out in full on the first prompt and every fifth prompt after that; in between they're shortened to a single line listing their ids, since they haven't changed. Run `clawness stats` for your exact per-turn estimate.
---
## Install
### Installing Python (if you don't have it)
Clawness needs **Python 3.10+** on your PATH. Check first:
```bash
python --version # or: python3 --version
```
If that prints `3.10` or higher, you're set, so skip to O
... (truncated)
tools
Comments
Sign in to leave a comment