Claude Agentic OS — a portable Claude Code setup

A one-command agentic operating system for Claude Code:
global rules, a curated plugin set, persistent per-project memory, a statusline
and an optional project launcher — installed, wired together and kept up to date
by ./install.sh.

Claude Code out of the box is a capable coding agent with no opinions. This pack
supplies the opinions: how the agent verifies its work, how it diagnoses a
failure, when it may push, what it may rewrite, where it keeps what it learned.
Most rules here were written after something went wrong, and each records what it
cost. The rest are preventive: each names the well-known failure it stops (a Why
line) until an incident gives it a cost.

Nothing in the pack is tied to one person, one machine or one repository. Your
name, GitHub handle, email, reply language and projects folder are placeholders
filled in at install time. The rule that keeps every project in that folder is
optional (--no-project-location).

git clone https://github.com/kgdemir/claude-agentic-os.git
cd claude-agentic-os
./install.sh

Works on: macOS · Ubuntu / Debian · Fedora / RHEL · openSUSE · Arch · WSL2
Needs: bash, git. Everything else is offered and installed for you.

Contents

• Why this exists
• What you get
• Install
• What gets installed where
• The plugin set
• The security-audit skill
• Memory: one database per project
• What the installer changes outside ~/.claude
• The statusline
• The optional launcher
• Adapting the rules
• Uninstalling and rolling back
• Security
• Keywords

Why this exists

An AI coding agent fails in the same few ways on every project:

• It reads a command's output instead of its exit code and reports a broken
  build as green.
• It ships a plausible fix for a bug it never diagnosed, then another, then
  another.
• It rewrites the user guide as a side effect of a one-line fix.
• It stages everything, including a virtual environment.
• It forgets, between sessions, everything it learned about the codebase.

Each of those has a rule in agent-working-rules.md, with the incident that
produced it. Install the pack and Claude Code starts every session already
holding them.

What you get

Install

./install.sh

It detects your operating system and package manager, reads your name, GitHub
handle and email from gh when you are signed in, asks for whatever it could
not detect, and writes the filled-in rules to ~/.claude/. Re-running is safe:
any file it would overwrite is copied to <name>.backup-<timestamp> first.

Non-interactive:

./install.sh --language English --name "Ada Lovelace" --github ada \
             --email [email protected] --project-root ~/projects \
             --with-plugins --with-security-audit --with-statusline --install-deps -y

The installer refuses rather than writing a blank if a required detail is
missing and it cannot ask — for example in a pipeline with no gh session.

It never writes a credential. The only environment values it sets are
CAVEMAN_DEFAULT_MODE, CLAUDE_CODE_AUTO_COMPACT_WINDOW (below) and, if you
ask for it, ECC_DISABLED_HOOKS.

It also fills in five settings a fresh machine otherwise needs by hand, and
only when settings.json does not already carry them:

What gets installed where

~/.claude/CLAUDE.md              global rules; imports the core guides and lists
                                 each add-on with the trigger that loads it
~/.claude/guides/
  core/                          always loaded, every project
    agent-working-rules.md       verification, diagnosis, background work, git,
                                 code quality, decisions and memory
    project-tools.md             repeatable commands live in tools/ scripts
    project-claude-md.md         each project keeps its own CLAUDE.md
    project-docs.md              README.md, capabilities.md, SECURITY.md
    docs-updates.md              docs change on request; baseline marker
    docs-folder.md               docs/adr/ and docs/architecture.md (C4)
  stacks/                        read when the project uses that stack
    dotnet.md                    .NET conventions (test gate, warnings as errors,
                                 async, HttpClient, options, logging, packages)
    dotnet-gotchas.md            .NET traps that fail silently
    dotnet-ef-core.md            EF Core traps, tracking, N+1, migrations, raw SQL
    dotnet-testing.md            real database in tests, cross-OS fakes, mocks
    aspnet-core.md               antiforgery, CORS on errors, idempotency, deploy config
    windows-desktop.md           WinForms/WPF/WebView2: UI thread, runtime, Linux builds
    python.md                    venv, pinned deps, ruff/pytest, timeouts, python -I
    frontend-testing.md          Node parity in CI, scoped jsdom, role queries
    typescript.md                strict config, type-check gate, runtime validation
    react.md                     React lint plugins, render-loop guards, keys, XSS
  tools/                         read when the project uses that tool
    eslint.md                    flat config baseline, zero warnings, typed linting
    vite.md                      chunk grouping and size budget
    child-processes.md           pipe and kill traps, any language
    ffmpeg.md                    ffmpeg/ffprobe traps (duration, option order)
    pdf-export.md                Markdown-to-PDF build and checks (always A4)
    sql-server.md                collations, parameters, certificates, transactions
    docker.md                    buildable Dockerfiles, pinned tags, no secrets, healthchecks
    redis.md                     honest fallback, one connection, TTLs, no KEYS
    github-actions.md            SHA-pinned actions, least privilege, no script injection
    dependency-updates.md        Dependabot/Renovate grouping, majors one at a time
    skills.md                    which skill, review command or plugin to use for a task
  features/                      read when the project has that feature
    realtime-media.md            WebSocket, SignalR, WebRTC, SFU: docs and hub rules
    ai-models.md                 model docs, output coverage, timeouts, GPU pins
    auth.md                      SSRF on every hop, JWT, rate limits, LDAP, cookies
    observability.md             tokens out of logs, log injection, error routing
    architecture.md              inward dependencies, feature folders, enforced boundaries
    api-design.md                OpenAPI contract, breaking-change check, pagination
    background-jobs.md           outbox, idempotent consumers, dead letters, single run
    resilience.md                timeouts, safe retries, breakers, liveness vs readiness
    database-migrations.md       expand/contract, batched backfills, UTC, online indexes
    i18n.md                      invariant vs user culture, Turkish-I, UTC, resources
    accessibility.md             WCAG 2.2 AA: names, keyboard, focus, contrast, axe
    web-security.md              HSTS, CSP, headers, CORS, uploads, OWASP Top 10
    releases.md                  Conventional Commits, SemVer, Keep a Changelog
    privacy.md                   personal data: minimise, retention, erasure, no PII in logs
    testing-strategy.md          test pyramid, real dependencies, flaky tests, coverage
    performance.md               measure first, budgets, percentiles, profiling, load tests
    caching.md                   TTLs, keys, private responses, stampede, fallback
    user-guide.md                docs/user-guides/ pages, combined.md and the PDF
  plugins/                       read when that plugin is active
    caveman.md                   terse reply style
    context-mode.md              sandboxed tool output
    memsearch.md                 one memory database per project
  addons/                        imported only when chosen at install
    project-location.md          every project under --project-root
