cc-settings

cc-settings gives Claude Code and Codex the Darkroom engineering team's standards, task workflows,
safety checks, and proof gates. One installer makes a new machine behave like the rest of the team
without replacing personal configuration that cc-settings does not own.

The practical effect is simple: "fix this bug" gets a cause-first debugging workflow, "review my
changes" stays read-only, and "ship it" must prove the real build and tests before anything is
published.

New here? Install it (5 minutes), run one read-only task, then learn the
daily loop. That is enough to get most of the value. Everything after that
section is reference you can come back to.

Five-minute first success

1. Install the product you plan to use

Install and authenticate Claude Code,
Codex CLI, or both. cc-settings configures those
products; it does not install a subscription or account.

2. Install cc-settings

Any platform (Node 18+):

npx darkroom-settings

Every installer flag works: npx darkroom-settings --light --auto-update=on. bunx darkroom-settings is
equivalent. The npm package is only a downloader; the configuration always installs from this
repository's pinned GitHub origin.

macOS or Linux, without Node:

curl -fsSL https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.sh | bash

Flags go after -s --. Every setup.sh flag works remotely, with no clone or download needed:

curl -fsSL https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.sh | bash -s -- --light --auto-update=on

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.ps1 | iex"

To pass flags remotely on Windows, invoke the downloaded script as a script block:

powershell -ExecutionPolicy Bypass -c "& ([scriptblock]::Create((irm https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.ps1))) --light"

The default target installs both products when codex is on PATH, and Claude Code only
otherwise. --light installs a minimal beginner tier; re-run without it to get the full setup.
Clone the repository only when you want a source checkout you own:

git clone https://github.com/darkroomengineering/cc-settings.git
cd cc-settings
bash setup.sh --target=both --dry-run
bash setup.sh --target=both

Review all requirements, tiers, system changes, prompts, managed paths, and undo behavior in the
installation reference.

3. Restart and inspect

Restart every selected product. In Codex full installs, open /hooks and review the installed
hooks once. Claude users can inspect the installed user-scope configuration from any
directory:

bun ~/.claude/src/scripts/whats-on.ts

That report shows what is installed and shaping Claude user scope. It does not identify which skill
handled a previous prompt or fully resolve project overrides.

4. Run one harmless task

Open a repository and say:

Explain where this project's configuration is loaded. Read only. Cite the files and lines.

The result should name its read-only scope, cite evidence, and leave the working tree unchanged.
Your first session shows the expected output, background behavior,
follow-up, and recovery.

The daily loop

You do not need to memorize commands. Describe the outcome in plain language and cc-settings picks
the matching workflow (a "skill"). Type the skill name only when you want to force a specific one:
/name in Claude Code, $name in Codex.

Most days are some path through these steps:

Claude Code also has a built-in /review. When you want the cc-settings one, say "run the
cc-settings local pre-commit review" or pick it from the skill picker.

Big tasks split themselves. Work that spans several files, a long chain of tool calls, or
security-sensitive code gets handed to focused agents (explore, implement, test, review, security)
that run in the background and report back. You can keep talking in the main conversation while
they work.

Every workflow for every situation, including audits, triage of a client
repo, and adversarial verification, is in the manual. The
skill guide says what each one can change and when it stops to ask.

Set up the projects you work in

cc-settings brings the team standards to every repository. Each project can add its own
instructions on top.

• Starting a new Darkroom project: say "new darkroom project" or run /dr-init. It creates the
  project from the satus or novus starter. The native /init is a different command that only
  writes a CLAUDE.md.
• Giving a project its own instructions: put them in AGENTS.md at the project root. Claude
  Code and Codex both read it. Good content is what an agent cannot learn from the code: the
  commands to run, the environments, the traps, and the decisions that look wrong but are
  deliberate.
• Existing project with a CLAUDE.md: say "migrate to agents.md" or run /cc migrate. Claude
  Code ignores AGENTS.md while a CLAUDE.md exists, so the two drift apart. The session banner
  tells you when a project needs this.
