Mike/freno-dev
1
0
Fork 3
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

marketing: FRE-199 second pair of informational pages (drafts)

Browse Source 
- agent-parallel-tracking/ — 'How do you keep track of multiple coding
  agents?' — the multi-agent attention cluster (1xmzp2n, 1xh5cum, 1xdjb2g,
  1xipsk0, 1xk0ghj); answered with documented per-session hook events
  (session_id, typed Notification matchers) and the status line.
- agent-run-without-asking/ — 'Should you let your coding agent run without
  asking permission?' — the autonomy cluster (1xexhwf, 1xk8imc, 1xk277d);
  answered with the permission-mode ladder, the docs' own container/VM
  warning, rule precedence, sandboxing pointer, PreToolUse deny.

Internal target Mon 2026-11-09; drafted 2026-11-05. All doc claims re-read
2026-11-05 against code.claude.com (permissions, hooks, statusline). Ban
compliance: no product of ours, no competitor, no handles, no price, no
invented figures.
This commit is contained in:
fixture
2026-11-05 19:58:59 +00:00
parent 77e692273e
commit c5fb98af8d
4 changed files with 353 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
marketing/drafts/agent-parallel-tracking/copy.md Normal file
View File

@@ -0,0 +1,111 @@
# How do you keep track of multiple coding agents?
> **Status: draft — awaiting sponsor fact-check** (FRE-199 pair 2, internal
> target Mon 2026-11-09). This page never names a product of ours and never
> names a competitor.
The honest answer: not by watching them. Run three agents and the watching
already fails — the session you are not reading is the one that finished, or
the one sitting on a question, and both states look identical from the outside.
The fix is not more windows; it is giving each agent a way to announce its own
state, so checking becomes something that happens to you instead of something
you have to remember.
## Why attention is the limit
Parallel agents are cheap to start and expensive to supervise. Every running
session can stop and wait for you — a permission prompt, a question, a finished
turn — and from your side of the screen those are invisible until you go look.
Operators who run agents at scale keep describing the same wall in different
words. One practitioner running dozens of parallel threads a day put it as the
limit moving "from tokens to my attention"; another, asked how many sessions
they could run, got the answer from their own comment section: not compute —
you. A developer who ran agents unattended for a month summarised the failure
as silence: "the six hours of silence was the real problem, not the dialog
itself." And the most common collision is the simplest — two agents waiting on
you while you are deep in the third, and one of them idle so long you lost the
thread of what you asked it to do.
None of that is a speed problem. It is a visibility problem: *which* of your
agents needs you, and *how do you find out without touring every window?*
## What a per-agent signal actually is
A terminal coding agent has no shared dashboard by default — each session is
its own process, its own window. But its state changes are events, and events
can be wired outward. Claude Code documents the pieces:
- **Every state you care about fires an event.** `Stop` fires when Claude
finishes responding — the end of a turn. `Notification` fires when Claude
Code sends a notification, and the notification's type tells you which kind
of waiting it is: a `permission_prompt`, an `idle_prompt`, `agent_needs_input`,
or `agent_completed`. `SessionStart` and `SessionEnd` bracket the whole
session.
- **The event names the session it came from.** Every hook payload carries a
`session_id`, so one handler can serve every window and still know which
agent fired.
- **A hook is just a command you choose.** The events are configured in the
settings files and run whatever command you point them at — append to a log
file, update a status line, send a desktop notification that names the
project.
- **The status line can carry per-session state.** Claude Code's status line
is a customizable bar driven by a script you write; it receives session data
on every render, and the docs name "work across multiple sessions and need
to distinguish them" as a reason it exists.
The pattern in all four: stop touring windows and make each agent's
running / waiting / finished state observable where you already are.
## What to check or do
1. **Name the states before naming the tools.** For your workflow the states
are usually three — running, waiting on you, finished — and the expensive
one is always "waiting on you". A tracking setup that cannot distinguish a
permission wait from a completion will quietly hide the state that costs
the most.
2. **Wire the waiting events first.** A `Notification` hook matched on
`permission_prompt` and `agent_needs_input` catches the blocked cases; the
payload's `session_id` lets one handler label each alert with the project
it came from.
3. **Route completions separately.** `Stop` means the turn ended — not that
the work was right, and not that nothing is blocked elsewhere. Treating
"finished" and "needs you" as one notification is how a waiting agent gets
buried under a pile of done messages.
4. **Make the state visible without switching windows.** A per-session status
line, a log file the hook appends to, or a desktop notification that names
the project all work — the test is whether you can answer "does anything
need me?" without leaving the window you are in.
5. **Expect the ceiling to be yours.** Operators consistently find the
bottleneck before the machines do. The number of agents you can run is the
number whose waiting state reaches you reliably — not the number your
terminal can host.
One next step: run two agents side by side and wire only their permission-wait
events to a notification that names the project. The first time the second
agent's prompt reaches you before you happen to check its window is the whole
argument.
---
## Fact-check table (not part of the page)
Every technical claim above, with its primary source. Claims about Claude
Code's behaviour come from its own documentation, re-read 2026-11-05.
| # | Claim in the page | Source |
|---|---|---|
| 1 | `Stop` fires when Claude finishes responding; `SessionStart`/`SessionEnd` are per-session events | Claude Code hooks reference — https://code.claude.com/docs/en/hooks (hook events table; "per session: SessionStart and SessionEnd; per turn: UserPromptSubmit, Stop, and StopFailure") |
| 2 | `Notification` fires when Claude Code sends a notification; matcher supports notification types including `permission_prompt`, `idle_prompt`, `agent_needs_input`, `agent_completed` | same hooks reference (matcher table: "Notification | notification type") |
| 3 | Every hook payload carries `session_id`, the current session identifier | same hooks reference (Common input fields: `session_id` — "Current session identifier") |
| 4 | Hooks are configured in the settings files and run a command of your choosing | same hooks reference (configuration and command-hook examples) |
| 5 | The status line is a customizable bar driven by a script, receives JSON session data, and the docs name "work across multiple sessions and need to distinguish them" as a use | Claude Code status line doc — https://code.claude.com/docs/en/statusline |
| 6 | "The limit moved from tokens to my attention" / "fifty a day add up to something I could feel by Friday" | r/ClaudeCode 1xh5cum (2026-10-27, "Four months of 50+ parallel agent threads a day"), logged in `drafts/listening.md` Scan 3. Practitioner's own account, not a measurement. |
| 7 | "How many sessions before you become the bottleneck" — the thread went to compute; the attention half stayed on the table | r/ClaudeCode 1xdjb2g (2026-10-23, 72 comments), logged in `drafts/listening.md` Scan 1. |
| 8 | "The six hours of silence was the real problem, not the dialog itself" | r/ClaudeCode 1xipsk0 (2026-10-29, "~40 Claude Code agents unattended for a month"), quoted by the OP in-thread, logged in `drafts/listening.md` Scan 2. |
| 9 | Two agents waiting while the human is in the third; idle so long the thread of the task was lost; "most of my idle time came from agents waiting on a permission prompt while I was in another window" | r/ClaudeAI 1xmzp2n (2026-11-03, "How do you keep track of multiple coding agents running in parallel?"), two independent commenters, logged in `drafts/listening.md` Scan 9. |
| 10 | "You're the bottleneck agents were meant to eliminate" — approvals routing through one person | r/ClaudeCode 1xk0ghj (2026-10-31, "multiple agents working on multiple projects"), commenter's words, logged in `drafts/listening.md` Scan 4. |
**Ban compliance:** no product of ours named · no competitor named (herdr,
tmux, dashboards: none named — the page answers generically) · no handles · no
superlatives · no benchmark numbers · no invented testimonials (anecdotes are
real threads, described without handles) · no price · no roadmap dates.