~/.claude/templates/
  adr-template.md                architecture decision record
  architecture-template.md       C4 context and container diagrams (Mermaid)
  project-claude-template.md     starting point for a project CLAUDE.md
~/.claude/bin/
  runclaude                      optional launcher (only with --with-launcher)
~/.claude/hooks/
  check-agent-brief.py           PreToolUse hook on the Agent tool: warns (never
                                 blocks) on a subagent brief without
                                 Goal:/Files:/Done: lines
                                 (Explore, claude-code-guide, statusline-setup
                                 and forks exempt); needs python3
  check-bash-command.py          PreToolUse hook on Bash: warns (never blocks)
                                 when a command breaks a core rule; on
                                 git commit it scans the staged diff and names
                                 only the file and kind of a likely secret
~/.claude/skills/security-audit/ the security-audit skill (only with --with-security-audit)
~/.claude/skill-backups/         earlier copies of that skill, as .tar.backup-<timestamp>
~/.claude/statusline.sh          statusline for this OS (only with --with-statusline)
~/.claude/settings.json          merged, never overwritten; backed up first

The plugin set

With --with-plugins (the interactive default is yes) the installer adds six
marketplaces, installs the plugins listed below, enables them, and sets
autoUpdate so later versions arrive on their own:

For the first five, the catalog is read from each marketplace rather than
hard-coded, so a plugin an upstream repository adds later is installed too,
without a change here. The official marketplace publishes over 300 plugins, so
only the named ones are installed (ADR-0011); a name it no longer publishes is
reported and skipped. Claude Code ships and updates that marketplace itself, so
no autoUpdate entry is written for it. Which of these tools to use for which
task is in guides/tools/skills.md.

It needs the claude CLI and python3. If either is missing the installer says
what it is for and offers to install it — python3 through your package
manager, claude through curl -fsSL https://claude.ai/install.sh | bash — and
only skips the step if you decline. --install-deps answers yes to all of them,
--no-deps answers no and just prints the command. The same offer covers npm
when ccusage is wanted for the statusline. Re-running installs nothing twice:
a marketplace or plugin already there is reported as present.

Two settings are written for you:

• CAVEMAN_DEFAULT_MODE=ultra, so caveman starts at its terse level.
• ECC_DISABLED_HOOKS, which the installer asks about. ECC's gateguard hooks
  interrupt before an edit, a read/write and a shell command to demand a cited
  fact. On a machine you own that is mostly a nag, so the installer offers the
  three ids that turn them off and leaves the rest of ECC running. An empty
  answer keeps every hook.

Everything lands in ~/.claude/settings.json (backed up first), beside whatever
is already in that file.

The security-audit skill

With --with-security-audit (asked in a terminal, default yes; off under -y)
the installer installs Cloudflare's
security-audit skill.
It has no plugin marketplace, so it uses the upstream install path, the skills
npm CLI, pinned to the version in SKILLS_CLI_VERSION in install.sh:

• The CLI runs with a throwaway HOME and CLAUDE_CONFIG_DIR and with
  telemetry off (DISABLE_TELEMETRY=1, DO_NOT_TRACK=1), so it writes nothing
  of yours.
• The result is compared with ~/.claude/skills/security-audit. Unchanged:
  left alone. Changed: the old copy is saved as
  ~/.claude/skill-backups/security-audit.tar.backup-<timestamp>, outside
  skills/ so it does not load as a second skill, then replaced.
• It needs npx (offered through your package manager as npm), git and
  network access to npm and GitHub. If the CLI fails, its output is printed and
  the rest of the install goes on.