• Planned work on GitHub: link the issue and /handoff posts progress to it, so agents read the
  issue and update it as they go.

Habits that change results

Small habits make the biggest difference in how well sessions go:

1. Say the outcome, not the steps. "Fix the flaky checkout test" works better than a list of
   commands. Add constraints you care about ("read only", "don't touch the API").
2. One task per session. Run /clear between unrelated tasks. Long, mixed sessions get slower,
   cost more, and lose track of details.
3. Save before you stop or risk something. /handoff at the end of a day or a long session;
   /checkpoint before a risky refactor or migration, so you can roll back.
4. Raise effort only for hard turns. The default is tuned for everyday work. Use /effort high
   or /effort xhigh for hard debugging, audits, or migrations, or add ultrathink to a single
   message.
5. Ask for a second opinion when it matters. "Poke holes in this" (/poke-holes) sends independent
   agents to find and disprove problems. Asking "what could go wrong?" before you commit to a plan
   gets a risk review.
6. Read the statusline. It shows context size and usage limits. When context passes about
   150K tokens, hand off or compact instead of pushing on.
7. When something feels off, look before you guess. whats-on.ts shows what is installed and
   active; troubleshooting covers hook warnings and install health.

Make it better for everyone

cc-settings improves when people feed back what they learn. There are three levels, from quickest
to most involved:

1. Share a lesson. When you hit a gotcha, a convention, or a decision the team should know,
   say "share this" or run /share-learning. It lands in the shared team-knowledge repository, and
   every machine sees it right before the command or file edit it applies to.
2. Keep a workflow that worked. When a session found a good way to do something repeatable,
   say "turn this session into a skill" or run /harvest. It proposes a skill, rule, or team note
   built from what actually happened.
3. Look back weekly. /retro reports what you shipped, how sessions went, and quality trends,
   and shows which guardrails fired and whether they helped.

To change cc-settings itself, clone it and read the maintainer docs.
The short version:

• Settings live in config/ as fragments that the installer merges into
  ~/.claude/settings.json. Edit the fragments, never the installed file.
• A new or reworded skill ships with an eval case in evals/; see
  skill authoring.
• Run bun test, bun run typecheck, and bun run lint before pushing.
• If you only want to suggest something, open an issue with the behavior you saw and what you
  expected.

Keep it current

• Update: say "update cc-settings" or run /cc update in a session, or re-run the install
  command. Restart the product afterwards.
• Auto-update (macOS): add --auto-update=on to the install command for a daily check at
  10:00 local time. --auto-update=off removes it.
• Check health: npx darkroom-settings --status reports installed versus packaged state.
• Undo: bun src/setup.ts --rollback from a checkout restores the newest backup. The
  installation reference covers uninstall.

What cc-settings adds on top of a vanilla install

A fresh Claude Code or Codex install is a capable general assistant with no memory of how this
team works. cc-settings installs that memory, plus the checks that make "done" mean the same thing
on every machine. The same request behaves differently once it is installed:

The pieces

• Standards. AGENTS.md holds the coding standards and guardrails every tool
  reads; Claude Code gets its copy as CLAUDE-FULL.md, installed as ~/.claude/CLAUDE.md. Twelve topic rules (TypeScript,
  React, performance, accessibility, security, git, motion, style) load only for the files they
  cover, and six stack profiles (Next.js, React Router, React Native, Tauri, WebGL, orchestration)
  add the specifics of each starter.
• 26 skills. Named workflows selected from ordinary language or pinned with /name in Claude
  and $name in Codex: fix, build, review, ship, audit, poke-holes, handoff, and the
  rest. The skill guide lists what each one changes and when it asks.
• 10 role agents. Planner, explorer, implementer, tester, reviewer, security reviewer,
  scaffolder, deslopper, orchestrator, and a cross-model verifier. Big work is divided instead of
  held in one conversation, and each role runs on the model tier its job needs.
• 36 hooks on 18 lifecycle events. Small programs that run around tool calls, commits, pushes,
  compaction, and session start or end. They block destructive commands, require proof before a
  PR, remind about docs before an install, nudge when unreviewed agent output piles up, and inject
  context the model would otherwise never see. Claude gets the full set; Codex gets the compatible
  plugin subset and asks you to review it once through /hooks.
