> For the complete documentation index, see [llms.txt](https://docs.thecolliery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thecolliery.org/tools/coalface/readme.md).

# CoalFace

## ⛏️ CoalFace

> *A coal face is the active surface of the seam — the one place the whole crew swarms to cut coal.* This one disciplines your agent's swarm.

**A fan-out discipline for swarm work.** When a task decomposes into many units — a bulk refactor, a repo-wide sweep, a 100-spot edit, a corpus batch — CoalFace runs the fan-out as a disciplined factory instead of an ad-hoc swarm: a mandatory scout, a deterministic partition, workers returning anchor-edit orders as text, mechanical QC at collection, one writer applying behind a snapshot, and a receipt at the end.

![version](https://img.shields.io/github/v/tag/TheColliery/CoalFace?sort=semver\&label=version\&color=blue) ![license](https://img.shields.io/badge/license-Apache_2.0-blue) ![status](https://img.shields.io/badge/status-stable-brightgreen) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/TheColliery/CoalFace?utm_source=oss\&utm_medium=github\&utm_campaign=TheColliery%2FCoalFace\&labelColor=171717\&color=FF570A\&link=https%3A%2F%2Fcoderabbit.ai\&label=CodeRabbit+Reviews)

*Compatibility: **validated** on Claude Code · **works with** every other concurrent-subagent platform (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot — installs and runs, not yet run by us; see the table for Antigravity's wired-but-unvalidated auto-conductor detail) · claude.ai has no subagents at all, so the contract's built-in sequential-pipeline degrade is what applies there, and no upload of ours has confirmed the install path yet — see the Compatibility table below.*

![Claude Code](https://img.shields.io/badge/Claude_Code-validated-brightgreen) ![Antigravity](https://img.shields.io/badge/Antigravity-works--with-blue) ![Cursor](https://img.shields.io/badge/Cursor-works--with-blue) ![Codex](https://img.shields.io/badge/Codex-works--with-blue) ![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-works--with-blue) ![Cline](https://img.shields.io/badge/Cline-works--with-blue) ![Copilot](https://img.shields.io/badge/Copilot-works--with-blue) ![claude.ai](https://img.shields.io/badge/claude.ai-upload_not_yet_confirmed-lightgrey)

[Contributing](https://github.com/TheColliery/CoalFace/tree/main/CONTRIBUTING.md) · [Changelog](https://docs.thecolliery.org/tools/coalface/changelog.md) · [Security](https://github.com/TheColliery/CoalFace/tree/main/SECURITY.md) · [Privacy](https://github.com/TheColliery/CoalFace/tree/main/PRIVACY.md) · [Releases](https://github.com/TheColliery/CoalFace/releases)

**Docs:** [docs.thecolliery.org/tools/coalface](https://docs.thecolliery.org/tools/coalface)

**Part of** [**TheColliery**](https://github.com/TheColliery/.github) — siblings: [**CoalMine**](https://github.com/TheColliery/CoalMine) (quality canaries) · [**CoalTipple**](https://github.com/TheColliery/CoalTipple) (model/effort routing) · [**CoalBoard**](https://github.com/TheColliery/CoalBoard) (consensus board) · [**CoalHearth**](https://github.com/TheColliery/CoalHearth) (session warm-resume) · [**CoalWash**](https://github.com/TheColliery/CoalWash) (memory defrag) · [**CoalLedger**](https://github.com/TheColliery/CoalLedger) (docs health) · [**CoalGob**](https://github.com/TheColliery/CoalGob) (OS-trash delete guard, PUBLIC BETA v0.1.0-beta.1).

***

### ⛏️ What it is

Agents already fan work out to subagents — CoalFace does not invent that. It disciplines it. An ad-hoc fan-out makes the same three promises with **no guarantee**; CoalFace makes them **enforced by structure**:

| Promise     | Ad-hoc fan-out                                                                                                    | CoalFace                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cost**    | UNBOUNDED — uncontrolled spawn overhead, N workers re-reading the same files, retry storms, stray runaway workers | Overhead BOUNDED (shared-digest + min-unit floor + no self-retry) and **cheaper in $ only when workers run on cheaper tiers** (with main-equivalent workers it can cost more than solo). NOTE: raw **tokens run HIGHER than solo** — fan-out multiplies the \~per-sub baseline by N (the benchmark showed \~5.3× on a small job); the wallet ESTIMATES **dollars** (about solo only on cheaper worker tiers, never a guarantee), never raw tokens; `bandwidth` sets the speed |
| **Speed**   | UNDER-FANNED — a lazy orchestrator batches 100 spots into 5-8 bloated workers whose tail quality drops            | Full width — worker count = spot count, floor/width-bounded waves                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Quality** | Can dip BELOW solo — a deviant worker, real-tree writes, a half-applied death                                     | Netted — mechanical QC at collection, single-writer apply behind a pre-swarm snapshot, a domain gate                                                                                                                                                                                                                                                                                                                                                                          |

Honest frame up front: CoalFace disciplines fan-outs that would happen anyway — it does **not** make models smarter and does **not** guarantee correctness (see the QC ceiling below). Zero-dependency, offline by default, no API keys — "by default" because the consent-gated self-update check (`/coalface:update`) goes online; the hooks never do.

### 🏭 How it works

The flow is fixed — a swarm never skips a step:

| # | Step                          | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| - | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | **Scout** (mandatory)         | Survey the worksite before sizing anything: the spot list, the dependency graph, the invariants to lock (your standing rules, glossary, API/style), the end-of-run domain gate, the swarm mode, and the **shared-digest** — the common context paid for once and shipped to every worker (never N workers re-reading the same files).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 2 | **Partition** (deterministic) | An interval-intersection check merges overlapping spots and chains dependent ones — a rule table, not model judgment. A unit smaller than spawn overhead merges with a neighbor (the min-unit floor).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 3 | **Heads-up** (conditional)    | If the job dwarfs the prompt, one NON-blocking line ("found N spots, \~est X — starting; Esc to stop") — never a question-box.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 4 | **Waves**                     | Worker-wave width = max(1, floor(platform width × `bandwidth`%)), never above the platform width — `maxLocalWorkers` never enters it. Separately, before each apply-time domain-gate run (main's own step-7 build/test, or a depth-1 nested conductor's own) and each wave of heavy local work, the agent runs `skills/coalface/scripts/admission.mjs`, which reads your thresholds from the config and then your CPU and memory now (through `machine-reading.mjs`): BREATHE starts the run, WAIT holds it (and names why) and reads again; at least one unit always runs, and a reading your machine cannot give never blocks, so a machine that cannot be read at all releases one unit at a time. AIMD backoff: a 429 shrinks the next wave, clear stretches re-grow — a `bandwidth` set above your account's real capacity simply settles AT the real capacity, nothing breaks. |
| 5 | **Orders as text**            | Workers return **anchor-edits** (`old-text → new-text`, exact-match, position-independent — that is why 100 spots in ONE file works) or the completed unit as text. Propose-not-execute: workers never touch the tree.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 6 | **QC at collection**          | Mechanical, before any apply: SCOPE (every anchor inside the assigned range, no foreign files) + SPEC (locked invariants grep-verifiable). Reject → quarantine + ONE bounded rework; a 2nd fail goes to you via the receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 7 | **Apply** (single writer)     | Behind a pre-swarm snapshot (git stash / HEAD-record, or plain file copies — git is never assumed), sequentially in topological order, then the domain gate (build+test / corpus rules / lint+links / schema-validate). Gate red = full rollback.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 8 | **Receipt** (always)          | Spots · workers · waves · effective width · machine holds · tokens vs the solo estimate · quarantined items · test-uncovered flags — in your language, plain wording first.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

**Activation.** `coalfaceMode: auto` (the default) lets the agent judge — any fan-out of ≥ `autoFanoutFloor` units (default 4) rides the contract; 1-3-sub ad-hoc spawns, below the default floor, keep zero ceremony. `on` scouts every prompt; `off` removes CoalFace entirely. Manual **`/coalface`** convenes it in any mode except `off`. There is no pre-pay gate: your command IS the consent — a solo run would burn a comparable **dollar** budget silently, and on cheaper worker tiers the wallet keeps the swarm's dollar cost near that (main-equivalent workers can exceed it) — so transparency arrives as the receipt.

**The wallet — a DOLLAR bound, not a token one.** The whole swarm — scout + workers + apply — fits inside the estimated solo **dollar** cost only when worker tiers are cheaper than main (CoalTipple delegate-down, or a cheaper model you set), NOT its token count. With the default main-equivalent workers the swarm can exceed the solo dollar cost, and no budget stop exists. Raw tokens run *higher* than solo: fan-out multiplies the fixed \~per-sub baseline by N (the [benchmark](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalFace/RESULTS.md) showed \~5.3× solo tokens on a small 6-spot job — its CF arm ran 3 workers, extrapolated to 6). What holds the *dollar* line is that Claude Code's cheap worker tiers cost \~5× less per token — so N cheap workers can undercut one expensive solo main (the benchmark: −15% in $). The shared-digest, min-unit floor, and no-self-retry rule (a per-worker-return journal + at most one re-spawn on the remainder) keep that overhead *bounded* — on cheaper worker tiers the result is "about solo **in dollars**, much faster, QC'd", never "fewer tokens", and never a dollar guarantee.

**No worksite "breaks."** The scout classifies the shape and routes it to a safe mode:

| Worksite shape                           | Mode                                                                                                |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Disjoint spots (flat)                    | Full parallel waves — worker count = spot count (floor/width-bounded)                               |
| Dependency chain                         | Topologically-ordered waves; a full chain = pipeline degrade (discipline kept; honesty: no speedup) |
| Global invariant (glossary/style/totals) | Lock first → ship in the shared-digest → consistency sweep at the end                               |
| Holistic quality (voice/architecture)    | Analyze-swarm only — ONE voice writes                                                               |
| Side-effects                             | Closed by propose-not-execute — side-effects fire only at the consented apply                       |
| Non-decomposable                         | Honest refusal: "not swarmable — solo"                                                              |

**The QC ceiling (honesty).** QC is mechanical. An in-scope, on-spec, semantically-WRONG return with no covering test can pass — the receipt flags those test-uncovered spots, and the escalation for that class is [CoalBoard](https://github.com/TheColliery/CoalBoard) (the error-not-allowed lane), never another swarm. On error-not-allowed work CoalBoard wins outright: critical work goes to consensus, not throughput.

### 🖥️ Compatibility

| Platform                                                                                           | Support               | What you get                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Code**                                                                                    | ✅ **validated**       | One-command plugin install; the SessionStart conductor injects the standing discipline; [CoalTipple](https://github.com/TheColliery/CoalTipple) (if installed) adds delegate-down worker tiering — a cost bonus, never a gate, and its sensitive-unit rule (crypto/auth/payment/migration stays main-tier) is inherited even when it's absent.                                                                                                                                                                                                                                                                                                                                                                                                |
| **Antigravity**                                                                                    | **works with**        | The skill-file contract — manual `/coalface` spawns real workers there (native subagent tool), same as any other row below. AG 2.0 also shipped a real hook engine, so the standing `auto` conductor is *wired* for it (built + hermetically tested against the current AG hook contract — the `injectSteps` emit, re-derived 2026-07-23) via a one-time copy of [`platform-configs/hooks.json`](https://github.com/TheColliery/CoalFace/tree/main/platform-configs/hooks.json) (see Install); whether that directive actually lands in the agent's context on live AG is **not yet validated**, so manual `/coalface` stays the reliable floor. Doesn't work as documented? [File an issue](https://github.com/TheColliery/CoalFace/issues). |
| **Other concurrent-subagent platforms** (Cursor, Codex, Gemini CLI, Cline, Copilot, Amp, Goose, …) | **works with**        | The skill file is the whole contract — workers spawn via the platform's native subagent tool, no API; we have not run a swarm there ourselves, so the contract itself says to treat width/nesting conservatively. Hooks and plugin commands are Claude-Code-only, so there is no standing `auto` directive: install the skill (or point your agent at it) and convene it on bulk work. Doesn't work as documented? [File an issue](https://github.com/TheColliery/CoalFace/issues).                                                                                                                                                                                                                                                           |
| **claude.ai** (web / desktop app)                                                                  | ⚠️ Sequential degrade | No subagents there — the contract's built-in degrade path applies instead (scout → units in order → QC → apply): the discipline without the parallel speed. The install path is the one claude.ai documents (a ZIP from [Releases](https://github.com/TheColliery/CoalFace/releases), uploaded as a custom skill); no upload of ours has confirmed it yet — see Install below.                                                                                                                                                                                                                                                                                                                                                                |
| **No concurrent fan-out**                                                                          | Sequential degrade    | The same contract runs as a pipeline (scout → units in order → QC → apply) — no speedup, discipline kept, never broken.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

Workers default to a main-equivalent model on every platform — capability never depends on Claude Code; only the cheap-worker cost option does.

### 🚀 Install

**Claude Code** — one command (also wires the SessionStart conductor + `/coalface:update`):

```bash
claude plugin marketplace add TheColliery/CoalFace
claude plugin install coalface@coalface
```

**Antigravity** — *works with; the swarm is e2e-proven only on Claude Code — re-verify on yours.* Antigravity has no plugin manager: a skill is installed by copying its folder into a customizations root, which Antigravity auto-discovers at session start (no install command, no manifest):

```powershell
git clone https://github.com/TheColliery/CoalFace.git --depth 1
# global (all workspaces):
New-Item -ItemType Directory -Force "$env:USERPROFILE\.gemini\config\skills\coalface" | Out-Null
Copy-Item -Recurse -Force CoalFace/skills/coalface/* "$env:USERPROFILE\.gemini\config\skills\coalface"
# — or per-project: copy into <your-repo>\.agents\skills\coalface instead
Remove-Item -Recurse -Force CoalFace   # optional cleanup
```

Same steps on macOS and Linux:

```sh
git clone https://github.com/TheColliery/CoalFace.git --depth 1
# global (all workspaces):
mkdir -p "$HOME/.gemini/config/skills/coalface"
cp -R CoalFace/skills/coalface/. "$HOME/.gemini/config/skills/coalface/"
# — or per-project: copy into <your-repo>/.agents/skills/coalface instead
rm -rf CoalFace   # optional cleanup
```

Start a new Antigravity session; `coalface` appears in the skills list, and `/coalface` convenes it manually.

**Auto conductor on AG (wired — live AG validation pending):** AG 2.0 shipped a real hook engine, so the standing `auto` directive can now ride Antigravity too. Keep the clone (the adapter is [`hooks/ag-conductor.js`](https://github.com/TheColliery/CoalFace/tree/main/hooks/ag-conductor.js), which requires its sibling [`hooks/coalface-conductor.js`](https://github.com/TheColliery/CoalFace/tree/main/hooks/coalface-conductor.js)) — or copy the `hooks/` folder wherever you keep the skill — then copy [`platform-configs/hooks.json`](https://github.com/TheColliery/CoalFace/tree/main/platform-configs/hooks.json) to `<workspace>/.agents/hooks.json` (per project) or `~/.gemini/config/hooks.json` (global) and replace `__COALFACE_DIR__` with the directory holding `hooks/`. The directive rides the first `PreInvocation` of a session (AG never fires `SessionStart`), at most once per session (once more if a session outlives its marker's seven days and another session's first call has swept it); delivery into the agent is not yet live-validated (the **wired** tier — defined in the Compatibility table; the adapter emits the current `injectSteps` contract, re-derived 2026-07-23 — the pilot-era `additionalContext` key was a dead letter) — so manual `/coalface` remains the reliable floor. `/coalface:update` stays Claude-Code-only (the self-update nudge is deliberately not ported — its payload is a CC plugin command; on AG, update by re-copying).

**Other concurrent-subagent platforms** (Cursor, Codex, Copilot, Gemini CLI, Cline, Amp, Goose, … — *works with; swarm e2e-proven only on Claude Code*) — the skill file is the whole contract: point your agent at [`skills/coalface/SKILL.md`](https://docs.thecolliery.org/tools/coalface/skill/skill.md) (it convenes via your platform's native subagent tool, no API; no one-command installer, and hooks + `/coalface:update` are Claude-Code-only there). Gemini CLI's parallel subagents are now first-party official (`/agents`) — business Standard/Enterprise plans only (individual tiers lost access 2026-06-18). **The fan-out discipline is cross-agent by design but proven only on Claude Code — re-verify concurrent-subagent support on yours.** A platform with no concurrent fan-out runs the same contract as a sequential pipeline (no speedup, discipline kept).

**claude.ai** (web / desktop app) — no subagents there, so the contract's built-in sequential-pipeline degrade applies instead. claude.ai's own page documents a skill as a ZIP whose top level is the skill folder (`coalface/SKILL.md` inside the archive; a `SKILL.md` at the archive root "isn't recognized as a skill"). Download `coalface.zip` from the [Releases page](https://github.com/TheColliery/CoalFace/releases) (built by CI on every stable tag, which lists each archive and fails the run unless it holds `coalface/SKILL.md`) and upload it as a custom skill, then turn it on under Customize > Skills. The upload path is confirmed by two other rooms' ZIPs, CoalMine's `rot-canary.zip` and CoalLedger's `doc-rot.zip` (2026-10-09, accepted, scan passed, listed under Created by you); **`coalface.zip` itself has not been uploaded yet**. A ZIP attached to an earlier Release has `SKILL.md` at the archive root and does not load as a skill: download the new one. Manual invocation only — no hooks there. **Don't hand-zip `skills/coalface` yourself** — zip the folder itself from its parent (`unzip -l coalface.zip` should show every entry starting with `coalface/`), and note the published ZIP's description is trimmed to 200 characters by our own conservative choice (claude.ai's page states a 1,024-character limit; `scripts/build-claude-ai-zips.mjs`; the source `skills/coalface/SKILL.md` is never edited). The Release also carries `SHA256SUMS.txt` — verify with `sha256sum -c SHA256SUMS.txt` (Windows: `(Get-FileHash coalface.zip).Hash -ieq (Select-String coalface.zip SHA256SUMS.txt).Line.Split()[0]`). General steps + capability notes: [CLAUDE-AI-INSTALL](https://github.com/TheColliery/.github/blob/main/CLAUDE-AI-INSTALL.md).

### Commands

| Command            | What it does                                                                                                                       |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `/coalface`        | Manually convene the fan-out discipline (scout → partition → waves → QC → single-writer apply → receipt) in any mode except `off`. |
| `/coalface:stats`  | CoalFace stats for this session — swarms run, receipts, wallet outcome vs the solo baseline.                                       |
| `/coalface:update` | Check for a newer CoalFace version and offer to apply it, or set how updates are handled.                                          |

### ⚙️ Configure

Everything is tunable in `.coalface.json` — global `~/.claude/.coalface.json` overlaid per key by the nearest project config (project wins; the lookup walks up from the cwd and stops at your home dir). **Per-project config lives under an agent dir** (`.claude/coal/coalface.json`, `.agents/coal/coalface.json`, or `.gemini/coal/coalface.json`), checked in this order at each directory level: **the dir of the agent actually reading this file first** (e.g. `.agents/coal/coalface.json` on Antigravity, `.claude/coal/coalface.json` on Claude Code — check your own agent's dir, not the CC default, if you're on a different platform), then the other dirs in fixed order `.claude` → `.agents` → `.gemini` (first found wins), then the two **deprecated** legacy shapes — the nested `.claude/.coalface.json` (`.agents/` and `.gemini/` likewise, same agent-dir order), then the root `<project>/.coalface.json` — both still read, so no existing config breaks ([Deprecated config paths](#deprecated-config-paths)). This lets you **tune or shut off a globally-installed skill per project** (off-switch: `coalfaceMode: off`) — a skill you don't need in a given project stops loading (and burning tokens) there. Every key is optional. The hook clamps an out-of-range `autoFanoutFloor` or `updateCheckDays` to its default on read; the two `admit…` keys are not clamped by the hook: the admission engine reads them itself, ignores an out-of-range value (the default stands), and takes the stricter of your global and project values. **Prefer the CLI over hand-editing:** `node scripts/configure.mjs --<key> <value>` sets any schema key — validated against the same `scripts/lib/config-schema.mjs` rules `verify.mjs` enforces — and writes the project layer by default, or the global one with `--global`; `node scripts/configure.mjs --help` lists every key with its range and default. The JSON above still works — the CLI is an addition, not a replacement, and hand-editing stays the only path for a reader with no shell. The high-impact keys:

| Key                  | Default | What it does                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `coalfaceMode`       | `auto`  | The discipline mode. `auto` — the agent judges; any fan-out of ≥ `autoFanoutFloor` units rides the contract. `on` — scout every prompt. `off` — CoalFace fully out; your platform's native fan-out untouched.                                                                                                                                                                                                             |
| `bandwidth`          | `25`    | Percent of the platform's available subagent width a wave may use (`100` = saturate — starves every sibling session; never the default). Orthogonal to the wallet: how FAST the same budget burns, never how much.                                                                                                                                                                                                        |
| `autoFanoutFloor`    | `4`     | Fan-out size (units) at/above which an `auto`-mode fan-out must ride the contract; below it, 1-3-sub ad-hoc spawns keep zero ceremony.                                                                                                                                                                                                                                                                                    |
| `maxLocalWorkers`    | `0`     | The user-set ceiling on concurrent apply-time DOMAIN-GATE runs (the step-7 build/test of main or of a depth-1 nested conductor), honoured as given. `0` = no count of ours: the live reading decides (`admitCpuBusyMaxPct`, `admitMemFreeMinPct`). Workers never hold this slot. A cap, not a consent/spend key: plain project-wins merge. Range 0-64.                                                                    |
| `admitCpuBusyMaxPct` | `80`    | Live-reading admission: WAIT when the CPU is at or above this busy percent (range 1-100). The default is ours, not a measurement of your machine; lower it on a shared or slow box. Read by the admission engine (`skills/coalface/scripts/admission.mjs`), which passes it on to the reading. A project config may only lower it below your global value (stricter admission); the engine takes the stricter of the two. |
| `admitMemFreeMinPct` | `10`    | Live-reading admission: WAIT when free memory is below this percent (range 0-99). The default is ours, not a measurement of your machine; raise it on a box that swaps early. Read by the admission engine (`skills/coalface/scripts/admission.mjs`), which passes it on to the reading. A project config may only raise it above your global value (stricter admission); the engine takes the stricter of the two.       |
| `language`           | `auto`  | Locks the reply language (`auto`/`th`/`en`/`ja`/`zh`/`es`). `auto` follows the conversation's language, EN fallback, no extra work. A lock translates PROSE only — commands, paths, identifiers, config keys, tier/effort/grade/model names and severity labels stay VERBATIM.                                                                                                                                            |

Full key reference: every key + default lives in [`scripts/lib/config-schema.mjs`](https://github.com/TheColliery/CoalFace/tree/main/scripts/lib/config-schema.mjs) and the commented template [`platform-configs/.coalface.json`](https://github.com/TheColliery/CoalFace/tree/main/platform-configs/.coalface.json).

#### Deprecated config paths

The canonical project config path is `.claude/coal/coalface.json` (its `.agents/` and `.gemini/` twins on those platforms). Two older shapes are **deprecated** — still read, but slated for removal:

| Deprecated path                                                                             | Replace with                 |
| ------------------------------------------------------------------------------------------- | ---------------------------- |
| `<project>/.claude/.coalface.json` (and `.agents/.coalface.json`, `.gemini/.coalface.json`) | `.claude/coal/coalface.json` |
| `<project>/.coalface.json`                                                                  | `.claude/coal/coalface.json` |

* **Marker:** the two rows above, and the `### Deprecated` entry in [CHANGELOG.md](https://docs.thecolliery.org/tools/coalface/changelog.md).
* **Notice — how to migrate:** move the file to `.claude/coal/coalface.json`, contents unchanged. Or run any `node scripts/configure.mjs --<key> <value>`: a write through the CLI moves a legacy project config to the first agent dir the project already has (`.claude` if none) and removes the legacy file.
* **Window:** deprecated as of v0.10.0 (a MINOR release); removable at the next MAJOR release, never sooner, and never on a months-count.
* **Owner:** the CoalFace room (this repo).
* **Channel: ship-text only** — this section and the CHANGELOG entry. There is no runtime deprecation warning, by design: Phoenix #13 lets a hook emit only on its sanctioned channels, and a deprecation notice is not one of them, so none is coming.

What the SessionStart hook does print is a report of *where* it found a config — not the deprecation warning:

```
LEGACY: <abs path> is a legacy config path; canonical = .claude/coal/coalface.json
IGNORED: <abs path> is not a config path; canonical = .claude/coal/coalface.json
UNREADABLE: <abs path> exists but is not a readable config (<reason>); it was skipped — canonical = .claude/coal/coalface.json
```

`LEGACY:` names the project config the walk selected when it is one of the two deprecated shapes; it says where the file is, not that it parsed — an unreadable or malformed one is named but not applied. `IGNORED:` names a file that looks like a config but sits at a path the walk never reads, so it is not being applied — `<project>/coalface.json` (no dot), `.claude/coalface.json` (no `coal/`), or `.claude/coal/.coalface.json` (old name inside the canonical dir). Only directory levels the walk reads are probed. `UNREADABLE:` names a config that exists at a candidate path — including the global `~/.claude/.coalface.json`, which is always probed but never itself the walk's selection — but could not be read as a config — `<reason>` is `malformed JSON`, `a directory`, or `unreadable` (a permission failure, `EACCES` or a Windows ACL denial); the line for a project config ends `canonical = .claude/coal/coalface.json` as shown above, while the line for the global file ends with that file's own absolute path (for the global `~/.claude/.coalface.json`, the full path of that file on your machine; there is no project location to move it to); the walk's own selection is unchanged, the candidate that IS selected still wins and still contributes nothing, only the silence goes. A correctly placed config, or none at all, prints nothing — even with `coalfaceMode: off`. All three lines still print under `coalfaceMode: off`; each names a file to move (`LEGACY:`), move or remove (`IGNORED:`), or fix (`UNREADABLE:`), and resolving that ends the line. On Antigravity the same lines ride the adapter's one message.

### Permissions

Workers only **read and propose** — anchor-edit text, never touching the tree; the conductor (main) is the **sole writer**, applying behind a pre-swarm snapshot with full rollback on a failed gate. Neither role deletes files or reaches the network in the swarm itself (main's apply-time gate does run the repo's own local build/test/lint). Workers get strictly less than main: no spawning, no user-facing prompts, no writes of their own.

Full series matrix + the must-fail set: [Permission Matrix](https://github.com/TheColliery/.github/blob/main/PERMISSION-MATRIX.md)

### 📊 Benchmark

**Fan-out cost, measured (2026-07-03, beta.2).** On a 6-spot shared-context job: fanning out costs **more raw tokens** than solo — the per-sub baseline × N (ad-hoc 4.2×, fully measured; CF-with-scout 5.3× — the CF arm measured 3 workers, extrapolated ×2 to 6). In **dollars**, cheap-tier fan-out lands **−15% vs a solo Opus main** (Haiku workers are \~5× cheaper/token) — but CF's scout is overhead that only pays back above a shared-context threshold, so on THIS small job CF itself costs a little MORE than plain ad-hoc. CF's real lever is **coarse packing** (fewest cheap workers): 2×3 workers = **−67% tokens vs naive ad-hoc**, the cheapest arm overall. The wallet is a **$-via-cheap-tier + right-sizing** bound, not a token saving vs solo. Full table + caveats: [`TheColliery/.github/benchmarks/CoalFace`](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalFace/RESULTS.md). (Measured at beta.2; CoalFace graduated to stable on its first real full-pipeline run — a 15-spot, 5-repo doc-conform sweep, 2026-07-09 — whose receipt matched this benchmark's honest frame: discipline and QC are the value, not a token saving.)

The structure sets the shape:

* **Wall-clock saturates at wave width.** Wall ≈ ceil(N / width) × unit-time — a 100-spot job at width 4 runs \~25 waves, not 100× faster; slicing finer than \~2-4× the width buys no wall-clock (an observation: the only reason to merge independent spots is the min-unit floor), and a full dependency chain degrades to a pipeline with **no speedup at all**.
* **The wallet is a DOLLAR bound, not free.** Spawn overhead is real and raw tokens run *higher* than solo; on cheaper worker tiers the swarm's **dollar** cost lands about the estimated solo dollar cost — "about solo cost in $, much faster, with QC", never "fewer tokens"; with main-equivalent workers it can exceed it.

### 🧭 Part of TheColliery

CoalFace is the **fan-out discipline** of the mining series, alongside its siblings:

* [CoalMine](https://github.com/TheColliery/CoalMine) — quality canaries
* [CoalTipple](https://github.com/TheColliery/CoalTipple) — model/effort routing
* [CoalBoard](https://github.com/TheColliery/CoalBoard) — consensus & debate
* [CoalHearth](https://github.com/TheColliery/CoalHearth) — session warm-resume
* [CoalWash](https://github.com/TheColliery/CoalWash) — memory defrag
* [CoalLedger](https://github.com/TheColliery/CoalLedger) — docs health
* [CoalGob](https://github.com/TheColliery/CoalGob) — OS-trash delete guard (PUBLIC BETA v0.1.0-beta.1; engine + tests ship, no skill/hook surface yet)

Install one, it stands alone; install all, they compose without conflict — CoalBoard wins on error-not-allowed work (consensus, not throughput; CoalFace may serve as its apply-hand after), CoalTipple tiering is an optional worker-cost bonus.

Shared doctrine: Phoenix-13 hooks (zero-dependency, no network, fail-silent, no child processes, deterministic), single-source-of-truth config schemas, and a strict no-overkill discipline. Series doctrine: [`TheColliery/.github`](https://github.com/TheColliery/.github).

Zero-dependency, offline by default, no API keys — "by default" because the consent-gated self-update check (`/coalface:update`) goes online; the hooks never do.

***

### 📄 License

Apache License 2.0. See [LICENSE](https://github.com/TheColliery/CoalFace/tree/main/LICENSE/README.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thecolliery.org/tools/coalface/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
