diff --git a/marketing/drafts/agent-parallel-tracking/copy.md b/marketing/drafts/agent-parallel-tracking/copy.md new file mode 100644 index 0000000..c89772d --- /dev/null +++ b/marketing/drafts/agent-parallel-tracking/copy.md @@ -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. diff --git a/marketing/drafts/agent-parallel-tracking/rationale.md b/marketing/drafts/agent-parallel-tracking/rationale.md new file mode 100644 index 0000000..cf31992 --- /dev/null +++ b/marketing/drafts/agent-parallel-tracking/rationale.md @@ -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. diff --git a/marketing/drafts/agent-run-without-asking/copy.md b/marketing/drafts/agent-run-without-asking/copy.md new file mode 100644 index 0000000..06e0c06 --- /dev/null +++ b/marketing/drafts/agent-run-without-asking/copy.md @@ -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. diff --git a/marketing/drafts/agent-run-without-asking/rationale.md b/marketing/drafts/agent-run-without-asking/rationale.md new file mode 100644 index 0000000..ce2c366 --- /dev/null +++ b/marketing/drafts/agent-run-without-asking/rationale.md @@ -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.