Re-running the installer is what updates the skill. The skill gives security
guidance by default and runs its full multi-phase audit only when you ask for
one (guides/tools/skills.md).

Memory: one database per project

Facts Claude learns are kept per project, never in one shared pile:

• ~/.claude/projects/<project>/memory/ — one fact per name.md, with a
  one-line pointer in MEMORY.md. The index holds pointers, never content, and
  no file is left unreferenced.
• Each project gets its own memsearch database. A shared database mixes
  unrelated repositories and answers a question about one codebase with a fact
  from another. The rule is in guides/plugins/memsearch.md.
• Memory is context, not truth: anything a stored note claims about the code is
  verified against the code before it is acted on.

What the installer changes outside ~/.claude

Four things live outside the rules directory. Each is asked about separately,
and each answers no when there is no terminal or when you passed -y, in
which case the exact command is printed for you to run yourself:

The statusline

Shows directory, git branch with +added/−deleted counts, model, effort, context
remaining, session cost and burn rate. The installer picks the build for your
system — statusline-linux.sh (GNU date, coreutils timeout) or
statusline-macos.sh (bash 3.2, BSD date, perl alarm) — copies it to
~/.claude/statusline.sh, and registers it in ~/.claude/settings.json,
keeping every other setting already in that file.

Its tools are all optional, and it degrades rather than failing:

The installer lists whichever are missing, explains each, and offers to install
them with your package manager — including npm itself when ccusage is wanted
and npm is absent.

Both builds set LC_NUMERIC=C. Without it a comma-decimal locale prints the
session cost as $53,00.

The optional launcher

runclaude is installed to ~/.claude/bin/runclaude, beside the rules rather
than in your projects folder, and so is its memsearch virtual environment
(~/.claude/.venv; override with CLAUDE_VENV). The projects root stays for
projects and reaches the launcher as CLAUDE_ROOT.

It opens a project, installs missing tooling (git, gh, jq, uv, node,
bun, .NET SDK, Claude Code) through whichever package manager the machine has,
sets up a memsearch virtual environment, and fast-forwards the repository's
default branch. It supports macOS and Linux.

It is opt-in because it installs software and touches your working tree. What it
will and will not do:

• It installs packages without a further prompt, using Homebrew on macOS
  (installing Homebrew itself if absent) or sudo apt/dnf/zypper/pacman on Linux.
• It pulls only when you are already on the default branch and the working
  tree is clean, and only as a fast-forward. It never switches branches for you.
• It mirrors GITHUB_PERSONAL_ACCESS_TOKEN into GH_TOKEN when that variable is
  set, so gh and git authenticate without an interactive login. It never writes
  that token anywhere.

Skip it if you would rather manage your own tooling; the rules work without it.

Adapting the rules

The guides are ordinary Markdown, meant to be edited. Three things to know before
you cut something:

• Core guides are imported into every session; add-on guides cost nothing
  until their trigger in ~/.claude/CLAUDE.md matches. A rule for one stack,
  tool, feature or plugin belongs in its own add-on file, not in a core guide.
• Each rule in agent-working-rules.md and dotnet-gotchas.md carries a note of
  what it cost when it was learned, or a Why line when it is preventive. A rule that looks like fussiness usually has
  a broken build behind it.
• react.md, eslint.md and vite.md are version-sensitive and say so at the top. The pinned versions
  expire; the reasoning does not.

Uninstalling and rolling back

Every file the installer replaces is kept as <name>.backup-<timestamp> in the
same directory, settings.json included; a file whose content would not change
is left alone and not backed up. Guides from the old flat layout
(~/.claude/guides/<name>.md) are moved aside the same way. To undo a run, move
the backups back.
To drop the plugins: claude plugin uninstall <plugin>@<marketplace> and
claude plugin marketplace remove <marketplace>. To drop the rules, delete
~/.claude/CLAUDE.md, ~/.claude/guides/ and ~/.claude/templates/. To unwire
the launcher, delete the block between the # >>> claude rules pack and
# <<< claude rules pack markers in your shell rc.
Old backups pile up over many runs; ./install.sh --prune-backups 3 keeps the
newest three sets and asks before deleting the rest.

Security

The installer can install operating-system packages, run the Claude Code
installer, add third-party plugin marketplaces with auto-update on, touch your
shell rc and set your global git identity — each after asking.
SECURITY.md lists exactly what it can and cannot do, and how to
report a problem.

Working on the pack

Contributing

Rules are welcome when they are project-agnostic and earned — see
CONTRIBUTING.md for what belongs here, the placeholder
contract and the shell-portability rules.

Maintained by Kerim Gökhan DEMİR (@kgdemir).
Licensed MIT.

Keywords

Claude Code setup · Claude agentic OS · agentic operating system · AI coding
agent rules · CLAUDE.md template · Claude Code plugins · Claude Code
marketplace · Claude Code statusline · Claude Code memory · agent memory per
project · memsearch · context-mode · caveman plugin · ECC plugin · drywall ·
AI agent guardrails · LLM coding standards · architecture decision records ·
ADR template · dotfiles for Claude Code · macOS Linux WSL installer