🇩🇪 Deutsch · 🇬🇧 English · 🌐 Repo root (this page)

🚧 Work in Progress. This framework is actively developed. Structure, docs and features may change. Feedback welcome via Issues.

claude-rails

Stop fighting Claude. Start shipping with it.

Claude without the chaos — the setup serious Claude users
wish they had from day one.

A file-based framework that gives Claude Code persistent memory, project structure, safety guardrails and extensible skills — so it works with your projects instead of forgetting everything between sessions.

For anyone who juggles multiple projects in parallel and wants Claude to actually keep up.

⚠️ Use at your own risk. This framework writes into ~/.claude/, creates ~/CLAUDE.md, installs hooks and modifies settings.json. Backups are made but no rollback guarantee. Recommended: dedicated Pi or fresh test user account.

⚠️ Claude can hallucinate. Always verify critical outputs. See EN/docs/11-trust-but-verify.md.

✨ Features

	Feature	What it does
📁	CLAUDE.md Cascading	Project context survives across sessions — global → project → sub-project, automatically loaded
📐	Master Template	7 mandatory sections per project. Convention over configuration — Claude knows where everything goes
🛡	Project Boundaries	PreToolUse hooks enforce write isolation. Sessions can't mess with other projects
⚡	Skills	Extensible slash commands (`/crnote`, `/crdiscard`, `/crdiary` ...) — add your own
🗑	Disposable Sessions	Mark & auto-delete throwaway sessions. Keep your `--resume` list clean
📝	Central Scratchpad	Cross-project notes via `/crnote` — ideas never get lost
🔍	Fresh-Eyes Review	Spawn a zero-context agent to catch what a loaded session can't see
🚦	Houston Mode	Safety switch: "Houston on" → analyze only. "go" → execute. One word to prevent disasters
🧹	Hat Counter	Fun bet tracking between you and Claude. Because guardrails should have personality

💡 Why a sandbox?

Claude Code in full autonomy needs an isolated environment — don't risk your main machine. Pick what fits:

Option	Cost	Notes
Raspberry Pi 4/5	~80 €	Dedicated hardware, our reference setup. Setup guide
VM (Proxmox, VirtualBox, UTM)	Free	Any spare machine or your Mac/PC
Docker	Free	Synology NAS, any Linux host
WSL2	Free	Windows — runs Linux natively
Fresh Linux user	Free	`adduser claude-sandbox` on an existing box

The framework uses chattr +a (Linux kernel feature) for INBOX hardening. Works out of the box on any Linux. macOS/Windows without WSL needs workarounds.

⚡ Real-world wins

🚀 Tender response 4× faster — Upload price list + datasheets, Claude fills your tender in Excel format. Was 4h, now 1h. Sample template
🧠 Knowledge base that researches itself — Dump meeting notes, Claude sorts them into the right folders. Workflows
🛡 Safe sandbox on a 80 € Pi — Full autonomy without risking your main machine. Setup

📚 Examples

🏢 Work/ — Stakeholder-centric knowledge base. Sales, consulting, project management.

🏠 Home_Automation/ — PV, heat pump, sensors, automation flows.

🌐 HomeNet/ — Tiny 5-file project. Proves the framework scales down.

📔 Tagebuch/ — Diary/blog. See it live at trazer.online.

🛠 Skills

EN Command	DE Command	Purpose
`/crnote`	`/crnotiz`	Append to central scratchpad (or show list)
`/crdiscard`	`/crwegwerfen`	Mark session for deletion on exit
`/crkeep`	`/crbehalten`	Undo `/crdiscard`
`/crdiary`	`/crtagebuch`	Create a bilingual blog entry from session context
`/crhatreport`	`/crbesenreport`	Show hat counter score and history

Skills live in ~/.claude/skills/cr-*/SKILL.md — drop your own in, they just work.

🏗 Architecture at a Glance

~/CLAUDE.md                          Global rules (style, keywords, project overview)
  ↓ cascading
~/Project/CLAUDE.md                  Project rules (7 sections, imports master template)
  ↓ @import
~/.claude/schablonen/master_template.md   Structure + maintenance rules (shared)
  ↓ enforcement
~/.claude/hooks/                     Boundary hooks, session capture, cleanup
  ↓ actions
~/.claude/skills/cr-*/               Slash commands (note, discard, diary, ...)

Details: EN/docs/02-architecture.md

🚀 Quickstart

git clone https://github.com/trazer-labs/claude-rails.git
cd claude-rails
bash install.sh          # asks DE or EN, handles the rest

Fresh Pi? Run bash EN/onboarding/bootstrap.sh first. Details: EN/PREREQUISITES.md.

📦 What the installer does

Backs up everything before touching it (timestamped backup dir)
Diff-based skill updates — detects your local changes, never silently overwrites (creates .upstream for manual merge)
Auto-cleans old commands — migrates deprecated /commands/*.md to the new Skills system
Wires hooks into settings.json — boundary enforcement, session capture, cleanup
Sets up INBOX with chattr +a — kernel-level append-only protection

📖 Documentation

#	Topic
1	Principles	Core ideas on one page
2	Architecture	Three layers, cascading, why pointers
3	Master Template	The 7 sections explained
4	Maintenance Rules	How the system stays consistent
5	Houston Mode	The safety switch
6	Project Boundaries	Write isolation + kernel hardening
7	Disposable Sessions	Mark, delete, clean
8	Keywords Workflow	"save", "done", "brainscan"
9	Consistency Check	Superadmin structure audits
10	Scratchpad	Cross-project notes
11	Trust but Verify	The hallucination discipline
12	Fresh-Eyes Review	Zero-context review pattern
13	Service Persistence	systemd + registry pattern
14	Graphify Integration	Knowledge graph for smarter navigation ✨ new

🇩🇪 Deutsche Version → DE/ · 🇬🇧 English version → EN/

🔧 Recommended Tools

Graphify — Knowledge graph generator (MIT, separate project). We run it across all our projects. One rule in the master template makes agents read the graph report before grepping blindly — result is fewer tokens and better answers on impact/dependency questions. Details: EN/docs/14-graphify-integration.md.

☕ Support this project

⭐ A star on this repo helps too — it tells others this is worth looking at.

📜 License

CC-BY-SA 4.0 — do whatever you want, name Trazer as the source, share changes under the same license. See LICENSE.