Independent · live
AI Stones: an AI harness for Claude Code
Markdown skills, guardrail hooks and JSON settings that protect and improve how Claude Code operates in a project, installed per project and safe to re-run.

Problem
A coding agent working in a real repository has two operational problems. It can do damage: delete files, touch what it shouldn’t, commit half-finished work, merge or publish code that never passed CI. And it works below its best: without the project’s commands, conventions and guidance, every session rediscovers how to build and test, and drifts from how the team writes code. AI Stones is a harness around the model that handles both: hooks that protect, skills and settings that improve, installed per project with one command, npx ai-stones init.
Constraints
- Any stack: it has to read what the project already is (languages, frameworks, package manager, monorepo tooling, test, lint, typecheck and build commands, formatters, commit style), not assume one.
- Never clobber people’s work: teams edit generated files; a re-run must not overwrite them silently.
- Small context: everything loaded on every prompt costs tokens, so most guidance has to load only when a task needs it.
- Guardrails without friction: protections must stop real damage without blocking normal work, or people turn them off.
- Zero install: the installer runs with
npx, with no registry token.
Architecture
Diagram source (Mermaid)
flowchart TB
session[Claude Code session] --> protect[Protection hooks · access guard, rm, atomic commits, CI gate]
session --> quality[Quality hooks · complexity, naming, format]
session --> memory[Memory hooks · history, code graph]
session --> skills[Skills · 24 Markdown guides]
session --> settings[Settings · JSON permissions, MCP]
session --> brief[AGENT.md · project brief]
init[npx ai-stones init] --> protect & quality & memory & skills & settings & brief
init -.-> state[stones.json · answers and file hashes]The harness is mostly text and configuration: 24 skills written in Markdown, JSON settings and permissions, and 13 small hook scripts that Claude Code runs around its tool calls. The hooks fall into three groups. Protection: an access guard, a block on rm, atomic-commit protection, and a workflows gate. Quality: complexity, naming and formatting checks. Memory: session history and a code graph.
init detects the stack first (npx ai-stones detect prints it as JSON), asks only for what it cannot infer, such as purpose, architecture, security conventions, branching and TDD preferences, and which hooks, skills, plugins and MCP servers to include, then installs only what was selected: a short AGENT.md brief imported by CLAUDE.md, .mcp.json, and .claude/ with settings, hooks, skills, slash commands such as /roadmap, and project tools.
Key decisions
- Guides as skills, not one big prompt. Putting every guide in
CLAUDE.mdwould load all of it on every prompt.CLAUDE.mdimports a shortAGENT.md; the rest is installed as Claude Code skills, whose full instructions load only when a task matches. - Safe to re-run, by hashing what it wrote. Overwriting on every run would destroy edits; refusing to touch existing files would freeze the setup.
stones.jsonstores the answers and a hash of every installed file, so a re-run updates unedited files, preserves and reports edited ones, and merges settings.--forceis the explicit opt-out. - Settings from the actual project. Permissions and sandbox domains follow the detected commands and ecosystems, and framework plugins are offered only when relevant, instead of a permissive default that fits nobody.
- Guardrails on by default, process opt-in. Lightweight guardrails, atomic-commit protection and a workflows hook are selected by default. That hook blocks merges, package publishes and releases until a full local CI run has passed for the current code. Heavier process gates, history recording and the code graph are opt-in.
Results
- Latest version on npm
- 3.2.0