• Model routing. Effort pinned to medium, subagents on Sonnet, planning and decisions on the
  session model, bulk or mechanical work and one cross-model review per PR or direct push routed to Codex when
  the bridge is installed. The statusline shows the usage limits that drive that routing.
• Connected tools. In Claude, four MCP servers: Context7 for current library docs, a TypeScript
  code map for call graphs and blast radius, Figma, and Chrome DevTools for screenshots and
  Lighthouse. Codex gets the Figma server only and reports a missing capability instead of faking
  the rest.
• Verbatim compaction. With a TypeSafe key, long sessions compact near the 200K working
  ceiling by removing stale tool output that Jev scores as no longer needed, while every user and
  assistant message stays word for word. Without a key, native summary compaction applies. See
  verbatim compaction with Jev.
• Team knowledge. A shared repository of decisions, conventions, and gotchas that every
  machine reads. Notes are posted with /share-learning and surface automatically before the
  command or file edit they apply to.
• Ownership and rollback. The installer records what it owns, keeps a backup per product,
  fingerprints its hooks, and can preview, roll back, or uninstall without touching your own
  configuration. Read SECURITY.md if a session ever warns about hook trust.

What it leaves alone

Your login and subscription, your permission mode, your personal memory, and any setting the
installer does not own. Put your own global instructions in ~/.claude/personal.md: the
installed CLAUDE.md imports it, and setup never replaces it (Claude Code only). It does not
grant GitHub, Figma, or browser access, and it does not make the two products identical: see Claude Code and Codex for what each
host can and cannot do.

Choose where to read next

Why the team maintains it

Written standards, workflows, and proof gates reduce per-machine drift. They also make the codebase
more legible to humans: the conventions an agent needs are the same debt the team owes its
engineers.

darkroom.engineering | MIT

{
  "name": "cc-settings",
  "owner": {
    "name": "Darkroom Engineering",
    "url": "https://darkroom.engineering"
  },
  "description": "Darkroom Engineering Claude Code marketplace — skills, agents, rules, and MCP connectors from the cc-settings harness.",
  "plugins": [
    {
      "name": "darkroom",
      "source": "./",
      "description": "Darkroom Engineering AI coding standards. Layered config with portable AGENTS.md, progressive complexity, and two-tier knowledge system.",
      "author": {
        "name": "Darkroom Engineering",
        "url": "https://darkroom.engineering"
      },
      "category": "workflow",
      "tags": [
        "darkroom",
        "react",
        "nextjs",
        "typescript",
        "orchestration"
      ]
    },
    {
      "name": "compaction-trigger",
      "source": "./plugins/compaction-trigger",
      "description": "Requests a session compaction when the live context passes a token threshold, so verbatim compaction plugins run near the working ceiling instead of at the model window.",
      "author": {
        "name": "Darkroom Engineering",
        "url": "https://darkroom.engineering"
      },
      "category": "workflow",
      "tags": [
        "compaction",
        "context"
      ]
    },
    {
      "name": "context-report",
      "source": "./plugins/context-report",
      "description": "Prints which instruction files the engine loaded (tier, path, @ imports, size) once per context load, and hints when a project CLAUDE.md keeps its AGENTS.md from being read.",
      "author": {
        "name": "Darkroom Engineering",
        "url": "https://darkroom.engineering"
      },
      "category": "workflow",
      "tags": [
        "instructions",
        "agents-md",
        "context"
      ]
    },
    {
      "name": "drift-fuse",
      "source": "./plugins/drift-fuse",
      "description": "Scores each unattended turn against the task the person asked for with TypeSafe's Jev model, and after consecutive off-task turns redirects or pauses the next machine-submitted prompt.",
      "author": {
        "name": "Darkroom Engineering",
        "url": "https://darkroom.engineering"
      },
      "category": "workflow",
      "tags": [
        "drift",
        "loop",
        "jev"
      ]
    }
  ]
}