71
marketing/drafts/agent-parallel-tracking/rationale.md Normal file
View File

@@ -0,0 +1,71 @@
# Rationale — "How do you keep track of multiple coding agents?"
FRE-199 item 1, page 1 of the second pair. Drafted 2026-11-05 by CMO (internal
target Mon 2026-11-09, beaten by four days — the backlog held, so drafting
early cost nothing).
## The phrase
Primary: **"how do you keep track of multiple coding agents running in
parallel"** (variants: "how many sessions before you become the bottleneck",
"which agent is waiting", "agent tracking dashboard").
## Why this phrase won the slot
- **Strongest recurrence in the backlog.** Seven independent threads across
nine scans state the multi-agent attention problem in their own words — more
than any other cluster after the pair-1 phrases. It is the natural next page:
the pair-1 pages answer *one* agent's silence (done-signal) and *one*
permission wait (waiting-on-permission); this is the fleet-scale version of
the same pain, and the buyers are already at fleet scale.
- **Buying intent.** Every quoting operator is running multiple agents *now*
and losing time to supervision, not exploring.
- **Answerable honestly, generically.** The mechanism (per-session hook events
with `session_id`, typed notifications, the status line) is documented in the
agent's own reference; every claim traces to it. No product needed.
- **Distinct from pair 1.** Done-signal owns "one agent, is it finished";
waiting-on-permission owns "one agent, why is it blocked". This page owns
"several agents, which one needs me" — the phrase, the evidence, and the
mechanism (typed Notification matchers, `session_id`, status line) do not
overlap pair 1's.
## Evidence trail
| Thread | Date | What it showed |
|---|---|---|
| r/ClaudeAI 1xmzp2n — "How do you keep track of multiple coding agents running in parallel?" | 2026-11-03 | The exact question as a fresh thread: "How do you notice when one is waiting, done, or stuck?"; two commenters independently: agents "sat waiting on a permission prompt while I was deep in the third", idle "long enough that I lost the thread of what I had asked it to do" |
| r/ClaudeCode 1xh5cum — "Four months of 50+ parallel agent threads a day" | 2026-10-27 | "The limit moved from tokens to my attention"; "fifty a day add up to something I could feel by Friday" |
| r/ClaudeCode 1xdjb2g — "How many sessions can you run before you become the bottleneck?" | 2026-10-23 | 72 comments; the thread went to compute and left the attention half open |
| r/ClaudeCode 1xipsk0 — "~40 Claude Code agents unattended for a month" | 2026-10-29 | "The six hours of silence was the real problem, not the dialog itself" |
| r/ClaudeCode 1xk0ghj — "multiple agents working on multiple projects" | 2026-10-31 | "If every decision routes through you, you're the bottleneck agents were meant to eliminate" |
| Hacker News 50298436 (herdr launch) | 2026-10-30 | A 30-year tmux user's stated switch reason: "visual indication which agent is working and which is waiting for an input" — used in rationale only; the page does not name any tool |
All rows live in `drafts/listening.md` (The-Nook local master line, single
canonical copy per FRE-748) with URLs and verbatim quotes.
## Gates before this page ships
1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
Freno). Page moves `drafts/` → `pending/` → `approved/` on his read, per
the marketing tree's hard rule.
2. **CTO eyes on the agent-behaviour claims** — five doc-sourced claims
(hooks reference ×4, statusline doc ×1), all re-read 2026-11-05. Routed to
the CTO per the FRE-199 plan.
3. **Publish path:** `approved/` → a human places it on nook.freno.me.
Nothing posts itself.
## Ban compliance (FRE-199 + positioning.md rule 1)
- The Nook: not named. The notch, the island, the companion: not mentioned.
- Competitors: not named. The herdr evidence is rationale-only; the page's
"what to check" recommends no tool at all — states and wiring, not products.
- Claude Code is named only as the subject whose documented behaviour the page
explains, with its own docs as the source — same status as pair 1.
- No superlatives, no benchmark numbers, no invented testimonials, no price,
no roadmap dates. Anecdotes are real threads, described without handles.
## Cadence note
Second pair. Queue behind it: the run-without-asking cluster (same pair), the
fan-control phrase, and the invisible-permission variants — above the
three-candidate floor. Two a week holds.

96
marketing/drafts/agent-run-without-asking/copy.md Normal file
View File

@@ -0,0 +1,96 @@
# Should you let your coding agent run without asking permission?
> **Status: draft — awaiting sponsor fact-check** (FRE-199 pair 2, internal
> target Mon 2026-11-09). This page never names a product of ours and never
> names a competitor.
You can — and the honest answer is that "should" is not one decision but two:
what you are letting it do, and what happens when it does the wrong thing.
Every operator who runs agents unattended converges on the same split — a free
hand on what git can undo, a confirmation on what it can't — and the agent's
own permission modes exist to draw that line somewhere you choose, not
somewhere a flag chooses for you.
## The mechanism: a spectrum, not a switch
Claude Code's permission modes form a ladder from "ask for everything" to "ask
for almost nothing", and each rung has a documented meaning:
- **`default`** prompts on the first use of each tool.
- **`acceptEdits`** auto-accepts file edits and common filesystem commands
(`mkdir`, `touch`, `mv`, `cp`) inside the working directory.
- **`plan`** reads files and runs read-only shell commands but does not edit
your source files — the agent explores, you approve the plan.
- **`auto`** runs without routine prompts; before actions such as shell
commands and network requests run, a background classifier checks that they
align with your request.
- **`bypassPermissions`** skips permission prompts, except for actions no mode
auto-approves.
Two documented facts should shape where you stop on that ladder. First, the
docs' own warning on the top rung: in `bypassPermissions` mode Claude Code
skips prompts — including for writes to protected paths such as `.git` — and
the mode belongs "in isolated environments like containers or VMs where Claude
Code can't cause damage". Second, enforcement is real, not advisory: the docs
state plainly that "permission rules are enforced by Claude Code, not by the
model" — a `CLAUDE.md` instruction asking nicely for permission changes
nothing.
## What to check or do
1. **Decide by blast radius, not by annoyance.** The question "how do I get
fewer prompts?" tempts a jump to the top of the ladder. The better
question: which of this agent's actions would be *undoable* if wrong? Edits
inside a git worktree are; `rm -rf` on the wrong path, a pushed commit, and
a message sent to a third party are not.
2. **Move down the ladder one rung at a time.** `acceptEdits` in a worktree
covers most of the prompt volume with the undo still in reach. If you
consider `auto` or `bypassPermissions`, the docs' own container-or-VM
condition is the bar: isolation first, autonomy second.
3. **Write the rules instead of trusting the mode.** Rules are evaluated in
order — deny, then ask, then allow — and the first match wins, so a broad
deny holds even against a narrower allow. `Bash(git commit *)` allowed with
`Bash(git push *)` denied is a policy the agent cannot talk its way around.
4. **Know what the rules do not cover.** A Bash rule matches the command text
Claude writes, and the docs are explicit that this "isn't a security
boundary around the program" — the same binary invoked by another path is
not matched. For filesystem and network enforcement that does not depend
on command text, the docs point at sandboxing.
5. **Use hooks as the programmable layer.** A `PreToolUse` hook sees every
tool call before it runs and can return a `deny` decision — the reference
builds one that blocks `rm -rf`. A silent hook does not approve anything;
the call just continues through the normal permission flow.
6. **Leave the failure path a way to reach you.** An unattended run that hits
a prompt nobody sees stops silently — that is the failure mode of unattended
work, not of permissions. Whatever mode you pick, wire the
"waiting on you" event somewhere you will actually notice.
One next step: write down the three actions your agent takes that you could
not undo, and put them in `deny` or `ask` rules today. Whatever mode you run
above them, those three now require a human — which is the whole point of the
ladder.
---
## Fact-check table (not part of the page)
Every technical claim above, with its primary source. Claims about Claude
Code's behaviour come from its own documentation, re-read 2026-11-05.
| # | Claim in the page | Source |
|---|---|---|
| 1 | Mode meanings: `default` prompts on first use; `acceptEdits` auto-accepts file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`) in the working directory; `plan` reads files and runs read-only shell commands but doesn't edit source; `auto` runs without routine prompts with a background classifier checking alignment; `bypassPermissions` skips prompts except actions no mode auto-approves | Claude Code permissions doc — https://code.claude.com/docs/en/permissions (Permission modes table) |
| 2 | Docs' warning: in `bypassPermissions` mode Claude Code skips prompts including for writes to protected paths such as `.git`; "Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage" | same permissions doc (warning under the modes table) |
| 3 | "Permission rules are enforced by Claude Code, not by the model" | same permissions doc (note under Manage permissions) |
| 4 | Rules evaluated in order deny → ask → allow; first match wins; a broad deny holds against a narrower allow | same permissions doc (Manage permissions) |
| 5 | A Bash rule matches the command text Claude writes and "isn't a security boundary around the program" (`Bash(curl *)` doesn't stop `/usr/bin/curl …`); for filesystem/network enforcement independent of command text the docs point at sandboxing | same permissions doc (What a Bash rule doesn't match) |
| 6 | A `PreToolUse` hook fires before a tool call executes, can block it, and can return a `permissionDecision` of `"deny"`; the reference builds a hook that blocks `rm -rf`; a silent hook does not approve — the call continues through the normal permission flow | Claude Code hooks reference — https://code.claude.com/docs/en/hooks (PreToolUse decision control walkthrough) |
| 7 | Undo-split practice ("free hand on what git can undo, confirmation on what it can't") | r/ClaudeCode 1xkoz06 (2026-10-31), commenter's described practice, logged in `drafts/listening.md` Scan 3 addendum; also r/ClaudeCode 1xexhwf commenters (VM, worktrees, blast-radius split). Described as operator practice, not a rule. |
| 8 | An unattended run that hits a prompt nobody sees stops silently | r/ClaudeCode 1xipsk0 (2026-10-29), commenter: "A run started from launchd or a background service can hit a prompt that no one will ever see", logged in `drafts/listening.md` Scan 2. |
| 9 | The trust asymmetry: comfortable with a model writing code, "considerably less comfortable giving an autonomous agent broad access to my development environment" | r/ClaudeCode 1xk8imc (2026-10-31, "Has anyone built a safe, autonomous coding workflow…?", 43 comments), OP's words, logged in `drafts/listening.md` Scan 4. |
| 10 | The operator's own safety menu: "committing before every run? containers? `--dangerously-skip-permissions` and hoping?" | r/ClaudeAI 1xk277d (2026-10-31, "How often has a coding agent done something you had to undo?"), OP's words, logged in `drafts/listening.md` Scan 4. Quoted as the question's shape, not as guidance. |
**Ban compliance:** no product of ours named · no competitor named · no
handles · no superlatives · no benchmark numbers · no invented testimonials ·
no price · no roadmap dates. The docs' container/VM warning is quoted as the
agent's own documentation, not as our policy.

75
marketing/drafts/agent-run-without-asking/rationale.md Normal file
View File

@@ -0,0 +1,75 @@
# Rationale — "Should you let your coding agent run without asking permission?"
FRE-199 item 1, page 2 of the second pair. Drafted 2026-11-05 by CMO (internal
target Mon 2026-11-09, beaten by four days).
## The phrase
Primary: **"do you let your coding agent run without asking permission"**
(variants: "safe autonomous coding workflow", "approve every step or skip
permissions", "is dangerously-skip-permissions safe").
On the standing phrase list (`drafts/listening.md` §The phrase list: "do you
let claude code run without asking").
## Why this phrase won the slot
- **Recurrence with independence.** Four separate threads state the autonomy
question from four angles: the direct one (1xexhwf, 24 comments), the trust
asymmetry (1xk8imc, 43 comments), the safety menu (1xk277d), and the
remove-permissions ask (1xfe6eh — Desktop, recorded, not answered). The
cluster has run continuously since Scan 1.
- **Buying intent.** These are people configuring or rejecting autonomy right
now — the objection vocabulary came straight out of this cluster
("--dangerously-skip-permissions and hoping").
- **Answerable honestly, generically.** The mode ladder, the docs' own
container/VM warning, the enforcement note, and `PreToolUse` deny are all
documented; every claim traces to the agent's docs. No product needed.
- **Distinct from pair 1's permission page.** `agent-waiting-on-permission`
answers "why is it *blocked* and why didn't I know" — the visibility of a
single stuck prompt. This page answers "should I *grant* autonomy and how do
I bound it" — the mode ladder, rule precedence, sandboxing, and hooks as
enforcement. Shared vocabulary (modes, rules) exists because the docs are
one system; the question, the claims, and the advice do not overlap.
## Evidence trail
| Thread | Date | What it showed |
|---|---|---|
| r/ClaudeCode 1xexhwf — "Do you let Claude Code run without asking, or approve every step?" | 2026-10-25 | The direct question, 24 comments; the thread became a safety argument (VM, worktrees, empty-variable `rm -rf`) — that argument *is* the page's subject |
| r/ClaudeCode 1xk8imc — "Has anyone built a safe, autonomous coding workflow…?" | 2026-10-31 | "Comfortable having another model work on code. Considerably less comfortable giving an autonomous agent broad access to my development environment" — the trust asymmetry, 43 comments |
| r/ClaudeAI 1xk277d — "How often has a coding agent done something you had to undo?" | 2026-10-31 | "What you do to stay safe today: committing before every run? containers? `--dangerously-skip-permissions` and hoping?" — the operator's own menu |
| r/ClaudeCode 1xipsk0 — "~40 agents unattended for a month" | 2026-10-29 | "A run started from launchd or a background service can hit a prompt that no one will ever see" — the unattended failure path |
| r/ClaudeCode 1xkoz06 | 2026-10-31 | The undo-split practice (also cited on pair 1; real thread, described without handles) |
| r/ClaudeAI 1xfe6eh — "How can I remove Claude's need to ask me for permission…" | 2026-10-30 | Recorded, not used: Claude Desktop computer-use, not Code — a mention there would be noise. Shows the phrase's reach |
All rows live in `drafts/listening.md` (The-Nook local master line, single
canonical copy per FRE-748) with URLs and verbatim quotes.
## Gates before this page ships
1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
Freno). Page moves `drafts/` → `pending/` → `approved/` on his read.
2. **CTO eyes on the agent-behaviour claims** — six doc-sourced claims
(permissions doc ×5, hooks reference ×1), all re-read 2026-11-05. Routed to
the CTO per the FRE-199 plan.
3. **Publish path:** `approved/` → a human places it on nook.freno.me.
Nothing posts itself.
## Ban compliance (FRE-199 + positioning.md rule 1)
- The Nook: not named. The notch, the island, the companion: not mentioned.
- Competitors: not named. Sandboxing and hooks are described as the agent's
own documented mechanisms, not as anyone's product.
- Claude Code is named only as the subject whose documented behaviour the page
explains, with its own docs as the source — same status as pair 1.
- No superlatives, no benchmark numbers, no invented testimonials, no price,
no roadmap dates. Anecdotes are real threads, described without handles.
## Cadence note
Second pair. Queue behind it: the fan-control phrase ("mac fan control
claude", standing phrase list), the invisible-permission variants
(dontallow/TCC cluster), and the notification-reliability thread (1xm6frp,
held back for overlap with done-signal). Above the three-candidate floor; two
a week holds.