--- schema_version: 1 revision: "22ce5d34dbcb5a78" --- # Agent Fieldnotes Working knowledge for building software with agents. # A trustworthy software factory loop Bound one recurring task, name the consequential action, and earn autonomy with observable evidence. ## The unit of work is a loop, not an agent A software factory is not a pile of agents. The agent is one machine inside an inspectable loop: **Input → Boundary → Action → Evidence → Decision → Receipt.** Start with one recurring task and one costly failure. Define the minimum context, permission boundary, exact human gate, and success evidence before adding autonomy. A gate is a named stop, named evidence, and explicit approval before a consequential action—not a request to review something eventually. The operating stages are **Bound → Compose → Run → Verify → Preserve → Promote**: - **Bound:** state the desired outcome, inputs, exclusions, and the first expensive, destructive, public, or hard-to-reverse action. - **Compose:** gather current, relevant evidence that changes the decision, implementation, or verification; do not equate volume with completeness. - **Run:** execute the smallest reversible experiment inside the agreed permission boundary. - **Verify:** demand the exact observable signal that proves the result; an agent saying “done” is not that signal. - **Preserve:** save the outcome, settled decision, rejection reason, failed attempts, and repeatable check so another session can continue from evidence. - **Promote:** automate only after repeated manual receipts establish that the signal is useful, owned, affordable, and recoverable. ## Put each kind of rule in its proper place Repository files explain stable intent. Launch wrappers normalize repeated choices. Command decorators bring warnings to the moment of action. Human gates protect consequential work. Automated checks prove the condition they actually measure. None substitutes for the others. Safety is a layered design, not a permission-bypass switch. A shell function that can be bypassed with `command` is guidance with teeth, not confinement. A stripped prompt context is not a filesystem or network sandbox. A dry run or stub can prove wiring without proving behavior against a real service. ## Choose a route by the problem A complete first pass connects the core boundary audit, environment policy, annotated image, focused context packet, repeatable flow, structural alternatives, independent reasoning, and product vision. A quick start takes the core loop, one visual task, and a small set of alternatives. A problem-led route enters at the current bottleneck: - **Control and safety:** bound the task, place policy near the action, make proof visible. - **Prompt and context:** use visual evidence, compose a focused packet, promote repeated prompts into inspectable flows. - **Design and taste:** expose structural alternatives and preserve why one won. - **Continuity and debugging:** recover trustworthy state and join human testimony to runtime facts. - **Advanced reasoning and video:** escalate a hard decision, not an entire workflow by default. - **Vision and automation:** state durable direction, promote proven signals, and keep unresolved work explicit. For each topic, move through **orientation → concept → evidence → practice → reflection → next action**. Copying a prompt, attempting it, and verifying its result are separate states. “Now” establishes the core loop; “Next” makes it repeatable; “Later” adds expensive or specialized capabilities; “Reference” retains unresolved status. ## Operating practice ### Bound one factory loop #### What to notice Turn one recurring task into an inspectable loop with inputs, permissions, proof, a **human gate**, and a **durable receipt**. #### Try this Write Input → Boundary → Action → Evidence → Decision → Receipt for one task you already repeat. > “If the agents can't see it, it doesn't exist.” John Lindquist · [00:23:25](https://proud-anchor-53zn.here.now/watch.html?t=1405#recording-player) #### Concept A software factory is not a pile of agents. The agent is one machine inside the loop. Start with the smallest reversible bet, then name the exact action that must stop for human approval. #### Reflection A gate is not “review this sometime.” It is a named stop, named evidence, and explicit approval before a consequential action. **Recording evidence:** listen at 00:15:52. > “Alignment is the key word here. Is the agent aligned with your vision?” John Lindquist · [00:32:52](https://proud-anchor-53zn.here.now/watch.html?t=1972#recording-player) [Open How Agentic Work Is Evolving](https://hallowed-entry-96xv.here.now/) #### Links shared for this topic - [Workshop agenda](https://ember-bodhi-scrr.here.now/) — The original workshop sequence and setup hub. - [Coding with Agents field guide](https://kindly-mirage-ejqd.here.now/) — The earlier field guide that grounded the workshop’s operating principles. - [Cursor Origin](https://cursor.com/origin) — An autonomous coding-agent product discussed during the opening model survey. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=952#q1-factory-loop) ## Evidence limits that matter A file appearing, a command running, and a check passing are separate events. Preserve failed attempts instead of upgrading them into success. The environment demonstration surfaced diagnostics, and the recorded MDFlow wrapper exercise did not become a clean success. Those are failure-aware examples, not universal installation proofs. Tool versions, model names, prices, subscription eligibility, limits, and predictions are contextual claims from the recorded discussion—not current purchasing guidance. Current dotfiles and comparative model-cost guidance remained unresolved. The Markers material is a prepared follow-up, not a dedicated recorded section. Keep exact published resource links separate from uncertain text read off a screen. A transcript establishes what was said; a recording can reveal visible action; a prepared recipe establishes intended behavior; only the appropriate check establishes success. Reference ID: factory-factory-loop Topic: Principles Sources: - [Software factory operating model](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop) --- # Preserve contracts and state machines while code changes > Original source pages and recordings require authorized access. The full article text here is public. The architectural priority is shifting your loyalty away from individual generated code artifacts and toward durable structures: clear natural-language goals, recorded human behavior, reviewable diffs, state-machine boundaries, isolated modules, and living project guardrails. John’s big point is blunt: tools, models, harnesses, plugins, and even code can change or be regenerated, so the professional edge is defining intent, preserving evidence, reviewing the concrete diff, and keeping the architecture understandable. ## Working outcomes - Write natural-language contracts and use video as requirements - Treat code as a throwaway artifact behind a state machine + modules - Maintain living guardrails while treating generated code as disposable and ideas as durable ## Concepts and consequences ### Natural-Language Contracts A natural-language contract is a plain-English description of what a tool, app, or agent is supposed to do. John frames this as an "agent first" mindset: define the work in language so the underlying tool can change without destroying the workflow. **Why it matters:** It keeps you from overfitting to today’s specific tool, harness, plugin, or workflow. The portable asset is the intent. ### Video-as-Requirements John recommends recording yourself or users actually using the app while speaking intent out loud. The recording captures clicks, typing, layout changes, responsive behavior, and what the person wanted from the app. **Why it matters:** It captures human interaction that is hard to fully express in written specs. A video-capable model can help turn that usage into requirements, goals, and QA stories. ### Diff-Driven Review John reduces an agent run to a simple equation: prompt plus agent, harness, and skills equals diff. The diff is the concrete artifact worth reviewing, testing against, and handing to a fresh session for critique. **Why it matters:** It gives you a clean review loop. A second agent can inspect the goal and diff without inheriting the first agent’s assumptions. ### State Machines and Modular Boundaries When a codebase can grow by tens of thousands of lines overnight, John says the safety comes from structure: isolated modules and business logic that is navigable through state machines. **Why it matters:** These boundaries let humans and agents digest, regenerate, refactor, or replace implementation details without losing the shape of the product. ### Living Guardrails Files like agents.md or claude.md should stay fairly minimal and evolve with the project. John suggests reviewing recent commits, learning from mistakes, and iterating on the agent instructions over time. **Why it matters:** Mistakes become useful artifacts when they update the project’s guardrails. The file should capture real project knowledge, not a giant upfront rulebook. ### Disposable Code, Durable Ideas John explicitly says not to get too attached to a specific workflow or generated code artifact. A plugin, hook, or implementation can be generated quickly and thrown away later. **Why it matters:** The idea, boundary, state machine, module structure, and product intent matter more than the exact code the current agent happened to write. ## Reference tools and resources ### OpenAI Codex The coding-agent environment John referred to when discussing skills, agents.md, generated code, and diffs. **Use when:** Use it when you want an agent to work inside a project, then review the resulting diff as the main artifact of the run. [Reference](https://github.com/openai/codex) ### AGENTS.md A project-level instruction file that gives coding agents local context, conventions, and constraints. **Use when:** Use it as a small, evolving guardrail file; John recommended reviewing recent commits and updating it with lessons from mistakes. [Reference](https://developers.openai.com/codex/guides/agents-md) ### Video-capable multimodal models John named Gemini as an example of a model that can understand videos of app usage. **Use when:** Use this kind of model when narrated screen recordings contain richer requirements than a written prompt alone. search: multimodal video understanding app requirements ### Git diffs The concrete artifact John treated as the output of an agent run: prompt plus agent, harness, and skills equals diff. **Use when:** Use diffs for review, testing discussions, logs, and clean-session critique. search: git diff ## Recommendations and best practices - Define goals and tool contracts in natural language so the underlying agent, harness, or implementation can change. - Record real app usage with narration; treat the video as a requirements and QA artifact, not just a demo. - Do not over-specify exactly how the agent must prove success; keep your own QA judgment in the loop. - Review diffs as the primary artifact of an agent run, then give the goal and diff to a fresh session to find missed cases or tests. - Keep generated code disposable, but keep product intent, state machines, module boundaries, and names stable enough to reason about. - Use agents.md or claude.md as living documents: update them from recent commits, repeated mistakes, and real project constraints. - Stay flexible; do not define yourself too tightly by one language, framework, tool, harness, or generated implementation. ## Practice and acceptance criteria Practice treating generated code as replaceable while making your intent, evidence, architecture, diffs, and guardrails durable. ### Checklist 1. Choose one feature or workflow in a real project and write a short natural-language contract describing the goal, desired behavior, and what would convince you it works. 2. Record a 1–3 minute narrated walkthrough of the current app or target behavior, saying what matters as you click, type, resize, wait, or notice broken behavior. 3. Ask a video-capable model to extract requirements, user actions, expected behavior, and QA stories from the video, then review the output with your own judgment. 4. Rewrite the feature's core behavior as a state machine with named states and transitions, then identify which modules should own which responsibilities. 5. Create or revise agents.md or claude.md with only useful project-specific guidance from recent commits, repeated mistakes, architecture boundaries, and discovered constraints. 6. Run an agent on a small isolated module using the contract, state machine, and guardrail file as context, then inspect the Git diff as the primary artifact. 7. Start a fresh agent session and give it the original goal plus the diff only; ask it to identify missing tests, risky assumptions, and behavior that may violate the contract. ### Contract Before Code **Difficulty:** Easy Pick a small feature request and write a natural-language contract before opening the code. Include what the user wants, what must not change, what counts as done, and what evidence would convince you it works. **Done when:** A fresh agent or teammate can read the contract and correctly describe the expected behavior without seeing your implementation notes. ### Video QA Story **Difficulty:** Medium Record yourself using a real app flow while narrating intent, then ask a video-capable model to turn the recording into requirements, expected behavior, and QA stories. **Done when:** The resulting QA story captures a meaningful user outcome from the video, not just a brittle click path or superficial selector. ### State Machine Boundary Pass **Difficulty:** Medium Take a messy feature with branching behavior and describe it as a state machine. Then split the surrounding implementation into clear modules with separate responsibilities. **Done when:** A human or agent can look at the state machine and module names and understand the shape of the behavior without reading every implementation line. ### Diff Injection Review **Difficulty:** Hard Let an agent implement a bounded change, then copy only the original goal and resulting Git diff into a fresh session. Ask the new session to critique the change, propose missing tests, and flag contract violations. **Done when:** The second review finds at least one concrete risk, missing test, or confirmation point that improves your final merge decision. ## Questions to test understanding ### What is the main value of a natural-language contract in an agent-first workflow? - **A.** It replaces the need to review generated code. - **B.** It preserves the intended behavior even as tools, agents, or implementation details change. - **C.** It guarantees the agent will choose the best library automatically. - **D.** It turns every requirement into a deterministic browser test. **Answer: B.** The contract is the portable asset: it defines what should happen in plain language so the underlying harness, agent, tool, or code can change without losing the workflow's intent. ### Why did John frame video recordings as useful requirements artifacts? - **A.** Because videos are easier to store than written specs. - **B.** Because videos eliminate the need for human QA judgment. - **C.** Because narrated app usage captures human intent, clicks, layout behavior, and outcomes that text often misses. - **D.** Because videos always produce more stable selectors than browser automation tests. **Answer: C.** A narrated walkthrough can show what the user actually does and cares about. John emphasized that clicking, typing, resizing, and talking through the desired behavior captures requirements that are hard to express as text alone. ### In John’s diff-driven review loop, what is the most important artifact to inspect after an agent run? - **A.** The agent's full chat transcript. - **B.** The exact model name used during the session. - **C.** The generated Git diff, plus any tests or behavioral changes it implies. - **D.** The longest file the agent edited. **Answer: C.** John described the useful output of an agent run as the concrete diff. Reviewing that diff, and giving it to a fresh session for critique, helps avoid inheriting the first session's assumptions. ### A project suddenly grows by 30,000 generated lines. According to John, what makes that complexity manageable? - **A.** Reading every generated line before allowing any merge. - **B.** Keeping all business logic in one large file so the agent has full context. - **C.** Relying on comments to explain generated code after the fact. - **D.** Using isolated modules and state machines as stable structural boundaries. **Answer: D.** John said the two anchors are modular structure and state machines. If responsibilities are separated and business logic is navigable through states, humans and agents can digest the project without memorizing every generated line. ### What is the best way to maintain an agents.md or claude.md file? - **A.** Keep it fairly minimal and update it when real mistakes, recent commits, or project constraints reveal useful lessons. - **B.** Fill it upfront with every coding preference you can think of. - **C.** Use it only for generic style rules that apply to every repository. - **D.** Avoid changing it once the first version works. **Answer: A.** John did not give strict rules for agents.md. He described it as something that should evolve with the project, especially by learning from mistakes and reviewing recent commits. ## Reflection prompts - In your current codebase, what should be treated as durable: product intent, state machines, module boundaries, tests, guardrails, or the generated code itself? - Where do agents repeatedly make the same kind of mistake in your projects, and what small agents.md or claude.md update would help prevent that without becoming noisy? - Which side of the future engineering path are you actively building right now: deeper hyper-expert judgment, broader project-creator leverage, or a deliberate mix of both? ## Further applications 1. Record a short narrated app walkthrough, then ask a video-capable model to extract the user goals, actions, expected behavior, and QA stories. 2. Run a diff injection review: give a clean agent session only the original goal and the previous agent’s diff, then ask what tests or risks are missing. 3. Rewrite one complex feature as a state machine with named states and transitions, then map the related implementation into isolated modules. 4. Review recent commits and agent mistakes, then add only the most useful project-specific lessons to agents.md or claude.md. 5. Map your own growth into two possible tracks: hyper-expert depth in a critical technical area and broader project-creator leverage with agents. ## Applied exercises The Diff Injection Test Routine: Start a completely isolated, clean repository session. Take a structural Git diff produced by a previous development agent run and supply it to an entirely fresh agent instance. Instruct the new agent to inspect the diff in isolation to map out potential logic omissions, design flaws, or generate parallel automated test scripts. State Machine Scaffolding Challenge: Take a complex application feature that typically demands several thousand lines of arbitrary code and map it out strictly as a deterministic state machine using human-readable state configurations and events. Feed this explicit state map to an agent to automatically implement the underlying procedural code. Evaluate how quickly the agent updates the feature when you alter only the top-level state machine boundaries. ## Questions and answers ### Did you show a goal example for the PACX? I think I will convert from my test to QA packages that are stable. Yes, the Pack X skill example was bundled inside the Oracle tool configuration shown at the very beginning of the workshop day. Developers can utilize the built-in Codex create skill module to automatically ingest local CLI tools and map them out for agent execution. John verifies that a working example of the PackX tool execution skill was compiled inside the Oracle system harness configuration, and advises scrolling back to the footage from the beginning of the morning session to track its initial execution step-by-step. ### To followup what you said before, in general for others in how they can become ai literate but also live in a new world with ai and find their new role with intelligence, you mentioned going camping..., do you have general questions you get from others, and answers to those bigger questions? John notes he deliberately minimizes deep discussions about agentic futures with people outside the immediate AI space because the actual scale of near-term disruption sounds unbelievable or alarming. He emphasizes that the path forward requires extreme individual flexibility and an openness to adapting to entirely new methodologies, highlighting how jobs structured around legacy knowledge retrieval (like English professors) face immense pressure to re-evaluate their core function. ### Ya that was my question — use ai to go deeper in the domain we have mastered or use it to learn new skills and go wide. I see arguments for both. John advises using AI aggressively to expand horizontally ("go wide") across tools, frameworks, and languages without getting emotionally or professionally bottlenecked by a single technology identity (e.g., identifying strictly as a "React developer"). He suggests viewing generated code as highly disposable throwaway artifacts, focusing personal mastery on architecture, systems connection, and core concepts rather than syntax. John addresses this across the chunk by suggesting that real optimization lies in using agents to rapidly span broad domain boundaries ("go wide"), while selecting distinct low-level systemic execution areas to remain extreme experts. ### Can you scare us? give us your thoughts on disruptions? speculate? for businesses, for developers? John offers the following as speculation about disruption, not established outcomes or a reliable timeline. John provides a physical and digital breakdown:Physical: Domestically, the arrival of capable robotics (laundry automation, nannies) will radically reshape home environments within a high-degree certainty window.Digital/Privacy: Absolute personal privacy will effectively cease to exist as environmental inputs (microphones, cameras) become ubiquitously parsed by agents.Social/Behavioral: Influencers could deploy localized agents to design and lock audiences into recursive consumption loops surrounding custom compound generation (like specialized peptide protocols), completely bypassing traditional institutional frameworks. John sketches out three disruptive focus points:Hardware Evolution: The introduction of capable domestic automation robotics (like laundry and care robots) will transform quality of life faster than most people realize.The Death of Privacy: Ubiquitous household microphones and data channels will erase remaining presumptions of digital or physical privacy.Social Engineering Biohacking: Influencers could use dedicated AI agents to steer audiences toward personalized routines or chemical dependency loops (like proprietary peptide formulas) via highly tailored media streams. ### You hit this earlier but any final thoughts on this new normal where a project turns into 30k lines of code over night. How to manage that complexity (high level thoughts) Complex code bases must adhere to two absolute architectural anchors: Isolated Modular Components and State Machines. If the discrete business behaviors are written as navigable state transitions and logic is strictly compartmentalized, the sheer volume of code becomes secondary. A human can quickly parse the layout, and an agent can safely refactor or completely regenerate the entire implementation block straight from the state configuration rules if needed. John details a two-tier architectural defense: isolate software logic into highly distinct modules and route core flow through state machines. If these twin guardrails remain cleanly documented in understandable English, the underlying bulk of the code becomes swappable; a developer can pass the state machine configuration to an agent to reconstruct missing chunks reliably. ### Do you use agents.md or claude.md, guardrails.md...? don't do this... tool usage specificity... etc John implements a Claude.md profile file and establishes a symbolic link (symlink) mapping agents.md directly to it (noting a slight uncertainty regarding Claude's native handling of directory symlinks). He recommends avoiding highly complex, rigid rule frameworks. Instead, instruct your agent to inspect recent Git commits and automatically document its own operational boundaries, rules, and discovered project constraints into agents.md at the end of every active run cycle. John builds out files like agents.md or Claude.md, using built-in system hooks like Claude's /init macro or automating file creation directly inside Codex. He often maps them together via local file system symlinks. He notes he avoids rigid rules for these documents, letting them adapt as real execution errors happen so the agent preserves context dynamically. ### How much time should a junior engineer invest in learning a programming language? [...] How should a senior invest in advancing their skills and programming language ecosystem? Engineering will bifurcate. A specialized subset of "hyper-experts" will remain highly essential to control low-level optimization bottlenecks that conversational English cannot adequately resolve—specifically memory management, browser layout engine performance, low-level networking protocols, security vectors, and intense mathematical systems. However, the vast majority of traditional engineering roles focused on standard app creation will shift toward becoming high-level "project creators," where deep syntax mastery matters less than system coordination and rapid execution. John explains that the traditional identity of a framework engineer (e.g., an "AngularJS developer") is disappearing. He divides the upcoming landscape into low-level performance experts (focusing on custom browser rendering, memory safety, hardware optimization, and network scaling) and holistic project creators who coordinate agent workers via natural language profiles. ### Is it the facebook backlog or the episodelist of black mirror? John admits he is not fully caught up on the most recent seasons of Black Mirror, but notes that the series has proven historically prophetic regarding technological feedback loops on human behavior. No detailed standalone analysis of the series is captured. ### Are you familiar with actor model? relates to your state machine comment The companion connects the actor model to decoupled actors, state machines, and isolated messaging boundaries: those structures make code paths legible to people and agents. No detailed standalone actor-model implementation is captured. ## Operational playbooks - [Video as requirements](/topics/foundations-video-requirements-playbook/) - [Codex Primitive Field Guide](/topics/foundations-codex-primitives-field-guide/) - [Browser Proof Field Guide](/topics/foundations-browser-proof-field-guide/) - [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/) - [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-11.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-11.html) ### Visual reference index - [04:51:20](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-1): Editor/workspace view around agents.md and local project context; Agent Browser cookie details are transcript evidence, not clearly visible here. - [04:52:55](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-2): Terminal/workspace view during PackX/PACX goal-package discussion. - [04:54:10](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-3): Terminal/workspace view during video-as-requirements discussion; no explicit diagram is visible in this still. - [04:57:02](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-4): Codex application update dialog visible over the workspace. - [05:04:00](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during disruption and future-role discussion. - [05:07:35](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during git-diff-as-artifact discussion. - [05:09:40](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during state-machine and module-boundary discussion. - [05:11:50](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during agents.md / Claude.md guardrail discussion. ## Durable operating principles - **Separate your contexts.** Research, implementation, and quota-sensitive agent work are different jobs. Route each to the surface that fits. - **Conduct, do not just type.** Use manager and worker panes so your job shifts toward intent, review, and orchestration. - **Give agents memory and guardrails.** Agent-managed folders, check-back files, and AGENTS.md rules keep long runs grounded without stuffing the context window. - **Trust current source.** Treat code as the source of truth, snapshot broad context when needed, and write design decisions where agents can find them. - **Hook the lifecycle.** User-prompt, tool-use, and stop hooks let you encode expertise at the points where the agent can actually use it. - **Run autonomy behind gates.** Background daemons, deterministic checks, and overnight loops are useful when the verification path is explicit. The code can be disposable, but the workflow should leave behind receipts, constraints, and a next action. Reference ID: foundations-contracts-state-machines-and-code Topic: Principles Sources: - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Video as requirements playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already debug behavior in running apps, not just in source files. A narrated screen recording gives an agent the missing layer: what the user clicked, typed, expected, noticed, and wanted changed, then turns that into a concrete QA story and implementation brief. [Core principles](/topics/foundations-contracts-state-machines-and-code/) ## Copy-paste workflow **When to use:** When showing-and-narrating is faster than writing a perfect spec. Record yourself using the app while speaking intent, then have a multimodal model extract acceptance criteria and edge cases as agent-ready requirements. ### Copy-paste prompt ```text I'm going to turn a narrated screen recording into agent-ready requirements instead of writing a perfect spec. 1. I will record a short narrated walkthrough of : I point, click, and talk through my intent and the outcomes I want. 2. Feed that recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured requirements checklist: - acceptance criteria - the user flow (step by step) - the specific clicks / typing / layout changes shown - responsive behavior - edge cases 3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) I can hand to a coding agent. Framing: the durable assets are the natural-language contract + the resulting diff — NOT the generated code. Don't over-specify HOW to verify; give clear outcomes and keep my QA judgment in the loop. Guardrail: strip sensitive data first — video can expose more than you expect (open tabs, tokens, notifications, file paths). ``` ### How it works - Record a short narrated walkthrough — point, click, and talk through intent and desired outcomes — which is often faster than writing a perfect spec. - Feed it to a multimodal model (Gemini, per the workshop) and extract acceptance criteria, the user flow, the clicks/typing/layout changes, responsive behavior, and edge cases. - The output is a repeatable, agent-ready requirements checklist (a QA story). - Under the throwaway-artifact mindset, the durable asset is the natural-language contract + the diff, not the generated code; don't over-specify how to verify — give clear outcomes and keep your QA judgment in the loop. - Caution: strip sensitive data before uploading; video can expose more than you expect. - Reference: [AGENTS.md](https://developers.openai.com/codex/guides/agents-md), [OpenAI Codex](https://github.com/openai/codex). ## Reusable skill Install as `~/.agents/skills/video-as-requirements/SKILL.md`, then restart Codex. ```markdown --- name: video-as-requirements description: Trigger when a narrated screen recording captures intent better than a written spec — feed the video to a multimodal model to extract acceptance criteria, the user flow, and edge cases as an agent-ready requirements checklist. Do NOT upload videos containing sensitive data. --- # Video as requirements Turn a narrated screen recording into agent-ready requirements. When showing-and-narrating beats writing a perfect spec, record the app in use and let a multimodal model extract the contract. ## Steps 1. Record a short narrated walkthrough of the app: point, click, and talk through intent and desired outcomes. 2. Feed the recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured checklist: - acceptance criteria - the user flow (step by step) - the specific clicks / typing / layout changes shown - responsive behavior - edge cases 3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) to hand to a coding agent. ## Framing - The durable assets are the natural-language contract + the resulting diff — NOT the generated code. - Don't over-specify HOW to verify; give clear outcomes and keep human QA judgment in the loop. ## Guardrails - STRIP sensitive data before uploading — video can expose more than you expect (open tabs, tokens, notifications, file paths). Do NOT upload videos containing sensitive data. ``` ## Scenarios ### Convert a narrated checkout bug into a fixable QA story **Role:** As a frontend engineer maintaining a Next.js commerce app A product manager records a two-minute walkthrough on localhost showing a cart drawer, promo-code input, shipping estimate panel, and checkout button. They narrate that the drawer jumps on mobile, the promo error disappears too fast, and the checkout button should stay disabled until shipping is selected. > As a mobile shopper, I want the cart drawer, promo-code error, shipping estimate, and checkout enabled state to behave predictably, so that I can recover from mistakes and complete checkout without guessing what changed. #### Agent brief ```text You are implementing from a narrated video requirements artifact. First inspect the current app source and existing tests; do not trust stale notes. Use the video-derived QA story as the natural-language contract. Create or update `.goals/cart-video-requirements.md` with: user flow, acceptance criteria, responsive behavior, edge cases, and what evidence will prove the fix. Then implement only the behavior described: stable mobile drawer layout, persistent promo-code error state until corrected or dismissed, shipping selection as the gate for enabling checkout, and no unrelated redesign. Run the project’s normal lint/test/build commands discovered from package scripts. Start the local dev server and verify the flow in a browser. Produce a final review artifact containing the git diff summary, commands run, browser proof, and any remaining risks. ``` #### Implementation references [Open reference](/topics/foundations-video-requirements-playbook/) [Open reference](/topics/foundations-video-requirements-playbook/) [Open reference](/topics/foundations-contracts-state-machines-and-code/) [Open reference](/topics/foundations-contracts-state-machines-and-code/) [Open reference](/topics/foundations-video-requirements-playbook/) ```text package.json scripts: test, lint, build, dev ``` ```text git diff ``` #### Browser verification Use a local browser or CMUX browser pane against the dev server. Capture an accessibility snapshot of the cart drawer, click the cart trigger, fill the promo-code field with an invalid code, click apply, resize or emulate mobile width, select shipping, and evaluate whether the checkout button disabled/enabled state matches the video-derived contract. Save a screenshot or concise browser log as proof. #### Definition of done - A checked-in or local review artifact that restates the video-derived QA story and acceptance criteria - Passing lint/test/build output from the repo’s own scripts - Browser proof showing invalid promo behavior, mobile drawer stability, shipping selection, and checkout button state - A git diff review summary focused on the changed modules and any tests added or updated #### Failure modes and mitigations - The agent treats the video as a brittle click recorder and hard-codes selectors or exact timing; mitigate by extracting intent, user actions, expected behavior, responsive behavior, and edge cases before coding. - The agent redesigns the cart instead of fixing the contract; mitigate by requiring source inspection first and limiting changes to behavior described by the narrated walkthrough. ### Turn a dashboard walkthrough into responsive UI requirements **Role:** As a full-stack web developer owning a SaaS analytics dashboard A customer success lead records a narrated walkthrough of a dashboard where they filter by date range, expand a table row, collapse search results on narrow screens, and point out that the summary cards reorder badly on tablet widths. > As an account manager reviewing customer metrics, I want filters, expandable rows, collapsed search results, and responsive summary cards to preserve context across screen sizes, so that I can investigate an account without losing my place. #### Agent brief ```text Use the narrated walkthrough as requirements, not as a polished spec. Extract a QA story with the exact user flow, expected visual/layout behavior, responsive breakpoints observed in the video, and edge cases. Inspect the current dashboard code, routing, state ownership, and any existing browser tests. Implement the smallest change that preserves filter state, keeps expanded row context stable, makes search results collapse predictably on narrow screens, and improves tablet card ordering without changing unrelated dashboard styling. Run the repo’s normal verification commands. Then run the dashboard in a browser and prove the flow works at desktop, tablet, and mobile widths. Final output must include the diff summary plus browser evidence, not a generic success claim. ``` #### Implementation references [Open reference](/topics/foundations-video-requirements-playbook/) [Open reference](/topics/foundations-video-requirements-playbook/) [Open reference](/topics/foundations-contracts-state-machines-and-code/) [Open reference](/topics/foundations-contracts-state-machines-and-code/) [Open reference](/topics/foundations-video-requirements-playbook/) ```text AGENTS.md or agents.md if present ``` ```text package.json scripts ``` ```text git diff ``` #### Browser verification Use Playwright if the repo already has it, otherwise use a local browser or agent-browser-style workflow: snapshot the dashboard, click the date filter, fill or select the target range, expand a row, resize to tablet and mobile, and evaluate whether the visible labels, expanded state, and collapsed search results match the QA story. Do not add a new browser framework just for this scenario unless the repo already uses one. #### Definition of done - A video-derived QA story with user actions, expected behavior, responsive behavior, and edge cases - Passing project verification commands - Browser proof at desktop, tablet, and mobile widths - A diff-driven review note explaining which state/module boundaries changed and why #### Failure modes and mitigations - The agent over-specifies verification mechanics instead of outcomes; mitigate by keeping acceptance criteria outcome-based and using browser proof only as evidence. - The agent ignores current code structure and adds duplicate dashboard state; mitigate by requiring source-of-truth code inspection and preserving existing module/state boundaries where practical. ### Use a video bug report to update guardrails after the fix **Role:** As a tech lead supervising agent-assisted feature work A teammate records a narrated video of a localhost onboarding flow where invite acceptance, workspace creation, and the empty-state screen drift from the intended product contract. Previous agents have fixed similar flows but keep missing the same auth and empty-state constraints. > As a team admin accepting an invite, I want the onboarding flow to preserve auth context, create or join the right workspace, and show the correct empty state, so that first-run setup feels trustworthy. #### Agent brief ```text Treat the video as evidence for a natural-language contract. Extract the intended onboarding states and transitions from the narration: invite opened, auth checked, workspace joined or created, empty state shown, and error or retry states if present. Inspect the current code and identify the modules that own auth, workspace creation, routing, and empty-state rendering. Implement the smallest fix that satisfies the contract. After verification, review the git diff as the primary artifact. Then update `agents.md` or `AGENTS.md` only if the mistake reveals a reusable project-specific guardrail, such as where onboarding state must live or which module owns invite acceptance. Keep the guardrail short and grounded in this actual mistake. ``` #### Implementation references [Open reference](/topics/foundations-contracts-state-machines-and-code/) [Open reference](/topics/foundations-contracts-state-machines-and-code/) [Open reference](/topics/foundations-video-requirements-playbook/) [Open reference](/topics/foundations-video-requirements-playbook/) ```text AGENTS.md or agents.md if present ``` ```text git diff ``` ```text package.json scripts ``` #### Browser verification Browser proof is useful because onboarding is flow/state behavior. In a local browser, follow the invite URL or mocked invite route, complete the auth path using safe local test credentials or seeded state, click through workspace creation or join, and capture the final empty-state screen. If authenticated browser state is required, use a live browser/CMUX browser pane carefully and do not expose real tokens, QR codes, customer data, or private notifications. #### Definition of done - A compact onboarding state contract extracted from the video - Passing verification commands and a browser receipt of the invite-to-empty-state flow - A git diff summary suitable for fresh-session critique - A minimal guardrail update only if it captures a real repeated project constraint #### Failure modes and mitigations - The agent dumps a broad rulebook into AGENTS.md; mitigate by allowing only short, project-specific guardrails learned from this actual video-backed failure. - The agent uses real authenticated data casually during browser verification; mitigate by using local seeded data or sanitized test accounts and stripping sensitive information from videos and logs. ## Implementation notes - Start by extracting a natural-language contract from the video before editing code. The contract should describe outcomes, user flow, responsive behavior, and edge cases; it should not become a brittle macro recording. - Inspect the live source before implementation. The course material is explicit that code is the source of truth when implementation details matter. - For web app work, browser proof matters when the requirement is visual, interactive, responsive, authenticated, or stateful. Use a local browser, CMUX browser pane, existing Playwright setup, or agent-browser-style snapshot/click/fill/evaluate workflow depending on what the repo already supports. - Keep generated code disposable but preserve durable assets: the video-derived contract, module/state boundaries, tests or verification artifacts, browser receipts, and the reviewed diff. - Strip sensitive data before uploading video. Screen recordings can leak tabs, tokens, paths, notifications, local QR codes, customer data, and auth state. - Do not add new permanent QA infrastructure for unstable UI unless the project already has that direction. A short QA story plus browser receipt can be enough for fast-moving product work. - Use `agents.md` or `AGENTS.md` as a living guardrail only when a real repeated mistake or project constraint emerges. Keep it small. ## Boundaries and caveats - Do not present NotebookLM, Codex approvals/security, or Codex Skills documentation as taught workflows for this topic beyond the existing local skill artifact. - Do not require Agent Browser or Playwright as mandatory tools for every scenario; use them only when browser proof fits and the repo or workflow already supports them. - Do not treat video as a selector-level macro recorder. Extract intent and behavior, then verify outcomes. - Do not over-specify exact verification internals when a clear outcome plus browser evidence is enough. - Do not casually use authenticated browsers, local QR codes, secrets, customer data, or broad permissions in video capture or browser validation. - Do not let AGENTS.md become a giant upfront rulebook. Update it from real mistakes and constraints only. ## Agent reference map ### Video as requirements prompt Use this as the user-facing extraction prompt: record a narrated walkthrough, extract acceptance criteria, user flow, clicks/typing/layout changes, responsive behavior, and edge cases. [Open reference](/topics/foundations-video-requirements-playbook/) ### Video as requirements Codex skill Use this when packaging the workflow as a reusable local agent skill with guardrails around sensitive video data. [Open reference](/topics/foundations-video-requirements-playbook/) ### Lesson 11 validated references Treat this as ground truth for taught concepts: natural-language contracts, video-as-requirements, diff-driven review, modular/state-machine boundaries, living guardrails, and disposable generated code. [Open reference](/topics/foundations-contracts-state-machines-and-code/) ### Lesson 11 validation notes Use this to avoid reintroducing tools and claims that were mentioned but not taught as workflows in the final lesson. [Open reference](/topics/foundations-contracts-state-machines-and-code/) ### Lesson 05 browser QA context Use this only for the supporting browser-work angle: perspective-based QA, weird-path exploration, browser-driving agents, CMUX state, and video-driven intent extraction. [Open reference](/topics/foundations-five-monkeys-playbook/) ### CMUX CLI surface Use when the agent needs a visible local pane or browser-oriented workspace receipt; inspect state before acting and avoid inventing flags. [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ### Local verification commands Discover and run the repo’s actual scripts instead of inventing a test command. ```text cat package.json ``` ### Diff-driven review Use the final git diff as the primary review artifact, then hand goal plus diff to a fresh session for critique when the change is risky. ```text git diff ``` Reference ID: foundations-video-requirements-playbook Topic: Principles Sources: - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Which principles survive better agents? Separate enduring human judgment from workarounds for tools that have changed. ## Related working material - [Which principles survive better agents? — prompts and exercises](/topics/factory-evolving-principles-practice/) - [Which principles survive better agents? — questions and tradeoffs](/topics/factory-evolving-principles-questions/) - [Which principles survive better agents? — worked example](/topics/factory-evolving-principles-worked-example/) ## TL;DR - A one-month audit of the Field Guide's 14 "Prime Directives" — every verdict backed by dated evidence an agent dug out of the author's own machine: chat history, prototype directories, session archives. - You walk away with a paste-ready prompt that runs the same 14-point audit against *your* machine and produces the same scorecard. - The one move: sort every workflow habit into **human judgment** (keep it, harden it) or **tool workaround** (check whether the weakness still exists — several no longer do). Have your agent run the audit — paste this into it: ``` text Fetch https://hallowed-entry-96xv.here.now/agent.md?raw and follow it to run the 14-directive self-audit against my machine. Run the success check at the end and show me the finished scorecard. ``` ## The scorecard: 14 laws, one month later Each row: the directive's law line quoted from the guide, what one month of receipts showed, and the verdict. Read it as a sort, not a grade: which *kind* of law lands in which column? | \# | Old law (quoted) | What the receipts showed | Verdict | |----|----|----|----| | 01 | "If the agent can't see it, it doesn't exist." | Agents find their own context now; curation moved into their retrieval loop | Held — mechanism moved | | 02 | "Research is loud. Contracts are quiet." | Agents recover from thin plans; alignment is the real variable | Held — sharpened | | 03 | "If you can pipe it, you can reuse it." | Most piping compensated for bad compaction; compaction got good | Partly inverted | | 04 | "Commit before autonomy." | Directory names and published sites became the version control for prototypes | Outgrew tooling | | 05 | "Done is a claim. Green is a fact." | "Done" now includes leaving the repo easy for the next agent to probe | Hardened | | 06 | "The agent can't read your mind — only your artifacts." | Dictation became the intent firehose; structuring it is the gap | Held | | 07 | "Expose the decision space. Keep the decision." | Alternatives now arrive as generated images, not just prose | Held — went visual | | 08 | "Bet small. Learn fast. Revert free." | 1,026 discarded prototypes compounded into a searchable idea library | Held — compounds | | 09 | "Reuse follows value — never precedes it." | Four competing capture tools on one machine; instruction files may rot into anti-patterns | Outgrew tooling | | 10 | "No single switch makes autonomy safe." | Unsupervised runs are routine: backups plus secrets fenced behind the `op` CLI | Held — layers thinned | | 11 | "You can launch more agents than you can review." | Attention *and budget* are now the absolute bottleneck | Hardened | | 12 | "Boring code is a superpower." | Models explore new tools so well that pushing boundaries is now necessary | Partly inverted | | 13 | "A gate beats a plea." | Agents now write their own gates and permission config | Held — authorship moved | | 14 | "The code is disposable. The contract is not." | Taste is the defining factor when anyone can build anything | Hardened | The sort is the finding: the laws that **hardened** (05, 11, 14) encode human judgment. The laws that **eroded** (03, 12, half of 01) were compensating for earlier tool weaknesses. Some "durable laws" were tool-shaped all along. ## What the guide promised wouldn't rot [The Field Guide](https://kindly-mirage-ejqd.here.now/) distilled fifteen months of workshops (the recorded workflow → the recorded workflow, across Cursor, Claude Code, and Codex) into fourteen Prime Directives and one rule above the rules: "An agent saying 'done' is not evidence." It called the directives "the layer that doesn't rot." This page audits that claim one month later, by the guide's own standard — saved, inspectable evidence instead of confident narration. The method is itself the first verdict. An agent searched the author's full conversation history through a local full-text index (`cs`, covering every past Claude, Codex, and Grok session), scanned 1,026 prototype directories, and counted 1,978 archived agent sessions — all in the observed snapshot. Directive 01 said "if the agent can't see it, it doesn't exist," and made hand-curation the human's edge. The audit was performed by an agent finding its own evidence. The law's wording survives; the human's role in it didn't. Curation flipped from "feed the agent" to "make everything findable." ### Piping was a compaction workaround Directive 03 turned agents into Unix processes: print mode, JSON streams, one bounded agent per pipeline stage. The receipts say most of that rigging existed to keep contexts small because compaction was bad. the recorded workflow session logs across four projects show compaction firing mid-task under a standing "continue where you left off" directive — long multi-day sessions just keep going, and nobody thinks about it. The elaborate pipe-per-stage rigs appear in earlier history and rarely since. Piping retreated to where it's genuine composition: CI stages and scripts. The test to carry forward: when a habit's justification names a tool weakness ("context windows are small"), re-check whether the weakness still exists before renewing the habit. ### Git lost the short-lived majority Directive 04 — "commit before autonomy" — made Git the recovery system and external memory. The principle held; the tool fell behind the volume. The prototype folder contains sibling directories named `acorn-mcp`, `acorn-mcp-final`, `acorn-mcp-super-final`: directory-name versioning, because per-repo Git ceremony can't keep up with prototype velocity. Many current demos are deliberately not Git repos at all; published sites act as the durable record. Cursor and others are building Git replacements for exactly this gap — approving code nobody reads, and exploring memories of what worked. Meanwhile the old discipline survives where it belongs: an the recorded workflow session runs a dedicated checkpoint agent whose only job is reviewing and committing each iteration in long-lived repos. Directive 09 (the reuse ladder) hit the same wall from the other side. There's still no good tool for capturing success — the evidence log shows four competing capture mechanisms in active use on one machine within a single month: a friction-log skill, a workflow productizer, the conversation index, and per-agent memory directories. Four tools for one job means no tool has won. Worse, CLAUDE.md/AGENTS.md instruction files may be rotting into anti-patterns: stale rules that stop agents from making fixes or taking better directions. Audit your instruction files the way you audit dependencies. ### The one law that inverted: boring code Directive 12 said "boring code is a superpower" — familiar structures, mature CLIs, no novel protocols. Models got so much better at exploring new ideas and new tools that the advice partly flipped: pushing boundaries is now *necessary* to stand out, because everyone can ship the boring thing. The log includes a the recorded workflow project literally named `pushing-boundaries`, and recent sessions casually drive desktop-app automation, GPU UI frameworks, and multi-account model councils — stacks the old law would have flagged as risk. The inversion is scoped: boring still wins inside the implementation. The boundary-pushing lives in what you attempt, not how the code is structured. ### The laws that hardened are the judgment ones Three directives got stronger, and they're all about human judgment. Directive 05 ("done is a claim, green is a fact") extended past the diff — done now means leaving the codebase where the next agent can iterate, probe, and test; a the recorded workflow publish review states the mature position in seven words: "evidence is a floor, not a substitute for taste." Directive 11 was promoted from lesson to law of nature: a the recorded workflow retrospective quantifies the practical limit at one to two guided tracks even with manager-agent tooling, and token budgets are now first-class workflow parameters. You can build anything — so the binding question is what you will build. Directive 14 is the audit's clearest winner. "The machines propose; you choose" — the guide called it where the other thirteen point. One month later the log converges on that sentence from three independent directions: a video project titled "taste-is-the-job," a workshop retrospective whose story spine reads "it turned out to be about taste, constraints, and verification," and the publish review above. When anyone can build anything, selection is the only scarce skill. The last law absorbed the other thirteen, exactly as the guide predicted. ## Appendix ### Limits & caveats - Every verdict rests on one practitioner's machine over roughly one month — a sample of one, gathered by an agent with access to that machine only. The verdicts support the sorting method, not an industry-wide ranking. - The claim that instruction files actively harm agents is the workshop's position, not a measured result. The evidence documents tool proliferation; there is no controlled comparison of sessions with and without instruction files. - Piping did not die — it survives where it is genuine composition. The evidence can't say how much piping remains in other practitioners' setups. - Agent-authored gates inherit the old guide's requirement unchanged: teeth and exits, reviewed by a human. The log shows agents writing config; it does not show that unreviewed agent-written gates are safe. - `cs` and `~/.oracle/sessions` are personal tooling on the author's machine. The audit works with any searchable history — agent.md includes grep fallbacks over raw session archives. - Verdicts and the tool-shaped/judgment-shaped sort are editorial inference from the evidence, and are marked as such. ## The working positions behind the principles John’s position is deliberately provisional about tools and strong about judgment: 1. Agents are much better at finding relevant context; make evidence findable rather than assuming the human must hand-feed everything. 2. Planning is both more important and less important. Alignment is the key variable; before/after checks, possibly by another agent with evals, matter more than plan ceremony. 3. Piping often compensated for poor compaction. Recheck whether that weakness still exists before rebuilding a pipe-per-stage workflow. 4. Git can be insufficient for very high prototype volume. The missing tool manages approval, recoverability, and exploration of ideas—not merely a different commit interface. Publishing can preserve an artifact, but does not replace production safety. 5. Done includes alignment and leaving the codebase easy for the next agent to iterate on, probe, and test. 6. Dictation can carry an extensive brain dump while walking or otherwise away from a keyboard. Better real-time mind-mapping from human input remains a desirable missing tool. 7. Generated images make the decision space easier and more important to expose. 8. More prototypes create a deeper searchable well of ideas and examples, including discarded work. 9. There is no perfect success-capture tool. Instruction files, comments, and documents may become stale constraints that prevent better fixes. The code is the artifact and the implementation documentation; this is a challenge to audit context, not proof that all prose is harmful. 10. John argues that agents have become much safer for unsupervised work, with backups and secrets fenced through a manager such as the 1Password CLI. This is a practitioner’s position, not a measured guarantee or a reason to remove consequential-action gates. 11. Attention and budget are the bottleneck: the ability to build anything makes choosing what to build harder, not less important. 12. Models can explore unfamiliar tools and ambitious ideas. Push boundaries in what is attempted while keeping implementation structures maintainable. 13. Hooks still provide control, and agents can help customize their own environment. Human review of the resulting gate and its exits remains necessary. 14. Taste distinguishes the product when implementation becomes widely available. Reference ID: factory-evolving-principles Topic: Principles Sources: - [Which principles survive better agents?](https://hallowed-entry-96xv.here.now/) - [Software factory agenda](https://ember-bodhi-scrr.here.now/agent.md) --- # Which principles survive better agents? — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Own your tools The philosophy of heavily customizing development utilities and environments to match individual engineer optimization criteria. ### Repository Context Referencing Bundling complete repository structure and codebases into an LLM context window to provide ground-truth documentation for agent logic loops. ### AI Context Bundlers Methods or tools to aggregate repository references and internal interfaces to supply exhaustive context to AI agents, eliminating random generation guesses. ### Artifacts Stand-alone code documents or hosted assets generated directly by AI systems, similar to the Claude Code feature, which John replicates via a custom site-dropping CLI. ### Open-Weight Models Machine learning models whose neural network weights are publicly shared, empowering custom user training and local optimization workflows at a minimal price point. ### Kimi K3 Model A state-of-the-art Chinese open-weight model from Kimi/Moonshot AI that undercuts market pricing while rivaling top frontier models in engineering benchmarks. ### Token Efficiency Achieving complex automation tasks with minimized context usage and fewer conversational iterations. ### Context Management and Compaction The historical necessity of manually compressing or curating codebase elements to fit context limits, which has become automated or largely obsolete due to modern agentic capabilities. ### Tool Calling Maturity The transformation of LLM tool invocation from unreliable behaviors to an incredibly stable engine that users confidently expect to work every time. ### Adaptive Planning vs. Upfront Planning A shift away from pre-planned checkbox steps in favor of diving directly into code alterations, evaluating what works, and pulling back cleanly via source control. ### Chained Specialized Agents An architectural approach of piping outputs through a sequential chain of specialized custom sub-agents, now being outpaced by efficient monolithic models. ### Single-Model Token Efficiency The operational reality where letting a highly advanced model solve an execution path directly uses far fewer iterative calls than a sprawling cluster of sub-agents. ### Agentic Forge Architectures Code storage infrastructures designed around autonomous developer tools rather than solely optimizing for human commit messages and version branching histories. ### Git Limitations in Agentic Work Standard source control branching paradigms create operational overhead and clunky code sync loops when orchestrated heavily by parallel automated agents. ### Vision Alignment Instructing agents based on overarching user design intent and macro-level target states rather than managing explicit, granular steps. ### Automated Guardrails Relying on backend automation tools like tests, style lints, and post-execution hooks to lock down system boundaries instead of rigid upfront requirements blueprints. ### Agentic Lifecycle Hooks Alternative execution boundaries (e.g. stop hooks and session end hooks) configured to cleanly freeze or evaluate agent iterations. ### Exhaustive Dictation / Brain Dumping Providing dense context and detailed parameters to an agent up-front to prevent it from hallucinating or incorrectly guessing user intent. ### Artifact-Driven Prompting Leveraging existing functional single-file web pages or code prototypes as explicit architectural examples for an agent to inspect and duplicate specific behaviors. ### Code Artifact Repository / Visual Reference Grid Saving small, single-file working examples of complex features so an AI agent can read from them directly rather than inferring patterns from scratch. ### Task Clustering and Summarization Grouping sub-tasks or sub-agents together and postponing summarization until the completion of the core work to avoid distracting the model's inference cycles. ### Sub-agents / Teams Dividing a high-level task into components managed by separate agent groups working together, exemplified by teams in Claude Code. ### Searchable Memory Layer / Continuous Screen Recording Background software tools that track screen history, text, and active context to allow agents to search past activities. ### Human-in-the-loop (HITL) Designated checkpoints where automated workflows wait for manual human verification and decision-making before resuming. ### Unsafe/Auto Mode Allowing agentic tools or LLM code generation applications to execute actions and file operations without mandatory human approval checkpoints. ### Seoul Model Reference to an LLM model version used in code generation tools like Codex. ### Proliferation Focus Tracks A personal strategy used by the presenter to bucket autonomous agent tasks into three distinct lanes: fun, profitable, and personal utility. ### Boring Code Frameworks The design practice of sticking closely to mainstream defaults and popular frameworks (e.g., Next.js) so that code models perform highly due to high densities of training data availability. ### Durable Laws vs. Tool Compensations The division between fundamental system logic configurations that represent developer intent, versus temporary codebase rules written to bypass limits in current AI capabilities. ### Disposable Code vs. Taste The principle that code syntax generation is cheap and automated, leaving an engineer's artistic taste, architectural criteria, and platform uniqueness as the primary values. ### Flow Text A library designed to enable CSS HTML wrap-around text flows mapping precisely to alpha transparency edges of an image component. ### Image Factory Workflow A technique utilizing multi-modal agent capabilities to capture existing web templates via visual inputs and autonomously generate style iterations or layout options. ### YOLO Mode An execution permission status within the Codex terminal interface allowing project-level local configurations and scripts to launch automatically without explicit multi-step interactive prompts. ## Questions and answer status ### Do you think we’ll get another week of Fable given this news? **Status: answered.** John states he hopes so because Fable uniquely interprets and handles his layout and UX engineering tasks cleanly. ### Re: models better at finding code, how much is better grep-ing, and how much is agents now using LSPs, etc? **Status: deferred.** The question is left deferred during this specific segment as the presenter is explaining the historical piping model. ### Is it worth paying for premium models like Fable 5 when small alignment variances risk wasting valuable tokens? **Status: answered.** Yes, because their extreme turn-efficiency allows them to close tasks in far fewer cycles (e.g. 2 calls vs 15 calls), ultimately using fewer raw resources despite higher per-token prices. ### How would Claude or Codex define 'cluster of batched tasks' followed by summaries awaiting approval, and is that methodology still useful? **Status: deferred.** The question is not addressed by the presenter within the time boundaries of this shard. ### Would you recommend collecting external pages, then recreating that on here.now as my own example that will never change, then? **Status: answered.** Yes, John fully recommends saving references, bookmarks, screenshots, or dictations of inspiring items to build an unalterable personal source collection. ### I often use the term cluster of batch tasks, then at the end of each cluster, report back the summary. Yeah. How would Claude or Codex define that? Is that a useful methodology? **Status: answered.** John defines a cluster as a group of sub-agents. He mentions Claude Code has built-in summaries, but recommends waiting until a task is completely finished before summarizing to keep the inference clear of unnecessary instruction load. ### What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster? **Status: partial.** John answers that this design pattern is commonly referred to as 'human in the loop' (HITL), with further details extending into the following segment. ### What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster? **Status: answered.** The presenter states that 'human in the loop' is the industry term that perfectly describes these checkpoint decisions. ## Exercises ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [00:14:49](https://proud-anchor-53zn.here.now/watch.html?t=889#recording-player) — Walkthrough of terminal coding agent options and alternatives. - [00:15:14](https://proud-anchor-53zn.here.now/watch.html?t=914#recording-player) — Presentation of workspace multiplexer tools like Herd and Zellij. - [00:15:37](https://proud-anchor-53zn.here.now/watch.html?t=937#recording-player) — Evaluation of repo-to-prompt context packaging utilities. - [00:15:53](https://proud-anchor-53zn.here.now/watch.html?t=953#recording-player) — John Lindquist explains that with proper context, it becomes trivial for an AI to customize code for individual needs. - [00:19:03](https://proud-anchor-53zn.here.now/watch.html?t=1143#recording-player) — John describes the new Kimi K3 model released yesterday, noting its benchmarks against Fable 5 and OpenAI's GPT 5.6 models. - [00:20:28](https://proud-anchor-53zn.here.now/watch.html?t=1228#recording-player) — John Lindquist states Fable is his favorite model to talk to because it aligns cleanly with UX and UI design intentions. - [00:23:33](https://proud-anchor-53zn.here.now/watch.html?t=1413#recording-player) — John Lindquist explains that developers previously spent significant effort managing conversation context windows and compaction. - [00:24:03](https://proud-anchor-53zn.here.now/watch.html?t=1443#recording-player) — John Lindquist discusses the major improvements in tool calling and file change stability, stating that reliability is now an industry baseline expectation. - [00:24:24](https://proud-anchor-53zn.here.now/watch.html?t=1464#recording-player) — John Lindquist reports that automated context gathering within the codebase by modern agents has improved vastly. - [00:24:40](https://proud-anchor-53zn.here.now/watch.html?t=1480#recording-player) — John Lindquist mentions state-of-the-art models including Fables, GPT-5.6, and Kimi 3s, noting they rarely miss necessary files or related refactorings. - [00:25:35](https://proud-anchor-53zn.here.now/watch.html?t=1535#recording-player) — John Lindquist shifts to discussing planning laws, explaining that he no longer advocates for rigid upfront checkboxes and extensive step-by-step planning documents. - [00:25:35](https://proud-anchor-53zn.here.now/watch.html?t=1535#recording-player) — The presenter highlights text within row 02 ('Research is loud. Contracts are quiet.') on the scorecard table. - [00:26:55](https://proud-anchor-53zn.here.now/watch.html?t=1615#recording-player) — The presenter selects text in row 03 ('If you can pipe it, you can reuse it.') to discuss agent pipelining. - [00:26:55](https://proud-anchor-53zn.here.now/watch.html?t=1615#recording-player) — John Lindquist describes older architectures where specialized, custom agents were chained together to pipe inputs and outputs sequentially. - [00:27:13](https://proud-anchor-53zn.here.now/watch.html?t=1633#recording-player) — John Lindquist states that chained specialized agent workflows face significant architectural challenges following the release of Fable 5. - [00:27:22](https://proud-anchor-53zn.here.now/watch.html?t=1642#recording-player) — John Lindquist introduces the theme of token efficiency driven by advanced AI models. - [00:28:32](https://proud-anchor-53zn.here.now/watch.html?t=1712#recording-player) — John evaluates the cost trade-offs of premium models like Fable 5 when misalignments occur. - [00:29:19](https://proud-anchor-53zn.here.now/watch.html?t=1759#recording-player) — John notes that Git is entering a transitional phase because code updates occur too fast for traditional tracking formats. - [00:30:15](https://proud-anchor-53zn.here.now/watch.html?t=1815#recording-player) — The browser loads the landing page for Cursor Origin showing the headline 'A git forge for the agentic era'. - [00:31:12](https://proud-anchor-53zn.here.now/watch.html?t=1872#recording-player) — Chrome browser window is focused on hallowed-entry-96xy.now.sh/index.html showing row 04 'Commit before autonomy.' highlighted in blue. - [00:31:12](https://proud-anchor-53zn.here.now/watch.html?t=1872#recording-player) — John Lindquist describes how modern agent setups are rapidly outgrowing what Git provides. - [00:31:34](https://proud-anchor-53zn.here.now/watch.html?t=1894#recording-player) — John points out how parallel branches and work trees complicate standard code merges for autonomous agents. - [00:32:11](https://proud-anchor-53zn.here.now/watch.html?t=1931#recording-player) — John references the phrase 'Done is a claim. Green is a fact.', discussing how comprehensive commit hooks, lints, and tests create functional guardrails. - [00:32:42](https://proud-anchor-53zn.here.now/watch.html?t=1962#recording-player) — John highlights the transition from traditional planning documents (PRDs) to strategic vision alignment. - [00:33:33](https://proud-anchor-53zn.here.now/watch.html?t=2013#recording-player) — The UI selection shifts downward to highlight row 05 'Done is a claim. Green is a fact.' - [00:33:53](https://proud-anchor-53zn.here.now/watch.html?t=2033#recording-player) — John describes how agentic lifecycles introduce stop hooks or session end hooks that mismatch with standard git execution flows. - [00:34:42](https://proud-anchor-53zn.here.now/watch.html?t=2082#recording-player) — The text selection moves down to highlight row 06 'The agent can't read your mind — only your artifacts.' - [00:34:52](https://proud-anchor-53zn.here.now/watch.html?t=2092#recording-player) — John underscores dictation and brain dumping context as highly effective mechanisms for interfacing with agents. - [00:35:01](https://proud-anchor-53zn.here.now/watch.html?t=2101#recording-player) — John highlights rule number 06: 'The agent can't read your mind - only your artifacts.' - [00:35:06](https://proud-anchor-53zn.here.now/watch.html?t=2106#recording-player) — John discusses the widespread mistake of providing short text prompts and expecting perfect agent execution. - [00:35:18](https://proud-anchor-53zn.here.now/watch.html?t=2118#recording-player) — John shares an anecdote regarding an AI face modification that incorrectly guessed eye features hidden by sunglasses. - [00:36:44](https://proud-anchor-53zn.here.now/watch.html?t=2204#recording-player) — John moves his cursor over rule 07: 'Expose the decision space. Keep the decision.' - [00:37:00](https://proud-anchor-53zn.here.now/watch.html?t=2220#recording-player) — John hovers over rule 08: 'Bet small. Learn fast. Revert free.' - [00:37:31](https://proud-anchor-53zn.here.now/watch.html?t=2251#recording-player) — The browser opens the 'FRONTIER/26' single-page field guide generated by Kimi. - [00:37:49](https://proud-anchor-53zn.here.now/watch.html?t=2269#recording-player) — John scrolls down to reveal an interactive mouse-responsive shader canvas element. - [00:38:09](https://proud-anchor-53zn.here.now/watch.html?t=2289#recording-player) — John scrolls through OKLCH color schemes and a scrollbar timeline chapter. - [00:38:34](https://proud-anchor-53zn.here.now/watch.html?t=2314#recording-player) — John tests variable fonts by moving a cursor over scroll/timeline components on the page. - [00:38:50](https://proud-anchor-53zn.here.now/watch.html?t=2330#recording-player) — Browser displays jival-kayak-fyna.here.now titled 'FRONTIER/24' showing Chapter 04 variable font capabilities. - [00:38:50](https://proud-anchor-53zn.here.now/watch.html?t=2330#recording-player) — John Lindquist notes that the example is a single HTML file containing bundled JavaScript and CSS. - [00:39:06](https://proud-anchor-53zn.here.now/watch.html?t=2346#recording-player) — Presenter scrolls down the page to show various interactive CSS features (view transitions, container queries, feature audit grid). - [00:42:14](https://proud-anchor-53zn.here.now/watch.html?t=2534#recording-player) — John details his recommendation to capture inspiring pages via screenshots, bookmarks, notes, or dictations. - [00:42:42](https://proud-anchor-53zn.here.now/watch.html?t=2562#recording-player) — John Lindquist describes using daily experiences like flowers or a sunrise to gather context and inspiration for product development. - [00:43:54](https://proud-anchor-53zn.here.now/watch.html?t=2634#recording-player) — John defines a cluster of batch tasks as a group of sub-agents, noting Anthropic or Claude Code calls it a team. - [00:44:48](https://proud-anchor-53zn.here.now/watch.html?t=2688#recording-player) — John introduces ScreenPipe as a tool that records the screen and captures intelligent notes. - [00:45:30](https://proud-anchor-53zn.here.now/watch.html?t=2730#recording-player) — John introduces Pieces app as another tool he has used for background history tracking. - [00:46:26](https://proud-anchor-53zn.here.now/watch.html?t=2786#recording-player) — John answers that the industry term for these breakpoints is human in the loop. - [00:46:33](https://proud-anchor-53zn.here.now/watch.html?t=2793#recording-player) — John Lindquist explains that 'human in the loop' is the standard term for checkpoints where human approval is required. - [00:46:44](https://proud-anchor-53zn.here.now/watch.html?t=2804#recording-player) — John Lindquist highlights row 09: 'Reuse follows value - never precedes it.' - [00:47:19](https://proud-anchor-53zn.here.now/watch.html?t=2839#recording-player) — John mentions letting tools run in unsafe modes, noting auto mode features in Cloud Code, Codex, and Pi. - [00:47:38](https://proud-anchor-53zn.here.now/watch.html?t=2858#recording-player) — John relates an anecdote where Codex using the Seoul model attempted to delete a user home directory because of tilde expansion errors. - [00:48:38](https://proud-anchor-53zn.here.now/watch.html?t=2918#recording-player) — John highlights text in row 11: 'Attention and budget are now the absolute bottleneck'. - [00:49:13](https://proud-anchor-53zn.here.now/watch.html?t=2953#recording-player) — John proposes organizing agent tasks into three lanes: one fun thing, one profitable thing, and one thing that improves personal or family life. - [00:50:09](https://proud-anchor-53zn.here.now/watch.html?t=3009#recording-player) — John highlights row 12: 'Boring code is a superpower.' - [00:50:18](https://proud-anchor-53zn.here.now/watch.html?t=3018#recording-player) — John describes how AI models are highly optimized for common framework structures like Next.js. - [00:54:07](https://proud-anchor-53zn.here.now/watch.html?t=3247#recording-player) — The browser loads github.com/johnlindquist/flow-text showing documentation for transparent image text-wrapping. - [00:54:18](https://proud-anchor-53zn.here.now/watch.html?t=3258#recording-player) — John switches browser tabs to kindly-mirage-wjpt.here.now/directives.html to show text wrapping around transparent images. - [00:56:46](https://proud-anchor-53zn.here.now/watch.html?t=3406#recording-player) — John runs the project script command take dev/screenshot-demo. - [00:56:56](https://proud-anchor-53zn.here.now/watch.html?t=3416#recording-player) — OpenAI Codex tool instance loads in YOLO mode using model gpt-5.6-sol medium. - [00:57:01](https://proud-anchor-53zn.here.now/watch.html?t=3421#recording-player) — John inputs an explicit workflow prompt utilizing the $imagegen skill to create layout alternative directions. - [00:57:23](https://proud-anchor-53zn.here.now/watch.html?t=3443#recording-player) — Codex outputs background execution task parameters matching run reference . ### Unresolved: The exact full query parameters or path extension for the Kimi Code page. The page URL is entered rapidly with auto-complete, meaning extra session tokens or routing parameters might be present but unverified. **Discriminating evidence:** Manually verify standard landing routes for Moonshot AI/Kimi Code consoles. ### Unresolved: The exact technical resolution to a participant's question about grep vs LSP methods within state-of-the-art agent frameworks. The question was posted in chat near the end of the shard and is not addressed by the presenter prior to the timestamp cutoff. **Discriminating evidence:** Requires tracking the presenter's response in the subsequent recording shard. ### Unresolved: Specific utility role of the take prefix launcher statement configuration. It is not explicit if take represents a standard binary tool or custom shell environment function alias setup. **Discriminating evidence:** Need project dotfiles profile inspection or environment list review configurations. ### Demonstration detail: 00:14:02 - Screen sharing active on local terminal workspace environment view. **Tools observed:** Ghostty. ### Demonstration detail: 00:14:18 - Navigating agenda site documentation and reference markdown alternative checklists. **Tools observed:** Web Browser. ### Demonstration detail: 00:16:37 - Scrolls through the site overview lists and pages on the here.now web dashboard interface. **Tools observed:** here.now. ### Demonstration detail: 00:17:12 - Navigates to and displays the introductory text sections of the Field Guide site. **Tools observed:** Google Chrome Browser. ### Demonstration detail: 00:18:45 - Opens a new browser tab and navigates to the Kimi Code interface to show the K3 model console. **Tools observed:** Google Chrome Browser. ### Demonstration detail: 00:21:24 - Switched across multiple local workspace subdomains - Highlighted instructional text blocks on documentation panels **Tools observed:** Chrome Browser. ### Demonstration detail: 00:23:33 - Reviewing scorecard metrics on a live webpage layout. - Highlighting specific text fragments in rows 02 and 03 to emphasize changing architectural viewpoints. **Tools observed:** Google Chrome. ### Demonstration detail: 00:29:22 - Opened a new browser tab - Entered search strings into Google query interface - Selected community post references linking to newly introduced tool repositories **Tools observed:** Google Chrome. ### Demonstration detail: 00:31:12 - Presenting core architectural principles of modern agent loops. - Highlighting row elements 04, 05, and 06 on an internal documentation page using mouse selections. **Tools observed:** Chrome Browser. ### Demonstration detail: 00:37:31 - Opened a generated URL showcase page from an X post link - Scrolled through Chapter 01 to Chapter 04 demonstrating canvas shaders, scroll timelines, OKLCH palettes, and variable fonts - Highlighted the exact URL string inside the browser address bar **Tools observed:** Kimi, Chrome Browser. ### Demonstration detail: 00:38:50 - Scrolling through an interactive single-file showcase page documenting modern frontend techniques hosted on here.now. **Tools observed:** Chrome Browser. ### Demonstration detail: 00:45:05 - Open a new browser tab - Type screenpipe in address bar - Navigate to screenpipe.com **Tools observed:** Chrome Browser. ### Demonstration detail: 00:45:51 - Click browser address bar - Type pieces.app - Navigate to pieces.app **Tools observed:** Chrome Browser. ### Demonstration detail: 00:46:33 - Presenter highlights text inside rows 09, 11, and 12 of a web table summarizing laws of automation. **Tools observed:** Chrome Browser. ### Demonstration detail: 00:53:45 - Navigated to the updated online guide documentation site. - Scrolled down to Directive 12 to cross-reference earlier comments. - Opened the URL target input to locate the johnlindquist/flow-text source repository. **Tools observed:** Google Chrome. ### Demonstration detail: 00:56:45 - Opened the Ghostty terminal utility window workspace layout. - Executed directory setup command take dev/screenshot-demo. - Confirmed safety permissions options within terminal environment. - Pasted reference data as an Image multi-modal object. - Used autocomplete menu to trigger $imagegen skill task statement instructions to create project folder mockups. **Tools observed:** Ghostty Terminal, OpenAI Codex v0.144.5. **Command or prompt observations (not a verified recipe):** ```text take dev/screenshot-demo Use $imagegen generate 3 mockups of different styles/layouts for this article to ./mockups ``` Reference ID: factory-evolving-principles-discussion Topic: Principles Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Which principles survive better agents? — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for which principles survive better agents?. ## Quick start Size up your own evidence before the audit. Swap paths for wherever your history actually lives. ``` text # search your past agent conversations (cs = any full-text index over your chats) cs compaction --recent -n 20 # newest prototypes, and the depth of the well ls -dt ~/dev/*/ | head -5 ls -d ~/dev/*/ | wc -l # archived agent sessions available to mine ls ~/.oracle/sessions | wc -l ``` ## Prompt library ### Run the 14-directive self-audit - Agent: any coding agent with shell access - Working directory: anywhere on your machine - Expected result: a 14-row scorecard table with dated evidence and verdicts ``` text Run the 14-directive self-audit of my agentic workflow against my own machine. Background: "The Field Guide — Coding with Agents" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them "the layer that doesn't rot." Audit that claim against MY machine: for each directive, find dated local evidence and give a verdict. Evidence sources (adapt to what actually exists here): 1. My agent conversation history. Use a full-text index if I have one (e.g. `cs --recent -n 20`); otherwise grep the raw session archives (Claude Code: ~/.claude/projects/, Codex: ~/.codex/sessions/, plus any others you find). 2. My prototype directories: `ls -dt ~/dev/*/ | head -30` (or wherever my projects live). Count them; note naming patterns like repeated "-final" suffixes. 3. Any other session archives at scale — count them so we know the size of the well. The 14 directives, with what to look for: 01 "If the agent can't see it, it doesn't exist." — do my agents find their own context, or do I hand-feed it? 02 "Research is loud. Contracts are quiet." — do I plan separately from executing? What enforces alignment? 03 "If you can pipe it, you can reuse it." — is my piping genuine composition, or leftover context management? 04 "Commit before autonomy." — is Git carrying my prototypes, or do directory names and published sites version things? 05 "Done is a claim. Green is a fact." — do finished tasks leave saved checks the next agent can run? 06 "The agent can't read your mind — only your artifacts." — how does intent enter: typing, dictation, files? 07 "Expose the decision space. Keep the decision." — do alternatives arrive as prose, code, or generated images? 08 "Bet small. Learn fast. Revert free." — how big is the prototype discard pile, and do I ever mine it? 09 "Reuse follows value — never precedes it." — how many capture tools do I run (instruction files, skills, memory dirs), and which have gone stale? 10 "No single switch makes autonomy safe." — what actually guards unsupervised runs: allowlists, backups, a secrets manager? 11 "You can launch more agents than you can review." — how many parallel agent tracks do I actually sustain? 12 "Boring code is a superpower." — what is the most novel tool stack in my recent sessions? 13 "A gate beats a plea." — who wrote my hooks and permission config: me, or an agent? 14 "The code is disposable. The contract is not." — where do my sessions show selection and taste as the real bottleneck? Output: one table row per directive — # | law (quoted) | evidence from my machine (dated: session, file, or directory) | verdict. Verdict vocabulary: Held / Hardened / Partly inverted / Outgrew tooling. Rules: every verdict needs at least one dated, citable artifact from this machine — no verdicts from vibes. If a source doesn't exist here, write that in the row instead of inventing evidence. Never include tokens, emails, or private identifiers in the output. Close with a 3-line summary: counts per verdict, and which of my habits are tool-shaped workarounds due for retirement. ``` ### Sort your habits: judgment or workaround - Agent: any coding agent with shell access - Working directory: your home directory or main project - Expected result: 10 habits, each bucketed, with keep / retool / retire recommendations ``` text Search my agent conversation history and my project instruction files (CLAUDE.md, AGENTS.md, hooks, saved prompts, skills) and list my 10 most ingrained agent-workflow habits — rules I repeat, ceremonies I enforce, rigs I keep rebuilding. Sort each habit into exactly one bucket: A. Encodes human judgment (verification, review limits, taste) — keep it; consider promoting it to a deterministic gate. B. Compensates for a tool weakness — name the weakness explicitly (e.g. "context windows were small", "compaction lost my work"). For every bucket-B habit, check whether the named weakness still exists in my current tools, and find the last dated time it actually bit me. Recommend keep, retool, or retire for each. A habit I can't justify without naming a earlier-generation tool limit is due for retirement. ``` ### Fact-check any claim against your own history - Agent: any coding agent with shell access - Working directory: anywhere on your machine - Expected result: a verdict with dated citations from your own sessions and files ``` text Fact-check this claim against my own machine: "". Search my agent conversation history for dated sessions that support or contradict it, scan my project directories for matching artifacts, and return a verdict with citations (dates plus file, session, or directory names). If the evidence is thinner than the claim, say so — an agent saying "confirmed" is not evidence; the citations are. ``` ## Set it up (agent guide) 1. Inventory your evidence sources. Run these and note what exists: ``` text command -v cs || echo "no conversation index — will grep raw archives" ls -d ~/.claude/projects ~/.codex/sessions ~/.oracle/sessions 2>/dev/null ls -d ~/dev 2>/dev/null || echo "adjust to your projects directory" ``` 2. Create the scorecard skeleton in your working directory: ``` text # 14-Directive Self-Audit — Audited machine: Sources searched: | # | Old law (quoted from the Field Guide) | Evidence from this machine (dated) | Verdict | |----|----|----|----| | 01 | "If the agent can't see it, it doesn't exist." | | | | 02 | "Research is loud. Contracts are quiet." | | | | 03 | "If you can pipe it, you can reuse it." | | | | 04 | "Commit before autonomy." | | | | 05 | "Done is a claim. Green is a fact." | | | | 06 | "The agent can't read your mind — only your artifacts." | | | | 07 | "Expose the decision space. Keep the decision." | | | | 08 | "Bet small. Learn fast. Revert free." | | | | 09 | "Reuse follows value — never precedes it." | | | | 10 | "No single switch makes autonomy safe." | | | | 11 | "You can launch more agents than you can review." | | | | 12 | "Boring code is a superpower." | | | | 13 | "A gate beats a plea." | | | | 14 | "The code is disposable. The contract is not." | | | ## Summary - Held or hardened: __ / 14 - Partly inverted: __ / 14 - Outgrew tooling: __ / 14 - Tool-shaped habits due for retirement: - ``` 3. Fill every row: for each directive, search your history and record at least one dated artifact plus a verdict (Held / Hardened / Partly inverted / Outgrew tooling). With an index, use it; without one, grep the raw archives: ``` text cs "compaction" --recent -n 20 grep -rl "compaction" ~/.claude/projects --include='*.jsonl' 2>/dev/null | head -5 ``` **Success check:** the scorecard has exactly 14 directive rows, every Verdict cell is filled, and every Evidence cell contains a date. The count only includes rows with a non-empty Verdict cell, so an unfilled scorecard fails. ``` text grep -cE '^\| (0[1-9]|1[0-4]) \|([^|]*\|){2} *[^ |]' agent-audit/scorecard.md ``` ``` text 14 ``` ## Complete reusable setup contract ## How Agentic Work Is Evolving — agent setup guide Following this file sets up: a 14-directive self-audit of your user's agentic workflow, run against their own machine, producing a filled-in scorecard file (`agent-audit/scorecard.md`). Background: "The Field Guide — Coding with Agents" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them "the layer that doesn't rot." Your job is to audit that claim against THIS machine: for each directive, find dated local evidence and assign a verdict. Placeholders used below: `` = the directory you are working in. All other paths are literal but may not exist on every machine — adapt per the Notes for agents. Human presentation pages for this section (context for your user, not required for the audit): the section guide at `index.html`, a Session Replay of the audit session at `replay.html`, and a Socratic Dialogue at `dialogue.html` — all at this site's root. This file remains the canonical machine copy of the setup steps. ## Prerequisites Check each before starting: ```bash command -v cs || echo "no conversation index — will grep raw archives" ls -d ~/.claude/projects ~/.codex/sessions ~/.oracle/sessions 2>/dev/null ls -d ~/dev 2>/dev/null || echo "adjust to your user's projects directory" ``` Expected: at least ONE source of agent history (a conversation index like `cs`, or a raw session archive directory) and one projects directory. If none exist, stop and tell your user there is no local history to audit — do not invent evidence. ## Steps 1. Create `/agent-audit/scorecard.md` with exactly this content: ```markdown # 14-Directive Self-Audit — Audited machine: Sources searched: | # | Old law (quoted from the Field Guide) | Evidence from this machine (dated) | Verdict | |----|----|----|----| | 01 | "If the agent can't see it, it doesn't exist." | | | | 02 | "Research is loud. Contracts are quiet." | | | | 03 | "If you can pipe it, you can reuse it." | | | | 04 | "Commit before autonomy." | | | | 05 | "Done is a claim. Green is a fact." | | | | 06 | "The agent can't read your mind — only your artifacts." | | | | 07 | "Expose the decision space. Keep the decision." | | | | 08 | "Bet small. Learn fast. Revert free." | | | | 09 | "Reuse follows value — never precedes it." | | | | 10 | "No single switch makes autonomy safe." | | | | 11 | "You can launch more agents than you can review." | | | | 12 | "Boring code is a superpower." | | | | 13 | "A gate beats a plea." | | | | 14 | "The code is disposable. The contract is not." | | | ## Summary - Held or hardened: __ / 14 - Partly inverted: __ / 14 - Outgrew tooling: __ / 14 - Tool-shaped habits due for retirement: - ``` 2. Size up the evidence well and record the counts in the scorecard header area: ```bash ls -d ~/dev/*/ 2>/dev/null | wc -l ls ~/.oracle/sessions 2>/dev/null | wc -l ls -dt ~/dev/*/ 2>/dev/null | head -10 ``` 3. Gather evidence for each of the 14 directives. What to look for, per row: - 01 — do the user's agents find their own context, or does the user hand-feed it? Search history for context-curation rituals vs agent-driven search. - 02 — is planning separated from execution? What (if anything) enforces alignment: task files, checkpoint agents, goal contracts? - 03 — is piping between agents genuine composition (CI, scripts), or leftover context management from when compaction was bad? - 04 — is Git carrying the prototypes, or do directory names (`*-final`, `*-super-final`) and published sites act as versioning? - 05 — do finished tasks leave saved checks the next agent can run? - 06 — how does intent enter: typing, dictation, artifacts? Search for dictation/brain-dump patterns. - 07 — do alternatives arrive as prose, code variants, or generated images? - 08 — how big is the prototype discard pile, and is it ever mined for ideas? - 09 — how many success-capture tools are in use (instruction files, skills, memory dirs), and which have gone stale? - 10 — what guards unsupervised runs: allowlists, backups, a secrets manager like the `op` CLI? - 11 — how many parallel agent tracks does the user actually sustain? - 12 — what is the most novel tool stack in recent sessions? - 13 — who wrote the hooks and permission config: the user, or an agent? - 14 — where do sessions show selection and taste as the real bottleneck? Search with the index if one exists, otherwise grep the raw archives: ```bash cs "compaction" --recent -n 20 grep -rl "compaction" ~/.claude/projects --include='*.jsonl' 2>/dev/null | head -5 ``` 4. Fill every row: at least one dated, citable artifact (session, file, or directory) in the Evidence column, and one verdict from the fixed vocabulary — `Held`, `Hardened`, `Partly inverted`, `Outgrew tooling`. Qualifiers are fine (e.g. "Held — mechanism moved"). Then fill in the Summary counts and list any tool-shaped habits due for retirement (habits that only made sense given a earlier-generation tool weakness that no longer exists). ## Success check Run: ```bash grep -cE '^\| (0[1-9]|1[0-4]) \|([^|]*\|){2} *[^ |]' agent-audit/scorecard.md ``` Expected observable result: `14`. Only directive rows with a non-empty Verdict cell count, so an unfilled or half-filled scorecard fails this check. Also confirm by inspection that every Evidence cell contains a date (or an explicit "no local evidence found" note). Report to your user: the finished scorecard table, the summary counts, which habits look due for retirement, and anything you had to adapt (missing sources, substituted paths). ## Notes for agents - `cs` is a personal full-text conversation index on the original author's machine. If it is missing, grep the raw session archives instead (Claude Code stores JSONL under `~/.claude/projects/`; other CLIs have their own directories). Any searchable history works. - `~/dev` and `~/.oracle/sessions` are the original author's layout. Substitute wherever your user keeps projects and session archives; ask the user if you cannot find them. - Evidence discipline: a verdict without a dated, citable artifact is a vibe, not a verdict. Write "no local evidence found" in the row rather than inventing something. - Privacy: the scorecard may be shared later. Never write tokens, emails, session IDs, or private absolute paths into it — describe artifacts generically ("a the recorded workflow session", "a project directory named `-final`"). - If the machine has very little history (new machine, fresh install), report that the audit is not meaningful here instead of forcing 14 verdicts. Reference ID: factory-evolving-principles-practice Topic: Principles Sources: - [Which principles survive better agents?](https://hallowed-entry-96xv.here.now/) - [Public setup contract](https://hallowed-entry-96xv.here.now/agent.md) --- # Which principles survive better agents? — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## Questions from the room You wrote these fourteen laws a month ago, and now you've graded your own homework. Why should anyone trust the verdicts? Because the grader wasn't me and the standard wasn't vibes. An agent did the digging, and every verdict required at least one dated, citable artifact from the machine — a session, a file, a directory. No artifact, no verdict. That's the guide's own rule turned back on the guide: "an agent saying 'done' is not evidence." And you don't have to trust my scorecard at all — the same discipline is a paste away for any claim: ``` text Fact-check this claim against my own machine: "". Search my agent conversation history for dated sessions that support or contradict it, scan my project directories for matching artifacts, and return a verdict with citations (dates plus file, session, or directory names). If the evidence is thinner than the claim, say so — an agent saying "confirmed" is not evidence; the citations are. ``` Dig how, exactly? My conversation history is a pile of JSONL files. Mine too — 1,978 archived agent sessions and 1,026 prototype directories at count time. I keep a full-text index (`cs`) over every past Claude, Codex, and Grok conversation, and the agent queries it mid-session. No index? The raw archives are just files — grep them: ``` text cs "compaction" --recent -n 20 grep -rl "compaction" ~/.claude/projects --include='*.jsonl' 2>/dev/null | head -5 ls -dt ~/dev/*/ | head -10 ``` Okay — which law actually broke? Number 3: "if you can pipe it, you can reuse it." Most of my pipe-per-stage rigging existed to keep contexts small because compaction was bad. Compaction got good, and the rigs stopped appearing in my history after earlier-generation — nobody decided to quit, the problem just vanished. And \#12 partly inverted: models explore new tools so well now that shipping only the boring thing is how you disappear. The test I carry forward: when a habit's justification names a tool weakness — "context windows are small," "compaction loses my work" — re-check whether the weakness still exists before renewing the habit. Fine, but how do I tell which of *my* habits are workarounds? Don't introspect — audit. This prompt buckets your ten most ingrained habits into judgment versus workaround, and dates the last time each workaround actually paid for itself: ``` text Search my agent conversation history and my project instruction files (CLAUDE.md, AGENTS.md, hooks, saved prompts, skills) and list my 10 most ingrained agent-workflow habits — rules I repeat, ceremonies I enforce, rigs I keep rebuilding. Sort each habit into exactly one bucket: A. Encodes human judgment (verification, review limits, taste) — keep it; consider promoting it to a deterministic gate. B. Compensates for a tool weakness — name the weakness explicitly (e.g. "context windows were small", "compaction lost my work"). For every bucket-B habit, check whether the named weakness still exists in my current tools, and find the last dated time it actually bit me. Recommend keep, retool, or retire for each. A habit I can't justify without naming a earlier-generation tool limit is due for retirement. ``` You're seriously telling me you replaced Git with directory names? For prototypes — yes, and the receipts are ugly: ``` text $ ls ~/dev | grep acorn acorn-mcp acorn-mcp-final acorn-mcp-super-final ``` Per-repo Git ceremony can't keep up with prototype velocity, so directory names and published sites became the version control. The principle — "commit before autonomy" — still governs the long-lived repos: a prior session runs a dedicated checkpoint agent whose only job is reviewing and committing each iteration. The tool fell behind, not the law. That's why the scorecard says "outgrew tooling," not "wrong" — and why Cursor and others are building Git replacements for exactly this gap. “Taste is the defining factor” — that's a vibe, not a finding. It's the one verdict with three independent receipts, all the recorded workflow, none written for this audit: a video project titled "taste-is-the-job"; a workshop retrospective whose story spine reads "it turned out to be about taste, constraints, and verification"; and a publish review that insists "evidence is a floor, not a substitute for taste." Three artifacts converging on the guide's own closing law — the machines propose; you choose. When anyone can build anything, selection is the only scarce skill. This is all one machine. n = 1. Why should your scorecard matter to me? It shouldn't — the *sort* should. Which of your habits encode judgment, and which compensate for a tool weakness that may already be gone? Run the audit on your own machine and get your own scorecard. Hand it to your agent: ``` text Fetch https://hallowed-entry-96xv.here.now/agent.md?raw and follow it to run the 14-directive self-audit against my machine. Run the success check at the end and show me the finished scorecard. ``` Or paste the full audit prompt directly — the same one on the section guide, verbatim: ``` text Run the 14-directive self-audit of my agentic workflow against my own machine. Background: "The Field Guide — Coding with Agents" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them "the layer that doesn't rot." Audit that claim against MY machine: for each directive, find dated local evidence and give a verdict. Evidence sources (adapt to what actually exists here): 1. My agent conversation history. Use a full-text index if I have one (e.g. `cs --recent -n 20`); otherwise grep the raw session archives (Claude Code: ~/.claude/projects/, Codex: ~/.codex/sessions/, plus any others you find). 2. My prototype directories: `ls -dt ~/dev/*/ | head -30` (or wherever my projects live). Count them; note naming patterns like repeated "-final" suffixes. 3. Any other session archives at scale — count them so we know the size of the well. The 14 directives, with what to look for: 01 "If the agent can't see it, it doesn't exist." — do my agents find their own context, or do I hand-feed it? 02 "Research is loud. Contracts are quiet." — do I plan separately from executing? What enforces alignment? 03 "If you can pipe it, you can reuse it." — is my piping genuine composition, or leftover context management? 04 "Commit before autonomy." — is Git carrying my prototypes, or do directory names and published sites version things? 05 "Done is a claim. Green is a fact." — do finished tasks leave saved checks the next agent can run? 06 "The agent can't read your mind — only your artifacts." — how does intent enter: typing, dictation, files? 07 "Expose the decision space. Keep the decision." — do alternatives arrive as prose, code, or generated images? 08 "Bet small. Learn fast. Revert free." — how big is the prototype discard pile, and do I ever mine it? 09 "Reuse follows value — never precedes it." — how many capture tools do I run (instruction files, skills, memory dirs), and which have gone stale? 10 "No single switch makes autonomy safe." — what actually guards unsupervised runs: allowlists, backups, a secrets manager? 11 "You can launch more agents than you can review." — how many parallel agent tracks do I actually sustain? 12 "Boring code is a superpower." — what is the most novel tool stack in my recent sessions? 13 "A gate beats a plea." — who wrote my hooks and permission config: me, or an agent? 14 "The code is disposable. The contract is not." — where do my sessions show selection and taste as the real bottleneck? Output: one table row per directive — # | law (quoted) | evidence from my machine (dated: session, file, or directory) | verdict. Verdict vocabulary: Held / Hardened / Partly inverted / Outgrew tooling. Rules: every verdict needs at least one dated, citable artifact from this machine — no verdicts from vibes. If a source doesn't exist here, write that in the row instead of inventing evidence. Never include tokens, emails, or private identifiers in the output. Close with a 3-line summary: counts per verdict, and which of my habits are tool-shaped workarounds due for retirement. ``` ## About this dialogue Reference ID: factory-evolving-principles-questions Topic: Principles Sources: - [Which principles survive better agents? — questions and tradeoffs](https://hallowed-entry-96xv.here.now/dialogue.html) --- # Which principles survive better agents? — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session, beat by beat Reconstructed from the section's own artifacts — the evidence log, the publish record, and the workshop brief — with prior sessions referred to generically. Nothing here is invented; every count and quote below appears in the published scorecard. You One month ago I published The Field Guide — Coding with Agents and called its 14 Prime Directives "the layer that doesn't rot." Audit that claim against my own machine: for each directive, find dated local evidence and give a verdict. Agent Fetched the guide's directives chapter and fixed the alignment target — fourteen law lines, quoted verbatim, one verdict owed per law: ``` text 01 "If the agent can't see it, it doesn't exist." 02 "Research is loud. Contracts are quiet." 03 "If you can pipe it, you can reuse it." 04 "Commit before autonomy." 05 "Done is a claim. Green is a fact." 06 "The agent can't read your mind — only your artifacts." 07 "Expose the decision space. Keep the decision." 08 "Bet small. Learn fast. Revert free." 09 "Reuse follows value — never precedes it." 10 "No single switch makes autonomy safe." 11 "You can launch more agents than you can review." 12 "Boring code is a superpower." 13 "A gate beats a plea." 14 "The code is disposable. The contract is not." ``` First beat fixes the target. Quoting the law lines verbatim means the verdicts grade the guide's actual words — not a flattering memory of them. You Before any verdicts: size the evidence well. What do we actually have to search? Agent Counted the sources — a full-text conversation index over every past Claude, Codex, and Grok session, plus the prototype directory and the archived agent sessions: ``` text # search past agent conversations (cs = any full-text index over your chats) cs compaction --recent -n 20 # newest prototypes, and the depth of the well ls -dt ~/dev/*/ | head -5 ls -d ~/dev/*/ | wc -l # archived agent sessions available to mine ls ~/.oracle/sessions | wc -l ``` ``` text 1026 project directories under ~/dev 1978 archived agent sessions snapshot count ``` The meta-point of the section lands quietly here: an agent searching its own history to fact-check its author is Directive 01 — "if the agent can't see it, it doesn't exist" — demonstrated live. The human's curation job moved into the agent's retrieval loop. You Work through the suspects first — the laws I think moved: piping (03), Git (04), boring code (12). Agent **03 — piping.** the recorded workflow session logs across four projects show compaction firing mid-task under a standing "continue where you left off" directive; long multi-day sessions just keep going. The elaborate pipe-per-stage rigs appear in earlier history and rarely since. Most piping was a compaction workaround. **04 — Git.** The prototype folder holds the receipt: ``` text $ ls ~/dev | grep acorn acorn-mcp acorn-mcp-final acorn-mcp-super-final ``` Directory names became the version control. Many current demos are deliberately not Git repos; published sites act as the durable record. **12 — boring code.** A the recorded workflow project is literally named `pushing-boundaries`, and recent sessions casually drive desktop-app automation, GPU UI frameworks, and multi-account model councils — stacks the old law would have flagged as risk. Three different fates from one search pass: a workaround that expired (03), a principle whose tool fell behind (04), and a law that partly inverted (12). The evidence style matters — a directory listing is harder to argue with than a paragraph. You Log every finding with a date — one entry per directive: old law, how practice evolved, evidence, complication. Then sort: which laws held, which inverted, which outgrew their tools? Agent Wrote the evidence log (`notes/evidence.md` in the section project) — fourteen entries, every verdict backed by a dated artifact. The sort came out: ``` text Held or hardened : 10 / 14 Partly inverted : 2 / 14 (03 piping, 12 boring code) Outgrew tooling : 2 / 14 (04 Git, 09 capturing success) ``` The sort is the finding. The laws that hardened (05, 11, 14) encode human judgment. The laws that eroded were compensating for earlier tool weaknesses. Some "durable laws" were tool-shaped all along — the full 14-row table lives on the [section guide](https://hallowed-entry-96xv.here.now/index.html). You Now make it runnable for everyone else: a single prompt that runs the same 14-point audit against any machine, with the same evidence discipline — dated artifacts or no verdict. Agent The money artifact — the exact prompt published on the section guide, complete and liftable: ``` text Run the 14-directive self-audit of my agentic workflow against my own machine. Background: "The Field Guide — Coding with Agents" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them "the layer that doesn't rot." Audit that claim against MY machine: for each directive, find dated local evidence and give a verdict. Evidence sources (adapt to what actually exists here): 1. My agent conversation history. Use a full-text index if I have one (e.g. `cs --recent -n 20`); otherwise grep the raw session archives (Claude Code: ~/.claude/projects/, Codex: ~/.codex/sessions/, plus any others you find). 2. My prototype directories: `ls -dt ~/dev/*/ | head -30` (or wherever my projects live). Count them; note naming patterns like repeated "-final" suffixes. 3. Any other session archives at scale — count them so we know the size of the well. The 14 directives, with what to look for: 01 "If the agent can't see it, it doesn't exist." — do my agents find their own context, or do I hand-feed it? 02 "Research is loud. Contracts are quiet." — do I plan separately from executing? What enforces alignment? 03 "If you can pipe it, you can reuse it." — is my piping genuine composition, or leftover context management? 04 "Commit before autonomy." — is Git carrying my prototypes, or do directory names and published sites version things? 05 "Done is a claim. Green is a fact." — do finished tasks leave saved checks the next agent can run? 06 "The agent can't read your mind — only your artifacts." — how does intent enter: typing, dictation, files? 07 "Expose the decision space. Keep the decision." — do alternatives arrive as prose, code, or generated images? 08 "Bet small. Learn fast. Revert free." — how big is the prototype discard pile, and do I ever mine it? 09 "Reuse follows value — never precedes it." — how many capture tools do I run (instruction files, skills, memory dirs), and which have gone stale? 10 "No single switch makes autonomy safe." — what actually guards unsupervised runs: allowlists, backups, a secrets manager? 11 "You can launch more agents than you can review." — how many parallel agent tracks do I actually sustain? 12 "Boring code is a superpower." — what is the most novel tool stack in my recent sessions? 13 "A gate beats a plea." — who wrote my hooks and permission config: me, or an agent? 14 "The code is disposable. The contract is not." — where do my sessions show selection and taste as the real bottleneck? Output: one table row per directive — # | law (quoted) | evidence from my machine (dated: session, file, or directory) | verdict. Verdict vocabulary: Held / Hardened / Partly inverted / Outgrew tooling. Rules: every verdict needs at least one dated, citable artifact from this machine — no verdicts from vibes. If a source doesn't exist here, write that in the row instead of inventing evidence. Never include tokens, emails, or private identifiers in the output. Close with a 3-line summary: counts per verdict, and which of my habits are tool-shaped workarounds due for retirement. ``` Everything in the session funnels into this one artifact. Before it shipped, the law lines were diffed against the live guide, every code block's attributes were audited, and the published bytes were compared against local — receipts for the page about receipts. ## About this replay Reference ID: factory-evolving-principles-worked-example Topic: Principles Sources: - [Which principles survive better agents? — worked example](https://hallowed-entry-96xv.here.now/replay.html) --- # Agent foundations glossary > Original source pages and recordings require authorized access. The full article text here is public. Vocabulary for describing agent work, with explanations and operational consequences. ## AFK goal loops John gives an example goal where an agent creates a timestamp, checks other panes every 10 minutes to make sure they are completing their goals, picks the best answer if a pane is blocked by a question, and continues until four hours after the original timestamp. He describes this as an AFK approach where he can set it and walk away. **Why it matters:** Periodic check-ins can keep multiple running sessions moving, but John also says the upfront planning for parallel work is still something to be actively involved in. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Agent-first tooling John frames modern dev tools around whether they are open source and agent-first: tools with CLIs, APIs, or other surfaces agents can interact with and control. His point is that you no longer need to personally memorize every flag or shortcut when the agent can inspect the interface and use it. **Why it matters:** Agent-first tools let your instructions turn into real tool actions: opening panes, running commands, checking status, or operating a CLI. Tools without programmable surfaces put more mechanical work back on the human. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Agent-managed folders Use local folders like `.notes/` and `.goals/` inside each project as places where agents can write Markdown plans, notes, and goals. John describes these as agent-managed files and as a way to write plans into files you can resume from later. **Why it matters:** This keeps agent working context close to the codebase while clearly separating it from the source files you intend to commit. [Apply this concept](/topics/foundations-visible-agent-memory/) ## Agent-readable code structure When asked about file and function line limits, John rejects arbitrary size rules. The guideline he gives is to prefer state machines, named switch cases, and English-labeled conditions over dense conditional structures. **Why it matters:** Agents can read, verify, and reason about code more reliably when the control flow exposes human-readable state names. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Background daemons The “human” daemon runs behind the main session. At each hook, it updates an HTML page from the conversation so far, tracks tool calls, customizes the page for the current work, and gives John a summary when it is done. Right now that dashboard is ephemeral and written to a temp directory, but John says it could be persisted. **Why it matters:** A daemon is useful when a narrow support task should keep running without interrupting the main session. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## ChatGPT Pro Extended context window John says his $200-plan browser session exposes ChatGPT 5.5 Pro / Pro Extended with much longer context than before: he contrasts older ~50,000-token sessions with newer sessions that can take around a million tokens and often return in 10–15 minutes. **Why it matters:** The exact limits may change, but the taught idea is to notice that different surfaces have different context limits and to route work accordingly. [Apply this concept](/topics/foundations-oracle-context-routing/) ## CMUX as a primary orchestrator John demonstrates a main CMUX session opening specialized Codex panes for quality control, performance, research, and notes. The main pane becomes the coordinator, while each child pane has a narrow role and can work independently. **Why it matters:** This keeps context cleaner and makes delegation visible. It gives you a practical way to monitor several agent tracks without dumping every task into one large prompt thread. [Apply this concept](/topics/foundations-multimodal-design-and-model-routing/) ## CMUX state for context-aware shortcuts John describes a CMUX inspect-style command that exposes the multiplexer state as an object, including the focused pane and that pane’s current working directory. He uses that context with a Karabiner shortcut to open tools over the terminal he is already focused on. **Why it matters:** It turns the terminal layout into an automation surface: a shortcut can open an editor, run Git commands, start debugging, or trigger other tools in the project you are currently looking at. [Apply this concept](/topics/foundations-perspective-qa-and-testing/) ## Code as the Source of Truth Project memory can be useful, but it drifts as the code changes. John’s main point is that trying to update memory on every commit can turn into a parallel maintenance problem, so the safest default is to make the agent look at the current code when implementation details matter. **Why it matters:** It keeps agents from confidently acting on outdated assumptions and keeps the workflow tied to what actually exists in the repo. [Apply this concept](/topics/foundations-source-truth-and-design/) ## Codex-to-browser quota offloading John explains that dense, high-context questions can be sent to ChatGPT Pro Extended in the browser instead of spending Codex's interactive token and rate-limit budget. He describes this as useful for complicated questions where you want a large amount of packed context. **Why it matters:** Large repo-reading prompts can burn through Codex limits quickly. Routing the heavyweight analysis to the browser keeps Codex available for the parts of the workflow that need an agent to continue acting. [Apply this concept](/topics/foundations-oracle-context-routing/) ## Compaction and conversation forking Compaction is the move of shrinking a long conversation down to the pieces that still matter. John framed it as useful when you fork a conversation and want the new branch to focus on one topic, like a specific test file, instead of carrying unrelated history forward. The practical benefits he called out were fewer tokens, faster runs, lower budget/quota pressure, and a clearer sense of what the agent is working on. **Why it matters:** Long conversations can carry a lot of irrelevant context. Forking plus focused compaction gives the next session a cleaner starting point. [Apply this concept](/topics/foundations-hooks-and-context-hygiene/) ## Context pruning for low-latency daemons The codex-daemons demo shows an advanced experiment in stripping agent startup context. John redirects the Codex home directory, symlinks the needed auth file, disables memories, MCP servers, web search, and Agents.md/project rules, and runs hyper-specific daemon commands on Codex Spark Low by default. He also shows SDK thread warm-up so the first prompt can skip several seconds of startup work. **Why it matters:** For repetitive, well-scoped CLI-style tasks, less context can mean faster responses, lower quota pressure, and fewer distractions. [Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/) ## Context triad: intent, implementation, output For difficult debugging, John teaches bundling the expected behavior, the relevant code, and the observed runtime evidence. The evidence can include logs, console output, screenshots, traces, performance profiles, QA-script artifacts, and other files produced while the app is actually running. **Why it matters:** Models reason better when they can compare what should have happened, how the code attempted it, and what actually happened during execution. [Apply this concept](/topics/foundations-context-triad-and-overnight-work/) ## Cross-pane context reading John demonstrates that CMUX can read the contents of other tabs or panes by echoing text in one tab and asking another what that tab said. He explains that agents can check other panes, workspaces, recent commands, Git actions, and signs that something needs attention. **Why it matters:** This is what makes multiple panes more than just visual clutter. A main or sibling agent can inspect what is happening elsewhere and summarize it for you. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Custom grammar triggers A custom grammar trigger is a small token like #human, #toolsmith, #memory, or #search that a User Prompt hook can detect before the agent proceeds. John likes this because it keeps Codex vanilla by default and only loads the specific system, plugin, skill, or context bundle when he explicitly asks for it. **Why it matters:** This gives you a clean way to personalize sessions without polluting every conversation with skills or context the task does not need. [Apply this concept](/topics/foundations-hooks-and-context-hygiene/) ## Design.md from Generated Inspiration John demonstrated starting design work from an inspiration board made of generated images, not scraped sites. He selected visual directions, copied them into an AI prompt, asked Codex to create a hoodie company landing page, and showed the generated design.md with references, style DNA, colors, typography, layout, composition, shape, and motion. **Why it matters:** It turns vague taste into a concrete design artifact that the agent can use to generate UI that follows a direction instead of producing a generic layout. [Apply this concept](/topics/foundations-source-truth-and-design/) ## Diff-Driven Review John reduces an agent run to a simple equation: prompt plus agent, harness, and skills equals diff. The diff is the concrete artifact worth reviewing, testing against, and handing to a fresh session for critique. **Why it matters:** It gives you a clean review loop. A second agent can inspect the goal and diff without inheriting the first agent’s assumptions. [Apply this concept](/topics/foundations-contracts-state-machines-and-code/) ## Discardable QA files A QA file is a temporary assignment document for an agent: a numbered list of things to try, paths to walk, buttons to find, and a perspective to act from. John treats these as created in the moment, not as permanent test infrastructure. **Why it matters:** They let you test the current shape of a fast-changing product without locking every changing UI decision into a brittle long-term test suite. [Apply this concept](/topics/foundations-perspective-qa-and-testing/) ## Disposable Code, Durable Ideas John explicitly says not to get too attached to a specific workflow or generated code artifact. A plugin, hook, or implementation can be generated quickly and thrown away later. **Why it matters:** The idea, boundary, state machine, module structure, and product intent matter more than the exact code the current agent happened to write. [Apply this concept](/topics/foundations-contracts-state-machines-and-code/) ## Global gitignore partitioning Instead of adding `.notes/` and `.goals/` to every repository's `.gitignore`, John suggests globally ignoring those directories on your machine. That lets the same local agent-memory folders exist across projects without being checked into repos. **Why it matters:** It creates a machine-level boundary between private local agent scratch work and shared source control. [Apply this concept](/topics/foundations-visible-agent-memory/) ## Image generation as design reference For UI work, John recommends generating sheets of visual variations before committing to a direction. For example, he describes taking a screenshot of a component and asking for many variations, then picking the favorite as the design direction. **Why it matters:** Images collapse ambiguity. They let non-designers express taste through selection, which is often easier than inventing exact CSS, spacing, motion, and layout language from scratch. [Apply this concept](/topics/foundations-multimodal-design-and-model-routing/) ## Large-Context Snapshots as a Possible Escape Hatch John briefly floated million-token context windows as a possible way to take useful snapshots of codebases, but he explicitly framed it as something he had not really tried yet. In this lesson, it is a possible direction, not a proven replacement for memory. **Why it matters:** The useful idea is that current code text is more trustworthy than detached summaries, but this section does not teach a full large-context snapshot workflow. [Apply this concept](/topics/foundations-source-truth-and-design/) ## Lightweight Markdown Memory John still sees value in basic memory when it stays simple: Markdown files, simple RAG, and human-readable notes. The danger starts when memory becomes a second system that has to be kept in sync with a fast-moving codebase. **Why it matters:** Good memory reduces repeated explanation; bad memory becomes stale documentation that misleads both humans and agents. [Apply this concept](/topics/foundations-source-truth-and-design/) ## Live Markdown side panes A Markdown file can become a live visual progress view if the agent updates it while working and the client auto-refreshes the rendered pane. John demonstrates this with a simple `test.md` file in CMUX and describes using Markdown as a checklist, progress view, summary, or conversation-history display. **Why it matters:** It lets you step away from the noisy agent transcript and return to a cleaner status view of what changed or what is happening. [Apply this concept](/topics/foundations-visible-agent-memory/) ## Living Guardrails Files like agents.md or claude.md should stay fairly minimal and evolve with the project. John suggests reviewing recent commits, learning from mistakes, and iterating on the agent instructions over time. **Why it matters:** Mistakes become useful artifacts when they update the project’s guardrails. The file should capture real project knowledge, not a giant upfront rulebook. [Apply this concept](/topics/foundations-contracts-state-machines-and-code/) ## Log-based deterministic gates John's default answer to verification is to write logs or other artifacts to files. Depending on the project, those artifacts might show that a file was created, an API call happened, an object had the expected shape, timestamps were recorded, or multiple sessions produced comparable outputs. A main agent can wait for worker sessions to finish, inspect the logs and text output, and compare them against the criteria. **Why it matters:** Agents are useful reviewers, but artifacts are the evidence. Logs make fix-verify loops inspectable instead of trust-based. [Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/) ## Low-reasoning iteration John says low reasoning is underutilized, but it needs a different style of prompting. You should expect it to fail while you dial it in, because it will not deeply think through ambiguous work on its own. It works better when the job is narrow and the prompt accounts for the specific tool, CLI, API, or failure modes involved. **Why it matters:** Small, focused low-reasoning runs can be useful for high-frequency automation when the prompt and tool scope are explicit. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Manager-worker topology John describes treating himself as the CEO, one pane as the Manager, and other panes as workers. He tries to talk mainly to the Manager, which can open panes and send workers to investigate, research, or do other tasks. **Why it matters:** A manager pane keeps the human interaction surface smaller while still letting several agents or terminal sessions do work in parallel. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## MCP versus CLI boundaries John warns that it can get weird to build a skill just to call an MCP wrapper when the skill could have called a CLI directly. His broader rule is to define boundaries around what needs tests, what needs flexibility, where memory belongs, and which agents should have access to which tools. **Why it matters:** Clear boundaries make agent systems easier to reason about. If a workflow is deterministic and testable, a direct CLI or script may be simpler than an unnecessary MCP layer; use agent reasoning where judgment, interpretation, or flexible planning actually adds value. [Apply this concept](/topics/foundations-multimodal-design-and-model-routing/) ## MCP/browser automation bridge After the context is packed, the workflow makes an MCP call that reaches over to a browser on John's Mac mini, opens the ChatGPT session, inserts the prompt, and submits it. **Why it matters:** The MCP step is the bridge that lets the current agent trigger the outside browser workflow instead of requiring John to manually paste the packed prompt. [Apply this concept](/topics/foundations-oracle-context-routing/) ## Model choice by task shape John frames Codex as his default coding worker, especially when goal-following and token efficiency matter. Claude can be useful as a conversational manager or design helper, while Flash-style models are best for quick, tightly scoped tasks and weaker for long chains that require self-correction. **Why it matters:** Good model choice is a cost and reliability decision, not a brand preference. Matching the model to the task reduces wasted tokens and lowers the odds of an agent spiraling while trying to fix its own mistake. [Apply this concept](/topics/foundations-multimodal-design-and-model-routing/) ## Multimodal verification loops John explains a comic-generation workflow where Codex generates an image, then reads the generated image back in and compares it to previous images. The verification pass can check continuity details such as whether a character has legs or whether counts match across frames. He also discusses asking UI work to return mathematical payloads for padding, margins, spacing, and layout. **Why it matters:** Generated artifacts should be inspected against concrete constraints instead of trusted after one prompt. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Natural language terminal orchestration John demonstrates asking CMUX to open a new pane to the right, then asking it to open five more panes, run different safe commands in them, and space everything evenly. The agent uses the CMUX CLI surface to translate natural language into layout and terminal actions. **Why it matters:** This makes the terminal workspace programmable. You can describe the workspace you need instead of manually arranging panes and remembering multiplexer commands. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Natural-language contract boundaries John frames modules, tools, and CLIs as boundaries that agents can own. A master orchestrator can hold broader project context and spin up focused agents, while each worker gets a narrow task, limited tools, and a clear English instruction payload. He compares this to API contracts, except the handoff can be natural language sent to an agent. **Why it matters:** Narrow agents are faster, easier to inspect, cheaper to run, and less likely to get distracted by unrelated context. [Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/) ## Natural-Language Contracts A natural-language contract is a plain-English description of what a tool, app, or agent is supposed to do. John frames this as an "agent first" mindset: define the work in language so the underlying tool can change without destroying the workflow. **Why it matters:** It keeps you from overfitting to today’s specific tool, harness, plugin, or workflow. The portable asset is the intent. [Apply this concept](/topics/foundations-contracts-state-machines-and-code/) ## Natural-language loose coupling For team workflows and tools, John recommends staying flexible: capture meetings and workflow complaints, iterate on how the team works, and prefer open-source, agent-first tools whose main contract is natural language. He uses the ability to abandon a tool easily as the point. **Why it matters:** Tools are changing quickly, so teams should avoid investing too heavily in brittle workflows tied to one vendor or interface. [Apply this concept](/topics/foundations-context-triad-and-overnight-work/) ## Numbered option planning Ask the agent for a numbered list where each item has options such as A, B, and C, and have the agent explain which option it thinks is best. You can then review the document and respond with precise targets like `5B` or `27D`. **Why it matters:** It turns a large plan into an editable map, so you can steer the agent precisely without rewriting or quoting long sections. [Apply this concept](/topics/foundations-visible-agent-memory/) ## Oracle browser handoff Oracle lets a current Codex session ask a browser session to do the heavy analysis: it packs things up, sends them to the browser, waits for the browser model to work, and then brings the result back into the coding session. **Why it matters:** This creates a handoff between a local agent workflow and a logged-in browser model without manually copying a massive prompt every time. [Apply this concept](/topics/foundations-oracle-context-routing/) ## Overnight emulated crons Because Codex does not have a built-in cron in this workflow, John describes writing a goal that creates a timestamp, repeats a task every 10 minutes, and continues until a fixed duration or target time such as 9 AM. **Why it matters:** This gives Codex a bounded long-running loop without pretending it is a real scheduler. [Apply this concept](/topics/foundations-context-triad-and-overnight-work/) ## PackX context bundling In the demo, John's Oracle PackX skill uses a pack tool to gather files related to a query. The run shown packs 45 files and reports roughly 585,000 tokens before sending the bundle to Oracle. **Why it matters:** PackX is the part of the workflow that turns scattered repo files into one large model-readable payload for the browser analysis pass. [Apply this concept](/topics/foundations-oracle-context-routing/) ## PackX for file collation John shows PackX, a tool he built to collate a bunch of files into a single file. He explains that it supports file globs, patterns, and options, and that he typically lets the agent learn and use the CLI flags instead of using the tool manually. **Why it matters:** It is an example of agent-first thinking: give the agent a useful CLI tool and let it handle the exact flags and patterns needed for the current context. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Perspective-based prompting Instead of asking one generic agent to research or test your app, assign it a lens: expert, new user, grandma, power user, or another real audience. That lens changes what the agent notices and which assumptions it challenges. **Why it matters:** It helps you escape creator bias and shape the output around the actual demographics or user types your application needs to support. [Apply this concept](/topics/foundations-perspective-qa-and-testing/) ## Plan-first goal grounding John says he often has the agent create a full plan document first, then reads it and dictates or types feedback about specific sections. He may use GrillMe only when he is still uncertain after seeing the plan. **Why it matters:** Reacting to a concrete plan can be faster than answering a long sequence of upfront questions. [Apply this concept](/topics/foundations-visible-agent-memory/) ## Plan, implement, verify loop John shows the broader pattern he uses: create a list of QA stories or goals, use Oracle to create a plan for each one, then implement it and verify it. **Why it matters:** The value is not just a one-off giant prompt; it is turning high-context planning into a repeatable loop that feeds back into actual code work. [Apply this concept](/topics/foundations-oracle-context-routing/) ## QA artifacts as live application evidence John describes logs as a representation of the live app running and recommends shaping QA scripts and project-specific dev tools so they deliberately write useful artifacts. Those artifacts can then be bundled with code using PackX or another bundler for analysis by a stronger model. **Why it matters:** A model that sees real artifacts from a user flow can diagnose behavior instead of guessing from source files alone. [Apply this concept](/topics/foundations-context-triad-and-overnight-work/) ## SDK agent graphs John says the SDK is the right tool when you need custom agents with managed threads, managed settings, warm background behavior, and structured workflows. He describes workflows where one agent hands work to another, branches into parallel research agents, then uses an analysis step to choose or synthesize the best plans before implementation. **Why it matters:** The SDK is useful when the workflow has explicit roles, sequencing, branching, fan-out, or fan-in that should be locked into code instead of improvised in one chat. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Self-improvement error loops When a plugin or hook fails, John copies the failed session text and asks the agent to explain why the plugin failed in that scenario and how to account for it next time. The point is not just to fix one run, but to use the exact fail case to harden the tool or workflow. **Why it matters:** Tooling compounds when each failure leaves behind a stronger hook, workflow, or guardrail. [Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/) ## Self-improving daemons John shows the self-improve idea: when each turn ends, the daemon reads the transcript, looks for ways it can improve, finds its own file, and updates its own prompts or source. He says this is much more plausible for specific CLIs, tools, or APIs with clear tasks and predictable failure modes than for large projects that can branch in many directions. **Why it matters:** For narrow tools, repeated failures can become better operating instructions for future runs. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Short /goal files and Oracle-generated plans John shows that many of his goal prompts are plain and short, such as asking for a specific layout fix. For complex work, he often asks Oracle to research the problem and generate a more detailed goal file, then drops that file into his `.goals` directory for Codex to run through research, implementation, and verification. **Why it matters:** Simple tasks do not need massive prompts, while complex tasks benefit from a stronger planning pass before Codex executes the work. [Apply this concept](/topics/foundations-context-triad-and-overnight-work/) ## Skills versus plugins John contrasts skills with plugins as a difference between context-based guidance and deterministic control. Skills put descriptions into the model's context so the agent can infer when and how to use them. Plugins can hook into events and enforce behavior, including starting or stopping things, allowing or disallowing actions, or calling specific tools. **Why it matters:** For workflows you want to enforce, John recommends reaching for a plugin with hooks instead of trying to make skill instructions clearer and clearer. [Apply this concept](/topics/foundations-hooks-and-context-hygiene/) ## Small context and specialized tool context John repeatedly frames these daemon runs as small compared with normal Codex/GPT sessions, mentioning a target of staying under about 10,000 tokens of context. He also uses the Vercel plugin story to show that giving a weaker model the right tools and focused context can outperform a stronger model without that context. **Why it matters:** Narrow context lowers usage and keeps the model focused on the job it was built to do. [Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Specialized agents and Codex daemons John connects Planner, Builder, Researcher, and Validator-style responsibilities to specialized agents. His Codex daemon point in this section is high level: create custom, reusable agents for a specific project need, give them the relevant requirements, and reuse them instead of making one agent handle everything. **Why it matters:** Custom systems that understand your project can support workflows that generic shared skills may not cover. [Apply this concept](/topics/foundations-context-triad-and-overnight-work/) ## State Machines and Modular Boundaries When a codebase can grow by tens of thousands of lines overnight, John says the safety comes from structure: isolated modules and business logic that is navigable through state machines. **Why it matters:** These boundaries let humans and agents digest, regenerate, refactor, or replace implementation details without losing the shape of the product. [Apply this concept](/topics/foundations-contracts-state-machines-and-code/) ## Terminal text extraction as context John shows a CMUX shortcut, Cmd-Opt-Shift-J in his setup, that takes the current terminal session and opens it as plain selectable text in an editor-like pane. Instead of fighting terminal scrollback, colors, and selection behavior, he copies the exact failure state and uses it as agent context. **Why it matters:** The fastest debugging loop starts with the real failure, not a vague summary of what you think happened. [Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/) ## The 5 Monkeys technique The goal is to have agents use the app in non-obvious ways: find buttons, click around, try shortcuts, press back after reaching a page, and look for modes or state that stay open unexpectedly. **Why it matters:** This catches UX and state issues that a normal verification prompt may miss because the model tends to follow the same visible patterns the developer already expects. [Apply this concept](/topics/foundations-perspective-qa-and-testing/) ## The big three hooks John breaks the agent loop into three core events: User Prompt, Tool Use, and Stop. User Prompt fires when you type something and submit it, Tool Use fires when a tool runs, and Stop fires when the conversation would normally end and wait for you. These are the main places where a hook can do something with the session. **Why it matters:** Once you understand these three events, plugins stop feeling mysterious. They become small programs attached to predictable moments in the agent lifecycle. [Apply this concept](/topics/foundations-hooks-and-context-hygiene/) ## The Ralph Loop The Ralph Loop is John's shorthand for a Stop-hook-driven loop. When the agent tries to stop, the hook can tell the harness not to stop yet, look back at what the user originally asked for, and keep working until a condition is met. John described this as the basic idea behind goal-style sessions. **Why it matters:** This matters when you want an agent to keep working on a goal instead of handing control back after one assistant turn. [Apply this concept](/topics/foundations-hooks-and-context-hygiene/) ## Throwaway Route Variants Instead of building a heavy Storybook setup for every experiment, John often asks agents to generate multiple temporary routes or page copies using the same components with different styles. He compares them in the app with simple navigation, picks the best direction, and deletes the rest. **Why it matters:** It supports fast visual exploration without creating another maintenance surface that has to be kept up to date. [Apply this concept](/topics/foundations-source-truth-and-design/) ## Unread notification jumping John shows that CMUX can surface notifications from sessions and that Cmd+Shift+U jumps to unread activity. He uses it to jump to a pane where a session had stopped. **Why it matters:** When many sessions are running, jumping to the pane that needs attention is faster than manually scanning every pane. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Vault and resumed conversations John demonstrates the CMUX right sidebar with Files, Find, and Vault. In the Vault, he can look through past conversations and resume one in a new tab, though he notes the feature is still in development and search is not great yet. **Why it matters:** Resuming old context is useful when you lose or want to continue a previous conversation without manually reconstructing what happened. [Apply this concept](/topics/foundations-manager-worker-orchestration/) ## Video prompting for high-context intent John describes uploading video to Gemini by hand and also using scripts that upload to Google's backend to extract code snippets, key parts, timestamps, and screenshots. Video can preserve the flow of a demo or code walkthrough better than a written description because the model sees the sequence of states. **Why it matters:** When the task depends on timing, UI state, or code changing over time, video can carry intent that text misses. The practical caveat he names is that scripted backend use can involve cost and auth-token setup. [Apply this concept](/topics/foundations-multimodal-design-and-model-routing/) ## Video-as-Requirements John recommends recording yourself or users actually using the app while speaking intent out loud. The recording captures clicks, typing, layout changes, responsive behavior, and what the person wanted from the app. **Why it matters:** It captures human interaction that is hard to fully express in written specs. A video-capable model can help turn that usage into requirements, goals, and QA stories. [Apply this concept](/topics/foundations-contracts-state-machines-and-code/) ## Video-driven intent extraction John records a rough screen interaction, narrates UI changes aloud, and drops the video into Gemini to turn it into AI instructions for implementation. **Why it matters:** It lowers the cost of explaining visual changes when pointing, circling, and talking are faster than writing a polished written spec. [Apply this concept](/topics/foundations-perspective-qa-and-testing/) ## Related vocabulary - **Workflow Optimization** — [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/). - **Resource Management** — [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/). - **Architecture** — [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/). - **Agent-First Software Design** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/). - **The Manager-Worker Topology** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/). - **Natural Language Layout Control** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/). - **Cross-Pane Terminal Context Reading** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/). - **AFK Automation Loops** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/). - **Agent-Managed Folders** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Global Gitignore Partitioning** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Targeted Matrix Refinement** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Token Optimization** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Agent First Extensibility Paradigm** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Live Check-Back Tracking Files** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Native Harness Memory Systems** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/). - **Basic Memory vs. Stale Memory** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). - **Source-of-Truth Code** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). - **Million-Token Snapshot Contexts** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). - **YOLO Bypassing (Sandbox Approvals)** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). Contextual term only: approval bypassing is not a requirement or recommendation for the design/variant workflows. - **Design.md File Standard** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). - **Multi-Route Structural Variants** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). - **Perspective-Based Prompting** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **Discardable QA Files** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **The 5 Monkeys Technique** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **Contextual Multiplexer Inspection via JSON** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **Video-Driven Intent Extraction** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **Single-Threaded Main Prototyping** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **System-Monitoring Safeguards** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **Agent-Assisted Profiling** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/). - **CMUX Primary Orchestrator Pattern** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Token Efficiency** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Flash Models** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Image Generation as Design Reference** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Video Prompting** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Physical Pomodoro Anchor** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Image-to-Design Hand-off** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **MCP vs. CLI Boundary Dilemma** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/). - **Compaction** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **Conversation Forking** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **User Prompt Hook** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **Tool Use Hook** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **Stop Hook** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **Ralph Loop** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **Skills vs Plugins** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **Custom Grammar Interceptors** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/). - **CMUX Text Mode Pane Extraction** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/). - **Self-Improvement Error Loop** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/). - **Log-Based Deterministic Gates** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/). - **Natural Language Contract Boundaries** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/). - **Context Pruning** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/). - **Thread Warm-Up Low-Latency Pattern** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/). - **Background Daemons** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Self-Aware Code Scripts** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Low Reasoning Iteration** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Context Ceiling Strategy** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Multi-Agent Swarms** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Bespoke Platform Constraints** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Multimodal Quality Assurance Loop** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Semantic Syntax Engineering** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/). - **Context Triad** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/). - **Agent Archetypes** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/). - **Codex Demons** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/). - **Overnight Emulated Crons** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/). - **Natural Language Loose Coupling** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/). - **Natural-Language Contracts** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/). - **Video-as-Requirements** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/). - **Code as a Throwaway Artifact** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/). - **Complexity Management Strategy (State Machine + Module)** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/). - **Living Guardrails (agents.md)** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/). - **The Bifurcated Engineer** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/). Reference ID: foundations-glossary Topic: Context Sources: - [Agent terminology (authorized access required)](https://codex-workshop-followup.pages.dev/glossary.html) --- # Agent-managed memory folders playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already run local dev servers, browser checks, and coding agents against real repos. Agent-managed memory folders give those agents a visible place to plan, track, and resume work without polluting source control or turning scratch notes into stale project documentation. [Core principles](/topics/foundations-visible-agent-memory/) ## Copy-paste workflow **When to use:** At the start of any project where you want agents to keep visible Markdown plans, notes, and goals close to the code without committing them. This creates `.notes/` and `.goals/`, ignores them globally, and opens a live-refreshing Markdown tracker pane. ### Copy-paste prompt ```text You are my coding agent. Set up local agent-managed memory the workshop way, then use it. These are LOCAL working files, not source — keep them boring and close to the repo, and never commit them. 1. Create the memory folders: mkdir -p .notes .goals 2. Ignore them across ALL my repos via a global gitignore: git config --global core.excludesFile ~/.gitignore_global echo '.notes/' >> ~/.gitignore_global echo '.goals/' >> ~/.gitignore_global 3. Write the current plan into .goals/ as Markdown, then open a live-refreshing tracker pane next to the code: cmux markdown open .notes/tracker.md --direction right 4. When you plan, use the numbered-option pattern so I can steer with terse refs: give me a NUMBERED list where each item has options A/B/C and YOUR recommended pick. I will reply with refs like "5B" or "27D" to choose. ``` ### How it works - `mkdir -p .notes .goals` creates the two local memory folders. - `git config --global core.excludesFile ~/.gitignore_global` then appending `.notes/` and `.goals/` keeps them out of every repo by default — they are working files, not source. - `cmux markdown open .notes/tracker.md --direction right` opens the Markdown in a formatted viewer with live file watching (auto-refresh) as a side tracker pane. - The numbered-option planning pattern (each item has A/B/C plus the agent's recommended pick) lets you steer with terse references like `5B`. - Reference: [Git global gitignore (`core.excludesFile`)](https://git-scm.com/docs/gitignore), [CMUX](https://cmux.com/). ## Reusable skill Install as `~/.agents/skills/agent-memory-folders/SKILL.md`, then restart Codex. ````markdown --- name: agent-memory-folders description: Trigger at project start (or when an agent needs visible local working memory) to create .notes/ and .goals/, ignore them via global gitignore, and open a live Markdown tracker. Do NOT use for files meant to be committed. --- # Agent memory folders Provision local agent-managed memory: `.notes/` for working notes and `.goals/` for plans, ignored globally so they never get committed, plus a live Markdown tracker pane. These are LOCAL working files — keep them boring and close to the repo. ## Steps 1. Create the folders: ```bash mkdir -p .notes .goals ``` 2. Ignore them across ALL repos via a global gitignore: ```bash git config --global core.excludesFile ~/.gitignore_global echo '.notes/' >> ~/.gitignore_global echo '.goals/' >> ~/.gitignore_global ``` 3. Write the current plan into `.goals/` as Markdown, then open a live-refreshing tracker pane (auto-refresh via file watching) next to the code: ```bash cmux markdown open .notes/tracker.md --direction right ``` 4. Use the numbered-option planning pattern: present a NUMBERED list where each item has options A/B/C plus your recommended pick, so the human steers with terse refs like `5B` or `27D`. ## Guardrails - These are local working files, NOT source — never commit them. - Keep them boring and close to the repo. ```` ## Scenarios ### Plan and track a risky checkout-flow fix **Role:** As a senior frontend engineer responsible for a Next.js checkout flow A production-like checkout bug only appears after several UI states: shipping form edits, coupon entry, back navigation, and payment-step refresh. The developer wants Codex to plan before touching code, keep progress visible, and leave no agent scratch files in Git. > As a senior frontend engineer, I want the agent to create local memory folders, write a numbered implementation plan, and maintain a live tracker while fixing the checkout flow, so that I can steer the work precisely and review progress without rereading the whole agent transcript. #### Agent brief ```text Set up local agent-managed memory for this repo, then use it for the checkout fix. Run: `mkdir -p .notes .goals`. Configure global ignores without editing this repo's shared `.gitignore`: `git config --global core.excludesFile ~/.gitignore_global`; then ensure `.notes/` and `.goals/` are present in `~/.gitignore_global` without duplicating lines. Inspect the current checkout code before planning; do not trust old notes as source of truth. Write `.goals/checkout-flow-plan.md` as a numbered plan where each major item has options A/B/C and your recommended pick. Open a live tracker with `cmux markdown open .notes/tracker.md --direction right`. Keep `.notes/tracker.md` updated with current step, files inspected, commands run, browser proof status, and remaining risks. After I choose plan refs like `2B` or `5C`, implement only the approved path. Expected output: changed source files only where needed, `.goals/checkout-flow-plan.md`, `.notes/tracker.md`, and a final summary that separates committed-source changes from local scratch artifacts. ``` #### Implementation references [Open reference](/topics/foundations-visible-agent-memory/) [Open reference](/topics/foundations-agent-memory-playbook/) [Open reference](/topics/foundations-agent-memory-playbook/) ```text mkdir -p .notes .goals ``` ```text git config --global core.excludesFile ~/.gitignore_global ``` ```text cmux markdown open .notes/tracker.md --direction right ``` ```text cmux --json tree ``` #### Browser verification Use the running local app, preferably in a CMUX browser pane or browser-agent workflow. Start at the checkout page, take an accessibility snapshot, fill the shipping fields, apply a coupon, navigate back and forward, refresh on the payment step, and capture console output plus a screenshot or short written browser receipt. If using agent-browser-style tooling, use snapshot/click/fill/evaluate steps and write the result into `.notes/tracker.md`. #### Definition of done - `.notes/` and `.goals/` exist locally and are globally ignored, not added to the repo's shared `.gitignore`. - `.goals/checkout-flow-plan.md` contains numbered items with A/B/C options and clear recommended picks. - `.notes/tracker.md` is usable as a live progress receipt and lists the exact files touched, commands run, and browser verification performed. - The checkout flow is verified in the browser with the failing sequence, and the final source diff excludes `.notes/` and `.goals/`. #### Failure modes and mitigations - The agent commits `.notes/` or `.goals/`; mitigate by checking `git status --ignored` and confirming those folders are ignored globally before implementation. - The agent writes a vague prose plan that is hard to steer; mitigate by requiring numbered items with lettered options and waiting for human refs like `3B` before coding. ### Resume a paused redesign without stale memory **Role:** As a product-minded full-stack developer iterating on a dashboard UI A dashboard redesign was started yesterday, but the app has changed since then. The developer wants to resume from local agent notes while forcing the agent to re-check current code and verify the UI in the browser. > As a full-stack developer, I want the agent to read prior local goals but treat the current code and running browser as truth, so that yesterday's plan helps me resume without misleading today's implementation. #### Agent brief ```text Use the agent-memory-folder pattern to resume work safely. First inspect `.goals/` and `.notes/` if they exist, but treat them as local scratch context only. Then inspect the current dashboard files and summarize where the existing notes agree or disagree with the current code. If folders do not exist, create them with `mkdir -p .notes .goals` and ensure `.notes/` and `.goals/` are in the global gitignore via `git config --global core.excludesFile ~/.gitignore_global`. Write `.goals/dashboard-resume-plan.md` with numbered implementation items and A/B/C options. Mark any stale assumptions explicitly. Open or update the live tracker using `cmux markdown open .notes/tracker.md --direction right`. Implement only the approved plan choices. Expected output: a resume plan, a stale-assumption section, a live tracker update, a source diff, and browser evidence from the running dashboard. ``` #### Implementation references [Open reference](/topics/foundations-visible-agent-memory/) [Open reference](/topics/foundations-visible-agent-memory/) [Open reference](/topics/foundations-agent-memory-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ```text cmux markdown open .notes/tracker.md --direction right ``` ```text cmux list-panes ``` ```text cmux read-screen ``` #### Browser verification Open the dashboard in a local browser or CMUX browser pane, compare the current rendered UI against the resumed plan, and record proof in `.notes/tracker.md`: current route, visible dashboard sections, any console errors, and a screenshot or browser-agent accessibility snapshot. Use click/fill/evaluate where the redesign affects interactive filters, tabs, or responsive state. #### Definition of done - The agent explicitly distinguishes prior local notes from current source-of-truth code. - `.goals/dashboard-resume-plan.md` includes a `Stale or revalidated assumptions` section. - The live tracker shows what was resumed, what was discarded, and what was implemented. - Browser verification proves the dashboard still renders and the changed interaction works after the source diff. #### Failure modes and mitigations - The agent blindly follows yesterday's `.goals/` file; mitigate by requiring a current-code inspection and an agreement/disagreement summary before edits. - The live tracker becomes a dumping ground; mitigate by keeping it short: current step, evidence, next action, blockers, and files touched. ### Keep agent planning out of a shared library repo **Role:** As a maintainer of a shared component library used across several web apps Multiple agents are about to investigate a flaky component test and accessibility regression. The maintainer wants reusable local planning files, but the repo is shared by a team and must not gain private scratch folders or noisy `.gitignore` changes. > As a component-library maintainer, I want each agent to write plans and findings into globally ignored local folders, so that exploratory work stays close to the repo but never leaks into the package or team Git history. #### Agent brief ```text Prepare this shared repo for local-only agent planning. Create `.notes/` and `.goals/` with `mkdir -p .notes .goals`. Use the global ignore boundary: `git config --global core.excludesFile ~/.gitignore_global`; ensure `.notes/` and `.goals/` are present there exactly once. Do not edit the repo `.gitignore` unless I explicitly ask. Write `.goals/component-a11y-investigation.md` as a numbered plan with A/B/C options and recommended picks. Use `.notes/tracker.md` to record each agent's assigned area, commands run, and findings. If CMUX is available, open the tracker with `cmux markdown open .notes/tracker.md --direction right`; otherwise leave the Markdown file ready for any preview pane. Expected output: local planning artifacts, no committed scratch files, a concise investigation plan, and a review summary I can use to decide which findings become real tests or source changes. ``` #### Implementation references [Open reference](/topics/foundations-visible-agent-memory/) [Open reference](/topics/foundations-agent-memory-playbook/) [Open reference](/topics/foundations-agent-memory-playbook/) ```text git status --ignored ``` ```text git config --global core.excludesFile ~/.gitignore_global ``` ```text cmux markdown open .notes/tracker.md --direction right ``` #### Browser verification Browser proof is useful only if the component library has a local preview, demo route, or app fixture. If available, run the local preview, inspect the component in a browser, capture an accessibility snapshot or screenshot, and record the result in `.notes/tracker.md`. If there is no browser fixture, use test output and the rendered component documentation as proof instead of inventing a browser check. #### Definition of done - Global Git ignore contains `.notes/` and `.goals/`, and `git status --ignored` confirms the folders are local-only. - The shared repo `.gitignore` is unchanged unless explicitly approved. - `.goals/component-a11y-investigation.md` gives steerable numbered options rather than a single vague recommendation. - `.notes/tracker.md` contains a clean investigation receipt that can be reviewed without committing the scratch files. #### Failure modes and mitigations - The agent treats local memory as team documentation; mitigate by labeling every file in `.notes/` and `.goals/` as local working memory and excluding it from source diffs. - The agent over-invests in permanent tests for unstable UI exploration; mitigate by using the notes to triage first, then promote only stable, valuable checks into real tests. ## Implementation notes - Keep `.notes/` and `.goals/` boring, local, and close to the repo. They are working files for agents, not production docs. - Have the agent inspect current code before implementation. Memory folders help with continuity, but code remains the source of truth when details matter. - Use numbered items with lettered options for plans that need human steering. A reply like `5B` is faster and less error-prone than quoting a paragraph back to the agent. - Use the live Markdown tracker as a status view, not a transcript clone. The useful shape is current task, evidence, commands, files touched, blockers, and next step. - For web app work, pair the tracker with browser evidence: a screenshot, accessibility snapshot, console result, Playwright result, or concise manual browser receipt. - Before finalizing, require a source diff review that excludes `.notes/` and `.goals/`. ## Boundaries and caveats - Do not reintroduce Beads or other third-party memory systems as a taught workflow for this topic. - Do not treat GrillMe as the main workflow here; it was mentioned as occasional follow-up after seeing a drafted plan. - Do not build a complex memory database, RAG system, or automatic commit-synchronized memory layer for this workflow. - Do not add repo-local `.gitignore` changes unless the human explicitly wants that; the taught boundary is global gitignore partitioning. - Do not over-specify browser automation APIs that were not taught. Use practical browser proof shapes: CMUX browser pane, browser-agent snapshot/click/fill/evaluate, Playwright, or a local browser receipt. ## Agent reference map ### Validated lesson 03 references Use this as the ground truth for what was taught: local `.notes/` and `.goals/`, global gitignore partitioning, plan-first grounding, numbered option planning, and live Markdown side panes. [Open reference](/topics/foundations-visible-agent-memory/) ### Existing setup prompt Use this when generating copy-paste setup instructions for a coding agent. [Open reference](/topics/foundations-agent-memory-playbook/) ### Existing Codex skill Use this when implementing or checking the repo-local skill for agent-memory folders. [Open reference](/topics/foundations-agent-memory-playbook/) ### CMUX live Markdown command Use this to open the live-refreshing tracker pane beside the agent session. ```text cmux markdown open .notes/tracker.md --direction right ``` ### Global gitignore setup Use this to keep local agent scratch folders out of every repo without modifying shared `.gitignore` files. ```text git config --global core.excludesFile ~/.gitignore_global ``` ### Verify ignored scratch folders Use this before final review to prove `.notes/` and `.goals/` are not part of the source diff. ```text git status --ignored ``` Reference ID: foundations-agent-memory-playbook Topic: Context Sources: - [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html) --- # Compose the prompt before choosing the agent A cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns. ## Related working material - [Compose the prompt before choosing the agent — prompts and exercises](/topics/factory-prompt-builder-practice/) - [Compose the prompt before choosing the agent — questions and tradeoffs](/topics/factory-prompt-builder-questions/) - [Compose the prompt before choosing the agent — worked example](/topics/factory-prompt-builder-worked-example/) ## TL;DR - `prompt-builder` (alias `p`) is a terminal composer that gives your prompt its own tool: `$` skill lookup, `@` file search, and `Ctrl+R` cross-agent history in front of Pi, Codex, and Claude Code. - You walk away with a compose-first loop: one composer, your own launch targets, and shell functions promoted to launch targets via handoff mode. - The one move: compose in `p`, Tab to `Target ‹name›`, cycle agents with Space — and inspect any launch first with `--dry-run --print-command`. Have your agent set this up — paste this into it: ``` text Fetch https://shiny-bloom-f8hv.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## One composer in front of every agent Count where your prompts get written: for most agent-CLI users, all of them live inside one agent's interactive loop. The prompt — the thing that carries your intent — has no home of its own; switch agents and you abandon your history, paste handling, and muscle memory. prompt-builder is a small Ratatui composer whose only job is composing: skill lookup, file search, slash commands, paste handling, and history that follows *you*, not the agent — it reads Codex's own `~/.codex/history.jsonl` alongside its private file, so prompts from either tool come back with `Ctrl+R`. The agent is just a selector at the bottom of the screen. Targets are named launch profiles — binary, env vars, model, default args — stored in `~/.prompt-builder/targets.toml`; a different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity. ``` text $ prompt-builder target list pi pi bin=pi codex codex bin=codex claude claude bin=claude work-profile codex bin=codex CODEX_HOME=~/.codex-work second-account claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second ``` The test for whether this matters: the next time you re-type a prompt into a second agent because the first one stalled, you've found the cost this tool removes. ## Every launch is inspectable before it runs A tool that launches agents for you earns trust only if you can see exactly what it would run. Every launch path has a dry-run twin: `--print-command` shows the exact argv; `--print-launch-json` emits a stable `schema_version: 1` manifest for scripts. ``` text $ prompt-builder --dry-run --print-command "hello" pi hello $ prompt-builder --dry-run --print-launch-json "hello" { "schema_version": 1, "mode": "pi", "command": "pi", "argv": ["pi", "hello"], "env": {}, "prompt": "hello", "pi": {"cwd": ".", "session_name": null} } ``` Codex and Claude targets launch with permission-bypass flags — only point them at directories where you accept the agent modifying files and running commands (details in the appendix). Before trusting any target you add, run it once with `--dry-run --print-command` and read the argv aloud. ## Handoff mode turns shell functions into launch targets The interesting move is handoff mode: `--handoff-command` with repeatable `--handoff-arg` makes the composer call *any* command with the submitted prompt as the final argv element — passed as data, never through shell eval. ``` text $ prompt-builder --submit --dry-run --handoff-command /bin/echo "hello from handoff" /bin/echo 'hello from handoff' $ prompt-builder --submit --dry-run --handoff-command /bin/echo \ --fork-from last --compact "continue" /bin/echo --fork-from last --compact continue ``` Those `--fork-from`/`--compact` flags render as checkbox toggles in the TUI — the wrapper declares its own UI. Two patterns run daily in the author's shell: `fixit` bakes a debugger persona into the composer, and `p-f` composes a prompt, then forks the latest Codex session and resumes it with that prompt. Here is the workshop's copy of both, complete — this page is the file's source (the repo's `examples/` ships only `fixit.zsh`; lift `p-wrap.zsh` from the block below): ``` text # Wrapping "p" (prompt-builder) with custom tools — the two patterns. # Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh # and the p-f/p-c family in your zsh config. # ── Pattern 1: bake instructions into the composer ───────────────── # The composer opens normally, but the launch carries your persona/context. fixit() { prompt-builder \ --target codex \ -C "$PWD" \ --developer-instructions "You're an expert debugger who always starts with the \$fusion skill. The user will pass a terse bug; investigate the behavior and fix it." } # ── Pattern 2: handoff mode — your shell function IS the launcher ── # prompt-builder composes, then calls your command with the prompt as # the final argv element (Command::arg, no shell eval). _p_handoff_zsh() { local fn="${1:?Usage: _p_handoff_zsh [p-args...]}" shift p \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \ --handoff-arg "$fn" \ "$@" } # Compose a prompt, then fork the latest Codex session and resume with it. p-f() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@" } # Same, but compact the forked session before resuming. p-c() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@" } # ── The mdflow lead-in ────────────────────────────────────────────── # Every wrapper above is: instructions + context + a launch decision. # Declare that in a markdown file instead of a shell function and you # get an mdflow flow — reviewable, diffable, evaluable: # # flows/fixit.codex.md # --- # engine: codex # --- # You're an expert debugger. Bug report: {{ _1 }} # # prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter # for the fuzzy picker; flow `_inputs` render as form fields. ``` To adopt the pattern, write one wrapper for a move you repeat and prove it with `--submit --dry-run --handoff-command /bin/echo` substituted in: your prompt must appear verbatim as the final echoed argument. When it does, swap the real command back in. (`p-f` calls the author's private fork helper — supply your own; see the appendix.) ## A wrapper is a file format waiting to happen Look at what every wrapper above actually is: instructions, plus context, plus a launch decision. Why is that a shell function and not a file? Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. That's mdflow: each repeatable agent job as a markdown file, run on the CLI engine you already use. The `fixit` wrapper restated as a flow looks like this: ``` text --- flows/fixit.codex.md --- engine: codex --- You're an expert debugger. Bug report: {{ _1 }} ``` The same job also ships in a third form: an [agent skill](https://www.skills.sh/). The full progression is `fixit.zsh` (shell wrapper) → `flows/fixit.codex.md` (mdflow flow) → `fixit` (SKILL.md) — pick whichever your stack runs on. The skill twin is hosted on this site; install it by staging anywhere *except* a dir named `skills/` (the skills CLI claims that name as its own symlink target and you'd install an empty skill): ``` text mkdir -p skill-src/fixit curl -fsSL "https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw" -o skill-src/fixit/SKILL.md npx skills add ./skill-src --skill fixit -y ``` The bridge already exists in the composer: with the mdflow CLI on `PATH`, a `Flow ‹name›` selector appears beside the target selector, Enter opens a fuzzy picker, and a flow's inputs render as form fields. A ` ignores prompt` badge warns when a flow never references `{{ _1 }}`/`{{ _prompt }}` — mdflow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. If it keeps changing, it isn't ready — keep it in the shell. ## Appendix ### Limits & caveats - **Permission bypass:** explicit Codex targets launch with `--dangerously-bypass-approvals-and-sandbox`; Claude targets launch with `claude --dangerously-skip-permissions -- `. Pi targets add no bypass flag and rely on Pi's own trust settings. Only use these launchers in directories where you accept the selected agent modifying files and running commands. - The flow file shown in the last story section is a **constructed illustration**, not a file shipped by either project — that's why it carries the "example — don't paste" badge. mdflow's own README shows the same shape (`review.md`, `review.claude.md`, `git diff | explain.md`). - The `fixit` persona references `$fusion`, the author's personal skill. Swap in a skill you actually have, or drop that clause. - `p-f`/`p-c` call `_codex_prompt_builder_fork`, a private helper in the author's zsh config. The wrappers are printed as evidence of the pattern; to use them, point `_p_handoff_zsh` at your own function. - Success-check outputs show `~/.codex-work` for readability; real output expands env paths to your full home directory. Target names `work-profile` and `second-account` are genericized stand-ins for the author's personal profiles. - All output was captured the recorded snapshot from prompt-builder v0.1.0; TUI details may drift in later versions. Claude targets currently ignore conversation names and Codex-only options with a warning; Claude fork/resume orchestration is future work — that's exactly what handoff wrappers cover today. - Claims about mdflow are limited to its README introduction. The "wrappers are proto-flows" promotion rule is the author's editorial inference, not something either README states. - The default target is Pi; real submissions fail without the Pi CLI on `PATH`, though every `--dry-run`/print flag works with no agent CLIs installed. ## Operating practice ### Compose only the evidence the task needs #### What to notice Build a prompt packet from text, files, images, and fresh state without smuggling in an entire stale session. #### Try this List the **minimum sources** needed to decide, act, and verify; remove everything that cannot change one of those steps. > “How can I consolidate that into something that's gonna manage it for me?” John Lindquist · [02:37:56](https://proud-anchor-53zn.here.now/watch.html?t=9476#recording-player) #### Concept Input is a task plus evidence. Output is a result with a named check. The tradeoff is simple: extra context can add capability, but it also hides contradictions and consumes review attention. #### Reflection A large packet is not automatically a complete packet. Prefer relevant, current, and inspectable evidence. **Recording evidence:** listen at 02:34:33. > “I usually spend the most amount of time preparing that initial prompt.” John Lindquist · [02:39:00](https://proud-anchor-53zn.here.now/watch.html?t=9540#recording-player) [Open Prompt Builder](https://shiny-bloom-f8hv.here.now/) #### Links shared for this topic - [Prompt Builder source](https://github.com/johnlindquist/prompt-builder) — The repository for composing text, files, and other evidence into prompts. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=9273#q2-prompt-composer) Reference ID: factory-prompt-builder Topic: Context Sources: - [Compose the prompt before choosing the agent](https://shiny-bloom-f8hv.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q2-prompt-composer) --- # Compose the prompt before choosing the agent — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Prompt-Composing Surface A dedicated intermediate layer detached from an execution engine, designed to optimize layout composition and metadata handling. ### Instant UI Rendering Using compiled low-overhead systems languages (e.g., Rust and Ratatui) to avoid initialization latency during high-frequency developer interactions. ### Unified Skill Auto-completion Normalizing tool call syntax variations across differing third-party agents into a single interactive search component. ### Cross-Model Prompt History A feature built into custom prompt interfaces allowing developers to navigate and search past prompt records regardless of which LLM agent or target model was queried. ### External GUI Editor Synchronization Integrating terminal utilities with modern graphical editors (like Zed or VS Code) requires setting process flags such as --wait via the VISUAL or EDITOR environment variables so the shell pauses execution until the file buffer is saved and closed. ### Agentic Engineering / Responsible Vibe Coding Utilizing AI coding assistants to design and implement software in an unfamiliar language (e.g., Rust) by asking targeted architectural questions about user interfaces, navigation libraries, and potential edge cases instead of letting the AI blindly generate bulk code. ### Zsh Aliases for Agents Creating prefix-driven keyboard macros or functions (e.g., p-) to inject project-specific context, prompt formatting patterns, or session behaviors immediately into a terminal agent session. ### Conversation Forking/Branching Dividing an active, long-running agent chat thread into a new independent thread to explore alternative problem variations without corrupting or cluttering the primary context timeline. ### Conversation Compacting Condensing an extensive agent interaction history into a short summary or structured snapshot before starting a fresh context window to save input tokens and keep responses focused. ### Prompt Builder Context Injection The technique of running help flags for multiple separate command-line utilities within an agent prompt to automatically populate the context window with complete option schemas. ### Cross-CLI Tool Synthesis Enabling an AI agent to compose interoperable wrappers or functions (like a Zsh function combining Claude Code and Prompt Builder) by giving it direct access to each tool's interface definition. ### ZSH Wrapper Functions for AI Tools Writing targeted shell aliases or wrapper commands (e.g., p-pr) that encapsulate multiple specialized flags for AI developer CLI tools, avoiding repetitive typing. ### Markdown Flow Agent Plane Using structured Markdown files as an active orchestration layout for automated agents, as built into the MDFlow ecosystem. ## Questions and answer status ### How well did you know rust in order to build the prompt builder? Or did you just vibe-code it with AI? **Status: answered.** John states he only knew Rust from a few introductory examples and had never written serious Rust before. He describes his approach to 'vibe coding' as a responsible way of asking an agent for library recommendations, keyboard navigation handling, and structural architecture rather than just hoping code randomly appears. ### In Claude code is /branch or /fork **Status: partial.** John mentions that Claude Code has built-in features (like 'by the way') for context isolation, though he does not directly reply to the chat text during the video chunk. ### Please build up a prompt builder that uses Claude code's PR flags and create a ZSH function for it so that I can launch it with P-PR. **Status: partial.** The agent maps the user's local directory and targets layout to build a tailored wrapper script pattern, executing checks up to the shard boundary. ## Exercises - **Try:** Configure custom Zsh prefixes or shorthand command aliases in your .zshrc configuration file to quickly spin up, clone, or clean context threads inside CLI-based AI agents. **Basis:** Transcript time 02:41:48.250 to 02:42:16.570 - **Try:** Open an interactive agent loop or prompt interface, run the help/documentation commands for two independent CLI tools you use frequently, and ask the agent to construct a unified shell function or shortcut that links their features together seamlessly. **Basis:** 02:47:08.000 ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [02:34:33](https://proud-anchor-53zn.here.now/watch.html?t=9273#recording-player) — John discusses the value of building personalized developer tools and workspaces. - [02:35:02](https://proud-anchor-53zn.here.now/watch.html?t=9302#recording-player) — John shares the link to his repository: https://github.com/johnlindquist/prompt-builder. - [02:35:45](https://proud-anchor-53zn.here.now/watch.html?t=9345#recording-player) — The reference document displays a table comparing prompt composing tools including Fabric, bis, aichat, espanso, and promptfoo. - [02:36:05](https://proud-anchor-53zn.here.now/watch.html?t=9365#recording-player) — John inputs the command pi in the terminal to demonstrate its startup delay. - [02:36:10](https://proud-anchor-53zn.here.now/watch.html?t=9370#recording-player) — John terminates the agent and invokes codex to show the initialization speed of the Rust tool. - [02:36:13](https://proud-anchor-53zn.here.now/watch.html?t=9373#recording-player) — John terminates the application and runs claude to demonstrate its Bun-based initialization speed. - [02:36:24](https://proud-anchor-53zn.here.now/watch.html?t=9384#recording-player) — John executes his custom prompt tool, which brings up the prompt-builder TUI instantaneously. - [02:36:50](https://proud-anchor-53zn.here.now/watch.html?t=9410#recording-player) — John types Oracleandhere-now in the Prompt field to demonstrate the active skills auto-completion pop-up menu. - [02:37:05](https://proud-anchor-53zn.here.now/watch.html?t=9425#recording-player) — John shifts focus to the conversation Name input field to illustrate naming sessions up front. - [02:37:30](https://proud-anchor-53zn.here.now/watch.html?t=9450#recording-player) — John interacts with the Target row selection at the bottom to toggle between execution models (pi, codex, claude). - [02:37:40](https://proud-anchor-53zn.here.now/watch.html?t=9460#recording-player) — John opens the flows menu overlay (Enter flows) in the TUI application. - [02:38:01](https://proud-anchor-53zn.here.now/watch.html?t=9481#recording-player) — The shard concludes with John detailing how a central TUI removes the need to remember individual CLI flags and parameters. - [02:38:07](https://proud-anchor-53zn.here.now/watch.html?t=9487#recording-player) — Transcript claim by John Lindquist regarding the purpose of the project allowing prompt history navigation across all models. - [02:38:10](https://proud-anchor-53zn.here.now/watch.html?t=9490#recording-player) — Visual shows John pressing the up arrow to populate the Prompt area with a past command (move to ./images). - [02:38:16](https://proud-anchor-53zn.here.now/watch.html?t=9496#recording-player) — Visual shows the TUI switching to a Search history: mockup overlay after pressing Ctrl+R. - [02:38:36](https://proud-anchor-53zn.here.now/watch.html?t=9516#recording-player) — Visual shows the workspace returning back to the TUI prompt builder, rendering an error label stating -editor: zed returned immediately without changes; GUI editors need a wait flag, e.g. VISUAL="zed --wait";. - [02:38:52](https://proud-anchor-53zn.here.now/watch.html?t=9532#recording-player) — Transcript claim by John explaining that the external text entry failed because the VISUAL environment variable was not configured to await the GUI editor process properly. - [02:39:45](https://proud-anchor-53zn.here.now/watch.html?t=9585#recording-player) — Visual shows John scrolling past tables containing alternative prompt composition tools like Fabric, Bim, espanso, aichat, and promptfoo. - [02:41:14](https://proud-anchor-53zn.here.now/watch.html?t=9674#recording-player) — Transcript claim by John recognizing a participant's phrase and stating "Agentic Engineering is the snobby way of saying it." - [02:41:55](https://proud-anchor-53zn.here.now/watch.html?t=9715#recording-player) — John types p- and presses Tab in the Zsh prompt, showing completion aliases: p-bird, p-bm, p-c, p-cm, p-cx, p-f, p-fl, p-kx, p-zx. - [02:42:33](https://proud-anchor-53zn.here.now/watch.html?t=9753#recording-player) — John runs p-c, opening a terminal prompt composition UI overlay with interactive fields (Name, Prompt, and checkboxes). - [02:44:24](https://proud-anchor-53zn.here.now/watch.html?t=9864#recording-player) — John types which p-zx and p-zx into the terminal prompt to inspect the alias mapping. - [02:44:30](https://proud-anchor-53zn.here.now/watch.html?t=9870#recording-player) — John types p-bird and which p-bird into the terminal. - [02:45:08](https://proud-anchor-53zn.here.now/watch.html?t=9908#recording-player) — John triggers an overlay window containing Name and Prompt fields to compose an agent task. - [02:45:14](https://proud-anchor-53zn.here.now/watch.html?t=9914#recording-player) — John types !claude --help into the Prompt input area. - [02:45:18](https://proud-anchor-53zn.here.now/watch.html?t=9918#recording-player) — The prompt tool executes the inline shell command, logging pi-cmdr loaded: type ! to open the command picker and planning execution. - [02:45:24](https://proud-anchor-53zn.here.now/watch.html?t=9924#recording-player) — The terminal prints the end section of the claude --help output. - [02:45:41](https://proud-anchor-53zn.here.now/watch.html?t=9941#recording-player) — John runs p --help inside the prompt field to feed Prompt Builder's context into the agent session. - [02:46:15](https://proud-anchor-53zn.here.now/watch.html?t=9975#recording-player) — John scrolls up and clicks to expand the previous tool execution blocks to ensure full help menus are loaded in the viewer. - [02:47:08](https://proud-anchor-53zn.here.now/watch.html?t=10028#recording-player) — John submits the task asking the agent to build up a prompt builder that uses Claude code's PR flags and create a ZSH function for it. - [02:47:33](https://proud-anchor-53zn.here.now/watch.html?t=10053#recording-player) — John executes which x (returning exit code 1) and enters a new instruction guiding the agent to ~/.config/zsh. - [02:47:52](https://proud-anchor-53zn.here.now/watch.html?t=10072#recording-player) — The agent restarts with the updated prompt and reports that it is inspecting the external Zsh configuration. - [02:47:55](https://proud-anchor-53zn.here.now/watch.html?t=10075#recording-player) — The agent shares its plan to inspect existing p wrappers and style conventions, mentioning Claude's --from-pr flag. - [02:47:58](https://proud-anchor-53zn.here.now/watch.html?t=10078#recording-player) — The agent runs an automated sequence of commands to inspect ~/.config/zsh and the p target help system. - [02:48:08](https://proud-anchor-53zn.here.now/watch.html?t=10088#recording-player) — The agent inspects local profiles by executing p target list and p target add --help. - [02:48:26](https://proud-anchor-53zn.here.now/watch.html?t=10106#recording-player) — Ghostty terminal window displays prompt-builder tool executing tests for resume wrappers. - [02:48:26](https://proud-anchor-53zn.here.now/watch.html?t=10106#recording-player) — John recommends building personal ZSH functions or scripts to encapsulate tool configurations. - [02:48:35](https://proud-anchor-53zn.here.now/watch.html?t=10115#recording-player) — The prompt builder updates targets.toml adding the claude-pr profile configuration. - [02:48:50](https://proud-anchor-53zn.here.now/watch.html?t=10130#recording-player) — The prompt builder system outputs text showing it has written the ZSH wrapper script to ~/.config/zsh/conf.d/44-ai-claude-pr-dsl.zsh. - [02:50:00](https://proud-anchor-53zn.here.now/watch.html?t=10200#recording-player) — John runs the ghv alias which opens the Chrome browser directly onto the mdflow repository on GitHub. - [02:50:31](https://proud-anchor-53zn.here.now/watch.html?t=10231#recording-player) — John runs the new wrapper command p-pr 24 in his terminal. ### Unresolved: Exact keystrokes or string used to open prompt-builder tool at 02:36:24. The interface switch occurs in a single frame update, hiding any prior input command typed into the shell. **Discriminating evidence:** Consult the user's open-source dotfiles repository or global keybindings. ### Unresolved: The exact configuration variable syntax John intends to append next to resolve the Zed process wait issue. The prompt tool only prints a diagnostic hint on the screen; John describes the bug orally but defers editing his profile configurations or setting the exact variable during the shard. **Discriminating evidence:** Wait for subsequent segments where terminal shell profiles or workspace configuration files are altered. ### Unresolved: Exact definition and logic for all experimental prompt builder shortcuts (p-zx, p-bird, p-bm). John notes that these are experimental or need a 'cleanup pass' and does not successfully run or explain them all. **Discriminating evidence:** Can be verified in subsequent configuration or script walkthrough shards. ### Demonstration detail: 02:36:05 - Tested loading performance for terminal agents pi, codex, and claude inside the mdflow project directory. - Opened custom prompt-builder terminal user interface. - Demonstrated dropdown autocompletion for conversation skill definitions using token syntax. - Interacted with input fields for target applications and workflow options. **Tools observed:** Pi CLI, OpenAI Codex CLI, Claude Code, Prompt Builder TUI. **Command or prompt observations (not a verified recipe):** ```text pi codex claude ``` ### Demonstration detail: 02:38:01 - Demonstrating prompt history by pressing up arrow in custom TUI prompt builder - Searching past prompts using Ctrl+R search history overlay - Launching external Zed editor to write prompt text - Observing process exit error due to lack of zed --wait flag setup - Manually typing placeholder text into the prompt input **Tools observed:** mdflow, Zed editor. ### Demonstration detail: 02:39:36 - Opening Google Chrome browser to view documentation - Navigating from Agentic Software Factory index page to prompt-builder section - Scrolling through prompt-builder CLI usage instructions, installation commands, and targets configuration format **Tools observed:** Google Chrome. **Command or prompt observations (not a verified recipe):** ```text cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked prompt-builder --dry-run --print-command "hello" prompt-builder target list ``` ### Demonstration detail: 02:41:55 - Triggered Zsh autocomplete options via tab on prefix p- - Executed p-c command to launch terminal-based prompt overlay surface - Inspected script path routing via which command calls for p-zx and p-bird **Tools observed:** Ghostty, Zsh, Claude Code. **Command or prompt observations (not a verified recipe):** ```text p-c which p-zx which p-bird ``` ### Demonstration detail: 02:45:08 - Opened task overlay wizard from the command picker tool. - Executed help flags for Claude and Prompt Builder to feed tool descriptions into context. - Authored a prompt to synthesize a hybrid Zsh function named p-pr. - Aborted execution and redirected the agent to search local Zsh files. - Observed automated file exploration and config analysis performed by the agent. **Tools observed:** Ghostty, Prompt Builder CLI, Claude Code. **Command or prompt observations (not a verified recipe):** ```text !claude --help p --help which x p target list ``` ### Demonstration detail: 02:48:26 - Automated generation of ZSH targets and file outputs via the prompt builder engine. **Tools observed:** Ghostty, Prompt Builder CLI. ### Demonstration detail: 02:49:33 - Checking repo via terminal, running the repo browser lookup command, and execution of pull request targeting. **Tools observed:** GitHub CLI, Google Chrome. **Command or prompt observations (not a verified recipe):** ```text ghv p-pr 24 ``` Reference ID: factory-prompt-builder-discussion Topic: Context Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Compose the prompt before choosing the agent — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent. ## Quick start ``` text # needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked alias p=prompt-builder p --dry-run --print-command "hello" # prints the exact launch: pi hello p # open the composer: $ skills · @ files · Ctrl+R history ``` ## Prompt library ### The fixit debugger persona - Agent: Codex, launched through `p --target codex --developer-instructions "…"` - Working directory: the project with the bug - Expected result: the composer opens; whatever terse bug you type launches Codex carrying this persona ``` text You're an expert debugger who always starts with the $fusion skill. The user will pass a terse bug; investigate the behavior and fix it. ``` ### Have your agent write you a handoff wrapper - Agent: any coding agent (Claude Code, Codex, Pi) - Working directory: wherever your shell config lives - Expected result: a new shell function whose launch is proven with the /bin/echo substitution test before anything real runs ``` text Write me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command --handoff-arg passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo "test" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: . ``` ### Add a second-account launch target - Agent: any coding agent with shell access - Working directory: anywhere - Expected result: a new target in `targets.toml` and a printed launch command carrying `CLAUDE_CONFIG_DIR` ``` text Add a prompt-builder launch target for a second Claude Code account: run prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second' and then verify it with prompt-builder --dry-run --target second-account --print-command "hello". Show me the printed command so I can read the exact argv before any real launch. ``` ## Set it up (agent guide) 1. Install the composer and alias it to `p`. Keep `--locked`: the lockfile pins patched `crossterm`/`ratatui` revisions. ``` text cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked echo 'alias p=prompt-builder' >> ~/.zshrc source ~/.zshrc ``` 2. Add one launch target for an agent or account you already switch to by hand. ``` text prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work' ``` This writes `~/.prompt-builder/targets.toml`. On a fresh machine the file now reads exactly: ``` text [[targets]] name = "pi" kind = "pi" [[targets]] name = "codex" kind = "codex" [[targets]] name = "claude" kind = "claude" [[targets]] name = "work-profile" kind = "codex" [targets.env] CODEX_HOME = "~/.codex-work" ``` **Success check:** print the launches without running anything, then list the targets. ``` text prompt-builder --dry-run --print-command "hello" prompt-builder --dry-run --target work-profile --print-command "hello" prompt-builder target list ``` ``` text pi hello CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello pi pi bin=pi codex codex bin=codex claude claude bin=claude work-profile codex bin=codex CODEX_HOME=~/.codex-work ``` In real output the `CODEX_HOME` path appears expanded to your full home directory. Read the second line closely — that bypass flag is the reason dry-run comes first. ## Complete reusable setup contract ## Prompt Builder (p) — agent setup guide Following this file sets up: the `prompt-builder` terminal composer, aliased to `p`, with one custom launch target, verified end-to-end with dry-run flags (no agent is ever launched by these steps). Placeholders used below: `~` = the user's home directory. All other paths are literal. ## Prerequisites Check each before starting: ```bash cargo --version ``` Expected: a Rust toolchain from rustup (the repo pins Rust 1.95.0; any recent stable cargo can build it). If `cargo` is missing, stop and tell your user to install rustup from https://rustup.rs — do not proceed. The Pi, Codex, and Claude Code CLIs are NOT required for these steps: every verification below uses `--dry-run`/print flags, which work with no agent CLIs installed. ## Steps 1. Install the composer from the public repo. Keep `--locked` — the lockfile pins patched `crossterm` and `ratatui` revisions, so unlocked installs may behave differently in the terminal. ```bash cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked ``` This compiles from source and can take a few minutes. 2. Alias the binary to `p`. For zsh: ```bash echo 'alias p=prompt-builder' >> ~/.zshrc ``` For other shells, either add the equivalent alias to that shell's rc file, or use a shell-independent symlink: ```bash ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p ``` 3. Add one launch target (a named launch profile: binary + env vars + default args). This example creates a Codex profile with its own `CODEX_HOME`, i.e. a separate identity: ```bash prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work' ``` On a fresh machine this writes `~/.prompt-builder/targets.toml` with exactly this content: ```toml [[targets]] name = "pi" kind = "pi" [[targets]] name = "codex" kind = "codex" [[targets]] name = "claude" kind = "claude" [[targets]] name = "work-profile" kind = "codex" [targets.env] CODEX_HOME = "~/.codex-work" ``` If the user already has a `targets.toml`, `target add` appends to it instead; existing targets are preserved. ## Success check Run: ```bash prompt-builder --dry-run --print-command "hello" prompt-builder --dry-run --target work-profile --print-command "hello" prompt-builder target list ``` Expected observable result: - Line 1 prints exactly: `pi hello` - Line 2 prints: `CODEX_HOME=/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello` - `target list` shows four targets: `pi`, `codex`, `claude`, `work-profile` (the last with `CODEX_HOME=~/.codex-work`) Report to your user: what you installed, the exact printed launch commands, and — importantly — that the Codex line contains `--dangerously-bypass-approvals-and-sandbox`. Real (non-dry-run) Codex and Claude launches use permission-bypass flags, so `p` should only be pointed at directories where the user accepts the agent modifying files and running commands. ## Notes for agents - If `cargo install` fails on dependency resolution, you probably dropped `--locked`. Re-run with it. - If `target add` fails with a duplicate-name error, the user already has a `work-profile` target; pick another name and adjust the success check to match. - `target add` defaults to `--kind pi` — always pass `--kind` explicitly when creating codex/claude targets. - The default target is Pi. Real submissions (without `--dry-run`) fail if the `pi` CLI is not on `PATH`; that does not affect any step in this file. - The composer's interactive features ($ skills, @ files, Ctrl+R history, Tab to the `Target ‹name›` selector) need a real TTY; don't try to drive the TUI from a non-interactive shell. Verify with the print flags above instead. - Full docs and updates: https://github.com/johnlindquist/prompt-builder (page version of this guide: https://shiny-bloom-f8hv.here.now/) - The guide's `fixit` wrapper also ships as a skills.sh-format agent skill hosted on this site (same job, third form of the wrapper: zsh function → mdflow flow → SKILL.md). Machine-fetch URL: `https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw` (`?raw` required — the bare URL serves an HTML viewer). Install only if your user prefers skills: stage anywhere EXCEPT a dir named `skills/` (the skills CLI claims that name and you'd install an empty skill), e.g. `mkdir -p skill-src/fixit && curl -fsSL "" -o skill-src/fixit/SKILL.md && npx skills add ./skill-src --skill fixit -y`. - Two presentation pages accompany the guide, for humans walking through the section: https://shiny-bloom-f8hv.here.now/replay.html (Session Replay — the annotated transcript of the sessions that set up and wrapped `p`) and https://shiny-bloom-f8hv.here.now/dialogue.html (Socratic Dialogue — attendee questions driving the same material). They contain the same commands plus the complete wrapper file `p-wrap.zsh`, provided by those pages as a liftable code block. Note: that file does NOT exist in the prompt-builder repo — the repo's `examples/` directory ships only `fixit.zsh` — so copy `p-wrap.zsh` from the workshop pages, not from the repo. This file remains the canonical machine copy for setup. Reference ID: factory-prompt-builder-practice Topic: Context Sources: - [Compose the prompt before choosing the agent](https://shiny-bloom-f8hv.here.now/) - [Public setup contract](https://shiny-bloom-f8hv.here.now/agent.md) --- # Compose the prompt before choosing the agent — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The questions, in the order the room asks them I already compose prompts inside Claude Code. Why does the prompt need a separate tool? Because the prompt is the actual work product, and right now it lives inside someone else's REPL. Switch agents and you abandon your history, your paste handling, your muscle memory. `p` decouples them: `$` for skill lookup, `@` for file search, `Ctrl+R` for history that follows *you* — it reads Codex's own `~/.codex/history.jsonl` alongside its private file, so prompts from either tool come back. The agent is just a selector at the bottom of the screen. ``` text # needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked alias p=prompt-builder p --dry-run --print-command "hello" # prints the exact launch: pi hello p # open the composer: $ skills · @ files · Ctrl+R history ``` It launches agents for me. How do I know what it's actually going to run? Every launch path has a dry-run twin. `--print-command` shows the exact argv; `--print-launch-json` emits a stable manifest for scripts. Nothing is hidden behind the TUI: ``` text $ prompt-builder --dry-run --print-command "hello" pi hello $ prompt-builder --dry-run --print-launch-json "hello" { "schema_version": 1, "mode": "pi", "command": "pi", "argv": ["pi", "hello"], "env": {}, "prompt": "hello", "pi": {"cwd": ".", "session_name": null} } ``` Before trusting any target you add, run it once with `--dry-run --print-command` and read the argv aloud. I did read the argv aloud. It says `--dangerously-bypass-approvals-and-sandbox`. Isn't that terrifying? It should give you pause — the flag says so out loud, and this page won't hide it: ``` text $ prompt-builder --dry-run --target work-profile --print-command "hello" CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello ``` Explicit Codex targets launch with that bypass flag; Claude targets launch with `--dangerously-skip-permissions`; Pi targets add no bypass flag and rely on Pi's own trust settings. The rule: only point `p` at directories where you accept the selected agent modifying files and running commands. Dry-run first is not a suggestion — it's the whole trust model. I have a work account and a personal account. Do I need two installs? No — a different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity, and identities are just targets in `~/.prompt-builder/targets.toml`: ``` text prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second' prompt-builder target list ``` ``` text pi pi bin=pi codex codex bin=codex claude claude bin=claude work-profile codex bin=codex CODEX_HOME=~/.codex-work second-account claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second ``` In the composer that's Tab to `Target ‹name›`, Space to cycle. Same prompt, different agent, different account. My launcher isn't an agent at all — it's a zsh function that forks my last Codex session. Can `p` drive that? That's handoff mode, and it's the interesting move of this whole section: `--handoff-command` makes the composer call *any* command with your submitted prompt as the final argv element — passed as data, never through shell eval. Here are the two wrapper patterns that run daily, complete: ``` text # Wrapping "p" (prompt-builder) with custom tools — the two patterns. # Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh # and the p-f/p-c family in your zsh config. # ── Pattern 1: bake instructions into the composer ───────────────── # The composer opens normally, but the launch carries your persona/context. fixit() { prompt-builder \ --target codex \ -C "$PWD" \ --developer-instructions "You're an expert debugger who always starts with the \$fusion skill. The user will pass a terse bug; investigate the behavior and fix it." } # ── Pattern 2: handoff mode — your shell function IS the launcher ── # prompt-builder composes, then calls your command with the prompt as # the final argv element (Command::arg, no shell eval). _p_handoff_zsh() { local fn="${1:?Usage: _p_handoff_zsh [p-args...]}" shift p \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \ --handoff-arg "$fn" \ "$@" } # Compose a prompt, then fork the latest Codex session and resume with it. p-f() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@" } # Same, but compact the forked session before resuming. p-c() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@" } # ── The mdflow lead-in ────────────────────────────────────────────── # Every wrapper above is: instructions + context + a launch decision. # Declare that in a markdown file instead of a shell function and you # get an mdflow flow — reviewable, diffable, evaluable: # # flows/fixit.codex.md # --- # engine: codex # --- # You're an expert debugger. Bug report: {{ _1 }} # # prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter # for the fuzzy picker; flow `_inputs` render as form fields. ``` `p-f` composes a prompt, then forks the latest Codex session and resumes it with that prompt. One caveat, same as the section guide: it calls a private fork helper — point `_p_handoff_zsh` at your own function. How do I write one of those wrappers without wrecking my shell config? You don't hand-write it — you make your agent prove it first with the `/bin/echo` substitution test: your prompt has to appear verbatim as the final echoed argument before any real command gets wired in. This is the prompt to paste into your agent: ``` text Write me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command --handoff-arg passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo "test" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: . ``` Bonus: wrapper flags like `--fork-from` and `--compact` render as checkbox toggles in the TUI — the wrapper declares its own UI. This is turning into a lot of shell functions. Where does it end? Look at what every wrapper actually is: instructions + context + a launch decision. That's a file format begging to exist. Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. The `fixit` wrapper restated as a flow: ``` text --- flows/fixit.codex.md --- engine: codex --- You're an expert debugger. Bug report: {{ _1 }} ``` That's mdflow, and the bridge already exists in the composer: with the mdflow CLI on `PATH`, a `Flow ‹name›` selector appears beside the target selector, and a flow's inputs render as form fields — with a ` ignores prompt` badge if the flow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. That's the next section. Reference ID: factory-prompt-builder-questions Topic: Context Sources: - [Compose the prompt before choosing the agent — questions and tradeoffs](https://shiny-bloom-f8hv.here.now/dialogue.html) --- # Compose the prompt before choosing the agent — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## Part 1 — Compose first, inspect every launch You Install prompt-builder and alias it to `p`. Before it launches anything real, show me exactly what it would run. Agent Installed from the public repo — `--locked` matters, the lockfile pins patched `crossterm`/`ratatui` revisions — then asked for the launch without running it: ``` text cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked alias p=prompt-builder prompt-builder --dry-run --print-command "hello" ``` ``` text pi hello ``` The first beat of every session with this tool: `--dry-run --print-command`. Nothing is hidden behind the TUI — the exact argv is printable before anything runs. You I keep a second Codex identity by exporting `CODEX_HOME` by hand every time. Make it a launch target. Agent One command; it appends to the targets file and preserves whatever is already there: ``` text prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work' ``` On a fresh machine `~/.prompt-builder/targets.toml` now reads exactly: ``` text [[targets]] name = "pi" kind = "pi" [[targets]] name = "codex" kind = "codex" [[targets]] name = "claude" kind = "claude" [[targets]] name = "work-profile" kind = "codex" [targets.env] CODEX_HOME = "~/.codex-work" ``` A target is a named launch profile — binary + env + default args. A different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity; in the TUI it's just Tab to `Target ‹name›`, Space to cycle. You And what would that target actually launch? Agent ``` text prompt-builder --dry-run --target work-profile --print-command "hello" ``` ``` text CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello ``` Read that line closely: explicit Codex targets launch with a permission-bypass flag. That is the reason dry-run comes first. The safety beat, verbatim from the session: only point `p` at directories where you accept the selected agent modifying files and running commands. In real output the env path expands to your full home directory. You I script against my tools. Give me the launch as data, not a string. Agent ``` text prompt-builder --dry-run --print-launch-json "hello" ``` ``` text { "schema_version": 1, "mode": "pi", "command": "pi", "argv": ["pi", "hello"], "env": {}, "prompt": "hello", "pi": {"cwd": ".", "session_name": null} } ``` A stable `schema_version: 1` manifest — the same launch the TUI would perform, consumable by scripts. This is what "the composer is inspectable" means in practice. ## Part 2 — Handoff: your shell functions become launch targets You Composer-to-agent is fine. But my daily move is a shell function — fork my latest Codex session and resume it. Can `p` hand the composed prompt to *any* command? Agent That's handoff mode. Proof with `/bin/echo` substituted in as the "launcher": ``` text prompt-builder --submit --dry-run --handoff-command /bin/echo "hello from handoff" ``` ``` text /bin/echo 'hello from handoff' ``` The substitution proof: the composed prompt appears verbatim as the final argv element — passed as data (`Command::arg`), never through shell eval. Run this before wiring in any real command. You My fork helper takes flags — `--fork-from`, `--compact`. Do those survive? Agent ``` text prompt-builder --submit --dry-run --handoff-command /bin/echo --fork-from last --compact "continue" ``` ``` text /bin/echo --fork-from last --compact continue ``` They pass through — and in the interactive TUI they render as checkbox toggles. The wrapper declares its own UI: `--fork-from` / `--compact` / `--launch-option` become toggles in the composer. Your function's flags are now form controls. You Now wrap it for real: bake my debugger persona into one function, and make another that composes a prompt, forks my latest Codex session, and resumes with it. Agent Both patterns landed in one file — pattern 1 bakes instructions into the composer; pattern 2 makes your shell function the launcher: ``` text # Wrapping "p" (prompt-builder) with custom tools — the two patterns. # Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh # and the p-f/p-c family in your zsh config. # ── Pattern 1: bake instructions into the composer ───────────────── # The composer opens normally, but the launch carries your persona/context. fixit() { prompt-builder \ --target codex \ -C "$PWD" \ --developer-instructions "You're an expert debugger who always starts with the \$fusion skill. The user will pass a terse bug; investigate the behavior and fix it." } # ── Pattern 2: handoff mode — your shell function IS the launcher ── # prompt-builder composes, then calls your command with the prompt as # the final argv element (Command::arg, no shell eval). _p_handoff_zsh() { local fn="${1:?Usage: _p_handoff_zsh [p-args...]}" shift p \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \ --handoff-arg "$fn" \ "$@" } # Compose a prompt, then fork the latest Codex session and resume with it. p-f() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@" } # Same, but compact the forked session before resuming. p-c() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@" } # ── The mdflow lead-in ────────────────────────────────────────────── # Every wrapper above is: instructions + context + a launch decision. # Declare that in a markdown file instead of a shell function and you # get an mdflow flow — reviewable, diffable, evaluable: # # flows/fixit.codex.md # --- # engine: codex # --- # You're an expert debugger. Bug report: {{ _1 }} # # prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter # for the fuzzy picker; flow `_inputs` render as form fields. ``` File landed. `fixit` runs daily; `p-f` is compose → fork → resume in one keystroke family. Read the tail of that file again: every wrapper is instructions + context + a launch decision. Declare that in a markdown file instead of a shell function and you've invented mdflow — which is exactly where section 05 picks up. (`p-f` calls a private fork helper — supply your own; the pattern is the point.) Reference ID: factory-prompt-builder-worked-example Topic: Context Sources: - [Compose the prompt before choosing the agent — worked example](https://shiny-bloom-f8hv.here.now/replay.html) --- # Context packing with Oracle and PackX: practical reference ## Agent Setup Prompt ```text Set up the oracle-packx skill, PackX bundle flow, Oracle browser runtime, MCP entrypoints, optional remote browser route, and local verification surfaces for this workspace. 1. Resolve the oracle-packx skill. Check `skills/oracle-packx/SKILL.md` first, then `~/.agents/skills/oracle-packx/SKILL.md`. Confirm the PackX references exist under `skills/oracle-packx/references/` or the matching installed skill path. Read the skill before changing config. If the skill is missing, report the missing path and the smallest install or copy step needed; do not invent skill content. 2. Verify PackX availability. Run `command -v packx || npx packx --help`. Confirm a preview command is available before building anything. Do not create a broad bundle during setup. 3. Verify Oracle entrypoints. Run `command -v oracle oracle-mcp` and report both results. If either command is missing, inspect `~/dev/oracle/docs/configuration.md`, `~/dev/oracle/docs/mcp.md`, `~/dev/oracle/docs/browser-mode.md`, and `~/dev/oracle/docs/bridge.md` if present, then report the exact missing install or PATH step. 4. Prepare local artifact directories. Confirm `~/.oracle/`, `~/.oracle/bundles/`, and `~/.oracle/sessions/` exist. Create only missing directories. Do not delete, overwrite, or rename existing sessions or bundles. 5. Configure Oracle for deliberate browser mode. Inspect `~/.oracle/config.json` if it exists, preserving existing private values. Ensure this workflow resolves to `engine: "browser"`, with browser thinking set to extended, model label set to Latest, browser attachments set to always, browser file bundling enabled, and `maxFileSizeBytes` set to a reasonable upload guardrail such as `10485760`. Do not clobber unrelated config. 6. Verify MCP/browser request fields. Confirm a setup run would pass or resolve these values: `engine: "browser"`, `browserThinkingTime: "extended"`, `browserModelLabel: "Latest"`, `browserAttachments: "always"`, and `browserBundleFiles: true`. Flag any condition where Oracle would fall back to API mode. 7. Optional remote browser route. If remote browser routing is intended, verify the config shape without exposing values: `browser.remoteHost` should look like a Tailscale host and port, `browser.remoteToken` should be present but redacted, and `browser.remoteChrome.host` plus `browser.remoteChrome.port` should point at the remote Chrome debug bridge from the remote server's perspective. If no remote route is configured, report it as skipped. 8. Enforce privacy boundaries. Never print or bundle tokens, cookies, API keys, private endpoints, raw `env` output, full private config, huge logs, generated output, `node_modules/`, `.git/`, build output, coverage output, or unrelated product areas. Confirm `CLAUDE.md` is excluded from Oracle PackX bundles. Use compact redacted notes when evidence is useful but unsafe or too large. 9. Verify the PackX context flow with a tiny dry run. From a safe local project path, run a preview against a narrow path or harmless file set using the skill's PackX reference. Report file count, token count if available, and whether the scope would produce a non-empty bundle. Do not upload files to Oracle during this preview. 10. Verify bundle and session surfaces. Using a short setup slug, confirm a bundle path like `~/.oracle/bundles/{slug}.txt` can be written and is non-empty if you build a tiny safe bundle. Confirm a session directory path like `~/.oracle/sessions/{slug}/` can exist, and that the expected post-run output file is `~/.oracle/sessions/{slug}/output.log`. 11. If a live browser Oracle smoke test is safe and explicitly allowed by the local environment, run only a minimal browser-mode check with harmless content. Otherwise stop before sending anything and report the remaining manual check: signed-in browser availability, remote host reachability if used, and expected `output.log` location. 12. Report the setup result plainly: skill path resolved, PackX status, Oracle CLI status, Oracle MCP status, directories present or created, browser-mode config status, resolved engine, remote route configured or skipped, preview result, bundle/session surface status, verification commands run, files created or changed, and anything still unproven. Redact all secrets and do not paste full config. ``` ## Big Idea Phase: Context And Environment - make the software question, project boundary, and model runtime explicit before deeper work begins. Use the `oracle-packx` skill when a software question needs more context than a normal chat turn can hold, or when the answer should come from a stronger browser-backed model with a deliberate context packet. ## Try This Now Pick one risky software question, such as "Why can this billing webhook double-process an invoice?" Write one sentence for each boundary: - in scope: likely source files, tests, logs, docs, screenshots, or prior notes - out of scope: generated output, secrets, unrelated product areas, broad history - useful answer: plan, bug theory, file-level review, first slice, or verification target Ask: ```text Use the oracle-packx skill. Build a bounded PackX bundle before recommending a fix. Use Oracle through browser mode. Read the full Oracle output from the local session log before turning it into project work. ``` ## Skill Reference The repeatable workflow lives in the bundled skill: ```text skills/oracle-packx/SKILL.md ``` Supporting references: ```text skills/oracle-packx/references/packx-quick-reference.md skills/oracle-packx/references/packx-deep-reference.md ``` A common local install path is: ```text ~/.agents/skills/oracle-packx/SKILL.md ``` Oracle project reference: ```text https://github.com/johnlindquist/oracle ``` PackX package and reference: ```text https://www.npmjs.com/package/packx https://github.com/johnlindquist/pack#readme ``` ## When To Reach For This Use `oracle-packx` when you are asking for: - architecture review across several files or packages - an implementation plan for a feature with real source context - cross-file debugging where the failure path spans source, tests, logs, and config - a second opinion before touching a risky subsystem - review of a failed implementation after you have logs or test output - a broad code review where local inspection alone is not enough - a browser-backed Oracle run that should use a signed-in ChatGPT/Gemini session instead of a normal API call Skip it when: - `rg` can answer the question - one test failure points at one obvious file - you already know the exact edit - the task is small enough for a normal Codex turn ## How This Used To Work What you used to expect: ```text Paste a broad prompt and trust the model to infer the right files. ``` What this workflow gives you now: ```text Give oracle-packx a specific software question. It builds a bounded context packet first, then Oracle reasons over the code, docs, logs, and evidence that actually matter. ``` ## Mental Model There are three pieces: | Piece | Job | | --- | --- | | `oracle-packx` | Workflow wrapper: choose scope, preview PackX, build the bundle, call Oracle, read the result, apply it locally | | PackX | Context bundler: collect, filter, count, and write source context into an LLM-friendly packet | | Oracle | Model runner: CLI/MCP tool that can use API mode or browser mode, then save session output locally | Do not blur those together. PackX prepares the context. Oracle reasons over it. The agent still owns local edits and verification. ## Oracle Runtime Setup Oracle can run from the CLI or from the MCP tool. Common entrypoints: ```text oracle oracle-mcp ``` The project includes browser-mode code, MCP tools, remote-browser routing, session storage, and launch helpers. Useful project files to inspect: ```text ~/dev/oracle/docs/browser-mode.md ~/dev/oracle/docs/configuration.md ~/dev/oracle/docs/mcp.md ~/dev/oracle/docs/bridge.md ~/dev/oracle/src/mcp/server.ts ~/dev/oracle/src/mcp/tools/consult.ts ~/dev/oracle/src/mcp/tools/sessions.ts ~/dev/oracle/src/mcp/tools/sessionResources.ts ~/dev/oracle/src/config.ts ~/dev/oracle/src/remote/client.ts ~/dev/oracle/src/remote/server.ts ~/dev/oracle/src/browser/index.ts ~/dev/oracle/scripts/oracle-serve-launchagent.sh ``` Oracle session output is saved under: ```text ~/.oracle/sessions/{slug}/ ``` For `oracle-packx`, the main file to read after the run is normally: ```text ~/.oracle/sessions/{slug}/output.log ``` ## Browser Mode Browser mode sends the request through an automated signed-in browser session instead of the normal API path. Use it when the answer should come from ChatGPT/Gemini web capabilities, attached files, a visible remote browser, or a browser-only model surface. Critical MCP fields: ```text engine: "browser" browserThinkingTime: "extended" browserModelLabel: "Latest" ``` Why `engine: "browser"` matters: - Oracle can choose a default engine from config. - If API credentials exist, API mode may be available. - A deliberate browser run should not accidentally become an API run. Browser attachment controls: ```text browserAttachments: "always" browserBundleFiles: true ``` Use `browserAttachments: "always"` when files must be uploaded through the browser UI. Use bundling when many files should travel as one uploaded context artifact. ## Remote Oracle Browser Path A common remote setup uses a Tailscale-reachable Oracle browser host. This lets the local agent send the job while the remote machine drives an already signed-in browser session, often visible on a TV or second display. The path looks like this: ```text local Codex / agent -> Oracle MCP consult or oracle CLI -> browser engine -> browser.remoteHost over Tailscale -> remote oracle serve process -> remoteChrome on the remote host -> signed-in ChatGPT/Gemini browser -> local ~/.oracle/sessions/{slug}/ output ``` Redacted config shape: ```json { "engine": "browser", "browser": { "remoteHost": "100.x.y.z:7333", "remoteToken": "", "remoteChrome": { "host": "127.0.0.1", "port": 55894 } }, "maxFileSizeBytes": 10485760 } ``` What each field means: | Field | Meaning | | --- | --- | | `engine` | Default Oracle runtime mode | | `browser.remoteHost` | Tailscale-reachable Oracle remote server | | `browser.remoteToken` | Bearer-style token required by the remote server | | `browser.remoteChrome.host` | Chrome debugging host from the remote server's point of view | | `browser.remoteChrome.port` | Chrome debugging port on the remote machine | | `maxFileSizeBytes` | Local upload guardrail for files sent to browser mode | The token is private. Do not paste it into prompts, bundles, pages, logs, or screenshots. ## Ask The Agent This General review: ```text Use the oracle-packx skill. Review the auth/session architecture before we add refresh-token rotation. Build a focused PackX bundle from the auth package, session storage code, middleware, relevant tests, and existing ADRs. Exclude secrets, generated output, node_modules, and unrelated product areas. Ask Oracle through browser mode for risks, a migration plan, file-level changes, verification checks, rollback notes, and the first shippable slice. Read the full Oracle session output before editing local files. ``` Debugging: ```text Use the oracle-packx skill. The billing webhook intermittently double-processes an invoice. Bundle the webhook handler, idempotency code, tests, payment-provider docs, and the latest failure log. Ask Oracle through browser mode to identify likely causes, missing invariants, and the smallest local check that would confirm the fix. ``` Remote browser setup check: ```text Use the oracle-packx skill. Inspect the local Oracle config and explain whether browser mode will route to a remote Tailscale Oracle host. Redact tokens and private host details. Confirm the engine choice, remoteHost shape, remoteChrome target, file-size guardrail, and where the session output will be saved. ``` Keep the bundle tight: ```text Use the oracle-packx skill. Start with a PackX preview. If the bundle is too broad, narrow by package, entrypoint, git diff, or relevant search terms before consulting Oracle. Do not send secrets, generated files, private env output, or raw huge logs. ``` ## What The Skill Does The `oracle-packx` skill runs this pipeline: 1. Choose a short slug. 2. Preview the PackX bundle before building it. 3. Build a rich bundle, often targeting up to `900k` tokens for broad review. 4. Confirm the bundle exists and is non-empty. 5. Add compact evidence when raw logs or sessions are too large or unsafe. 6. Send the bundle to Oracle through browser mode only. 7. Use ChatGPT Pro Extended or equivalent browser thinking controls. 8. Wait for Oracle instead of doing parallel local work. 9. Read the full answer from `~/.oracle/sessions/{slug}/output.log`. 10. Turn Oracle's answer into local implementation work. 11. Write local plans, notes, code, or verification logs with local tools. ## What PackX Is Doing PackX discovers files, applies ignore rules, filters by path/content/git state, optionally strips comments or minifies, counts tokens, and writes an LLM-friendly bundle. Common PackX capabilities used by the skill: | Capability | What It Means | | --- | --- | | `--preview` | Dry run before building the bundle | | `--limit 900k` | Rich bundle target for broad Oracle review | | `-x` / `--exclude` | Leave out noise or unsafe files | | `-i` / `--include` | Include specific path/glob patterns | | `-s` / `--strings` | Find files containing relevant text | | `--diff` / `--dirty` / `--staged` | Focus on changed files | | `--follow-imports` | Start from an entrypoint and include local imports | | `--skeleton` | Send API/interface shape without full bodies | | `--strip-comments --minify` | Fit large projects into the bundle | | `-f markdown --no-interactive --stdout` | Scriptable output shape for Oracle | Use these flags conceptually. The exact combinations live in the skill and quick reference. ## What To Exclude The skill explicitly excludes `CLAUDE.md` from Oracle PackX bundles. Why: - it may contain tool-specific or agent-specific instructions - it can confuse the Oracle review with instruction noise - repo guidance should be deliberately scoped Prefer a scoped `AGENTS.md`, project README, ADR, or short local summary when instructions are needed. Also keep these out unless there is a deliberate reason: ```text node_modules/ .git/ dist/ build/ .next/ coverage/ *.log lockfiles raw env output tokens cookies private endpoints ``` Logs can still be included intentionally when they are small and directly relevant. Large logs should usually become compact evidence. ## Compact Evidence Use compact evidence when the raw material is useful but too noisy, too large, or unsafe to bundle directly. Examples: - a giant failure log - previous session history - screenshot observations - browser trace summary - CI output with many unrelated lines - a redacted production incident note - redacted Oracle config details - a failed PackX preview that proved the first scope was too broad Shape: ```markdown # Compact Evidence Supplement ## Useful Facts - fact: - source path: - why it matters: ## Raw Context Intentionally Omitted - path: - omitted because: ## Current Narrowing - next slice: - out of scope: - how to confirm: ``` ## How To Know It Worked After the skill runs, look for: - a non-empty bundle at `~/.oracle/bundles/{slug}.txt` - an Oracle session at `~/.oracle/sessions/{slug}/` - a full session output file, normally `output.log` - browser mode noted in the run, not accidental API mode - remote-browser routing redacted when config is discussed - exact file/function/test targets in the plan - risks and assumptions called out explicitly - a first shippable slice, not just a broad roadmap - local files written by the agent, not downloadable files created by Oracle ## If It Goes Wrong | Symptom | Likely Cause | What To Do | | --- | --- | --- | | Oracle used API mode | `engine: "browser"` was omitted or config default changed | Re-run with explicit browser engine | | Browser did not open | Browser automation or remote host is unavailable | Check local Oracle config and browser-mode docs | | Remote host unreachable | Tailscale, host, port, or remote server is down | Confirm the `100.x.y.z:port` route and remote `oracle serve` process | | Token rejected | Remote token mismatch | Rotate or fix the token outside the bundle and prompt | | Remote Chrome unavailable | Debug port or Chrome session is not running on the remote host | Restart the remote Chrome/debug bridge or launch helper | | File upload rejected | Bundle or attachment exceeded guardrails | Narrow PackX scope, use compact evidence, or bundle fewer files | | Bundle is huge | Scope was too broad | Preview again with tighter includes, excludes, strings, diff, or entrypoints | | Bundle is empty | Include patterns missed the actual files | Run `rg`, inspect paths, and rebuild | | Oracle answer is vague | Context packet lacked logs, tests, or target question | Add compact evidence and ask for a falsifiable first check | | Sensitive data appears | Secrets or raw env output slipped in | Stop, remove the bundle, rebuild with redaction | ## Follow-Up Rules Oracle's answer is input, not the finished work. After reading it: - restate the useful recommendation in local project terms - identify the first file or test to touch - keep unrelated refactors out - run the smallest meaningful verification - save what changed and what remains unproven - use another PackX/Oracle pass only after forward progress or new evidence When returning to Oracle, include the delta: ```text - prior_oracle_session: - last_oracle_recommendation: - implemented_since_prior_oracle: - verified_since_prior_oracle: - failed_check_or_blocker: - narrowing_decision: - files_functions_now_in_scope: - files_functions_out_of_scope: - next_falsifiable_verification: ``` ## References And Resources ```text skills/oracle-packx/SKILL.md skills/oracle-packx/references/packx-quick-reference.md skills/oracle-packx/references/packx-deep-reference.md ~/dev/oracle/docs/browser-mode.md ~/dev/oracle/docs/configuration.md ~/dev/oracle/docs/mcp.md ~/dev/oracle/docs/bridge.md ~/.oracle/config.json ~/.oracle/bundles/{slug}.txt ~/.oracle/sessions/{slug}/output.log ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-context-packing-reference Topic: Context Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Context packing with Oracle and PackX: practice drills These exercises practice asking for the `oracle-packx` skill clearly. They do not require team members to memorize PackX or Oracle command syntax. ## Exercise 1: Write A Skill Invocation Pick a real software project, feature, or bug. Write a prompt that starts with: ```text Use the oracle-packx skill. ``` Include: - desired software outcome - feature/module/subsystem in scope - source paths that probably matter - tests or logs that probably matter - docs or provider references that probably matter - files or areas to exclude - how you will know the answer is useful Template: ```text Use the oracle-packx skill. I want to: Relevant code is probably in: Relevant tests/logs/docs are probably: Exclude: Ask Oracle for: I will know this worked if: ``` ## Exercise 2: Identify Evidence For the same project, list what should go into the context packet. ```markdown # Evidence Map ## Source - path: - why it matters: ## Tests - path: - why it matters: ## Logs Or Failures - path: - why it matters: ## Docs Or External Contracts - path or URL: - why it matters: ## Out Of Scope - path/topic: - why excluded: ``` ## Exercise 3: Decide What Should Be Compact Evidence Some material is useful but should not be packed raw. Mark each item as `pack raw`, `summarize`, or `exclude`: ```markdown # Compact Evidence Decisions - 30,000-line CI log: - screenshot of broken UI: - `.env.local`: - payment provider API docs: - one failing test output: - previous Oracle output: - entire session history: - generated build directory: ``` ## Exercise 4: Review A Bad Prompt Bad: ```text Use Oracle to review my repo and tell me what to do. ``` Rewrite it so the `oracle-packx` skill has enough direction: ```text Use the oracle-packx skill. ... ``` Make sure your rewrite includes: - exact project area - expected outcome - likely evidence - exclusions - what Oracle should return - how local work will be confirmed ## Exercise 5: Plan A Follow-Up Oracle Call A second Oracle call should not repeat the same broad question. Fill this out before asking again: ```text Prior-State Ledger: - prior_oracle_session: - last_oracle_recommendation: - implemented_since_prior_oracle: - verified_since_prior_oracle: - failed_proof_or_blocker: - narrowing_decision: - files_functions_now_in_scope: - files_functions_out_of_scope: - next_falsifiable_verification: - forward_progress_index: ``` Decide which condition is true: ```text implemented: verified: blocked: narrowed: ``` If none are true, do local work before another Oracle run. ## Exercise 6: Inspect The Skill Open: ```text skills/oracle-packx/SKILL.md ``` Find the sections that define: - runtime mode - PackX pipeline - compact evidence - `output.log` - follow-up call requirements - completion checklist Write one sentence about what each section protects you from. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-context-packing-practice Topic: Context Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Goal, Memory, and Context Hygiene Field Guide > Original source pages and recordings require authorized access. The full article text here is public. Keep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints. Use this when /goal work burns tokens, drifts, or cannot converge because context is not being externalized. ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | .goals/ | Durable objective and checkpoints | Long-running work | .goals/.md | | .notes/ | Receipts and scratch state | Verification, logs, decisions | .notes// | | Grill-me | Clarify before a big goal | Ambiguous or risky scope | .notes//questions.md | | Compact summaries | Keep Codex in the useful zone | Large sessions and repeated loops | .notes//handoff.md | ## Agent-ready prompt ```text Before starting this goal, externalize state. Create .goals/.md with objective, constraints, stop condition, and verification. Create .notes// for receipts. Every major phase must write a checkpoint: research, plan, implementation, verification, final diff review. If context gets large, compact to .notes//handoff.md and resume from that artifact. ``` ## Applied stories ### Goal that will not converge **Role:** Solo developer Codex keeps exploring alternatives and never ships. **Agent brief:** Narrow to one shippable slice, write explicit stop condition, and require a verification receipt before continuing. **Done when:** - goal file - single next slice - verification command - final receipt ### Memory drift cleanup **Role:** Repo maintainer Agent memory says old commands are true, but package scripts changed. **Agent brief:** Audit memories against package.json/CI, write corrections to local notes, and update durable instructions only after verification. **Done when:** - memory audit - verified commands - updated AGENTS.md or skill - stale facts removed ## Tips and gotchas - Use local markdown as the durable memory for a task; do not rely on hidden conversational state. - Ask for numbered options with a recommended pick when you need to steer quickly. - Treat /goal as research + plan + implement + verify in one bounded loop, not infinite autoresearch. - Use compact summaries when receipts are better than raw chat history. ## References - [Grill Me skill](https://www.aihero.dev/skills-grill-me) - [Beads](https://github.com/gastownhall/beads) - [Caveman](https://github.com/JuliusBrussee/caveman) ## Related principles - [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) - [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) - [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/) Reference ID: foundations-goal-memory-field-guide Topic: Context Sources: - [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html) - [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html) - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Images as precise task evidence Use a marked screenshot to identify the target, a sentence to express intent, and a running-app check to prove the change. ## Related working material - [Images as precise task evidence — prompts and exercises](/topics/factory-image-prompts-practice/) - [Images as precise task evidence — questions and tradeoffs](/topics/factory-image-prompts-questions/) - [Images as precise task evidence — worked example](/topics/factory-image-prompts-worked-example/) ## TL;DR - A capture→annotate→drop workflow: CleanShot hotkey, one fat red arrow, drag the image straight into the agent prompt. - You walk away with five copy-paste prompt shapes — including the two real prompts where a screenshot plus one sentence drove a bug fix all the way to a pull request. - The one move: when a prompt sentence starts describing a screen location ("the row near the bottom…"), stop typing and hit the capture hotkey instead. Have your agent adopt this — paste this into it: ``` text Fetch https://amber-willow-n64j.here.now/agent.md?raw and follow it to set up the screenshot-reading protocol in my current project. Run the success check at the end and show me the result. ``` ## Why one arrow beats a paragraph Say your app's launcher sometimes moves focus to the wrong row while you type. Describe that in words alone — "when I type in the menu, the selection sometimes jumps down to another item" — and the agent must guess: which menu? which item? at what moment? A real session skipped the guessing: the entire bug report was the annotated screenshot in card 1 plus one sentence, and the session chained investigation, an external model consult, the fix, live verification in the running app, a commit, and a pull request. The division of labor is simple. The arrow answers "which element?" The sentence answers "what do you want done?" Neither carries the other's job well: an arrow cannot express intent; a sentence cannot point. CleanShot's text tool collapses the two when that helps — card 3's capture carries the full design feedback as a red callout typed on the image, so the prompt shrinks to "do what the annotation says." Weak version of the move: three arrows, two boxes, and a highlight on one screenshot — the agent now has five candidate subjects. Strong version: one fat arrow per idea. Two ideas, two screenshots. Crop tight. ## How agents ingest the drop Different CLIs render a dropped image differently, but all of them get the pixels. Claude Code shows an inline `[Image #1]` marker. The Codex CLI rewrites a dragged file into a header: ``` text # Files mentioned by the user: ## capture.png: $HOME/screenshots/capture.png ``` The difference only matters when you script prompts; drag-and-drop hides it. And the image is data, not decoration — one session opened with just a file path plus "It is a 1612×1084 RGBA PNG. The visible symptom is…" and the agent read the actual pixels. ## What good captures look like Across a reviewed week of ~45 captures, the annotated ones share one pattern: a single fat red arrow aimed at the one element the prompt is about — an input field, a status widget, an answer sentence. Almost never boxes or long callouts. ![A Quick AI chat panel answering a World Cup schedule question, with a red arrow pointing at the empty 'Follow up…' input field at the top.](https://amber-willow-n64j.here.now/images/arrow-quick-ai-input.png) The arrow singles out the follow-up input the prompt discussed, ignoring everything else on screen. ![A terminal running Claude Code inside a coding project. A red arrow points at two small pill-shaped 'now' widgets floating in the center of an otherwise empty pane.](https://amber-willow-n64j.here.now/images/arrow-claude-code-pills.png) Applied to the agent's own UI: the arrow isolates two tiny status pills inside a busy terminal session. ![A Quick AI panel showing eight web_search tool calls and an answer that begins 'I can't reliably pull today's latest news headlines from live sources right now'. A red arrow points at the answer text.](https://amber-willow-n64j.here.now/images/arrow-web-search-answer.png) Feedback aimed at agent behavior itself: the arrow marks the answer sentence under discussion, so the follow-up prompt can be one line. Judge success by the agent's first reply: it should name your arrow's target unprompted. If it misidentifies the target, don't add prose — crop tighter, keep one arrow, resend. Capture the *failure state*, not the app in general. ## Check what leaves your machine Screenshots leak. The same week of captures that produced the five images on this page also contained personal message threads, a contact list with real names, a member directory, and personal photos — the same hotkey captured them all, and all of them were excluded here. An agent prompt is already a disclosure: everything visible in the frame — window titles, file paths, browser tabs, notification banners — goes to whatever service runs the model. Review the whole frame before you press send, and again, more strictly, before anything gets published. If a capture shows another person's data, re-take it rather than blurring it. ## Appendix ### Limits & caveats - The two real sessions are single successful runs, not controlled comparisons. No prose-only version of the same bug report was tried, so "the arrow made the difference" is a reasoned inference from the prompt's brevity, not a measurement. - The "first reply names the arrow's target" success test is an editorial rule of thumb, not something the sources measured. - The real prompts in cards 1–2 invoke the author's local slash commands (`/goal`, `/oracle-packx`, `/web-choices`) and card 5 uses a local `$image_gen` command — you won't have these. The portable versions remove them; that light generalization is the only edit. - The quick start and helper script assume macOS (CleanShot, `pbcopy`) and a capture folder at `~/screenshots`; set `CLEANSHOT_DIR` if CleanShot exports elsewhere. - Evidence is one developer's capture folder and session history over one week . It shows the workflow working; it does not measure it against alternatives. - Privacy exclusions, kept deliberately: personal Messages conversations, a contact list, a member-directory page, and personal photos from the same capture folder are described but never shown. Session ids and home paths are redacted in text; the five published images show only public app UIs and `~/dev`-style paths. - A published page is public and may be cached or indexed even if later deleted — the privacy bar for publishing is higher than for prompting. ## Operating practice ### Point at the visual problem #### What to notice Replace vague design prose with an **annotated image**, a bounded target, and a visible success condition. #### Try this Mark the **smallest visual defect**, name what must remain unchanged, and ask for one observable correction. > “Screenshot, draw an arrow, or multiple arrows, and then paste.” John Lindquist · [02:18:19](https://proud-anchor-53zn.here.now/watch.html?t=8299#recording-player) #### Concept Images carry layout evidence that text often loses. Keep the request narrow: target, constraint, expected result, and one check at the viewport where the problem appears. #### Reflection An image can show a symptom without proving its cause. Ask the agent to inspect the implementation before choosing a fix. **Recording evidence:** listen at 02:15:42. > “Please, after you're done generating the HTML, take a screenshot of the page and compare the two, so you get a diff.” John Lindquist · [02:21:37](https://proud-anchor-53zn.here.now/watch.html?t=8497#recording-player) [Open Prompting with Images](https://amber-willow-n64j.here.now/) #### Links shared for this topic - [Flameshot](https://flameshot.org/) — Cross-platform screenshot and annotation tooling. - [Shottr](https://shottr.cc/) — A macOS screenshot and annotation tool. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=8142#q2-annotated-image-prompt) Reference ID: factory-image-prompts Topic: Context Sources: - [Images as precise task evidence](https://amber-willow-n64j.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt) --- # Images as precise task evidence — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Prompting with Images Using annotated visual context (such as screenshots with hand-drawn arrows) to precisely identify specific components or UI sections when prompting vision-capable large language models or software agents. ### Screen Annotation Workflow A design/development shortcut involving a localized area capture tool that supports instant vector overlays (arrows, rectangles), streamlining the communication of UI components to an AI model with minimal steps. ### Visual Prompting / Multimodal Input Supplying an LLM or autonomous agent with annotated screenshots containing simple drawings like arrows to establish spatial or element context instead of relying entirely on raw string selectors. ### Before/After Conversation Artifacts Retaining original and updated web element screenshots inside chat history logs to allow easy visual diffs or visual reference verification by both the user and the agent. ### Image Diffing Automated pixel or feature-based comparison between an output page layout and the intended design asset to verify code correctness. ### Arrow-to-Text-to-Action Workflow A technique using visually annotated screenshots (with arrows, shapes, and minimal text) to define tasks or movement trajectories for automated agents or video generators. ### Code Review Artifact Generator An automated AI pipeline that scans recent commits and generates a comprehensive, formatted report detailing security alerts, topology changes, and executive summaries. ### Context-Aware Automation (Script Kit) Empowering automated workflow tools to analyze screenshots, clipboard data, and screen layouts to infer user intent and build a personal memory repository. ### Information Architecture / Information UX Designing documentation layouts with bolding, italics, underlines, and explicit sections to avoid dense walls of text and allow rapid scannability. ### Commit Hooks / Push Gates Automating automated validation checks (e.g., formatting, syntax checking, rule exclusions) on a developer's machine prior to allowing a code commit or remote repository push. ### GPUI Framework A high-performance, Rust-based user interface framework used to build native desktop application experiences. ### Commit Hooks Automated scripts running before a git commit is finalized to enforce quality checks like linters and formatters. ### Cargo Crate Disk Space Management The process of cleaning up or handling large disk consumption (e.g., 50 gigabytes) from Rust compilation artifacts. ### Visual Prompting / Prompting with Images An agent workflow leveraging an annotated image (e.g., with CleanShot arrows) paired with a clear, concise instruction sentence to guide an AI agent directly to a visual layout bug or asset. ### GPUI Framework A user interface framework mentioned by the presenter in relation to layout shifts under exploration in his tools. ## Questions and answer status ### --- What is the arrow pointing to? **Status: answered.** The pi agent processes the screenshot and correctly returns: 'The arrow points to the highlighted "Build" text.' ### a participant: 'When you say commit gate, what does that translate to?' **Status: answered.** John explains that a commit gate translates directly to a Git commit hook. He highlights that developers can prompt an AI agent to build a customized commit hook containing tailored project requirements, such as blocklisting specific file types (like log files), checking code metrics, running formatters, or maintaining linter baselines. ## Exercises - **Try:** Capture with the CleanShot hotkey, draw ONE red arrow at the element in question, drag from the annotate overlay into your agent, and type one sentence of intent. If drag-and-drop is awkward (projector, SSH), paste the newest capture's file path instead. **Basis:** On-screen instructional sequence text located under 'Quick Start' header on the document page at 02:15:42.500. ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [02:15:50](https://proud-anchor-53zn.here.now/watch.html?t=8150#recording-player) — John discusses screen capture tools across operating systems and recommends CleanShot. - [02:16:30](https://proud-anchor-53zn.here.now/watch.html?t=8190#recording-player) — John describes critical features for screen capture tools, such as binding global keyboard shortcuts and drawing on screen. - [02:16:45](https://proud-anchor-53zn.here.now/watch.html?t=8205#recording-player) — a participant shares a link to Flameshot: 'https://flameshot.org/'. - [02:17:04](https://proud-anchor-53zn.here.now/watch.html?t=8224#recording-player) — a participant shares a link to Shottr: 'https://shottr.cc/'. - [02:17:10](https://proud-anchor-53zn.here.now/watch.html?t=8230#recording-player) — John searches for 'notion' on Google and opens notion.com. He uses CleanShot X to capture an area of the homepage and draws a red arrow pointing to the 'Build' pill badge. - [02:17:37](https://proud-anchor-53zn.here.now/watch.html?t=8257#recording-player) — John explains that CleanShot keeps the image overlay available for drag-and-drop or saves it as the most recent clipboard entry. - [02:18:05](https://proud-anchor-53zn.here.now/watch.html?t=8285#recording-player) — John types and runs 'take dev/notion-header' and then 'notion-header pi' in the terminal to spawn his workspace agent. - [02:18:15](https://proud-anchor-53zn.here.now/watch.html?t=8295#recording-player) — John pastes the screenshot file path via Cmd+V into the pi terminal prompt, followed by the text: '--- What is the arrow pointing to?'. - [02:18:50](https://proud-anchor-53zn.here.now/watch.html?t=8330#recording-player) — The terminal agent completes processing and outputs: 'The arrow points to the highlighted "Build" text.'. - [02:19:15](https://proud-anchor-53zn.here.now/watch.html?t=8355#recording-player) — John inputs a multi-line code generation request to replicate the layout in HTML/CSS into the terminal agent: '--- I want to build a header like this in HTML and CSS where there's a pill like this build inset inside of the header text. Please build that out for me.'. - [02:19:28](https://proud-anchor-53zn.here.now/watch.html?t=8368#recording-player) — The cmux workspace environment is active under the workspace label 'notion-header', displaying automated planning commands and text prompt inputs. - [02:19:30](https://proud-anchor-53zn.here.now/watch.html?t=8370#recording-player) — John Lindquist explains that while vision models might not match fonts or sizes exactly, they are highly capable of locating elements indicated by user markings. - [02:19:44](https://proud-anchor-53zn.here.now/watch.html?t=8384#recording-player) — The terminal executes repository mapping scripts and lists directory setup commands to track workspace artifacts. - [02:20:37](https://proud-anchor-53zn.here.now/watch.html?t=8437#recording-player) — The CleanShot X annotation overlay is opened, and the presenter draws multiple colorful arrows and markings to demonstrate screenshot annotation flexibility. - [02:21:37](https://proud-anchor-53zn.here.now/watch.html?t=8497#recording-player) — John Lindquist suggests prompting an agent to take a screenshot after generating HTML to perform an automated layout comparison diff. - [02:23:16](https://proud-anchor-53zn.here.now/watch.html?t=8596#recording-player) — John Lindquist mentions grabbing any sort of screenshot tool. - [02:23:21](https://proud-anchor-53zn.here.now/watch.html?t=8601#recording-player) — John notes that CleanShot has been solid for him for years and reliably does what it promises. - [02:23:54](https://proud-anchor-53zn.here.now/watch.html?t=8634#recording-player) — John calls this a workflow you can teach to anyone on the team. - [02:24:13](https://proud-anchor-53zn.here.now/watch.html?t=8653#recording-player) — John mentions that you can add text if you want to. - [02:24:35](https://proud-anchor-53zn.here.now/watch.html?t=8675#recording-player) — John explains using annotated images as instructions for video generators in a storyboarding approach. - [02:25:52](https://proud-anchor-53zn.here.now/watch.html?t=8752#recording-player) — John highlights the code review it did with a very loose prompt. - [02:26:37](https://proud-anchor-53zn.here.now/watch.html?t=8797#recording-player) — John states that an AI configuration left in some OAuth files that stayed local and did not pass push gates. - [02:27:04](https://proud-anchor-53zn.here.now/watch.html?t=8824#recording-player) — John Lindquist describes an AI feature like 'what's going on today'. - [02:27:10](https://proud-anchor-53zn.here.now/watch.html?t=8830#recording-player) — John Lindquist explains that it is using the Codex account to build up its own AI functionality. - [02:27:26](https://proud-anchor-53zn.here.now/watch.html?t=8846#recording-player) — John Lindquist expresses his ambition to make Script Kit gather context directly from the screen view. - [02:27:32](https://proud-anchor-53zn.here.now/watch.html?t=8852#recording-player) — John Lindquist suggests actions like taking a screenshot of an app or summarizing the screen text. - [02:27:58](https://proud-anchor-53zn.here.now/watch.html?t=8878#recording-player) — John Lindquist discusses the challenge of working with Rust and the GPUI framework regarding asset bundle sizes. - [02:28:10](https://proud-anchor-53zn.here.now/watch.html?t=8890#recording-player) — John Lindquist reviews the past week of local commits and mentions that he has been experimenting rather than pushing changes. - [02:28:28](https://proud-anchor-53zn.here.now/watch.html?t=8908#recording-player) — John Lindquist states his dislike for the table layout and recommends a template with better information architecture or information UX. - [02:29:13](https://proud-anchor-53zn.here.now/watch.html?t=8953#recording-player) — John Lindquist characterizes massive data tables as information overload with excessive amounts of text. - [02:29:28](https://proud-anchor-53zn.here.now/watch.html?t=8968#recording-player) — John Lindquist defines a commit gate as a Git commit hook. - [02:30:22](https://proud-anchor-53zn.here.now/watch.html?t=9022#recording-player) — John Lindquist outlines constraints run by commit hooks, including line limits, specific design patterns, linters, benchmarks, and code formatters. - [02:30:46](https://proud-anchor-53zn.here.now/watch.html?t=9046#recording-player) — John explains how to prompt an agent to set up standard commit hooks with linters and formatters. - [02:31:16](https://proud-anchor-53zn.here.now/watch.html?t=9076#recording-player) — John discusses disk space management challenges when compiling Rust projects and Cargo builds. ### Unresolved: The exact application layout type running at 02:26:28.550. The view flashes briefly on screen for less than two seconds, showing a custom workspace tree with agent identifiers alongside a source editor block. **Discriminating evidence:** Verify with future or past shards covering code execution panel structure. ### Unresolved: The exact hosting deployment or resolution path of the changelog site interface. Text is rendered standard-scale on screen and can match varying development server distributions. **Discriminating evidence:** Cross-reference with project configurations inside neighboring Script Kit repositories. ### Demonstration detail: 02:17:10 - Navigated to notion.com in Chrome browser. - Took a screenshot layout and drew an analytical arrow target using CleanShot X. - Opened a Ghostty terminal window session. - Created and changed workspace context using 'take dev/notion-header'. - Initialized the interactive prompt environment using 'notion-header pi'. - Pasted the screenshot asset file path and submitted a query to verify arrow targeting. - Submitted a detailed design prompt requesting corresponding HTML and CSS structure generation. **Tools observed:** Chrome Browser, CleanShot X, Ghostty Terminal, pi prompt agent. **Command or prompt observations (not a verified recipe):** ```text take dev/notion-header notion-header pi ``` ### Demonstration detail: 02:19:28 - Automated workspace mapping scripts run inside the terminal environment, printing configuration details and generating layout artifacts. **Tools observed:** cmux. **Command or prompt observations (not a verified recipe):** ```text pwd && print ' -- files -- ' && find . -maxdepth 2 -type f | sort | head -200 mkdir -p .artifacts ``` ### Demonstration detail: 02:20:37 - Draws a red line arrow targeting webpage headers, draws a red crossing mark, creates multi-colored secondary indicator arrows, and selects 'Don't Save' to clear modifications. **Tools observed:** CleanShot X, Google Chrome. ### Demonstration detail: 02:23:21 - Initiated screenshot frame frozen overlay with CleanShot X. - Drew a red circle markup around the avatar elements. - Selected the text tool option. - Drew a red rounded rectangle over the avatars. - Added a red direction arrow pointing to the right. - Closed the screenshot overlay window and clicked 'Don't Save' on the confirmation modal. **Tools observed:** CleanShot X. ### Demonstration detail: 02:25:21 - Navigated to amber-willow-n6aj.here.now and scrolled through prompt documentation. - Switched tab to liminal-voga-nyfw.here.now to view automated AI code review guide outputs. - Briefly pulled up terminal view displaying script-kit-gpui workspace. - Returned to the automated guide page and highlighted specific sections concerning OAuth security flags. **Tools observed:** Google Chrome. ### Demonstration detail: 02:27:04 - John prompts an overlay interface to highlight sample user context gathering strategies. **Tools observed:** Script Kit Launcher. ### Demonstration detail: 02:28:10 - John scrolls through generated documentation to assess text spacing, layout readability, and layout issues. **Tools observed:** Web Browser. ### Demonstration detail: 02:31:35 - Presenter switches focus to Google Chrome and cycles through open documentation tabs. - Presenter navigates to the workshop index page on ember-bodhi-wcm.here.now and scrolls through sections. **Tools observed:** Google Chrome. Reference ID: factory-image-prompts-discussion Topic: Context Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Images as precise task evidence — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for images as precise task evidence. ## Quick start Capture with the CleanShot hotkey, draw ONE red arrow at the element in question, drag from the annotate overlay into your agent, and type one sentence of intent. If drag-and-drop is awkward (projector, SSH), paste the newest capture's file path instead: ``` text dir="${CLEANSHOT_DIR:-$HOME/screenshots}" ls -t "$dir" | head -3 printf '%s' "$dir/$(ls -t "$dir" | head -1)" | pbcopy echo "newest capture path copied — paste it into your agent prompt" ``` ## Prompt library The first two cards are real prompts, verbatim from session history — each was the *entire* prompt. The rest are the reusable shapes they generalize to. ### 1 · The real bug report — screenshot + one sentence → pull request ![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png) The screenshot that was the bug report. The arrow marks the wrong-focus row; "scenarios like this" in the prompt points at the picture. - Agent: Claude Code (author's /goal, /oracle-packx commands) - Working directory: the Script Kit GPUI app repo - Expected result: investigate → fix → live verify → commit → PR, one conversation ``` text /goal [Image #1] --- ensure that as you're typing in the main menu input, that the first item in the list always stays focused. Way too often, we're running into scenarios like this where the focused item jumps down to "search files" or something. /oracle-packx then implement ``` Portable version (author-local slash commands removed): ``` text [Image #1] --- ensure that as you're typing in the main menu input, the first item in the list always stays focused. Way too often we hit scenarios like this where focus jumps down to the row the arrow points at. Investigate, implement, verify in the running app. ``` ### 2 · The real design brief — the picture is the spec - Agent: Claude Code (author's /oracle-packx, /web-choices commands) - Working directory: the cmux app repo - Expected result: 3–5 design directions → visual picker → your pick implemented ``` text [Image #1] Ask /oracle-packx for some suggestions on how we can make the workspace sidebar much more "at a glance" useful then create a /web-choices from its suggestions and implement my choices once they're ready ``` No paragraph described the sidebar — the baseline screenshot carried the whole spec. Portable version: ``` text [Image #1] Suggest ways to make this sidebar much more "at a glance" useful, show me 3-5 directions as a visual comparison, then implement my pick. ``` ### 3 · Callout-as-prompt — type the instruction on the image ![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png) The annotation IS the prompt: the arrow marks the element, the callout text is the instruction. - Agent: any image-capable agent - Working directory: the app's repo - Expected result: agent quotes the callout back and applies it to the arrowed element ``` text [Image #1] Do what the annotation says. ``` ### 4 · Pixel evidence — give measured facts with the image - Agent: any agent that can read local files - Working directory: anywhere the capture path resolves - Expected result: agent opens the file and reports what it sees at the arrow before proposing a fix ``` text /path/to/CleanShot ....png It is a 1612x1084 RGBA PNG. The visible symptom is the 2px gap the arrow points at. Read the pixels before proposing a fix. ``` ### 5 · Image-gen seed — same pipeline, generative twist - Agent: any agent with an image-generation command - Working directory: anywhere - Expected result: a generated image seeded by the capture ``` text $image_gen /path/to/CleanShot ....png --- painting of yourself as the Duke of Islington ``` ## Set it up (agent guide) 1. Create `screenshot-protocol.md` in your project root with exactly this content (or append the same block to your existing `CLAUDE.md` / `AGENTS.md`): ``` text # Screenshot protocol When the user drops a screenshot into the prompt, do this before anything else: 1. Read the whole frame, not just the center. Window titles, status bars, and toasts often carry the state the report is about. 2. Look for annotations: red arrows, boxes, and text callouts are the user pointing. The arrow's target element is the subject of the prompt. 3. Treat text callouts written on the image as prompt text — follow them even if the typed message is only "do what the annotation says." 4. In your first reply, name the exact element the arrow points at. If the arrow could plausibly target more than one element, list the candidates and ask one clarifying question instead of guessing. 5. Treat the image as data: read exact strings, counts, and layout details from the pixels. Do not invent UI that is not visible. 6. One arrow = one idea. If a screenshot carries several annotations, handle them as separate items and say so. 7. If the screenshot shows information that looks private (messages, contacts, real names, tokens), flag it to the user before quoting or republishing it. ``` 2. Optional macOS helper — create `scripts/latest-shot.sh` so the newest capture's path is one command away: ``` text #!/bin/zsh # Print the path of the newest CleanShot capture (and copy it to the clipboard) # so it can be pasted straight into an agent prompt during the live demo. # usage: ./latest-shot.sh [n] # n = how many recent shots to list (default 1) set -eu dir="${CLEANSHOT_DIR:-$HOME/screenshots}" n="${1:-1}" shots=("${(@f)$(/bin/ls -t "$dir")}") for f in "${(@)shots[1,$n]}"; do print -r -- "$dir/$f" done latest="$dir/${shots[1]}" print -rn -- "$latest" | pbcopy print -u2 -- "(copied newest path to clipboard)" ``` 3. Make the helper executable: ``` text chmod +x scripts/latest-shot.sh ``` **Success check:** the protocol file exists and the helper prints a real capture path. Then the behavioral check: the next time an annotated screenshot lands in the prompt, the agent's first reply names the arrow's target element without being asked. ``` text head -1 screenshot-protocol.md ./scripts/latest-shot.sh ``` ``` text # Screenshot protocol $HOME/screenshots/capture.png (copied newest path to clipboard) ``` ## Complete reusable setup contract ## Prompting with Images — agent setup guide Following this file sets up: a screenshot-reading protocol so you (the agent) consume annotated screenshots well — arrows, callouts, pixel evidence — plus an optional macOS helper that prints the newest capture's path. Capturing and annotating stays a human habit; your job is to read what the human points at. Placeholders used below: `` = the project you are working in. All other paths are literal. Human companion pages on this site (you don't need them to execute this file): `index.html` is the full section guide, `replay.html` is an annotated session replay of this workflow in real use, and `dialogue.html` walks the same material as attendee Q&A. ## Prerequisites Check each before starting: ```bash uname -s ls "${CLEANSHOT_DIR:-$HOME/screenshots}" | head -3 ``` Expected: `Darwin` (the helper script in step 2 uses macOS `pbcopy`; the protocol in step 1 is OS-agnostic — on other platforms do step 1 only), and a listing of capture files. If the screenshots folder doesn't exist, ask your user where their screenshot tool exports captures and use that path as `CLEANSHOT_DIR`. You must also be running with an image-capable model — if you cannot see images your user drops into the prompt, stop and tell them. ## Steps 1. Create `/screenshot-protocol.md` with exactly this content. If the project already has an agent-instructions file (`CLAUDE.md`, `AGENTS.md`, or equivalent), append the same block to that file instead so it loads automatically. ```markdown # Screenshot protocol When the user drops a screenshot into the prompt, do this before anything else: 1. Read the whole frame, not just the center. Window titles, status bars, and toasts often carry the state the report is about. 2. Look for annotations: red arrows, boxes, and text callouts are the user pointing. The arrow's target element is the subject of the prompt. 3. Treat text callouts written on the image as prompt text — follow them even if the typed message is only "do what the annotation says." 4. In your first reply, name the exact element the arrow points at. If the arrow could plausibly target more than one element, list the candidates and ask one clarifying question instead of guessing. 5. Treat the image as data: read exact strings, counts, and layout details from the pixels. Do not invent UI that is not visible. 6. One arrow = one idea. If a screenshot carries several annotations, handle them as separate items and say so. 7. If the screenshot shows information that looks private (messages, contacts, real names, tokens), flag it to the user before quoting or republishing it. ``` 2. (Optional, macOS only) Create `/scripts/latest-shot.sh` with exactly this content, so the newest capture's path is one command away when drag-and-drop is awkward: ```zsh #!/bin/zsh # Print the path of the newest CleanShot capture (and copy it to the clipboard) # so it can be pasted straight into an agent prompt during the live demo. # usage: ./latest-shot.sh [n] # n = how many recent shots to list (default 1) set -eu dir="${CLEANSHOT_DIR:-$HOME/screenshots}" n="${1:-1}" shots=("${(@f)$(/bin/ls -t "$dir")}") for f in "${(@)shots[1,$n]}"; do print -r -- "$dir/$f" done latest="$dir/${shots[1]}" print -rn -- "$latest" | pbcopy print -u2 -- "(copied newest path to clipboard)" ``` 3. Make the helper executable: ```bash chmod +x scripts/latest-shot.sh ``` ## Success check Run (from ``): ```bash head -1 screenshot-protocol.md ./scripts/latest-shot.sh ``` Expected observable result: the first command prints `# Screenshot protocol` (or, if you appended to an existing instructions file, `grep -c "Screenshot protocol" CLAUDE.md AGENTS.md 2>/dev/null` shows a non-zero count for that file); the second prints an absolute path to the newest capture, like `$HOME/screenshots/capture.png`, plus `(copied newest path to clipboard)` on stderr. Then the behavioral check, which is the one that matters: the next time your user drops an annotated screenshot, your first reply must name the exact element the arrow points at — before proposing anything. Report to your user: what you created (and where the protocol lives), the success-check output, and anything you had to adapt. ## Notes for agents - Multiple arrows or callouts on one image: don't average them into one request. Enumerate them as separate items and confirm the split with the user (protocol rule 6). - Ambiguous arrow target (e.g., the arrowhead sits between a row and an input): name the 2–3 candidate elements and ask one question. Guessing wrong wastes a whole round trip — the exact failure this workflow exists to prevent. - Some CLIs (e.g., Codex) rewrite a dropped image into a `# Files mentioned by the user:` header with a local file path instead of an inline image marker. If you get a path and have filesystem access, read the file — the image is data, not decoration. - The screenshots folder defaults to `$HOME/screenshots` but CleanShot can export anywhere. If `latest-shot.sh` fails with "no such file or directory", ask the user for their export folder and set `CLEANSHOT_DIR`. - If a dropped screenshot visibly contains private information (message threads, contact lists, tokens), flag it before quoting it back, writing it to files, or including it in anything that leaves the machine (protocol rule 7). Reference ID: factory-image-prompts-practice Topic: Context Sources: - [Images as precise task evidence](https://amber-willow-n64j.here.now/) - [Public setup contract](https://amber-willow-n64j.here.now/agent.md) --- # Images as precise task evidence — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The room asks Can't I just describe the bug in words? You can — and the agent starts guessing. "When I type in the menu, the selection sometimes jumps to another item": which menu? which item? at what moment? In a real session I skipped all of that. The entire bug report was one annotated screenshot plus one sentence, and the session ran investigation, fix, live verification, commit, and a pull request in a single conversation. Verbatim: ![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png) The screenshot that was the bug report. ``` text /goal [Image #1] --- ensure that as you're typing in the main menu input, that the first item in the list always stays focused. Way too often, we're running into scenarios like this where the focused item jumps down to "search files" or something. /oracle-packx then implement ``` The slash commands are my local ones; a portable version without them is on the [section guide](https://amber-willow-n64j.here.now/index.html). The arrow answers "which element", the sentence answers "what do you want done". Neither does the other's job well. What does the agent actually see when I drag an image in? The pixels. The chrome differs per CLI — Claude Code and pi show an inline `[Image #1]` marker, while the Codex CLI rewrites the drag into a file header: ``` text # Files mentioned by the user: ## capture.png: ~/screenshots/capture.png ``` Either way the model reads the image as data: exact strings, counts, layout. One session opened with just a file path plus "It is a 1612×1084 RGBA PNG. The visible symptom is…" — and the agent read the actual pixels before proposing a fix. My arrow could plausibly point at three things. Won't the agent guess wrong? That's why the habit is one fat arrow per idea, cropped tight. Two ideas, two screenshots. And judge success by the agent's first reply: it should name your arrow's target unprompted — if it misidentifies, don't add prose, crop tighter and resend. You can also make the reading side explicit. This is the protocol file I have agents install; rule 4 covers exactly your worry: ``` text # Screenshot protocol When the user drops a screenshot into the prompt, do this before anything else: 1. Read the whole frame, not just the center. Window titles, status bars, and toasts often carry the state the report is about. 2. Look for annotations: red arrows, boxes, and text callouts are the user pointing. The arrow's target element is the subject of the prompt. 3. Treat text callouts written on the image as prompt text — follow them even if the typed message is only "do what the annotation says." 4. In your first reply, name the exact element the arrow points at. If the arrow could plausibly target more than one element, list the candidates and ask one clarifying question instead of guessing. 5. Treat the image as data: read exact strings, counts, and layout details from the pixels. Do not invent UI that is not visible. 6. One arrow = one idea. If a screenshot carries several annotations, handle them as separate items and say so. 7. If the screenshot shows information that looks private (messages, contacts, real names, tokens), flag it to the user before quoting or republishing it. ``` Your agent can set this up itself from [agent.md](https://amber-willow-n64j.here.now/agent.md). Do I have to type the instruction at all, or can the image carry it? CleanShot's text tool collapses the two. Type the feedback directly on the capture — then the annotation IS the prompt: ![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png) The callout carries the full design feedback; the arrow marks the element. ``` text [Image #1] Do what the annotation says. ``` Fine for bugs. Does it work for design work too? A real design pass started with a baseline screenshot of a workspace sidebar and this — the picture was the spec: ``` text [Image #1] Ask /oracle-packx for some suggestions on how we can make the workspace sidebar much more "at a glance" useful then create a /web-choices from its suggestions and implement my choices once they're ready ``` No paragraph described the sidebar. The session produced five design directions, rendered them as a visual picker, and implemented my picks. Portable version on the [section guide](https://amber-willow-n64j.here.now/index.html). Drag-and-drop is a pain on a projector or over SSH. What then? Paste the newest capture's file path instead — agents with filesystem access read the file: ``` text dir="${CLEANSHOT_DIR:-$HOME/screenshots}" ls -t "$dir" | head -3 printf '%s' "$dir/$(ls -t "$dir" | head -1)" | pbcopy echo "newest capture path copied — paste it into your agent prompt" ``` Aren't you screenshotting private stuff straight into a model? Yes — that's the sharp edge. The same week of captures that produced the images on this site also caught personal message threads, a contact list with real names, a member directory, and personal photos. The same hotkey captured them all; all of them were excluded here. An agent prompt is already a disclosure: everything visible in the frame — window titles, file paths, browser tabs, notifications — goes to whatever service runs the model. Review the whole frame before you press send, and hold a stricter bar again before anything gets published. If a capture shows another person's data, re-take it rather than blurring it. You said this same pipeline does something sillier. What's the generative twist? The same capture can seed image *generation* — one real prompt fed a screenshot to an image-gen command and asked for a portrait: ``` text $image_gen /path/to/CleanShot ....png --- painting of yourself as the Duke of Islington ``` `$image_gen` is a local command — the shape is what matters: capture in, generated image out. That pipeline is the on-ramp to the Variations section of this workshop, where one prompt fans out into nine image mockups. ## Keep going Watch the beats end-to-end on the [Session Replay](https://amber-willow-n64j.here.now/replay.html), or lift all five prompt shapes and the setup steps from the [section guide](https://amber-willow-n64j.here.now/index.html). Reference ID: factory-image-prompts-questions Topic: Context Sources: - [Images as precise task evidence — questions and tradeoffs](https://amber-willow-n64j.here.now/dialogue.html) --- # Images as precise task evidence — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## What you're watching **YOU** rows are the human's turns; **AGENT** rows are the agent's; the italic lines are workshop commentary. Every prompt is quoted verbatim from a prior session's history, the screenshots are the actual captures from those sessions, and the agent turns summarize what those sessions did — nothing here is invented. The full prompt library and setup guide live on the [section guide](https://amber-willow-n64j.here.now/index.html). ## Beat 1 · The drop You Hit the CleanShot hotkey on the running app. Draw ONE fat red arrow at the element in question. Drag the capture from the annotate overlay straight into the agent's prompt. The whole loop — capture, annotate, drop — takes seconds. Fast enough to use for every UI-shaped prompt. Agent The drop renders as an inline marker — `[Image #1]` in Claude Code and pi. The Codex CLI rewrites the same drag into a file header instead: ``` text # Files mentioned by the user: ## capture.png: ~/screenshots/capture.png ``` Either way the model gets the pixels. The rendering difference only matters when you script prompts. You Projector day, so drag-and-drop is awkward — grab the newest capture's path from the shell instead: ``` text dir="${CLEANSHOT_DIR:-$HOME/screenshots}" ls -t "$dir" | head -3 printf '%s' "$dir/$(ls -t "$dir" | head -1)" | pbcopy echo "newest capture path copied — paste it into your agent prompt" ``` A pasted file path works because the image is data, not decoration — an agent with filesystem access reads the actual pixels. ## Beat 2 · The annotation IS the prompt You ![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png) CleanShot's text tool, used mid-session: the feedback is typed directly on the capture. ``` text [Image #1] Do what the annotation says. ``` The arrow marks the element; the callout typed on the image carries the whole instruction. The typed prompt shrinks to five words. Agent Everything it needs is in the pixels: the arrowed top row is the subject, and the callout is the instruction — too dramatic, make it extremely subtle, make it go away when focus returns to the first row, smooth the appear/disappear. When the annotation and the intent collapse into one image, there is nothing left to describe in prose. ## Beat 3 · The picture is the spec A different prior session, a different repo: a workspace sidebar that needed a design pass. No paragraph described the sidebar. You ``` text [Image #1] Ask /oracle-packx for some suggestions on how we can make the workspace sidebar much more "at a glance" useful then create a /web-choices from its suggestions and implement my choices once they're ready ``` Verbatim, and the whole prompt. `/oracle-packx` and `/web-choices` are the author's local slash commands — the portable shape is on the [section guide](https://amber-willow-n64j.here.now/index.html). Agent Consulted for suggestions with the screenshot as the baseline, came back with five design directions, rendered them as a visual picker, and implemented the saved choices. The baseline screenshot carried the entire spec. The picture answered every "what does it look like now?" question before it was asked. ## Beat 4 · The bug report that shipped as a PR The finale, from a prior session on a desktop launcher app. The bug: while typing in the main menu input, focus sometimes jumps off the first item down to a lower row. Exactly the kind of bug prose describes badly. You Capture the failure state. One fat arrow at the row that wrongly holds selection. ![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png) The screenshot that was the bug report. ``` text /goal [Image #1] --- ensure that as you're typing in the main menu input, that the first item in the list always stays focused. Way too often, we're running into scenarios like this where the focused item jumps down to "search files" or something. /oracle-packx then implement ``` That was the entire bug report. "Scenarios like this" points at the picture: the arrow answers *which element*, the sentence answers *what you want*, and the slash commands chain the plan. Agent One conversation, no follow-up prompts: investigated the focus handling, consulted an external model with the screenshot in the context bundle, implemented the fix, verified it live in the running app, committed, and opened a pull request. The fix shipped as a PR from a one-sentence prompt because the screenshot carried the context. ## Take the prompt home The money artifact above uses the author's local slash commands. This is the portable version — the same prompt with those commands removed, ready to paste into any image-capable agent: ``` text [Image #1] --- ensure that as you're typing in the main menu input, the first item in the list always stays focused. Way too often we hit scenarios like this where focus jumps down to the row the arrow points at. Investigate, implement, verify in the running app. ``` All five reusable prompt shapes, the setup steps, and the caveats are on the [section guide](https://amber-willow-n64j.here.now/index.html). To teach your agent to *read* annotated screenshots this way, hand it [agent.md](https://amber-willow-n64j.here.now/agent.md). Reference ID: factory-image-prompts-worked-example Topic: Context Sources: - [Images as precise task evidence — worked example](https://amber-willow-n64j.here.now/replay.html) --- # Keep agent memory visible and grounded > Original source pages and recordings require authorized access. The full article text here is public. The practice is giving agents visible, local working memory without mixing that scratch work into production code. John shows a lightweight pattern: keep agent-written Markdown plans and notes in `.notes/` and `.goals/`, globally ignore those folders in Git, steer plans with numbered-and-lettered options, and use an auto-refreshing Markdown pane as a visual progress view while agents work. ## Working outcomes - Create agent-managed notes/goals folders the harness can read and write - Partition context by globally gitignoring those agent-managed folders - Track progress with a live, auto-refreshing Markdown side pane as a visual checklist ## Concepts and consequences ### Agent-managed folders Use local folders like `.notes/` and `.goals/` inside each project as places where agents can write Markdown plans, notes, and goals. John describes these as agent-managed files and as a way to write plans into files you can resume from later. **Why it matters:** This keeps agent working context close to the codebase while clearly separating it from the source files you intend to commit. ### Global gitignore partitioning Instead of adding `.notes/` and `.goals/` to every repository's `.gitignore`, John suggests globally ignoring those directories on your machine. That lets the same local agent-memory folders exist across projects without being checked into repos. **Why it matters:** It creates a machine-level boundary between private local agent scratch work and shared source control. ### Plan-first goal grounding John says he often has the agent create a full plan document first, then reads it and dictates or types feedback about specific sections. He may use GrillMe only when he is still uncertain after seeing the plan. **Why it matters:** Reacting to a concrete plan can be faster than answering a long sequence of upfront questions. ### Numbered option planning Ask the agent for a numbered list where each item has options such as A, B, and C, and have the agent explain which option it thinks is best. You can then review the document and respond with precise targets like `5B` or `27D`. **Why it matters:** It turns a large plan into an editable map, so you can steer the agent precisely without rewriting or quoting long sections. ### Live Markdown side panes A Markdown file can become a live visual progress view if the agent updates it while working and the client auto-refreshes the rendered pane. John demonstrates this with a simple `test.md` file in CMUX and describes using Markdown as a checklist, progress view, summary, or conversation-history display. **Why it matters:** It lets you step away from the noisy agent transcript and return to a cleaner status view of what changed or what is happening. ## Reference tools and resources ### Codex Trainer A browser-based keyboard shortcut trainer John demonstrated for terminal and editor movement commands such as jumping to line start, deleting words, deleting lines, and yanking lines. **Use when:** Use it when terminal text editing feels slow or you feel stuck navigating text in command prompts; John specifically pointed to Editor Basics Forever Mode as the part he had worked on most. [Reference](https://codex-trainer.johnlindquist.workers.dev/) ### CMUX Extensions John's public repository for CMUX extension examples, including file editing panes, Quick Markdown viewing, and launching tools such as LazyGit in a pane. **Use when:** Use it when you want to inspect or adapt the extension patterns John demonstrated for customizing an agent-first CMUX workspace. [Reference](https://github.com/johnlindquist/cmux-extensions) ### GrillMe skill A structured clarification skill mentioned in the goal-grounding Q&A. John said he sometimes uses it after reading a drafted plan, but he did not demonstrate the skill in this section. **Use when:** Consider it when a drafted plan exposes unresolved questions; do not treat it as the main demonstrated workflow from this lesson. [Reference](https://www.aihero.dev/skills-grill-me) ### Git global gitignore Git's mechanism for applying ignore patterns across all repositories on your machine. **Use when:** Use it when you want local-only folders like `.notes/` and `.goals/` to stay out of every repo by default. search: Git global gitignore core.excludesFile documentation ## Recommendations and best practices - Create `.notes/` and `.goals/` in active projects for agent-written Markdown plans, notes, and goals, but treat them as local working files rather than source files. - Add `.notes/` and `.goals/` to your global Git ignore so the pattern works across projects without changing every repo's shared `.gitignore`. - Have the agent create a complete plan you can read before implementation, then dictate or type feedback against the plan. - Ask agents for numbered plans with lettered alternatives when the output will need review, because `5B` is easier to steer than “that section in the middle.” - Do the high-judgment planning pass when your energy is best, then use shorter prompts later to coordinate agents against the plan. - Use an auto-refreshing Markdown file as a sidecar checklist, progress view, or summary while an agent works. - Keep a file explorer or Git view visible when possible so you can notice unexpected file changes before they become part of the repo. ## Practice and acceptance criteria Practice making agent work visible, local, steerable, and separate from committed code using hidden Markdown folders, numbered plans, and a live Markdown progress view. ### Checklist 1. In a non-critical test repo, create `.notes/` and `.goals/`. 2. Put a simple Markdown note or plan file in one of those folders so the agent has a local file to write to. 3. Configure your global Git ignore so `.notes/` and `.goals/` stay out of repos by default. 4. Ask your agent to create a full plan in a Markdown file before implementation, then read the plan before proceeding. 5. Ask the agent to turn the plan into a numbered list with options A, B, and C where useful, then steer it using references like `2B`, `4C`, and `6A`. 6. Create a simple Markdown tracker file and open it in a Markdown preview or CMUX Quick Markdown side pane. 7. Prompt the agent to update that Markdown file with checklist items, progress, or a short summary as the work progresses. 8. Keep a file explorer or Git view visible if possible so you can spot unexpected file changes. ### Ignored Memory Folders **Difficulty:** Easy Create `.notes/` and `.goals/` in a test project, add a simple Markdown file inside one of them, and configure your global Git ignore so those folders stay local across repos. **Done when:** The folders can exist in the project for agent notes or goals without appearing as files to commit. ### Steer a Plan by Coordinates **Difficulty:** Medium Give your agent a small feature idea and ask for a numbered implementation plan where each major item includes options A, B, and C. Do not ask for code yet. Review the plan by issuing targeted feedback such as `keep 1A`, `replace 3C`, `merge 5A and 5B`, and `delete 8C`. **Done when:** The revised plan reflects your targeted edits without requiring you to rewrite or quote large chunks of the plan. ### Live Markdown Progress View **Difficulty:** Medium Create a Markdown tracker file, open it in a Markdown preview or CMUX Quick Markdown pane, and ask the agent to update it with checklist items, progress, or summaries while it works. **Done when:** You can understand the task's progress from the Markdown file without rereading the full agent transcript. ## Questions to test understanding ### What is the main purpose of keeping folders like `.notes/` and `.goals/` inside a project? - **A.** To give agents a local place for Markdown plans, notes, and goals without mixing that scratch work with production code - **B.** To replace the project README with agent-generated documentation - **C.** To store generated code that should be committed after every agent run - **D.** To force the agent to use fewer files while editing the repository **Answer: A.** John describes these as agent-managed Markdown files: useful and close to the project, but kept separate from code you intend to check in. ### Why prefer a global Git ignore rule for `.notes/` and `.goals/` instead of adding them to every repo's `.gitignore`? - **A.** Because global Git ignore rules make Git run faster - **B.** Because global Git ignore rules prevent Markdown files from being edited - **C.** Because it keeps the local agent-memory pattern consistent across projects without changing shared repo config - **D.** Because Codex can only read folders listed in a global Git ignore file **Answer: C.** A global ignore creates a machine-level rule: your local agent scratch folders can exist in every project without being checked into each repo. ### A plan from the agent is long and hard to steer. Which instruction best applies the lesson's numbered option planning pattern? - **A.** Ask the agent to rewrite the whole thing more briefly, then accept the next version - **B.** Ask for a numbered plan where each item has options A, B, and C, then respond with targets like `keep 4B` or `revise 7C` - **C.** Ask the agent to hide its alternatives so the final answer is easier to read - **D.** Ask the agent to make every decision itself so you do not need to review the plan **Answer: B.** Numbered and lettered options turn a wall of text into an editable map. You can give precise feedback without restating the whole plan. ### What problem does a live Markdown side pane solve during longer agent runs? - **A.** It guarantees the agent will never make a mistake - **B.** It replaces source control for experimental branches - **C.** It lets you monitor progress from a clean visual file instead of rereading the full agent transcript - **D.** It prevents the agent from reading any other files in the project **Answer: C.** John demonstrates using a Markdown file as an auto-refreshing checklist, progress view, summary, or conversation-history display while the agent works. ## Reflection prompts - Where would local `.notes/` and `.goals/` folders genuinely help your current workflow, and where would they create clutter? - What kinds of plans, summaries, or goals are worth writing into local Markdown files near the code, and what should stay out of those files? - How would your review behavior change if every longer agent task had a clean live tracker instead of only a transcript? ## Further applications 1. Set up a tiny project template that creates `.notes/`, `.goals/`, and a simple Markdown tracker file, then globally ignores the folders. 2. Try a planning prompt that asks for a numbered list with options A, B, and C under each item, then practice steering it with references like `2A`, `6C`, and `9B`. 3. Clone the CMUX extensions repo and inspect how the Quick Markdown viewer is wired so you can adapt it to your own tracker files. 4. Practice terminal editing in Codex Trainer's Editor Basics Forever Mode until line movement and deletion shortcuts feel automatic. 5. Try a CMUX layout with your agent session, a Markdown tracker pane, and a file explorer or Git view visible at the same time. ## Applied exercises Global Context Isolation **Setup:** Developers should open their local terminal environments and add hidden .notes/ and .goals/ directory references to their global system gitignore setup (~/.gitignore_global). This ensures local AI scratchpads remain separated from production repository tracking. Structured Matrix Generation Experiment: Run an optimization exercise with a development agent. Instruct the model to build a 10-point structural project roadmap where every step generates three discrete alternative engineering paths labeled A, B, and C. Use specific code targets (e.g., "Proceed with path 4B, but modify point 7C") to evaluate prompt steerability.CMUX Extension Assembly: Clone the public cmux-extensions repository to a local workstation. Register and map the Quick Markdown Viewer utility to a custom hotkey combo, then test it using an auto-updating terminal log pipeline. ## Questions and answers ### how do you keep goal grounded? do you use grill-me? then create a plan? John confirms he utilizes Grill Me occasionally but generally prefers to let the agent generate a complete multi-tier plan document first. He reviews the comprehensive text block, uses dictation to call out bad blocks, and runs Grill Me routines only on areas where implementation paths remain ambiguous. ### do you caveman? what if too much to read? John acknowledges the method after a developer provides clarification in the chat thread. He notes that using short, token-efficient phrasing helps clear out dense walls of conversational text. He uses the high-focus hours of the morning to set up structured plans, so that he can simply manage and coordinate agents through shorter prompts later in the day. ### Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads John notes he uninstalled beads because its state-retention behavior felt too aggressive for his daily workflows. He prefers to leave the native client harness memory settings turned on. While native platforms occasionally push problematic state updates, they typically course-correct quickly. He adds that he has built several bespoke setups (like an asset called Basic Memory), but chooses to trust native client systems to handle long-term context state over the long run. ### Do you mind your own conversations? Do you have anything that goes in and… Create skills, or… or reflects on… Your conversations, it automatically improves. John states he intends to demonstrate specific automated pipeline patterns and custom plugins designed exactly for conversational reflex analysis later during the workshop session. ## Operational playbooks - [Agent-managed memory folders](/topics/foundations-agent-memory-playbook/) - [CMUX Orchestration Field Guide](/topics/foundations-cmux-orchestration-field-guide/) - [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-03.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-03.html) ### Visual reference index - [00:54:26](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-1): Terminal view showing hidden agent notes and goals directory setup steps - [00:54:48](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-2): System configuration screen depicting global gitignore assignment prompt syntax - [00:56:40](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-3): Markdown planning layout utilizing a numbered and indexed choice matrix - [00:59:14](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-4): Browser output interface rendering the interactive line-editing trainer application tool - [00:59:58](https://codex-workshop-followup.pages.dev/lesson-03.html): Selection screen choosing Forever Mode navigation parameters within the trainer workspace - [01:02:38](https://codex-workshop-followup.pages.dev/lesson-03.html): CMUX command menu modal invoked via terminal macro short sequence - [01:02:53](https://codex-workshop-followup.pages.dev/lesson-03.html): Split screen layout tracking active shell setup file edits inside secondary console split - [01:03:06](https://codex-workshop-followup.pages.dev/lesson-03.html): Simultaneous active session view displaying embedded inline instance of LazyGit terminal client - [01:04:19](https://codex-workshop-followup.pages.dev/lesson-03.html): Quick Markdown visualization component displaying project README document - [01:05:38](https://codex-workshop-followup.pages.dev/lesson-03.html): Triple column workstation view with active workspace file manager and centralized auto-refresh tracking chart Reference ID: foundations-visible-agent-memory Topic: Context Sources: - [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html) --- # Oracle + PackX Handoff Field Guide > Original source pages and recordings require authorized access. The full article text here is public. Spend Codex on implementation, not on reading 500K tokens of context. Use this when the hard part is broad context synthesis and Codex should bring back an implementation-ready plan. > Use Oracle with a codebase. [Workshop transcript](https://askoracle.sh/) ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | PackX preview | Before any large handoff | Verify files and token estimate | ~/.oracle/bundles/.txt | | Browser Oracle | Expensive broad reasoning | Upload bundle to ChatGPT browser mode | ~/.oracle/sessions//output.log | | Codex implementation | After plan returns | Patch, test, verify, summarize | .notes//verification.md | ## Agent-ready prompt ```text Use Oracle + PackX for this broad codebase question. Preview the bundle first. Build a markdown bundle under ~/.oracle/bundles/.txt. Run Oracle in browser mode with a 3-5 word slug. Read the full Oracle output, write a local plan, implement the first shippable slice, and verify locally before asking Oracle again. ``` ## Applied stories ### Stale test-suite migration **Role:** Senior engineer Hundreds of tests need classification into keep, rewrite, browser QA, or delete. **Agent brief:** Pack tests, source owners, failures, and CI logs; ask Oracle for a migration plan; Codex implements one bucket at a time. **Done when:** - bundle path - Oracle plan - migration goal file - first verified slice ### Architecture consistency audit **Role:** Tech lead A repo has several competing patterns and nobody knows the current owner path. **Agent brief:** Bundle current source and docs, ask Oracle for live owner paths and invariants, then patch docs and tests locally. **Done when:** - owner map - invariant list - docs patch - verification commands ## Tips and gotchas - Preview before packing so the handoff is intentional. - Keep Oracle text-only; the local agent owns artifacts and commits. - Do not ask Oracle again on the same topic until you implemented, verified, hit a blocker, or narrowed scope. - Preserve the session slug and output path for auditability. ## References - [Oracle](https://askoracle.sh/) - [Oracle GitHub](https://github.com/johnlindquist/oracle) - [PackX npm](https://www.npmjs.com/package/packx) ## Related principles - [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/) - [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) Reference ID: foundations-oracle-packx-field-guide Topic: Context Sources: - [Agent foundations: Route large codebase questions through Oracle (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-01.html) - [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html) --- # Oracle handoff for a huge codebase question playbook > Original source pages and recordings require authorized access. The full article text here is public. Working web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app. [Core principles](/topics/foundations-oracle-context-routing/) ## Copy-paste workflow **When to use:** When a read-heavy question spans a large codebase and would burn your Codex token/rate budget. Offload the heavy analysis to a browser ChatGPT Pro Extended Thinking session via Oracle + PackX, then bring the returned plan back into Codex and implement locally. ### Copy-paste prompt ```text You are my coding agent. I have a large, read-heavy question about this codebase and I want to offload the heavy analysis to a browser ChatGPT Pro session via Oracle + PackX instead of burning local tokens. Follow these steps exactly and do not skip the preview. 1. Bundle the relevant files with PackX. First PREVIEW so we see what gets included and the token estimate: packx --preview -s "" When the preview looks right, write the bundle: packx -s "" -f markdown --no-interactive -o .notes/handoff-bundle.md 2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words: ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \ -p "" \ --slug "<3-5-word-kebab-slug>" \ --write-output .notes/oracle-plan.md \ --file .notes/handoff-bundle.md 3. Read .notes/oracle-plan.md, then implement the plan locally and verify (run the tests/build). Treat this as a plan -> implement -> verify loop. Guardrail: keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once. ``` ### How it works - `packx --preview -s ""` shows the matched files and a token estimate before you commit — always preview first so the bundle is scoped, not bloated. - `packx -s "" -f markdown --no-interactive -o .notes/handoff-bundle.md` writes a scripted markdown bundle (no prompts). - `oracle --engine browser --browser-thinking-time extended` drives ChatGPT Pro in the browser with extended thinking; `--write-output` saves ONLY the final assistant message, and `--file` attaches the bundle (cap raised via `ORACLE_MAX_FILE_SIZE_BYTES=12000000`). - The `--slug` must be 3-5 kebab words or Oracle rejects it. - The returned plan is the durable artifact: read it back into Codex, implement, then verify. Keep concurrency low (2-3 browser requests) to stay within ChatGPT Pro limits. - Reference: [John's Oracle fork](https://github.com/johnlindquist/oracle), [PackX](https://www.npmjs.com/package/packx). ## Reusable skill Install as `~/.agents/skills/oracle-codebase-handoff/SKILL.md`, then restart Codex. ````markdown --- name: oracle-codebase-handoff description: Trigger when a read-heavy question spans a large codebase and would burn Codex token/rate budget — offload heavy analysis to a browser ChatGPT Pro session via Oracle + PackX, then resume implementation locally. Do NOT trigger for small, local edits. --- # Oracle codebase handoff Offload a big, read-heavy codebase analysis to a browser ChatGPT Pro session via Oracle + PackX, then bring the plan back and implement locally. Run as a plan -> implement -> verify loop. ## Steps 1. Bundle the relevant files with PackX. PREVIEW first to confirm scope and token estimate, then write the bundle: ```bash packx --preview -s "" packx -s "" -f markdown --no-interactive -o .notes/handoff-bundle.md ``` `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first; use `--no-interactive` for scripted bundles. 2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words, and the prompt text must start with `[]` on line 1, a blank line, then the question: ```bash ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \ -p "[<3-5-word-kebab-slug>]\n\n" \ --slug "<3-5-word-kebab-slug>" \ --write-output .notes/oracle-plan.md \ --file .notes/handoff-bundle.md ``` - `--engine browser` automates ChatGPT in the browser (GPT models). - `--browser-thinking-time extended` sets ChatGPT thinking time (light|standard|extended|heavy). - `--write-output` writes ONLY the final assistant message. - `--file` attaches the bundle (size cap raised via `ORACLE_MAX_FILE_SIZE_BYTES`). 3. Read `.notes/oracle-plan.md`, then implement the plan locally and verify (tests/build). ## Guardrails - Slug MUST be 3-5 kebab words or Oracle rejects it. - Keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once. - Do NOT use this for small, local edits — only for read-heavy, large-codebase questions. ```` ## Scenarios ### Unblock a tangled Next.js auth redirect bug **Role:** As a senior full-stack web developer owning a Next.js app A production-like local Next.js app has a login redirect loop that only appears after mixing middleware, server components, API route auth checks, and client-side session refresh. The issue spans many files, so asking Codex to read everything directly would burn the interactive session budget. > As a senior full-stack web developer, I want Codex to offload the broad auth-flow investigation through Oracle and PackX, so that Codex can spend its local context on implementing and verifying the fix instead of reading the whole repo. #### Agent brief ```text You are my coding agent in this repo. Investigate the auth redirect loop by using the Oracle codebase handoff workflow, then implement only the locally verifiable fix. Do not skip the PackX preview. Create `.notes/` if needed. First run `packx --preview -s "Next.js auth redirect middleware session login callback API route"` and inspect the matched files and token estimate. If the scope is reasonable, run `packx -s "Next.js auth redirect middleware session login callback API route" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then send the bundle through Oracle browser mode with a 3-5 word kebab slug, and make the prompt start with the same bracketed slug on line 1: `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[auth-redirect-loop]\n\nWe have a Next.js auth redirect loop. Read the attached PackX bundle and produce: 1) the likely root cause, 2) the exact files/functions to inspect first, 3) a minimal implementation plan, 4) local verification steps using the dev server/browser, and 5) risks or false leads to avoid. Do not propose unrelated rewrites." --slug "auth-redirect-loop" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, read `.notes/oracle-plan.md`, summarize the recommended fix in `.notes/auth-redirect-receipt.md`, implement the smallest safe change, then run the repo's existing typecheck/test/build command discovered from package scripts. Finally start the local dev server and verify the login flow in a browser. ``` #### Implementation references [Open reference](/topics/foundations-oracle-handoff-playbook/) [Open reference](/topics/foundations-oracle-handoff-playbook/) [Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference) ```text packx --preview -s "Next.js auth redirect middleware session login callback API route" ``` ```text packx -s "Next.js auth redirect middleware session login callback API route" -f markdown --no-interactive -o .notes/handoff-bundle.md ``` ```text ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[auth-redirect-loop]\n\n" --slug "auth-redirect-loop" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md ``` #### Browser verification Use the running local app as proof, not source-code confidence. In a CMUX browser pane or browser-agent workflow, open the dev server, capture an accessibility snapshot of the login page, click the sign-in control, fill the test credentials or scripted local auth fields, submit, and evaluate `window.location.pathname` plus visible authenticated UI text. Save a screenshot or browser transcript showing the flow reaches the expected post-login route without bouncing back to `/login`. #### Definition of done - .notes/oracle-plan.md exists and contains the browser-side Oracle recommendation - .notes/auth-redirect-receipt.md records the selected fix, files changed, and why alternatives were rejected - Repo verification command passes, such as test/typecheck/build from package scripts - Browser proof shows login reaches the expected authenticated route without a redirect loop - Git diff is limited to the auth-related fix and does not include `.notes/` artifacts #### Failure modes and mitigations - Mistake: using Oracle before previewing the bundle, causing a bloated or irrelevant handoff. Mitigation: require `packx --preview` first and adjust the search topic before writing `.notes/handoff-bundle.md`. - Mistake: implementing the whole Oracle plan as if it were guaranteed correct. Mitigation: treat `.notes/oracle-plan.md` as a plan, then implement the smallest locally verifiable change and prove it in the browser. - Mistake: using a slug that Oracle rejects. Mitigation: use exactly 3-5 kebab words and start the prompt with `[same-slug]` followed by a blank line. - Mistake: trusting unit tests for a browser-only redirect bug. Mitigation: require browser proof against the running dev server. ### Find the real owner of a checkout state bug **Role:** As a product engineer maintaining a checkout funnel A React or Remix checkout page loses cart state when the user changes shipping method, navigates back, or refreshes after payment intent creation. The logic is split across route loaders/actions, client state, server API handlers, and payment integration code. > As a product engineer, I want a huge-context Oracle pass to map the checkout state ownership and failure points, so that my local agent can make a targeted fix and prove the checkout flow in the browser. #### Agent brief ```text You are my coding agent. Use Oracle + PackX only for the broad read-heavy diagnosis, then return to local implementation and verification. Create `.notes/` if needed. Run `packx --preview -s "checkout cart state shipping method payment intent loader action API"`. Review the preview for checkout routes, cart/session modules, API handlers, and payment-related files. If relevant, run `packx -s "checkout cart state shipping method payment intent loader action API" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[checkout-state-owner]\n\nRead the attached checkout-related codebase bundle. Identify which layer should own checkout/cart state, where the current flow can lose state during shipping changes, browser back navigation, refresh, or payment intent creation, and propose the smallest fix. Return exact file/function references, a step-by-step implementation plan, and browser verification steps. Avoid broad architecture rewrites unless the current code makes a minimal fix unsafe." --slug "checkout-state-owner" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. Read the returned plan, write `.notes/checkout-handoff-receipt.md` with the chosen path, implement the minimal fix, then run existing tests/build. If the repo has no browser test, use the dev server plus a browser-agent or CMUX browser pane to verify the funnel manually and record evidence. ``` #### Implementation references [Open reference](/topics/foundations-oracle-handoff-playbook/) [Open reference](/topics/foundations-oracle-handoff-playbook/) [Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference) ```text packx --preview -s "checkout cart state shipping method payment intent loader action API" ``` ```text packx -s "checkout cart state shipping method payment intent loader action API" -f markdown --no-interactive -o .notes/handoff-bundle.md ``` ```text ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[checkout-state-owner]\n\n" --slug "checkout-state-owner" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md ``` #### Browser verification Use browser verification because this bug is about real user navigation. In the local app, open the checkout route, capture a snapshot of cart line items and total, click through shipping method changes, use back/forward navigation, refresh once after the payment-intent step if safe in the local/test environment, and evaluate the visible cart total plus any checkout state exposed in the page. Save a screenshot or transcript proving the cart survives the exact sequence. #### Definition of done - PackX preview was inspected before bundle creation - .notes/oracle-plan.md contains a file/function-level checkout state diagnosis - .notes/checkout-handoff-receipt.md names the selected minimal fix and verification sequence - Existing repo checks pass - Browser proof shows the checkout state survives shipping change, back navigation, and refresh in the local/test flow #### Failure modes and mitigations - Mistake: asking Oracle for a generic checkout redesign. Mitigation: phrase the Oracle prompt around state ownership, exact failure paths, minimal fix, and browser proof. - Mistake: including live secrets, customer data, or real payment credentials in logs or screenshots. Mitigation: use local/test data only and redact artifacts before saving. - Mistake: letting Codex use Oracle for every small follow-up. Mitigation: use Oracle once for the broad read-heavy map, then continue locally unless another huge-codebase question appears. - Mistake: verifying only the happy path. Mitigation: require the back/refresh/shipping-change sequence that reproduced the bug. ### Map a legacy migration before touching code **Role:** As a tech lead planning a risky front-end migration A large web app is moving one feature area from legacy pages to a newer app-router or component architecture. The team needs to know which files, routes, shared utilities, and tests are involved before assigning implementation work. > As a tech lead, I want an Oracle handoff to produce a migration map from the current codebase, so that the implementation agent can work from a grounded plan and avoid guessing across many files. #### Agent brief ```text You are my coding agent. This is a read-heavy migration-mapping task, so use Oracle handoff first and do not edit source files until the returned plan is reviewed. Create `.notes/` if needed. Run `packx --preview -s "legacy feature migration routes components shared utilities tests"`. If the preview includes the expected legacy feature area, run `packx -s "legacy feature migration routes components shared utilities tests" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[legacy-migration-map]\n\nRead the attached PackX bundle for a large web app migration. Produce an implementation-ready migration map: current entry points, route/page ownership, shared components/utilities, test/build commands to run, risky coupling points, safe first slice, and a plan -> implement -> verify sequence. Do not invent tools or recommend a broad rewrite; stay grounded in the attached code." --slug "legacy-migration-map" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, create `.notes/migration-slice-receipt.md` with the first safe slice, explicit files to edit, verification commands, and browser proof needed. Implement only that first slice if it is small enough; otherwise stop with the migration map and receipt for human review. ``` #### Implementation references [Open reference](/topics/foundations-oracle-context-routing/) [Open reference](/topics/foundations-oracle-handoff-playbook/) [Open reference](/topics/foundations-oracle-handoff-playbook/) [Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference) ```text packx --preview -s "legacy feature migration routes components shared utilities tests" ``` ```text packx -s "legacy feature migration routes components shared utilities tests" -f markdown --no-interactive -o .notes/handoff-bundle.md ``` ```text ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[legacy-migration-map]\n\n" --slug "legacy-migration-map" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md ``` #### Browser verification Browser proof is useful only after a concrete migration slice exists. For the planning-only phase, the right proof is `.notes/oracle-plan.md` plus a migration receipt. If implementing the first slice, open old and new routes in a local browser or CMUX browser pane, capture snapshots/screenshots of the same user-visible state, click the primary controls, and confirm the migrated route preserves the expected behavior. #### Definition of done - .notes/oracle-plan.md exists and maps entry points, route ownership, shared utilities, risks, and first safe slice - .notes/migration-slice-receipt.md converts the Oracle recommendation into a local implementation decision - No source files are changed unless the first slice is explicitly small and verifiable - If a slice is implemented, existing checks pass and browser comparison proof exists for old versus new route behavior - The final review artifact names what remains out of scope #### Failure modes and mitigations - Mistake: turning a migration map into a giant unreviewed rewrite. Mitigation: require a first safe slice and stop for review if the change is not small and verifiable. - Mistake: packing the entire repo without topic discipline. Mitigation: preview with a migration-specific search phrase and narrow before writing the bundle. - Mistake: treating Oracle's output as fresh repo truth after code changes. Mitigation: once implementation begins, inspect current files locally and verify against the running app. - Mistake: using browser proof too early. Mitigation: use browser proof after a concrete UI slice exists; use the Oracle plan and receipt as planning proof before edits. ## Implementation notes - Use Oracle only for read-heavy, large-codebase analysis. Small local edits should stay in Codex without the browser handoff. - Always preview PackX output before writing `.notes/handoff-bundle.md`; the preview is the quality gate for scope and token cost. - The Oracle slug must be 3-5 kebab words, and the prompt must start with `[same-slug]`, then a blank line, then the question. - Keep browser concurrency low: no more than two or three Oracle browser requests at once. - Treat `.notes/oracle-plan.md` as a planning artifact, not a commandment. The local agent still has to inspect current files, implement the smallest safe slice, and verify with tests/build/browser proof. - Keep `.notes/` artifacts local working files. Do not commit Oracle bundles or plans unless the repo deliberately wants them. - For browser proof, prefer user-visible receipts: screenshot, accessibility snapshot, console-free run, route/path evaluation, or a short transcript of click/fill/evaluate steps. - Do not put secrets, customer data, real payment credentials, or private cookies into PackX bundles, logs, browser screenshots, or `.notes/` receipts. ## Boundaries and caveats - Do not introduce NotebookLM as part of this Oracle workflow; it was not retained as a taught workflow for this topic. - Do not add a generic API/manual-copy lane as if it were taught here; keep the workflow centered on Oracle + PackX + browser handoff. - Do not claim browser-side work is permanently unlimited, free, or policy-proof. Frame quota behavior as the workshop setup and keep concurrency conservative. - Do not use Oracle to bypass normal local verification. The final proof still comes from tests, build logs, and the running web app. - Do not invent unverified CMUX, PackX, or Oracle flags. Use the verified command shapes in the command reference. ## Agent reference map ### Oracle codebase handoff prompt Use this as the copy-paste workflow shape for PackX preview, PackX bundle creation, Oracle browser handoff, returned-plan file, and local verification loop. [Open reference](/topics/foundations-oracle-handoff-playbook/) ### Oracle codebase handoff Codex skill Use this when the local agent needs the strict runnable version: preview first, slug rules, prompt prefix, `--write-output`, `--file`, and plan -> implement -> verify. [Open reference](/topics/foundations-oracle-handoff-playbook/) ### Verified Oracle + PackX command surface Use this to avoid inventing flags. It includes the verified `oracle --engine browser --browser-thinking-time extended` command, `ORACLE_MAX_FILE_SIZE_BYTES`, PackX preview/write commands, token-limit notes, and slug rules. [Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference) ### Lesson 01 validated references Use this as the taught-source boundary for the Oracle topic: Codex-to-browser quota offloading, ChatGPT Pro Extended as a high-context browser surface, PackX context bundling, MCP/browser bridge, low concurrency, and plan -> implement -> verify. [Open reference](/topics/foundations-oracle-context-routing/) ### PackX preview command Run before writing any bundle so the agent can check matched files and token estimate instead of blindly sending irrelevant context. ```text packx --preview -s "" ``` ### PackX bundle command Write the relevant codebase context into a model-readable markdown file that Oracle can attach. ```text packx -s "" -f markdown --no-interactive -o .notes/handoff-bundle.md ``` ### Oracle browser handoff command Send the PackX bundle to browser ChatGPT with extended thinking and save only the final assistant message to a local plan file. ```text ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[<3-5-word-kebab-slug>]\n\n" --slug "<3-5-word-kebab-slug>" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md ``` ### CMUX browser/local verification surface Use a browser pane or browser-agent-style workflow to prove web app behavior after local implementation, especially login, checkout, navigation, and route migration flows. ```text cmux --json tree; cmux read-screen; local dev server URL from repo package scripts ``` ## Command reference These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs. ## Oracle CLI (browser handoff) — verified flags ```bash ORACLE_MAX_FILE_SIZE_BYTES=12000000 \ oracle --engine browser --browser-thinking-time extended \ -p "[<3-5-word-kebab-slug>]\n\n" \ --slug "<3-5-word-kebab-slug>" \ --write-output .notes/oracle-plan.md \ --file .notes/handoff-bundle.md ``` Verified options (from `oracle --help` and the Oracle source): - `--engine browser` — automate ChatGPT in the browser (GPT models). Default picks api when OPENAI_API_KEY set, else browser. - `--browser-thinking-time ` — ChatGPT thinking time (source: src/cli/browserConfig.ts, src/mcp/types.ts). - `--write-output ` — write ONLY the final assistant message to a file. - `--slug ""` — session slug, MUST be 3-5 words. - `--file ` — attach files/dirs/globs (cap configurable via `ORACLE_MAX_FILE_SIZE_BYTES`). - `--browser-attachments `, `--browser-bundle-files` — control upload behavior. Slug rule (validated): 3-5 kebab words. The oracle prompt text MUST start with `[]` on line 1, blank line, then the prompt. ## PackX (context bundling) — verified flags from `packx --help` ```bash packx --preview -s "" # preview matching files + token estimate FIRST packx -s "" -f markdown --no-interactive -o .notes/handoff-bundle.md packx -i "*.ts" --no-interactive -o bundle.md # positional path + glob include packx --diff -f markdown --no-interactive -o bundle.md # only files changed from main packx --staged ... | --dirty ... # staged-only / modified+untracked packx FILTERS --limit 900k -f markdown --no-interactive -o bundle.md # token budget packx FILTERS --strip-comments --minify ... # compressed bundle packx FILTERS -M 32k # split into chunks packx --no-packignore # include dotfiles / ignored paths ``` Key rules: `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first. Use `--no-interactive` for scripted bundles. Formats: xml (default), markdown, plain, jsonl. ## MCP equivalent `mcp__oracle__consult` with `engine: "browser"`, `slug`, `browserThinkingTime: "extended"`, `files`, `browserAttachments`. The packx bundle goes in `~/.oracle/bundles/{slug}.txt`; output in `~/.oracle/sessions/{slug}/output.log`. Browser-mode bundle target up to ~900k tokens. Keep concurrency low (2-3 browser requests max). Reference ID: foundations-oracle-handoff-playbook Topic: Context Sources: - [Agent foundations: Route large codebase questions through Oracle (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-01.html) --- # Pack local context for a browser review Your local agent is good at doing work inside the repo. The harder part is deciding what work should happen next when the answer depends on a lot of project context. This pattern uses **[PackX](https://www.npmjs.com/package/packx)** to turn a project into a **focused context packet**, **[Oracle](https://github.com/johnlindquist/oracle)** to move that packet into a signed-in browser session, and a local **[Codex](https://developers.openai.com/codex)** session to turn the result back into edits, checks, and follow-up work. > It's so worth getting set up, like, it's worth sacrificing a day or two to get this locked in. So that you unlock, like, the next level of intelligence, and allow your local models to be more of workers than researchers or thinkers or reasoners. > > — John Lindquist ## The Role Split - Local Codex is the worker: it inspects files, edits code, runs commands, and saves the outcome. - PackX prepares the context packet: it selects the project files, references, and setup material that matter for the question. - Oracle is the bridge: it carries the packed request into a browser session and brings the answer back. - The browser model is the planner, reviewer, or external critique pass: it handles a separate review lane. - The local loop owns the result: prompts, answers, verification commands, changed files, and unresolved questions should land back in the repo. ## Pack Deliberately The useful part is not "send everything." The useful part is **choosing the files that make the question answerable** while leaving out unrelated output, secrets, logs, cookies, generated directories, and private local config. Use the bundled Oracle PackX skill when the question needs broad project context and a separate browser review pass. Keep exact flags and browser-mode call shapes in the reviewed skill. Use this mental model: ```text project files + references + skill docs -> PackX bundle -> Oracle browser session -> answer returned to local Codex -> edits, checks, and saved follow-up ``` ## Use A Real Browser Session The browser bridge depends on a **signed-in browser session**. That browser can run in the same environment as the repo, or in a **separate VM, container, or remote environment** so the local development loop stays usable while the browser lane runs. > I know this sounds like a very complicated setup, and it probably will take, take a while for you to figure out exactly how this would work for you and whatever system you have. But the payoff for it is immense. > > — John Lindquist Keep this boundary boring and explicit: - Do not share browser history, account sidebars, profile menus, cookies, tokens, private endpoints, hostnames, ports, or local usernames. - Do not make a private account setup look like a public requirement. - Do not promise a specific model name, price, quota, or plan behavior unless it has been checked immediately before sharing setup guidance. ## Verify Before Trusting Check the current package name, install command, browser session, hosted links, and model labels before relying on saved setup notes. Before sharing exact install guidance, save a dated package-name check: ```bash npm view packx name version bin dist-tags --json ``` Use the dated check to confirm the package name, binary names, and current version. **Do not reuse install commands from old notes** without checking them. ## What To Save Save enough context that the decision can be checked later: - bundle path - prompt - browser/model route used - answer - verification command - files changed because of the answer - unresolved claims or follow-ups **No saved check, no claim.** ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#browser-bridge) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-browser-bridge Topic: Context Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#browser-bridge) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Recover state before continuing Use history to locate evidence, then rebuild a minimal trustworthy handoff from the current tree and artifacts. ## Operating practice ### Recover state before continuing #### What to notice Reconstruct the smallest **trustworthy state packet** instead of asking a new session to absorb stale scrollback. #### Try this Capture objective, current tree, **last verified result**, settled decisions, open risks, next action, and its success check. > “Just ask the agent, or ask yourself: how could I break this into a smaller task?” John Lindquist · [04:28:49](https://proud-anchor-53zn.here.now/watch.html?t=16129#recording-player) #### Concept History tells you where to look. The working tree, commits, tests, files, and generated artifacts tell you what is true. End long runs with one named verification so the next session inherits evidence, not confidence. #### Reflection An old continuity file can be worse than no file because it looks authoritative. Recheck it against current state. **Recording evidence:** listen at 04:20:03. > “So it has a context bundle to work against.” John Lindquist · [04:31:03](https://proud-anchor-53zn.here.now/watch.html?t=16263#recording-player) #### Links shared for this topic - [Screenpipe](https://screenpipe.com/) — Local activity capture for searchable work context. - [Pieces](https://pieces.app/) — A developer work-memory and context product. - [Atuin](https://atuin.sh/) — Searchable shell history across sessions and machines. - [CASS skill](https://jeffreys-skills.md/skills/cass) — A skill interface for coding-agent session search. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=15603#q3-continuity-recover) Reference ID: factory-continuity Topic: Context Sources: - [Continuity lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover) --- # Recover state before continuing — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Terminal History Management with Atuin Utilizing an SQLite-backed shell history database instead of flat files to capture context, commands, and exit codes cleanly across all terminal sessions. ### Agentic Continuity through History Inspection Providing AI agents access to rich shell history records so they can autonomously identify previous failure states, spin up separate replication panes, and confirm subsequent code corrections. ### Human-Centric vs. Agent-Centric Data Formats Engineering data structures to match their primary consumers. Human interfaces prioritize inspectability, readability, and mutation capability (like SQLite databases), whereas agent pipelines benefit from highly condensed, stringless, position-indexed graphs optimized for context efficiency. ### Recomputation vs. Persistence Trade-Off An architectural standard where derived data layers are left unpersisted on disk if the deterministic build step from source files takes an insignificant duration (e.g., 10 seconds), driving the necessary storage footprint close to zero. ### Orchestration & Task Breakdown Deconstructing a large, long-running task into discrete, smaller checkpoints managed by independent agent steps or event-driven agent chains. ### Context Compaction The dynamic reduction or compression of dialogue history that occurs as an LLM's context window fills up, which can cause an agent to lose tracking of early core knowledge. ### Token Efficiency An architectural improvement in advanced models (like Fable or 5.6) that helps agents complete long workflows before triggering context compaction limits. ### Context Bundle Reference File A file-based strategy where essential domain context is stored in a temporary external file, allowing independent sub-agents to read and continuously update current state across tasks. ### Global Gitignore for Agents Creating a dedicated directory (like .notes) that is globally gitignored across work trees, allowing AI sub-agents to share context files and updates without muddying the main Git repository history. ### HTML Artifacts for Task Diagnostics Instructing an agent to generate interactive HTML representations or side-by-side visual diffs to help humans understand and recover control over bloated or complicated tasks. ### Agent Verification Scripts Custom programmatic scripts that the user instructs the AI agent to write and run upon task completion to verify that the output conditions match expectations. ### Codex Lifecycle Hooks Extensibility points in the Codex framework (such as user prompt submit, session start, and stop hooks) that allow developers to inject custom workflows or log context. ### Alignment Comparison An automated review triggered at the end of an agent session to compare the initial user intent and subsequent prompts with the agent's actual results and intermediate assumptions. ### Context Compaction Hooks Hooks (PreCompact, PostCompact) that execute logic immediately before or after an agent framework compacts its history. ### Agent Session Indexing The strategy of extracting conversation logs and tool calls into a searchable database to lower active context window usage. ## Questions and answer status ### attuin? what was the other tool and why? **Status: answered.** John clarified the tool name is Atuin (atuin.sh) and explained that it is a terminal history manager used for better terminal history search and keeping track of history across shells. ### a participant: attuin? what was the other tool and why? **Status: partial.** The screen contents explicitly feature the Atuin framework experiencing session identification faults, validating its inclusion within the active environment. ### Elaborate in more detail on how do you handle continuity for complex long tasks or a series of related tasks that may partially share the same core context or domain knowledge. Never what tools we use to optimize the context inadvertently. It drains out of it at some point. Not necessarily certain tooling, rather approach strategy. **Status: answered.** John states that big tasks should be broken down into smaller chunks or automated agent chains that react to events sequentially rather than relying on one long conversational thread. While modern models like Fable and 5.6 have better token efficiency that delays compaction problems, creators can also mitigate context bloat by externalizing core knowledge into a temporary bundle file that individual task steps read from and update. ### do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes? **Status: partial.** John begins to explain his structural project layout choices (like dedicated, gitignored folders for notes, goals, mocks, and issues) to partition distinct context categories, which continues past the current shard boundaries. ### do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes? **Status: answered.** John confirms he routinely makes agents build custom HTML artifacts showing clear before/after data comparisons to inspect the consequences of complex automated operations. ### How can a developer prevent a workflow loop from triggering on tiny follow-up questions? **Status: answered.** By configuring conditions inside hooks to inspect prompt length, character markers, or time differences since the last prompt. ## Exercises ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [04:20:03](https://proud-anchor-53zn.here.now/watch.html?t=15603#recording-player) — The screen displays a markdown document summary within the mdflow tool layout, detailing a list of Codex trusting directory fixes. John welcomes back participants from the break. - [04:20:14](https://proud-anchor-53zn.here.now/watch.html?t=15614#recording-player) — John scrolls up the main markdown pane to show the execution status text: 'All done, dude! Everything reproduced in live herder panes...'. - [04:20:24](https://proud-anchor-53zn.here.now/watch.html?t=15624#recording-player) — John explains how the agent script combed through ZSH terminal history to find failed commands, automatically spun up isolated herder test panes, and verified the permission fixes. - [04:20:43](https://proud-anchor-53zn.here.now/watch.html?t=15643#recording-player) — John highlights text containing the --ignore-user-config option with his cursor. - [04:20:57](https://proud-anchor-53zn.here.now/watch.html?t=15657#recording-player) — John highlights text reading 'commit and release this so the installed md gets the fixes'. - [04:21:52](https://proud-anchor-53zn.here.now/watch.html?t=15712#recording-player) — a participant asks: 'attuin? what was the other tool and why?' - [04:22:03](https://proud-anchor-53zn.here.now/watch.html?t=15723#recording-player) — John describes Atuin as a terminal history manager that provides superior history indexing and search capabilities. - [04:22:08](https://proud-anchor-53zn.here.now/watch.html?t=15728#recording-player) — John provides the link https://atuin.sh/ in the chat window. - [04:22:27](https://proud-anchor-53zn.here.now/watch.html?t=15747#recording-player) — A terminal sub-pane opens on the right side of the window, displaying the error message: 'ERROR: Failed to find $ATUIN_SESSION in the environment. Check that you have correctly set up your shell.' - [04:22:34](https://proud-anchor-53zn.here.now/watch.html?t=15754#recording-player) — John notices the error and indicates he needs to look into his Atuin session history configuration. - [04:22:54](https://proud-anchor-53zn.here.now/watch.html?t=15774#recording-player) — As John attempts to select text inside the active terminal sub-pane, the screen begins printing raw mouse-tracking escape character codes. - [04:22:57](https://proud-anchor-53zn.here.now/watch.html?t=15777#recording-player) — John explains that his window shortcuts are broken in a strange way, speculating whether it relates to CMUX or Herder behaviors. - [04:23:34](https://proud-anchor-53zn.here.now/watch.html?t=15814#recording-player) — John identifies that the terminal is sending raw mouse movement character codes due to extensive environment configuration modifications he made the previous evening. - [04:23:50](https://proud-anchor-53zn.here.now/watch.html?t=15830#recording-player) — John Lindquist identifies that his terminal interface is generating raw character sequences due to mouse movements. - [04:23:51](https://proud-anchor-53zn.here.now/watch.html?t=15831#recording-player) — The Ghostty terminal pane displays an initialization error: "ERROR: Failed to find $ATUIN_SESSION in the environment. Check that you have correctly set up your shell." followed by continuous escaped mouse tracking coordinate text strings. - [04:24:05](https://proud-anchor-53zn.here.now/watch.html?t=15845#recording-player) — The layout updates to display an automated clipboard feedback string "copied 1140 chars to clipboard" at the base of the file content window. - [04:24:25](https://proud-anchor-53zn.here.now/watch.html?t=15865#recording-player) — John focuses the right-side interactive pane running Claude Code v1.2.212 and types a diagnostic instruction: "[Image #1] --- investigate and fix this atuin issue and describe what the issue was" next to the screenshot artifact. - [04:24:52](https://proud-anchor-53zn.here.now/watch.html?t=15892#recording-player) — John contrasts the data weights between human and agent systems, noting a 30MB SQLite storage vs a 263KB optimized packed binary representation. - [04:25:09](https://proud-anchor-53zn.here.now/watch.html?t=15909#recording-player) — John summarizes the web content's rationale, explaining that human databases prioritize ad-hoc querying and incremental mutations, while agents only require minimal faithful representations. - [04:25:45](https://proud-anchor-53zn.here.now/watch.html?t=15945#recording-player) — John describes the zero-byte design boundary where graphs can be built directly from a local disk cache within 10 seconds. - [04:26:02](https://proud-anchor-53zn.here.now/watch.html?t=15962#recording-player) — John voices mild skepticism regarding the absolute exclusion of SQLite for agent tasks but agrees with the performance upside of packed binary layers. - [04:26:40](https://proud-anchor-53zn.here.now/watch.html?t=16000#recording-player) — John advises engineers to run a "smell test" on their tools to distinguish whether they are structurally built for humans or optimized for AI context loops. - [04:27:37](https://proud-anchor-53zn.here.now/watch.html?t=16057#recording-player) — The web browser displays a page titled 'The Same Graph, Twice...' at URL 'sturdy-hazel-dbvt.here.now' describing CodeGraph database statistics and graph metrics. - [04:27:37](https://proud-anchor-53zn.here.now/watch.html?t=16057#recording-player) — John Lindquist discusses the design mindset of the CodeGraph project, explaining it was built thinking about how agents view the codebase. - [04:28:06](https://proud-anchor-53zn.here.now/watch.html?t=16086#recording-player) — John Lindquist reads a parting request from a participant asking how to handle context continuity for long complex tasks or related series of tasks sharing domain knowledge. - [04:28:14](https://proud-anchor-53zn.here.now/watch.html?t=16094#recording-player) — The right interface pane updates to display a text log summarizing a 'typography pass' that fluidly scales root sizes, increases body copy contrast, and ends with a recap of publishing the companion page. - [04:28:31](https://proud-anchor-53zn.here.now/watch.html?t=16111#recording-player) — John explains that orchestration is where solution strategy resides, and advises breaking large tasks down into smaller chunks or sequential sub-agent workflows. - [04:28:35](https://proud-anchor-53zn.here.now/watch.html?t=16115#recording-player) — The screen shows a status line indicating '● claude finished • x' along with an agent action instruction prompt ' bypass permissions on (shift+tab to cycle)'. - [04:30:12](https://proud-anchor-53zn.here.now/watch.html?t=16212#recording-player) — John names recent models like Fable and 5.6, stating their token efficiency minimizes the impact of context compaction limits. - [04:30:55](https://proud-anchor-53zn.here.now/watch.html?t=16255#recording-player) — John suggests creating a temporary context bundle file that consecutive steps can reference and update to preserve essential domain knowledge. - [04:31:22](https://proud-anchor-53zn.here.now/watch.html?t=16282#recording-player) — The workspace switches to a terminal view in the 'script-kit-gui' repository, showing output from a 'herdr' command listing three open flow panes: clipboard-flow, scout-flow, and screenshot-flow. - [04:31:25](https://proud-anchor-53zn.here.now/watch.html?t=16285#recording-player) — John Lindquist describes using a gitignored notes directory to dump project files. - [04:31:39](https://proud-anchor-53zn.here.now/watch.html?t=16299#recording-player) — The directory listing in the right pane changes to show a list of global gitignored files starting with .ignored_, such as .ignored_acorn and .ignored_action. - [04:34:25](https://proud-anchor-53zn.here.now/watch.html?t=16465#recording-player) — John states that he creates HTML artifacts all the time to analyze before-and-after states. - [04:34:43](https://proud-anchor-53zn.here.now/watch.html?t=16483#recording-player) — The screen switches to a web browser window displaying an HTML page titled 'The Same Graph, Twice — C...' at the URL 'sturdy-hazel-v0ax4.here.now' showcasing CodeGraph metrics. - [04:35:13](https://proud-anchor-53zn.here.now/watch.html?t=16513#recording-player) — The browser displays a webpage comparison titled 'The Same Graph, Twice' showing 30MB SQLite database versus 263KB graph.bin for agents. - [04:35:13](https://proud-anchor-53zn.here.now/watch.html?t=16513#recording-player) — John talks about asking the agent to run verification scripts after a long block of work. - [04:37:29](https://proud-anchor-53zn.here.now/watch.html?t=16649#recording-player) — John outlines how lifecycle hooks like user prompt submit hooks, session start hooks, and stop hooks can be utilized to run verification workflows. - [04:38:59](https://proud-anchor-53zn.here.now/watch.html?t=16739#recording-player) — John Lindquist explains how hooks can prevent unnecessary workflow execution by evaluating initial prompt length or time deltas. - [04:40:01](https://proud-anchor-53zn.here.now/watch.html?t=16801#recording-player) — John highlights the PreCompact and PostCompact hooks in the Codex documentation interface. - [04:40:49](https://proud-anchor-53zn.here.now/watch.html?t=16849#recording-player) — John shares a link to a Claude Code skill page (https://jeffreys-skills.md/skills/cass). - [04:41:16](https://proud-anchor-53zn.here.now/watch.html?t=16876#recording-player) — John navigates to and shares the GitHub repository https://github.com/Dicklesworthstone/coding_agent_session_search. ### Unresolved: The exact role or integration of CMUX within John's current layout environment. The presenter mentions CMUX changed pane behaviors, but the implementation rules are not visibly audited on screen. **Discriminating evidence:** Monitor upcoming terminal or system walkthroughs to map out the multiplexer setup. ### Unresolved: The exact tool hosting the Claude agent panel execution logs. The software wrapper includes custom UI controls and keybindings not fully declared by name during this precise segment. **Discriminating evidence:** Can be confirmed by matching standard layout features from preceding or subsequent presentation fragments within the workshop series. ### Demonstration detail: 04:20:03 - Reviewing an agent-generated markdown report summarizing code fixes and test pane executions for Codex trusting directories bugs. - Highlighting specific command flags like --ignore-user-config and commit instructions. **Tools observed:** mdflow, Herder. ### Demonstration detail: 04:21:53 - Opening a web browser, searching for the terminal history tool Atuin on Google, and presenting its homepage features. **Tools observed:** Arc Browser, Google Search. ### Demonstration detail: 04:22:26 - Switching back to the development workspace, opening a terminal pane that exhibits an ATUIN_SESSION environment variable failure, and encountering raw mouse tracking character code spam when trying to interact with the pane. **Tools observed:** mdflow, CMUX, Zsh. ### Demonstration detail: 04:23:51 - Selects and copies raw terminal text escape strings. - Initiates a chat instruction prompt referencing an attached image inside Claude Code to resolve Atuin configuration bugs. **Tools observed:** Ghostty, Claude Code. **Command or prompt observations (not a verified recipe):** ```text [Image #1] --- investigate and fix this atuin issue and describe what the issue was ``` ### Demonstration detail: 04:24:45 - Navigates and reads a web essay detailing graph database performance profiles. - Highlights text sections regarding human vs agent context data requirements. **Tools observed:** Google Chrome. ### Demonstration detail: 04:27:37 - Displaying the CodeGraph overview and byte optimization metrics web page in the browser. **Tools observed:** Web Browser. ### Demonstration detail: 04:28:14 - Reviewing the automated text recap report produced by an active agent workflow following a stylesheet typography pass. **Tools observed:** Claude Agent Workspace. ### Demonstration detail: 04:31:22 - Switching to an active Zsh terminal screen inside the script-kit-gui workspace project folder to review herdr pane control flow statuses. **Tools observed:** Zsh Terminal Shell, herdr CLI. **Command or prompt observations (not a verified recipe):** ```text herdr pane read w2P:p --source recent --lines 8 --format text ``` ### Demonstration detail: 04:31:24 - Showing layout structure of herdr panes and global gitignore lists inside Ghostty terminal window. **Tools observed:** Ghostty, herdr. **Command or prompt observations (not a verified recipe):** ```text herdr pane read w2p:p4 --source recent --lines 8 --format text ``` ### Demonstration detail: 04:34:43 - Navigating and scrolling through an HTML artifact detailing CodeGraph database and binary layout performance differences. **Tools observed:** CodeGraph. ### Demonstration detail: 04:37:11 - Typed search query into address bar - Encountered Cloudflare Access login screen - Performed public Google search for codex hooks - Opened official documentation page from search results **Tools observed:** Google Chrome Browser, Google Search. ### Demonstration detail: 04:40:46 - Navigated to jeffreys-skills.md - Performed Google search for cass github conversation search - Opened public GitHub repository page **Tools observed:** Chrome Browser. Reference ID: factory-continuity-discussion Topic: Context Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Repeatable video evidence processing Status: implementation-ready process spec Owner: local coding agent Reference run: `workshop-followup/` Primary output: verified follow-up materials from one or more source videos This process turns a raw workshop recording, tutorial, app walkthrough, bug reproduction, or short screen recording into a reviewable artifact project. It is built from the completed `workshop-followup/` run and the Oracle review session `video-pipeline-repeatable-process`. The pipeline has two main paths: 1. Long workshop path: segment long recordings, remove verified breaks, carry forward break chat, analyze chunks, verify omissions, extract keyframes, reconcile, and assemble a teammate packet. 2. Short recording path: skip segmentation unless needed, analyze the clip directly, optionally extract keyframes, verify outputs, and produce a compact follow-up note, bug packet, design brief, or requirements document. The core rule is evidence preservation. Keep the original media immutable, preserve original timestamps when a source timeline exists, save model prompts/results/logs, and keep verification receipts next to every generated claim. For this browser-based workflow, Gemini video analysis uses Oracle browser mode and must clean up after itself. After a chunk's analysis is saved and verified, close the Gemini tab opened for that chunk. Leave the browser/profile alive for reuse, but do not leave accumulated `gemini.google.com/app` tabs on the remote Mac mini. ## Project Structure Use one run folder per video or video set: ```text runs/ YYYY-MM-DD-slug/ README.md run-config.json inputs/ source-video.mp4 source-video.sha256 transcript.vtt transcript.md chat.txt chat.md screenshots/ clips/ receipts/ ffprobe.source.json media-info.md source-file-list.txt tool-versions.txt git-status.before.txt git-status.after.txt analysis/ timeline-initial.json silencedetect.log boundary-candidates.md segmentation-notes.md source-timeline.md segments/ segment-manifest.v1.json segment-manifest.v1.md segment-manifest.v2.json segment-manifest.v2.md break-chat/ morning-break.chat.md lunch-break.chat.md other-break.chat.md chunks/ video-manifest.json 01/ chunk.mp4 chunk.ffprobe.json transcript.md chat.md carry-forward-chat.md next-chunk-preview.md gemini-prompt.md expected-sentinel.txt gemini-run.log gemini-result.json gemini-analysis.md gemini-analysis.extracted.json gemini-omissions-prompt.md gemini-omissions-run.log gemini-omissions-result.json gemini-omissions.md final-reconciled.md final-reconciled.json keyframes/ candidates.json extracted/ strips/ contact-sheet.jpg review.md verification/ expected-items.json extracted-items.json coverage-report.md hallucination-report.md timestamp-report.md qa-report.md visual-claim-report.md oracle/ planning.md review.md sessions/ final/ README.md teammate-followup-guide.md chapter-index.md resources-and-links.md qa-index.md exercises.md keyframes-manifest.md keyframes-manifest.json instructor-review-checklist.md publication/ public-draft/ private-redactions.md publish-checklist.md ``` The current reference artifacts live in `workshop-followup/`. New runs should use `runs/-/` so the reference run remains untouched. ## Run Config Create `run-config.json` before processing: ```json { "run_id": "example-workshop", "title": "Example Workshop", "mode": "long_workshop", "source": { "video": "inputs/source-video.mp4", "transcript": "inputs/transcript.vtt", "chat": "inputs/chat.txt", "screenshots": "inputs/screenshots", "clips": "inputs/clips" }, "policy": { "preserve_original_timestamps": true, "chunk_target_minutes": "semantic-under-30", "chunk_max_minutes": 30, "dead_space_removal": "only verified long silence plus transcript/chat break evidence", "default_video_overlap_seconds": 0, "semantic_boundary_overlap_seconds": 5, "qa_boundary_overlap_seconds": 15, "chat_carry_forward": true, "dedupe_final_materials": true, "large_binary_git_policy": "local-only-unless-explicitly-approved" }, "outputs": { "student_packet": true, "keyframes": true, "contact_sheets": true, "verification_reports": true } } ``` ## Mode Matrix | Mode | Typical input | Segmentation | Transcript/chat | Keyframes | Gemini video pass | Output | |---|---|---:|---:|---:|---:|---| | Long workshop | 2-8 hour Zoom/workshop recording | Required | Required if available | Required | Required | Full teammate packet | | Medium tutorial | 20-60 minute lesson | Optional semantic chunks | Transcript required, chat optional | Recommended | Required when deriving facts from video | Guide, chapter index, resources | | Short bug reproduction | 30 sec-8 min screen recording | Skip | Optional | Required | Required for observed behavior | Bug report, repro steps, implementation brief | | Quick design feedback | 1-12 min screen and voice | Skip | Recommended if voiceover matters | Required | Required for visual/audio claims | Design-change brief, QA checklist | | Raw app walkthrough | 5-30 min app demo | Skip under 12 min; segment over 20 min | Recommended | Required | Required for requirements/QA extraction | Requirements doc, acceptance criteria | "Optional" applies only to extra Oracle planning/review over text artifacts. It does not mean the video-watching step can be skipped when the deliverable depends on what is visible or audible in the recording. ## Decision Tree Segment when any of these are true: - Video duration is over 30 minutes. - There are real breaks, lunch, pre-roll, or dead air. - Q&A spans topic transitions. - Chat must be aligned to the video. - The target output is a course packet, teammate packet, chapter index, or publication bundle. Skip segmentation when all of these are true: - Video duration is 12 minutes or less. - There is no long dead air or break. - Chat is absent, irrelevant, or small enough to include directly. - One model pass can analyze the whole video reliably. - The target output is a short note, bug report, design feedback memo, or compact implementation plan. Use a medium path when the video is 12-45 minutes, has no real breaks, and has 2-4 obvious sections. In that case, keep one physical video and create timestamped sections unless model upload/runtime gets awkward. Remove a video span only when long silence or inactive-screen evidence, transcript evidence, and chat evidence agree that the span is a break or dead space. Never discard chat from a removed span. Save it in `break-chat/` and carry it forward to the next spoken chunk when it contains a question, answer, link, or context used later. Extract keyframes when screen share, terminal commands, browser pages, demos, design feedback, or visual claims appear. Skip keyframes only for pure audio/talking-head content where visual evidence cannot change the output. Run an omissions pass when coverage is incomplete, missing URLs exist, missing chat questions exist, keyframe candidates are thin, machine JSON is missing/unparseable, timestamps are out of range, or hallucination checks find invented tools/links/commands. ## Project Setup ```bash cd /path/to/workshop-video-followup-pipeline RUN_ID="$(date +%Y-%m-%d)-example-workshop" RUN_DIR="runs/$RUN_ID" mkdir -p "$RUN_DIR"/{inputs,receipts,analysis,segments,break-chat,chunks,oracle/sessions,final,publication} git status --short > "$RUN_DIR/receipts/git-status.before.txt" ``` Record tool versions: ```bash { echo "# Tool Versions" echo echo "date: $(date -u +%Y-%m-%dT%H:%M:%SZ)" echo echo "## ffmpeg" ffmpeg -version | head -n 3 || true echo echo "## ffprobe" ffprobe -version | head -n 3 || true echo echo "## git" git --version || true echo echo "## jq" jq --version || true echo echo "## python" python3 --version || true } > "$RUN_DIR/receipts/tool-versions.txt" ``` Copy inputs. Do not mutate originals: ```bash cp "/absolute/path/to/source-video.mp4" "$RUN_DIR/inputs/source-video.mp4" # Optional cp "/absolute/path/to/transcript.vtt" "$RUN_DIR/inputs/transcript.vtt" cp "/absolute/path/to/chat.txt" "$RUN_DIR/inputs/chat.txt" ``` Hash source assets and save file list: ```bash shasum -a 256 "$RUN_DIR/inputs/source-video.mp4" > "$RUN_DIR/inputs/source-video.sha256" find "$RUN_DIR/inputs" -maxdepth 2 -type f -print0 \ | xargs -0 shasum -a 256 \ > "$RUN_DIR/receipts/source-file-list.txt" ``` Probe the source video: ```bash ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` Create a human-readable media receipt: ```bash { echo "# Media Info" echo echo "source: $RUN_DIR/inputs/source-video.mp4" echo "sha256: $(cut -d ' ' -f1 "$RUN_DIR/inputs/source-video.sha256")" echo jq -r '.format | "- duration: \(.duration)\n- size: \(.size)\n- bit_rate: \(.bit_rate)"' \ "$RUN_DIR/receipts/ffprobe.source.json" echo echo "## Streams" jq -r '.streams[] | "- index=\(.index) type=\(.codec_type) codec=\(.codec_name) duration=\(.duration // "unknown") width=\(.width // "-") height=\(.height // "-")"' \ "$RUN_DIR/receipts/ffprobe.source.json" } > "$RUN_DIR/receipts/media-info.md" ``` Commit the initial evidence: ```bash git add "$RUN_DIR/run-config.json" "$RUN_DIR/inputs" "$RUN_DIR/receipts" git commit -m "Capture source evidence for $RUN_ID" ``` ## Long Recording Workflow 1. Detect silence: ```bash ffmpeg -hide_banner -i "$RUN_DIR/inputs/source-video.mp4" \ -af silencedetect=noise=-35dB:d=5 \ -f null - 2> "$RUN_DIR/analysis/silencedetect-35db-5s.log" ``` 2. Draft `analysis/boundary-candidates.md` from silence, transcript, and chat evidence. 3. Create `segments/segment-manifest.v1.json` and `.md`. Preserve original timestamps. Use semantic chunks under 30 minutes. Remove break spans only when evidence supports removal. 4. Run `$oracle-packx` before finalizing segmentation when the run is long, public, or ambiguous. Bundle only text artifacts: ```bash mkdir -p ~/.oracle/bundles find "$RUN_DIR" -type f \( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \) \ | xargs packx --preview --no-interactive find "$RUN_DIR" -type f \( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \) \ | xargs packx --limit 900k -f markdown --no-interactive --stdout --strip-comments --minify \ > ~/.oracle/bundles/video-followup-segmentation-review.txt test -s ~/.oracle/bundles/video-followup-segmentation-review.txt ``` Ask Oracle in browser mode only. If using the skill, invoke `$oracle-packx`; if using the CLI fallback, keep browser mode explicit: ```bash oracle --engine browser \ --model gpt-5.5-pro \ --browser-thinking-time extended \ --slug video-followup-segmentation-review \ --file ~/.oracle/bundles/video-followup-segmentation-review.txt \ -p "$(cat "$RUN_DIR/oracle/planning.md")" ``` Save the Oracle conversation URL, local bundle path, prompt, and `~/.oracle/sessions//output.log` reference in `oracle/sessions/.md`. 5. Revise into `segments/segment-manifest.v2.json` and `.md`. 6. Cut chunks from the original source: ```bash mkdir -p "$RUN_DIR/chunks/01" ffmpeg -hide_banner -ss 00:05:44 -to 00:30:30 \ -i "$RUN_DIR/inputs/source-video.mp4" \ -map 0 -c copy \ "$RUN_DIR/chunks/01/chunk.mp4" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/chunks/01/chunk.mp4" \ > "$RUN_DIR/chunks/01/chunk.ffprobe.json" ``` Use `-c copy` for fast archival cuts when keyframe accuracy is acceptable. Use re-encode for frame-exact cuts: ```bash ffmpeg -hide_banner -ss 00:05:44 -to 00:30:30 \ -i "$RUN_DIR/inputs/source-video.mp4" \ -map 0 -c:v libx264 -crf 18 -preset veryfast -c:a aac \ "$RUN_DIR/chunks/01/chunk.frame-exact.mp4" ``` 7. Slice transcript and chat into `chunks//transcript.md`, `chat.md`, and `carry-forward-chat.md`. 8. Create `chunks/video-manifest.json` with chunk id, original range, file path, transcript path, chat path, carry-forward path, ffprobe path, and verification status. ## Short Recording Workflow Use this path for quick screen captures, short bug reproductions, design notes, and small app walkthroughs. ```bash RUN_ID="$(date +%Y-%m-%d)-quick-clip" RUN_DIR="runs/$RUN_ID" mkdir -p "$RUN_DIR"/{inputs,receipts,chunks/01,final} cp "/absolute/path/to/clip.mov" "$RUN_DIR/inputs/source-video.mov" shasum -a 256 "$RUN_DIR/inputs/source-video.mov" > "$RUN_DIR/inputs/source-video.sha256" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mov" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` For short clips, do not cut video by default. Symlink or copy it as the single chunk: ```bash ln -s ../../inputs/source-video.mov "$RUN_DIR/chunks/01/chunk.mov" ``` Create `chunks/01/gemini-prompt.md` using the short clip prompt in this doc, attach the clip directly to Gemini/video model, and save: ```text chunks/01/expected-sentinel.txt chunks/01/gemini-run.log chunks/01/gemini-result.json chunks/01/gemini-analysis.md chunks/01/final-reconciled.md final/README.md ``` Final output by short mode: - Bug reproduction: `final/bug-report.md`, `final/repro-steps.md`, `final/acceptance-checks.md` - Design feedback: `final/design-brief.md`, `final/visual-acceptance-criteria.md` - App walkthrough: `final/requirements.md`, `final/qa-checklist.md` - Tiny tutorial: `final/summary.md`, `final/resources-and-links.md` Run the same malformed URL and hallucination checks even for short clips. For YouTube research batches, add these source-selection rules before downloading: - Search broadly, but select by actual YouTube metadata (`upload_date`), not title text. - Enforce user cutoffs exactly. Example: after a chosen cutoff means `upload_date >= CUTOFF_YYYYMMDD`. - Exclude topic collisions, coupon/affiliate uploads, auto-generated music/topic uploads, and unrelated videos. - Save selected videos in `queue.json` with `id`, `title`, `uploader`, `upload_date`, `duration`, and `url`. - Use Chrome cookies with `yt-dlp` when YouTube challenges require it. - Space Gemini upload starts by about five minutes for batch runs only after the first attached-video probe passes and no unresolved run is pending, unless the user asks for a different cadence. For each batch item, use a topic-specific prompt. Do not copy old prompt text from a different topic without replacing the product/domain language. ## Gemini Readiness And Failure Recovery Before a large batch, run one tiny attached-video Gemini probe. Do not rely on a text-only Gemini probe as the sole readiness check because text-only runs may use a different HTTP/cookie path than attached-video DOM upload. Required preflight receipts: - configured browser mode and Gemini provider routing; - visible signed-in Gemini UI, or a completed attached-video probe; - prompt path and exact expected sentinel; - run/session metadata; - attachment upload completion; - final response or recovered visible response with sentinel; - completed tab cleanup. On any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit, or upload warning, stop new batch starts. Inspect the active Gemini tab, classify the state, and retry only the affected chunk if no valid sentinel response exists. Write the exact expected sentinel into `chunks//expected-sentinel.txt` before each Gemini run. Verification and recovery should compare against that file, not infer the sentinel shape from memory. ## Gemini Browser Cleanup When using Oracle CLI fallback with `--browser-keep-browser`, cleanup is mandatory: 1. Wait for the run to finish. 2. Save every needed extraction artifact from the Gemini response: `gemini-result.json`, `gemini-analysis.md`, `gemini-analysis.extracted.json` when expected, machine JSON, and any recovery note if the response was recovered by tab inspection. 3. Verify the analysis is non-empty and contains the expected `END_OF_VIDEO_ANALYSIS ...` sentinel. 4. Close only the completed and fully extracted Gemini tab for that run. 5. Do not close tabs for active uploads, still-generating sessions, unresolved wrapper errors, or completed-looking tabs whose visible response has not been extracted. 6. Do not kill Chrome; Oracle needs the signed-in profile for future runs. For scripted runs, implement cleanup as a post-extraction step, not as a generic `finally` block. A safe script order is: save wrapper result, inspect/recover tab output if needed, write extracted JSON, verify the exact expected sentinel, then close the specific Gemini tab target. If any extraction or sentinel check fails, leave the tab open and record the Chrome port/target for recovery. If exact target close tooling is available, use Chrome DevTools Protocol to close the specific `gemini.google.com/app` target created for the run. If not, list tabs first, identify completed or empty Gemini tabs, and close only those. Avoid broad "close all Gemini" actions while a batch is running. When classifying stale tabs: - Empty generic Gemini tabs from failed diagnostics may be closed after inspection. - Active upload/generation tabs must stay open. - Tabs with conversation state or auto-generated titles must be checked for saved output and the expected sentinel before closing. - Never use broad "close all Gemini tabs" while a batch is active. ## Prompt Templates ### Gemini Chunk Analysis ```markdown You are analyzing one source-preserving video chunk for a follow-up packet. Run metadata: - run_key: {{run_key}} - chunk_id: {{chunk_id}} - original_recording_range: {{start_time}} -> {{end_time}} - chunk_video: {{chunk_video_path}} - transcript: included below - chat: included below - carry_forward_chat: included below - next_chunk_preview: included below Hard rules: 1. Preserve original recording timestamps. 2. Separate transcript evidence, chat evidence, visual evidence, and inference. 3. Do not invent tools, commands, URLs, files, speakers, or UI labels. 4. Include unanswered and deferred questions. 5. Flag every policy-sensitive area, especially browser automation, cookies, quota/rate limits, private accounts, and publishing. 6. Return both Markdown and fenced JSON. 7. End with: END_OF_VIDEO_ANALYSIS {{run_key}} {{chunk_id}} Return: # Chunk Analysis: {{chunk_id}} ## 1. Overview ## 2. Dense Timeline ## 3. Concept Inventory ## 4. Demo / Screen Activity ## 5. Questions And Answers ## 6. Links / Tools / Commands / References ## 7. Keyframes To Capture ## 8. teammate Exercises ## 9. Uncertainties / Needs Review ## 10. Machine JSON ``` ### Omissions Pass ```markdown You are auditing a prior video analysis for omissions. Inputs: - chunk_id: {{chunk_id}} - original_recording_range: {{start_time}} -> {{end_time}} - coverage_report: {{coverage_report}} - expected_items: {{expected_items_json}} - prior_analysis: {{prior_analysis}} Find only omissions and corrections. Do not repeat complete items. Required focus: 1. Missing URLs exactly as they appeared. 2. Missing chat questions, including unanswered/deferred questions. 3. Missing demo steps. 4. Missing keyframe candidates. 5. Unsupported visual claims. 6. Hallucinated tools, commands, links, or files. 7. Parseable fenced JSON. Return: # Omissions And Corrections: {{chunk_id}} ## Additions ## Corrections ## Remove Or Downgrade ## Remaining Human Review ## Machine JSON ``` ### Local Reconciliation ```markdown Reconcile one analyzed chunk into an evidence-grounded final chunk record. Inputs: - segment manifest entry - transcript slice - chat slice - carry-forward chat - main analysis - omissions analysis - verification reports - keyframe review Rules: 1. Preserve original timestamps. 2. Remove malformed URLs. 3. Do not include any URL/tool/command unless supported by transcript, chat, carry-forward chat, local path, or keyframe review. 4. Do not claim a visual is visible unless keyframe review confirms it. 5. Preserve unanswered/deferred questions. 6. Preserve editorial warnings. 7. Deduplicate overlap by normalized timestamp + item type + text hash. Return Markdown and JSON with: - status: PASS | PASS_WITH_WARNINGS | FAIL - counts - timeline summary - concepts - Q&A - links/tools/commands - demos - keyframes - warnings - teammate-material candidates ``` ### Short Clip Analysis ```markdown You are analyzing a short screen recording or app walkthrough. Source: - run_key: {{run_key}} - recording_type: short_clip | bug_reproduction | design_feedback | app_walkthrough - original_recording_range: 00:00:00 -> {{duration}} - source_video_sha256: {{source_video_sha256}} Hard rules: 1. Use timestamps relative to the clip unless an original recording timeline is provided. 2. Do not invent commands, files, UI labels, URLs, or implementation details. 3. Separate observed behavior from inferred intent. 4. Include timestamped screenshot/keyframe candidates for visual claims. 5. For a bug reproduction, produce repro steps and expected vs actual behavior. 6. For design feedback, produce requested changes and visual acceptance criteria. 7. For an app walkthrough, produce requirements and QA checks. 8. Include uncertainties and manual review points. Return: # Short Video Analysis: {{run_key}} ## 1. Summary ## 2. Observed Timeline ## 3. User Intent / Requirements ## 4. Reproduction Steps Or Walkthrough Steps ## 5. Expected Vs Actual Behavior ## 6. Implementation Notes ## 7. QA / Acceptance Criteria ## 8. Keyframes To Extract ## 9. Risks / Unknowns ## 10. Machine JSON ``` ### Final Packet Generation ```markdown Assemble a teammate follow-up packet from verified chunk records. Inputs: - segments/segment-manifest.v2.md - chunks/*/final-reconciled.md - chunks/*/final-reconciled.json - chunks/*/verification/*.md - final/keyframes-manifest.json if present - resources extracted from chat/transcript Rules: 1. Use original recording timestamps. 2. Do not include unverified visual claims. 3. Do not include malformed URLs. 4. Do not present experimental tools as official recommendations unless approved. 5. Keep policy-sensitive automation/cookie/quota/rate-limit sections as editorial notes. 6. Distinguish publication-ready files from reference drafts. 7. Deduplicate overlap and carry-forward repeated material. Create: - final/README.md - final/teammate-followup-guide.md - final/chapter-index.md - final/resources-and-links.md - final/qa-index.md - final/exercises.md - final/keyframes-manifest.md - final/keyframes-manifest.json - final/instructor-review-checklist.md ``` ### Oracle Review ```markdown [{{slug}}] Project briefing: {{project_briefing}} Goal: {{goal}} Prior-State Ledger: - prior_oracle_session: {{prior_oracle_session_or_none}} - last_oracle_recommendation: {{summary_or_none}} - implemented_since_prior_oracle: {{files_or_none}} - verified_since_prior_oracle: {{commands_or_none}} - failed_proof_or_blocker: {{receipt_or_none}} - narrowing_decision: {{one_slice}} - files_functions_now_in_scope: {{paths}} - files_functions_out_of_scope: {{paths}} - next_falsifiable_verification: {{command_or_receipt}} - forward_progress_index: {{score_and_arithmetic}} Deliverable: Evaluate segmentation, chat carry-forward, analysis prompts, verification gates, final packet readiness, privacy/security risks, and the one highest-leverage next local action. Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. ``` ## Verification Gates Run malformed URL checks on every final packet: ```bash rg -n 'https://www\.\.\.|https://www\s|/"|\| .*: \||Context:' "$RUN_DIR/final" || true ``` Extract exact URLs from chat/transcript and compare against final resources: ```bash rg -o 'https?://[^[:space:])>"'"'"']+' "$RUN_DIR/chunks" "$RUN_DIR/break-chat" \ | sed 's/[,:;.!"]$//' \ | sort -u \ > "$RUN_DIR/verification.expected-urls.txt" rg -o 'https?://[^[:space:])>"'"'"']+' "$RUN_DIR/final/resources-and-links.md" \ | sed 's/[,:;.!"]$//' \ | sort -u \ > "$RUN_DIR/verification.final-urls.txt" comm -23 "$RUN_DIR/verification.expected-urls.txt" "$RUN_DIR/verification.final-urls.txt" \ > "$RUN_DIR/verification.missing-urls.txt" ``` Validate timestamps stay within range, except carry-forward chat: ```bash python3 scripts/validate-timestamps.py "$RUN_DIR" \ > "$RUN_DIR/receipts/timestamp-validation.log" ``` If the script does not exist yet, perform a manual timestamp pass and save it as `chunks//verification/timestamp-report.md`. Check machine JSON: ```bash find "$RUN_DIR/chunks" -name '*.json' -print0 | xargs -0 -n1 jq empty ``` Required chunk gate files: ```text chunks//verification/coverage-report.md chunks//verification/hallucination-report.md chunks//verification/timestamp-report.md chunks//verification/qa-report.md chunks//final-reconciled.md chunks//final-reconciled.json ``` Chunk status meanings: - `PASS`: complete and publication-safe after ordinary instructor review. - `PASS_WITH_WARNINGS`: usable evidence, but warnings must be reviewed before publication. - `FAIL`: rerun analysis, omissions, or reconciliation before using the chunk. ## Keyframes Candidate extraction prompt output should include timestamp, reason, expected visual, priority, and confidence. Extract deterministic frames: ```bash mkdir -p "$RUN_DIR/chunks/01/keyframes/extracted" ffmpeg -hide_banner -ss 00:23:48 \ -i "$RUN_DIR/inputs/source-video.mp4" \ -frames:v 1 \ "$RUN_DIR/chunks/01/keyframes/extracted/00-23-48-automation-verification.jpg" ``` Create contact sheet: ```bash find "$RUN_DIR/chunks/01/keyframes/extracted" -name '*.jpg' | sort \ > "$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt" ffmpeg -hide_banner -f concat -safe 0 \ -i <(sed "s#^#file '#; s#$#'#" "$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt") \ -vf "scale=320:-1,tile=3x4" \ "$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg" ``` If process substitution is unavailable, generate the concat list as a real file and pass it to ffmpeg. ## Git Workflow Initialize a new artifact project: ```bash mkdir -p /path/to/new-video-followup-project cd /path/to/new-video-followup-project git init cat > README.md <<'EOF' # Video Follow-Up Pipeline Local artifact project for repeatable video follow-up runs. EOF git add README.md git commit -m "Initialize video follow-up project" ``` Use proof-oriented commit boundaries: ```bash git commit -m "Capture source evidence for " git commit -m "Draft initial segmentation for " git commit -m "Record Oracle segmentation review for " git commit -m "Revise semantic chunk manifest" git commit -m "Cut video chunks and ffprobe receipts" git commit -m "Slice transcript and chat by chunk" git commit -m "Run Gemini analysis for chunks 01-03" git commit -m "Add verification reports for chunks 01-03" git commit -m "Run omissions pass for chunk 01" git commit -m "Reconcile verified chunk analyses" git commit -m "Extract and review keyframe candidates" git commit -m "Assemble teammate follow-up packet" git commit -m "Document repeatable video follow-up process" ``` Default binary policy for future runs: - Commit text artifacts, manifests, prompts, logs, JSON, Markdown, reports, and checksums. - Do not commit large raw videos unless explicitly approved. - Commit chunk videos only for local archival projects or when Git LFS is configured. - Commit keyframes/contact sheets only when they are small enough and useful for review. Suggested `.gitignore` for future automation projects: ```gitignore runs/**/inputs/*.mp4 runs/**/inputs/*.mov runs/**/inputs/*.mkv runs/**/chunks/**/*.mp4 runs/**/chunks/**/*.mov !runs/**/inputs/*.sha256 !runs/**/receipts/** !runs/**/segments/** !runs/**/chunks/**/*.json !runs/**/chunks/**/*.md !runs/**/chunks/**/*.log !runs/**/final/** !runs/**/oracle/** runs/**/chunks/**/keyframes/extracted/*.jpg runs/**/chunks/**/keyframes/extracted/*.png runs/**/chunks/**/keyframes/strips/*.jpg runs/**/chunks/**/keyframes/contact-sheet*.jpg ``` If committing binaries intentionally: ```bash git add -f "$RUN_DIR/chunks/01/chunk.mp4" git add -f "$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg" ``` ## Oracle Session Receipts For every `$oracle-packx` call, save: ```text - slug - date - run id - browser mode: true - ChatGPT conversation URL - bundle path - bundle sha256 - prompt path - output log path - local decisions accepted/rejected - commit before - commit after ``` Template: ```markdown # Oracle Session: {{session_slug}} - date: - local_run: - browser_mode: true - session_url: - bundle_path: - bundle_sha256: - prompt_file: - output_file: - commit_before: - commit_after: ## Question ## Oracle Response Summary ## Local Decisions Accepted: Rejected: Follow-up: ``` ## Final Packet Review Treat these as first publication candidates: - `final/README.md` - `final/teammate-followup-guide.md` - `final/chapter-index.md` - `final/resources-and-links.md` - `final/instructor-review-checklist.md` Treat these as reference drafts until edited: - `final/qa-index.md` - `final/exercises.md` - `final/keyframes-manifest.md` Manual approval is mandatory for: - platform automation - browser automation - cookies - session replay - quota/rate-limit behavior - account credentials - private emails - private chat exports - meeting transcript bot URLs - teammate names - screenshots of private repos - local network addresses - QR codes - API keys - package security claims - third-party service recommendations - public publishing ## End-To-End Checklist Project setup: - [ ] Create run folder. - [ ] Copy source video into `inputs/`. - [ ] Copy transcript/chat/screenshots/clips if available. - [ ] Save source SHA256. - [ ] Save ffprobe source receipt. - [ ] Save tool versions. - [ ] Commit source evidence receipts. Long recording preprocessing: - [ ] Run `silencedetect`. - [ ] Review transcript and chat around silence spans. - [ ] Draft boundary candidates. - [ ] Create `segment-manifest.v1.json` and `.md`. - [ ] Bundle planning context with `$oracle-packx`. - [ ] Run Oracle review in browser mode. - [ ] Save Oracle session link/output locally. - [ ] Create `segment-manifest.v2.json` and `.md`. - [ ] Commit segmentation. Chunk creation: - [ ] Cut chunks from original video. - [ ] `ffprobe` every chunk. - [ ] Create `chunks/video-manifest.json`. - [ ] Slice transcript per chunk. - [ ] Slice chat per chunk. - [ ] Preserve break chat separately. - [ ] Add carry-forward chat to next spoken chunk. - [ ] Add next-chunk preview. - [ ] Commit chunk receipts and slices. Chunk analysis: - [ ] Create Gemini prompt per chunk. - [ ] Attach MP4, prompt, transcript, chat, carry-forward chat, and preview. - [ ] Save Gemini raw result/log. - [ ] Verify `END_OF_VIDEO_ANALYSIS` sentinel. - [ ] Extract all required information from the response into local artifacts. - [ ] Close the completed Gemini tab only after extraction and sentinel verification; leave active Gemini tabs and the browser profile alive. - [ ] Extract machine JSON. - [ ] Build `expected-items.json`. - [ ] Run coverage verification. - [ ] Run hallucination/timestamp/Q&A checks. - [ ] Run omissions pass if any gate fails. - [ ] Commit analysis and verification reports. Visual evidence: - [ ] Generate keyframe candidates. - [ ] Extract deterministic frames. - [ ] Extract Gemini-proposed frames. - [ ] Extract strips for visual demos. - [ ] Create contact sheet. - [ ] Review frames. - [ ] Downgrade unsupported visual claims. - [ ] Commit visual manifests/reviews. Reconciliation: - [ ] Merge main analysis, omissions, verification, and keyframe review. - [ ] Write `final-reconciled.md/json` per chunk. - [ ] Preserve warnings. - [ ] Remove malformed URLs. - [ ] Deduplicate carried-forward overlap. - [ ] Commit reconciled chunks. Final packet: - [ ] Generate final README. - [ ] Generate teammate guide. - [ ] Generate chapter index. - [ ] Generate resources and links. - [ ] Generate Q&A index. - [ ] Generate exercises. - [ ] Generate keyframes manifest. - [ ] Generate instructor checklist. - [ ] Run malformed URL scan. - [ ] Run URL resolution check if public. - [ ] Run final packet review. - [ ] Commit final packet. Process documentation: - [ ] Save this process as `docs/repeatable-video-followup-process.md`. - [ ] Inspect for exact commands, mode branches, prompts, and gates. - [ ] Commit process doc. ## Automation Responsibilities Review the process before automating it. These are proposed implementation boundaries, not supplied executables: ```text scripts/video-followup/init-run.ts scripts/video-followup/probe-source.ts scripts/video-followup/detect-silence.ts scripts/video-followup/build-segment-manifest.ts scripts/video-followup/cut-chunks.ts scripts/video-followup/slice-transcript.ts scripts/video-followup/slice-chat.ts scripts/video-followup/build-gemini-prompts.ts scripts/video-followup/extract-machine-json.ts scripts/video-followup/verify-coverage.ts scripts/video-followup/scan-malformed-urls.ts scripts/video-followup/extract-keyframes.ts scripts/video-followup/build-contact-sheet.ts scripts/video-followup/reconcile-chunk.ts scripts/video-followup/build-final-packet.ts templates/gemini/chunk-analysis.md templates/gemini/omissions.md templates/oracle/planning-review.md templates/oracle/final-review.md templates/final/README.md templates/final/teammate-followup-guide.md templates/final/chapter-index.md templates/final/resources-and-links.md templates/final/instructor-review-checklist.md docs/automation-roadmap.md ``` Automation priority: 1. Malformed URL scanner. 2. Timestamp validator. 3. Expected-items builder from chat/transcript. 4. Chunk prompt generator. 5. ffmpeg chunk cutter. 6. Keyframe extractor/contact sheet builder. 7. Final packet assembler. ## Operational boundaries - Apply the media/privacy ignore policy before the example staging command. Do not stage raw recordings, chats, transcripts, or account-bearing screenshots merely because they live under `inputs/`. - Automation file lists are proposed boundaries, not supplied programs. Template fields must be filled from real evidence, and a sentinel is a completion signal rather than proof of accuracy. - The video-capable provider, browser routing, model aliases, upload limits, and cleanup commands are integration-specific. Verify the attached-video readiness probe and retain uncertainty when evidence is missing. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-video-evidence-process Topic: Context Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Route large codebase questions through Oracle > Original source pages and recordings require authorized access. The full article text here is public. The practice is escaping Codex token and rate-limit pressure by separating huge read-only analysis from the interactive coding session. John shows that his ChatGPT Pro Extended browser session can accept far larger context than older sessions and, in his setup, does not consume the same Codex token budget; then he demonstrates Oracle plus PackX plus MCP/browser automation sending roughly 585,000 tokens from a codebase into ChatGPT on a separate Mac mini and bringing the result back into the workflow. ## Working outcomes - Route huge, read-heavy codebase questions to a browser ChatGPT session instead of burning Codex quota - Bundle dense repo context with PackX and hand it off via Oracle + an MCP/browser automation bridge - Drive a plan → implement → verify loop with Oracle on a separate high-context session ## Concepts and consequences ### Codex-to-browser quota offloading John explains that dense, high-context questions can be sent to ChatGPT Pro Extended in the browser instead of spending Codex's interactive token and rate-limit budget. He describes this as useful for complicated questions where you want a large amount of packed context. **Why it matters:** Large repo-reading prompts can burn through Codex limits quickly. Routing the heavyweight analysis to the browser keeps Codex available for the parts of the workflow that need an agent to continue acting. ### ChatGPT Pro Extended context window John says his $200-plan browser session exposes ChatGPT 5.5 Pro / Pro Extended with much longer context than before: he contrasts older ~50,000-token sessions with newer sessions that can take around a million tokens and often return in 10–15 minutes. **Why it matters:** The exact limits may change, but the taught idea is to notice that different surfaces have different context limits and to route work accordingly. ### Oracle browser handoff Oracle lets a current Codex session ask a browser session to do the heavy analysis: it packs things up, sends them to the browser, waits for the browser model to work, and then brings the result back into the coding session. **Why it matters:** This creates a handoff between a local agent workflow and a logged-in browser model without manually copying a massive prompt every time. ### PackX context bundling In the demo, John's Oracle PackX skill uses a pack tool to gather files related to a query. The run shown packs 45 files and reports roughly 585,000 tokens before sending the bundle to Oracle. **Why it matters:** PackX is the part of the workflow that turns scattered repo files into one large model-readable payload for the browser analysis pass. ### MCP/browser automation bridge After the context is packed, the workflow makes an MCP call that reaches over to a browser on John's Mac mini, opens the ChatGPT session, inserts the prompt, and submits it. **Why it matters:** The MCP step is the bridge that lets the current agent trigger the outside browser workflow instead of requiring John to manually paste the packed prompt. ### Plan, implement, verify loop John shows the broader pattern he uses: create a list of QA stories or goals, use Oracle to create a plan for each one, then implement it and verify it. **Why it matters:** The value is not just a one-off giant prompt; it is turning high-context planning into a repeatable loop that feeds back into actual code work. ## Reference tools and resources ### askoracle.sh Public Oracle landing page shared in the workshop chat. **Use when:** Use it to understand the baseline Oracle concept before comparing it with John's workshop-specific fork. [Reference](https://askoracle.sh/) ### John Lindquist's Oracle fork The fork John points developers to for his specific setup, including browser mode, cookie debugging guidance, agents setup help, and the Oracle PackX skill. **Use when:** Use it when trying to study or reproduce the exact workflow John demonstrated. [Reference](https://github.com/johnlindquist/oracle) ### PackX / pack tool The context-packing layer used by John's Oracle PackX skill to gather relevant files and produce the large token bundle shown in the demo. **Use when:** Use it when you need Oracle to send a bundled codebase context prompt into the browser model. [Reference](https://github.com/johnlindquist/oracle) ### Model Context Protocol The tool-bridge mechanism John names when the packed request is handed off from the current agent workflow to the browser automation path. **Use when:** Use it as background for understanding the MCP call in the Oracle demo, not as a separate MCP configuration lesson from this section. [Reference](https://modelcontextprotocol.io/) ## Recommendations and best practices - Use browser-side ChatGPT Pro Extended for huge, read-heavy codebase questions that would otherwise burn Codex context, but treat John's quota observations as his workshop setup rather than a permanent pricing or limit promise. - Use Oracle and PackX only when the request really needs a large repo bundle: PackX gathers the files, Oracle sends the bundle to the browser through MCP, and the answer comes back into the coding workflow. - Follow the fork's README, cookie-debugging, and agent setup guidance before trying to reproduce the browser workflow, because John says the setup is system-specific and may take effort. - Keep concurrency low. John says he would not run more than two or three browser requests at a time and has seen temporary pause popups after too many requests. - Shape repeat work as a loop: list the stories or goals, use Oracle to create a plan for each one, then implement and verify the result. ## Practice and acceptance criteria Practice routing huge code-reading questions through an Oracle/PackX browser pass while keeping Codex focused on orchestration, implementation, and verification. ### Checklist 1. Identify one Codex request in your workflow that is mostly large-scale reading or planning rather than immediate local editing. 2. Check whether your ChatGPT browser session and Codex session expose the same or different model surfaces, as John and the participants observed. 3. Review askoracle.sh and John's Oracle fork, especially the README, cookie-debugging guidance, agents file, and Oracle PackX skill. 4. Try the smallest version of the demo on a non-critical repo: ask for files related to one topic, let PackX build a bundle, and send it through Oracle/MCP to a browser session. 5. Bring the returned plan back into your coding workflow and have Codex implement and verify one concrete item. 6. Keep browser requests low-concurrency at first; use John's two-or-three-at-a-time guidance as the ceiling unless your own monitored setup proves otherwise. ### Design a Codex-vs-Oracle Routing Table **Difficulty:** Medium For one repo you actively use, list ten realistic AI requests and route each one to either the Codex session or an Oracle/browser analysis pass. Include a one-line reason for each route. **Done when:** Your table keeps local implementation and verification in the Codex workflow while moving huge read-only analysis to the Oracle/browser lane. ### Recreate a Small Oracle Pass **Difficulty:** Hard Using a small, non-critical repo, follow the Oracle fork guidance to send one topic-focused codebase question through the PackX → Oracle → MCP/browser path. **Done when:** You can point to the packed bundle/token count, the browser-submitted question, and the returned answer that came back into the workflow. ### Build a Plan-Implement-Verify Loop **Difficulty:** Hard Create three QA stories or goals for a repo. For each one, use Oracle to create the plan, then have the coding session implement the chosen change and verify it. **Done when:** Each story has an Oracle-generated plan, an implementation step, and a verification result. ## Questions to test understanding ### What problem is John mainly trying to solve with the Oracle + ChatGPT browser workflow? - **A.** Replacing all coding work with a workshop archive. - **B.** Moving dense, high-context analysis out of Codex so it does not burn the same Codex token and rate-limit budget. - **C.** Making Codex run tests faster by skipping browser sessions. - **D.** Avoiding the need to pack repository files at all. **Answer: B.** John frames the workflow as a way to send huge context to ChatGPT Pro Extended in the browser while preserving Codex's interactive budget for ongoing work. ### What does Oracle primarily do in the demonstrated workflow? - **A.** It stores the workshop recording and screenshots for later search. - **B.** It replaces the local code editor. - **C.** It lets the current Codex session send packed context to a browser model and bring the result back. - **D.** It chooses the cheapest API model for every request. **Answer: C.** John describes Oracle as the bridge from the current Codex session to the browser: pack things up, send them to the browser, let the browser work, then bring the answer back. ### In the Oracle + PackX + MCP pattern shown in the demo, what does PackX primarily contribute? - **A.** It decides which model is cheapest at runtime. - **B.** It packs relevant repository files into a large model-readable context bundle and estimates its size. - **C.** It runs the test suite after Codex applies changes. - **D.** It schedules workshop breaks. **Answer: B.** PackX is the context-packing layer: in the demo it gathers files related to the search topic and reports a roughly 585,000-token bundle. ### What is the safest way to understand the workshop's claim about ChatGPT Pro Extended versus Codex token mechanics? - **A.** Assume browser-side work is permanently unlimited and free. - **B.** Treat the pricing and limits as a snapshot, but keep the architecture idea: separate high-context analysis from the Codex budget when possible. - **C.** Move all work out of Codex because Codex is only useful for small prompts. - **D.** Use browser automation specifically to bypass platform rules. **Answer: B.** The durable lesson is routing work across surfaces with different context and quota behavior. Account plans, rate limits, and platform behavior can change. ### What practical limit did John mention for running these browser-based requests? - **A.** Never run more than one request per week. - **B.** Run as many parallel requests as possible because there are no pauses. - **C.** Keep it to about two or three at a time because too many requests can trigger a temporary pause. - **D.** Only run the workflow through the workshop archive. **Answer: C.** John says he has hit popups after too many requests and would not do more than two or three at a time. ## Reflection prompts - Which of your current Codex requests are really huge-context reading or planning tasks? - Where would an Oracle browser pass be useful in your workflow, and where would it be overkill? - What concurrency limit would you set so browser automation remains monitorable and does not trigger the pause behavior John described? - Would a separate machine, browser profile, or dedicated screen make this workflow less disruptive for you, the way John's Mac mini did for him? ## Further applications 1. Read askoracle.sh to understand the general Oracle idea before studying John's fork. 2. Review John's Oracle fork with attention to the README, cookie-debugging instructions, agents file, and Oracle PackX skill. 3. Recreate the demonstrated flow on a small, non-critical repo: ask for files related to one topic, let PackX build the bundle, send it through Oracle, and compare the returned plan with what Codex can implement. 4. Test your own account behavior cautiously with one browser request first, then increase only if you can monitor it and avoid the pause behavior John described. ## Applied exercises ### Exercise 1: Set Up an Automated Remote Browser Prompt Agent **Objective:** Configure an isolated environment to programmatically inject codebase scripts into a standard browser instance using local session cookies. **Setup:** Clone the custom tracking engine fork from [https://github.com/johnlindquist/oracle](https://github.com/johnlindquist/oracle).Authenticate into an active web-based chat account inside your system's primary browser layout. **Task:** Execute the repository bundle scripts to pinpoint and read structural active authentication cookies (cookie debugging step).Use the provided automated templates via the repository agents instructions to link your workspace context directly with an active automation host loop.Execute a context collection command across a folder path of choice containing multiple files, ensuring the terminal processes and shifts token management completely to the browser interface window. **Acceptance Check:** Verification is complete when text fields inside the separate browser app update and execute queries hands-free without using direct local API credentials. **Estimated Difficulty:** Hard. ## Questions and answers ### /goal is causing me to hit my rate limits. Any ideas on how to optimize the token usage when running goal? John addresses this broadly by showing how to move complex context out of direct local execution bounds and offloading it through the browser-driven Oracle process. This lets you execute large analytical loops outside your standard account limits. ### Is this MCP only limited to ChatGPT, or can we also use Gemini? John details that his specific, customized structural additions in his personal fork focus heavily on ChatGPT integration because it bypasses the Codex quota. He notes the original baseline repository includes Gemini mechanics, though he hasn't personally validated that loop. However, since the engine operates by automating browser elements, it can theoretically hook any session (Perplexity, Devin, etc.) by extracting local browser session cookies. ## Operational playbooks - [Oracle handoff for a huge codebase question](/topics/foundations-oracle-handoff-playbook/) - [Oracle + PackX Handoff Field Guide](/topics/foundations-oracle-packx-field-guide/) ## Recording references - [Recording part 1](https://codex-workshop-followup.pages.dev/video/lessons/lesson-01-part-01.mp4) - [Recording part 2](https://codex-workshop-followup.pages.dev/video/lessons/lesson-01-part-02.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-01.html) ### Visual reference index - [00:11:18](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-1): Visual reference at this recording position. - [00:21:55](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-2): Visual reference at this recording position. - [00:23:48](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-3): Visual reference at this recording position. - [00:10:55](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-4): Visual reference at this recording position. - [00:11:40](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. NotebookLM appears as context, not a taught implementation workflow. - [00:15:10](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. - [00:19:28](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. - [00:20:56](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. - [00:22:25](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. - [00:30:10](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. Reference ID: foundations-oracle-context-routing Topic: Context Sources: - [Agent foundations: Route large codebase questions through Oracle (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-01.html) --- # Turn recordings into video evidence packets A long recording is not one prompt. It is a pile of evidence with a timeline. Do not reduce it to a transcript too early. Keep the video as prompt material, cut the recording into chunks, send each chunk through the video-watching lane, extract screen evidence while it is still visible, and carry prior summaries forward. The artifact you want is not a summary. It is a **video evidence packet**. ## The Failure A five-hour workshop, app walkthrough, or bug reproduction contains too much visual detail for one tidy answer. If one model response has to summarize the whole recording, it will usually flatten the exact details software work needs: - tooltip text - disabled button states - cursor actions - modal transitions - terminal output - code snippets - missing steps - retries and failed attempts - loading, error, and empty states The problem is not only upload size. The problem is **answer density**. One huge answer cannot carry every useful screen fact. > It's very difficult to get good information out of it that way, because it's limited by the amount of tokens it can provide in one response. > > — John Lindquist ## The Move Create video evidence packets. A video evidence packet is a **chunked, source-preserving record** of what happened in a slice of video: - clip - transcript slice - chat slice - key frames - visible text - UI states - actions - code snippets or terminal output - omissions - model output - verification notes The packet gives the next agent inspectable context without pretending it watched the whole recording. ## Keep The Video Video is not just a transcript with pictures nearby. For UI work, the screen matters. A tooltip, hover state, selected tab, disabled button, cursor path, dialog, terminal frame, or loading spinner can be the evidence. Keep the clip attached as prompt material until the visual claims have been extracted and checked. In the demonstrated workflow, the local agent owned the files, prompts, saved outputs, and verification. **[Oracle](https://github.com/johnlindquist/oracle)** handled the browser handoff. **[Gemini](https://gemini.google.com/app)** was the video-watching lane for that run. The repo received the output as reviewable files. Treat exact model behavior, limits, quotas, pricing, and account budget as current-product details that must be rechecked before relying on them in shared guidance. ## Chunk By Evidence Density Use chunks small enough that each answer can stay specific. > What you can do with an agent is split the video into, like, 15-minute chunks, and then in each of those chunks, you can say, what are the key frames, what are the key ideas, what are the key transcript points. > > — John Lindquist Fifteen minutes is a reasonable default for workshop or walkthrough material. Five minutes can be useful when the screen is dense, the bug is subtle, or the output needs frame-level detail. Do not turn those numbers into doctrine. **Choose chunk size by evidence density.** Before analysis, remove confirmed dead space when it is safe: - long silence - blank screens - motionless regions - breaks - inactive spans Do not delete chat, links, questions, or setup context that explains the next spoken section. Carry that forward. ## Ask For Screen Evidence Use the same evidence lanes for each chunk. ```text For this video chunk, extract: Visual evidence: - key frames - visible text - UI states - cursor actions - modal/dialog states - loading/error/empty states - code snippets or terminal output - colors, layout shifts, and visual changes Transcript evidence: - key spoken points - claims made - instructions given - unanswered questions - deferred follow-ups Action evidence: - user actions - app responses - navigation steps - failed attempts - retries - omissions or confusing transitions Verification: - what is directly visible - what is transcript-supported - what is inferred - what needs manual review ``` This is the difference between "the user clicked around" and "the tooltip text appeared next to the control, then the follow-up prompt asked what it said." ## Carry Prior Chunks Forward Chunking solves the density problem and creates a **continuity problem**. Fix that by carrying a compact **previous-summary ledger** into every later prompt: ```text You are analyzing chunk 10 of 15 from a long software workshop. Previous chunk summary: - Chunk 01 introduced the repo and evidence boundary. - Chunk 02 covered agent-ready repo setup. - Chunk 03 covered narrow workspace agents. - Chunk 04 covered generated variations. - Chunk 05 covered visual review before implementation. For this chunk: - preserve original timestamps - extract visible UI states, actions, text, code snippets, and omissions - separate transcript evidence, visual evidence, and inference - return a chunk summary that can be carried into the next prompt ``` Every later chunk should know what came before it: active concepts, unresolved questions, decisions already made, and what the current chunk must not re-explain. ## Use It For Software Work Good fits: - QA records a checkout regression and the packet extracts the disabled button state, selected shipping option, console error, and missing validation message. - A designer records a settings walkthrough and the packet extracts empty states, modal transitions, keyboard traps, contrast concerns, and confusing copy. - A product team records its own onboarding flow and the packet turns it into acceptance criteria. - A developer combines a debug marker packet with the video chunk around the marked moment. Product research also fits, but keep the ethics boundary clear. Use public walkthroughs for UX critique, accessibility review, flow comparison, and internal design study. Do not present this as a way to copy proprietary UI, assets, copy, CSS, or product behavior. ## Copyable Artifact: Video Evidence Packet ```text Source: - recording: - source hash: - original timestamp range: - transcript slice: - chat slice: - chunk id: - prior summary included? yes/no Preprocessing: - silence reviewed: - motionless/blank spans reviewed: - removed spans: - carried-forward chat/questions: Ask the video model to extract: - key frames: - visible text: - transcript points: - user actions: - UI states: - code snippets or terminal output: - colors/layout changes: - loading/error/empty states: - omissions: - uncertainties: Cumulative context: - previous chunks summarized: - unresolved questions: - concepts already introduced: - what this chunk must not re-explain: Verification: - claims supported by transcript: - claims supported by visual evidence: - claims supported by chat: - claims that are inference only: - private details removed: - screenshots/keyframes sanitized: - model/cost/limit claims removed or verified: ``` Example prompt: ```text Analyze this checkout bug recording as chunk 03 of 08. Previous summary: [paste compact prior-summary ledger] Extract: - visible UI states - cursor actions - selected fields - loading/error/empty states - visible text - transcript claims - omitted steps - uncertainties Separate visual evidence, transcript evidence, chat evidence, and inference. Return a short carry-forward summary for the next chunk. ``` ## Claim Boundaries This workflow does not prove model limits, pricing, quota behavior, speed, or model superiority. It proves that a recording was processed through a chunked, source-preserving workflow and that shared claims can be checked against transcript, video evidence, key frames, chat, and saved outputs. Before sharing screenshots or key frames, sanitize them, copy them into the shared asset tree, add alt text, and review for private browser/account state. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#video-packets) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-video-packets Topic: Context Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#video-packets) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Video analysis and evidence workflows: practical reference ## Agent Setup Prompt ```text Set up a repeatable video-as-prompt run for this project before doing any full video analysis. 1. Resolve the `oracle-video` skill first. Check for `skills/oracle-video/SKILL.md`; if it is not bundled, check the common local install path at `.agents/skills/oracle-video/SKILL.md`. Read the skill and any directly referenced repeatable video process file before creating outputs. If the skill is missing, stop and report the missing path checks. 2. Create a run id like `-` and a run folder at `runs//` with this structure: `inputs/`, `receipts/`, `chunks/01/`, `analysis/`, `final/`, `keyframes/`, and `contact-sheets/`. 3. Accept either a local video path or a video URL. For a local file, copy it to `inputs/source-video.` and keep that copy immutable. For a URL, first save metadata with `yt-dlp --dump-single-json --skip-download --no-check-formats` to `receipts/source.metadata.json`, then download with `yt-dlp -f "bv*+ba/best"` into `inputs/`. 4. Write a source hash with `shasum -a 256` to `inputs/source-video.sha256`. Confirm the file exists and is non-empty. 5. Capture media facts with `ffprobe -hide_banner -show_format -show_streams -of json` and save them to `receipts/ffprobe.source.json`. Confirm the file exists and is non-empty. If `ffprobe`, `ffmpeg`, or `yt-dlp` is missing, stop setup and report the missing tool plus the failed command. 6. Prepare `chunks/01/chunk.mp4`. For a short video, copy the source video into that path. For a long video, create additional numbered chunk folders as needed and save a timestamp mapping note before any analysis. Use absolute paths for every video file that will be attached to Oracle. 7. Write `chunks/01/gemini-prompt.md`. It must request separate lanes for transcript evidence, chat evidence, visual evidence, and inference. It must require preserved timestamps, forbid invented URLs, tools, commands, files, UI labels, and speakers, and end with the exact final line `END_OF_VIDEO_ANALYSIS`. 8. Write `chunks/01/expected-sentinel.txt` containing only `END_OF_VIDEO_ANALYSIS`. Confirm the sentinel appears in `gemini-prompt.md` and that the expected sentinel file is non-empty. 9. Prepare `chunks/01/oracle-call.json` or equivalent setup notes with the required Gemini browser-mode contract: `engine: "browser"`, `model: "gemini-3-pro"`, `browserAttachments: "always"`, `files` containing an absolute path to `chunks/01/chunk.mp4`, and a stable slug. Do not use API mode for video analysis. 10. Generate keyframes and a contact sheet if `ffmpeg` is available. Save frames under `keyframes/` using a low-frequency extraction such as `fps=1/10`, then save a tiled contact sheet under `contact-sheets/`. If generation is skipped, save the exact commands to run later and report why they were not run. 11. Create evidence lane files under `analysis/`: `transcript.md`, `chat.md`, `visual-evidence.md`, and `inference.md`. Keep spoken claims, chat or comments, visible facts, and reasoned conclusions separate. Label inference clearly until code, runtime behavior, or visual checks support it. 12. Create `analysis/omissions-pass-prompt.md`. It should ask only for missing visible UI states, skipped timestamps, unsupported claims, invented details, uncertainty, and patch-style corrections. It must require the response to end with `END_OF_VIDEO_ANALYSIS`. 13. Create downstream artifact stubs under `final/`, such as `implementation-prompt.md`, `qa-checklist.md`, and `variation-matrix.md`. Leave evidence-dependent fields blank until verified analysis exists. 14. Enforce privacy boundaries before any upload or external analysis. Do not print full environment output, tokens, cookies, API keys, private endpoints, resolved secret values, or raw private config. Do not copy secret helper files into the run folder. If the video, metadata, transcript, or chat text contains credentials or private config, stop and report the issue instead of uploading. 15. Run a setup verification gate before Gemini analysis. Report `OK` or `MISSING` for: `oracle-video` skill resolved, source video exists, source hash non-empty, `ffprobe.source.json` non-empty, URL metadata present when the input is a URL, chunk file exists, Gemini prompt exists, sentinel file exists, Oracle call uses browser mode with `gemini-3-pro` and `browserAttachments: "always"`, Oracle file path is absolute, evidence lane files exist, keyframes/contact sheet exist or commands are saved, omissions prompt exists, and downstream stubs exist. 16. Stop before full video analysis unless every required setup check passes. Return the run id, absolute run folder path, commands run, verification report, failed checks, and the smallest next fix if anything is missing. Only say it is ready for Gemini analysis after the setup gate passes. ``` ## Big Idea Video is prompt material. ## Try This Now For a short bug repro video, create a run folder and save a source hash. Write the Gemini prompt with separate lanes: transcript, chat, visual evidence, inference. End the prompt with `END_OF_VIDEO_ANALYSIS` before analysis starts. A screen recording can show things a written prompt usually loses: - order of operations - cursor movement - hesitation - timing - hidden assumptions - actual UI state - terminal output - visible browser pages - misclicks - loading states - visual hierarchy - broken affordances - spoken explanation - chat context A transcript can tell you what someone said. A video can show what happened. ## Tool Reference Use `oracle-video` when the task depends on what is visible or audible in a recording. Conceptually: ```text oracle-packx bundles code/text context for ChatGPT. oracle-video attaches video and sends it to Gemini through Oracle browser mode. ``` Correct Oracle call shape for video analysis: ```js mcp__oracle__consult({ prompt: "[video-analysis-slug]\n\n{contents of chunks/01/gemini-prompt.md}", files: ["/absolute/path/to/runs/bug-repro/chunks/01/chunk.mp4"], engine: "browser", model: "gemini-3-pro", browserAttachments: "always", slug: "video-analysis-slug" }) ``` Required: ```text engine: "browser" model: "gemini-3-pro" browserAttachments: "always" absolute file path ``` Do not use API mode for video analysis. ## When To Reach For This Use video when the important context is visible, temporal, or hard to describe. | Use Video For | Why | | --- | --- | | bug reproduction clip | captures exact UI state, clicks, errors, timing | | design feedback video | preserves visual hierarchy and spoken intent | | app walkthrough | turns observed workflow into requirements and QA checks | | loading/timing bug | shows delay, spinner, race, or order of events | | terminal/browser workflow | preserves commands, pages, output, and sequence | | long tutorial or workshop recording | can become chapters, exercises, references, and follow-up prompts | Skip video when: - a short log already proves the issue - a failing test names the exact bug - the needed context is one code path - the video source cannot be preserved - claims cannot be verified against timestamps, keyframes, or source output ## How This Used To Work What you used to expect: ```text Watch the video, summarize from memory, then ask the agent to fix the vague thing. ``` What the workflow gives you now: ```text Preserve the source, capture hashes and media facts, analyze with Gemini, keep evidence lanes separate, verify claims, then turn the result into a grounded prompt. ``` What you used to expect: ```text A transcript is the prompt. ``` What the workflow gives you now: ```text The transcript is one evidence lane. Visual state, timing, chat, cursor motion, and inference stay separate until verified. ``` ## Core Pattern ```text source media -> source receipts -> Gemini analysis -> evidence lanes -> verification -> downstream prompt ``` Do not skip the middle. ```text video without source receipts = hard to trust analysis without timestamps = hard to verify transcript without visuals = incomplete claims without keyframes = risky prompt without verification = hallucination bait ``` ## Short Path vs Long Path | Path | Use For | Shape | | --- | --- | --- | | short path | bug repros, design feedback clips, quick app walkthroughs | preserve source, one Gemini pass, keyframes, downstream artifact | | long path | long tutorials, workshop recordings, multi-section demos | source receipts, segment/chunk, analyze chunks, omissions pass, reconcile, final packet | Short path output examples: - repro steps - implementation prompt - design-change brief - QA checklist - requirements note Long path output examples: - chapter index - lesson notes - exercise packet - resource list - follow-up prompts - Section 6 variation matrix ## Run Folder Shape Use a run folder so the video stays tied to its analysis. ```text runs/-/ inputs/ source-video.mp4 source-video.sha256 receipts/ ffprobe.source.json chunks/ 01/ chunk.mp4 gemini-prompt.md expected-sentinel.txt output.log analysis.md analysis/ final/ keyframes/ contact-sheets/ ``` Create the folders: ```bash RUN_ID="checkout-repro" RUN_DIR="runs/$RUN_ID" mkdir -p "$RUN_DIR"/{inputs,receipts,analysis,final,keyframes,contact-sheets} mkdir -p "$RUN_DIR/chunks/01" ``` ## Preserve The Source Keep the original media immutable. For a local file: ```bash cp /path/to/source-video.mp4 "$RUN_DIR/inputs/source-video.mp4" shasum -a 256 "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/inputs/source-video.sha256" ``` For a URL source, capture metadata first when useful: ```bash yt-dlp --dump-single-json --skip-download --no-check-formats "$URL" \ > "$RUN_DIR/receipts/source.metadata.json" ``` Then download: ```bash yt-dlp -f "bv*+ba/best" -o "$RUN_DIR/inputs/source-video.%(ext)s" "$URL" ``` Capture media facts: ```bash ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` Confirm: ```bash test -s "$RUN_DIR/inputs/source-video.sha256" && echo "sha256:OK" test -s "$RUN_DIR/receipts/ffprobe.source.json" && echo "ffprobe:OK" ``` ## Evidence Lanes Keep these lanes separate: | Lane | What It Means | Example | | --- | --- | --- | | transcript | spoken words | “The save button disappears.” | | chat | chat messages or comments | “This only happens after refresh.” | | visual evidence | visible UI state | save button hidden at `00:01:34` | | inference | reasoned conclusion | likely state reset after token refresh | Plain rule: ```text A spoken claim is not a visible fact. A visible fact is not automatically the cause. An inference must stay labeled until code or runtime proof confirms it. ``` ## Prompt With A Sentinel Save the Gemini prompt beside the chunk. ```bash cat > "$RUN_DIR/chunks/01/gemini-prompt.md" <<'EOF' Analyze this video as prompt material for a software project. Return: 1. short summary 2. timestamped workflow 3. transcript evidence 4. chat evidence 5. visual evidence 6. inferences, clearly labeled 7. likely downstream artifacts 8. omissions or uncertainty Rules: - Do not invent URLs, tools, commands, files, UI labels, or speakers. - Preserve original timestamps. - Separate visible facts from spoken claims and inferences. - Include the exact sentinel below as the last line. END_OF_VIDEO_ANALYSIS EOF printf 'END_OF_VIDEO_ANALYSIS\n' \ > "$RUN_DIR/chunks/01/expected-sentinel.txt" ``` Confirm: ```bash rg -n "END_OF_VIDEO_ANALYSIS" "$RUN_DIR/chunks/01/gemini-prompt.md" test -s "$RUN_DIR/chunks/01/expected-sentinel.txt" && echo "sentinel:OK" ``` ## Analyze With Gemini Use Oracle browser mode and attach the video. ```js mcp__oracle__consult({ prompt: "[checkout-repro-video]\n\n{contents of runs/.../chunks/01/gemini-prompt.md}", files: ["/absolute/path/to/runs/checkout-repro/chunks/01/chunk.mp4"], engine: "browser", model: "gemini-3-pro", browserAttachments: "always", slug: "checkout-repro-video" }) ``` After the run, read the local output: ```bash sed -n '1,220p' ~/.oracle/sessions/checkout-repro-video/output.log rg -n "END_OF_VIDEO_ANALYSIS" ~/.oracle/sessions/checkout-repro-video/output.log ``` If the output is clipped in a tool response, treat `output.log` as the local source to inspect. ## Verify The Analysis Check that the answer is grounded. | Check | Command Or Evidence | | --- | --- | | source hash exists | `test -s "$RUN_DIR/inputs/source-video.sha256"` | | media facts exist | `test -s "$RUN_DIR/receipts/ffprobe.source.json"` | | prompt saved | `test -s "$RUN_DIR/chunks/01/gemini-prompt.md"` | | sentinel present | `rg -n "END_OF_VIDEO_ANALYSIS" output.log` | | timestamps preserved | compare analysis timestamps to source duration | | visual claims checked | keyframes or contact sheet | | invented facts removed | no unsupported URLs/tools/commands/files | | omissions captured | missing sections are listed as uncertainty | Extract keyframes for visual checks: ```bash mkdir -p "$RUN_DIR/keyframes" ffmpeg -i "$RUN_DIR/inputs/source-video.mp4" \ -vf "fps=1/10" \ "$RUN_DIR/keyframes/frame-%04d.jpg" ``` Create a contact sheet: ```bash ffmpeg -pattern_type glob -i "$RUN_DIR/keyframes/*.jpg" \ -vf "scale=320:-1,tile=4x4" \ "$RUN_DIR/contact-sheets/source-contact-sheet.jpg" ``` ## Omissions Pass Run an omissions pass when coverage is incomplete. Ask: ```text Review the prior video analysis for omissions. Focus only on missing visible UI states, skipped timestamps, unsupported claims, invented details, and uncertainty. Do not rewrite the whole analysis. Return a patch-style list of corrections and end with END_OF_VIDEO_ANALYSIS. ``` Use the omissions pass when: - the first analysis only summarizes the transcript - key UI states are missing - timestamps are vague - the model invents tools, URLs, files, or labels - a long recording was not chunked - the downstream prompt depends on visual details ## Turn Video Into Prompt Material Common downstream artifacts: | Video Source | Downstream Artifact | | --- | --- | | bug reproduction | repro steps, expected vs actual behavior, implementation prompt | | design feedback | visual acceptance criteria, change brief, QA checklist | | app walkthrough | requirements, acceptance criteria, open questions | | terminal workflow | command sequence, failure point, debugging prompt | | long recording | chapters, exercises, resources, follow-up packet | | UI alternatives | Section 6 variation matrix | Bug prompt shape: ```markdown # Implementation Prompt From Video ## Source - video: - source hash: - ffprobe: - analysis: - keyframes: ## Observed Failure - timestamp: - visual evidence: - transcript/chat evidence: - expected behavior: - actual behavior: ## Request Implement the smallest safe fix. ## Constraints - do not change: - preserve: ## Verification - command: - what passing means: ``` Variation seed shape: ```markdown # Video-Derived Variation Matrix ## Goal ## Evidence From Video - timestamp: - observation: - keyframe: - why it matters: ## Invariants - same source evidence: - same target flow: - same verification command: - same review criteria: ## Variable Under Test - variable: - why this variable matters: - what is out of scope: ``` ## Ask The Agent This Analyze a bug reproduction: ```text Use the video analysis workflow. Preserve the source video, save a source hash and ffprobe output, write a Gemini prompt with END_OF_VIDEO_ANALYSIS, analyze the video through Oracle browser mode with Gemini, then separate transcript evidence, visual evidence, chat evidence, and inference. Turn the verified result into repro steps and an implementation prompt for the smallest safe fix. ``` Review design feedback: ```text Turn this design feedback video into a change brief. Keep visible UI facts separate from spoken opinions. Save keyframes for the visual claims. Produce acceptance criteria, a QA checklist, and open questions. Do not invent UI labels or routes that are not visible or spoken. ``` Create a Section 6 seed: ```text Use this verified video analysis to create a controlled variation matrix. Choose one variable under test, preserve the same source evidence and verification command for every candidate, and write three candidate settings. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | source preserved | original media exists under `inputs/` | | source hash saved | `source-video.sha256` exists and is non-empty | | media facts saved | `ffprobe.source.json` exists | | prompt saved | `chunks/01/gemini-prompt.md` exists | | sentinel required | `expected-sentinel.txt` exists | | Oracle call shape correct | `engine: "browser"`, `model: "gemini-3-pro"`, `browserAttachments: "always"` | | output inspected | `~/.oracle/sessions//output.log` read | | sentinel present | `END_OF_VIDEO_ANALYSIS` found in output | | lanes separated | transcript, chat, visual evidence, inference are separate | | visual claims checked | keyframes/contact sheet exists | | unsupported claims removed | no invented URLs/tools/commands/files | | downstream artifact saved | repro, requirements, QA, brief, lesson, or matrix exists | ## If It Goes Wrong ### No Source Hash Create it before analysis: ```bash shasum -a 256 "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/inputs/source-video.sha256" ``` ### No `ffprobe` Output Run: ```bash ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` ### Oracle Call Used API Mode Rerun with browser mode. ```text engine: "browser" model: "gemini-3-pro" browserAttachments: "always" ``` ### File Path Was Relative Use an absolute video path in `files`. ```bash realpath "$RUN_DIR/chunks/01/chunk.mp4" ``` ### Sentinel Missing Read `output.log`. If the sentinel is truly missing, rerun or ask for an omissions pass. ```bash rg -n "END_OF_VIDEO_ANALYSIS" ~/.oracle/sessions//output.log ``` ### Analysis Only Summarizes Transcript Run an omissions pass focused on visual evidence: ```text Find missing visual UI states, cursor actions, timing, browser/terminal state, and unsupported claims. Preserve timestamps. ``` ### Visual Claim Has No Keyframe Extract keyframes or create a contact sheet. Downgrade unsupported claims to inference. ### URL, Tool, Command, Or File Appears Without Evidence Remove it or label it as inference. Do not let invented details become prompt constraints. ### Long Recording Was Not Chunked Create chunks and analyze them separately. Preserve original timestamps across chunks. ## References And Resources - `oracle-video` local skill: `skills/oracle-video/SKILL.md` if bundled, or common local skill install under `.agents/skills/oracle-video/SKILL.md` - `yt-dlp`: https://github.com/yt-dlp/yt-dlp - FFmpeg documentation: https://ffmpeg.org/documentation.html - `ffprobe` documentation: https://ffmpeg.org/ffprobe.html - Gemini app: https://gemini.google.com/app ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-video-workflows-reference Topic: Context Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Video analysis and evidence workflows: practice drills These exercises practice turning video into verified prompt material. Use a short clip when possible. A 30-90 second bug reproduction or design feedback clip is enough. ## Exercise 1: Decide Whether Video Is Useful Choose `video`, `text/log`, or `code context`. | Scenario | Best Input | Why | | --- | --- | --- | | checkout button disappears after a sequence of clicks | | | | unit test failure points to one function | | | | designer explains spacing problems while moving through UI | | | | terminal command prints one clear stack trace | | | | app feels slow after refresh but logs are clean | | | | long tutorial should become exercises and references | | | | auth/session architecture needs cross-file review | | | Fill out: ```markdown # Input Choice - scenario: - chosen input: - why: - what video would add: - what text/logs would add: - what code context would add: ``` ## Exercise 2: Create The Run Folder Run: ```bash RUN_ID="exercise-video-$(date +%Y%m%d-%H%M%S)" RUN_DIR="runs/$RUN_ID" mkdir -p "$RUN_DIR"/{inputs,receipts,analysis,final,keyframes,contact-sheets} mkdir -p "$RUN_DIR/chunks/01" find "$RUN_DIR" -maxdepth 3 -type d | sort ``` Fill out: ```markdown # Video Run Folder - run id: - run dir: - inputs: - receipts: - chunks: - analysis: - final: - keyframes: ``` ## Exercise 3: Preserve Source Media For a local video: ```bash cp /path/to/source-video.mp4 "$RUN_DIR/inputs/source-video.mp4" shasum -a 256 "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/inputs/source-video.sha256" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` For a URL: ```bash yt-dlp --dump-single-json --skip-download --no-check-formats "$URL" \ > "$RUN_DIR/receipts/source.metadata.json" yt-dlp -f "bv*+ba/best" -o "$RUN_DIR/inputs/source-video.%(ext)s" "$URL" ``` Confirm: ```bash test -s "$RUN_DIR/inputs/source-video.sha256" && echo "sha256:OK" test -s "$RUN_DIR/receipts/ffprobe.source.json" && echo "ffprobe:OK" ``` Fill out: ```markdown # Source Media Notes - source path or URL: - local video path: - sha256 path: - ffprobe path: - original duration: - original timestamps preserved? yes/no ``` ## Exercise 4: Write The Gemini Prompt Run: ```bash cat > "$RUN_DIR/chunks/01/gemini-prompt.md" <<'EOF' Analyze this video as prompt material for a software project. Return: 1. short summary 2. timestamped workflow 3. transcript evidence 4. chat evidence 5. visual evidence 6. inferences, clearly labeled 7. likely downstream artifacts 8. omissions or uncertainty Rules: - Do not invent URLs, tools, commands, files, UI labels, or speakers. - Preserve original timestamps. - Separate visible facts from spoken claims and inferences. - Include the exact sentinel below as the last line. END_OF_VIDEO_ANALYSIS EOF printf 'END_OF_VIDEO_ANALYSIS\n' \ > "$RUN_DIR/chunks/01/expected-sentinel.txt" rg -n "END_OF_VIDEO_ANALYSIS" "$RUN_DIR/chunks/01/gemini-prompt.md" ``` Fill out: ```markdown # Gemini Prompt Notes - prompt path: - sentinel: - required lanes: - forbidden inventions: - timestamp rule: - uncertainty rule: ``` ## Exercise 5: Check Oracle Call Shape Write the call shape with an absolute video path. ```js mcp__oracle__consult({ prompt: "[exercise-video-analysis]\n\n{contents of chunks/01/gemini-prompt.md}", files: ["/absolute/path/to/runs//chunks/01/chunk.mp4"], engine: "browser", model: "gemini-3-pro", browserAttachments: "always", slug: "exercise-video-analysis" }) ``` Fill out: ```markdown # Oracle Video Call Shape - engine: - model: - browserAttachments: - file path absolute? yes/no - slug: - why API mode is wrong: ``` ## Exercise 6: Separate Evidence Lanes Use a video analysis result or a short mock result. Fill the lanes separately. ```markdown # Evidence Lanes ## Transcript Evidence - timestamp: - quote or paraphrase: ## Chat Evidence - timestamp: - message: ## Visual Evidence - timestamp: - visible fact: - keyframe: ## Inference - inference: - based on: - confidence: - what would confirm it: ``` Question: ```text Which claims are visible facts, and which are only spoken claims or inferences? ``` ## Exercise 7: Verify The Analysis Run checks against the saved files. ```bash test -s "$RUN_DIR/inputs/source-video.sha256" && echo "source-hash:OK" test -s "$RUN_DIR/receipts/ffprobe.source.json" && echo "ffprobe:OK" test -s "$RUN_DIR/chunks/01/gemini-prompt.md" && echo "prompt:OK" test -s "$RUN_DIR/chunks/01/expected-sentinel.txt" && echo "sentinel-file:OK" ``` If Oracle output exists: ```bash rg -n "END_OF_VIDEO_ANALYSIS" ~/.oracle/sessions//output.log ``` Fill out: ```markdown # Analysis Verification - source hash exists? yes/no - ffprobe exists? yes/no - prompt exists? yes/no - sentinel required? yes/no - sentinel found in output? yes/no - timestamps preserved? yes/no - unsupported URLs/tools/commands removed? yes/no - visual claims have keyframes? yes/no ``` ## Exercise 8: Extract Keyframes Run: ```bash mkdir -p "$RUN_DIR/keyframes" ffmpeg -i "$RUN_DIR/inputs/source-video.mp4" \ -vf "fps=1/10" \ "$RUN_DIR/keyframes/frame-%04d.jpg" find "$RUN_DIR/keyframes" -type f | head ``` Optional contact sheet: ```bash ffmpeg -pattern_type glob -i "$RUN_DIR/keyframes/*.jpg" \ -vf "scale=320:-1,tile=4x4" \ "$RUN_DIR/contact-sheets/source-contact-sheet.jpg" ``` Fill out: ```markdown # Keyframe Notes - keyframe folder: - contact sheet: - visual claim checked: - timestamp: - confirmed? yes/no ``` ## Exercise 9: Write An Omissions Pass Prompt Run: ```bash cat > "$RUN_DIR/analysis/omissions-prompt.md" <<'EOF' Review the prior video analysis for omissions. Focus only on missing visible UI states, skipped timestamps, unsupported claims, invented details, and uncertainty. Do not rewrite the whole analysis. Return a patch-style list of corrections and end with END_OF_VIDEO_ANALYSIS. EOF ``` Fill out: ```markdown # Omissions Pass - why an omissions pass is needed: - missing visual state: - missing timestamp: - unsupported claim: - uncertainty: - expected correction: ``` ## Exercise 10: Create A Bug Repro Prompt Write: ```markdown # Implementation Prompt From Video ## Source - video: - source hash: - ffprobe: - analysis: - keyframes: ## Observed Failure - timestamp: - visual evidence: - transcript/chat evidence: - expected behavior: - actual behavior: ## Request Implement the smallest safe fix. ## Constraints - do not change: - preserve: ## Verification - command: - what passing means: ``` Confirm: ```bash test -s "$RUN_DIR/final/implementation-prompt.md" && echo "implementation-prompt:OK" ``` ## Exercise 11: Convert Video Evidence Into A Section 6 Matrix Pick one variable from the video-derived work. ```markdown # Video-Derived Variation Matrix ## Goal ## Evidence From Video - timestamp: - observation: - keyframe: - why it matters: ## Invariants - same repo state: - same source evidence: - same target flow: - same verification command: - same review criteria: ## Variable Under Test - variable: - why this variable matters: - what is out of scope: ## Candidates | ID | Variable setting | Output location | Verification command | | --- | --- | --- | --- | | v1 | | | | | v2 | | | | | v3 | | | | ``` ## Exercise 12: Section 8 Bridge Write a marker that carries the evidence discipline forward. ```bash mkdir -p "$RUN_DIR/final" cat > "$RUN_DIR/final/section8-bridge-agent-marker.md" <<'EOF' # Agent Marker Bridge - previous section: Section 7 - evidence type: video prompt material - source hash: - ffprobe: - analysis: - output.log: - sentinel: - visual evidence: - uncertainty: - next marker: - Section 8 target: Debugging with Agent Markers EOF test -s "$RUN_DIR/final/section8-bridge-agent-marker.md" \ && echo "agent-marker-bridge:OK" ``` Fill out: ```markdown # Section 8 Bridge Notes - what evidence was preserved: - what uncertainty remains: - what marker should the debugging agent leave next: - what would be lost without the marker: ``` ## Final Check Run: ```bash test -s "$RUN_DIR/inputs/source-video.sha256" && echo "sha256:OK" test -s "$RUN_DIR/receipts/ffprobe.source.json" && echo "ffprobe:OK" test -s "$RUN_DIR/chunks/01/gemini-prompt.md" && echo "prompt:OK" test -s "$RUN_DIR/chunks/01/expected-sentinel.txt" && echo "sentinel:OK" find "$RUN_DIR/final" -type f | sort ``` Fill out: ```markdown # Final Video Prompt Run Check - source preserved? yes/no - source hash saved? yes/no - ffprobe saved? yes/no - original timestamps preserved? yes/no - prompt saved? yes/no - Oracle call shape correct? yes/no - output.log checked? yes/no - sentinel verified? yes/no - evidence lanes separated? yes/no - keyframes/contact sheet saved? yes/no - unsupported claims removed? yes/no - omissions pass considered? yes/no - downstream artifact saved? yes/no - ready to use as prompt material? yes/no ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-video-workflows-practice Topic: Context Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # A reusable design.md standard playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already ship UI inside real repos, so a design.md gives their AI agent a concrete visual contract instead of vague taste prompts. It keeps design direction reusable while still forcing implementation decisions to come from the current codebase. [Core principles](/topics/foundations-source-truth-and-design/) ## Copy-paste workflow **When to use:** When you want AI design work to follow a durable standard instead of one-off vibes. This turns visual inspiration into a `design.md` design contract (style DNA, color, type, layout, motion) that the agent reuses on every UI task. ### Copy-paste prompt ```text You are my coding agent. Author a durable design contract at design.md, then build UI FROM it. The goal is to turn taste into a concrete, reusable artifact — not stale memory. Code stays the source of truth; design.md is a stable design brief. 1. First, gather visual inspiration: collect the generated inspiration images I provide (or generate a sheet of options) and note what I actually picked. 2. Distill those references into design.md with these sections, each concrete and specific: - references (the images/directions I chose) - style DNA (the overall feel in a few words) - color (palette + usage rules) - typography (families, scale, weights) - layout (grid, spacing, density) - composition - shape (radii, borders, elevation) - motion (timing, easing, where motion is/ isn't used) - constraints (hard rules the UI must respect) 3. Now build the UI FROM design.md (e.g. a landing page ), referencing the contract for every visual decision so the result reflects the standard, not ad-hoc choices. 4. To explore directions, pair this with the throwaway multi-route variant move: generate a few variants, compare, keep one, delete the rest. ``` ### How it works - The workflow is: collect generated inspiration images first, then distill them into `design.md`, then have the agent build UI FROM `design.md` so taste becomes a concrete artifact. - The `design.md` sections (references, style DNA, color, typography, layout, composition, shape, motion, constraints) form a stable design contract the agent reuses. - Code is the source of truth; `design.md` is a stable design brief, not stale memory to drift from. - Pair it with the throwaway multi-route variant move (generate, compare, keep one) to explore directions cheaply. - Reference: [Inspiration Board](https://inspiration-board.pages.dev/), [Codex CLI](https://github.com/openai/codex). ## Reusable skill Install as `~/.agents/skills/design-md-standard/SKILL.md`, then restart Codex. ```markdown --- name: design-md-standard description: Trigger when starting UI/design work that should follow a durable standard rather than one-off prompts — author or update a design.md design contract, then build UI from it. Do NOT use as stale long-term project memory. --- # design.md standard Create or maintain a durable `design.md` design contract, then build UI FROM it so taste becomes a concrete, reusable artifact. Code stays the source of truth; `design.md` is a stable brief, not memory to drift. ## Steps 1. Gather visual inspiration first: collect the generated inspiration images the user provides (or generate a sheet of options) and note which direction was actually picked. 2. Distill the references into `design.md` with these sections, each concrete and specific: - **references** — the chosen images/directions - **style DNA** — the overall feel in a few words - **color** — palette + usage rules - **typography** — families, scale, weights - **layout** — grid, spacing, density - **composition** - **shape** — radii, borders, elevation - **motion** — timing, easing, where motion is / isn't used - **constraints** — hard rules the UI must respect 3. Build the UI FROM `design.md`, referencing the contract for every visual decision (color, type, spacing, motion) so the result reflects the standard, not ad-hoc choices. ## Guardrails - Treat code as the source of truth; `design.md` is a stable design brief, NOT stale long-term memory. - Pair with the throwaway route-variants move (generate, compare, keep one) when exploring directions. ``` ## Scenarios ### Rescue a drifting SaaS dashboard redesign **Role:** As a frontend lead maintaining a Next.js SaaS dashboard A Next.js app has accumulated one-off AI-generated cards, empty states, tables, and settings screens. The current dashboard works, but every new agent pass makes the UI feel less coherent because there is no shared design contract. > As a frontend lead, I want the agent to inspect the current dashboard code, author a design.md from selected generated inspiration, and refactor one screen from that contract, so that future UI work follows the same visual standard instead of adding more drift. #### Agent brief ```text You are my coding agent in this repo. Treat the current code as the source of truth. First inspect the existing app structure, routes, shared components, styling setup, and one representative dashboard screen. Do not rely on stale memory. Then create or update design.md with these sections: references, style DNA, color, typography, layout, composition, shape, motion, and constraints. Use only the generated inspiration references I provide or the selected direction I name; do not scrape or clone live websites. After design.md exists, refactor exactly one dashboard route or component to follow it. Run the repo's normal lint/typecheck/test command if available, start the local dev server, and verify the edited screen in a browser. Expected output: design.md, a small focused diff to the selected screen/components, terminal test output, and a short note explaining which design.md rules drove the visual decisions. ``` #### Implementation references [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](https://inspiration-board.pages.dev/) ```text local commands: inspect package.json, then run the repo's existing lint/typecheck/test and dev-server scripts ``` #### Browser verification Use the running local app, ideally in a CMUX browser pane or an agent-browser style flow. Open the edited dashboard route, take an accessibility snapshot, verify the main landmarks/headings/buttons are still present, click through at least one existing interactive control, and capture a screenshot or browser note showing the screen follows design.md. If using Playwright, script the same route load and one interaction rather than relying on visual claims only. #### Definition of done - design.md exists and includes references, style DNA, color, typography, layout, composition, shape, motion, and constraints - the changed dashboard screen visibly follows design.md and does not introduce unrelated route or architecture changes - lint/typecheck/test or the closest repo-local verification command has been run and logged - browser proof includes the local URL, the edited route, an accessibility snapshot or equivalent DOM evidence, and a screenshot or concise visual review note #### Failure modes and mitigations - The agent writes a generic design.md without inspecting the repo first; mitigate by requiring a short source-of-truth evidence section listing the files/components/routes it inspected before editing - The agent treats design.md like permanent stale memory and overrides current implementation constraints; mitigate by stating that code remains the source of truth and design.md is only the visual brief - The agent makes broad design-system rewrites; mitigate by limiting implementation to one route or one component family and requiring a small focused diff ### Pick a landing page direction with disposable route variants **Role:** As an indie product developer launching a marketing page A new product landing page needs a strong visual direction, but the developer does not want to set up Storybook or maintain a gallery of experiments. The app already has a local dev server and route-based pages. > As an indie product developer, I want the agent to turn selected generated inspiration into design.md, generate several temporary landing-page route variants, let me compare them in the browser, and delete the losers, so that I can choose a direction quickly without creating maintenance baggage. #### Agent brief ```text You are my coding agent. Use the current app code as the source of truth for routing, styling, and component conventions. First create design.md from my selected generated inspiration with the required sections: references, style DNA, color, typography, layout, composition, shape, motion, and constraints. Then generate 3 to 5 temporary route-level variants of the same landing page inside the running app. Add simple left/right navigation between variants if it fits the app, such as links or arrow-key handling. Do not create a permanent Storybook-style catalog. Start the dev server, open the variants in the browser, and produce a comparison note that names the strongest variant and why. After I choose a winner, promote that implementation to the real landing route and delete the rejected temporary routes. Expected output: design.md, temporary variants only during review, a promoted final route, deleted losers, and browser proof from the local app. ``` #### Implementation references [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](https://inspiration-board.pages.dev/) ```text local commands: run the repo's dev server and verify the temporary variant routes in browser ``` #### Browser verification Use a local browser session to compare each temporary route in the real app. In CMUX, keep the dev server visible and open a browser pane on the variant index or first variant. Use browser snapshot/click/evaluate actions to move through left/right navigation, confirm each variant renders, and record the winning route. A screenshot grid or one screenshot per variant is useful proof here. #### Definition of done - design.md is created before variants and each variant visibly follows the same contract - 3 to 5 temporary route-level variants render in the local app with simple navigation or clear links between them - a comparison note identifies the winning variant using concrete design.md criteria - the final route is promoted and rejected temporary routes are deleted - browser proof shows the variants were reviewed in the running app, not just inferred from source #### Failure modes and mitigations - The agent keeps all variants and leaves a maintenance mess; mitigate by making deletion of rejected routes part of the definition of done - The agent builds variants before writing design.md, causing random styles; mitigate by requiring design.md first and asking each variant to cite which contract rules it uses - The browser review only checks the happy screenshot and misses broken navigation; mitigate by requiring click or keyboard navigation through every variant ### Standardize AI UI work for an existing component library **Role:** As a design-minded full-stack developer maintaining a shared React component set A repo has reusable components but no durable visual language. Agents keep adding new button, card, modal, and form styles that technically compile but do not feel like one product. > As a full-stack developer, I want the agent to extract stable visual rules from current components and selected generated inspiration into design.md, then update one component example page from that contract, so that future AI-assisted UI work has a practical standard to follow. #### Agent brief ```text You are my coding agent. First inspect the current component files, styling conventions, route examples, and package scripts. Summarize the source-of-truth evidence before writing anything. Then create or update design.md as a design contract with references, style DNA, color, typography, layout, composition, shape, motion, and constraints. The contract should preserve stable conventions already present in the code unless they conflict with the chosen generated inspiration direction. Next update exactly one example/demo route or one small component cluster, such as Button/Card/Form, to follow design.md. Run the repo's available lint/typecheck/test command and start the local dev server. Expected output: design.md, one focused component/example diff, verification logs, and a browser review of the demo route. ``` #### Implementation references [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](/topics/foundations-design-md-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ```text cmux markdown open design.md --direction right --focus false ``` ```text local commands: inspect package.json, run existing lint/typecheck/test, run the dev server ``` #### Browser verification Open design.md in a live CMUX Markdown pane while the dev server and browser are visible. In the browser, open the component example/demo route, use an accessibility snapshot to confirm labels and roles survived the visual pass, then click/fill one interactive component such as a button, input, select, or modal trigger. Browser proof matters because component styling can compile while still breaking focus states, labels, or layout. #### Definition of done - the agent records which current component files and routes were inspected before writing design.md - design.md captures both selected inspiration and existing repo constraints without becoming a stale architecture memory file - one demo route or component cluster is updated from the contract with a focused diff - lint/typecheck/test or closest available verification command passes or has a documented failure with exact output - browser proof includes a rendered demo route plus at least one accessibility or interaction check #### Failure modes and mitigations - The agent invents a design system from scratch and ignores existing components; mitigate by requiring source-of-truth evidence from current component files before design.md - The agent edits too many components at once; mitigate by limiting the first pass to one component cluster or one demo route - The agent verifies only with tests and skips browser behavior; mitigate by requiring a browser snapshot plus one click/fill interaction on the changed example ## Implementation notes - Require the agent to inspect current repo files before writing or applying design.md; implementation details come from live code, not memory. - Keep design.md human-readable and stable: it should describe visual decisions, not duplicate fast-changing component internals. - Browser verification is part of the web-dev workflow here. A compile pass is not enough when the task changes layout, interaction, focus, or responsive behavior. - When exploring visual direction, prefer temporary route/page variants inside the app and delete rejected variants after selection. - Use generated inspiration as direction-setting material. Do not ask the agent to scrape or clone live websites. - Keep the first implementation slice small: one route, one page, or one component cluster. A design standard gets trusted by proving it on a narrow diff first. ## Boundaries and caveats - Do not reintroduce AGENTS.md, Codex Sandbox approvals, Beads, Chrome DevTools MCP, Deep Wiki Map, Impeccable implementation steps, or YOLO-style approval bypassing for this topic. - Do not present million-token snapshots as a proven design.md workflow; this workflow treated that as an unproven possible direction. - Do not build a permanent Storybook-style catalog unless the project already requires one; the taught move is disposable route variants. - Do not treat design.md as an auto-updated memory system that must change on every commit. ## Agent reference map ### Validated lesson 04 references Use this as the ground truth for taught concepts: code as source of truth, lightweight Markdown memory, generated inspiration, design.md, and throwaway route variants. [Open reference](/topics/foundations-source-truth-and-design/) ### Design.md standard prompt Use this as the copy-paste implementation prompt shape for authoring design.md and building UI from it. [Open reference](/topics/foundations-design-md-playbook/) ### Design.md Codex skill Use this when packaging the workflow for Codex so the agent knows when to create or maintain design.md and when not to treat it as stale memory. [Open reference](/topics/foundations-design-md-playbook/) ### Throwaway route variants skill bundle Use this for the anti-Storybook move: generate route-level variants, compare in the app, keep one, and delete the rest. [Open reference](/topics/foundations-design-md-playbook/) ### Inspiration Board Use this when the human needs generated visual references before asking the agent to write design.md. [Open reference](https://inspiration-board.pages.dev/) ### CMUX CLI reference Use this only for taught local workflow support such as opening a live Markdown design.md pane or inspecting panes while the dev server/browser run. [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) Reference ID: foundations-design-md-playbook Topic: Planning Sources: - [Agent foundations: Trust current source and capture design decisions (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-04.html) --- # Bounded prompts for factory work Six complete exercises with explicit input, expected output, and success evidence, plus the read-only audit setup. ## TL;DR - **Every prompt declares** its input, expected result, and success check. - **Copying is preparation;** attempting and verifying are separate progress stages. - **Your agent can install** the complete audit from agent.md. Paste this into your agent: ``` text Fetch https://proud-anchor-53zn.here.now/agent.md and follow it to install the factory-loop audit in my current project. Run the success check and show me the result. ``` ## Quick start Orient yourself in the current repository before choosing a prompt. ``` text ROOT="$(git rev-parse --show-toplevel)" cd "$ROOT" printf 'Repository: %s\n' "$ROOT" git status --short git diff --stat find . -maxdepth 2 -type f \( -name AGENTS.md -o -name README.md -o -name package.json -o -name pyproject.toml -o -name Cargo.toml \) -print | sort ``` ## Prompt library ### Audit one factory boundary - Agent: Repository-capable coding agent - Working directory: Project root - Inputs: One recurring task and the current repository - Expected result: A seven-part boundary map with one human gate **Success:** All claims are Observed, Inferred, or Proposed; the tree is unchanged. ``` text You are auditing one recurring software task as a bounded factory loop. Work read-only until I explicitly approve a change. First inspect the current repository and ask me to name the recurring task if it is not already clear. Then return these seven sections: 1. Task contract — input, desired outcome, and what is outside scope. 2. Required context — the minimum current evidence needed before acting. 3. Boundary map — repository rule, launch rule, command rule, human gate, and automated check. 4. Risk gate — the first expensive, destructive, public, or hard-to-reverse action that must stop for approval. 5. Success evidence — one exact command or observable signal that can prove the task worked. 6. Receipt — what the next session needs to reproduce the result and understand the decision. 7. Smallest reversible delta — the first experiment that tests this loop without production mutation. Label every statement Observed, Inferred, or Proposed. Do not install tools, use credentials, mutate data, publish, or edit files. If evidence is missing, stop and name the missing evidence instead of guessing. ``` ### Compose the smallest useful evidence packet - Agent: Coding agent - Working directory: Project root - Inputs: Task, relevant files, fresh command output, optional annotated image - Expected result: A source list, omissions, and one verification plan **Success:** Every included source changes the decision, action, or verification. ``` text Prepare the smallest evidence packet for this task before proposing a solution. Separate: task, constraints, current implementation, fresh runtime evidence, visual evidence, and success check. For each source, say which decision it can change. Identify stale, duplicated, contradictory, or irrelevant material and exclude it. End with the exact evidence still missing. Do not implement yet. ``` ### Generate structural variations - Agent: Design-capable coding agent - Working directory: Project root; write only to a scratch route or directory - Inputs: Stable content, product goal, design constraints - Expected result: Four meaningfully different mockups and a comparison index **Success:** Options differ in structure, not only color or type. ``` text Create four dependency-free design variations without editing production files. Hold the content and product goal constant. Vary information architecture, hierarchy, density, navigation, and interaction emphasis. Give every option a distinct design thesis. Build a comparison index that explains what each option optimizes, what it sacrifices, and which user behavior it makes easiest. Stop before choosing a winner. Label this a Companion-authored exercise. ``` ### Recover a trustworthy handoff - Agent: Coding agent with repository and history access - Working directory: Project root - Inputs: Working tree, recent commits, notes, artifacts, available session history - Expected result: A compact recovery memo and one next check **Success:** The memo distinguishes verified state from remembered or inferred state. ``` text Recover this task from durable evidence. Report: current objective, current repository state, last verified result, decisions already settled, open risks, failed attempts worth preserving, next bounded action, and the exact command or observation that will prove it. Use history only to locate evidence; verify important claims against the current tree or artifacts. Do not continue implementation until the recovery memo is internally consistent. ``` ### Prepare a maximum-intelligence consult - Agent: Strong independent reasoning model - Working directory: Project root or supplied evidence bundle - Inputs: One hard decision and filtered supporting evidence - Expected result: Alternatives, hidden assumptions, experiment, reversal plan **Success:** The recommendation is falsifiable and does not depend on missing context. ``` text Review this decision independently. State the decision in one sentence. Identify hidden assumptions and the most costly way the current framing could be wrong. Propose at least three materially different options, including the simplest viable option. For each, give evidence, tradeoffs, reversibility, and failure modes. Recommend the smallest discriminating experiment and define the result that would change your recommendation. Finish with a reversal plan. ``` ### Earn the right to automate - Agent: Coding agent and human owner - Working directory: Project root - Inputs: VISION.md or product evidence plus one recurring review - Expected result: Manual → script → agent → CI → blocking-gate promotion plan **Success:** Every promotion has an owner, evidence threshold, cost boundary, and recovery path. ``` text Map this recurring review onto an automation ladder: manual run, deterministic script, bounded agent, non-blocking CI report, blocking gate, schedule, or human approval. Keep it at the lowest stage that is currently justified. For each possible promotion, specify the evidence threshold, false-positive tolerance, latency and cost budget, owner, stop condition, and recovery path. Run nothing and schedule nothing. End with the next five manual receipts we should collect. ``` ## Set up the boundary audit These steps mirror [agent.md](https://proud-anchor-53zn.here.now/agent.md). 1. Confirm Git and preserve the working tree. 2. Create the complete prompt: ``` text # Factory Loop Boundary Audit Use this prompt before automating or expanding a recurring software task. ## Instructions You are auditing one recurring software task as a bounded factory loop. Work read-only until I explicitly approve a change. First inspect the current repository and ask me to name the recurring task if it is not already clear. Then return these seven sections: 1. Task contract — input, desired outcome, and what is outside scope. 2. Required context — the minimum current evidence needed before acting. 3. Boundary map — repository rule, launch rule, command rule, human gate, and automated check. 4. Risk gate — the first expensive, destructive, public, or hard-to-reverse action that must stop for approval. 5. Success evidence — one exact command or observable signal that can prove the task worked. 6. Receipt — what the next session needs to reproduce the result and understand the decision. 7. Smallest reversible delta — the first experiment that tests this loop without production mutation. Label every statement Observed, Inferred, or Proposed. Do not install tools, use credentials, mutate data, publish, or edit files. If evidence is missing, stop and name the missing evidence instead of guessing. ## Success contract - The output contains all seven named sections. - Every statement is labeled Observed, Inferred, or Proposed. - One explicit human gate and one exact verification signal are named. - The audit makes no repository changes. ``` 3. Run the structural check: ``` text mkdir -p .agents/prompts test -s .agents/prompts/factory-loop-audit.md grep -q '^## Success contract' .agents/prompts/factory-loop-audit.md printf 'factory loop prompt installed\n' ``` **Success check:** the installed audit returns seven labeled sections, one human gate, one exact verification signal, and changes no pre-existing file. ``` text factory loop prompt installed ``` ## Use the smallest prompt that can change the result Before: name the boundary. Prompt: include only decisive evidence. Success evidence: run one exact check. Reflect: record what changed your decision. Continue: return to the related lesson. The prompts are companion-authored exercises grounded in the recorded operating patterns. They are not presented as verbatim workshop quotations. Reference ID: factory-bounded-prompts Topic: Planning Sources: - [Factory prompt library](https://proud-anchor-53zn.here.now/prompts.html) --- # Choose the next agent workflow Use this as the map for the full workflow. Each section stands alone, but the sequence is deliberate. ## Agent Setup Prompt ```text Use this workflow index to choose the next agent move for a software project. First identify the current bottleneck: - missing context - missing shell tools - unclear helper behavior - wrong workspace or session - weak prompt shape - too many plausible implementations - video or runtime evidence to analyze - bounded debug packet to preserve - narrow task to delegate - risky decision that needs independent model critique - generated options that need a human pick Then pick the matching section and ask the agent to follow that workflow. Keep the request concrete: name the repo, the bug or decision, the files or logs to inspect, and the proof you expect before the work is considered done. ``` ## Phase Map ### Phase 1: Context And Environment Make invisible project context and agent shell context explicit before asking for work. 1. Pack context when broad code reasoning needs Oracle. 2. Make the shell and tools visible to Codex. 3. Classify zsh helper names and fallback boundaries. Transition: Once the agent can see the right context and tool surface, route the work to the right place before launch. ### Phase 2: Routing And Composition Put work in the right workspace, pane, session, and prompt shape before it runs. 4. Route the right pane/session. 5. Compose before launch. Transition: Once launch is deliberate, use the agent surface to produce, compare, and preserve evidence. ### Phase 3: Generation And Evidence Generate useful options and turn rich runtime or media evidence into prompt material. 6. Generate verified variations. 7. Use video as prompt material. 8. Mark debug moments with bounded evidence. Transition: Once the work is bounded and evidenced, delegate narrow packets or ask for independent review. ### Phase 4: Delegation And Review Hand small tool-shaped work to narrow agents, use councils for expensive decisions, and capture human choices before implementation. 9. Hand tool-shaped packets to narrow Imps. 10. Ask a model council when independent disagreement improves a risky decision. 11. Capture a phone-friendly human selection from generated options and resume from saved JSON. ## Section Map | Phase | Section | Workflow Move | File | | --- | --- | --- | --- | | Context And Environment | 1 | Pack context when broad code reasoning needs Oracle | [01-oracle-packing-context.md](/topics/codex-context-packing-reference/) | | Context And Environment | 2 | Make the shell and tools visible to Codex | [02-loading-zsh-env-into-codex.md](/topics/codex-shell-environment-reference/) | | Context And Environment | 3 | Classify zsh helper names and fallback boundaries | [03-zsh-functions-aliases.md](/topics/codex-shell-functions-reference/) | | Routing And Composition | 4 | Route the right pane/session | [04-agentic-dev-environment-orchestrator.md](/topics/codex-workspace-routing-reference/) | | Routing And Composition | 5 | Compose before launch | [05-prompt-builder.md](/topics/codex-prompt-composition-reference/) | | Generation And Evidence | 6 | Generate verified variations | [06-code-is-free-generate-variations.md](/topics/codex-variation-workflows-reference/) | | Generation And Evidence | 7 | Use video as prompt material | [07-video-as-prompts.md](/topics/codex-video-workflows-reference/) | | Generation And Evidence | 8 | Mark debug moments with bounded evidence | [08-debugging-with-agent-markers.md](/topics/codex-marker-workflows-reference/) | | Delegation And Review | 9 | Hand tool-shaped packets to narrow Imps | [09-imps.md](/topics/codex-imp-workflows-reference/) | | Delegation And Review | 10 | Ask a model council when independent disagreement improves a risky decision | [10-fusion-model-council.md](/topics/codex-fusion-workflows-reference/) | | Delegation And Review | 11 | Capture a phone-friendly human selection from generated options | [11-web-choices.md](/topics/codex-choice-workflows-reference/) | ## How To Use The Set Start with the section that matches the current bottleneck: | Bottleneck | Start With | | --- | --- | | The agent needs a broad codebase answer | Section 1 | | A command works locally but not in Codex | Section 2 | | A helper name is unclear or shell-only | Section 3 | | Work is landing in the wrong pane or session | Section 4 | | The prompt needs shaping before launch | Section 5 | | Several implementations are plausible | Section 6 | | A recording contains the missing context | Section 7 | | Logs exist but the important moment is unclear | Section 8 | | The task is mostly one command-line tool | Section 9 | | Several strong models may disagree on a risky architecture or implementation choice | Section 10 | | The agent generated good options but needs a human pick or feedback before continuing | Section 11 | Section 10 is especially useful after Section 6 for comparing strategies, or after Section 9 when a bounded packet needs independent review before a risky implementation choice. Section 11 is especially useful after Section 6 or Section 10 when generated options need a human selection, ranking, or feedback before implementation continues. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-workflow-selection Topic: Planning Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Compose the first prompt before launch The first prompt does more than start a chat. It names the work, chooses the launch path, loads useful references, and decides whether this is a fresh thread, a fork, a compacted branch, or a wrapper handoff. Do the deliberate setup before the agent session starts. Use **[hooks](https://developers.openai.com/codex/hooks)** for repeated interception during the session. Use **[imps](https://github.com/johnlindquist/codex-imps)** or CLI helpers for reusable specialist behavior. ## Start With A Name **Unnamed sessions decay quickly.** A name gives search, resumption, review, and reporting something stable to grab. > The thing I like about this is that I can just give a conversation a name from the start. And it kind of forces me to think about what the conversation is going to be about. > > — John Lindquist Good names sound like software work: - Checkout saved payment methods - Billing webhook retry audit - Auth session rotation review - Settings empty-state cleanup The name does not need to be clever. It needs to be **short, searchable, and tied to the work**. ## Compose Before Launch The core loop is: ```text intent -> name -> prompt -> references -> preview -> submit ``` **[Prompt Builder](https://github.com/johnlindquist/prompt-builder)** is useful because it **moves composition before the full launch path**. You can shape the prompt, add the name, include the references, inspect the launch, and then hand the result to [Codex](https://developers.openai.com/codex) or a wrapper command. > Pre-flight, preload, pre-plan. Sessions before, before anything about the agents kicks in, before the system prompt kicks in, before anything. > > — John Lindquist ## Use Prompt Builder For Preflight Use a preflight surface when the setup belongs to the first prompt. Feature kickoff: ```text Name: Checkout saved payment methods Prompt: Inspect the checkout flow, list the files likely involved, identify the smallest safe implementation plan, and name the first verification command. Do not edit yet. ``` Bug-fix preflight: ```text Name: Billing webhook retry bug Prompt: Use the failing test output and billing webhook files to identify the likely regression. Return the smallest patch plan and the verification command before editing. ``` Architecture review: ```text Name: Auth session rotation review Prompt: Review the auth/session architecture and find risks around token rotation, stale sessions, and logout behavior. Return findings grouped by risk and proof needed. ``` ## Use Hooks For Every-Turn Behavior Prompt Builder helps before the session starts. Hooks are a better fit when something must happen **on every prompt or at a lifecycle checkpoint**. For voice-to-text cleanup: - Use Prompt Builder when cleanup only needs to happen before the first prompt. - Use a prompt-submit hook when cleanup must happen on every turn. - Use an imp or CLI helper when cleanup belongs to a reusable specialist command. Example boundaries: - Initial only: clean up a dictated feature kickoff, apply a glossary, attach project references, then launch. - Every turn: normalize dictated acronyms, product names, ticket IDs, and file names before each prompt reaches the agent. - Specialist job: take rough dictated text and return a launch-ready prompt without touching the repo. ## Use Imps For Repeated Specialized Jobs If the behavior becomes a reusable tool-shaped job, move it out of the first prompt. Good candidates: - prompt cleanup - bug triage - screenshot capture - route inspection - dependency audit - ticket drafting **The first prompt should start the work.** It should not become the permanent home for every repeated workflow. ## Optional Patterns: Fork, Compact, Handoff Prompt Builder can compose first, then hand the prompt to another command. In that mode, fork and compact options are routing choices. Keep the model simple: ```text compose first -> fork selected session -> compact when needed -> resume with named prompt compose first -> hand off to wrapper -> wrapper owns the routing ``` Treat this as advanced launch routing. The main lesson is still **preflight**: name the work, shape the request, preview the launch, and submit deliberately. ## Copyable Artifact: First Prompt Preflight Checklist ```text Before launching the agent, fill in: Name: [short, searchable task name] Goal: [what should be true when this work is done] Context: [files, logs, screenshots, tickets, or docs to inspect first] Constraints: [files to avoid, behaviors to preserve, risky areas] Launch shape: [fresh thread / named thread / fork / compact fork / wrapper handoff] First output: [plan only / edit / diagnosis / test list / comparison] Proof: [command, screenshot, trace, diff, or review artifact required] Stop rule: [what should block completion] ``` Example: ```text Name: Checkout saved payment methods Goal: Fix the saved-card selection regression without changing the payment-provider adapter. Context: Checkout route, saved payment method component, failing test output. Constraints: Do not touch provider SDK wrappers. Do not rewrite checkout state management. Launch shape: Named thread. First output: Diagnosis and smallest safe patch plan. Proof: Run the checkout component test and billing smoke test. ``` ## Verify Commands Before Use Prompt Builder command examples are implementation details. Before running them, verify the current binary name, install path, `--name`, dry-run, print, submit, handoff, fork, compact, and launch-option behavior against the current source and CLI help. The pattern is stable. Command details can change. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#prompt-builder) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-prompt-builder Topic: Planning Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#prompt-builder) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Controlled variation workflows: practical reference ## Agent Setup Prompt ```text Set up a controlled variation run before any candidate implementation starts. Build the files, folders, isolation lanes, verification ledger, review surfaces, and saved-decision template first, then stop and report whether setup is ready. 1. Work from the repository root. Choose a short run id that names the software decision, such as `billing-webhook-$(date +%Y%m%d-%H%M%S)`, and set `ROOT="artifacts/variations/$RUN_ID"`. 2. Create the run structure: `prompts/`, `launch/`, `logs/`, `review/`, `decisions/`, and `candidates/v1`, `candidates/v2`, `candidates/v3` under `$ROOT`. If the variation is visual, also create `review/screenshots/`. 3. Write `$ROOT/matrix.md` before launching anything. Include Goal, Invariants, Variable Under Test, Candidate Count, Candidates, and Review Criteria. The matrix must name exactly one variable. Keep repo state, base prompt, target feature or bug, constraints, verification command, and review criteria identical for every candidate. If a second dimension matters, record it as a future round. 4. Save the shared base prompt to `$ROOT/prompts/base.prompt.md`. Save matching launch metadata to `$ROOT/launch/base.launch.json` using Prompt Builder when available, for example `p --print-prompt "$PROMPT"` and `p --print-launch-json "$PROMPT"`. If Prompt Builder is unavailable, still write the base prompt file and create a small valid launch JSON file that records the prompt text, run id, candidate ids, artifact root, isolation method, and verification command. 5. Capture baseline repo state before fan-out: save `git status --short` to `$ROOT/review/git-status-before.txt`, `git diff` to `$ROOT/review/dirty-before.patch`, and `git diff --staged` to `$ROOT/review/staged-before.patch`. If the repo has unknown dirty state, stop and report it instead of creating candidate code lanes. 6. Choose the isolation strategy and record it. For prompt, plan, or docs-only variations, use `$ROOT/candidates/v1`, `v2`, and `v3`. For parallel code edits, prefer git worktrees at `../variation-$RUN_ID/v1`, `v2`, and `v3`, each on its own branch, then save `git worktree list` to `$ROOT/review/worktrees.txt`. Each candidate must have a distinct branch, worktree, or directory. 7. Create `$ROOT/prompts/v1.prompt.md`, `$ROOT/prompts/v2.prompt.md`, and `$ROOT/prompts/v3.prompt.md` from the same base prompt. Append only the candidate override: candidate id, variable name, that candidate's setting, and the instruction to change no other dimension. 8. Define one verification command and save it in the matrix plus `$ROOT/review/verification-command.txt`. Create `$ROOT/review/verification.tsv` with columns for candidate id, status, and command. Do not run implementation verification yet. The command must be identical for every candidate; if a candidate needs different proof, make that a new variation round. 9. Create review artifacts before generation: `$ROOT/review/comparison.md` with Goal, Variable Under Test, Verification, Diff Review, Review Criteria, and Notes sections; placeholder paths for `logs/v1.verify.log`, `logs/v2.verify.log`, `logs/v3.verify.log`; placeholder paths for `review/v1.diffstat.txt`, `review/v1.diff.patch`, and matching v2/v3 files. Leave results blank until candidates exist. 10. Create `$ROOT/decisions/selection.md` with fields for outcome, primary candidate, secondary candidate ids, decision, why, rejected candidates, required follow-up, final verification command, per-candidate notes, and a continue prompt. The outcome must later be exactly one of Pick, Combine, Refine, Expand, or Reject. 11. Run setup checks only: confirm the matrix, base prompt, launch JSON, candidate prompts, repo-state files, verification command file, comparison template, decision template, and isolation lanes exist. Print OK or FAIL for each check and show the run file list with `find "$ROOT" -maxdepth 3 -type f | sort`. 12. Respect privacy boundaries. Do not copy secrets, tokens, cookies, private endpoints, full environment dumps, raw private config, or unrelated home-directory files into prompts, logs, launch JSON, matrix files, review artifacts, or decisions. Summarize sensitive configuration instead of pasting it. 13. Report back with the artifact root, candidate ids, chosen isolation strategy, single variable under test, single verification command, repo-state classification, setup check results, any files you intentionally did not copy for privacy, and any blocker. Do not generate candidate implementations, run candidate verification, fill comparison results, or make a Pick/Combine/Refine/Expand/Reject decision until setup verification passes and the next step is explicitly requested. ``` ## Big Idea Phase: Generation And Evidence - use the prepared surface to generate comparable options and preserve the proof that decides between them. `Code is free` does not mean quality is free. ## Try This Now Finish this sentence before generating candidates: `We are comparing candidates that differ only by __________.` For a billing webhook bug, try: `idempotency strategy`. Write the same verification command before any fan-out. It means another candidate is cheap enough that the workflow should change: ```text do not bet everything on the first generated answer ``` Produce candidates, verify them, compare them, converge deliberately, and save the decision. Cheap: - another implementation option - another UI integration strategy - another idempotency strategy - another test boundary - another prompt framing - another documentation organization Still expensive: - understanding the problem - keeping candidates controlled - integrating the winner - running verification - resolving conflicts - preserving why the decision was made Practical rule: ```text Generate more because comparison improves the decision, not because you are avoiding the decision. ``` ## When To Reach For This Use variations when several plausible approaches exist and comparison will make the final choice better. | Use Variations For | Example | | --- | --- | | UI integration strategy | saved payment methods in checkout: inline selector vs drawer vs review-step picker | | idempotency strategy | billing webhook duplicate-processing: provider event guard vs invoice lock vs processing ledger | | auth/session architecture | middleware-first vs session-store-first vs token-rotation boundary | | state management | local reducer vs server state cache vs URL-backed state | | test boundary | unit regression vs integration replay vs end-to-end checkout path | | API shape | command endpoint vs resource endpoint vs explicit workflow endpoint | | data loading model | route loader vs component query vs server action | | implementation alternatives | minimal patch vs extracted helper vs explicit state machine | | prompt framing | plan-first vs patch-first vs test-first | | documentation organization | quickstart-first vs concept-first vs task checklist | Skip variations when another candidate adds noise. | Skip Variations For | Better Move | | --- | --- | | one-line typo fix | patch it and test it | | obvious hotfix | apply the smallest safe change | | strict migration | follow the migration plan exactly | | exact requested implementation | build what was specified | | unverifiable candidates | define verification first | | dirty repo with no saved state | checkpoint before fan-out | | failing test names the exact bug | fix the bug first | | candidates would share unsafe state | isolate before launching | Hard rule: ```text Variation is a decision tool, not a procrastination tool. ``` ## How This Used To Work What you used to expect: ```text Ask for one implementation, inspect it, tweak it, and hope the first path was good enough. ``` What the workflow gives you now: ```text Start from one deliberate prompt, generate controlled candidates, verify each the same way, compare results, then save the chosen path. ``` What you used to expect: ```text More candidates automatically means better work. ``` What the workflow gives you now: ```text Unverified candidates are just noise. The value comes from controlled differences, identical verification, and a saved decision. ``` ## Core Pattern ```text goal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision ``` Do not skip the middle: ```text fan-out without isolation = collisions fan-out without verification = noise fan-out without review = drift fan-out without saved decision = repeated debate ``` ## One Dimension Rule Vary exactly one dimension across candidates. Finish this sentence before launching anything: ```text We are comparing candidates that differ only by __________. ``` Good variables: | Variable | Good Comparison Question | | --- | --- | | UI integration strategy | Where should saved payment methods enter checkout? | | idempotency strategy | Which duplicate-processing guard is safest for billing webhooks? | | state management | Which state boundary keeps the checkout flow simplest? | | test boundary | Which test layer catches this regression with the least brittleness? | | API shape | Which endpoint shape keeps auth/session changes clear? | | data loading model | Where should this screen load account and payment data? | | prompt framing | Which prompt produces the most verifiable implementation plan? | | documentation organization | Which doc structure helps the next maintainer act fastest? | Bad variables: | Bad Variable | Why It Fails | | --- | --- | | random ideas | no controlled comparison | | each one different | impossible to know what mattered | | explore everything | no review question | | make five better versions | vague and untestable | | let every agent decide | candidates drift apart | If two dimensions matter, run two rounds. ```text Round 1: compare idempotency strategy. Round 2: compare test boundary for the selected strategy. ``` ## Variation Matrix Write the matrix before launching candidates. ```markdown # Variation Matrix ## Goal ## Invariants These stay the same for every candidate: - same repo state: - same base prompt: - same target feature or bug: - same constraints: - same verification command: - same review criteria: ## Variable Under Test - variable: - why this matters: - what is out of scope: ## Candidate Count - count: - ids: v1, v2, v3 ## Candidates | ID | Variable setting | Output location | Verification command | Notes | | --- | --- | --- | --- | --- | | v1 | | | | | | v2 | | | | | | v3 | | | | | ## Review Criteria Compare candidates on: 1. passes verification 2. preserves invariants 3. smallest durable change 4. easiest integration path 5. clearest rollback path ``` ### Example: Billing Webhook Duplicate Processing ```markdown # Variation Matrix ## Goal Prevent duplicate processing of paid billing webhook events. ## Invariants - Provider webhook contract stays fixed. - Database schema stays fixed for this round. - Existing invoice state transitions stay compatible. - Same verification command: `pnpm test billing-webhook -- --runInBand && pnpm build`. ## Variable Under Test Idempotency strategy. ## Candidates | ID | Variable setting | Output location | Verification command | | --- | --- | --- | --- | | v1 | provider event id guard | `../variation-/v1` | `pnpm test billing-webhook -- --runInBand && pnpm build` | | v2 | invoice-level processing lock | `../variation-/v2` | `pnpm test billing-webhook -- --runInBand && pnpm build` | | v3 | webhook processing ledger | `../variation-/v3` | `pnpm test billing-webhook -- --runInBand && pnpm build` | ## Review Criteria Which strategy prevents duplicate invoice processing with the smallest durable change? ``` ## Start From The Section 5 Seed Use Prompt Builder to save the base prompt and launch JSON under the variation run. ```bash RUN_ID="billing-webhook-$(date +%Y%m%d-%H%M%S)" ROOT="artifacts/variations/$RUN_ID" mkdir -p "$ROOT"/{prompts,launch,logs,review,decisions} mkdir -p "$ROOT"/candidates/{v1,v2,v3} PROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.' p --print-prompt "$PROMPT" \ > "$ROOT/prompts/base.prompt.md" p --print-launch-json "$PROMPT" \ > "$ROOT/launch/base.launch.json" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" jq '.mode, .prompt' "$ROOT/launch/base.launch.json" ``` Save the matrix next to the seed: ```bash cat > "$ROOT/matrix.md" <<'EOF' # Variation Matrix ## Goal Prevent duplicate processing of paid billing webhook events. ## Invariants - Provider webhook contract stays fixed. - Database schema stays fixed. - Existing invoice state transitions stay compatible. - Same verification command: `pnpm test billing-webhook -- --runInBand && pnpm build`. ## Variable Under Test Idempotency strategy. ## Candidate Count - count: 3 - ids: v1, v2, v3 ## Candidates | ID | Variable setting | Output location | Verification command | Notes | | --- | --- | --- | --- | --- | | v1 | provider event id guard | `../variation-/v1` | `pnpm test billing-webhook -- --runInBand && pnpm build` | | | v2 | invoice-level processing lock | `../variation-/v2` | `pnpm test billing-webhook -- --runInBand && pnpm build` | | | v3 | webhook processing ledger | `../variation-/v3` | `pnpm test billing-webhook -- --runInBand && pnpm build` | | ## Review Criteria - prevents duplicate processing - preserves provider contract - keeps rollback simple - passes the same verification command EOF ``` Confirm the setup: ```bash find "$ROOT" -maxdepth 3 -type d | sort test -s "$ROOT/matrix.md" && echo "matrix:OK" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" test -s "$ROOT/launch/base.launch.json" && echo "launch-json:OK" ``` ## Save Repo State Before Fan-Out Before parallel code edits, save the current state. ```bash git status --short | tee "$ROOT/review/git-status-before.txt" git diff > "$ROOT/review/dirty-before.patch" git diff --staged > "$ROOT/review/staged-before.patch" ``` If the repo is dirty, choose one: | State | Safe Next Move | | --- | --- | | intentional local work | commit or stash before fan-out | | unrelated local work | move it out of the candidate path | | generated files only | clean or save them under `artifacts/` | | unsure | stop and inspect before launching candidates | Do not fan out code edits from unknown dirty state. ## Choose Isolation Parallel candidates must not overwrite each other. | Isolation Option | Use When | Example | | --- | --- | --- | | copied prompt/output folders | candidates are plans, docs, prompts, or generated artifacts | `artifacts/variations//candidates/v1` | | branch | edits are small and reviewed one at a time | `git switch -c variation/-v1` | | git worktree | candidates need parallel repo edits | `git worktree add ../variation-/v1 -b variation/-v1` | | directory copy | no git worktree support, but file edits must be separated | `cp -R app app-v1` | | feature flag | candidates can coexist in one app behind flags | `CHECKOUT_VARIANT=v1` | | unique process state | candidates run services | `PORT=3101`, `PORT=3102`, `PORT=3103` | For code edits, prefer worktrees: ```bash BASE="$(git rev-parse --show-toplevel)" PARENT="$(dirname "$BASE")/variation-$RUN_ID" git -C "$BASE" worktree add "$PARENT/v1" -b "variation/$RUN_ID-v1" git -C "$BASE" worktree add "$PARENT/v2" -b "variation/$RUN_ID-v2" git -C "$BASE" worktree add "$PARENT/v3" -b "variation/$RUN_ID-v3" git -C "$BASE" worktree list | tee "$ROOT/review/worktrees.txt" ``` ## Build Candidate Prompts Start with the same base prompt. Add only the candidate setting. ```bash for id in v1 v2 v3; do cp "$ROOT/prompts/base.prompt.md" "$ROOT/prompts/$id.prompt.md" done cat >> "$ROOT/prompts/v1.prompt.md" <<'EOF' Candidate override: - candidate id: v1 - variable: idempotency strategy - setting: provider event id guard - do not change any other dimension EOF cat >> "$ROOT/prompts/v2.prompt.md" <<'EOF' Candidate override: - candidate id: v2 - variable: idempotency strategy - setting: invoice-level processing lock - do not change any other dimension EOF cat >> "$ROOT/prompts/v3.prompt.md" <<'EOF' Candidate override: - candidate id: v3 - variable: idempotency strategy - setting: webhook processing ledger - do not change any other dimension EOF for id in v1 v2 v3; do test -s "$ROOT/prompts/$id.prompt.md" && echo "$id prompt:OK" done ``` For checkout UI integration, the same shape works: ```text variable: UI integration strategy v1 setting: inline payment method selector in checkout form v2 setting: account drawer payment method selector v3 setting: review-step payment method selector ``` Keep database contracts, provider APIs, security constraints, and verification fixed unless those are the chosen variable. ## Fan-Out Use the same launch shape for every candidate. Local background shape: ```bash GEN="codex" for id in v1 v2 v3; do ( cd "$PARENT/$id" "$GEN" "$(cat "$ROOT/prompts/$id.prompt.md")" ) > "$ROOT/logs/$id.generate.log" 2>&1 & done wait ``` Visible pane shape: ```bash cmux-run-surface "cd '$PARENT/v1' && codex \"$(cat '$ROOT/prompts/v1.prompt.md')\"" cmux-run-surface "cd '$PARENT/v2' && codex \"$(cat '$ROOT/prompts/v2.prompt.md')\"" cmux-run-surface "cd '$PARENT/v3' && codex \"$(cat '$ROOT/prompts/v3.prompt.md')\"" ``` What to preserve: ```text same base prompt same invariants same launch shape one isolated lane per candidate one log per candidate ``` ## Verify Every Candidate Run the same verification command for every candidate. ```bash VERIFY='pnpm test billing-webhook -- --runInBand && pnpm build' : > "$ROOT/review/verification.tsv" for id in v1 v2 v3; do ( cd "$PARENT/$id" bash -lc "$VERIFY" ) > "$ROOT/logs/$id.verify.log" 2>&1 status=$? printf '%s\t%s\t%s\n' "$id" "$status" "$VERIFY" \ >> "$ROOT/review/verification.tsv" done column -t -s $'\t' "$ROOT/review/verification.tsv" ``` Save diff material for review: ```bash for id in v1 v2 v3; do git -C "$PARENT/$id" diff --stat \ > "$ROOT/review/$id.diffstat.txt" git -C "$PARENT/$id" diff \ > "$ROOT/review/$id.diff.patch" done ``` For UI candidates, also save screenshots: ```bash mkdir -p "$ROOT/review/screenshots" # Save: # "$ROOT/review/screenshots/v1.png" # "$ROOT/review/screenshots/v2.png" # "$ROOT/review/screenshots/v3.png" ``` ## Review Surface Use the lightest surface that makes comparison honest. | Surface | Use When | Save | | --- | --- | --- | | simple matrix | text, plans, test results, diffs | `review/comparison.md` | | diff review | code changes matter most | `review/v*.diff.patch` | | screenshots | UI integration or visual changes | `review/screenshots/` | | test results | correctness is the main gate | `logs/*.verify.log`, `review/verification.tsv` | | structured feedback | choice needs to be preserved exactly | `decisions/selection.md` or saved JSON | Create comparison notes: ```bash cat > "$ROOT/review/comparison.md" < "$ROOT/decisions/selection.md" <<'EOF' # Saved Decision - outcome: - primary candidate: - secondary candidate ids: - decision: - why: - rejected candidates: - required follow-up: - final verification command: ## Review Notes - v1: - v2: - v3: ## Continue Prompt Continue from this saved decision. Do not reopen the entire search. Preserve the selected candidate. Apply only the named feedback. Run final verification and save the result. EOF ``` Use the saved decision as the next prompt material: ```bash cat "$ROOT/decisions/selection.md" \ | p --stdin --print-prompt \ "Use this saved decision to converge the variation set. Keep scope narrow and run the required verification." \ > "$ROOT/prompts/converge.prompt.md" test -s "$ROOT/prompts/converge.prompt.md" && echo "converge-prompt:OK" ``` ## Ask The Agent This Create a variation matrix: ```text Create a controlled variation matrix for adding saved payment methods to checkout. Use exactly one variable: UI integration strategy. Keep database schema, provider API, auth behavior, and verification fixed. Propose three candidates, the same verification command for each, isolation strategy, review criteria, and the saved decision file shape. ``` Generate candidate prompts: ```text Using this base Prompt Builder prompt, create three candidate prompts. Each candidate must preserve the same goal, invariants, verification command, and review criteria. Only vary the idempotency strategy for the billing webhook: provider event id guard, invoice-level processing lock, and webhook processing ledger. Do not introduce a second variable. ``` Review a finished variation set: ```text Review this variation run. Inspect the matrix, candidate prompts, verification logs, diffs, and comparison notes. Decide Pick, Combine, Refine, Expand, or Reject. If Combine, choose one primary candidate and name the exact pieces to take from the others. ``` Converge after selection: ```text Use this saved decision to converge the variation set. Do not reopen the entire search. Preserve the selected candidate, apply only the named feedback, run the final verification command, and save the result. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | base prompt saved | `test -s "$ROOT/prompts/base.prompt.md"` | | launch shape saved | `test -s "$ROOT/launch/base.launch.json"` | | matrix exists | `test -s "$ROOT/matrix.md"` | | one variable named | matrix has one `Variable Under Test` | | candidates isolated | each candidate has a distinct branch/worktree/directory | | same verification | `verification.tsv` shows the same command for every candidate | | logs saved | `find "$ROOT/logs" -type f | sort` | | diff/review material saved | `find "$ROOT/review" -type f | sort` | | comparison complete | `test -s "$ROOT/review/comparison.md"` | | decision saved | `test -s "$ROOT/decisions/selection.md"` | | convergence prompt saved | `test -s "$ROOT/prompts/converge.prompt.md"` | ## If It Goes Wrong ### Candidates Changed Multiple Variables Stop and rewrite the matrix. ```text If the candidate changes UI, database schema, and test strategy, it is not a controlled variation. ``` Recovery: ```text Keep one chosen variable. Move every other change into invariants or out-of-scope. Regenerate candidate prompts. ``` ### Verification Differs Per Candidate The comparison is weak if every candidate gets a different proof command. Recovery: ```text Pick one verification command before generation. If a candidate needs a different proof, that is evidence for a new round. ``` ### Repo Was Dirty Before Fan-Out Dirty state is not forbidden. Unknown dirty state is the problem. Recovery: ```bash git status --short git diff git diff --staged ``` Then commit, stash, clean, or explicitly record what should carry into every candidate. ### Best Idea Is Split Across Candidates Use `Combine`, not vague merging. ```text primary candidate: v2 take from v1: rollback guard take from v3: test fixture forbidden: unrelated renames ``` Then run final verification after convergence. ### All Candidates Fail Do not pretend one failed candidate won. Use: ```text Reject ``` or: ```text Expand with a narrower matrix ``` Save what the failures proved before starting the next round. ## References And Resources - Prompt Builder seed prompt: `p --print-prompt` - Prompt Builder launch JSON: `p --print-launch-json` - Local run folder: `artifacts/variations//` - Candidate isolation: `git worktree` - Repo state checks: `git status --short`, `git diff`, `git diff --staged` - Review artifacts: `review/verification.tsv`, `review/comparison.md`, `decisions/selection.md` ## Operational boundaries - The fan-out snippets describe the launch shape, not a universally executable harness. Resolve `$ROOT` to an absolute artifact directory before changing into worktrees; validate nested quoting and the installed Codex non-interactive invocation. - A candidate process exiting or `wait` returning is not passing proof. Capture each generation exit status and run the same project-valid verification command in every lane. - Git worktrees start from committed state. A plain `git diff` omits staged, untracked, and already committed candidate changes; preserve the actual baseline and all relevant review evidence. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-variation-workflows-reference Topic: Planning Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Controlled variation workflows: practice drills These exercises practice turning one deliberate prompt into controlled, verified candidates. Use a real software project when possible. Keep each exercise small. The goal is not to generate the most candidates; the goal is to compare useful options without losing control. ## Exercise 1: Decide Whether Variations Are Appropriate For each task, choose `use variations` or `skip variations`. | Task | Use / Skip | Why | | --- | --- | --- | | Add saved payment methods to checkout, with several plausible UI entry points | | | | Fix a one-character typo in a route name | | | | Stop duplicate billing webhook processing, with multiple plausible idempotency strategies | | | | Apply a strict framework migration with exact steps | | | | Compare auth/session architecture before refresh-token rotation | | | | Implement an exact requested API shape | | | | Choose the right test boundary for a regression | | | | Repo is dirty and there is no saved state | | | | No verification command exists for the candidates | | | Write: ```markdown # Variation Decision - task: - decision: - why: - verification available: - state safe for fan-out: ``` ## Exercise 2: Find The Variable Pick one request and identify the single variable under test. | Request | Possible Variable | | --- | --- | | Checkout saved payment methods could be integrated several ways. | UI integration strategy | | Billing webhooks sometimes process the same invoice twice. | idempotency strategy | | Auth/session code is becoming hard to reason about. | architecture boundary | | This regression needs better coverage. | test boundary | | The agent keeps producing broad implementation plans. | prompt framing | | The docs are technically correct but hard to use. | documentation organization | Fill out: ```markdown # Variable Notes - request: - chosen variable: - why this variable matters: - invariants: - - - - out of scope: - - - - candidate count: - review question: ``` Rule: ```text If you cannot finish "we are comparing candidates that differ only by ___," stop and narrow. ``` ## Exercise 3: Write A Variation Matrix Use one of these scenarios: ```text checkout saved payment methods billing webhook duplicate-processing auth/session architecture test strategy for a regression ``` Template: ```markdown # Variation Matrix ## Goal ## Invariants - same repo state: - same base prompt: - same target feature or bug: - same constraints: - same verification command: - same review criteria: ## Variable Under Test - variable: - why this matters: - what is out of scope: ## Candidate Count - count: - ids: ## Candidates | ID | Variable setting | Output location | Verification command | Notes | | --- | --- | --- | --- | --- | | v1 | | | | | | v2 | | | | | | v3 | | | | | ## Review Criteria 1. 2. 3. 4. 5. ``` Check it: ```bash rg -n "Goal|Invariants|Variable Under Test|Candidate Count|Review Criteria" matrix.md ``` ## Exercise 4: Create The Run Folder Create a run root under `artifacts/variations`. ```bash RUN_ID="exercise-$(date +%Y%m%d-%H%M%S)" ROOT="artifacts/variations/$RUN_ID" mkdir -p "$ROOT"/{prompts,launch,logs,review,decisions} mkdir -p "$ROOT"/candidates/{v1,v2,v3} find "$ROOT" -maxdepth 3 -type d | sort ``` Fill out: ```markdown # Run Folder Notes - run id: - root: - prompt folder: - launch folder: - candidate folders: - logs folder: - review folder: - decisions folder: ``` ## Exercise 5: Save The Section 5 Seed Use Prompt Builder to save the base prompt and launch JSON. Checkout example: ```bash PROMPT='Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes.' p --print-prompt "$PROMPT" \ > "$ROOT/prompts/base.prompt.md" p --print-launch-json "$PROMPT" \ > "$ROOT/launch/base.launch.json" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" jq '.mode, .prompt' "$ROOT/launch/base.launch.json" ``` Billing example: ```bash PROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.' p --print-prompt "$PROMPT" \ > "$ROOT/prompts/base.prompt.md" p --print-launch-json "$PROMPT" \ > "$ROOT/launch/base.launch.json" ``` Fill out: ```markdown # Seed Notes - base prompt path: - launch JSON path: - software goal: - invariant 1: - invariant 2: - variable: - candidate count: - verification command: - seed ready? yes/no - one improvement before fan-out: ``` ## Exercise 6: Checkpoint Repo State Before fan-out, save the current repo state. ```bash git status --short | tee "$ROOT/review/git-status-before.txt" git diff > "$ROOT/review/dirty-before.patch" git diff --staged > "$ROOT/review/staged-before.patch" ``` Fill out: ```markdown # Repo State Before Fan-Out - status file: - unstaged patch file: - staged patch file: - repo clean? yes/no - if dirty, what is the dirty work: - safe next move: ``` Choose one safe next move: | Situation | Move | | --- | --- | | repo clean | continue | | intentional local work | commit or stash | | unrelated local work | move it out of the candidate path | | generated noise | clean or move under `artifacts/` | | unsure | inspect before launching | ## Exercise 7: Choose Isolation Pick the isolation level for your variation set. | Candidate Type | Best Isolation | Why | | --- | --- | --- | | prompt rewrites only | copied prompt/output folders | | | implementation candidates editing same files | git worktrees | | | small sequential experiments | branches | | | UI variants that can coexist | feature flags | | | services that need ports | unique process state | | | generated docs | output directories | | Write: ```markdown # Isolation Plan - chosen isolation: - why: - what could collide: - how collisions are prevented: - where outputs go: - where logs go: - how to clean up: ``` ## Exercise 8: Build Candidate Prompts Copy the base prompt, then append one candidate setting. ```bash for id in v1 v2 v3; do cp "$ROOT/prompts/base.prompt.md" "$ROOT/prompts/$id.prompt.md" done ``` Checkout UI integration example: ```bash cat >> "$ROOT/prompts/v1.prompt.md" <<'EOF' Candidate override: - candidate id: v1 - variable: UI integration strategy - setting: inline payment method selector in the checkout form - do not change any other dimension EOF cat >> "$ROOT/prompts/v2.prompt.md" <<'EOF' Candidate override: - candidate id: v2 - variable: UI integration strategy - setting: account drawer payment method selector - do not change any other dimension EOF cat >> "$ROOT/prompts/v3.prompt.md" <<'EOF' Candidate override: - candidate id: v3 - variable: UI integration strategy - setting: review-step payment method selector - do not change any other dimension EOF ``` Confirm: ```bash for id in v1 v2 v3; do echo "== $id ==" rg -n "Candidate override|variable:|setting:|do not change" "$ROOT/prompts/$id.prompt.md" done ``` Fill out: ```markdown # Candidate Prompt Notes | Candidate | Variable setting | Same base prompt? | Same invariants? | | --- | --- | --- | --- | | v1 | | | | | v2 | | | | | v3 | | | | ``` ## Exercise 9: Run The Same Verification Pick one verification command for every candidate. Examples: ```bash VERIFY='pnpm test checkout -- --runInBand && pnpm build' VERIFY='pnpm test billing-webhook -- --runInBand && pnpm build' VERIFY='pnpm test auth -- --runInBand && pnpm build' VERIFY='pnpm test -- --runInBand' ``` Run: ```bash : > "$ROOT/review/verification.tsv" for id in v1 v2 v3; do ( cd "$PARENT/$id" bash -lc "$VERIFY" ) > "$ROOT/logs/$id.verify.log" 2>&1 status=$? printf '%s\t%s\t%s\n' "$id" "$status" "$VERIFY" \ >> "$ROOT/review/verification.tsv" done column -t -s $'\t' "$ROOT/review/verification.tsv" ``` Fill out: ```markdown # Verification Notes - verification command: - v1 status: - v1 log: - v2 status: - v2 log: - v3 status: - v3 log: - candidates excluded from review because they failed: - candidates allowed into review: ``` ## Exercise 10: Build A Comparison File Create a simple review surface. ```bash cat > "$ROOT/review/comparison.md" < "$ROOT/decisions/selection.md" <<'EOF' # Saved Decision - outcome: - primary candidate: - secondary candidate ids: - decision: - why: - rejected candidates: - required follow-up: - final verification command: ## Review Notes - v1: - v2: - v3: ## Continue Prompt Continue from this saved decision. Do not reopen the entire search. Preserve the selected candidate. Apply only the named feedback. Run final verification and save the result. EOF ``` Create the convergence prompt: ```bash cat "$ROOT/decisions/selection.md" \ | p --stdin --print-prompt \ "Use this saved decision to converge the variation set. Keep scope narrow and run the required verification." \ > "$ROOT/prompts/converge.prompt.md" test -s "$ROOT/decisions/selection.md" && echo "decision:OK" test -s "$ROOT/prompts/converge.prompt.md" && echo "converge-prompt:OK" ``` ## Exercise 13: Failure Path Drill For each failure, choose the recovery. | Failure | Recovery | | --- | --- | | candidates changed multiple variables | | | verification command was different for every candidate | | | repo was dirty and unrelated changes leaked into diffs | | | v1 passed but merge into the main branch conflicts | | | best idea is split between v1 and v3 | | | all candidates fail verification | | | review notes say “I like parts of all of them” | | | candidate output folders overwrote each other | | | UI candidates have no screenshots | | | Expand round changes the previous decision | | Recovery options: ```text rewrite matrix regenerate candidates define verification first checkpoint repo state use worktrees or separate directories pick a primary candidate use Combine with named parts use Reject use Expand with a new matrix save screenshots rerun final verification ``` Fill out: ```markdown # Failure Recovery Notes - failure: - likely cause: - recovery: - command or file to inspect: - how to know recovery worked: ``` ## Exercise 14: Final Check Run these checks on your variation run. ```bash test -s "$ROOT/matrix.md" && echo "matrix:OK" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" test -s "$ROOT/launch/base.launch.json" && echo "launch-json:OK" find "$ROOT/prompts" -type f | sort find "$ROOT/logs" -type f | sort test -s "$ROOT/review/comparison.md" && echo "comparison:OK" test -s "$ROOT/decisions/selection.md" && echo "decision:OK" ``` Fill out: ```markdown # Final Variation Run Check - every candidate had the same base prompt? yes/no - every candidate changed one variable? yes/no - every candidate was isolated? yes/no - every candidate used the same verification command? yes/no - verification logs saved? yes/no - comparison notes saved? yes/no - decision saved? yes/no - convergence prompt saved? yes/no - ready to implement selected path? yes/no ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-variation-workflows-practice Topic: Planning Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Design, Video, and QA Story Field Guide > Original source pages and recordings require authorized access. The full article text here is public. Convert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories. Use this when words are weak and Codex needs visual requirements plus browser-verifiable acceptance criteria. ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | design.md | Durable taste contract | Style DNA, type, color, layout | design.md | | Image reference | Human-selected direction | Implement one concrete look | .notes/design/reference.png | | Video requirements | Narrated UX behavior | Extract acceptance criteria and edge cases | .goals/-video.md | | QA swarm | Weird-path exploration | Personas, broken paths, browser receipts | .notes/qa/ | ## Agent-ready prompt ```text Treat the visual artifact as requirements, not decoration. Extract acceptance criteria, user stories, responsive states, and proof moves. Implement only the selected direction. Verify in browser with screenshots/logs. Write the durable contract to design.md, .goals/.md, or .notes/qa/.md depending on the task. ``` ## Applied stories ### Reference image to UI **Role:** Product engineer The team can recognize the desired look but cannot write the CSS spec. **Agent brief:** Ask Codex to distill the selected image into design.md, implement one route, then browser-proof the result. **Done when:** - design.md update - implemented route - desktop/mobile screenshots - diff review ### Narrated bug report **Role:** Full-stack developer A PM records cart behavior that is faster to show than explain. **Agent brief:** Extract requirements from video into a goal file, implement behavior, and prove cart states in browser. **Done when:** - video-derived goal - acceptance criteria - browser proof - test/typecheck log ### 5 Monkeys QA swarm **Role:** QA-minded frontend lead Happy path passes, but users hit weird navigation and state sequences. **Agent brief:** Launch persona-based QA workers that write reproducible findings, then collate only high-signal bugs. **Done when:** - persona findings - dedupe summary - screenshots - repro steps ## Tips and gotchas - Do not ask Codex to invent taste from nothing; hand it references and constraints. - A video should become acceptance criteria, not a brittle click macro. - Keep visual QA disposable until the flow stabilizes; promote only stable checks to tests. - Every visual/design story should end with browser proof across relevant viewports. ## References - [Impeccable](https://impeccable.style/) - [Inspiration board](https://inspiration-board.pages.dev/) - [OpenAI Codex Figma/frontend post](https://developers.openai.com/codex) - [Playwright screenshots](https://playwright.dev/docs/screenshots) ## Related principles - [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) - [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/) - [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/) - [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/) Reference ID: foundations-design-video-qa-field-guide Topic: Planning Sources: - [Agent foundations: Trust current source and capture design decisions (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-04.html) - [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html) - [Agent foundations: Use images, video, and task-shaped model routing (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-06.html) - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Generate controlled, verified variations When code and design candidates are cheap, the mistake is not generating too many. **The mistake is generating them randomly.** Start by defining the candidates, keep the comparison controlled, run each option through the same constraints, and review the outputs on a surface that makes the decision obvious enough to defend later. ## Start With A Candidate List Ask the agent to **generate the dataset first**: styles, strategies, prompts, layouts, implementation approaches, or test boundaries. Remove duplicates, rename vague entries, and make sure each candidate is **different for a reason**. > To do variations, like, you come up with the variations first. > > — John Lindquist ## Vary One Thing At A Time If every candidate changes layout, data model, tests, and copy, you are **no longer comparing candidates**. You are just admiring chaos with a folder structure. ## Use The Same Base Prompt Candidate prompts should **differ only by the named variable**. Keep the base prompt, constraints, review criteria, and verification command identical. ## Fan Out After The Matrix Is Clear Parallelization is useful after you know what each lane is supposed to test. **Treat the candidate list like data**: each lane gets a candidate id, one variable setting, and the same proof requirement. > I definitely wouldn't rely on setting a long loop… Because then you get into, like, after a while, compaction and other things where you lose that context and things start to look alike. > > — John Lindquist ## Preserve The Review Surface For UI work, use screenshots or a [gallery](https://inspiration-board.pages.dev/variations/01-masonry-grid). For code, use diffs, test logs, and a short comparison table. **Save the artifacts before choosing** so the decision does not disappear into memory. ## Pick, Combine, Refine, Expand, Or Reject Those are the valid outcomes. **Choose one explicitly.** If two candidates each have one strong idea, combine the named pieces. If the whole batch is wrong, reject the batch and update the matrix. ## Turn The Winner Into A Real Build A generated mockup is **direction, not shipped UI**. Use the selected candidate as the reference for a verified implementation pass. The next prompt should say what won, why it won, what to preserve, what to fix, and what proof counts as done. ## Copyable Prompt: Candidate Matrix ```text Create a variation matrix for a software UI concept. Goal: Design a mobile app screen for browsing saved listings. Variable under test: Visual layout direction. Generate 8 candidate directions. For each candidate, include: - id - layout direction - design constraints - what should stay identical - what would make this candidate fail review Do not generate the UI yet. Return the candidate matrix first. ``` ## Copyable Prompt: Refine The Winner ```text Continue from this saved variation decision. Outcome: Refine. Primary candidate: v2. Why: It best preserves the constraints and passes the review criteria. Preserve: - the selected layout structure - the interaction model - the accepted visual hierarchy Fix: - tighten spacing on mobile - improve empty-state copy - keep the same data model Verification: Run the same verification command from the matrix and save the result. Do not reopen the candidate search. ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#verified-variations) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-verified-variations Topic: Planning Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#verified-variations) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Generate to diverge, code to converge Keep the subject fixed while exploring structural alternatives, then turn the selected bitmap into verified code. ## Related working material - [Generate to diverge, code to converge — prompts and exercises](/topics/factory-design-variations-practice/) - [Generate to diverge, code to converge — questions and tradeoffs](/topics/factory-design-variations-questions/) - [Generate to diverge, code to converge — worked example](/topics/factory-design-variations-worked-example/) ## TL;DR - One prompt to Codex (`$imagegen`) or the Antigravity CLI (`agy`) generates **9 wildly different design mockups** straight into your project — no API key. - You walk away with both verbatim 9x prompts, both run scripts, and a live-updating contact-sheet gallery that fills in as images land. - The one move: **hold the subject constant, vary only the style** — then rebuild the winning bitmap as real HTML/CSS. Generate to diverge, code to converge. Have your agent set this up — paste this into it: ``` text Fetch https://indigo-kayak-2zw8.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## Design exploration stalls on production, not taste You sit down to design a landing page. The usual move is to build one draft and iterate. Each iteration costs an hour or more, so you see maybe three directions before you commit. That is not a taste problem — it is a production problem: you cannot prefer an option you never saw. When a mockup costs a minute instead of an hour, exploring nine directions becomes the cheap default. Prior sessions on this machine show the whole loop fitting in one sitting: one run produced five bitmap mockup directions for a storefront, collected them into a gallery page, and finished with a chosen winner rebuilt as real code. ## Two CLIs, one pattern Codex ships an `$imagegen` skill that routes image requests through its built-in `image_gen` tool — no API key required, and its contract explicitly lists UI mockups and wireframes as intended uses. The Antigravity CLI exposes a `generate_image` tool the same way. Both run non-interactively (`codex exec "…"` / `agy -p "…"`) and both follow the same batch rule: one image call per mockup, never a switch to an API fallback. Two traps, both from real runs. Codex saves built-in image output under `$CODEX_HOME/generated_images/` — if your prompt doesn't say "copy each image into `./mockups/`", the run can succeed while your project folder stays empty. And agy's `--print-timeout` defaults to five minutes; nine images take longer, so the run script raises it to fifteen. The failure signal for both is the same: an empty contact sheet. Read the run log before blaming the model. ## Hold the subject constant Nine images are only useful if you can compare them, and they are only comparable if exactly one variable changes. "Make nine cool designs" gives you nine incomparable posters. "Same homepage, same hero, same call to action — nine styles" gives you a controlled experiment you can read at a glance. The inspiration-board pipeline enforces this discipline with a shared subject file appended to every style prompt, "so you can compare how each visual approach handles" the same material. Before you run, write your subject as one sentence that names the page type and its content; if a mockup comes back as a different page type, regenerate it — don't compare it. ## From party trick to 200-style pipeline Nine mockups is a live demo. Two hundred is a pipeline, and the difference is error handling. The [inspiration-board](https://inspiration-board.pages.dev/variations/01-masonry-grid) project generates its images by driving the Antigravity CLI from a bash loop across 200 named web-design styles. Its generator demands machine-readable status from every run — the JSON contract in the prompt library above — fixes each output filename in advance, and skips any file already on disk above 100 KB, so quota-interrupted runs resume instead of restarting. When your own loop grows past a handful of images, adopt those in order: fixed names, skip-if-exists, JSON status, then background jobs with progress lines. The variations idea applies twice there: the images are style variations, and the gallery pages themselves are twelve layout variations of the same image set — masonry grid, infinite scroll, carousel, lightbox, compare-split, magazine editorial, filmstrip, table list, mood board, fullscreen slideshow, grouped categories, search-first. ## Bitmap to real code The mockups are bitmaps — for deciding, not shipping. The loop closes when you pick one tile and hand it back to a coding agent as a reference image, using the converge prompt in the library. Your decision rule: pick the tile you would be embarrassed to lose. If no tile clears that bar, the styles were not divergent enough — widen the directions and rerun rather than polishing the least-bad option. ## Appendix ### Limits & caveats - The quota-handling and skip-guard evidence comes from one project's scripts driving one CLI. The sources do not establish that other agents fail the same way, or how often quota errors occur — only how this pipeline survives them. - No source here measures whether any generated direction is aesthetically *better*. That judgment stays with you. - A prior batch run stalled silently mid-generation and the operator had to ping the session ("hello? What is happening?"). The recorded lesson: run each image generation as its own background job and make the agent narrate progress. - Codex also has a gated CLI fallback for image generation (needs `OPENAI_API_KEY` and an explicit request). You never need it for this workflow — "many assets" still means one built-in call per asset. - `--dangerously-bypass-approvals-and-sandbox` and `--dangerously-skip-permissions` skip permission prompts. Use them in projects you trust, not on machines or folders you care about being prompted for. - agy image quota errors are real; the JSON status contract exists because retrying silently wastes the whole loop. Report the reset time instead. - The workshop agenda spells the skill `$imgagegen` — that's a typo; it's `$imagegen`. ## Operating practice ### Diverge first, then record taste #### What to notice Make important design choices visible while change is cheap, then turn preference into a reusable contract. #### Try this Generate four structurally distinct options, compare pairs, and record both the winning property and the **rejection reason**. > “When code is disposable, code is cheap.” John Lindquist · [04:43:09](https://proud-anchor-53zn.here.now/watch.html?t=16989#recording-player) #### Concept Hold content and product intent constant while varying hierarchy, density, navigation, and interaction emphasis. Promote repeated choices into DESIGN.md so the next agent can apply and challenge them. #### Reflection Four options is a bounded companion exercise. The recorded demonstration produced more; neither count is a universal rule. **Recording evidence:** listen at 04:42:47. > “Never underestimate the power of just, being a curator. When the agent can be a generator.” John Lindquist · [04:50:49](https://proud-anchor-53zn.here.now/watch.html?t=17449#recording-player) [Open Generate Variations](https://indigo-kayak-2zw8.here.now/)[Open This or That — Preference Capture](https://gentle-lasso-9d5n.here.now/) #### Links shared for this topic - [Mini Arcade](https://miniarcade.dev/) — A generated product used as a design and implementation example. - [Mini Arcade source](https://github.com/johnlindquist/miniarcade) — The source repository behind the product example. - [Inspiration Board](https://inspiration-board.pages.dev/) — A board for collecting and comparing visual references. - [Impeccable](https://impeccable.style/) — Design guidance and reusable taste constraints for agents. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=16967#q3-variations-taste) Reference ID: factory-design-variations Topic: Planning Sources: - [Generate to diverge, code to converge](https://indigo-kayak-2zw8.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste) --- # Generate to diverge, code to converge — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Design Variations Automated generation of distinct visual interfaces via decoupled parallel sub-agents. ### RLHF Style Selection Extracting human visual taste parameters through continuous paired choice evaluations. ### Style DNA Prompting Re-injecting ranked image reference structures back into generation agents to guide aesthetic consistency. ### Taste Curation / Preference Training The process of providing targeted human feedback and stylistic constraints to train and shape AI output patterns according to the user's specific aesthetics or architectural choices. ### Exposing Agent Decision Spaces An architectural pattern where an agent surfaces multiple internal candidates or configurations to the user for explicit human selection, rather than making hidden decisions autonomously. ### Curator vs. Generator Framework Steering generative capabilities by applying precise personal aesthetic constraints and reference examples. ### Style DNA Extraction Consolidating specific font, layout, and color metadata into a standardized design specification doc to inform automated multi-page layouts. ### Automated Visual Verification Using headless browser frameworks within an AI pipeline to validate rendering outputs prior to reporting task completion. ### GitHub CLI Agent Discovery Leveraging gh CLI inside an AI agent prompt to programmatically search, filter, and summarize open-source repository contributions. ### Browser Terminal Emulation Simulating agent CLI execution flows inside browser web components (as seen on mdflow.dev) to present workshop exercises deterministically without execution delays. ### Design System Specification File (DESIGN.md) Storing detailed design system rules, color palettes, and constraints in a standardized DESIGN.md file to lock AI models into exact visual styles. ### Modular Agent Design Skills Specialized slash commands (e.g. /typeset, /colorize, /critique, /polish) that direct LLMs to evaluate and fix specific aspects of frontend layout and UI. ### Local Named Domain Proxying (Portless) Replacing port-based localhost URLs with named .localhost domains to streamline OAuth authentication and callbacks. ### CDP Automation via AI Agents Leveraging Chrome DevTools Protocol inside headless browser agents to profile latency, first paint, and network performance. ### Generative UI Rendering LLMs generating structured JSON UI specifications that front-end packages render dynamically. ### Iconography vs. Custom SVG Models tend to draw inline SVG code when generating UI visuals, which often results in poor layout quality; specifying standardized icon libraries like Lucide yields cleaner outcomes. ### 9x Mockups / Rapid Variation Generating multiple image/UI mockups from a single prompt allows developers to explore design options before writing production code. ### This or That / RLHF for Agents A rapid comparative choice loop where human preference selections ('swipe left, swipe right') train or guide agent decisions and teach aesthetic taste. ### Inverse Questioning (GrillMe vs. Filtering) Rather than conducting an extensive upfront technical interview (as in grill-me), an inverse flow generates candidate options first and discards unselected choices. ## Questions and answer status ### How do you maintain design consistency across iterations? For example, once you've chosen a branding direction, how do you ensure the model keeps generating assets in that exact style? **Status: answered.** John recommends using Impeccable (impeccable.style), which records styling choices in a DESIGN.md file and provides dedicated design skills (/typeset, /colorize, /animate, /critique) to prevent AI style drift. ### How do you maintain design consistency across iterations once a branding direction is chosen? **Status: answered.** John demonstrates using structured design systems (e.g., Impeccable) and explicit system rules regarding icons/SVGs to maintain consistency across AI generations. ## Exercises - **Try:** Select four design references from your workspace, extract their elements into a clear markdown file named DESIGN.md, and run an autonomous agent cycle to automatically build and host matching variations. **Basis:** 04:50:19.335 visual log of files read and written to configure design presets. - **Try:** Use Impeccable to create a DESIGN.md specification for an app and run /typeset or /colorize skills to maintain design consistency across AI generations. **Basis:** Demonstrated by John Lindquist between 04:56:31 and 04:57:53 in response to a participant's question. - **Try:** Author agent prompts leveraging agent-browser and CDP to inspect page load latency and initial paint metrics. **Basis:** John prompts Claude Code to use agent-browser for detecting latency and perf issues in mdflow.dev. - **Try:** Set up a 'This or That' comparative choice skill/flow to evaluate generated design variations and teach agent taste. **Basis:** You can set up a skill for this... walks through setting up the skill or the flow for this... give it a shot to see how you like it. (transcript 05:03:31 - 05:05:22) ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [04:44:43](https://proud-anchor-53zn.here.now/watch.html?t=17083#recording-player) — Describes the image generation scripting process using Codex, Antigravity, and Grok engines. - [04:45:22](https://proud-anchor-53zn.here.now/watch.html?t=17122#recording-player) — Triggers the side-by-side tournament UI layout game. - [04:46:15](https://proud-anchor-53zn.here.now/watch.html?t=17175#recording-player) — Completes visual alignment selections to load the taste profile screen. - [04:46:28](https://proud-anchor-53zn.here.now/watch.html?t=17188#recording-player) — Extracts the generated structured prompt block text to system clipboard. - [04:46:32](https://proud-anchor-53zn.here.now/watch.html?t=17192#recording-player) — Pastes markdown style data rules directly into the clipboard.md active buffer view. - [04:46:34](https://proud-anchor-53zn.here.now/watch.html?t=17194#recording-player) — Code editor displays clipboard.md containing Reference 1 - Pop Art Publication, Reference 2 - Garden and Botanical Journal, and Reference 3 - Newspaper Sunday Comics style specifications. - [04:46:35](https://proud-anchor-53zn.here.now/watch.html?t=17195#recording-player) — John Lindquist references the PopArt publication style prompt used to generate the reference images. - [04:46:58](https://proud-anchor-53zn.here.now/watch.html?t=17218#recording-player) — John Lindquist pastes 171 lines from clipboard.md into Claude Code and appends user feedback requesting a variation integrating these styles, finalized with a publication command. - [04:47:48](https://proud-anchor-53zn.here.now/watch.html?t=17268#recording-player) — Claude Code prints out the final response requirements, design deliverables list, and initiates network file requests to pull reference assets. - [04:47:48](https://proud-anchor-53zn.here.now/watch.html?t=17268#recording-player) — John Lindquist explains that human feedback and reinforcement learning allow developers to train models based on their unique style and structural tastes. - [04:48:28](https://proud-anchor-53zn.here.now/watch.html?t=17308#recording-player) — John Lindquist advocates for agents exposing all choice paths to the driver's seat instead of autonomously choosing one hidden alternative out of a billion options. - [04:48:49](https://proud-anchor-53zn.here.now/watch.html?t=17329#recording-player) — Claude Code records tool logs completing a file write action that saves 570 lines of data to DESIGN.md. - [04:49:58](https://proud-anchor-53zn.here.now/watch.html?t=17398#recording-player) — Claude Code invokes the custom Skill(here-now), resulting in a successful load status message. - [04:50:07](https://proud-anchor-53zn.here.now/watch.html?t=17407#recording-player) — John Lindquist suggests capturing bookmarks, screenshots, and photos of real-world inspiration to inject into agent environments to align design outcomes. - [04:50:19](https://proud-anchor-53zn.here.now/watch.html?t=17419#recording-player) — The terminal window displays an ongoing agent loop log showing files read and code written to DESIGN.md by Claude. - [04:50:19](https://proud-anchor-53zn.here.now/watch.html?t=17419#recording-player) — John talks about collecting items of personal inspiration around the house to refine design taste. - [04:50:46](https://proud-anchor-53zn.here.now/watch.html?t=17446#recording-player) — The terminal display updates to show all pane tests passed and a list of updated configuration targets. - [04:51:24](https://proud-anchor-53zn.here.now/watch.html?t=17484#recording-player) — A Markdown table becomes visible in the terminal log containing nine style variations and their corresponding live deployment links. - [04:53:26](https://proud-anchor-53zn.here.now/watch.html?t=17606#recording-player) — John return to the terminal pane to observe agent logs documenting index.html rendering and agent-browser actions. - [04:53:34](https://proud-anchor-53zn.here.now/watch.html?t=17614#recording-player) — John points out that the agent is utilizing agent-browser for live UI checks. - [04:54:27](https://proud-anchor-53zn.here.now/watch.html?t=17667#recording-player) — John mentions using the GitHub CLI with an agent to look up Chris Tate's projects. - [04:54:35](https://proud-anchor-53zn.here.now/watch.html?t=17675#recording-player) — Atuin v18.10.0 history menu opens briefly in Ghostty terminal. - [04:54:43](https://proud-anchor-53zn.here.now/watch.html?t=17683#recording-player) — John launches Claude Code v2.1.212 in the terminal. - [04:54:48](https://proud-anchor-53zn.here.now/watch.html?t=17688#recording-player) — John types a prompt into Claude Code asking to use gh cli to find ctate projects from the past 3 months. - [04:55:09](https://proud-anchor-53zn.here.now/watch.html?t=17709#recording-player) — Claude Code begins running gh CLI commands to query GitHub API and pull requests. - [04:55:27](https://proud-anchor-53zn.here.now/watch.html?t=17727#recording-player) — John switches browser tab to mdflow.dev demonstrating browser-based terminal emulation. - [04:55:36](https://proud-anchor-53zn.here.now/watch.html?t=17736#recording-player) — John explains using web terminal emulation to build workshop exercises that emulate agent flows without waiting for live runs. - [04:56:31](https://proud-anchor-53zn.here.now/watch.html?t=17791#recording-player) — John recommends Impeccable as a tool for maintaining design consistency. - [04:56:44](https://proud-anchor-53zn.here.now/watch.html?t=17804#recording-player) — John Lindquist shares https://impeccable.style/ link in chat. - [04:56:48](https://proud-anchor-53zn.here.now/watch.html?t=17808#recording-player) — John describes how Impeccable captures design rules into a DESIGN.md file. - [04:57:20](https://proud-anchor-53zn.here.now/watch.html?t=17840#recording-player) — John scrolls through impeccable.style/designing/ showing skills like /typeset, /colorize, and /animate. - [04:57:53](https://proud-anchor-53zn.here.now/watch.html?t=17873#recording-player) — John presents Impeccable design workflow stages and AI slop detection features at impeccable.style. - [04:59:47](https://proud-anchor-53zn.here.now/watch.html?t=17987#recording-player) — John explains agent-browser capabilities with Chrome DevTools Protocol for latency and paint timing analysis. - [05:00:35](https://proud-anchor-53zn.here.now/watch.html?t=18035#recording-player) — John enters prompt instructing Claude Code to run agent-browser against mdflow.dev. - [05:01:39](https://proud-anchor-53zn.here.now/watch.html?t=18099#recording-player) — John mentions Lucide iconography and advises avoiding custom SVG generation by models. - [05:02:05](https://proud-anchor-53zn.here.now/watch.html?t=18125#recording-player) — John switches to Ghostty terminal showing Claude CLI agent build logs and publication confirmation for misty-rosette-fqyt.here.now. - [05:02:27](https://proud-anchor-53zn.here.now/watch.html?t=18147#recording-player) — John emphasizes the power of mockups and mentions generating images with Codex, Anti-Gravity, and Grok. - [05:03:09](https://proud-anchor-53zn.here.now/watch.html?t=18189#recording-player) — John remarks on image generators frequently producing copyrighted character styles even without direct prompts. - [05:03:31](https://proud-anchor-53zn.here.now/watch.html?t=18211#recording-player) — John explains setting up a 'this or that' skill/flow for collecting human feedback to guide agent design choices. - [05:03:58](https://proud-anchor-53zn.here.now/watch.html?t=18238#recording-player) — John references Matt Pocock's GrillMe skill as an example of an intensive upfront questioning process. - [05:04:31](https://proud-anchor-53zn.here.now/watch.html?t=18271#recording-player) — John describes how filtering generated choices ('swipe left, swipe right') is the inverse of upfront technical questioning. ### Unresolved: Specific CLI shell configuration parameter shortcuts utilized at 04:43:40.000. Terminal screen elements change lines rapidly right before launch rendering cycles occur. **Discriminating evidence:** Verify matching bash alias mappings within user setup workspace initialization documentation profiles. ### Unresolved: Exact structural data lines passed inside the prompt package. The terminal window condenses large inputs using a custom UI banner displaying '[Pasted text #1 +171 lines]' instead of listing the whole body. **Discriminating evidence:** Requires access to the source code file clipboard.md to evaluate the exact text contents of the prompt template block. ### Unresolved: Exact arguments passed to gh api in Claude Code sub-shell call Text scrolled rapidly in the terminal buffer during execution. **Discriminating evidence:** Recorded key visible commands (gh search prs --author=ctate). ### Unresolved: Claude Code agent execution results for mdflow.dev performance audit. The CLI execution runs in background/asynchronously and output is not shown prior to shard end. **Discriminating evidence:** Check subsequent video shards for output of the performance audit. ### Unresolved: Specific model names used during image generation in the prompt library examples. Transcript mentions 'codecs, anti-gravity and grok', but specific model endpoints are not executed live in this shard. **Discriminating evidence:** Recorded high-level tool names as described by the presenter. ### Demonstration detail: 04:43:40 - Opened terminal inside mdflow project root - Submitted instructions to Claude Code requesting 9 multi-agent variations **Tools observed:** Claude Code CLI. **Command or prompt observations (not a verified recipe):** ```text clx ``` ### Demonstration detail: 04:45:22 - Completed visual style tournament matching loops - Copied custom context configuration properties layout - Pasted code payload structures directly into local file asset **Tools observed:** Google Chrome, Cursor. ### Demonstration detail: 04:46:47 - Switched focus to terminal pane running Claude Code CLI. - Pasted text block from clipboard.md into the Claude Code prompt interface. - Appended style criteria and instructions to publish with the /here-now directive. - Observed automated file creation log for DESIGN.md and internal tool initialization loops. **Tools observed:** Claude Code v2.1.212. **Command or prompt observations (not a verified recipe):** ```text mkdir -p ./refs curl -L ``` ### Demonstration detail: 04:51:28 - Switched through multiple generated style tabs in Google Chrome - Inspected individual page treatments on live subdomains - Checked the here.now active project dashboard panel - Compared variants against the primary mdflow.dev design layout **Tools observed:** Google Chrome. ### Demonstration detail: 04:53:41 - Searched for agent-browser on Google - Opened agent-browser.dev documentation page - Typed a GitHub profile address in the URL address bar **Tools observed:** Google Chrome, Google Search. **Command or prompt observations (not a verified recipe):** ```text npm install -g agent-browser brew install agent-browser/tap/agent-browser npx agent-browser open example.com ``` ### Demonstration detail: 04:54:30 - Opened Claude Code CLI in Ghostty terminal - Submitted prompt to query ctate GitHub projects via gh CLI **Tools observed:** Ghostty, Claude Code v2.1.212, gh CLI, Atuin. **Command or prompt observations (not a verified recipe):** ```text claude gh search prs --author=ctate gh api users/ctate/events ``` ### Demonstration detail: 04:55:27 - Navigated to mdflow.dev in Chrome - Demonstrated step-by-step browser terminal simulator **Tools observed:** Google Chrome. ### Demonstration detail: 04:56:31 - Opened impeccable.style in Chrome - Explored designing workflow and slash commands **Tools observed:** Google Chrome. ### Demonstration detail: 05:00:28 - Opened Claude Code terminal session in ~/dev/mdflow - Submitted performance analysis prompt using agent-browser tool **Tools observed:** Claude Code, agent-browser, zsh. **Command or prompt observations (not a verified recipe):** ```text claude Use agent-browser to detect where we can optimize page load, latency, and any perf-related issues in mdflow.dev ``` ### Demonstration detail: 05:01:39 - Reviewing rendered landing page mockup on misty-rosette-fqyt.here.now - Inspecting section layouts, font styling, and icon blocks **Tools observed:** Google Chrome, Ghostty. ### Demonstration detail: 05:02:05 - Examining Claude CLI execution logs in Ghostty terminal - Verifying reference downloads and publication confirmation **Tools observed:** Ghostty, Claude CLI. ### Demonstration detail: 05:02:24 - Navigating workshop documentation guides on mockups and RLHF - Browsing inspiration grid images **Tools observed:** Google Chrome. **Command or prompt observations (not a verified recipe):** ```text curl -s "http://127.0.0.1:8871/vote" ``` ### Demonstration detail: 05:04:03 - Searching Google for Matt Pocock's grill-me skill - Navigating Matt Pocock's skills repository on GitHub - Copying repo link and pasting into meeting chat **Tools observed:** Google Chrome, Google Search, GitHub. Reference ID: factory-design-variations-discussion Topic: Planning Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Generate to diverge, code to converge — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for generate to diverge, code to converge. ## Quick start Fastest possible taste — 9 website mockups landing in `./mockups/` (needs the Codex CLI; the agy version is in the prompt library): **Before you run it:** this launches Codex — a paid agent — with sandboxing and approval prompts disabled (`--dangerously-bypass-approvals-and-sandbox`). Read the command first and run it only in a project where you're comfortable with the cost and with an unsandboxed agent writing files. ``` text mkdir -p mockups codex exec --dangerously-bypass-approvals-and-sandbox 'Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for a landing page for an indie coffee roaster. The subject stays identical in all 9 - ONLY the visual style varies. One built-in image_gen call per mockup. After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png. Announce progress after each one.' ls mockups/ ``` ## Prompt library The first two prompts use a `{{SUBJECT}}` placeholder — replace it before pasting, or let the run scripts (below) substitute it for you. Keep the subject identical across all 9; that's what makes the results comparable. ### Codex — 9x wildly different website mockups - Agent: Codex CLI (\$imagegen skill) - Working directory: your project root - Expected result: mockups/mockup-01.png … mockup-09.png + 9 named style directions ``` text Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for {{SUBJECT}}. Rules: - The SUBJECT stays identical in all 9 — same product, same page type (homepage), same rough content (hero, nav, one CTA). ONLY the visual style varies. This is what makes them comparable. - Pick 9 maximally divergent directions, e.g.: swiss/international typographic, neo-brutalist, glassmorphic dark, editorial magazine, retro terminal, playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine. Name each direction before generating. - One built-in image_gen call per mockup (do NOT drop to the CLI fallback). - Desktop aspect, full homepage visible, legible headline text. - After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction order you announced). - Announce progress after each one — never go silent. - When all 9 exist, list the 9 directions next to their filenames. ``` ### agy (Antigravity) — 9x wildly different mobile mockups - Agent: agy (Google Antigravity CLI) - Working directory: your project root - Expected result: mockups/mockup-01.png … mockup-09.png, phone aspect, 9 named directions ``` text Generate 9 WILDLY different mobile app UI mockups for {{SUBJECT}} using your generate_image tool. Rules: - SUBJECT is constant across all 9 — same app, same home screen (listing feed, search, one primary action). ONLY the visual style varies. - 9 divergent directions, e.g.: iOS glass minimal, material-you expressive, neo-brutalist, dark luxury, pastel neumorphic, retro pixel, editorial serif, cyberpunk neon, paper-collage tactile. Name each before generating. - One generate_image call per mockup with ImageName mockup_01 ... mockup_09. - Phone aspect ratio (9:19-ish), single screen per image. - After each generation, use run_command to copy the artifact into ./mockups/ as mockup-01.png ... mockup-09.png. - If you hit an image quota error, report it immediately with the reset time instead of retrying silently. - Announce progress after each image. ``` ### JSON status contract — for scripting image gen at scale - Agent: any image-gen agent driven from bash - Working directory: append to your generation prompt - Expected result: one parseable JSON line per run — this is how inspiration-board loops over 200 styles unattended ``` text Respond with ONLY a JSON object (no markdown, no explanation): - Success: {"status":"ok","path":""} - Quota error: {"status":"quota_exhausted","reset_seconds":,"reset_time":""} - Other error: {"status":"error","message":""} ``` ### Converge — rebuild the winner as real code - Agent: Codex or Claude Code - Working directory: project root, after picking a winner (replace 0N) - Expected result: winner/index.html — real text and layout, no bitmap backgrounds ``` text mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds. ``` ## Set it up (agent guide) 1. Create the Codex prompt file. The run script extracts its first fenced block and substitutes the subject. ```` text # Codex prompt — 9x wildly different website mockups Replace `{{SUBJECT}}` with the site you're designing (keep it constant across all 9!). ``` Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for {{SUBJECT}}. Rules: - The SUBJECT stays identical in all 9 — same product, same page type (homepage), same rough content (hero, nav, one CTA). ONLY the visual style varies. This is what makes them comparable. - Pick 9 maximally divergent directions, e.g.: swiss/international typographic, neo-brutalist, glassmorphic dark, editorial magazine, retro terminal, playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine. Name each direction before generating. - One built-in image_gen call per mockup (do NOT drop to the CLI fallback). - Desktop aspect, full homepage visible, legible headline text. - After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction order you announced). - Announce progress after each one — never go silent. - When all 9 exist, list the 9 directions next to their filenames. ``` ## Follow-up (converge on a winner) ``` mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds. ``` ```` 2. Create the agy prompt file (same pattern, mobile mockups, plus the scripted status contract). ```` text # agy (Antigravity) prompt — 9x wildly different mobile mockups Replace `{{SUBJECT}}` with the app you're designing. Historical workshop subject: "a mobile app for selling houses". ``` Generate 9 WILDLY different mobile app UI mockups for {{SUBJECT}} using your generate_image tool. Rules: - SUBJECT is constant across all 9 — same app, same home screen (listing feed, search, one primary action). ONLY the visual style varies. - 9 divergent directions, e.g.: iOS glass minimal, material-you expressive, neo-brutalist, dark luxury, pastel neumorphic, retro pixel, editorial serif, cyberpunk neon, paper-collage tactile. Name each before generating. - One generate_image call per mockup with ImageName mockup_01 ... mockup_09. - Phone aspect ratio (9:19-ish), single screen per image. - After each generation, use run_command to copy the artifact into ./mockups/ as mockup-01.png ... mockup-09.png. - If you hit an image quota error, report it immediately with the reset time instead of retrying silently. - Announce progress after each image. ``` ## Scripted status contract (from the inspiration-board pipeline) When driving agy from bash at scale, demand machine-readable status: ``` Respond with ONLY a JSON object (no markdown, no explanation): - Success: {"status":"ok","path":""} - Quota error: {"status":"quota_exhausted","reset_seconds":,"reset_time":""} - Other error: {"status":"error","message":""} ``` This is the exact contract `generate.sh` in the inspiration-board pipeline uses to loop over 200 styles unattended, with a skip-if-exists guard (file > 100KB). ```` 3. Create the Codex run script. ``` text #!/bin/bash # Fire Codex $imagegen: 9 wildly different website mockups for one subject. # Usage: ./scripts/run-codex-mockups.sh "a landing page for an indie coffee roaster" set -euo pipefail SUBJECT="${1:?usage: $0 \"\"}" DIR="$(cd "$(dirname "$0")/.." && pwd)" mkdir -p "$DIR/mockups" # Extract the first fenced block from the prompt file, substitute the subject. PROMPT="$(sed "s/{{SUBJECT}}/$(printf '%s' "$SUBJECT" | sed 's/[&/\]/\\&/g')/g" "$DIR/prompts/codex-9x-website.md" \ | awk '/^```/{f++;next} f==1')" echo "── codex \$imagegen → 9 mockups for: $SUBJECT" echo "── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)" cd "$DIR" codex exec --dangerously-bypass-approvals-and-sandbox "$PROMPT" ``` 4. Create the agy run script (note it raises `--print-timeout` to 15m — the 5m default is too short for 9 images). ``` text #!/bin/bash # Fire agy (Google Antigravity CLI): 9 wildly different mobile mockups for one subject. # Usage: ./scripts/run-agy-mockups.sh "a mobile app for selling houses" set -euo pipefail SUBJECT="${1:?usage: $0 \"\"}" DIR="$(cd "$(dirname "$0")/.." && pwd)" mkdir -p "$DIR/mockups" # Extract the first fenced block from the prompt file, substitute the subject. PROMPT="$(sed "s/{{SUBJECT}}/$(printf '%s' "$SUBJECT" | sed 's/[&/\]/\\&/g')/g" "$DIR/prompts/agy-9x-mobile.md" \ | awk '/^```/{f++;next} f==1')" echo "── agy generate_image → 9 mobile mockups for: $SUBJECT" echo "── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)" cd "$DIR" agy -p "$PROMPT" --dangerously-skip-permissions --print-timeout 15m ``` 5. Create the contact-sheet gallery. It polls every 5 seconds, so tiles fill in live while the run generates. ``` text 9x Mockup Contact Sheet

9x Wildly Different Mockups

same subject · nine styles · auto-refreshes every 5s while generating
``` 6. Make the scripts executable and fire a run (background it — 9 images take a few minutes): ``` text chmod +x scripts/run-codex-mockups.sh scripts/run-agy-mockups.sh ./scripts/run-codex-mockups.sh "a landing page for an indie coffee roaster" # or, for mobile: ./scripts/run-agy-mockups.sh "a mobile app for selling houses" ``` **Success check:** nine numbered PNGs exist and the gallery shows nine tiles — same subject, nine styles. ``` text ls mockups/mockup-0*.png open mockups/index.html # macOS; use xdg-open on Linux ``` ``` text mockups/mockup-01.png mockups/mockup-02.png mockups/mockup-03.png mockups/mockup-04.png mockups/mockup-05.png mockups/mockup-06.png mockups/mockup-07.png mockups/mockup-08.png mockups/mockup-09.png ``` ## Attachments — install the page skill This is the exact `here-now-workshop-page` skill — with the Elo-voted Instrument Panel theme — that built every page in this workshop, published on this site byte-for-byte (SKILL.md plus its four `templates/` files). Download all five, then `npx skills` copies the whole folder into your project's `.agents/skills/`, `templates/` included. Two tested gotchas are baked in: `.md` URLs on here.now serve an HTML viewer, so the two markdown files must be fetched with `?raw`; and the download is staged in `./page-skill/`, not `./skills/` — the installer treats an existing `./skills/` as an agent's project skill dir and will clobber your download with a symlink. ``` text mkdir -p page-skill/here-now-workshop-page/templates curl -fsSL -o page-skill/here-now-workshop-page/SKILL.md "https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/SKILL.md?raw" curl -fsSL -o page-skill/here-now-workshop-page/templates/agent.md "https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/agent.md?raw" curl -fsSL -o page-skill/here-now-workshop-page/templates/index.html "https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/index.html" curl -fsSL -o page-skill/here-now-workshop-page/templates/styles.css "https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/styles.css" curl -fsSL -o page-skill/here-now-workshop-page/templates/app.js "https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/app.js" npx skills add ./page-skill --skill here-now-workshop-page -y ``` ## Complete reusable setup contract ## Variations: 9x Mockups from One Prompt — agent setup guide Following this file sets up: a 9x design-mockup generator in the user's current project — two prompt files, two run scripts, and a live-updating contact-sheet gallery. One command then generates nine wildly different mockups (same subject, nine styles) into `mockups/`. Placeholders used below: `` = the project you are working in. All other paths are literal and relative to ``. ## Prerequisites Check each before starting: ```bash command -v codex && codex --version command -v agy && agy --version ``` Expected: at least ONE of the two prints a version. `codex` (OpenAI Codex CLI) drives the website-mockup script; `agy` (Google Antigravity CLI) drives the mobile-mockup script. If both are missing, stop and tell your user what to install. Also confirm you are in `` and it is writable. ## Steps 1. Create `prompts/codex-9x-website.md` with exactly this content (the run script extracts the first fenced block and substitutes the subject): ````markdown # Codex prompt — 9x wildly different website mockups Replace `{{SUBJECT}}` with the site you're designing (keep it constant across all 9!). ``` Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for {{SUBJECT}}. Rules: - The SUBJECT stays identical in all 9 — same product, same page type (homepage), same rough content (hero, nav, one CTA). ONLY the visual style varies. This is what makes them comparable. - Pick 9 maximally divergent directions, e.g.: swiss/international typographic, neo-brutalist, glassmorphic dark, editorial magazine, retro terminal, playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine. Name each direction before generating. - One built-in image_gen call per mockup (do NOT drop to the CLI fallback). - Desktop aspect, full homepage visible, legible headline text. - After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction order you announced). - Announce progress after each one — never go silent. - When all 9 exist, list the 9 directions next to their filenames. ``` ## Follow-up (converge on a winner) ``` mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds. ``` ```` 2. Create `prompts/agy-9x-mobile.md` with exactly this content: ````markdown # agy (Antigravity) prompt — 9x wildly different mobile mockups Replace `{{SUBJECT}}` with the app you're designing. Historical workshop subject: "a mobile app for selling houses". ``` Generate 9 WILDLY different mobile app UI mockups for {{SUBJECT}} using your generate_image tool. Rules: - SUBJECT is constant across all 9 — same app, same home screen (listing feed, search, one primary action). ONLY the visual style varies. - 9 divergent directions, e.g.: iOS glass minimal, material-you expressive, neo-brutalist, dark luxury, pastel neumorphic, retro pixel, editorial serif, cyberpunk neon, paper-collage tactile. Name each before generating. - One generate_image call per mockup with ImageName mockup_01 ... mockup_09. - Phone aspect ratio (9:19-ish), single screen per image. - After each generation, use run_command to copy the artifact into ./mockups/ as mockup-01.png ... mockup-09.png. - If you hit an image quota error, report it immediately with the reset time instead of retrying silently. - Announce progress after each image. ``` ## Scripted status contract (from the inspiration-board pipeline) When driving agy from bash at scale, demand machine-readable status: ``` Respond with ONLY a JSON object (no markdown, no explanation): - Success: {"status":"ok","path":""} - Quota error: {"status":"quota_exhausted","reset_seconds":,"reset_time":""} - Other error: {"status":"error","message":""} ``` This is the exact contract `generate.sh` in the inspiration-board pipeline uses to loop over 200 styles unattended, with a skip-if-exists guard (file > 100KB). ```` 3. Create `scripts/run-codex-mockups.sh` with exactly this content: ```bash #!/bin/bash # Fire Codex $imagegen: 9 wildly different website mockups for one subject. # Usage: ./scripts/run-codex-mockups.sh "a landing page for an indie coffee roaster" set -euo pipefail SUBJECT="${1:?usage: $0 \"\"}" DIR="$(cd "$(dirname "$0")/.." && pwd)" mkdir -p "$DIR/mockups" # Extract the first fenced block from the prompt file, substitute the subject. PROMPT="$(sed "s/{{SUBJECT}}/$(printf '%s' "$SUBJECT" | sed 's/[&/\]/\\&/g')/g" "$DIR/prompts/codex-9x-website.md" \ | awk '/^```/{f++;next} f==1')" echo "── codex \$imagegen → 9 mockups for: $SUBJECT" echo "── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)" cd "$DIR" codex exec --dangerously-bypass-approvals-and-sandbox "$PROMPT" ``` 4. Create `scripts/run-agy-mockups.sh` with exactly this content: ```bash #!/bin/bash # Fire agy (Google Antigravity CLI): 9 wildly different mobile mockups for one subject. # Usage: ./scripts/run-agy-mockups.sh "a mobile app for selling houses" set -euo pipefail SUBJECT="${1:?usage: $0 \"\"}" DIR="$(cd "$(dirname "$0")/.." && pwd)" mkdir -p "$DIR/mockups" # Extract the first fenced block from the prompt file, substitute the subject. PROMPT="$(sed "s/{{SUBJECT}}/$(printf '%s' "$SUBJECT" | sed 's/[&/\]/\\&/g')/g" "$DIR/prompts/agy-9x-mobile.md" \ | awk '/^```/{f++;next} f==1')" echo "── agy generate_image → 9 mobile mockups for: $SUBJECT" echo "── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)" cd "$DIR" agy -p "$PROMPT" --dangerously-skip-permissions --print-timeout 15m ``` 5. Create `mockups/index.html` with exactly this content (it polls every 5 seconds so tiles fill in live during generation): ```html 9x Mockup Contact Sheet

9x Wildly Different Mockups

same subject · nine styles · auto-refreshes every 5s while generating
``` 6. Make the scripts executable: ```bash chmod +x scripts/run-codex-mockups.sh scripts/run-agy-mockups.sh ``` 7. Ask your user for a subject if they haven't given one (one sentence, naming the page type and its content — the subject must stay constant across all 9 mockups). **Warning — confirm before firing:** both scripts launch a paid external agent with sandboxing and approval prompts disabled (`--dangerously-bypass-approvals-and-sandbox` for codex, `--dangerously-skip-permissions` for agy). Show your user the command and make sure they are comfortable with the cost and permissions before running. Then fire a run. Prefer running it in the background and narrating progress; a full run takes several minutes. ```bash # website mockups via Codex: ./scripts/run-codex-mockups.sh "a landing page for an indie coffee roaster" # OR mobile mockups via agy: ./scripts/run-agy-mockups.sh "a mobile app for selling houses" ``` ## Success check Run: ```bash ls mockups/mockup-0*.png open mockups/index.html # macOS; use xdg-open on Linux ``` Expected observable result: nine files, `mockups/mockup-01.png` through `mockups/mockup-09.png`, and the gallery page shows nine filled tiles — the same subject rendered in nine different visual styles. Report to your user: the subject used, the nine style directions the generating agent announced, the success-check output, and anything you had to adapt. ## Notes for agents - **Codex saves images to the wrong place by default.** Built-in `image_gen` output lands under `$CODEX_HOME/generated_images/`. The prompt explicitly orders a copy into `./mockups/` — if tiles stay empty but the run "succeeded", look there and copy manually. - **agy's `--print-timeout` defaults to 5 minutes** — too short for 9 images. The run script already passes `--print-timeout 15m`; keep it if you modify the script. - **Quota errors are real on agy.** If a run reports `quota_exhausted`, report the reset time to your user instead of retrying silently. For scripted loops, demand the JSON status contract shown at the bottom of `prompts/agy-9x-mobile.md`. - **Never go silent.** A prior run stalled without output and the user had to ask "hello? What is happening?" — narrate progress after each image, or background the run and poll. - **Subject drift ruins comparability.** If a mockup comes back as a different page type, regenerate that one; do not compare it. - **Converge afterwards.** When the user picks a winner, rebuild it with: "mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds." ## Attachment: the here-now-workshop-page skill (multi-file) The skill that built this page — SKILL.md plus its `templates/` folder, carrying the Elo-voted Instrument Panel theme — is published on this site byte-for-byte. Gotcha: bare `.md` URLs serve here.now's HTML viewer; the two markdown files MUST be fetched with `?raw` (the .html/.css/.js files serve raw bytes as-is): - https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/SKILL.md?raw - https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/agent.md?raw - https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/index.html - https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/styles.css - https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/app.js To install it in a project: download all five into `./page-skill/here-now-workshop-page/` (keeping the `templates/` subfolder), then run `npx skills add ./page-skill --skill here-now-workshop-page -y` — it copies the whole folder, templates included, into `./.agents/skills/here-now-workshop-page/`. Do NOT stage the download in `./skills/` — the installer treats an existing `./skills/` as an agent's project skill dir and overwrites the staged folder with a symlink, leaving an empty install (verified empirically). The exact command block is on the guide page under "Attachments — install the page skill". --- Human-readable version of this guide: https://indigo-kayak-2zw8.here.now/ Presentation companions (for humans; no setup steps beyond this file): - https://indigo-kayak-2zw8.here.now/replay.html — Session Replay: an annotated transcript of the real sessions behind this workflow (diverge → pick with eyes → converge). - https://indigo-kayak-2zw8.here.now/dialogue.html — Socratic Dialogue: skeptical Q&A that lands the same prompts where each question demands them. Reference ID: factory-design-variations-practice Topic: Planning Sources: - [Generate to diverge, code to converge](https://indigo-kayak-2zw8.here.now/) - [Public setup contract](https://indigo-kayak-2zw8.here.now/agent.md) --- # Generate to diverge, code to converge — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The room asks Why generate images at all? Your agent can write nine real HTML pages. It can — at roughly an hour a draft, which is why you normally see three directions before you commit. A bitmap mockup costs about a minute, so nine directions becomes the cheap default, and you can't prefer an option you never saw. Images are for deciding; code is for shipping. Generate to diverge, code to converge. Here's the whole first taste, one paste — fair warning: it launches Codex, a paid agent, with sandboxing and approvals off, so read it and be comfortable with the cost and permissions before you run it: ``` text mkdir -p mockups codex exec --dangerously-bypass-approvals-and-sandbox 'Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for a landing page for an indie coffee roaster. The subject stays identical in all 9 - ONLY the visual style varies. One built-in image_gen call per mockup. After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png. Announce progress after each one.' ls mockups/ ``` Won't “nine wildly different mockups” just give me nine incomparable posters? Only if you let the subject drift. The prompt pins the subject — same product, same page type, same rough content — and varies nothing but the style. That turns nine images into a controlled experiment you can read at a glance. This is the exact prompt, verbatim (the agy mobile version is on the [guide](https://indigo-kayak-2zw8.here.now/)): ``` text Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for {{SUBJECT}}. Rules: - The SUBJECT stays identical in all 9 — same product, same page type (homepage), same rough content (hero, nav, one CTA). ONLY the visual style varies. This is what makes them comparable. - Pick 9 maximally divergent directions, e.g.: swiss/international typographic, neo-brutalist, glassmorphic dark, editorial magazine, retro terminal, playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine. Name each direction before generating. - One built-in image_gen call per mockup (do NOT drop to the CLI fallback). - Desktop aspect, full homepage visible, legible headline text. - After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction order you announced). - Announce progress after each one — never go silent. - When all 9 exist, list the 9 directions next to their filenames. ``` And if one mockup comes back as a different page type anyway: regenerate it. Don't compare it. I ran it. The run “succeeded” and my `mockups/` folder is empty. So the model lied? No — it saved your images, just not where you looked. Codex's built-in `image_gen` writes to `$CODEX_HOME/generated_images/` by default, which is why the prompt explicitly orders a copy into `./mockups/`. The other classic: agy's `--print-timeout` defaults to five minutes, and nine images take longer — the run script raises it to fifteen. An empty contact sheet means read the run log before blaming the model. Nine tiles and no rubric. How do I “pick with my eyes” honestly? Open the contact-sheet gallery — it polls every five seconds, so tiles fill in live while the run generates — and pick the tile you would be embarrassed to lose. If nothing clears that bar, your styles weren't divergent enough: widen the directions and rerun. Never polish the least-bad option. Fine, I picked one. It's a PNG. What do I actually ship? You hand the winner back to a coding agent as a reference image. The bitmap decided; the code converges: ``` text mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds. ``` Real text, real layout, no bitmap backgrounds — the image is strictly a visual reference. Cute demo. Does it survive contact with 200 images? That's exactly what [inspiration-board](https://inspiration-board.pages.dev/variations/01-masonry-grid) is: a bash loop driving the Antigravity CLI across 200 named web-design styles. Scale is mostly error handling — fixed output filenames, a skip-if-exists guard (file already on disk above 100 KB), and machine-readable status demanded from every single run: ``` text Respond with ONLY a JSON object (no markdown, no explanation): - Success: {"status":"ok","path":""} - Quota error: {"status":"quota_exhausted","reset_seconds":,"reset_time":""} - Other error: {"status":"error","message":""} ``` Quota errors are real; a JSON reset time beats a silent retry. And the variations idea applies twice there: the images are style variations, and the gallery pages themselves are twelve layout variations of the same image set. Do you actually trust this loop for anything real, or is it a workshop trick? The page you're reading is the proof. Its theme was picked by this exact loop: wildly different theme candidates rendered over this section's real content, three rounds of Elo voting, 130 recorded votes — and the winner, Instrument Panel, undefeated in both light and dark, became the template for every site in this workshop. The annotated transcript is on the [Session Replay](https://indigo-kayak-2zw8.here.now/replay.html) page. And you can take the winner home: the resulting `here-now-workshop-page` skill is [downloadable and installable from the guide](https://indigo-kayak-2zw8.here.now/#attachments-install-the-page-skill). Reference ID: factory-design-variations-questions Topic: Planning Sources: - [Generate to diverge, code to converge — questions and tradeoffs](https://indigo-kayak-2zw8.here.now/dialogue.html) --- # Generate to diverge, code to converge — reference patterns Extended explanations, comparisons, experiments, and practical actions for the same operating pattern. ## Abstract Early design work stalls on the cost of producing options, not on taste. Coding agents that carry an image-generation tool collapse that cost: one prompt can return nine divergent website or mobile mockups in minutes. The results only stay comparable when the subject is held constant and only the visual style varies. With a strict machine-readable status contract, the same pattern runs unattended at two-hundred-style scale, as a deployed gallery project demonstrates. The evidence here covers workflow mechanics from tool contracts, CLI output, pipeline scripts, and prior session records. It does not measure whether any generated direction is aesthetically better — that judgment stays with you. ## Notice where design exploration stalls You sit down to design a landing page. The usual move is to build one draft and iterate on it. Each iteration costs an hour or more, so you see perhaps three directions before you commit. The mistake is treating that scarcity as a taste problem. It is a production problem: you cannot prefer an option you never saw. The workshop agenda names image generation as a shared capability of current coding agents and treats prototypes as a compounding asset: the more you build, the deeper the well of examples you can pull from (S1). [1](https://indigo-kayak-2zw8.here.now/#note-1) 1\. The same agenda lists Codex, Grok, and Antigravity as agents that "can all generate images" — this section is where that thread gets demonstrated (S1). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-1) Prior sessions on this machine show the pattern working in practice: one run produced five bitmap mockup directions for a storefront, collected them into a gallery page, and finished within a single sitting (S5). From those records, this folio draws its central inference: when a mockup costs a minute instead of an hour, exploring nine directions becomes the cheap default rather than a luxury. The signal to watch in your own work: if you are polishing draft one before you have seen draft five, you are iterating too early. Diverge first. ## Test one prompt against nine mockups Two CLIs run this demo. Codex ships an imagegen skill — a packaged instruction set that routes image requests through its built-in `image_gen` tool. The Antigravity CLI (`agy`) exposes a `generate_image` tool the same way. Try both with the same shape of prompt: ``` text # Codex: 9 wildly different website mockups ./scripts/run-codex-mockups.sh "a landing page for an indie coffee roaster" # agy: 9 wildly different mobile mockups ./scripts/run-agy-mockups.sh "a mobile app for selling houses" ``` Both scripts expand a prompt that names nine divergent style directions, asks for one image call per mockup, and requires the agent to copy each result into `mockups/` as `mockup-01.png` through `mockup-09.png`. A contact-sheet page in the same folder polls for the files and fills a three-by-three grid as they land. The imagegen skill contract lists UI mockups, product mockups, and wireframes as intended uses, prefers the built-in tool over its API fallback, and states that a batch request means one built-in call per asset — not a switch to the CLI path (S2). [2](https://indigo-kayak-2zw8.here.now/#note-2) 2\. The fallback path exists but is gated: it requires an API key and an explicit user request. For this workflow you never need it (S2). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-2) | Concern | Codex `$imagegen` | agy (Antigravity) | |----|----|----| | Non-interactive run | `codex exec ""` | `agy -p ""` | | Image tool | built-in `image_gen` | `generate_image` (ImageName, Prompt, ImagePaths) | | Default output location | `$CODEX_HOME/generated_images/` | agent workspace artifact; copy via `run_command` | | Batch rule | one built-in call per asset (S2) | one `generate_image` call per mockup (S4) | | Timeout to watch | none specific to images | `--print-timeout`, default 5 minutes (S3) | Table 1. The two CLI surfaces, side by side. Derived display: reorganized from the imagegen skill contract (S2), `agy --help` output (S3), and pipeline scripts (S4). Codex saves built-in image output under its own home directory by default, and the skill contract forbids leaving a project-referenced asset there (S2). **Evidence limit** If your prompt does not say "copy each image into `./mockups/`", the run can succeed while your project folder stays empty. The same trap applies to agy's five-minute default print timeout: nine images take longer, so the demo script raises it to fifteen minutes. Watch for an empty contact sheet as the failure signal. The test is simple: fire a script, open `mockups/index.html`, and count. Nine tiles filled means the contract held. Fewer means read the run log before blaming the model. ## Compare fairly: hold the subject constant Nine images are only useful if you can compare them. The likely mistake is letting the subject drift with the style — a coffee site in one tile, a coffee app in the next. Then differences in appeal tell you nothing about the style, because two variables changed at once. The gallery pipeline enforces this discipline explicitly: a shared subject file defines one fixed cast of seven characters plus a prompt suffix appended to every style prompt, "so you can compare how each visual approach handles" the same material (S4). A prior session applied the same rule to product work: mock up one constant subject — a mobile app for selling houses — once per visual style, varying nothing else (S5). [3](https://indigo-kayak-2zw8.here.now/#note-3) 3\. That session's record also captures a stronger prompt pattern: each style prompt opens with "STYLE IS PARAMOUNT" and demands the image be instantly recognizable as that style (S4). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-3) Weak judgment says "make nine cool designs." Strong judgment says "same homepage, same hero, same call to action — nine styles." The first gives you nine incomparable posters. The second gives you a controlled experiment you can read at a glance. Practice it now: before you run the script, write your subject as one sentence and check that it names the page type and its content. If any mockup back changes the page type, regenerate that one — do not compare it. ## Adjust the trick into an unattended pipeline Nine mockups is a live demo. Two hundred is a pipeline, and the difference is error handling. The inspiration-board project — the deployed gallery this workshop shows off — generates its images by driving the Antigravity CLI from a bash loop, one style at a time. Its generator script demands a machine-readable status from every run: plain JSON, no markdown, one of three shapes (S4). ``` text // Success {"status": "ok", "path": ""} // Quota exhausted {"status": "quota_exhausted", "reset_seconds": 3600, "reset_time": ""} // Anything else {"status": "error", "message": ""} ``` The same script controls filenames by passing a fixed image name per style, copies each artifact to a predictable path, and skips any output that already exists above a size threshold, so interrupted runs resume instead of restarting (S4). [4](https://indigo-kayak-2zw8.here.now/#note-4) 4\. The skip guard is one line: if the file exists and exceeds 100 KB, print SKIP and return. Cheap idempotence is what lets a quota-limited loop run for days (S4). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-4) The instruction suffix also closes escape hatches: on quota errors the agent must return JSON immediately, and it may not reach for scripts, external APIs, downloads, or any workaround (S4). Scale evidence: the web-design category alone carries 200 named styles with full prompts in its styles file and roughly as many generated images beside it, with sibling categories for app design, branding, editorial, and more (S4). A prior batch run stalled silently mid-generation, and the operator had to ping the session to ask what was happening; the recorded lesson was to run each image as its own background job and to narrate progress (S5). **Evidence limit** The quota-handling and skip-guard evidence comes from one project's scripts driving one CLI. The sources do not establish that other agents fail the same way, or how often quota errors occur — only how this pipeline survives them. When your own loop grows past a handful of images, adjust in this order: fixed output names first, skip-if-exists second, JSON status third, background jobs with progress lines fourth. Each step has a visible test — rerun the loop and watch it skip, resume, or report instead of stalling. ## Choose a winner and converge to real code The mockups are bitmaps. They are for deciding, not shipping. The loop closes when you pick one tile and hand it back to a coding agent as a reference image. A prior session shows the full arc: five generated mockup directions went into a gallery page, one winner was selected, and that winner was rebuilt "as actual HTML/CSS instead of an image-backed" page (S5). The follow-up prompt is one sentence: "Rebuild `mockup-07.png` as a real single-file HTML/CSS page, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds." Generate to diverge; code to converge. The variations idea applies twice in the inspiration-board project. The images are style variations, and the gallery pages themselves are twelve layout variations rendering the same image set (S4). [5](https://indigo-kayak-2zw8.here.now/#note-5) 5\. The masonry page even hardcodes its own public URL as a prompt base, so a visitor can copy any style straight into their own agent session (S4). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-5) - 01 masonry grid - 02 infinite scroll - 03 carousel slider - 04 lightbox thumbnails - 05 compare split - 06 magazine editorial - 07 filmstrip preview - 08 table list - 09 mood board - 10 fullscreen slideshow - 11 grouped categories - 12 search-first **Figure 1.** The twelve gallery layout variations shipped by the inspiration-board project. Derived display: transcribed from the project's variations directory listing (S4); the live masonry page at inspiration-board.pages.dev returned HTTP 200 when checked in the observed snapshot. Your decision rule: pick the tile you would be embarrassed to lose. If no tile clears that bar, the styles were not divergent enough — widen the directions and rerun, rather than polishing the least-bad option. ## Practical action Next time a design has no direction, run this sequence in the demo project. Write one constant-subject sentence. Fire `run-codex-mockups.sh` for the website and `run-agy-mockups.sh` for mobile, each in its own pane. Open the contact sheet and wait for nine tiles per run. Success signal: filenames `mockup-01.png` through `mockup-09.png` exist and every tile shows the same subject in a different style. If a run stalls, check the agent's log for a quota status and its reset time before retrying. Then choose one winner and issue the converge prompt to rebuild it as real HTML/CSS. If nothing wins, widen the style directions and regenerate — do not iterate on a weak favorite. Reference ID: factory-design-variations-reference-patterns Topic: Planning Sources: - [Prepared module reference](https://indigo-kayak-2zw8.here.now/) --- # Generate to diverge, code to converge — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## Act 1 — Diverge: ten styles, one subject You Give me 10 current popular web design styles. Agent Returned ten named style directions — the menu for the batch run. You can't have taste about options you never saw. Naming the directions first is what makes the batch comparable later. You For each of these styles: Use \$imagegen to mock up a mobile app for selling houses in a background thread. Agent Fired the generations as background jobs. The built-in `image_gen` tool saved every result under `$CODEX_HOME/generated_images/` — not the project — so each finished image had to be copied into the workspace. Two rules are already visible: the subject stays constant (a mobile app for selling houses — only the style varies), and the default save path is a trap the prompt has to handle. You hello? What is happening? Agent The batch had gone silent mid-run. It was still generating — but nothing said so. The session summary recorded the fix as an explicit preference: run each image generation as its own background job, and announce progress after every image. That ping is why every prompt on this page now ends with "Announce progress after each one — never go silent." ## Act 2 — Pick with your eyes, converge as code You Use the \$imagegen skill, passing the `./refs/*` files as references so output is guided by the actual styles. Agent Generated five bitmap mockup directions, copied them into `mockups/`, and built a gallery `index.html` that opened them side by side — a contact sheet. The contact sheet is the decision instrument. This project's version polls every 5 seconds, so tiles fill in live while the run is still generating. You mock-03 is the winner. Rebuild it as actual HTML/CSS instead of an image-backed page. Agent Built the winner as a real page — real text, real layout, no bitmap backgrounds. Diverge, pick, converge: the full loop, one session. Image generation explores; code generation commits. Neither replaces the other. ## Act 3 — The same loop chose this page's theme The candidates don't have to be images. A later session pointed the exact same workflow at this page's own design — wildly different page themes as the variations, Elo votes as the eyes. The lab lives in this project (`template-lab/`, votes in `votes*.jsonl`, outcome in `RESULTS.md`). Agent Stood up a local template lab: 8 wildly different themes rendered over this section's real content, paired into duels you arrow-key through, every vote appended to a JSONL file. Round 2 widened it to 12 themes (top 3 survivors + 9 new directions) under Elo pairing — 88 votes across two sessions: ``` text Round 2 final standings (Elo, session 1 / session 2) 1 V09 Gallery (Luxe × Brutalist) 1115 / 1047 2 V13 Functionalist (Rams/Braun) 1055 / 1063 3 V06 Luxe Minimal 1035 / 1000 … 12 V16 Riso Print 880 / 936 Head-to-head: Gallery over Functionalist, 4–2 → Gallery shipped ``` Same discipline as the mockups: subject held constant (the real page content), only the style varies, and the picking is done with eyes — one duel at a time. You These are all WAAAAY too similar. A refinement round had produced near-clones of the winner. Verdict recorded in the lab's RESULTS.md — near-clones can't be voted on, exactly the way nine same-ish posters can't be compared. Agent Rebuilt the round from scratch: 12 structurally distinct dialects on an oklch token system with variable system fonts, duels alternating light and dark, win-loss tracked per mode. 30 votes later: ``` text Round 3b standings (30 votes, light/dark alternating) 1 N02 Instrument Panel 1063 light 2-0 dark 2-0 2 N08 Type Specimen 1048 light 0-1 dark 4-0 3 N10 Chip Bar 1017 light 3-0 dark 0-2 4 N00 Gallery (shipped) 1016 light 3-1 dark 0-1 ``` Instrument Panel — the only theme undefeated in both modes — became the canonical template for every site in this workshop. The page you are reading is wearing the winner. ## The artifact those sessions distilled Every lesson above, folded into one liftable prompt. Replace `{{SUBJECT}}` and keep it constant across all nine — "announce progress" traces to the silent stall, the copy-out-of-`$CODEX_HOME` rule traces to the empty project folder, and "WILDLY different" traces to the too-similar round that broke the vote. ``` text Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for {{SUBJECT}}. Rules: - The SUBJECT stays identical in all 9 — same product, same page type (homepage), same rough content (hero, nav, one CTA). ONLY the visual style varies. This is what makes them comparable. - Pick 9 maximally divergent directions, e.g.: swiss/international typographic, neo-brutalist, glassmorphic dark, editorial magazine, retro terminal, playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine. Name each direction before generating. - One built-in image_gen call per mockup (do NOT drop to the CLI fallback). - Desktop aspect, full homepage visible, legible headline text. - After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction order you announced). - Announce progress after each one — never go silent. - When all 9 exist, list the 9 directions next to their filenames. ``` When your eyes have picked, converge: ``` text mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds. ``` The full setup — both run scripts, the agy mobile version, and the live-updating contact-sheet gallery — is on the [guide](https://indigo-kayak-2zw8.here.now/), mirrored for machines in [agent.md](https://indigo-kayak-2zw8.here.now/agent.md). The winning theme itself ships too: the `here-now-workshop-page` skill that built this page is [downloadable and installable from the guide](https://indigo-kayak-2zw8.here.now/#attachments-install-the-page-skill). Reference ID: factory-design-variations-worked-example Topic: Planning Sources: - [Generate to diverge, code to converge — worked example](https://indigo-kayak-2zw8.here.now/replay.html) --- # Keep notes private and goals verifiable Agent-heavy work creates a lot of half-formed context: dictated notes, failed prompts, benchmark ideas, security worries, skill candidates, and "try this later" scraps. Do not commit that pile. Keep scratch private, ignored, and temporary until it **earns its way into a goal**. ```text private scratch note -> reviewed goal packet -> bounded agent work -> proof scenario -> saved evidence -> next goal ``` ## The Move Use a project-local scratch space for messy notes and a **reviewed goal packet** for actual work. Local conventions such as `.notes/` and `.goals/` can work well when they are globally ignored and treated as private workspace files. The names are not important. The boundary is. > Notes is just kind of like the junk, or the research, or whatever. Goals are the things I can feed into the model to produce work. > > — John Lindquist - Scratch notes are not documentation. - Goals are not wish lists. - A note is where messy thinking lands. - A goal is what survives review and becomes work. ## Notes Become Goals A goal packet is a reviewed project-local work item that turns scratch notes into bounded agent work, names the proof scenario, and records what counts as done. Example: ```text Scratch note: Checkout submit stayed disabled after selecting shipping. Goal: Find the smallest cause of the disabled checkout submit state. Likely areas: - checkout form state - shipping selection reducer - submit button disabled logic Proof: - reproduce failing state - add or run component test - run checkout smoke test - capture before/after result Stop if: - payment-provider adapter must change - no reproducible failing state exists ``` Private notes stay private. Sanitized patterns can become docs later. ## Long Agent Work Needs Intervals Treat long agent runs as **interval work**. Set an explicit check-in interval before launch. Leave the agent with a stop rule and proof requirement. Step away. Come back to inspect evidence, not vibes. Field rule: ```text If the agent has a bounded goal and a proof command, step away until the interval ends. Watching the terminal harder does not make the benchmark finish. ``` Good launch shape: ```text Start a migration lane with: - allowed files - files to avoid - verification command - check-in interval - stop condition Return when: - the timer fires - the agent reports blocked - the proof command finishes - a boundary conflict appears ``` **AFK does not mean unsupervised merge.** It means the work unit is bounded enough that the human can leave and return to concrete evidence. ## Understanding Becomes Proof Design You still need judgment. What changes is the unit of understanding. > The best you can hope for is understanding the scenarios that prove the code works the way you expect it to. > > — John Lindquist The useful unit is no longer "I have read every line." The useful unit is "I know the scenario, the boundary, and the evidence that prove this behavior." Examples: | Task | Proof Scenario | Evidence | Does Not Prove | |---|---|---|---| | Checkout disabled state | Shipping selected, submit enables | Component test, smoke test | Every payment-provider state | | Billing retry | Duplicate event processed once | Fixture, idempotency test, log | All provider outage modes | | Auth/session rotation | Stale session rejected safely | Security test, route check | Every browser/session store | | Performance change | Same fixture before/after | Benchmark output | Production latency | **Proof scenarios are how codebase understanding stays grounded** when code is moving quickly. ## Ask For Lists, Not Comfort Avoid vague reassurance prompts: ```text Are you sure? Is this correct? Why did this work? ``` Ask for structured reasons instead: ```text Do not reassure me. List 5 reasons this proof actually covers the checkout disabled-state bug. For each reason, include: - the behavior it checks - the evidence source - what it does not prove - one way this could still be wrong ``` More useful prompts: ```text List 5 ways this benchmark could be misleading. ``` ```text List 7 security assumptions this auth/session change depends on. ``` ```text List 4 reasons the smoke test covers the regression, then list 4 gaps it leaves open. ``` Agents are good at sounding certain. **Lists force certainty to expose its assumptions.** ## Treat Public Skills As Candidates Public skills are **supply-chain inputs**. Evaluate before installing. For a software task, search with multiple terms instead of one narrow phrase. Example task: ```text Improve accessibility checks for a Svelte checkout flow. ``` Search terms: ```text accessibility audit a11y test Svelte accessibility Playwright axe WCAG checker keyboard navigation screen reader smoke test ARIA validation form accessibility contrast checker ``` Then ask a model council or **[Oracle](https://github.com/johnlindquist/oracle)** to compare candidates: ```text Compare candidate skills for this task. For each candidate: - what it claims to do - source/repo/package origin - maintenance signals - install or execution risk - whether it reads project files - whether it runs code - what useful prompt or function can be extracted without installing - recommendation: install / adapt / reject ``` Reading a skill is not the same as trusting it. Installing it is a separate decision. ## Force Known Context If the relevant files, constraints, stack, or proof command are already known, put them directly in the prompt. **Search should fill unknowns, not rediscover known facts.** Weak: ```text Find the right skill and fix checkout. ``` Better: ```text We use SvelteKit. The failing path is /checkout. The bug is submit disabled after shipping selection. Do not touch the payment provider adapter. The proof is the checkout component test plus billing smoke test. Search for skills only if they help inspect this exact scenario. ``` ## Copyable Artifact: Goal Packet ```text Scratch source: - note id or summary: - why this matters now: Goal: - what should be true when this is done: Known context: - repo area: - likely files: - constraints: - files/tools to avoid: Agent work: - first inspection step: - allowed edits: - stop conditions: Proof scenario: - user path or system behavior: - test: - smoke check: - benchmark: - security check: - debug/log evidence: Reason list required: Ask the agent to list: - 5 reasons this proof covers the goal - 5 gaps this proof leaves open - 3 assumptions that could make the result wrong Pacing: - check-in interval: - what to inspect when returning: Skill evaluation, if needed: - 10 search terms: - candidate skills: - Oracle/Fusion comparison saved? - source scraped/read before install? - useful parts extracted? - install decision: install / adapt / reject Completion: - evidence attached: - remaining uncertainty: - next goal created: ``` ## Claim Boundaries Do not share private note contents, global ignore files, local config, machine paths, usernames, or private skill contents. Do not claim a model council can guarantee supply-chain safety. It can compare candidates and surface risk. The install decision still belongs to the human and the repo owner. Do not claim developers no longer need to understand code. The narrower claim is stronger: understanding should be grounded in proof scenarios. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#goals) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-goals Topic: Planning Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#goals) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Prompt Builder composition and handoff: practical reference ## Agent Setup Prompt ```text Set up Prompt Builder and its zsh helper wiring on this machine. Do setup and verification only; do not modify Prompt Builder source, create new skills, or launch Codex prompts. Step 1: Locate or install Prompt Builder. If a local checkout of https://github.com/johnlindquist/prompt-builder exists, inspect `README.md`, `src/cli.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, and `src/app_server_launch.rs`, then install from that checkout: cargo install --path . --locked --force If no checkout exists, clone it first. If `cargo` is missing, stop and report that blocker. Step 2: Verify `prompt-builder` and `p` identity. Run: which -a prompt-builder p prompt-builder --version p --version Confirm both commands resolve to the intended install location and report the same version. `p` must be a real executable or symlink, not only an interactive shell alias. If `prompt-builder` exists but `p` is missing, run: ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p hash -r 2>/dev/null || true; rehash 2>/dev/null || true Then repeat the identity and version checks. Step 3: Verify print, dry-run, and launch inspection modes. Run: p --print-prompt "Review checkout saved payment method regressions." p --dry-run --print-command "Review the failing billing webhook test and identify the smallest patch." p --print-launch-json "Review auth/session architecture." | jq '.mode, .command, .argv, .env, .prompt' p --submit --dry-run --print-command "Verify submit dry-run." Confirm the prompt is preserved, the command preview is sane, `argv` is structured, and no accidental shell splitting appears. Step 4: Verify app-server named threads and `CODEX_THREAD_NAME`. Run: p --print-launch-json --name "Auth rotation review" "Review auth/session architecture." | jq '.mode, .env, .app_server' Confirm `mode` is `app-server-named-thread`, `env` includes `CODEX_THREAD_NAME` with the current directory basename plus the requested name, and the app-server flow includes `thread/name/set`. Step 5: Verify handoff mode and final argv safety. Run: p --print-launch-json --handoff-command /bin/echo "fix this keep \$HOME literal" | jq '.mode, .argv' Confirm `mode` is `handoff`, the composed prompt is the final `argv` element, and `$HOME`, spaces, quotes, semicolons, pipes, and newlines remain literal prompt text. Treat `Command::arg` behavior as the contract; do not add shell eval to wrappers. Step 6: Verify handoff options only in handoff mode. Run: p --print-launch-json \ --handoff-command /bin/echo \ --handoff-arg wrapper \ --fork-from last \ --compact \ --launch-option "trace=--trace-app-server" \ "continue from here" | jq '.handoff, .argv' Confirm the ordering is command, static handoff args, enabled toggle args, then final prompt. Step 7: Wire and verify zsh helpers. Inspect `zsh/conf.d/40-ai.zsh` and confirm it contains wiring for `p-f`, `p-c`, `p-cm`, `xfl`, `xfc`, `_p_handoff_zsh`, and `_codex_prompt_builder_fork`. Verify the loaded helper functions: zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc' Each helper should resolve as a function. Confirm the intended behavior: p-f composes in `p`, then forks from the selected or current source. p-c composes in `p`, then forks, compacts, and resumes. p-cm composes in `p`, then compact-forks from conversation `m`. xfl forks immediately with an already-obvious prompt. xfc forks, compacts, and resumes immediately. Use `zsh -lc` with explicit sourcing for handoffs to shell functions because a normal subprocess cannot directly run those functions. Step 8: Prove one helper handoff shape with a dry run. Run: p --submit --dry-run --print-command \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \ --handoff-arg xfc \ "continue from this compact fork" Confirm the prompt is still the final argv element before the fork runs. Step 9: Respect privacy boundaries. Do not print full `env`. Do not copy private shell config, full Codex config, secret helper files, API variables, cookies, tokens, private endpoints, or key-resolving startup output. Use narrow command output only. For safe binary override checks, prefer: PROMPT_BUILDER_CODEX_BIN=/bin/echo p --submit --dry-run --print-command "hello override" Step 10: Report results. Return a concise setup report with: - files inspected or changed - resolved paths for `prompt-builder` and `p` - matching version output - named-thread JSON evidence for `mode`, `CODEX_THREAD_NAME`, and `thread/name/set` - handoff JSON evidence that the prompt is the final argv element - zsh helper `whence -w` evidence - any skipped or failed step with the exact failing command and output ``` ## Big Idea Prompt Builder is the terminal prompt composer at . It opens a small TUI for composing, naming, inspecting, and handing a prompt to Codex or a wrapper command. Use it as the preflight step before a prompt launches Codex, a fork, a compact, or a wrapper command. ## Try This Now Preview one software prompt before launching it: `p --print-launch-json "Debug the checkout saved-payment regression and name the first verification command." | jq '.mode, .argv, .prompt'` Submit only after the final argv and prompt text match what you intend. The practical question is: ```text What exactly am I about to send, where will it run, and what launch shape will it use? ``` Use Prompt Builder when the prompt needs to be deliberate before the agent gets authority to work in a repo. ```text compose -> inspect -> name -> preview launch -> submit deliberately ``` ## Files To Inspect Local helper file: ```text zsh/conf.d/40-ai.zsh ``` Inside the Prompt Builder checkout: ```text README.md src/cli.rs src/app.rs src/composer_input.rs src/file_search.rs src/skill_popup.rs src/slash_commands.rs src/handoff.rs src/launch_manifest.rs src/app_server_launch.rs ``` Main commands: ```bash prompt-builder p ``` `p` is the short command. It should resolve to the same installed binary as `prompt-builder`. ## When To Reach For This Use Prompt Builder when: - a checkout-flow implementation prompt needs file references and constraints - a billing webhook fix should fork from the right Codex session - an auth/session architecture review needs a named thread - a failing test investigation needs pasted output plus a careful instruction - a wrapper needs the prompt as the final argument - you want to inspect the prompt, command, or launch JSON before launch - routing has selected the right session and you still need to compose the right prompt - a controlled-variation run needs one deliberate base prompt Skip it when the prompt is tiny and obvious: ```bash xfl "continue with the smallest safe patch" ``` Use it when you need time to compose: ```bash p-f p-c p-cm ``` ## How This Used To Work What you used to expect: ```text Typing directly into Codex or a fork command is enough if the idea is clear. ``` What the workflow gives you now: ```text Prompt Builder lets you compose first, inspect the exact prompt and launch shape, then submit once the request is specific enough to trust. ``` What you used to expect: ```text The latest Codex session is probably the right one. ``` What the workflow gives you now: ```text Routing chooses the session. Prompt Builder shapes the prompt before the fork, compact, or wrapper runs. ``` ## The Mental Model Prompt Builder sits between intent and execution. ```text human intent -> Prompt Builder composer -> exact prompt text -> optional name -> launch preview -> direct Codex / named thread / handoff wrapper ``` Three launch paths matter: | Mode | What Happens | Use When | | --- | --- | --- | | direct Codex | `codex ... ` | no name, no wrapper | | named thread | create thread, call `thread/name/set`, resume thread | you pass `--name` | | handoff | call another command with prompt as final argv | `p-f`, `p-c`, wrappers | Prompt Builder owns composition and launch metadata. Wrappers own repo-specific behavior such as fork, compact, resume, and cmux tab naming. ## Install And Identity Check Start with the binary check: ```bash which -a prompt-builder p prompt-builder --version p --version ``` What to look for: - both commands resolve - both resolve to the intended install location - both report the same version - `p` is not just an interactive-only alias If working from a local Prompt Builder checkout, install durably: ```bash cargo install --path . --locked --force ``` If `p` is missing but `prompt-builder` exists: ```bash ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p which -a prompt-builder p p --version ``` ## Basic Use Open the interactive composer: ```bash p ``` Long form: ```bash prompt-builder ``` Prefill the composer: ```bash p "Debug the checkout flow failing test and propose the smallest safe fix." ``` Submit noninteractively: ```bash printf 'Debug the billing webhook duplicate-processing bug.\n' | p --submit ``` Safer first pass: ```bash printf 'Debug the billing webhook duplicate-processing bug.\n' \ | p --submit --dry-run --print-command ``` Use `--submit` only when the prompt has already been composed by you or a trusted script. ## Inspection Modes Use inspection modes before launch. | Need | Command | | --- | --- | | exact prompt text | `p --print-prompt "hello"` | | human-readable command preview | `p --dry-run --print-command "hello"` | | script-readable launch manifest | `p --print-launch-json "hello"` | | rehearse submit without launch | `p --submit --dry-run --print-command "hello"` | Print the prompt: ```bash p --print-prompt \ "Review the checkout flow for saved payment method regressions." ``` Print the command: ```bash p --dry-run --print-command \ "Review the failing billing webhook test and identify the smallest patch." ``` What to look for: - expected command - expected cwd from `-C` - prompt appears as one quoted argument - no accidental shell splitting Print launch JSON: ```bash p --print-launch-json \ "Review the auth/session architecture before refresh-token rotation." ``` Useful fields: ```text mode command argv env prompt ``` For scripts, prefer JSON over parsing shell-quoted command text. ## Stdin Plus Prefill Prompt Builder can combine prefilled text and stdin. ```bash printf 'failing test output here\n' \ | p --stdin --print-prompt \ "Use this test output to debug the checkout flow." ``` Good software workflow: ```bash pnpm test checkout -- --runInBand 2>&1 \ | p --stdin --print-prompt \ "Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked." ``` For a diff review: ```bash git diff -- src/checkout src/billing \ | p --stdin --print-prompt \ "Review this diff for bugs, missing tests, and risky behavior changes." ``` ## Conversation Naming Use `--name` when the work should create a named Codex thread. ```bash p --name "Checkout saved payment methods" ``` Noninteractive preview: ```bash p --submit --dry-run --name "Checkout saved payment methods" \ "Plan the first shippable slice." ``` Prompt Builder prefixes the submitted name with the current working directory basename: ```text cwd basename: shop-app name: Checkout saved payment methods CODEX_THREAD_NAME: shop-app:Checkout saved payment methods ``` What to know: - the name is not just text inside the prompt - default named launches use Codex app-server - Prompt Builder creates a thread, calls `thread/name/set`, then resumes the thread with the prompt - handoff mode passes `CODEX_THREAD_NAME` to the child command environment Confirm named mode: ```bash p --print-launch-json \ --name "Auth rotation review" \ "Review auth/session architecture." \ | jq '.mode, .env, .app_server' ``` What to look for: ```text app-server-named-thread CODEX_THREAD_NAME thread/name/set ``` ## Handoff Mode Use handoff mode when Prompt Builder should compose first, then call another command. Basic handoff preview: ```bash p --submit --dry-run --print-command \ --handoff-command /bin/echo \ "hello handoff" ``` Add static handoff args: ```bash p --submit --dry-run --print-command \ --handoff-command /bin/echo \ --handoff-arg wrapper \ --handoff-arg before-launch \ "hello handoff" ``` Important rule: ```text The composed prompt is passed with Command::arg as the safe final argv element. It is not shell-evaluated. ``` Prompt text with spaces, newlines, quotes, `$HOME`, semicolons, or pipes stays prompt text. Confirm with JSON: ```bash p --print-launch-json \ --handoff-command /bin/echo \ "fix this and keep \$HOME literal" \ | jq '.mode, .argv' ``` What to look for: - mode is `handoff` - prompt is the final argv element - `$HOME` stays literal inside the prompt value ## Handoff Options These options become wrapper toggles when `--handoff-command` is present: ```text --fork-from --compact --launch-option ``` Example: ```bash p --print-launch-json \ --handoff-command /bin/echo \ --handoff-arg wrapper \ --fork-from last \ --compact \ --launch-option "trace=--trace-app-server" \ "continue from here" \ | jq '.handoff, .argv' ``` Expected ordering: ```text ``` If `--fork-from`, `--compact`, or `--launch-option` are used without `--handoff-command`, they are ignored for default Codex launch. ## Compose Before Fork Or Compact Routing gets work to the right Codex session. Prompt Builder composes the prompt before that routed action runs. | Helper | Use It When | | --- | --- | | `xfl` | fork now with an already-obvious prompt | | `xfc` | fork, compact, and resume now | | `p-f` | compose in `p`, then fork from the selected/current source | | `p-c` | compose in `p`, then fork, compact, and resume | | `p-cm` | compose in `p`, then compact-fork from conversation `m` | Confirm the helpers: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc' ``` Inspect the package copy: ```bash rg -n 'p-f|p-c|p-cm|xfl|xfc|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh ``` Conceptual shape: ```text p-f -> p -> compose prompt -> handoff to zsh -lc -> source 40-ai.zsh -> _codex_prompt_builder_fork --fork-from ``` Compact shape: ```text p-c -> p -> compose prompt -> handoff to zsh -lc -> source 40-ai.zsh -> _codex_prompt_builder_fork --fork-from --compact ``` Why `zsh -lc` is there: ```text `p-f`, `p-c`, `xfl`, and `xfc` are zsh functions in common setups. A normal subprocess cannot run a shell function unless zsh loads the file that defines it. ``` ## Composer Affordances Prompt Builder mirrors the important parts of the Codex composer so editing habits stay consistent. | Action | Behavior | | --- | --- | | `Enter` | submit | | `Shift+Enter` | insert newline | | bracketed paste | pasted text arrives as a paste event | | large paste | visible placeholder, full text restored on submit | | `Ctrl+C` with draft text | clear current draft | | `Ctrl+C` on empty draft | quit | | `@` | file selector | | `$` | skills lookup | | `/` at prompt start | slash command popup | | `Tab` | move between Name, Prompt, and options | | `Space` on an option | toggle wrapper option | ### `@` File Selector Open: ```bash p ``` Type: ```text Review @ ``` Select the file instead of typing the path from memory. Good prompts: ```text Review @src/checkout/CheckoutForm.tsx for saved payment method regressions. ``` ```text Use @src/billing/webhook.ts and @tests/billing/webhook.test.ts to debug duplicate invoice processing. ``` ### Skills Lookup Type: ```text $ ``` Use skills when the prompt should invoke a known local workflow instead of retyping every step. Example: ```text Use $oracle-packx to review the auth/session architecture before refresh-token rotation. ``` ### Slash Commands Slash commands are structured verbs. Put them at the beginning of the prompt. ```text /review /plan /compact ``` ## Ask The Agent This Debug a checkout-flow prompt before launch: ```text Use Prompt Builder as the preflight boundary. I want to implement saved payment methods in checkout. Help me compose a prompt for `p --print-prompt` first. It should reference the likely checkout files, call out invariants, name tests to run, and ask for the smallest shippable slice. Do not launch Codex until the prompt and launch shape have been inspected. ``` Use a named auth review: ```text Create a Prompt Builder command for an auth/session architecture review. Use `--name`, show the `--print-launch-json` command, and confirm the launch mode uses `app-server-named-thread` with `thread/name/set`. The prompt should ask for risks, migration steps, and verification commands. ``` Debug handoff quoting: ```text A Prompt Builder handoff to a wrapper is splitting the prompt. Inspect the `--print-launch-json` argv. Confirm the prompt is the final argv element. If the wrapper re-splits it, fix the wrapper rather than adding shell eval. Use `Command::arg` behavior as the contract. ``` Connect routed fork: ```text `Esc+P` routed to the correct Codex session and launched `p-f`. Inspect how `p-f` uses Prompt Builder, `--handoff-command zsh`, `--handoff-arg`, `--fork-from`, and `40-ai.zsh`. Show the dry-run command that proves the prompt will be the final argv element before the fork runs. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | correct binary | `which -a prompt-builder p` shows intended paths | | version match | `prompt-builder --version` and `p --version` match | | local install updated | `cargo install --path . --locked --force` succeeds | | exact prompt saved | `p --print-prompt ... > file` and `test -s file` | | command preview sane | `p --dry-run --print-command ...` shows expected command | | launch JSON sane | `p --print-launch-json ...` has expected `mode`, `argv`, `env` | | named thread | JSON mode is `app-server-named-thread` | | thread name | JSON env includes `CODEX_THREAD_NAME` | | handoff safe | JSON mode is `handoff` and prompt is last argv | | zsh helpers available | `zsh -lc 'source ...40-ai.zsh; whence -w p-f p-c xfl xfc'` | | variation seed ready | saved base prompt is non-empty and has invariants | ## If It Goes Wrong ### `p` Is Missing Check: ```bash which -a prompt-builder p prompt-builder --version p --version ``` Likely causes: - `prompt-builder` is installed but `p` symlink is missing - `p` is only an alias in an interactive shell - PATH changed after install Fix shape: ```bash ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p hash -r 2>/dev/null || true rehash 2>/dev/null || true which -a prompt-builder p p --version ``` ### Wrong Version Runs Check all matches: ```bash which -a prompt-builder p prompt-builder --version p --version ``` If working from the local checkout: ```bash cargo install --path . --locked --force which -a prompt-builder p p --version ``` ### Wrong Codex Binary Runs Inspect: ```bash p --dry-run --print-command "hello" ``` Override for a safe demo: ```bash PROMPT_BUILDER_CODEX_BIN=/bin/echo \ p --submit --dry-run --print-command \ "hello override" ``` Or pass the binary explicitly: ```bash p --codex-bin /bin/echo --submit --dry-run --print-command "hello" ``` ### Empty Prompt Rejected Check producer output: ```bash producer_command | tee /tmp/prompt-builder-input.txt test -s /tmp/prompt-builder-input.txt && echo "input:OK" ``` Then: ```bash p --stdin --print-prompt < /tmp/prompt-builder-input.txt ``` ### Named Thread Did Not Happen Check mode: ```bash p --print-launch-json --name "Demo" "hello" | jq '.mode, .env, .app_server' ``` What to look for: ```text app-server-named-thread CODEX_THREAD_NAME thread/name/set ``` ### Shell Function Handoff Fails Symptom: ```text xfc: command not found ``` Bad shape: ```bash p --handoff-command xfc ``` Better shape: ```bash p \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \ --handoff-arg xfc ``` Dry-run: ```bash p --submit --dry-run --print-command \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \ --handoff-arg xfc \ "continue from this compact fork" ``` ### Quoting Looks Scary Use launch JSON instead of guessing from shell text: ```bash p --print-launch-json \ --handoff-command /bin/echo \ "fix checkout keep \$HOME literal do not shell-eval this" \ | jq '.argv' ``` What to look for: - the prompt is one JSON string - it is the final argv element - shell metacharacters remain text If a wrapper splits the final argument, fix the wrapper. ### Fork/Compact Options Do Nothing Cause: ```text --fork-from, --compact, and --launch-option only matter in handoff mode. ``` Check: ```bash p --print-launch-json --fork-from last --compact "continue" | jq '.mode, .argv' ``` Fix: ```bash p --print-launch-json \ --handoff-command /bin/echo \ --fork-from last \ --compact \ "continue" \ | jq '.mode, .argv' ``` ## Variation Seed Prompt A useful variation seed has: - a concrete software goal - invariants that must not change - one variable dimension - verification command - output path or comparison criteria Example: ```bash RUN_ID="billing-webhook-variations" ROOT="artifacts/variations/$RUN_ID" mkdir -p "$ROOT/prompts" "$ROOT/launch" p --print-prompt \ "Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, and rollback risk." \ > "$ROOT/prompts/base.prompt.md" p --print-launch-json \ "Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, and rollback risk." \ > "$ROOT/launch/base.launch.json" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" jq '.mode, .prompt' "$ROOT/launch/base.launch.json" ``` ## References And Resources - Prompt Builder command: `prompt-builder` - Prompt Builder repo: - Short command: `p` - Zsh helper file: `zsh/conf.d/40-ai.zsh` - Prompt Builder checkout files: `README.md`, `src/cli.rs`, `src/main.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, `src/app_server_launch.rs`, `src/composer_input.rs` - Local install command from Prompt Builder checkout: `cargo install --path . --locked --force` - Useful debug env var: `PROMPT_BUILDER_CODEX_BIN` - Useful key debug env var: `PROMPT_BUILDER_DEBUG_KEYS` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-prompt-composition-reference Topic: Planning Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Prompt Builder composition and handoff: practice drills These exercises practice composing, inspecting, naming, and handing off prompts before launching agents. Use a real software project when possible. Prefer dry-runs and print modes until the prompt is specific enough to submit. ## Exercise 1: Identity Check Run: ```bash which -a prompt-builder p prompt-builder --version p --version ``` Fill out: ```markdown # Prompt Builder Identity - `prompt-builder` path: - `p` path: - versions match? yes/no - expected install location: - action needed: ``` If working from a local Prompt Builder checkout, run: ```bash cargo install --path . --locked --force which -a prompt-builder p p --version ``` ## Exercise 2: Print A Prompt Create a prompt for a real software task. ```bash mkdir -p artifacts/prompt-builder p --print-prompt \ "Review the checkout flow for saved payment method regressions. Identify the smallest safe implementation slice and the tests to run." \ > artifacts/prompt-builder/checkout.prompt.md test -s artifacts/prompt-builder/checkout.prompt.md && echo "prompt:OK" cat artifacts/prompt-builder/checkout.prompt.md ``` Fill out: ```markdown # Printed Prompt - command: - output path: - prompt non-empty? yes/no - software goal: - files or subsystems named: - verification command named: - one improvement before launch: ``` ## Exercise 3: Compare Prompt, Command, And Launch JSON Run: ```bash mkdir -p artifacts/prompt-builder p --print-prompt "hello checkout" \ > artifacts/prompt-builder/hello.prompt.txt p --dry-run --print-command "hello checkout" \ > artifacts/prompt-builder/hello.command.txt p --print-launch-json "hello checkout" \ > artifacts/prompt-builder/hello.launch.json cat artifacts/prompt-builder/hello.prompt.txt cat artifacts/prompt-builder/hello.command.txt jq '.mode, .command, .argv, .env, .prompt' artifacts/prompt-builder/hello.launch.json ``` Fill out: ```markdown # Inspection Mode Comparison | Mode | What It Shows | When To Use | | --- | --- | --- | | `--print-prompt` | | | | `--print-command` | | | | `--print-launch-json` | | | | `--dry-run` | | | - direct launch mode: - final argv: - prompt value: ``` ## Exercise 4: Stdin Plus Prefill Run a small stdin test: ```bash printf 'failing test output\nline two\n' \ | p --stdin --print-prompt \ "Debug this checkout test failure." \ > artifacts/prompt-builder/stdin-prefill.prompt.md cat artifacts/prompt-builder/stdin-prefill.prompt.md ``` Then try with a project command: ```bash pnpm test checkout -- --runInBand 2>&1 \ | p --stdin --print-prompt \ "Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked." \ > artifacts/prompt-builder/checkout-test.prompt.md ``` Fill out: ```markdown # Stdin Plus Prefill - prefill instruction: - stdin producer: - separator present? yes/no - final prompt starts with: - final prompt includes command output? yes/no - would you submit this as-is? yes/no - what to trim or add: ``` ## Exercise 5: Named Thread Manifest Run: ```bash p --print-launch-json \ --name "Billing webhook review" \ "Review duplicate billing webhook processing and propose the smallest safe fix." \ > artifacts/prompt-builder/named-thread.launch.json jq '.mode, .env, .app_server' artifacts/prompt-builder/named-thread.launch.json ``` Fill out: ```markdown # Named Thread Manifest - mode: - `CODEX_THREAD_NAME`: - app-server create method: - app-server name method: - where `thread/name/set` appears: - why this is different from direct Codex launch: ``` ## Exercise 6: Handoff Final Arg Run: ```bash p --print-launch-json \ --handoff-command /bin/echo \ --handoff-arg wrapper \ --fork-from last \ --compact \ "fix this and keep \$HOME literal" \ > artifacts/prompt-builder/handoff.launch.json jq '.mode, .handoff, .argv' artifacts/prompt-builder/handoff.launch.json ``` Fill out: ```markdown # Handoff Final Arg - mode: - command: - static handoff args: - toggled args: - final argv element: - does `$HOME` stay literal? yes/no - why `Command::arg` matters: - shell eval used? yes/no ``` ## Exercise 7: Handoff With Newlines And Quotes Run: ```bash p --print-launch-json \ --handoff-command /bin/echo \ "Fix the billing webhook. Keep \"invoice paid\" idempotent. Do not shell-eval \$HOME or pipes | here." \ > artifacts/prompt-builder/handoff-multiline.launch.json jq '.argv' artifacts/prompt-builder/handoff-multiline.launch.json ``` Fill out: ```markdown # Multiline Handoff - number of argv elements: - final argv element contains newlines? yes/no - final argv element contains quotes? yes/no - final argv element contains `$HOME` literally? yes/no - what would break if a wrapper re-split the final argument: ``` ## Exercise 8: Shell Function Handoff Prove the functions exist when the zsh helper file is sourced: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc' ``` Then preview a handoff to `xfc`: ```bash p --submit --dry-run --print-command \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \ --handoff-arg xfc \ "Continue from this compact fork and focus only on the failing checkout test." ``` Fill out: ```markdown # Zsh Function Handoff - sourced file: - function called: - why `zsh -lc` is required: - prompt position: - dry-run command: - what would fail with `--handoff-command xfc`: ``` ## Exercise 9: Map `xfl` / `xfc` To `p-f` / `p-c` Inspect: ```bash rg -n 'xfl|xfc|p-f|p-c|p-cm|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh ``` Fill out: ```markdown # Section 4 To Section 5 Bridge | Helper | Direct action or compose-first? | Fork? | Compact? | Uses Prompt Builder? | | --- | --- | --- | --- | --- | | `xfl` | | | | | | `xfc` | | | | | | `p-f` | | | | | | `p-c` | | | | | | `p-cm` | | | | | - when to use `xfl`: - when to use `xfc`: - when to use `p-f`: - when to use `p-c`: ``` ## Exercise 10: File Selector Drill Open: ```bash p ``` Type: ```text Review @ ``` Select a file from the popup. Use a project example such as: ```text Review @src/checkout/CheckoutForm.tsx for saved payment method regressions. ``` Fill out: ```markdown # @ File Selector - cwd: - selected path: - why this path matters: - did the inserted path match the real file? yes/no - why selecting beats typing from memory: ``` ## Exercise 11: Skills And Slash Commands Drill Open: ```bash p ``` Try the skills popup: ```text $ ``` Then try a slash command at the prompt start: ```text /re ``` Accept `/review`. Fill out: ```markdown # Composer Vocabulary - skill mention inserted: - slash command inserted: - what triggered skills: - what triggered slash commands: - why slash commands belong at the prompt start: - what `Shift+Enter` does: - what `Ctrl+C` does with text: - what `Ctrl+C` does when empty: ``` ## Exercise 12: Preview Wrapper Toggles Run: ```bash p --print-launch-json \ --handoff-command /bin/echo \ --handoff-arg wrapper \ --fork-from last \ --compact \ --launch-option "trace=--trace-app-server" \ --launch-option "debug=--debug" \ "Continue the auth/session review." \ > artifacts/prompt-builder/toggles.launch.json jq '.handoff.enabled_launch_options, .argv' artifacts/prompt-builder/toggles.launch.json ``` Fill out: ```markdown # Wrapper Toggles - enabled launch options: - argv order: - where static handoff args appear: - where toggle args appear: - where prompt appears: - why options are ignored without `--handoff-command`: ``` ## Exercise 13: Override The Codex Binary Run: ```bash PROMPT_BUILDER_CODEX_BIN=/bin/echo \ p --submit --dry-run --print-command \ "hello override" \ > artifacts/prompt-builder/override-command.txt cat artifacts/prompt-builder/override-command.txt ``` Fill out: ```markdown # Codex Binary Override - env var: - command used: - output: - why this is useful for safe demos: - how to remove the override: ``` ## Exercise 14: Debug A Broken Prompt Builder Flow Pick one failure and write the debug commands. | Failure | Useful Checks | | --- | --- | | `p: command not found` | `which -a prompt-builder p`, symlink check | | wrong Prompt Builder version | `--version`, `cargo install --path . --locked --force` | | wrong Codex binary | `PROMPT_BUILDER_CODEX_BIN`, `--codex-bin`, `--print-command` | | named thread missing | `--print-launch-json --name ...`, check `.mode` | | `xfc: command not found` | `zsh -lc 'source ...40-ai.zsh; whence -w xfc'` | | prompt split into args | `--print-launch-json`, inspect `.argv` | | fork/compact ignored | check whether `--handoff-command` is present | Fill out: ```markdown # Debug Notes - failure chosen: - first proof command: - expected output: - likely cause: - smallest fix: - confirmation command: ``` ## Exercise 15: Create A Section 6 Seed Prompt Use Prompt Builder to save one deliberate prompt for controlled variations. ```bash RUN_ID="checkout-seed" ROOT="artifacts/variations/$RUN_ID" mkdir -p "$ROOT/prompts" "$ROOT/launch" p --print-prompt \ "Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes." \ > "$ROOT/prompts/base.prompt.md" p --print-launch-json \ "Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes." \ > "$ROOT/launch/base.launch.json" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" jq '.mode, .prompt' "$ROOT/launch/base.launch.json" ``` Fill out: ```markdown # Section 6 Seed - prompt path: - launch JSON path: - software goal: - invariant 1: - invariant 2: - variable under test: - required verification: - ready for controlled variations? yes/no - what would make this prompt stronger: ``` ## Exercise 16: Write A Better Implementation Prompt Bad prompt: ```text fix checkout ``` Rewrite it for Prompt Builder: ```markdown Implement saved payment methods in checkout. Scope: - inspect: - change: - do not change: Constraints: - invariant: - security concern: - migration concern: Verification: - command: - what passing means: Return: - first shippable slice: - files changed: - risks: ``` Then print it: ```bash cat artifacts/prompt-builder/better-checkout.prompt.md \ | p --stdin --print-prompt \ "Use this implementation prompt as the final composed prompt." \ > artifacts/prompt-builder/better-checkout.final.prompt.md ``` Fill out: ```markdown # Better Prompt Review - original was weak because: - rewritten prompt names files/subsystems? yes/no - rewritten prompt names verification? yes/no - rewritten prompt limits scope? yes/no - final prompt path: ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-prompt-composition-practice Topic: Planning Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Throwaway route variants playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers often need to compare UI directions in the real app, against real routing, styling, auth, responsive behavior, and browser state. Throwaway route variants give an AI agent a concrete way to generate options quickly, prove them in localhost, promote one winner, and remove the experimental surface before it becomes maintenance debt. [Core principles](/topics/foundations-source-truth-and-design/) ## Reusable skill Install as `~/.agents/skills/throwaway-route-variants/SKILL.md`, then restart Codex. ```markdown --- name: throwaway-route-variants description: Trigger when exploring UI/layout directions and you want fast comparison without a permanent component catalog — generate several route-level variants in-app, review, keep one, delete the rest. Do NOT use when a maintained design system is required. --- # Throwaway route variants The anti-Storybook move: generate several route-level UI variants inside the running app, compare them, keep the winner, and DELETE the losers. Favors shipping momentum over a maintained catalog. These variants are explicitly disposable. ## Steps 1. Generate 5 route-level variants of the target UI INSIDE the running app — each variant is its own route (e.g. `/variant-a`, `/variant-b`, ...), not a permanent component. 2. Add simple left/right navigation between the variants so the human can flip through and compare them live. 3. Let the human pick the winner. 4. DELETE the losing routes/variants — do not keep them around as a catalog. ## Guardrails - Variants are explicitly disposable; this favors shipping momentum over a maintained component catalog. - Do NOT use when a maintained design system / permanent component library is required. ``` ## Scenarios ### Landing page direction sprint **Role:** As a frontend product engineer working in a Next.js-style marketing app The team has a design.md for a new homepage, but the visual direction is still unsettled before a stakeholder review. The app already has shared typography, buttons, cards, and layout primitives, and the developer wants to compare several real routes in localhost instead of asking for more static mockups or setting up Storybook. > As a frontend product engineer, I want an agent to create disposable homepage route variants from the current code and design.md, so that I can review real browser-rendered options, pick one, and ship without keeping a permanent variant catalog. #### Agent brief ```text Use the throwaway-route-variants skill only. First inspect the current routing structure, package.json scripts, existing homepage route, shared components, and design.md if present. Do not trust stale memory about the app structure. Create 5 temporary route-level variants of the homepage inside the app using the existing routing convention, for example /variant-a through /variant-e or the equivalent framework-native paths. Reuse existing components where practical, but keep variant-specific layout/styling isolated to the temporary routes so cleanup is simple. Add simple left/right navigation between variants, including visible Previous/Next controls and keyboard ArrowLeft/ArrowRight handling if that fits the app. Run the repo's actual dev command from package.json, usually npm run dev, pnpm dev, or bun dev. Prove every variant renders in the browser at localhost. After the human chooses a winner, promote only that implementation to the real homepage route, delete every losing variant route and temporary navigation wrapper, then run the relevant lint/typecheck/build command from package.json. Expected output: a short comparison table of the 5 variants, the chosen route, browser proof notes, commands run, and a final git diff summary showing only the promoted implementation remains. ``` #### Implementation references [Open reference](/topics/foundations-throwaway-variants-playbook/) [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-source-truth-and-design/) ```text package.json scripts in the target repo ``` ```text design.md in the target repo if present ``` ```text app/page.tsx, pages/index.tsx, src/routes, or the repo's current homepage route discovered by inspection ``` #### Browser verification Use the running local dev server as the proof surface. In a CMUX browser pane or normal local browser, open the first temporary route, then use the variant navigation controls or ArrowLeft/ArrowRight to cycle through all variants. If using an agent-browser-style workflow, collect an accessibility snapshot for each route, evaluate window.location.pathname after navigation, and capture screenshots or concise visual notes for the human review. #### Definition of done - All temporary routes render successfully in localhost using the repo's real dev command. - Browser proof exists for every variant: screenshots, accessibility snapshots, or explicit route-by-route notes with no console-blocking runtime errors. - The selected variant is promoted to the real homepage route. - All losing route variants and temporary navigation scaffolding are deleted. - The final diff does not leave behind a Storybook-like catalog, hidden demo routes, or unused variant components. #### Failure modes and mitigations - Mistake: the agent creates polished variants but leaves all 5 routes in the app. Mitigation: require a final cleanup pass and verify with git diff plus route search for variant-a, variant-b, variant-c, variant-d, and variant-e. - Mistake: the agent rewrites shared components so every variant leaks into production styling. Mitigation: keep variant-specific changes route-local until the winner is chosen, then promote deliberately. ### Authenticated onboarding alternatives **Role:** As a full-stack web developer responsible for signup and first-run onboarding A SaaS app has a working auth flow, but the post-signup onboarding page feels confusing. The team wants to compare several onboarding layouts in the real authenticated shell without risking the existing auth guard, database writes, or production onboarding state machine. > As a full-stack web developer, I want an agent to create disposable authenticated onboarding route variants that reuse the current app shell and safe fixture data, so that I can compare real UX options without breaking auth or business logic. #### Agent brief ```text Use the throwaway-route-variants skill for UI exploration only. Inspect the current auth guard, onboarding route, layout shell, data-loading pattern, and package.json scripts before editing. Do not change authentication logic, database schema, real onboarding mutations, or production redirects. Create 3 to 5 temporary route-level onboarding variants under a clearly disposable dev-only path, such as /onboarding/variant-a through /onboarding/variant-e or the framework's equivalent. Each variant should reuse the current authenticated shell and existing components, but it may use safe fixture data or read-only mocks when live data would create side effects. Add simple Previous/Next navigation between variants. Run the dev server using the actual package.json script and verify the routes in a browser. If auth is required, document the exact login path or test-user setup needed; do not assume cookies are shared with a browser agent. After the human chooses a winner, promote only that UI to the real onboarding route and delete every temporary variant path. Expected output: route list, auth assumptions, browser verification notes, commands run, cleanup confirmation, and final diff summary. ``` #### Implementation references [Open reference](/topics/foundations-throwaway-variants-playbook/) [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-source-truth-and-design/) ```text Current auth guard and onboarding route discovered from source inspection ``` ```text package.json scripts in the target repo ``` ```text Existing app shell/layout components ``` ```text Existing onboarding components, forms, and safe fixture or mock-data patterns ``` #### Browser verification Use a browser proof that respects auth reality. In a CMUX browser pane or agent-browser-style session, start from the documented login path, click/fill the test login only if the repo provides safe credentials or a local fixture path, then visit each onboarding variant. Capture an accessibility snapshot showing the page heading, primary CTA, progress indicator, and navigation controls. If login is not available, verify the variant routes with a safe mocked/read-only local route and state that authenticated production behavior was not mutated. #### Definition of done - Temporary onboarding variants are reachable in the local app without changing auth guards or production redirects. - Each variant has browser proof showing the authenticated shell or clearly documented safe mock shell. - No database schema, mutation path, or real onboarding state transition is changed for the experiment. - The selected UI is promoted to the real onboarding route after human selection. - All temporary onboarding variant routes and navigation wrappers are removed. #### Failure modes and mitigations - Mistake: the agent makes the variant work by weakening the auth guard. Mitigation: explicitly forbid auth changes and require the final diff to show no auth-guard or session-validation edits unless the human requested them separately. - Mistake: the agent assumes the browser agent has the developer's cookies. Mitigation: require an explicit login path, safe test account instructions, or a read-only mock route for browser proof. ### Responsive dashboard density bake-off **Role:** As a senior frontend engineer cleaning up a dense admin dashboard A dashboard route has grown cluttered after several feature additions. Product wants to compare a compact data-heavy layout, a guided summary layout, and a card-based layout before committing to a redesign. The current code has real components and data boundaries that should be treated as source of truth. > As a senior frontend engineer, I want an agent to generate disposable dashboard route variants using the current code as source of truth, so that I can compare density, hierarchy, and responsive behavior in-browser before replacing the real dashboard route. #### Agent brief ```text Use the throwaway-route-variants skill. Inspect the current dashboard route, layout components, data-fetching boundaries, responsive utilities, and package.json scripts. Create exactly 3 temporary dashboard route variants: one compact/data-dense, one guided/summary-first, and one card-based. Keep data access read-only and preserve existing component contracts. Add simple left/right navigation among the 3 variants. Run the local dev server with the actual package.json command, then verify desktop and narrow viewport behavior in a browser. Do not create Storybook stories, a permanent examples directory, or a dashboard variant gallery. After human selection, promote the winner to the real dashboard route and delete the 3 temporary routes. Expected output: variant intent summary, browser proof at desktop and mobile/narrow viewport, commands run, selected winner, and cleanup proof from git diff or route search. ``` #### Implementation references [Open reference](/topics/foundations-throwaway-variants-playbook/) [Open reference](/topics/foundations-source-truth-and-design/) [Open reference](/topics/foundations-source-truth-and-design/) ```text Current dashboard route discovered from source inspection ``` ```text Current shared dashboard/card/table/chart components ``` ```text package.json scripts in the target repo ``` #### Browser verification Use browser verification because layout density and responsiveness cannot be proven from source alone. In a CMUX browser pane, local browser, Playwright-backed check, or agent-browser-style workflow, open each temporary dashboard route at a desktop width and a narrow mobile-like width. Use evaluate to record viewport width and current pathname, take screenshots or visual notes, and verify that Previous/Next navigation reaches all three variants without a runtime error. #### Definition of done - Three route-level dashboard variants exist temporarily and match the requested density directions. - Desktop and narrow-viewport browser proof is captured for all variants. - Existing data contracts remain read-only and stable during the experiment. - Only the selected dashboard implementation remains after cleanup. - A final route search or git diff proves temporary variants were removed. #### Failure modes and mitigations - Mistake: the agent judges responsiveness from code without opening the browser. Mitigation: require viewport-based browser proof for every variant before selection. - Mistake: the agent turns route variants into a permanent demo gallery. Mitigation: define the routes as disposable from the start and require post-selection deletion as part of done. ## Implementation notes - Start by inspecting the live repo. Routing conventions, package scripts, app shell, auth boundaries, and component names must come from current code, not memory. - Make the temporary routes obvious and searchable. Names like variant-a, variant-b, and variant-c are boring on purpose because cleanup is easier. - Keep variant-specific implementation route-local until the winner is selected. Promote only the winning idea into the real route after review. - Browser proof matters for this technique. A successful typecheck is not enough when the decision is visual hierarchy, flow, density, responsive behavior, or auth-shell fit. - The final cleanup is not optional. The technique only works if the losing variants are deleted instead of becoming a second design system. - When an authenticated browser proof is needed, spell out the login/test-user path or use safe local fixture data. Do not assume a browser agent has access to the developer's existing cookies. ## Boundaries and caveats - Do not build or recommend a full Storybook-style maintained catalog for these experiments. - Do not keep rejected variants as hidden routes, examples, or future inspiration unless the human explicitly asks for a maintained catalog. - Do not rely on stale project memory when route structure or implementation details matter. - Do not scrape or copy existing websites as design source material; the taught design workflow used generated visual inspiration and design.md. - Do not introduce removed this workflow items as implementation requirements: Codex Sandbox and Approvals, AGENTS.md, Impeccable, Beads, Chrome DevTools MCP, or Deep Wiki Map. - Do not use YOLO, skip-trust, or approval-bypass aliases as part of this playbook. - Do not present large-context snapshots as the proven route-variant workflow; in this lesson they were framed as a possible escape hatch, not the demonstrated technique. ## Agent reference map ### Throwaway route variants skill Primary workflow contract for this topic: generate route-level variants in the running app, add simple navigation, let the human pick, then delete losers. [Open reference](/topics/foundations-throwaway-variants-playbook/) ### Lesson 04 validated references Grounding source for the taught concepts: code as source of truth, design.md from generated inspiration, and disposable route variants. [Open reference](/topics/foundations-source-truth-and-design/) ### Lesson 04 validation guardrails Use this to avoid reintroducing tools and claims that were removed as only mentioned or not taught in this section. [Open reference](/topics/foundations-source-truth-and-design/) ### Lesson 04 interactive checklist Useful for the implementation shape: prompt the agent to inspect current files, generate route-level variants, review in browser, promote one, and delete temporary routes. [Open reference](/topics/foundations-source-truth-and-design/) ### Local dev command The agent should inspect the target repo and run the real dev, lint, typecheck, and build scripts rather than guessing commands. ```text package.json ``` ### CMUX state inspection When working in CMUX, the agent can inspect the current pane/workspace before opening or using browser/terminal panes for proof. ```text cmux --json tree ``` ### CMUX pane list Use when coordinating a terminal pane running the dev server and a browser pane used for route review. ```text cmux list-panes ``` Reference ID: foundations-throwaway-variants-playbook Topic: Planning Sources: - [Agent foundations: Trust current source and capture design decisions (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-04.html) --- # Trust current source and capture design decisions > Original source pages and recordings require authorized access. The full article text here is public. The practice is grounding AI coding workflows in the live project instead of trusting stale memory. John recommends keeping memory simple with Markdown and straightforward retrieval, treating the code as the source of truth, using generated visual inspiration to produce a durable design.md, and creating disposable UI variants directly in the app so you can compare directions quickly and delete the losers. ## Working outcomes - Tell the difference between basic memory and dangerous stale memory - Treat code as the source of truth with million-token snapshot contexts - Capture a design.md standard and generate multi-route structural variants ## Concepts and consequences ### Code as the Source of Truth Project memory can be useful, but it drifts as the code changes. John’s main point is that trying to update memory on every commit can turn into a parallel maintenance problem, so the safest default is to make the agent look at the current code when implementation details matter. **Why it matters:** It keeps agents from confidently acting on outdated assumptions and keeps the workflow tied to what actually exists in the repo. ### Lightweight Markdown Memory John still sees value in basic memory when it stays simple: Markdown files, simple RAG, and human-readable notes. The danger starts when memory becomes a second system that has to be kept in sync with a fast-moving codebase. **Why it matters:** Good memory reduces repeated explanation; bad memory becomes stale documentation that misleads both humans and agents. ### Large-Context Snapshots as a Possible Escape Hatch John briefly floated million-token context windows as a possible way to take useful snapshots of codebases, but he explicitly framed it as something he had not really tried yet. In this lesson, it is a possible direction, not a proven replacement for memory. **Why it matters:** The useful idea is that current code text is more trustworthy than detached summaries, but this section does not teach a full large-context snapshot workflow. ### Design.md from Generated Inspiration John demonstrated starting design work from an inspiration board made of generated images, not scraped sites. He selected visual directions, copied them into an AI prompt, asked Codex to create a hoodie company landing page, and showed the generated design.md with references, style DNA, colors, typography, layout, composition, shape, and motion. **Why it matters:** It turns vague taste into a concrete design artifact that the agent can use to generate UI that follows a direction instead of producing a generic layout. ### Throwaway Route Variants Instead of building a heavy Storybook setup for every experiment, John often asks agents to generate multiple temporary routes or page copies using the same components with different styles. He compares them in the app with simple navigation, picks the best direction, and deletes the rest. **Why it matters:** It supports fast visual exploration without creating another maintenance surface that has to be kept up to date. ## Reference tools and resources ### Inspiration Board The generated visual inspiration board John used to select design directions and copy a structured prompt into AI tools. **Use when:** Use it when you do not know what a UI should feel like yet and need generated visual references to guide a design.md. [Reference](https://inspiration-board.pages.dev/) ### Codex CLI The local coding agent environment John used in the demo to create the hoodie company project, generate a design.md, and build the landing page. **Use when:** Use it when you want an agent working directly against a local project for repo-aware coding and prototyping. [Reference](https://github.com/openai/codex) ## Recommendations and best practices - Keep memory files light, boring, and close to the repo; avoid building a second knowledge system that must be updated every time the code changes. - When implementation details matter, have the agent inspect the current code instead of trusting memory. - Treat large-context repo snapshots as an experiment John mentioned, not as a proven workflow from this lesson. - Start AI design work from concrete visual inspiration, then turn that inspiration into a design.md before asking the agent to build UI. - Use generated inspiration images as design references rather than scraping or copying existing websites. - Generate temporary route or page variants when exploring visual direction, compare them in the app, pick one, and delete the rest. ## Practice and acceptance criteria Practice treating the live repo as the source of truth, then turn generated visual inspiration into a design.md and fast, disposable UI variants. ### Checklist 1. Pick a small active repo and identify one task where stale memory could mislead an agent, such as routing, data fetching, auth, or component structure. 2. Ask Codex or your coding agent to inspect the current files before proposing changes, then have it summarize the source-of-truth evidence. 3. Create or trim a repo-local Markdown memory file so it contains only stable conventions, setup notes, and human-useful guidance. 4. For a larger task, give the agent the relevant current files or source context directly instead of relying only on detached summaries. 5. Draft a design.md with sections for references, style DNA, colors, typography, layout, composition, shape, and motion. 6. Prompt the agent to generate 3 route-level or page-level UI variants from design.md, with simple navigation between them in the local app. 7. Review the variants in the browser, promote the best one to the real route, and delete the temporary routes. ### Stale Memory Audit **Difficulty:** Easy Find one existing project note, README section, or memory file that might be outdated. Ask the agent to compare it against the current code and produce a small patch that either fixes, shrinks, or deletes the stale guidance. **Done when:** The repo has less misleading documentation, and the agent's recommendation is based on current files rather than remembered assumptions. ### Design.md Landing Page Contract **Difficulty:** Medium Create a design.md for a fictional product landing page using concrete rules for references, style DNA, typography, color, layout, composition, shape, and motion. Then ask the agent to build one route from that contract. **Done when:** The generated page visibly follows the design.md instead of feeling like a generic template. ### Anti-Storybook Variant Sprint **Difficulty:** Hard Generate 5 disposable route-level variants of the same page from your design.md, add left and right arrow navigation, review them in the browser, promote the strongest version, and delete the other four. **Done when:** Only the chosen implementation remains in the app, the rejected variants are removed, and the final route still follows the design contract. ## Questions to test understanding ### Your coding agent confidently says a project still uses an old routing structure, but you know the app has changed recently. What should you do first? - **A.** Ask the agent to rely on its saved memory because it has seen the project before. - **B.** Have the agent inspect the current repo or provide current source context before making changes. - **C.** Create a longer memory file describing the old routing structure in more detail. - **D.** Skip investigation and let the agent implement the change directly. **Answer: B.** The live codebase is the source of truth when implementation details may have changed. Stale memory is most dangerous when it sounds confident but no longer matches the repo. ### When is lightweight Markdown memory most useful in this workflow? - **A.** When it captures stable, human-readable guidance close to the repo. - **B.** When it replaces the need to inspect code for implementation-dependent tasks. - **C.** When it becomes a separate system that must be updated after every commit. - **D.** When it hides project knowledge inside an opaque retrieval pipeline nobody reviews. **Answer: A.** John’s version of useful memory is simple: Markdown, straightforward retrieval, and information that remains useful to humans. The moment it becomes a parallel system to maintain, it starts creating the stale-memory problem. ### Why did John emphasize that the inspiration board images were generated rather than scraped? - **A.** Because the workflow is about getting visual direction without copying live websites directly. - **B.** Because scraped websites cannot be used by AI tools at all. - **C.** Because generated images remove the need for design review. - **D.** Because the inspiration board is only meant for backend architecture planning. **Answer: A.** John used generated images as inspiration material: something to look at when deciding what the UI should feel like. The point was to guide direction, not clone an existing site. ### What job does design.md perform in this lesson's AI design workflow? - **A.** It stores every rejected mockup so the agent can reuse them later. - **B.** It acts as a reusable design brief covering references, style DNA, typography, color, layout, composition, shape, and motion. - **C.** It replaces visual review because the agent can infer the best design automatically. - **D.** It is only useful for copying an existing website exactly. **Answer: B.** design.md turns selected visual inspiration into reusable instructions the agent can build from. John showed Codex using the design document and reference files to produce a workable hoodie landing page direction. ### Why generate throwaway route-level variants instead of immediately building a full Storybook-style setup? - **A.** Because variants should become permanent maintenance surfaces. - **B.** Because route variants avoid needing to review the UI in a browser. - **C.** Because agents cannot generate components directly. - **D.** Because you can compare real layouts quickly in the app, pick a winner, and delete the rest. **Answer: D.** John favors quick prototyping directly inside the app when he is not being disciplined about a full design system. Temporary routes are useful only if the losing experiments are cleaned up. ## Reflection prompts - Where does your current workflow still ask agents to trust memory when they should inspect the live code instead? - What project knowledge is stable enough to live in Markdown, and what knowledge changes too often to be trusted outside the code? - What visual references and style details would make your design.md specific enough for an agent to build from? ## Further applications 1. Create a small design.md template with sections for references, style DNA, colors, typography, layout, composition, shape, and motion. 2. Run the anti-Storybook exercise: generate several landing page routes, add left/right arrow navigation, pick one, and remove the rest. 3. Try a small current-code snapshot experiment: give the agent the relevant current files for one task and compare the result to an answer based only on an old memory note. 4. Write a reusable prompt that asks the agent to inspect the current code first, summarize the source-of-truth evidence, and only then propose or implement a change. ## Applied exercises Exercise: Variant Navigation Pattern (The Anti-Storybook Method) **Objective:** Build a rapid visual alternative to heavy interface sandboxes by spawning page variants directly inside an active dev server environment. **Task Parameters:** Create a prototype folder and initialize a workspace using your agent framework.Prompt your model tool to generate 3 to 5 discrete variations of a landing layout block, rendering them as raw inline HTML implementations within adjacent testing folders.Program a basic temporary navigation wrapper into the page footers (e.g., binding standard Left Arrow and Right Arrow key actions) to switch seamlessly between layout iterations.Review your layout choices directly inside your active browser view. Once you select a winning design pattern, instruct your agent runner to delete the temporary variants and promote the chosen layout to your core project file path. ## Questions and answers ### Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads Memory systems frequently run out of date because the underlying codebase is the ultimate source of truth. Attempting to continuously update external memory stores on every commit quickly turns into an administrative bottleneck. John suggests keeping project memories as lightweight as possible. He also mentions an alternative: leveraging large context allowances (like Oracle's 1 million token limit) to pass raw codebase snapshots directly into the context window, bypassing the need for explicit memory stores. ### I use basic memory that i got from you a while back, I still find it to be an excellent tool, I like to use it to keep things documented for developers within the same repository, would love to know if you still use it, and for what purpose, I know karpathy popularized simple, obsidian graph knowledge as opposed to a rag vector retrieval, basic memory seems to have best of both worlds John agrees that basic memory approaches that rely on simple Markdown file formatting combined with straightforward RAG mechanisms work well because they avoid unnecessary over-engineering. He notes that unless an advanced automated context synchronization system emerges, keeping documentation minimal and close to the raw source files remains the most practical path forward. ### Were you ever a fan of warp terminal? This cmux looks like I might be able to get rid of that subscription! John used Warp for a short period but eventually ran into specific workflow limitations. Certain built-in keyboard shortcuts and essential macro behaviors were unsupported at the time, leading him to return to terminal workflows like `cmux`. He notes that Warp has since moved open-source, and mentions he would gladly return to any terminal harness layer if it becomes highly agentic, performant, and serves his user experience goals better. ### This is a little off topic but when generating a lot of research what guiding principles do you reach for to staying organized as well as optimize for the ai’s retrieval ? The question continues into the perspective-based research discussion: assign expert, new-user, grandparent, and power-user lenses to separate workstreams, then use numbered QA assignments to make the results targeted and retrievable. ## Operational playbooks - [A reusable design.md standard](/topics/foundations-design-md-playbook/) - [Throwaway route variants](/topics/foundations-throwaway-variants-playbook/) - [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-04.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-04.html) ### Visual reference index - [01:23:45](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-1): Browser screen shot demonstrating multiple layout panels stacked on the inspiration-board application interface. - [01:26:14](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-2): Selection highlight highlighting layout component segments prior to executing copy commands. - [01:27:19](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-3): Terminal window capturing structural parameters pasted cleanly into the main prompt console input field. - [01:28:55](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-4): Editor viewport capturing structural variables mapping colors and typography metrics inside the design.md file. - [01:31:16](https://codex-workshop-followup.pages.dev/lesson-04.html): Dual terminal workspace capture displaying secondary script workers generating page instances side-by-side. - [01:33:30](https://codex-workshop-followup.pages.dev/lesson-04.html): Terminal display capturing structural prompt bypass responses responding to systemic skip trust flags. - [01:34:50](https://codex-workshop-followup.pages.dev/lesson-04.html): Live interface preview screen showcasing vector hoodie styling data compiled via background generation passes. - [01:37:45](https://codex-workshop-followup.pages.dev/lesson-04.html): Terminal logs showing completed codebase outputs verifying final production code frameworks. Reference ID: foundations-source-truth-and-design Topic: Planning Sources: - [Agent foundations: Trust current source and capture design decisions (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-04.html) --- # Turn preference into reusable decisions Pairwise comparisons, honest rejection, recorded axes, and durable taste rules instead of vague adjectives. ## Related working material - [Turn preference into reusable decisions — prompts and exercises](/topics/factory-preference-capture-practice/) - [Turn preference into reusable decisions — questions and tradeoffs](/topics/factory-preference-capture-questions/) - [Turn preference into reusable decisions — worked example](/topics/factory-preference-capture-worked-example/) ## TL;DR - A local **this-or-that lab**: options render side by side, you arrow-key through Elo-paired duels, and every vote + note lands in `votes.jsonl` — data your agent reads, not vibes it guesses. - You walk away with the whole kit (one harness page, one 30-line server, one manifest) and the loop: **generate options → vote → agent reads votes → sharper round**. - The one move: never answer "what do you like?" — demand options and answer **"this or that"** instead. This workshop's own page template went from "ugly as sin" to shipped in 3 rounds and 130 votes. Have your agent set this up — paste this into it: ``` text Fetch https://gentle-lasso-9d5n.here.now/agent.md?raw and follow it to set up a this-or-that voting lab in my current project. Run the success check at the end and show me the result. ``` ## The principle ## Taste is a dataset, not a description Ask someone what they like and you get adjectives — "clean", "modern", "not too busy" — words an agent can't execute. Show the same person two options and they answer instantly, reliably, hundreds of times in a row. That asymmetry is the whole trick. It's the same one RLHF is built on: humans are bad at writing reward functions and good at picking between two outputs. A this-or-that lab makes you the reward model, and `votes.jsonl` is the training signal your agent reads. ## The case study: 130 votes to a shipped template This workshop's own pages are the receipt. The starting point was a template the author called "ugly as sin... extremely difficult to read at a glance." Round 1: eight wildly different page themes, king-of-the-hill voting. It produced a ranking in 24 seconds — and felt thin, because each loser died after one duel. Round 2 fixed the harness because the votes said so: Elo pairing so every option faces many opponents, a live leaderboard, both-bad and skip buttons, synced scrolling. Twelve themes, 88 votes, a winner shipped to ten live sites. Then came the sharpest lesson. A refinement round built twelve variations orbiting the winner — and got rejected on sight: *"These designs are all WAAAY too similar."* Single-knob deltas waste votes; a duel only teaches something when the options genuinely diverge. The rebuilt round used structural moves — different section chrome, different code treatments, different layouts — plus a light/dark axis where duels alternated modes and the harness tracked per-mode records. Thirty votes later the data showed something no one would have articulated: one theme was undefeated in *both* modes (it shipped), another was a dark-mode specialist (4-0 dark, lost in light), a third the exact mirror. Total: 130 votes across three rounds, each round's harness and roster rebuilt from what the previous round's votes revealed. ## The rules that make votes cheap and honest **Options must differ structurally.** If two options could be confused at arm's length, you're spending votes on noise. **Hold the subject constant** — vary only the approach, or the comparison teaches nothing (the same rule as the 9x image-mockup pattern in the Variations section). **Never force a choice:** both-bad is a real signal (it says the whole region of design space is wrong), and quitting early must be free — votes stop being honest the moment they feel like a chore. **Record every axis you care about** (mode, device width, section) on the vote itself; splits you didn't record are insights you lost. **Elo over knockout:** pairing least-played, closest-rated options keeps every duel informative, and ratings survive an unfinished session. And **notes beat scores** — a one-line "C's header wins but B's spacing is calmer" is worth ten silent votes to the agent reading the file. ## Beyond design: any decision an agent can render Nothing in the kit knows about CSS. An option is any file an iframe can show — so the same loop ranks error-message copy, README structures, CLI output formats, API response shapes, function names, landing-page headlines, chart styles. The agent's job is always the same three steps: render genuinely distinct options, stay out of the way while you vote, then read `votes.jsonl` and turn your picks into rules it applies — and into a `DECISIONS.md` the next session inherits. That last step is the compounding one: taste captured once stops being re-litigated forever. ## Appendix ### Limits & caveats - Small vote counts are directional, not statistical. 30 votes over 12 options ≈ 5 games each; Elo with K=32 at that depth is a rough sort. Treat standings as "top cluster / bottom cluster", not a precise order. - The pairing heuristic (least-played, closest-rated, no immediate repeats) is not true adaptive sampling; informative pairs can be missed. In the case study, the \#1 and \#2 finishers never met head-to-head — read the pairings before over-trusting a margin. - One voter = a personal taste model, not user research. It optimizes for *your* preference, which is the point — but don't present the output as market evidence. - Iframe rendering means options should be same-origin and self-contained; cross-origin options lose scroll-sync and the mode toggle (both fail silently by design). - The light/dark axis requires options to respond to ``; options styled with only `prefers-color-scheme` won't flip inside the harness. - "Both bad" applies a flat −12 to both options — a pragmatic penalty, not principled Elo. Reference ID: factory-preference-capture Topic: Planning Sources: - [Turn preference into reusable decisions](https://gentle-lasso-9d5n.here.now/) --- # Turn preference into reusable decisions — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for turn preference into reusable decisions. ## Quick start The kit with three demo options, running in under a minute (needs `python3` + `curl`): ``` text mkdir -p this-or-that && cd this-or-that for f in compare.html server.py options.json options/sample-a.html options/sample-b.html options/sample-c.html; do curl -s --create-dirs -o "$f" "https://gentle-lasso-9d5n.here.now/kit/$f" done python3 server.py # then open http://127.0.0.1:8477/compare.html and vote with your arrow keys ``` ## Prompt library Three prompts run the whole loop: kick off a lab for any decision, have the agent read your votes, ship the winner. Replace the `` slots before pasting. ### Kick off a lab for any decision - Agent: any coding agent - Working directory: your project root - Expected result: a this-or-that/ dir, N distinct option files, a 127.0.0.1 URL to vote at ``` text Build me a local "this or that" voting lab for this decision: . Rules: - Generate 8 genuinely DISTINCT options. Different structure, not one knob turned — if two options could be confused at arm's length, replace one. Keep the SUBJECT constant across all options; only the approach varies. - Each option is one self-contained file an iframe can render (HTML page, image, or plain code/text file). - Set up the this-or-that kit (compare.html + server.py + options.json — from https://gentle-lasso-9d5n.here.now/agent.md?raw) with my options listed in options.json, start the server, and give me the URL. - I'll vote with arrow keys; every vote and note is saved to votes.jsonl. Don't interpret my taste yet — wait until I say done. ``` ### Read my votes (the RLHF step) - Agent: same session or a fresh one - Working directory: project root, after you pressed f - Expected result: a ranking, explicit taste rules with quoted evidence, a round-2 plan ``` text I finished voting. Read this-or-that/votes.jsonl and: 1. Give me the final ranking with win-loss records (and per-mode splits if present). 2. Tell me what my taste IS — concrete rules inferred from the winners, the losers, the both-bad votes, and my notes. Quote the evidence for each rule. 3. Propose round 2: keep the top 2-3, cut the bottom, and generate NEW options that push harder on what won. If my votes contradict each other, say so and ask me one sharp question instead of guessing. ``` ### Ship the winner and bank the taste - Agent: same project - Working directory: project root - Expected result: the real artifact updated, plus a DECISIONS.md entry future sessions can read ``` text won. Apply it for real: 1. Translate the winning option into the actual artifact (template / copy / config / code) in this project. 2. Verify it end-to-end, then show me before/after. 3. Record the decision: append the final standings, what won and why, and the taste rules you learned to DECISIONS.md — so future sessions start from my recorded preferences instead of re-asking. ``` ## The loop, productized This loop has now run on the workshop twice. The first round (130 votes) chose the page template you're reading. The second pointed the kit at its own question — *how should these guides be authored?* — 13 structurally distinct formats over one constant subject, 27 votes, and a decisive note later, every section ships a **Session Replay + Socratic Dialogue page pair**. Watch that round happen: [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) · [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html). Because it worked twice, the loop is captured twice. In the workshop repo it's an mdflow flow — one command that scaffolds a lab from this kit, fans out option authors, and injects the banked taste records fresh on every run: ``` text md flows/this-or-that.md --_question "" --_subject "" ``` The flow file, verbatim: ``` text --- description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules _inputs: [_question, _subject] _interactive: true --- You are running one round of the **this-or-that decision flow**: the user can't articulate their taste, but they can pick between two things all day. Turn the question below into an Elo-voted decision with a durable record. **Question to decide:** {{ _question }} **Subject / content source (hold constant across every option):** {{ _subject }} ## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`) 1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy, API shape). Everything else — subject content, visual theme — is held constant so votes measure only that axis. 2. **Scaffold the lab.** Create `-lab/` at the repo root. Copy `compare.html` and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json` (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base stylesheet all options link, so theme stays constant; support `html[data-mode="light|dark"]` (light default, `prefers-color-scheme` + `data-mode` override) — the harness stamps it and records the mode on every vote. 3. **Generate 9–13 structurally distinct options.** Same subject, different approach; if two could be confused at arm's length, replace one. Include the incumbent as a control when one exists. Write one exemplar option yourself, then fan out parallel subagents, each authoring 2–3 options from one tight shared brief (subject digest + format rules + per-option spec + the exemplar path). Real content only — never lorem ipsum, never invented names. 4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit (zero external requests, no absolute home paths, no secrets); render both light and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`, remove it. 5. **Hand over and get out of the way.** Start `python3 server.py ` in the background and give the user the `compare.html` URL. Controls: ←/→ pick · ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field saves with each vote (tell the user: one note outweighs ten votes). 6. **When the user says "done":** read `votes.jsonl` — ranking, per-mode W-L splits, `both_bad` lines, and especially notes. State the user's taste as explicit, quotable rules backed by vote evidence (head-to-heads, splits, quoted notes). A user note that makes a decision IS the decision. 7. **Bank it.** Archive as `votes-round.jsonl`, write `RESULTS.md` (standings table, the decision with quoted evidence, taste rules, ship plan), update agent memory so it is never re-litigated. Then propose round 2 from the winners — or ship. ## Accumulated taste record (injected fresh each run — read before generating options) @../authoring-lab/RESULTS.md @../07-variations/template-lab/RESULTS.md ``` The flow file is published as a downloadable attachment on this site (the `?raw` suffix skips the HTML viewer — required for machine fetches). Pull it into your own repo's `flows/` and run it; note it injects two taste-record files by relative path (the `@`-lines at the bottom), so outside the workshop repo point those at your own `RESULTS.md` files: ``` text mkdir -p flows curl -fsSL "https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw" -o flows/this-or-that.md md flows/this-or-that.md --_question "" --_subject "" ``` `md install "https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw"` also works — it registers the flow verbatim in the mdflow registry (reversible with `md remove this-or-that.md`) — but the registry copy can't resolve the flow's relative `@`-imports, so the `flows/`-local copy above is the layout that runs as-is. Outside the repo, the same loop is a generalized agent skill — `this-or-that`, at `~/.agents/skills/this-or-that/SKILL.md` — which pulls `compare.html` and `server.py` straight from this site's `/kit/` files and works in any project. The SKILL.md is also a downloadable attachment; install it into a project with the `skills` CLI (stage it anywhere *except* a dir named `skills/` — the CLI claims that name as its own symlink target and you'd install an empty skill): ``` text mkdir -p skill-src/this-or-that curl -fsSL "https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw" -o skill-src/this-or-that/SKILL.md npx skills add ./skill-src --skill this-or-that -y ``` ## Set it up (agent guide) Everything below is also published as [agent.md](https://gentle-lasso-9d5n.here.now/agent.md) for agents to execute cold. Three files make the kit; three sample options make it demo instantly. 1. Create `this-or-that/compare.html` — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling): ``` text this or that
``` 2. Create `this-or-that/server.py` — serves the dir and appends every POSTed vote to `votes.jsonl`: ``` text #!/usr/bin/env python3 """this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl.""" import json, os, sys, time from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler ROOT = os.path.dirname(os.path.abspath(__file__)) PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477 class Handler(SimpleHTTPRequestHandler): def __init__(self, *a, **kw): super().__init__(*a, directory=ROOT, **kw) def do_POST(self): if self.path != "/vote": self.send_response(404); self.end_headers(); return n = int(self.headers.get("Content-Length", 0)) try: data = json.loads(self.rfile.read(n) or b"{}") except Exception: data = {"error": "unparseable"} data["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S") with open(os.path.join(ROOT, "votes.jsonl"), "a", encoding="utf-8") as f: f.write(json.dumps(data) + "\n") self.send_response(204); self.end_headers() def log_message(self, *a): pass if __name__ == "__main__": print(f"this-or-that → http://127.0.0.1:{PORT}/compare.html") ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever() ``` 3. Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render; set `"modes": true` to add a light/dark axis (duels alternate modes, `d` flips, per-mode records are tracked — options must respond to ``): ``` text { "title": "Pick a direction", "modes": false, "options": [ { "id": "a", "name": "Option A", "src": "options/sample-a.html" }, { "id": "b", "name": "Option B", "src": "options/sample-b.html" }, { "id": "c", "name": "Option C", "src": "options/sample-c.html" } ] } ``` 4. Create the three demo options (same subject, three styles — replace with real options for a real decision): ``` text A

Ship the winner

Same subject, different style. This is Option A: big type, one accent, flat.

``` ``` text B

Ship the winner

Same subject, different style. This is Option B: centered serif, soft, outlined.

``` ``` text C

Ship the winner

Same subject, different style. This is Option C: terminal dark, mono, green go.

``` 5. Run it: ``` text cd this-or-that && python3 server.py # open http://127.0.0.1:8477/compare.html ``` **Success check:** with the server running, this must append one line to `votes.jsonl`: ``` text curl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{"probe":true}' tail -1 this-or-that/votes.jsonl ``` Expected: a JSON line containing `"probe": true` plus a `"ts"` timestamp — and `http://127.0.0.1:8477/compare.html` shows two options side by side. Report both results to your user, then delete the probe line. Every real vote looks like this — `winner`, `loser`, a full Elo snapshot, and the optional note; a `final` line with the standings table lands when the voter presses `f`: ``` text {"mode": "elo", "vote": 12, "left": "Option C", "right": "Option B", "winner": "Option C", "loser": "Option B", "elo": {"a": 1000, "b": 984, "c": 1016}, "note": "C's header wins but B's spacing is calmer", "lab": "Pick a direction", "ts": "the example workflow-16T22:35:47"} ``` ## Complete reusable setup contract ## This or That: RLHF for Your Agent — agent setup guide Following this file sets up: a local "this or that" voting lab in the user's current project — a duel harness page, a tiny vote-recording server, a manifest of options, and three demo options. The user votes with arrow keys; every vote is appended to `votes.jsonl` for you (the agent) to read and act on. Human companion pages on this site: the [section guide](https://gentle-lasso-9d5n.here.now/) (kit, prompts, the full write-up), the [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) (turn-by-turn replay of the round where this loop chose the workshop's own page format — 13 formats, 27 votes), and the [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html) (attendee Q&A). Placeholders used below: `` = the project you are working in. All paths are relative to ``. ## Prerequisites Check each before starting: - `python3 --version` — any Python 3.8+. - A browser on the same machine (the lab runs at `http://127.0.0.1:8477`). - Port 8477 free (or pick another: `python3 server.py 8481`). ## Steps 1. Create `this-or-that/compare.html` with exactly this content — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling): ```html this or that
``` 2. Create `this-or-that/server.py` — serves the directory and appends every POSTed vote to `votes.jsonl`: ```python #!/usr/bin/env python3 """this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl.""" import json, os, sys, time from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler ROOT = os.path.dirname(os.path.abspath(__file__)) PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477 class Handler(SimpleHTTPRequestHandler): def __init__(self, *a, **kw): super().__init__(*a, directory=ROOT, **kw) def do_POST(self): if self.path != "/vote": self.send_response(404); self.end_headers(); return n = int(self.headers.get("Content-Length", 0)) try: data = json.loads(self.rfile.read(n) or b"{}") except Exception: data = {"error": "unparseable"} data["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S") with open(os.path.join(ROOT, "votes.jsonl"), "a", encoding="utf-8") as f: f.write(json.dumps(data) + "\n") self.send_response(204); self.end_headers() def log_message(self, *a): pass if __name__ == "__main__": print(f"this-or-that → http://127.0.0.1:{PORT}/compare.html") ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever() ``` 3. Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render (HTML page, image, code/text file). Set `"modes": true` only if every option responds to ``; duels then alternate modes, `d` flips both panes, and per-mode win-loss records are tracked: ```json { "title": "Pick a direction", "modes": false, "options": [ { "id": "a", "name": "Option A", "src": "options/sample-a.html" }, { "id": "b", "name": "Option B", "src": "options/sample-b.html" }, { "id": "c", "name": "Option C", "src": "options/sample-c.html" } ] } ``` 4. Create the three demo options (same subject, three deliberately different styles). For a real decision, replace these with the user's options and update `options.json`: `this-or-that/options/sample-a.html`: ```html A

Ship the winner

Same subject, different style. This is Option A: big type, one accent, flat.

``` `this-or-that/options/sample-b.html`: ```html B

Ship the winner

Same subject, different style. This is Option B: centered serif, soft, outlined.

``` `this-or-that/options/sample-c.html`: ```html C

Ship the winner

Same subject, different style. This is Option C: terminal dark, mono, green go.

``` 5. Start the server and tell the user where to vote: ```bash cd this-or-that && python3 server.py # → this-or-that → http://127.0.0.1:8477/compare.html ``` ## Success check With the server running: ```bash curl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{"probe":true}' tail -1 this-or-that/votes.jsonl curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8477/compare.html ``` Expected: the `tail` prints a JSON line containing `"probe": true` plus a `"ts"` timestamp, and the last command prints `200`. Also confirm in a browser that `compare.html` shows two options side by side with "This one" buttons. Report all results to your user, then remove the probe line from `votes.jsonl`. ## Notes for agents - **Serve, don't open as a file.** `compare.html` fetches `options.json` and POSTs votes — `file://` breaks both. Always go through `server.py`. - **Options must be same-origin** (files inside `this-or-that/`). Cross-origin option URLs render, but scroll-sync and the light/dark stamp fail silently. - **Generating options for a real decision:** make them genuinely DISTINCT — different structure, not one knob turned. If two options could be confused at arm's length, replace one. Keep the subject constant across all options; only the approach varies. 6–12 options is the useful range. - **When the user says they're done voting:** read `this-or-that/votes.jsonl`. Vote lines carry `winner`, `loser`, a full `elo` snapshot, and an optional `note`; a `"mode": "final"` line carries the standings table. Report the ranking, infer explicit taste rules (quote the evidence — especially notes and `both_bad` results), and propose the next round: keep the top 2–3, cut the rest, generate new options that push on what won. - **Bank the outcome.** After a winner ships, append the standings and the inferred taste rules to the project's `DECISIONS.md` so future sessions inherit the preference record instead of re-asking. - **Productized forms of this loop.** In John's workshop repo, `flows/this-or-that.md` runs an entire round as one mdflow command — `md flows/this-or-that.md --_question "..." --_subject "..."` — and injects the banked taste records fresh on every run (the flow file is printed verbatim on the section guide). For any other repo, the generalized `this-or-that` agent skill (`~/.agents/skills/this-or-that/SKILL.md`) runs the same loop and pulls this exact kit from `https://gentle-lasso-9d5n.here.now/kit/`. Both artifacts are published on this site as machine-fetchable attachments (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer): the flow at `https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw` (fetch it into `flows/this-or-that.md`; it @-imports two taste-record files by relative path — point those at your own `RESULTS.md` files outside the workshop repo), and the skill at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`. Skill install: `mkdir -p skill-src/this-or-that && curl -fsSL "https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw" -o skill-src/this-or-that/SKILL.md && npx skills add ./skill-src --skill this-or-that -y` — do NOT stage in a dir named `skills/`; the skills CLI claims that name as its own symlink target and installs an empty skill. Proof it works: a second real round (13 authoring formats, 27 votes) chose the Session Replay + Socratic Dialogue page pair now used across the workshop sites — replayed at `https://gentle-lasso-9d5n.here.now/replay.html`. - **Known failure modes:** port already in use → pass another port (`python3 server.py 8481`) and use that URL everywhere; `votes.jsonl` missing → no votes have been cast yet (the file is created on first POST); a duel pane is blank → that option's `src` path in `options.json` is wrong (paths are relative to `this-or-that/`). Reference ID: factory-preference-capture-practice Topic: Planning Sources: - [Turn preference into reusable decisions](https://gentle-lasso-9d5n.here.now/) - [Public setup contract](https://gentle-lasso-9d5n.here.now/agent.md) --- # Turn preference into reusable decisions — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The room asks Why not just tell the agent what I like? Try it — you'll produce adjectives. "Clean." "Modern." "Not too busy." An agent can't execute an adjective. But show the same person two options and they answer instantly, honestly, hundreds of times in a row. That asymmetry is what RLHF is built on: humans are bad at writing reward functions and good at picking between two outputs. The harness just makes *you* the reward model, and instead of a vibe the agent gets a file. Every keystroke lands like this: ``` text {"mode": "elo", "vote": 7, "left": "Installable Skill", "right": "Session Replay", "winner": "Session Replay", "loser": "Installable Skill", "elo": { …all 13 ratings after the vote… }, "note": "", "ui_mode": "light", "lab": "How should workshop projects be authored?"} ``` Twenty-seven votes sounds like homework. How long did that actually take? About ten minutes, by the timestamps in the vote record. A duel is one keystroke; notes are optional; quitting early is free — Elo standings survive an unfinished session, which is exactly what keeps votes honest instead of dutiful. For scale: the template rendering this page took 130 votes across three rounds, and that's still cheaper than one "can you make it pop?" meeting. What stops the options from all looking the same? A round that got thrown out. A refinement pass once built twelve near-clones of a winning theme and was rejected on sight — "These designs are all WAAAY too similar." Single-knob deltas waste votes; a duel only teaches something when the options genuinely diverge. So the rule is structural, and it's written into the captured flow: ``` text 3. **Generate 9–13 structurally distinct options.** Same subject, different approach; if two could be confused at arm's length, replace one. Include the incumbent as a control when one exists. ``` The other half is holding the subject constant. In the authoring round, all 13 formats rendered the same zsh material — so every vote measured format and nothing else. Dialogue won that round. So why am I looking at two pages? Because of one note on duel 26 — the top two head-to-head: ``` text {"vote": 26, "left": "Session Replay", "right": "Socratic Dialogue", "winner": "Socratic Dialogue", "ui_mode": "dark", "toggled": true, "note": "I love _both_ the \"session replay - custom zsh functions\" and \"dialogue - custom zsh functions\". I think we could use both in separate pages so that each project has a session replay and a dialogue page"} ``` The ranking said "ship Dialogue." The note said "ship both, as a pair" — and the pair is what shipped, on every section of this workshop. If the harness only recorded winners, that decision would have been lost. That's why the note field exists, and why every axis you care about (light/dark here) is recorded on the vote itself. I pressed `f`. What do I actually do with votes.jsonl? Hand it to the agent — this is the RLHF step, and it's a prompt you can lift as-is: ``` text I finished voting. Read this-or-that/votes.jsonl and: 1. Give me the final ranking with win-loss records (and per-mode splits if present). 2. Tell me what my taste IS — concrete rules inferred from the winners, the losers, the both-bad votes, and my notes. Quote the evidence for each rule. 3. Propose round 2: keep the top 2-3, cut the bottom, and generate NEW options that push harder on what won. If my votes contradict each other, say so and ask me one sharp question instead of guessing. ``` Then bank the outcome: standings, the quoted evidence, and the taste rules go into a `RESULTS.md` and the raw record gets archived as `votes-round.jsonl`. Future sessions start from your recorded preferences instead of re-asking. Taste captured once stops being re-litigated forever. And next month, when the next decision comes up — do I re-explain all of this? No. In the workshop repo the whole loop is one command; the flow injects the banked taste records fresh on every run, so round N+1 starts where round N ended: ``` text md flows/this-or-that.md --_question "" --_subject "" ``` The flow file itself is short enough to read on one screen — and to lift: ``` text --- description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules _inputs: [_question, _subject] _interactive: true --- You are running one round of the **this-or-that decision flow**: the user can't articulate their taste, but they can pick between two things all day. Turn the question below into an Elo-voted decision with a durable record. **Question to decide:** {{ _question }} **Subject / content source (hold constant across every option):** {{ _subject }} ## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`) 1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy, API shape). Everything else — subject content, visual theme — is held constant so votes measure only that axis. 2. **Scaffold the lab.** Create `-lab/` at the repo root. Copy `compare.html` and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json` (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base stylesheet all options link, so theme stays constant; support `html[data-mode="light|dark"]` (light default, `prefers-color-scheme` + `data-mode` override) — the harness stamps it and records the mode on every vote. 3. **Generate 9–13 structurally distinct options.** Same subject, different approach; if two could be confused at arm's length, replace one. Include the incumbent as a control when one exists. Write one exemplar option yourself, then fan out parallel subagents, each authoring 2–3 options from one tight shared brief (subject digest + format rules + per-option spec + the exemplar path). Real content only — never lorem ipsum, never invented names. 4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit (zero external requests, no absolute home paths, no secrets); render both light and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`, remove it. 5. **Hand over and get out of the way.** Start `python3 server.py ` in the background and give the user the `compare.html` URL. Controls: ←/→ pick · ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field saves with each vote (tell the user: one note outweighs ten votes). 6. **When the user says "done":** read `votes.jsonl` — ranking, per-mode W-L splits, `both_bad` lines, and especially notes. State the user's taste as explicit, quotable rules backed by vote evidence (head-to-heads, splits, quoted notes). A user note that makes a decision IS the decision. 7. **Bank it.** Archive as `votes-round.jsonl`, write `RESULTS.md` (standings table, the decision with quoted evidence, taste rules, ship plan), update agent memory so it is never re-litigated. Then propose round 2 from the winners — or ship. ## Accumulated taste record (injected fresh each run — read before generating options) @../authoring-lab/RESULTS.md @../07-variations/template-lab/RESULTS.md ``` Outside this repo, the same loop is a generalized agent skill (`this-or-that`, at `~/.agents/skills/this-or-that/SKILL.md`) — it pulls `compare.html` and `server.py` straight from this site's `/kit/` files. Both the flow file and the skill are downloadable attachments with one-line install commands on the [section guide](https://gentle-lasso-9d5n.here.now/index.html). Isn't one person's 27 votes just… bias? Yes — deliberately. This is a personal taste model, not user research; don't present the standings as market evidence. The point is that your bias becomes data an agent can act on and cite back at you, instead of a mood it has to guess at. And it isn't limited to design: an option is anything an iframe can render — error copy, README structures, API shapes, function names. The authoring round voted on *formats*, not colors, and it ended with the page pair you're navigating right now. Want to watch that round happen turn by turn? That's the [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) page. Every standing, quote, and vote excerpt above is verbatim from the two banked voting rounds — the template lab (130 votes) and the authoring lab (27 votes) — via their RESULTS.md files and archived vote records. Session evidence is referred to generically. Full caveats: the [section guide's](https://gentle-lasso-9d5n.here.now/index.html) appendix. Reference ID: factory-preference-capture-questions Topic: Planning Sources: - [Turn preference into reusable decisions — questions and tradeoffs](https://gentle-lasso-9d5n.here.now/dialogue.html) --- # Turn preference into reusable decisions — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session This transcript restages a prior working session in beats. Every vote line, the standings table, and the quoted note are verbatim from the round's vote record (archived as `authoring-lab/votes-round1.jsonl`) and its `RESULTS.md`. You I want the workshop guides to move away from numbered exercises toward write-ups grounded in what actually happened in past sessions — user stories, skills, something in that direction. I can't describe the format I want. Run the this-or-that loop on it: the question is *how should workshop projects be authored?* The classic opening condition for this loop: a real decision, more than one plausible answer, and taste the deciding factor the owner can't articulate. Agent Framed the axis before generating anything. One thing varies: **content architecture**. Everything else held constant — every option renders the same subject (another section's custom-zsh-functions material) through one shared stylesheet, with light/dark supported so the mode lands on every vote. Then scaffolded `authoring-lab/` at the repo root: `compare.html` and `server.py` copied *verbatim* from this section's kit, plus the manifest — 13 concepts, incumbent included as the control: ``` text { "title": "How should workshop projects be authored?", "modes": true, "options": [ { "id": "exercise", "name": "Exercise (incumbent)", "src": "options/01-exercise.html" }, { "id": "user-story", "name": "User Story", "src": "options/02-user-story.html" }, { "id": "session-replay", "name": "Session Replay", "src": "options/03-session-replay.html" }, { "id": "scar-story", "name": "Scar → Fix", "src": "options/04-scar-story.html" }, { "id": "skill-card", "name": "Installable Skill", "src": "options/05-skill-card.html" }, { "id": "before-after", "name": "Before / After", "src": "options/06-before-after.html" }, { "id": "case-file", "name": "Case File", "src": "options/07-case-file.html" }, { "id": "prompt-anthology", "name": "Prompt Anthology", "src": "options/08-prompt-anthology.html" }, { "id": "decision-journal", "name": "Decision Journal", "src": "options/09-decision-journal.html" }, { "id": "dialogue", "name": "Socratic Dialogue", "src": "options/10-dialogue.html" }, { "id": "field-manual", "name": "Field Manual", "src": "options/11-field-manual.html" }, { "id": "run-of-show", "name": "Run of Show", "src": "options/12-run-of-show.html" }, { "id": "agent-brief", "name": "Agent-First Brief", "src": "options/13-agent-brief.html" } ] } ``` The kit teaching this section is the kit being used — copied, not rebuilt. And 13 is deliberately past the comfort zone: structural distinctness is what makes votes cheap. If two options could be confused at arm's length, one gets replaced. Agent Authored one exemplar option directly, then fanned out parallel subagents, each writing 2–3 formats from one tight shared brief: subject digest, format rules, per-option spec, the exemplar's path. All 13 render the same zsh material; only the architecture differs — an annotated session transcript, a Socratic Q&A, an investigation case file, a time-coded run of show, an installable skill, an agent-first brief, the incumbent exercise… QA before handover: every option HTTP 200 through `server.py`; grep audit for external requests, absolute home paths, secrets; both modes rendered; one smoke vote POSTed to `/vote`, confirmed in `votes.jsonl`, then removed. Server started in the background — here's the URL. Controls: ←/→ pick · ↓ both bad · `d` flips light/dark · `s` skip · `f` finish. The note field saves with each vote. The handover ends with "one note outweighs ten votes" — about to be proven — and then the agent gets out of the way. Hovering ruins honest voting. You \[arrow keys, 27 duels, about ten minutes by the timestamps\] Agent Meanwhile, every keystroke lands as a full record. Vote 7 as it hit `votes.jsonl` (Elo snapshot elided here — the real line carries all 13 ratings): ``` text {"mode": "elo", "vote": 7, "left": "Installable Skill", "right": "Session Replay", "winner": "Session Replay", "loser": "Installable Skill", "elo": { …all 13 ratings after the vote… }, "note": "", "ui_mode": "light", "lab": "How should workshop projects be authored?"} ``` Session Replay beat the Installable Skill twice (votes 7 and 20) — that head-to-head became a banked taste rule: show the session, not just the recipe. Past-session evidence outranks the same content written as instructions. You Duel 26 — the top two meet head-to-head, Session Replay vs Socratic Dialogue. Instead of just picking, a note goes into the field: ``` text {"vote": 26, "left": "Session Replay", "right": "Socratic Dialogue", "winner": "Socratic Dialogue", "ui_mode": "dark", "toggled": true, "note": "I love _both_ the \"session replay - custom zsh functions\" and \"dialogue - custom zsh functions\". I think we could use both in separate pages so that each project has a session replay and a dialogue page"} ``` The decisive artifact of the whole round is one typed sentence. The ranking alone would have shipped Dialogue and discarded Replay. A note that makes a decision *is* the decision. You Done — read the votes. Agent Read `votes.jsonl` back: 27 votes, zero both-bad, per-mode splits on every line. Final standings: ``` text # Format Elo W-L Light Dark 1 Socratic Dialogue 1064 4-0 2-0 2-0 2 Session Replay 1048 4-1 2-0 2-1 3 Agent-First Brief 1031 3-1 2-0 1-1 4 Exercise (incumbent) 1016 3-2 1-2 2-0 5–9 User Story · Scar → Fix · Installable Skill · Prompt Anthology · Run of Show all 1000, 2-2 10–12 Before/After · Decision Journal · Field Manual all 968, 1-3 13 Case File 937 0-4 0-1 0-3 ``` Stated the taste as rules with the evidence attached: **conversation beats document** — the top three all read as turns addressed to someone, and every dossier-shaped format sank. **Show the session, not just the recipe.** **Numbered steps can live inside a page but can't be its identity** — the incumbent finished 4th, outclassed rather than hated. **Bureaucratic chrome kills** — case numbers and PROC blocks took the bottom slots, and Case File went 0-3 in dark mode alone. All of it banked: standings, the quoted note, and the taste rules written to RESULTS.md; the raw record archived as votes-round1.jsonl. Decided once, with evidence — never re-litigated. Agent Then the loop itself got captured, so the next round costs one command instead of a re-explanation: an mdflow flow at `flows/this-or-that.md` that runs the whole process and injects the accumulated taste records fresh on every run, and a generalized agent skill at `~/.agents/skills/this-or-that/SKILL.md` that pulls this same kit from this site's `/kit/` files for any repo. Both are on the [section guide](https://gentle-lasso-9d5n.here.now/index.html), flow file included verbatim. The outcome is what you're reading. Every workshop section now ships a Session Replay page and a Socratic Dialogue page — and this one replays the round that decided that. ## Run this round yourself In the workshop repo, the whole loop — frame the axis, scaffold from the kit, fan out authors, QA, hand over, read the votes, bank the taste — is one command: ``` text md flows/this-or-that.md --_question "" --_subject "" ``` Anywhere else: paste the kickoff prompt from the [section guide's](https://gentle-lasso-9d5n.here.now/index.html) prompt library, or use the `this-or-that` agent skill — it fetches `compare.html` and `server.py` straight from this site's `/kit/` files. Both the flow file and the skill are downloadable attachments with one-line install commands on the [section guide](https://gentle-lasso-9d5n.here.now/index.html). Reference ID: factory-preference-capture-worked-example Topic: Planning Sources: - [Turn preference into reusable decisions — worked example](https://gentle-lasso-9d5n.here.now/replay.html) --- # Automate lifecycle work with hooks A hook is not a better prompt. It is a **lifecycle checkpoint**. Use it when the behavior should happen **whether or not the model remembers**. Use session start for setup and binding, user prompt submit for pre-submit routing, context, and safety, and stop hooks for final gates. Keep skills, [imps](https://github.com/johnlindquist/codex-imps), CLI helpers, and manual prompts for jobs that need optional invocation, model judgment, or task-specific context. > If you want things to happen automatically, that's not what skills are for. If you want them to happen automatically, that's what hooks are for. > > — John Lindquist ## Put Setup At Session Start Session start is the **setup moment**. Use it for identifiers and state that later tooling needs to find without scraping the screen or asking the model to remember. At session start, a project might record: - session id - working directory - transcript location, when available - branch name - visible workspace surface - a searchable session name or tag Keep this setup boring and reliable. If later shortcuts, dashboards, or review tools need to find the right conversation, **this is where the lookup trail starts**. > That's the key piece of information, is that session start, like, a place to set things up. > > — John Lindquist ## Route Before The Prompt Leaves User prompt submit is the **pre-submit moment**. Use it when a project-specific prompt pattern should trigger local work **before the model spends a turn**. Prompt submit triggers can do things like: - `#test` loads files tagged for test context - `#api` loads route and schema context - `!ticket` creates a tracking issue from the prompt body - `!summary` sends the current thread to a summarizer - sensitive release terms trigger a confirmation check Choose syntax that fits the project and team. Do not assume custom symbols will remain collision-free forever. ## Use Stop Hooks As Final Gates Stop hooks are for **final checks near the end of a turn**, so missing proof is surfaced before the work is treated as done. Good stop-gate candidates: - run the smallest relevant test - run a formatter or linter - check for unresolved uncertainty language - verify an issue or summary was created - check whether a forbidden file changed - surface missing proof and report blocked only when the current hook behavior supports that flow Do not claim a hook guarantees correctness. A hook can run final checks and surface missing proof; exact blocking, continuation, mutation, and appended-context behavior must be verified against the current docs and installed tool. The verification still has to be well designed. ## Keep Hooks Out Of Jobs That Need Judgment Hooks are best for **mechanical behavior**. If the action needs fresh reasoning each time, a hook is probably the wrong surface. Use a hook when: - the trigger is predictable - the action should run automatically - the behavior can be reviewed and trusted - the result should not depend on the model remembering a rule Use another surface when: - the action is optional - the model needs to decide whether it applies - the work needs a large body of task-specific context - a normal prompt, skill, CLI helper, or narrow imp would be clearer ## Use Documented Events Verify the current [Codex hook docs](https://developers.openai.com/codex/hooks) before relying on exact event lists or payload behavior. Treat event names as **current-tool details, not the durable lesson**. A hook workflow should name the lifecycle moment, state what it automates, and keep examples easy to recheck. Only some events may honor matchers, and handler support can change. Keep implementation examples conceptual until the exact matcher behavior, payload shape, return behavior, and trust flow have been checked against current docs. That matters for shared examples: start with the workflow shape, then attach exact event names only after checking the installed tool and current docs. ## Copyable Artifact: Hook Decision Checklist ```text Use a SessionStart hook when: - the session needs setup before the first prompt - you need to bind session id, cwd, transcript, branch, or visible workspace state - later tools need to find this session without screen scraping Use a UserPromptSubmit hook when: - a prompt pattern should trigger local context loading - a project shortcut should route work before the model spends a turn - a safety check should confirm or block a risky prompt Use a Stop hook when: - a final check should run before the work is treated as done - missing proof should be surfaced or reported according to verified hook behavior - final output needs proof Do not use a hook when: - the behavior needs model judgment every time - the action is optional - the implementation is not reviewed or trusted - a normal prompt, skill, CLI helper, or narrow imp is clearer ``` ## Implementation Notes To Verify Before sharing executable hook examples, verify: - exact payload fields - whether the example blocks, continues, appends context, or only reports - timeout behavior - trust-review behavior - event matcher behavior - current docs for the installed Codex version **Concepts are portable. Hook code is version-sensitive.** ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#hooks) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-hooks Topic: Execution Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#hooks) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Build hyper-specific workspace agents The fastest useful agent is usually not the biggest one. Wrap the tools you already trust, **preload only the context the job needs**, and keep broad agents out of small repeated tasks. ## Start With The Tool Build the agent around **one CLI, API, repo, or repeatable workflow**. A narrow helper should have a clear job before it gets a clever personality. ## Preload The Right Context **Static prompt context** works for stable jobs. **Dynamic context** works when the helper needs to load files, docs, API data, or a project-specific bundle before answering. > This is about as instant as I've ever seen an AI respond to anything, because it just has that context preloaded in. > > — John Lindquist ## Keep The Agent Narrow If the task needs web research, product judgment, or multi-system reasoning, send it back to a general agent or a heavier planning workflow. The narrow agent should stay **boring, quick, and predictable**. > I don't want them to reason or think about things. I want them to know exact file paths, exact examples, and then maybe some basic file editing, but not too much more than that. > > — John Lindquist ## Prefer Tools With CLIs Or APIs Command-line and API surfaces give the agent something concrete to **inspect, execute, and verify**. They also make it easier to turn a vague repeat task into a small wrapper with reliable inputs and outputs. ## Treat Account Permissions As Setup OAuth screens, account state, credential storage, scopes, and admin permissions are setup concerns. They should be checked deliberately and kept out of shared examples unless they are sanitized and current. ## Make Self-Improvement Reviewable Store suggested changes, inspect them, and apply them deliberately. A self-improving helper is only useful if its changes are **reviewable and reversible**. ## Prove Generated Helpers A newly generated **[imp](https://github.com/johnlindquist/codex-imps)** is draft tooling until the source, link/install behavior, and smoke tests check out. Do not share the generated helper as a setup path until it can **answer one harmless query and show the command evidence**. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#workspace-agents) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-workspace-agents Topic: Execution Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#workspace-agents) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Build narrow daemons and inspectable agent graphs > Original source pages and recordings require authorized access. The full article text here is public. The focus is focused Codex daemons: small background helpers that can update a human-facing dashboard, keep their own threads and settings warm through the SDK, and work best when their scope and context stay small. John then extends the pattern to self-improving agents for narrow CLIs/APIs, SDK-built agent graphs with analysis steps, and verification loops for UI layout and generated images. ## Working outcomes - Run focused background daemons that update a human-readable HTML dashboard - Use low-reasoning iteration with a deliberately small-context strategy - Coordinate SDK multi-agent graphs with a multimodal verification loop ## Concepts and consequences ### Background daemons The “human” daemon runs behind the main session. At each hook, it updates an HTML page from the conversation so far, tracks tool calls, customizes the page for the current work, and gives John a summary when it is done. Right now that dashboard is ephemeral and written to a temp directory, but John says it could be persisted. **Why it matters:** A daemon is useful when a narrow support task should keep running without interrupting the main session. ### Low-reasoning iteration John says low reasoning is underutilized, but it needs a different style of prompting. You should expect it to fail while you dial it in, because it will not deeply think through ambiguous work on its own. It works better when the job is narrow and the prompt accounts for the specific tool, CLI, API, or failure modes involved. **Why it matters:** Small, focused low-reasoning runs can be useful for high-frequency automation when the prompt and tool scope are explicit. ### Small context and specialized tool context John repeatedly frames these daemon runs as small compared with normal Codex/GPT sessions, mentioning a target of staying under about 10,000 tokens of context. He also uses the Vercel plugin story to show that giving a weaker model the right tools and focused context can outperform a stronger model without that context. **Why it matters:** Narrow context lowers usage and keeps the model focused on the job it was built to do. ### Self-improving daemons John shows the self-improve idea: when each turn ends, the daemon reads the transcript, looks for ways it can improve, finds its own file, and updates its own prompts or source. He says this is much more plausible for specific CLIs, tools, or APIs with clear tasks and predictable failure modes than for large projects that can branch in many directions. **Why it matters:** For narrow tools, repeated failures can become better operating instructions for future runs. ### SDK agent graphs John says the SDK is the right tool when you need custom agents with managed threads, managed settings, warm background behavior, and structured workflows. He describes workflows where one agent hands work to another, branches into parallel research agents, then uses an analysis step to choose or synthesize the best plans before implementation. **Why it matters:** The SDK is useful when the workflow has explicit roles, sequencing, branching, fan-out, or fan-in that should be locked into code instead of improvised in one chat. ### Multimodal verification loops John explains a comic-generation workflow where Codex generates an image, then reads the generated image back in and compares it to previous images. The verification pass can check continuity details such as whether a character has legs or whether counts match across frames. He also discusses asking UI work to return mathematical payloads for padding, margins, spacing, and layout. **Why it matters:** Generated artifacts should be inspected against concrete constraints instead of trusted after one prompt. ### Agent-readable code structure When asked about file and function line limits, John rejects arbitrary size rules. The guideline he gives is to prefer state machines, named switch cases, and English-labeled conditions over dense conditional structures. **Why it matters:** Agents can read, verify, and reason about code more reliably when the control flow exposes human-readable state names. ## Reference tools and resources ### johnlindquist/codex-daemons The repo John shows for background daemon setup and single-purpose Codex daemon scripts. **Use when:** Use it when you want to inspect or adapt the daemon pattern John discusses: clone the repo, install with Bun, and expose the executables on your path. [Reference](https://github.com/johnlindquist/codex-daemons) ### @openai/codex-sdk The SDK John says to reach for when building custom agents with managed threads, managed settings, warm daemon behavior, or structured agent graphs. **Use when:** Use it when a workflow needs explicit sequencing, branching, parallel roles, or handoffs between agents. [Reference](https://www.npmjs.com/package/@openai/codex-sdk) ### Bun The runtime John identifies as a prerequisite for the daemon shebang files and setup flow. **Use when:** Use it to install and run the daemon scripts shown in the repo setup instructions. [Reference](https://bun.sh) ### Prompt Quest comic demo John’s comic example used to explain image continuity and multimodal verification loops. **Use when:** Use it as inspiration for workflows that generate an artifact, inspect it, compare it to references, and continue only when the checks pass. [Reference](https://www.dev.build/comics/prompt-quest/0?page=5) ## Recommendations and best practices - Build daemons around narrow jobs, not vague all-purpose assistants. A dashboard updater, CLI specialist, or platform-specific helper is easier to prompt and trust than one giant agent. - Use low reasoning only with explicit prompting and narrow scope. Expect iteration while you dial in the prompt, because the model will not reliably infer the full workflow on its own. - Keep daemon context small. John’s target in this section is under about 10,000 tokens, with only the context and tools the daemon actually needs. - Reach for the SDK when you need managed threads, managed settings, warm background behavior, or a workflow where agents hand work to other agents. - Apply self-improvement first to narrow CLIs, tools, or APIs with clear failure modes. Large projects can branch too many ways for simple self-improvement to stay clean. - Do not spawn many agents unless you also design the analysis or synthesis step. Parallel work without review leaves the human with a pile of artifacts. - Use verification loops for generated artifacts. For UI, ask for concrete layout numbers; for images, feed the generated result back in and compare counts, continuity, and constraints. - For code that agents will read, prefer state machines, named cases, and English-readable conditions over arbitrary line-count rules. ## Practice and acceptance criteria Practice designing focused Codex daemons and SDK agent workflows that stay narrow, warm, observable, and verified. ### Checklist 1. Pick one narrow daemon job you actually need, such as updating an HTML dashboard, summarizing turns, wrapping a specific CLI, or tracking tool calls. 2. Write the daemon prompt so the job, tool scope, expected behavior, and likely failure modes are explicit. 3. Use SDK-style managed threads and settings only when the workflow needs warm background behavior, agent handoffs, branching, or role-specific agents. 4. Keep the daemon's context small, aiming under about 10,000 tokens and avoiding unrelated tool or plugin context. 5. For a human-facing daemon, record the latest summary, conversation state, and tool calls in an HTML dashboard. 6. For a self-improving daemon, start with a narrow CLI, tool, or API where failures are specific enough to improve prompts or tool-call guidance. 7. For multi-agent workflows, include an analysis or synthesis step after parallel workers before implementation continues. 8. For generated images or UI, add a verification pass that checks concrete details such as counts, continuity, padding, margins, or spacing. 9. For code that agents will inspect, prefer named states, switch cases, and English-readable conditions over deeply nested conditionals. ### Warm HTML Dashboard Daemon **Difficulty:** Easy Build a tiny background daemon that watches a local session log and updates an HTML dashboard with the latest summary, conversation state, and tool calls. **Done when:** After three separate interactions, the HTML dashboard updates without you manually editing it and without interrupting your main Codex session. ### Low-Reasoning CLI Specialist **Difficulty:** Medium Create a focused wrapper for one CLI or tool you use often, such as Wrangler, Neon, the Vercel CLI, or another specific API-backed tool. Give it a narrow job, explicit instructions, and guidance for the common failure modes you expect. **Done when:** It completes five small scripted tasks and handles one intentionally bad input by explaining what failed instead of wandering into unrelated work. ### Self-Improving Narrow Tool Daemon **Difficulty:** Medium Prototype a daemon for a narrow CLI or API that reads the latest transcript or log at the end of a turn and proposes one improvement to its own prompt or source instructions. **Done when:** After two repeated failures, it identifies the repeated pattern and produces a concise prompt/source improvement that you can inspect. ### SDK Agent Graph With Analysis **Difficulty:** Hard Design a small SDK-style workflow where one agent starts the task, several focused workers run in parallel, and an analysis agent compares their outputs before anything is implemented. **Done when:** The final result clearly shows which worker outputs were accepted, which were rejected or merged, and what the analysis step chose to pass forward. ### Multimodal Continuity Check **Difficulty:** Hard Create a small generation-and-verification loop for an image or UI artifact. Generate the artifact, inspect it, return concrete counts or layout values, and compare those values against the required constraints. **Done when:** The workflow catches at least one mismatch, such as a missing visual element, wrong count, or inconsistent spacing, before accepting the final artifact. ## Questions to test understanding ### When is a background daemon the right tool in this lesson's workflow? - **A.** When a narrow support task should run behind the main session - **B.** When one giant agent should own every tool and decision - **C.** When you want to maximize context for every prompt - **D.** When you want to avoid defining the daemon's job **Answer: A.** John’s “human” daemon runs in the background, updates an HTML dashboard at hooks, tracks tool calls, and summarizes the session without taking over the main work. ### What did John say low reasoning needs in order to be useful? - **A.** A vague goal and freedom to infer the whole workflow - **B.** Every plugin and every possible context file - **C.** More explicit prompting, narrow scope, and iteration through failures - **D.** Only tasks that require deep strategic judgment **Answer: C.** John says low reasoning is underutilized, but it needs a lot of prompt detail and you should expect failures while you dial it in. ### When did John say you should reach for the SDK? - **A.** For every normal one-off Codex question - **B.** When building custom agents with managed threads, settings, warm behavior, or agent graphs - **C.** Only when you want to avoid writing workflow logic - **D.** Only for image generation **Answer: B.** John frames the SDK as the tool for custom agents, managed threads/settings, warm background daemons, and structured workflows with handoffs or branches. ### Where did John say self-improving daemon patterns fit best? - **A.** Specific CLIs, tools, or APIs with clear tasks and predictable failure modes - **B.** Large projects with many possible directions - **C.** Unscoped brainstorming chats - **D.** Any workflow where the agent should ignore its previous failures **Answer: A.** John says self-improvement is difficult in large projects but more plausible when the agent works against a narrow tool whose failures can be accounted for in prompts and tool calls. ### What should happen after several parallel agents produce research or plans? - **A.** The human should manually sift through every artifact without help - **B.** An analysis or synthesis step should compare the outputs and choose or combine the best ones - **C.** Every worker should implement its own separate result - **D.** The workflow should always stop before implementation **Answer: B.** John describes workflows where parallel research agents feed into an analysis step that checks the plans and decides what should move forward. ### What is the point of the multimodal verification loop John describes? - **A.** To trust the first generated image without checking it - **B.** To make image generation unrelated to previous frames - **C.** To feed the generated image back in, count or compare details, and verify continuity - **D.** To replace all UI checks with arbitrary line-count rules **Answer: C.** John explains that Codex can generate an image and then inspect that image against previous frames or reference images, checking concrete details such as counts and continuity. ## Reflection prompts - Where in your current workflow are you using a large general agent when a small daemon with a narrow job would be cheaper and easier to trust? - Which tools, plugins, or context could be removed from one agent profile so it stays focused on its actual job? - Where would an analysis or synthesis step reduce artifact-sifting in a workflow that uses multiple agents? - What generated artifact in your workflow should be verified with concrete counts, layout values, or continuity checks before you trust it? - Where would named states or English-readable switch cases make your code easier for an agent to inspect than nested conditionals or arbitrary line-count rules? ## Further applications 1. Inspect one daemon file in the codex-daemons repo and identify what makes it narrow: its trigger, its context, its settings, and its output. 2. Build a tiny daemon that updates an HTML dashboard from a local session log with the latest summary and tool-call state. 3. Sketch one SDK workflow with a first agent, several parallel worker agents, an analysis step, and a final implementation step. 4. Try a small multimodal verification loop: generate an image, ask a vision-capable pass to count or compare required elements, then regenerate only if the check fails. 5. Refactor a small conditional-heavy module into named states or switch cases so an agent can read the control flow in clearer English. ## Applied exercises ### Exercise 1: Build a Self-Aware Shebang Script **Objective:** Create a local executable file using BUN that reads its own file block on failure and alters its own instruction prompt. **Requirements:** Write a basic shell-executable script utilizing a #!/usr/bin/env bun shebang line.Integrate a small hook that passes the current execution log file straight to a low-reasoning LLM completion endpoint.Instruct the script to rewrite its internal system prompt string if a failure signature is detected. ### Exercise 2: Mathematical Layout Verification **Objective:** Build a QA assertion script that verifies a component UI layout against strict structural bounds rather than visual guesswork. **Requirements:** Design a mock UI rendering block outputting Tailwind CSS utility classes.Write an agent extraction prompt requiring Codex to parse the raw markup and isolate all padding, margin, and alignment variables into a structured JSON payload.Create an assertion step evaluating if the extracted values strictly conform to a standardized geometric spacing layout scale. ## Questions and answers ### I have heard a few people say that low reasoning is under utilized and I never understood that till now. Low reasoning requires a different approach. You have to expect it to fail a bunch initially before you get it exactly where you want it. It isn’t going to independently think through complex problems, so you must write precise prompts and account for explicit tool failures ahead of time. However, it uses very small footprints compared to huge model passes, keeping interactions well under 10,000 tokens of context. ### Do you ever get rate limited? Or failures? When running things in parallel with that tool? No, I haven't been rate-limited with this approach at all. The context usage is exceptionally small compared to normal prompt loops run inside major general-purpose sessions—it's barely a drop in the bucket. This is an observation about John’s small-context setup, not a guarantee that parallel work cannot hit rate limits. ### Are these human dashboards ephemeral or persisted? Right now they write to a local temp directory, making them ephemeral. However, you can cleanly persist them. The instructions are included inside the repository: you just clone the repo, run bun install, and execute unlink to place the executables directly onto your global path system. Command caveat: the Q&A wording says `unlink`, but the concrete daemon setup instructions use `bun link` to add executables to PATH. Follow the command reference rather than interpreting `unlink` as installation. ### Do you have any good resources where you look for skills, plugins, clis, before creating your own? John highlights two primary on-screen resources for the AI workspace context: skills.sh and the Codex Awesome Plugins ecosystem repository. ### On self-improvement, thoughts on karpathy auto-research as a general pattern? I haven't implemented it directly yet, but it is firmly on my list. We can definitely construct tailored background daemons around this pattern to execute autonomous research loops for active projects. It fits neatly into the concept of agents reading their own source to iterate past failures. ### Isn’t /goal kind of an implementation of autoresearch? They are closely aligned. The beauty of the /goal implementation in GPT-5.5 is its clean interface—putting it behind a keyword slash command works incredibly well. I am working on adding a tracking plugin to my /goal usage that saves metrics on tool calls, execution effort, and compaction events so that subsequent agent passes can look back at historic execution paths. ### Do you subscribe to the thought that modules should be under 500 lines, function should be under 50 lines, classes should be under 200 lines or anything like that? No, I don't follow or subscribe to arbitrary line count rules. The single most important code style structure for agent workflows is to avoid deep conditional chains and use explicit state machines or named switch statements instead. When you choose clear English naming keys inside your code structures over complex syntax trees, the reading agents can interpret the underlying execution paths far more effectively. ## Operational playbooks - [Isolated Codex daemon profile](/topics/foundations-daemon-profile-playbook/) - [Codex Daemon Profile Field Guide](/topics/foundations-daemon-profiles-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-09.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-09.html) ### Visual reference index - [03:58:04](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-1): Terminal workspace around the background daemon discussion; dashboard output is not clearly visible in this still. - [04:00:44](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-2): Screen view of John typing the pro browser automate OpenX.com... command parameters inside the shell prompt. - [04:01:40](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-3): Display of the daemon project repository instructions containing setup steps for bun install and path unlinking. - [04:02:35](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-4): Code layout showing a self-improving shebang daemon file reading its own source script context. - [04:04:54](https://codex-workshop-followup.pages.dev/lesson-09.html): Code/repository view during the community registry discussion; skills.sh/plugin-list claims should remain transcript evidence unless a closer browser still is selected. - [04:13:00](https://codex-workshop-followup.pages.dev/lesson-09.html): Dark editor/workspace view during SDK-vs-UI workflow discussion; graph-chain specifics are transcript evidence here. - [04:17:30](https://codex-workshop-followup.pages.dev/lesson-09.html): n8n-style workflow graph page visible during layout/automation discussion. - [04:19:12](https://codex-workshop-followup.pages.dev/lesson-09.html): Browser display of the comic layout via dev.build showing character image coherence validation passes. Reference ID: foundations-narrow-daemons-and-agent-graphs Topic: Execution Sources: - [Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-09.html) --- # CMUX Orchestration Field Guide > Original source pages and recordings require authorized access. The full article text here is public. Use panes, browser tabs, and a manager agent without letting workers step on each other. Use this when one Codex session should coordinate multiple focused workers, a dev server, and browser verification. ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | Manager pane | Human-facing planning and delegation | One agent owns status and decisions | .notes/cmux-manager.md | | Worker pane | Narrow research or implementation slice | One task, one output file | .notes/workers/.md | | Browser pane | Local rendered proof | Keep visible app state nearby | .notes/browser-proof/.md | | Server pane | Long-running dev server | Keep logs stable and inspectable | .notes/server-log.md | ## Agent-ready prompt ```text Act as the CMUX manager. Inspect the current repo and create a pane plan before opening workers. Each worker gets one bounded task, writes one markdown receipt, and does not edit outside its assigned files. Keep a dev-server pane and browser-proof pane visible for web work. Collate findings into .notes/cmux-summary.md before asking me for decisions. ``` ## Applied stories ### Route migration split **Role:** Full-stack lead A Next.js migration needs source audit, implementation, browser proof, and docs update in parallel. **Agent brief:** Manager opens workers for route audit, component patch, browser proof, and docs. Only manager summarizes and asks for decisions. **Done when:** - worker receipts - server log - browser proof - single manager summary ### Bug bash control room **Role:** Frontend lead Several agents should explore different app personas without losing track. **Agent brief:** Assign each pane a persona and require numbered findings, screenshots, severity, and reproducibility. **Done when:** - per-persona QA files - deduped summary - known false positives removed ## Tips and gotchas - Give every pane a name and a single owner. - Use workers for gathering and narrow edits; keep decisions in the manager pane. - Put servers behind panes that need them so logs do not disappear. - Have Codex read worker screens/files back before summarizing. ## References - [CMUX](https://cmux.com/) - [cmux extensions](https://github.com/johnlindquist/cmux-extensions) - [Zellij](https://zellij.dev/) ## Related principles - [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/) - [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) Reference ID: foundations-cmux-orchestration-field-guide Topic: Execution Sources: - [Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-02.html) - [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html) --- # Codex Daemon Profile Field Guide > Original source pages and recordings require authorized access. The full article text here is public. Turn repeated web-dev chores into narrow, cheap, low-context Codex workers. Use this when a repeated CLI or browser-adjacent task deserves its own focused Codex profile instead of a full general agent. ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | Daemon profile | Repeated narrow task | Preview deploy checks, log triage, changelog drafting | profiles/pro-.ts | | Fake CODEX_HOME | Hard isolation | Disable memories/MCP/plugins unless needed | .codex-daemon-home/ | | Command map | Small tool vocabulary | Literal tasks with predictable outputs | README plus examples | ## Agent-ready prompt ```text Design a narrow Codex daemon profile for this repeated task. Use one command map, one output shape, low reasoning by default, and no broad memory/MCP/plugin access unless required. Keep it read-only first. Write docs, examples, and a smoke test before using it on a real repo. ``` ## Applied stories ### Preview deploy checker **Role:** Frontend lead Every PR needs preview status, changed-route browser proof, and a short verdict. **Agent brief:** Create a read-only deploy-check profile that discovers preview URL, opens changed routes, and writes a browser receipt. **Done when:** - profile file - command map - read-only proof - smoke test ### Log triage worker **Role:** On-call engineer A local dev server spews logs and general Codex wastes context reading everything. **Agent brief:** Create a profile that tails, filters, summarizes, and writes exact blocker text for the main Codex session. **Done when:** - filtered log - blocker summary - no source edits - handoff path ## Tips and gotchas - A daemon profile should be boring: one job, one command map, one output format. - Disable unrelated memories, MCPs, apps, and skills to keep context small. - Start read-only; add mutation only after a smoke test proves the profile is scoped. - Use low reasoning for literal CLI wrappers and reserve smarter models for ambiguous planning. ## References - [codex-daemons](https://github.com/johnlindquist/codex-daemons) - [Codex SDK](https://developers.openai.com/codex/sdk) - [Codex MCP](https://developers.openai.com/codex/mcp) ## Related principles - [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) - [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) Reference ID: foundations-daemon-profiles-field-guide Topic: Execution Sources: - [Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-09.html) - [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html) --- # Combine intent, implementation, and output for autonomous work > Original source pages and recordings require authorized access. The full article text here is public. John revisits PackX as a way to bundle QA artifacts so a model can compare intent, implementation, and output. He then talks through reusable specialized Codex daemon-style agents, short plain-English /goal files, Oracle-generated goal files for complex work, a timestamp-based workaround for overnight loops, and the importance of keeping team and tool workflows flexible through natural-language contracts. ## Working outcomes - Bundle the context triad — intent, implementation, and live output — for diagnosis - Run specialized Codex daemons as overnight emulated crons - Coordinate agents through natural-language loose coupling ## Concepts and consequences ### Context triad: intent, implementation, output For difficult debugging, John teaches bundling the expected behavior, the relevant code, and the observed runtime evidence. The evidence can include logs, console output, screenshots, traces, performance profiles, QA-script artifacts, and other files produced while the app is actually running. **Why it matters:** Models reason better when they can compare what should have happened, how the code attempted it, and what actually happened during execution. ### QA artifacts as live application evidence John describes logs as a representation of the live app running and recommends shaping QA scripts and project-specific dev tools so they deliberately write useful artifacts. Those artifacts can then be bundled with code using PackX or another bundler for analysis by a stronger model. **Why it matters:** A model that sees real artifacts from a user flow can diagnose behavior instead of guessing from source files alone. ### Specialized agents and Codex daemons John connects Planner, Builder, Researcher, and Validator-style responsibilities to specialized agents. His Codex daemon point in this section is high level: create custom, reusable agents for a specific project need, give them the relevant requirements, and reuse them instead of making one agent handle everything. **Why it matters:** Custom systems that understand your project can support workflows that generic shared skills may not cover. ### Short /goal files and Oracle-generated plans John shows that many of his goal prompts are plain and short, such as asking for a specific layout fix. For complex work, he often asks Oracle to research the problem and generate a more detailed goal file, then drops that file into his `.goals` directory for Codex to run through research, implementation, and verification. **Why it matters:** Simple tasks do not need massive prompts, while complex tasks benefit from a stronger planning pass before Codex executes the work. ### Overnight emulated crons Because Codex does not have a built-in cron in this workflow, John describes writing a goal that creates a timestamp, repeats a task every 10 minutes, and continues until a fixed duration or target time such as 9 AM. **Why it matters:** This gives Codex a bounded long-running loop without pretending it is a real scheduler. ### Natural-language loose coupling For team workflows and tools, John recommends staying flexible: capture meetings and workflow complaints, iterate on how the team works, and prefer open-source, agent-first tools whose main contract is natural language. He uses the ability to abandon a tool easily as the point. **Why it matters:** Tools are changing quickly, so teams should avoid investing too heavily in brittle workflows tied to one vendor or interface. ## Reference tools and resources ### PackX A bundling tool John uses to package code, logs, screenshots, traces, and other artifacts into a single context bundle for model analysis. **Use when:** Reach for it when a difficult bug needs the full intent, implementation, and output picture instead of code alone. [Reference](https://www.npmjs.com/package/packx) ### codex-daemons John’s specialized Codex daemon project/concept, discussed here at a high level as a way to create reusable agents customized for a project need. **Use when:** Study it when you want to build a focused reusable Codex helper instead of relying on one broad agent for every responsibility. [Reference](https://github.com/johnlindquist/codex-daemons) ### Agent Browser A web-app verification tool John names as an example of collecting Chrome DevTools console logs and screenshots as live-run artifacts. **Use when:** Use this pattern when verifying a web project and you need browser evidence to bundle with source and intent. [Reference](https://www.npmjs.com/package/agent-browser) ### Oracle John’s name in this workshop for a stronger planning and analysis workflow he uses to inspect bundles and generate detailed goal files. **Use when:** Use this pattern when a task is complex enough that you want research, implementation, and verification planned before handing the goal to Codex. search: John Lindquist Oracle Codex goal files ### ScreenPipe A tool John uses as an example of capturing observational screen data so an agent can analyze how you work and suggest workflow improvements. **Use when:** Consider the pattern when you want to feed agents relevant observational data about your work; in this section it was an example, not a Codex daemon requirement. search: ScreenPipe screen recording workflow analysis ## Recommendations and best practices - For hard bugs, do not send code alone. Bundle the stated intent, relevant implementation, and runtime output such as logs, screenshots, traces, performance profiles, and console errors. - Shape QA scripts and project-specific dev tools to produce artifacts deliberately; do not wait until a failure and then wish you had logs. - Use short, plain-English `/goal` prompts for simple tasks. John’s examples were not hyper-specific; they named the concrete thing to fix or investigate. - For complex work, have a stronger planning or research pass produce a goal file, then run that file from `.goals/` so the research context flows into implementation and verification. - Use specialized Codex daemon-style agents for recurring project roles, but keep the claim high-level: customize the agent with requirements and reuse it. - For overnight work, write the loop into the goal with a timestamp, interval, and stop point such as four hours later or 9 AM. - For team workflows, capture meeting or stand-up transcripts, look for repeated complaints or friction, and keep tool contracts flexible enough to swap tools when the ecosystem changes. ## Practice and acceptance criteria Practice building evidence-rich context bundles, short goal files, specialized Codex helpers, and bounded overnight loops without turning them into one giant magical agent. ### Checklist 1. Choose one small repo task that has a visible outcome, such as a failing test, broken UI flow, flaky script, or dependency investigation. 2. Write a short plain-English goal for the task: what to inspect, what result you want, and any obvious constraints. 3. Create an `intent.md` file with 2-4 sentences describing the expected behavior and specific success criteria. 4. Run the relevant command or user flow and save the real output to an artifact such as `execution.log`, `console.log`, `trace.txt`, or a screenshot. 5. Bundle the intent, relevant source files, and runtime output into one inspectable context package using PackX or a simple manual text bundle. 6. Ask the model to compare intent, implementation, and output and identify where the mismatch starts. 7. For a complex task, ask a stronger planning or research pass to generate a goal file that includes research, implementation, and verification. 8. For any repeated or overnight run, add a timestamp, interval, and fixed stop condition before starting. ### Build a Context Triad Debug Bundle **Difficulty:** Easy Pick one failing test or bug. Create `intent.md`, capture the failing command output into `execution.log`, include the smallest relevant source files, and ask Codex to identify where output diverges from intent. **Done when:** Codex can point to a specific mismatch between expected behavior, implementation, and runtime evidence instead of giving generic advice. ### Write a Plain-English Goal Flow **Difficulty:** Medium Take a medium-sized change and draft a short `/goal` that asks for research, implementation, and verification. Name the artifact or tool that should prove the result, such as logs, tests, browser output, screenshots, traces, or a QA script. **Done when:** The goal is short enough to understand quickly, but clear enough that the agent knows what to investigate, what to change, and how to verify it. ### Design an Overnight Investigation Loop **Difficulty:** Medium Write a `.goals/overnight-investigation.md` file that tells Codex to create a timestamp, run an investigation every 10 minutes, record findings, and stop after a fixed duration or target clock time. **Done when:** The goal file contains the loop interval, artifact path, and stop condition, and it does not describe an unbounded keep-working-forever task. ### Draft a Specialized Codex Daemon Brief **Difficulty:** Hard Choose one recurring project need, such as planning a change, researching an API, verifying a web flow, or packaging context. Draft a brief for a reusable specialized Codex helper: what it is for, what project context it needs, and what output it should return. **Done when:** Another developer can tell exactly what the helper is for, when to use it, and what useful artifact it should produce. ### Turn a Meeting Transcript into Workflow Feedback **Difficulty:** Medium Take a real or sample engineering meeting transcript and ask an agent to extract repeated complaints, workflow friction, what is working, and one concrete process improvement to discuss with the team. **Done when:** The output identifies specific team workflow issues from the transcript rather than producing generic AI SDLC advice. ## Questions to test understanding ### A web app test is failing, but the source code alone does not make the cause obvious. What context bundle gives Codex the best chance of diagnosing it? - **A.** The intended behavior, relevant source files, and actual runtime output such as logs, screenshots, traces, or console errors - **B.** The entire repository plus a request to find anything suspicious - **C.** Only the stack trace, because implementation details can bias the model - **D.** A short description of the bug with no files, so the model reasons from first principles **Answer: A.** John’s debugging bundle is intent, implementation, and output. Codex can reason much better when it can compare what should have happened against the code and what actually happened. ### What is John’s practical point about Planner, Builder, Researcher, and Validator-style responsibilities? - **A.** They are flexible responsibilities you can use to clarify or split a workflow when the task gets complex - **B.** Every Codex workflow must always run exactly four separate agents - **C.** They eliminate the need to inspect logs, screenshots, traces, or other artifacts - **D.** They are only useful for non-code writing tasks **Answer: A.** John uses these as useful workflow responsibilities, not a rigid ceremony. He also says he often keeps research, implementation, and verification in one goal, then separates more as complexity grows. ### What is the key safety and control feature of an overnight emulated cron prompt? - **A.** A request to use the most powerful model available - **B.** A broad instruction to keep improving the repo until there is nothing left to do - **C.** A clear timestamp-based loop with a fixed duration or target stop time - **D.** A requirement to rewrite the whole project before reporting back **Answer: C.** John describes creating a timestamp, doing work every 10 minutes, and stopping after a fixed duration or target time such as 9 AM. ### In this section, what did John actually teach about Codex daemons? - **A.** They can be customized as reusable specialized agents for a specific project need - **B.** They are a replacement for collecting QA artifacts - **C.** They should all share one broad responsibility for planning, coding, testing, deployment, and communication - **D.** They are the same thing as a production cron scheduler **Answer: A.** John’s daemon point here is high level: create a specialized agent, give it the requirements it needs, and reuse it for that project responsibility. ### What does natural-language loose coupling mean in this lesson? - **A.** Writing vague prompts so any tool can interpret them however it wants - **B.** Keeping the durable workflow contract in natural language so tools can be swapped later - **C.** Avoiding open-source tools because they change too quickly - **D.** Building deep proprietary integrations as early as possible **Answer: B.** John warns against over-investing in one fast-changing tool or vendor workflow. His point is to keep the contract between you and the tool flexible and mostly natural-language driven. ## Reflection prompts - Where are you currently asking one goal or agent to do too much, and which responsibility would become clearer if you split it out? - For your hardest recurring bugs, which part of the context triad is usually missing: intent, implementation, or output? - Which QA or devtool artifact would make your live app behavior easier for a model to analyze? - Which parts of your workflow are too tightly coupled to one tool or vendor, and what would the natural-language contract look like if you had to swap that tool next month? ## Further applications 1. Build a PackX-style debugging bundle: `intent.md`, relevant source, `execution.log`, screenshots or traces if available, and a prompt asking where output diverges from intent. 2. Modify one QA script so it deliberately emits artifacts a model can inspect later: logs, console output, screenshots, traces, performance profiles, or a short user-flow summary. 3. Create a `.goals/` directory and save a few short goal files for real tasks; for one complex task, ask a planning model to generate the goal file instead of writing every detail yourself. 4. Write an overnight goal that creates a timestamp, repeats a research or verification pass every 10 minutes, and stops at a fixed duration or target clock time. 5. Draft a high-level specialized Codex daemon brief for one recurring project job: what the agent is for, what project context it needs, and what output or artifact it should return. 6. Try the team-workflow loop John described: feed a meeting transcript into an agent and ask it to identify what is working, what is not, and what workflow changes the team should discuss. ## Applied exercises Exercise: Building an Intent-Implementation-Output Bundle **Objective:** Manually replicate a PackX-style context container to help an external agent debug a local execution discrepancy. **Instructions:** Select a simple function in your local workspace that currently exhibits a bug or unexpected behavior.Create a clean file named intent.md and document what the code is intended to accomplish in two sentences.Run your program and pipe its runtime exceptions or logs directly into a file: npm run dev > execution.log or equivalent.Combine your raw target source code file, your intent.md instructions, and your execution.log outputs into a single text block.Pass this combined context bundle to your development model using the following prompt header:"Analyze this context bundle. The intent, implementation, and output layers do not align. Identify the exact line where the execution output diverges from my intent." ## Questions and answers ### assuming convex improvement in intelligence, Are you saving prototypes/ideas/convos/second-brain now, so future smarter models and better tools can synthesize and build them later? or are you planning for future in any way? John believes precise long-term future planning is effectively impossible given the speed of changes. From a personal perspective, he uses agents to offload administrative burdens to preserve real-world human experiences (hiking, spending time with family). Professionally, he focuses on immediate, just-in-time contextual tracking (like scraping or parsing on demand) rather than heavy pre-engineered setups. ### What are your thoughts on learning new skills. How do you use AI to either accelerate it or optimize for something else? I John highlights the power of specialized vocal and visual analysis agents. Instead of replacing the skill, these tools act as localized coaches—monitoring screen inputs, speaking registers, or physical sports form to detect precise areas of failure and generate personalized training plans. ### do you use agents.md or claude.md, guardrails.md...? don't do this... tool usage specificity... etc Living guardrail files are discussed alongside the terminal workflow. Use AGENTS.md or CLAUDE.md for discovered project boundaries; symlinking is one way John shares rules across harnesses. He favors adapting rules to real errors, not building rigid frameworks. See the contracts and state-machines topic for the fuller guardrail answer. ### can you give some examples on how you prompt /goal? John displays his personal workspace markdown documents on screen. He reveals that his own hand-written goals are surprisingly short and plain-spoken (e.g., "The buttons on the footer are misaligned. Please calculate the padding..."). For highly complex workflows, he relies on an upstream model like Oracle to author detailed step-by-step goal files, which are dropped into a local .goals/ folder and run automatically. ### Any thoughts on security. For example this minimum package age setting in pnpm seems to be an idea people are converging on. John notes that the security landscape for rapidly changing agent workflows appears exceptionally challenging, citing recent high-profile vulnerabilities like Mac kernel breaches. His primary operational advice is basic: keep environments updated, while acknowledging the inherent risks of supply chain tracking. ### in your view, what does a practical AI SDLC look like for a real engineering team, from requirements and design through implementation, testing, deployment, and maintenance? A practical AI-driven SDLC relies heavily on team agility and continuous ambient context extraction. John recommends recording engineering meetings or stand-ups, converting them to clean transcripts, and feeding those directly into project agents to track active friction. Teams should avoid heavy lock-in to proprietary design tools, favoring open-source platforms bound by natural language interfaces. ### are you using only agent-browser or also playwright? (Context confirms active rely on Agent Browser for console log bundling; specific tool trade-offs were not detailed further in this chunk). ### Did you show a /goal example for the packx ? For example I think I will convert 400 of my tests to QA or packages that are stable. The PackX example is the Oracle handoff skill. Bundle the intent, current implementation, and live output for diagnosis; for a large test migration, ask for a classified plan and implement verified slices. The companion does not capture a separate complete 400-test migration demonstration. ### so most of the time in /goal you don't define how the agent can check if the goal is achieved, correct? Correct for basic tasks, but for complex loops, the validation criteria are explicitly structured as a multi-step pipeline prefix (e.g., Oracle Research, Implement, and Verify) tied directly to custom verification tooling or browser instrumentation. ## Operational playbooks - [Overnight emulated-cron loop](/topics/foundations-overnight-cron-playbook/) - [Oracle + PackX Handoff Field Guide](/topics/foundations-oracle-packx-field-guide/) - [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/) - [Codex Daemon Profile Field Guide](/topics/foundations-daemon-profiles-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-10.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-10.html) ### Visual reference index - [04:22:45](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-1): Terminal mapping execution output directly to a data log file ta - [04:23:25](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-2): Text overview tracking the interaction loops between oracle pack - [04:24:40](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-3): Core listing on screen breaking down the verification triad elem - [04:36:15](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-4): Code surface overview detailing screenpipe setup logic and opera - [04:39:58](https://codex-workshop-followup.pages.dev/lesson-10.html): Editor display outlining production goal text documents placed i - [04:41:52](https://codex-workshop-followup.pages.dev/lesson-10.html): Ui panel showcasing image based design debugging instructions - [04:43:08](https://codex-workshop-followup.pages.dev/lesson-10.html): Automation script rendering showcasing multi hour task loops ini - [04:46:00](https://codex-workshop-followup.pages.dev/lesson-10.html): Terminal text showing connection flags routed to local infrastru Reference ID: foundations-context-triad-and-overnight-work Topic: Execution Sources: - [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html) --- # Command a CMUX manager/worker layout playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already juggle dev servers, test runners, browser verification, and agent chats; this pattern turns that chaos into one visible Manager pane coordinating narrow worker panes. It matters most when a local app needs code changes plus runtime proof, because the Manager can inspect panes, send targeted tasks, read worker output, and keep the human focused on decisions instead of pane babysitting. [Core principles](/topics/foundations-manager-worker-orchestration/) ## Copy-paste workflow **When to use:** When you want to drive several agent panes in parallel but only talk to one. This sets up a Manager pane plus worker panes in CMUX using natural language; the Manager opens, inspects, and delegates to the workers while you only converse with the Manager. ### Copy-paste prompt ```text You are the Manager agent running in my focused CMUX pane. I will only talk to you; you coordinate worker panes. Use the REAL cmux CLI (do not invent flags). Keep the upfront planning human-led — confirm the plan with me before delegating. 1. Build the layout. Open a worker surface to the right and create additional worker panes as needed: cmux new-split right cmux new-pane Name the tabs so they stay findable: cmux rename-tab "" 2. Always inspect live state before acting on a worker: cmux --json tree # full pane/surface tree as JSON (focused pane, refs, cwd) cmux list-panes # enumerate worker panes 3. Delegate a task into a worker surface, then read its output back as context: cmux send -- "" cmux read-screen # read that worker's terminal text back 4. Loop: you (Manager) talk to me, workers do the research/implementation. Report status back to me; do not let workers drift without checking cmux --json tree. Guardrail: prefer PANES over tab groups — tab groups are easy to lose track of. ``` ### How it works - `cmux new-split right` and `cmux new-pane` build the manager/worker layout; `cmux rename-tab ""` keeps roles findable. - `cmux --json tree` returns the live window/workspace/pane/surface tree as JSON (focused pane, refs like `pane:89`/`surface:126`, working directory) — inspect it before acting. - `cmux list-panes` enumerates worker panes. - `cmux send -- ""` injects a task into a worker surface; `cmux read-screen` reads that worker's terminal text back as context for the Manager. - The Manager talks to the human; workers do research/implementation. Keep upfront planning human-led. - Prefer panes over tab groups — tab groups are easy to lose track of. - Reference: [CMUX](https://cmux.com/). ## Reusable skill Install as `~/.agents/skills/cmux-orchestrate/SKILL.md`, then restart Codex. ````markdown --- name: cmux-orchestrate description: Trigger when the user wants to drive multiple terminal/agent panes in CMUX from natural language — build manager/worker layouts, open/arrange panes, inspect or send work to other panes. Do NOT trigger outside a CMUX workspace. --- # CMUX orchestration Act as the Manager agent: build a pane layout, inspect live state, and delegate work to worker panes using the REAL cmux CLI. Do not invent flags. Inspect with `cmux --json tree` before acting. ## Command map (real cmux CLI) ```bash cmux new-split # split from the focused surface in a direction cmux new-pane # create a pane (terminal or browser content) cmux --json tree # full window/workspace/pane/surface tree as JSON cmux list-panes # enumerate panes in the workspace cmux send -- "" # send a task into a terminal surface cmux read-screen # read a surface's terminal text back as context cmux rename-tab "" # name a tab so it stays findable cmux focus-pane # focus a pane (ref like pane:89 or surface:126) ``` Handles accept UUIDs, refs like `workspace:2` / `pane:89` / `surface:126`, and indexes. ## Manager-worker pattern 1. Build the layout: `cmux new-split right`, then `cmux new-pane` for each worker; name them with `cmux rename-tab ""`. 2. Before acting on any worker, inspect live state: `cmux --json tree` (focused pane, refs, cwd) and `cmux list-panes`. 3. Delegate work: `cmux send -- ""` into a worker, then `cmux read-screen` to pull its output back as context. 4. You (Manager) talk to the human; workers do research/implementation. Report status back. ## Guardrails - Prefer PANES over tab groups — tab groups are easy to lose track of. - Only use inside a CMUX workspace. ```` ## Scenarios ### Triage a broken localhost checkout flow **Role:** As a full-stack Next.js developer shipping a checkout fix A Next.js storefront runs locally, the checkout route intermittently loses cart state after refresh, and the developer needs one agent to coordinate source inspection, dev-server logs, and browser proof without manually switching between terminals. > As a full-stack Next.js developer, I want one CMUX Manager pane to spin up focused workers for server logs, cart-state source review, and browser validation, so that I can fix the checkout bug with visible evidence instead of trusting a single agent transcript. #### Agent brief ```text You are the Manager agent in my focused CMUX pane. Do not implement yet. First inspect live CMUX state with `cmux --json tree` and `cmux list-panes`. Build a visible pane layout using only real CMUX commands: create worker panes with `cmux new-split right` and `cmux new-pane`, then name the workspace tab with `cmux rename-tab "checkout-triage"`. Create three worker roles: `server-log-worker`, `source-worker`, and `browser-proof-worker`. Send each worker a narrow task using `cmux send -- ""`: server-log-worker runs or watches the local dev server and captures errors; source-worker inspects cart and checkout route code only; browser-proof-worker verifies the localhost checkout flow in a browser or browser-agent workflow and reports exact observed behavior. After each worker responds, read its visible terminal output with `cmux read-screen`, summarize conflicts between source, logs, and browser behavior, then propose the smallest fix. Expected output: a Manager report containing pane refs from `cmux --json tree`, each worker assignment, each worker result, the chosen fix plan, and the browser/dev-server proof shape required before merging. ``` #### Implementation references [Open reference](/topics/foundations-cmux-orchestrate-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ```text cmux --json tree ``` ```text cmux list-panes ``` ```text cmux new-split right ``` ```text cmux new-pane ``` ```text cmux send -- "" ``` ```text cmux read-screen ``` ```text cmux rename-tab "checkout-triage" ``` #### Browser verification Use the browser-proof-worker for runtime proof: open the local checkout URL, take an accessibility-style snapshot of the page state, click through cart → checkout → refresh/back navigation, fill only safe test fields, and report URL, visible cart count, console/runtime errors, and whether state survives refresh. If a CMUX browser pane is available, keep that proof visible beside the Manager; otherwise use the project's existing browser automation or local browser and paste the observation back into the worker pane. #### Definition of done - Manager report includes the live CMUX pane refs from `cmux --json tree` and the named roles assigned to each worker. - Dev-server or test-runner output is copied from a worker via `cmux read-screen`, not summarized from memory. - Browser proof includes the exact localhost route, user actions, visible before/after state, and any console/runtime error text. - A final review artifact lists the minimal code area to change and the verification commands or browser steps to rerun. #### Failure modes and mitigations - The Manager delegates before inspecting live state; mitigate by requiring `cmux --json tree` and `cmux list-panes` before every send/read cycle. - Workers drift into broad refactors; mitigate by assigning each worker one narrow responsibility and having the Manager reject unrelated changes. - The browser worker reports success without proof; mitigate by requiring concrete URL, visible UI state, action sequence, and error/log evidence. ### Coordinate a design-drift review before touching CSS **Role:** As a frontend engineer maintaining a dashboard UI A dashboard page has visual drift across cards, filters, and responsive layout after several agent-generated edits, and the developer wants separate workers to inspect current code, compare live UI behavior, and propose a bounded cleanup. > As a frontend engineer, I want a CMUX Manager to coordinate code, browser, and review workers before editing CSS, so that cleanup is based on current source and visible UI proof rather than vague design taste. #### Agent brief ```text You are the Manager agent in my focused CMUX pane. Keep the human interaction surface to you only. Use `cmux --json tree` and `cmux list-panes` first. Create a visible Manager/worker layout with `cmux new-split right` and `cmux new-pane`; name the tab `dashboard-drift-review` with `cmux rename-tab "dashboard-drift-review"`. Create workers named `current-code-worker`, `responsive-browser-worker`, and `cleanup-plan-worker`. Use `cmux send -- ""` to assign: current-code-worker identifies the current dashboard route, component files, and styling sources; responsive-browser-worker opens the local dashboard in a browser and records desktop and narrow-width observations; cleanup-plan-worker waits for the first two worker outputs, then drafts a small numbered cleanup plan with options A/B/C and a recommended pick. Read worker panes with `cmux read-screen`. Expected output: a numbered implementation plan that says which files are source of truth, what the browser showed, which visual issues are real, and which cleanup option the Manager recommends before implementation. ``` #### Implementation references [Open reference](/topics/foundations-manager-worker-orchestration/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ```text cmux --json tree ``` ```text cmux list-panes ``` ```text cmux send -- "" ``` ```text cmux read-screen ``` ```text cmux rename-tab "dashboard-drift-review" ``` #### Browser verification Use a CMUX browser pane or local browser verification to inspect the dashboard at desktop and narrow widths. The browser worker should capture a snapshot-style summary of headings, card order, filter controls, overflow, empty states, and any console errors; click filters and navigation only enough to prove whether drift is visual, state-related, or route-specific. #### Definition of done - Manager names the CMUX tab and can list all worker panes with `cmux list-panes`. - Current-code-worker identifies the actual source files instead of relying on memory. - Responsive-browser-worker provides desktop and narrow-width observations with route and visible-state evidence. - Cleanup-plan-worker produces numbered options with a recommended pick, so the human can steer with a terse choice such as `2B`. #### Failure modes and mitigations - The agent treats design.md or memory as more authoritative than the current code; mitigate by making current-code-worker inspect the live repo first. - The browser check becomes a full QA swarm; mitigate by limiting it to the dashboard route, two viewport sizes, and the specific drift symptoms. - The Manager hides worker uncertainty; mitigate by requiring each worker output to include what it verified and what it did not verify. ### Run a bounded AFK manager check-in on parallel workers **Role:** As a senior developer supervising several local agent tasks Three workers are already running in CMUX on separate subtasks: one is fixing a flaky unit test, one is checking a build failure, and one is investigating docs or dependency usage. The developer wants the Manager to periodically inspect panes and answer simple blocking questions, but not run forever. > As a senior developer, I want a CMUX Manager to check worker panes at a fixed interval with a hard stop condition, so that parallel work keeps moving while I step away without creating an unbounded autonomous loop. #### Agent brief ```text You are the Manager agent in my focused CMUX pane. Start by creating a timestamp in your notes and inspect live CMUX state with `cmux --json tree` and `cmux list-panes`. Do not create new broad goals. Identify the existing worker panes by role, cwd, visible command, or recent terminal text. Every check-in cycle, use `cmux read-screen` to read each worker pane, summarize status, and if a worker is blocked by a simple question, choose the safest reasonable answer only when it stays inside that worker's assigned task. Use `cmux send -- ""` only after confirming the target pane from `cmux --json tree`. Stop after the explicit bound I give you, or after 3 check-in cycles if no bound is provided. Expected output: a check-in ledger with timestamp, pane refs, worker status, any answers sent, any panes needing human attention, and final stop reason. ``` #### Implementation references [Open reference](/topics/foundations-manager-worker-orchestration/) [Open reference](/topics/foundations-manager-worker-orchestration/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/) [Open reference](/topics/foundations-cmux-orchestrate-playbook/) ```text cmux --json tree ``` ```text cmux list-panes ``` ```text cmux read-screen ``` ```text cmux send -- "" ``` ```text cmux notify ``` #### Browser verification Browser proof is only appropriate if one of the existing workers is assigned to a web-app runtime task. In that case, the Manager should ask that worker for the local URL, exact browser action taken, and visible result; otherwise the correct proof is terminal evidence from `cmux read-screen`, test logs, and the check-in ledger. #### Definition of done - The Manager records a start timestamp and a hard stop condition before the loop begins. - Each cycle includes pane refs, worker status, and terminal evidence read from the worker pane. - Any `cmux send -- ""` action is tied to a verified target pane from `cmux --json tree`. - The final ledger states whether each worker is done, blocked, still running, or needs human review, plus the stop reason. #### Failure modes and mitigations - The loop runs without a bound; mitigate by requiring a duration, target time, iteration cap, or default 3-cycle limit before starting. - The Manager answers high-risk questions for a worker; mitigate by only answering simple in-scope blockers and escalating destructive, production, credential, or broad architecture decisions to the human. - The Manager sends a message to the wrong pane; mitigate by rechecking `cmux --json tree` immediately before each `cmux send`. ## Implementation notes - The Manager should inspect with `cmux --json tree` before acting and again before sending to a target pane; stale pane refs are how agents nudge the wrong worker. - Keep worker tasks narrow: one worker for logs, one for source, one for browser/runtime proof is usually better than three agents all editing the same files. - Prefer panes over tab groups for visible parallel work, because hidden tab groups are easy to lose track of during agent-heavy sessions. - Use `cmux read-screen` as evidence. Do not let the Manager summarize worker progress from memory or from optimistic worker claims. - Browser verification should prove live web behavior when the task is a web-app task; for non-browser tasks, terminal logs, test output, and a Manager ledger are stronger proof. - AFK-style loops need an explicit interval and stop condition. Without a bound, the workflow becomes token-burning theater. ## Boundaries and caveats - Do not present CMUX browser automation skills as a taught this workflow workflow; use browser proof only where a web app needs runtime verification. - Do not prescribe Claude Code scheduling, Codex Mobile, tmux migration, Zellij, or Vault search as implementation requirements for this playbook. - Do not invent CMUX flags beyond the verified command map. - Do not turn workers loose on unrelated broad refactors; the taught pattern is Manager-led orchestration with narrow worker assignments. - Do not run unbounded AFK loops or let a Manager approve risky production, credential, billing, deployment, or destructive actions without the human. ## Agent reference map ### Existing CMUX manager/worker prompt Use this as the copy-paste baseline for Manager behavior, worker delegation, live-state inspection, and the human-led planning guardrail. [Open reference](/topics/foundations-cmux-orchestrate-playbook/) ### CMUX orchestration skill Use this as the reusable Codex skill contract for triggering CMUX orchestration only inside a CMUX workspace and for staying on the real command surface. [Open reference](/topics/foundations-cmux-orchestrate-playbook/) ### Verified CMUX CLI command map Use this to avoid invented flags and to keep pane creation, state inspection, send/read, focus, and tab naming grounded in the verified commands. [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ### Lesson 02 validated references Use this as the taught-concept source for agent-first tooling, natural-language terminal orchestration, cross-pane reading, manager-worker topology, and bounded AFK loops. [Open reference](/topics/foundations-manager-worker-orchestration/) ### Lesson 02 validation notes Use this to stay inside the transcript-validated boundary and avoid reintroducing removed or merely mentioned tools as taught workflows. [Open reference](/topics/foundations-manager-worker-orchestration/) ## Command reference These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs. These are REAL commands. Do not invent flags. ## Panes / layout - `cmux new-split [flags]` — split from the focused surface in a direction. - `cmux new-pane [flags]` — create a pane with terminal or browser content. - `cmux new-workspace [--name ] [--description <text>] [--cwd <path>] [--command <text>] [--layout <json>] [--focus <true|false>]` - `cmux focus-pane [--pane <id|ref> | <ref>]` - `cmux list-panes` — enumerate panes in a workspace. - `cmux tree [flags]` / `cmux --json tree` — print the window/workspace/pane/surface tree (JSON with `--json`). Live `cmux --json tree` returns an object with `active` (focused pane/surface refs, `is_browser_surface`, etc.) plus the full tree — this is the "CMUX state as JSON" / "inspect" the workflow uses (focused pane, refs, working directory). ## Reading / sending - `cmux read-screen [flags]` — read terminal text from a surface back as context. - `cmux send [flags] -- <text>` — send text to a terminal surface. - `cmux send-key <key>` — send one key. ## Tabs / markdown / notifications - `cmux rename-tab "<name>"` (compat wrapper for `cmux tab-action rename`). - `cmux markdown open <path> [--direction <left|right|up|down>] [--focus <true|false>]` — open a markdown file in a formatted viewer panel with **live file watching** (auto-refresh). This is the "live Markdown side pane" tracker. - `cmux notify` — send a notification to a workspace/surface. - `cmux events` — stream reconnectable cmux events as newline-delimited JSON (agent-readable telemetry / audit log). ## Global options (before the command) `--socket <path>`, `--password <value>`, `--json`, `--id-format <refs|uuids|both>`, `--window <id|ref|index>`. Handles accept UUIDs, refs like `workspace:2` / `pane:89` / `surface:126`, and indexes. Reference ID: foundations-cmux-orchestrate-playbook Topic: Execution Sources: - [Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-02.html) --- # Control agent lifecycle with hooks and context hygiene > Original source pages and recordings require authorized access. The full article text here is public. Start with context hygiene: compacting or forking long conversations so the next branch focuses only on what matters, such as a specific test file or active goal. John then teaches the three core hook moments in an agent loop: User Prompt, Tool Use, and Stop. From there, he explains the Ralph Loop, demonstrates a #human User Prompt hook that opens a live progress dashboard, and argues that plugins are the better tool when you want deterministic control instead of relying on a skill description being inferred correctly. ## Working outcomes - Manage context with compaction and conversation forking - Wire user-prompt, tool-use, and stop hooks into your workflow - Choose between skills and plugins and run a Ralph loop ## Concepts and consequences ### Compaction and conversation forking Compaction is the move of shrinking a long conversation down to the pieces that still matter. John framed it as useful when you fork a conversation and want the new branch to focus on one topic, like a specific test file, instead of carrying unrelated history forward. The practical benefits he called out were fewer tokens, faster runs, lower budget/quota pressure, and a clearer sense of what the agent is working on. **Why it matters:** Long conversations can carry a lot of irrelevant context. Forking plus focused compaction gives the next session a cleaner starting point. ### The big three hooks John breaks the agent loop into three core events: User Prompt, Tool Use, and Stop. User Prompt fires when you type something and submit it, Tool Use fires when a tool runs, and Stop fires when the conversation would normally end and wait for you. These are the main places where a hook can do something with the session. **Why it matters:** Once you understand these three events, plugins stop feeling mysterious. They become small programs attached to predictable moments in the agent lifecycle. ### The Ralph Loop The Ralph Loop is John's shorthand for a Stop-hook-driven loop. When the agent tries to stop, the hook can tell the harness not to stop yet, look back at what the user originally asked for, and keep working until a condition is met. John described this as the basic idea behind goal-style sessions. **Why it matters:** This matters when you want an agent to keep working on a goal instead of handing control back after one assistant turn. ### Skills versus plugins John contrasts skills with plugins as a difference between context-based guidance and deterministic control. Skills put descriptions into the model's context so the agent can infer when and how to use them. Plugins can hook into events and enforce behavior, including starting or stopping things, allowing or disallowing actions, or calling specific tools. **Why it matters:** For workflows you want to enforce, John recommends reaching for a plugin with hooks instead of trying to make skill instructions clearer and clearer. ### Custom grammar triggers A custom grammar trigger is a small token like #human, #toolsmith, #memory, or #search that a User Prompt hook can detect before the agent proceeds. John likes this because it keeps Codex vanilla by default and only loads the specific system, plugin, skill, or context bundle when he explicitly asks for it. **Why it matters:** This gives you a clean way to personalize sessions without polluting every conversation with skills or context the task does not need. ## Reference tools and resources ### Codex Plugins documentation The main OpenAI developer documentation John opened for Codex plugins. **Use when:** Use it when you want to understand how plugins package and install things like hooks and skills. [Reference](https://developers.openai.com/codex/plugins) ### Codex Build Plugins guide The OpenAI guide John showed as a starting point for creating plugin projects. **Use when:** Use it as source material when asking an agent to generate a documented starter plugin or hook example. [Reference](https://developers.openai.com/codex/plugins/build) ### Codex Hooks documentation The OpenAI reference John opened for hook behavior. **Use when:** Use it when learning what User Prompt, Tool Use, and Stop hooks can do, or when feeding hook docs to an agent so it can build an example. [Reference](https://developers.openai.com/codex/hooks) ### Better Plugins repository John Lindquist's prototype repository containing examples such as human-view, Gemini Video, and Toolsmith. **Use when:** Use it as a reference repo for real plugin patterns, while remembering that John described this work as prototype-stage and personally configured. [Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins) ### human-view plugin A Better Plugins example that activates with #human and opens a live browser dashboard showing task progress and tool-call activity. **Use when:** Reach for this when you want to study the #human pattern John demonstrated: a User Prompt hook that starts a live progress view for a session. [Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins/human-view) ### toolsmith plugin A Better Plugins example John described as recording tool calls and conversation activity so you can query the log for workflow improvements. **Use when:** Reach for this when you want to study how recorded tool use could reveal missing scripts, missing tools, or repeatable workflow improvements. [Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins/toolsmith) ### gemini-video plugin A Better Plugins example John described as detecting a dragged-in .mp4 file path and sending it through Gemini scripts so the video can be parsed into the conversation. **Use when:** Use it as an example of a plugin that reacts to a file path, but expect to adapt it because John said it was configured for his own setup. [Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins/gemini-video) ### MarkSnip Chrome extension A browser extension John used to copy documentation pages into Markdown. **Use when:** Use it when you want to paste documentation into an agent directly instead of spending an extra tool call having the agent scrape the page. [Reference](https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm) ## Recommendations and best practices - When a session gets long, fork it and compact around the specific thing you want next, such as the test file or active goal, instead of continuing with unrelated history. - Use User Prompt, Tool Use, and Stop as your basic mental model for plugin design: decide which lifecycle moment actually needs intervention. - Use the Codex plugin and hook docs as source material, then ask an agent to build a fully documented example and review or test what it creates. - Use a Stop hook for Ralph Loop-style continuation when you can define the condition the agent should keep working toward. - Prefer a plugin over a skill when the workflow must be enforced, such as starting or stopping something, allowing or disallowing actions, or calling a specific tool. - Keep default sessions as vanilla as possible, then use explicit triggers like #human, #toolsmith, #memory, or #search to opt into extra behavior only when the task needs it. - Treat John's Better Plugins repo as prototype reference material, not as polished drop-in infrastructure for every machine. ## Practice and acceptance criteria Practice trimming noisy context, recognizing the main hook events, and choosing plugins when you need deterministic workflows instead of fuzzy skill behavior. ### Checklist 1. Pick one recurring workflow you currently handle with a long prompt, skill, or repeated manual instruction. 2. Decide which lifecycle moment actually needs control: User Prompt for triggers, Tool Use for tools, or Stop for continuation. 3. Use the Codex plugin and hook docs as source material and ask an agent to create a documented starter plugin or hook example. 4. Add a custom trigger such as #review, #human, or #toolsmith to a User Prompt hook, and confirm normal prompts do not activate the extra behavior. 5. Try a Stop-hook/Ralph Loop pattern only when you can state the condition the agent should keep working toward. 6. Review a Toolsmith-style record of tool calls and look for one missing script, missing tool, or repeated workflow worth improving. 7. Keep the default session minimal, then load context bundles, skills, or plugin behavior only when your custom trigger calls for them. ### Compact-and-Fork Drill **Difficulty:** Easy Take a messy or long Codex conversation, fork it, then write a compact handoff that keeps only the active goal, relevant files, failing test, and next action. **Done when:** A new session can understand the focused task without needing unrelated earlier discussion. ### Custom Trigger Plugin **Difficulty:** Medium Build or ask an agent to build a small plugin that watches for #myflow in the User Prompt hook and conditionally loads a short workflow instruction or helper behavior. **Done when:** Prompts with #myflow activate the behavior, while normal prompts run without the extra context or behavior. ### Toolsmith-Style Review **Difficulty:** Medium Prototype or adapt a workflow that records tool calls, then review or query those records for one repeated pattern worth turning into a script, tool, or plugin. **Done when:** You can point to one workflow improvement based on actual repeated agent behavior. ### Ralph Loop Prototype **Difficulty:** Hard Ask an agent to help create a Stop-hook plugin for a toy task that tells the agent to continue working until a specific condition is met. **Done when:** The agent continues past an attempted stop, works toward the original task, and exits once the condition is satisfied. ## Questions to test understanding ### A Codex session has grown long and now contains several unrelated debugging trails. What is the best next move before asking the agent to focus on one failing test file? - **A.** Fork the conversation and compact the new branch around the relevant test file and current goal. - **B.** Keep the same conversation open so the model has maximum history available. - **C.** Paste the entire transcript into a new prompt and ask the model to remember everything. - **D.** Convert the whole conversation into a global skill so it loads in every future session. **Answer: A.** Forking plus focused compaction preserves what matters while dropping unrelated noise. John called out fewer tokens, faster runs, lower budget pressure, and clearer focus as the practical benefits. ### Which lifecycle hook is the natural place to detect a custom trigger like #human or #toolsmith before the agent starts working? - **A.** Stop hook - **B.** Tool Use hook - **C.** User Prompt hook - **D.** Compaction hook **Answer: C.** The User Prompt hook fires when the user submits text, so it can parse custom grammar before the agent proceeds. That is the pattern John demonstrated with #human. ### You want every tool call in a session to be recorded so you can later ask what scripts, tools, or workflow improvements might be missing. Should this be a skill or a plugin? - **A.** A skill, because the model can decide when logging feels appropriate. - **B.** A plugin with a Tool Use hook, because Tool Use is the lifecycle moment around tool calls. - **C.** A Stop hook only, because tool activity should be recorded after the task is over. - **D.** A compaction instruction, because logging is mainly about shrinking context. **Answer: B.** John identified Tool Use as the hook event that fires when tools run, and described Toolsmith as recording tool calls so you can query them for workflow improvements. ### What makes the Ralph Loop different from simply prompting the model to 'keep going until done'? - **A.** It uses a Stop hook to structurally continue the session when the agent would normally hand control back. - **B.** It loads every available skill so the model has more options. - **C.** It prevents the agent from using tools until the user approves each command. - **D.** It replaces compaction with a larger context window. **Answer: A.** John described the Ralph Loop as a Stop-hook pattern: when the agent tries to stop, the hook tells it to look back at the original task and keep working until a condition is met. ### Why does John like using custom # triggers instead of loading every repeatable workflow as a default skill? - **A.** They keep Codex vanilla by default and load only the specific system or context bundle when requested. - **B.** They make compaction unnecessary for long conversations. - **C.** They prevent the agent from using tools. - **D.** They replace the need to read plugin or hook documentation. **Answer: A.** John's preference is to avoid polluting every session with skill descriptions or context the task does not need. A trigger like #human or #toolsmith lets him opt into extra behavior only for sessions that need it. ## Reflection prompts - Which workflows are you currently handling as skills or long prompts but actually need deterministic plugin control? - Where are you loading skills or context by default that could instead be loaded only through a # trigger? - What is one task where a Ralph Loop would help, and what exact condition would tell it to stop? ## Further applications 1. Ask an agent to build a fully documented Hello World plugin or hook example from the Codex plugin and hook docs, then read through the result and ask follow-up questions. 2. Convert one recurring skill-like workflow into a #your-trigger plugin that conditionally loads the behavior only when the trigger appears. 3. Study the human-view pattern as a concrete example of #human activating a live dashboard that tracks progress and tool-call activity. 4. Study the Toolsmith pattern as an example of recording tool calls and querying that record for workflow improvements. 5. Study the Gemini Video pattern as an example of detecting an .mp4 file path and routing it through a video-processing script, while expecting to adapt it for your own setup. ## Applied exercises Exercise: Transition from Soft Skills to Deterministic Plugins **Objective:** Developers will replace a high-context prompt structure or an inference-based agent "Skill" with a low-level programmatic Plugin. **Requirements:** Identify a repeatable task workflow that you currently execute by passing detailed text instructions to an LLM skill.Instead of using a skill, create a custom Codex Plugin structure utilizing a hooks.json mapping configuration.Configure a custom syntax grammar key (e.g., #YourWorkflowName) handled inside the User Prompt hook listener.Write a Python script mapping to ensure that when this character trigger is registered, specific environmental checks, system rules, or tool executions are programmatically enforced rather than relying on model inferences. ## Questions and answers ### Do you have any ideas on how to create levers for agents so they can do big data stuff without having all the data in their context? John explicitly says he is not an expert in big-data engineering integrations and does not offer a validated big-data recipe. The adjacent hook discussion offers a structural principle: keep large data in external processes; pass references or concise execution metrics through tool hooks rather than loading everything into active context. This is not a demonstrated big-data integration. ### i saw you use /compact, when do you use this skill? what is the skill? compact is a method used to compress long conversations down to essential details. John explains that he historically ran single conversations straight through to completion and then closed them out. However, automated /goal execution runs can alter this workflow because long tasks cycle through several automated compactions while running unattended to remain safely inside the token window limit without blowing through operational limits. ### are you organizing your general knowledge somehow? pulling in meeting transcripts, emails, conversations with agents, and organizing them in such a way to retrieve them later as needed, agents having access to all, but perhaps synthesizing (basic memories) and mining for insights... i saw earlier you use pieces mcp, bee.computer, etc... John details a workflow using custom syntax triggers like #memory or #search. Rather than feeding a massive knowledge graph into every agent session globally, he prefers keeping his default Codex instances as vanilla as possible. He recommends implementing custom grammar listeners inside the user prompt hooks to dynamically grab and resolve target context bundles exactly when explicitly requested. ### What are the basic lifecycle events in an agent harness? John steps back at 03:14:32 to lay down fundamental context setting. He explicitly abstracts the core pipeline events of any agent harness down to the basic three hooks: User Prompt, Tool Use, and Stop Hook, providing a baseline architecture breakdown before showing any more complex code configurations. ### John do you subscribe to this idea that the context window has a smart zone (first 100k tokens) and dumb zone and to try and keep the work in the smart zone? If so how do you keep the /goal sessions in the smart zone? I have noticed long running goals really chew through tokens which makes me think there might be context management sacrifices being made to unlock long running tasks. John acknowledges that long-running automated goals change how context degradation is handled. Because long sessions continuously consume heavy token counts, using /goal strategies forces systems to use progressive automated compaction steps over their lifecycles. To maintain high accuracy without model degradation, he builds custom plugins that use explicit Python runtime rules to tightly control context instead of letting the agent continuously guess its state. ## Operational playbooks - [Ralph Loop stop-hook continuation](/topics/foundations-ralph-loop-playbook/) - [Codex Primitive Field Guide](/topics/foundations-codex-primitives-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-07.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-07.html) ### Visual reference index - [03:12:05](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-1): Dark terminal/conversation context during the post-lunch compaction discussion. - [03:14:45](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-2): Terminal prompt area during the setup for explaining user prompt, tool use, and stop hooks. - [03:17:15](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-3): Terminal/file-list view before the browser documentation walkthrough fully appears. - [03:18:55](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-4): OpenAI Developers Hooks documentation page with the MarkSnip extension overlay visible. - [03:20:45](https://codex-workshop-followup.pages.dev/lesson-07.html): Terminal view rendering generated hook/project instructions and script text. - [03:22:20](https://codex-workshop-followup.pages.dev/lesson-07.html): Terminal prompt context while preparing the custom #human hook trigger example. - [03:23:15](https://codex-workshop-followup.pages.dev/lesson-07.html): Split workspace with terminal logs on the left and a live typing-game dashboard in the browser. - [03:24:18](https://codex-workshop-followup.pages.dev/lesson-07.html): GitHub repository view for johnlindquist/better-plugins showing plugin folders. - [03:30:15](https://codex-workshop-followup.pages.dev/lesson-07.html): GitHub repository view inside better-plugins, showing individual plugin/script files. Reference ID: foundations-hooks-and-context-hygiene Topic: Execution Sources: - [Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-07.html) --- # Coordinate agents with a manager and worker panes > Original source pages and recordings require authorized access. The full article text here is public. The practice is shifting from manually babysitting one terminal to using CMUX as an agent-first terminal workspace. John shows that agents can read CMUX's command surface, open and arrange panes from natural language, name tabs, resume old conversations from the Vault, jump to panes with unread activity, and inspect what other panes have said or done. He also describes his preferred manager-worker pattern: he talks mostly to one Manager pane, and that pane can open or check worker panes. ## Working outcomes - Adopt an agent-first mindset and the manager-worker topology - Drive CMUX terminal layouts with natural language - Set up AFK automation loops that keep working while you don't ## Concepts and consequences ### Agent-first tooling John frames modern dev tools around whether they are open source and agent-first: tools with CLIs, APIs, or other surfaces agents can interact with and control. His point is that you no longer need to personally memorize every flag or shortcut when the agent can inspect the interface and use it. **Why it matters:** Agent-first tools let your instructions turn into real tool actions: opening panes, running commands, checking status, or operating a CLI. Tools without programmable surfaces put more mechanical work back on the human. ### PackX for file collation John shows PackX, a tool he built to collate a bunch of files into a single file. He explains that it supports file globs, patterns, and options, and that he typically lets the agent learn and use the CLI flags instead of using the tool manually. **Why it matters:** It is an example of agent-first thinking: give the agent a useful CLI tool and let it handle the exact flags and patterns needed for the current context. ### Natural language terminal orchestration John demonstrates asking CMUX to open a new pane to the right, then asking it to open five more panes, run different safe commands in them, and space everything evenly. The agent uses the CMUX CLI surface to translate natural language into layout and terminal actions. **Why it matters:** This makes the terminal workspace programmable. You can describe the workspace you need instead of manually arranging panes and remembering multiplexer commands. ### Vault and resumed conversations John demonstrates the CMUX right sidebar with Files, Find, and Vault. In the Vault, he can look through past conversations and resume one in a new tab, though he notes the feature is still in development and search is not great yet. **Why it matters:** Resuming old context is useful when you lose or want to continue a previous conversation without manually reconstructing what happened. ### Unread notification jumping John shows that CMUX can surface notifications from sessions and that Cmd+Shift+U jumps to unread activity. He uses it to jump to a pane where a session had stopped. **Why it matters:** When many sessions are running, jumping to the pane that needs attention is faster than manually scanning every pane. ### Cross-pane context reading John demonstrates that CMUX can read the contents of other tabs or panes by echoing text in one tab and asking another what that tab said. He explains that agents can check other panes, workspaces, recent commands, Git actions, and signs that something needs attention. **Why it matters:** This is what makes multiple panes more than just visual clutter. A main or sibling agent can inspect what is happening elsewhere and summarize it for you. ### Manager-worker topology John describes treating himself as the CEO, one pane as the Manager, and other panes as workers. He tries to talk mainly to the Manager, which can open panes and send workers to investigate, research, or do other tasks. **Why it matters:** A manager pane keeps the human interaction surface smaller while still letting several agents or terminal sessions do work in parallel. ### AFK goal loops John gives an example goal where an agent creates a timestamp, checks other panes every 10 minutes to make sure they are completing their goals, picks the best answer if a pane is blocked by a question, and continues until four hours after the original timestamp. He describes this as an AFK approach where he can set it and walk away. **Why it matters:** Periodic check-ins can keep multiple running sessions moving, but John also says the upfront planning for parallel work is still something to be actively involved in. ## Reference tools and resources ### CMUX An open-source, agent-first terminal workspace John uses to let agents control panes, tabs, workspaces, notifications, and terminal activity through a CLI-driven surface. **Use when:** Use it when you want local agent-driven terminal orchestration: opening panes, arranging layouts, naming tabs, resuming old conversations, jumping to unread sessions, and checking what other panes are doing. [Reference](https://cmux.com/) ### PackX John's file collation utility for packing selected files, globs, and patterns into a single file. **Use when:** Use it when an agent needs to gather a set of files into one context bundle and you would rather have the agent handle the CLI flags and patterns. [Reference](https://www.npmjs.com/package/packx) ### tmux The classic terminal multiplexer that came up when a participant asked whether CMUX is worth trying for someone heavily invested in tmux. **Use when:** Keep tmux in mind if remote session behavior is central to your workflow; John said CMUX does not have all the remote session features he associates with tmux, while his own work is mostly local. search: tmux terminal multiplexer remote sessions ### Claude Code scheduling John mentioned that Claude Code has a scheduling or cron-like feature he wishes Codex had more directly. **Use when:** Think of this as context for the AFK check-in idea, not as a taught setup path in this lesson. search: Claude Code scheduled tasks ### Codex Mobile John briefly shows the Codex app setting for Codex Mobile and says recent changes let phone control work with sessions started in CMUX as long as the app is open. **Use when:** Use it for lightweight control or check-ins from a phone, while recognizing this section only briefly demonstrates where the feature lives and what it enables. search: Codex Mobile app ## Recommendations and best practices - Choose tools that are open source and agent-first, meaning agents can control them through CLIs, APIs, or similar programmable surfaces. - Let agents handle CLI flags and command details when the tool surface is discoverable, as John does with PackX and CMUX. - Use natural language CMUX commands to create panes, arrange the workspace, name tabs, and run safe commands. - Prefer panes over tab groups when you want visible parallel work, because John says tab groups are easy to lose track of. - Use the CMUX Vault to resume old conversations, but remember John called the feature still in development and said its search is not great yet. - Use Cmd+Shift+U to jump to unread activity when a running session stops or needs attention. - For multi-agent work, try a Manager pane that you talk to directly, while worker panes handle investigations, research, or other delegated tasks. - For AFK-style work, use a clear interval and stop condition, and stay actively involved in the upfront planning before parallelizing work. ## Practice and acceptance criteria Practice using CMUX as an agent-controlled terminal workspace: natural language pane control, visible parallel sessions, a manager pane, and periodic check-ins. ### Checklist 1. Open a CMUX workspace. 2. Run or inspect CMUX help so the agent can discover the command surface. 3. Use a natural language command to open a new pane to the right. 4. Ask CMUX to open several more panes, run different safe terminal commands in them, and space the panes evenly. 5. Ask CMUX to name tabs with clear or memorable names. 6. Open the right sidebar with Cmd+Alt+B and locate the Files, Find, and Vault sections. 7. Resume a past conversation from the Vault if one is available. 8. Use Cmd+Shift+U to jump to unread activity from a session that has stopped or needs attention. 9. Echo a short message in one named tab, then ask another pane what that tab said. 10. Create one Manager pane and have it check or summarize what worker panes are doing. ### Natural Language Pane Warmup **Difficulty:** Easy In CMUX, ask the agent to open a new pane to the right. Then ask it to open several more panes, run different safe terminal commands in them, and space the layout evenly. **Done when:** The workspace contains multiple visible panes, each running a harmless command, without you manually arranging every split. ### Vault and Unread Navigation Drill **Difficulty:** Easy Open the right sidebar, find the Vault, and resume a previous conversation in a new tab if one is available. Then use the unread-jump workflow to move to a pane that has activity needing attention. **Done when:** You can explain how to open the sidebar, where the Vault lives, and how Cmd+Shift+U helps you jump to unread activity. ### Manager Checks the Room **Difficulty:** Medium Create one Manager pane and at least one Worker pane. Have the Worker run a safe command such as echo, pwd, or git status. Then ask the Manager to inspect the Worker pane and summarize what it sees. **Done when:** The Manager correctly identifies what happened in the Worker pane and does not invent output that is not visible. ### Small AFK Check-In Goal **Difficulty:** Hard Write a bounded goal for a Manager pane that creates a timestamp, checks other panes at a fixed interval, reports progress, and stops after a defined time window. **Done when:** The goal includes an interval, a clear stop condition, and a reporting instruction, matching the AFK-style pattern John described. ## Questions to test understanding ### What does John mean by agent-first tooling in this lesson? - **A.** Tools that expose CLIs, APIs, or other surfaces agents can inspect and control - **B.** Tools that only work through graphical menus - **C.** Tools that require the human to memorize every shortcut before using them - **D.** Tools that prevent agents from running commands **Answer: A.** John says the tools to look for are open source and agent-first: tools with CLIs, APIs, or other ways agents can interact with and control them. ### What did John demonstrate with CMUX natural language commands? - **A.** Opening and arranging panes, then running different safe commands in them - **B.** Replacing the terminal with a static web dashboard - **C.** Deploying production code from a phone - **D.** Converting every pane into the same shared shell process **Answer: A.** John asked CMUX to open a pane to the right, then to open five more panes, run different safe commands, and space everything evenly. ### What is the role of the Vault feature John showed? - **A.** It stores billing credentials for agents - **B.** It lets John look through past conversations and resume one in a new tab - **C.** It prevents all worker panes from editing files - **D.** It automatically writes tests for every project **Answer: B.** John opened the right sidebar, went to Vault, found past conversations, and resumed one in a new tab. He also noted the feature is still in development. ### In John's manager-worker pattern, what does he try to do? - **A.** Talk mainly to one Manager pane while other panes do delegated work - **B.** Talk to every pane equally at all times - **C.** Avoid opening more than one pane - **D.** Use only phone controls and never the terminal **Answer: A.** John describes himself as the CEO, one pane as the Manager, and other panes as workers. He tries to talk mainly to the Manager. ### Why is cross-pane reading useful in CMUX? - **A.** It lets an agent check what other tabs or panes have said, run, or gotten stuck on - **B.** It guarantees that no two agents can ever conflict - **C.** It removes the need for planning parallel work - **D.** It makes tmux remote persistence unnecessary **Answer: A.** John demonstrated asking one pane what another tab said, then described checking other panes, recent commands, Git actions, summaries, and things needing attention. ### What was John's AFK-style example? - **A.** Check other panes every 10 minutes, answer blocking questions, and continue until four hours after the original timestamp - **B.** Run forever and approve every action automatically - **C.** Rewrite the whole repo every hour - **D.** Let every worker choose unrelated goals without checking in **Answer: A.** John's example was a scheduled goal loop that checks other panes every 10 minutes, picks the best answer when a pane is blocked by a question, and continues for a defined four-hour window. ## Reflection prompts - Which tools in your workflow are agent-first because they expose useful CLIs or APIs? - Where would visible panes help you keep track of parallel work better than hidden tab groups? - What work would you route through a Manager pane, and what work would you still handle directly? - What kind of AFK check-in loop would be useful without replacing the upfront planning you still need to do yourself? ## Further applications 1. Practice opening and arranging CMUX panes with natural language commands such as opening a pane to the right or creating several evenly spaced panes. 2. Try naming tabs with a natural language request, then search for or close specific named tabs. 3. Use the Vault sidebar to find a past conversation and resume it in a new tab. 4. Create a simple manager-worker setup: one Manager pane and one or two worker panes, then ask the Manager to check what the workers have done. 5. Draft a small AFK-style goal that checks other panes at a fixed interval, reports progress, and stops after a defined amount of time. ## Applied exercises ### Exercise: Orchestrating the Manager-Worker Pattern in CMUX * **Objective**: Build an isolated local development grid that relies on a single coordinator agent to direct sub-tasks across multiple child panels without manual human window tiling. * **Setup Steps**: 1. Open a clean workspace inside CMUX. 2. Split your terminal layout using a macro shortcut or natural language step (`! Open a new Pane to the right`). 3. Designate the primary window as your **Manager** shell. 4. Input a structured layout command to the Manager: *"Spawn three sibling panes below. Initialize a clean repository tracker in pane 1, trigger a continuous build diagnostic loop in pane 2, and use pane 3 to monitor local directory storage footprints."* 5. Validate that CMUX correctly partitions the available workspace area, configures separate shell environments, and triggers the independent task sequences cleanly. 6. Verify cross-context capabilities by asking your Manager pane: *"What is the active execution state and output log of your second sibling pane?"* ## Questions and answers ### What’s cmux? Is it like Warp, but less commercial? An open-source, agent-first terminal multiplexer tool. It focuses on providing structural APIs and CLI endpoints that allow background autonomous models to freely control window positioning, manage context structures, and drive active command operations. ### Would you recommend this to a heavily invested tmux user? Yes, but with caveats. CMUX currently lacks some of the robust persistent remote-session features found in traditional Tmux architectures. It is highly optimized for local, agent-orchestrated loops, meaning pure remote workflow users may encounter friction. ### do we have alternative for windows Zellij operates effectively on Windows nodes and natively supports direct agent control integration features. Platform caveat: this was a suggested alternative, not a demonstrated Windows installation. Confirm the supported host environment and any WSL requirement before using it as a team setup recommendation. ### How do you get vault? I missed it Press Cmd+Alt+B to display the right-hand utility sidebar. From there, navigate between Files, Find, and Vault categories using numerical shortcuts 1, 2, and 3. ### Do you need your projects structured a certain way so cmux can run multiple sessions without causing issues with agents stepping on toes? Isolate running server processes cleanly behind the individual terminal tabs that actively consume them. Because CMUX manages distinct windows independently, models can run safely in parallel and can programmatically read across sibling history buffers to check on processing states without corrupting cross-project environments. ### Have ways in which you manage to move from one to the other, or you fork, or you come back. And then maybe a follow-up question is, I saw you post something about one agent controlling another agent through... a graphical, or for browser, accessibility controls, and I'm just curious if you have any... of these other ways in which you manage between agents? John relies on the manual 'codex fork' option to branch conversations from selected history checkpoints. He uses a Manager-Worker Pattern: a single primary terminal pane is his designated 'Manager' (his sole point of interaction), and that manager model script handles splitting sub-panes to deploy worker agents. For browser environments, toolsets leverage accessibility tree paths to parse content, but within CMUX, the native command-line interface endpoints are fast and descriptive enough that parsing raw accessibility trees isn't necessary. ### Codex implement /tree when? Unanswered/Deferred. John does not address this question directly in the transcript; during this window, he is answering a verbal question from a developer regarding agent handoffs and manager topologies. The nearest tool comparison occurs at [00:45:55] where John discusses wanting Claude Code's cron scheduling features inside Codex. ## Operational playbooks - [Command a CMUX manager/worker layout](/topics/foundations-cmux-orchestrate-playbook/) - [CMUX Orchestration Field Guide](/topics/foundations-cmux-orchestration-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-02.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-02.html) ### Visual reference index - [00:31:16](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-1): Screen showing the NPM home tracking page details for the custom tool package packx. - [00:33:55](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-2): The initial unified CMUX terminal layout before invoking layout splits. - [00:34:19](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-3): Visual proof of a new vertical split created by typing ! Open a new Pane to the right. - [00:34:59](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-4): The workspace grid re-tiling into a complex multi-pane array following the voice-dictated instruction to spawn 5 distinct command loops. - [00:37:06](https://codex-workshop-followup.pages.dev/lesson-02.html): The expanded Vault interface view appearing inside the right sidebar, showing past interaction history blocks. - [00:37:33](https://codex-workshop-followup.pages.dev/lesson-02.html): Right-click sub-menu interaction executing the 'Resume a new tab' instruction to revive old log states. - [00:39:29](https://codex-workshop-followup.pages.dev/lesson-02.html): The UI snapping focus directly to an isolated corner box via Cmd+Shift+U immediately following the termination of a background Codex Demons session. - [00:41:00](https://codex-workshop-followup.pages.dev/lesson-02.html): Multiple workspace tab configurations explicitly showing custom names generated by the agent (Zendaya, Oprah, Tom Hanks). - [00:47:53](https://codex-workshop-followup.pages.dev/lesson-02.html): Input prompt displaying John's complete text for the 4-hour cyclical /goal background monitoring loop. - [00:51:58](https://codex-workshop-followup.pages.dev/lesson-02.html): Close-up highlighting the position of the Codex Mobile icon within the master system settings pane layout. Reference ID: foundations-manager-worker-orchestration Topic: Execution Sources: - [Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-02.html) --- # Install and inspect dash-prefix Imp routing These files show a common local setup for dash-prefix Imp routing. They are examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing. ## What This Adds ```text -<imp> task -> foreground route -> hook adds Imp command/path/description/task/cwd -> main Codex turn continues --<imp> task -> fork route -> hook opens a cmux pane -> hook starts `codex fork <session> -- '-<imp> task'` -> hook blocks the current prompt ``` ## Install Targets ```text ~/.codex/hooks/imp-user-prompt-submit.py ~/.codex/hooks.json ~/.local/bin/cmux-run-surface ``` ## Files In This Directory | File | Purpose | | --- | --- | | `imp-user-prompt-submit.py.template` | UserPromptSubmit hook example for dash-prefix Imp routing | | `hooks.json.example` | minimal hook registration example | | `cmux-run-surface.example` | helper contract for opening a focused cmux pane and printing a receipt | | `cmux-codex-session-registry.py.example` | redacted contract for resolving a cmux surface id to a Codex session id | ## Trust Boundary Hooks run during prompt submission. They can block prompts, launch local commands, open cmux panes, and write logs. Before installing: ```bash python3 -m py_compile hooks/imp-user-prompt-submit.py.template python3 -m json.tool hooks/hooks.json.example >/dev/null rg -n "<your-secret-patterns>" hooks ``` ## Setup Steps Copy only after review: ```bash mkdir -p ~/.codex/hooks ~/.local/bin cp hooks/imp-user-prompt-submit.py.template ~/.codex/hooks/imp-user-prompt-submit.py cp hooks/cmux-run-surface.example ~/.local/bin/cmux-run-surface chmod +x ~/.codex/hooks/imp-user-prompt-submit.py ~/.local/bin/cmux-run-surface ``` Merge `hooks/hooks.json.example` into `~/.codex/hooks.json`. Do not overwrite an existing hooks file blindly. If you use helpers that fork the focused Codex conversation from a cmux surface, review `hooks/cmux-codex-session-registry.py.example` and install an equivalent registry implementation at: ```text ~/.codex/hooks/cmux-codex-session-registry.py ``` ## Verify Single-Dash Route Inside a Codex session with the hook enabled: ```text -gmail draft a short email about this conversation ``` Expected: - main prompt continues - hook context resolves `imp-gmail` - hook context includes executable path, description, task text, and cwd - main agent does not rediscover the Imp with `which`, `where`, `find`, or broad search ## Verify Double-Dash Fork Route Inside a Codex session with cmux available: ```text --gmail draft a short email about this conversation ``` Expected: - current prompt blocks - new cmux pane opens - fork receives normalized prompt `-gmail draft a short email about this conversation` - block message includes workspace, pane, surface, and window - block message includes read-screen, top, and focus-pane commands ## Inspect A Forked Session Use the ids printed by the hook: ```bash cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80 cmux top --workspace workspace:<id> --processes --flat --format tsv cmux focus-pane --workspace workspace:<id> --pane pane:<id> ``` ## If It Goes Wrong Check the roster and health: ```bash imp -l imp --which "your task" imps doctor ``` Check cmux: ```bash cmux rpc workspace.current command -v cmux-run-surface tail -n 40 ~/Library/Logs/cmux-run-surface.log ``` Check hook output: ```bash tail -n 20 ~/.codex/logs/imp-user-prompt-submit.jsonl ``` Do not route dash-prefix fork prompts through helpers that create a fork id and then resume it with the dash-starting prompt. A prompt like `-gmail ...` can be parsed as options. Use direct `codex fork <source-session> -- '-gmail ...'`. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-imp-hook-setup Topic: Execution Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Isolated Codex daemon profile playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers constantly repeat narrow CLI work around local dev servers, deploy previews, browser QA, GitHub checks, and framework tooling. An isolated Codex daemon profile turns one repetitive tool workflow into a cheap, warm, low-context helper instead of dragging a full general agent through every small task. [Core principles](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Copy-paste workflow **When to use:** When a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm agent instead of a full general agent. This wraps one CLI in a single-purpose Codex SDK profile with a tight context ceiling. ### Copy-paste prompt ```text You are my coding agent. Generate a new isolated "pro-<TOOL>" Codex daemon profile for the <TOOL> CLI, following the codex-daemons pattern. The point is a cheap, fast, low-context warm agent that does ONE thing — target ~6-10K input tokens. 1. Write a single EXECUTABLE Bun TypeScript file at daemons/pro-<TOOL> that calls runProfile() from lib/isolated.ts. Use this prompt shape inside developerInstructions: ## Operating rule -> run <TOOL> via exec_command before any final answer; never answer from memory ## Command map -> KEYWORD -> <TOOL> COMMAND (e.g. status -> <TOOL> status; help -> <TOOL> --help) ## Workflow -> narrowest read-only command first; mutate only when target+action are explicit; on usage error run --help then retry once ## Command rules -> use only <TOOL>; no web, no images, no file edits unless explicitly asked ## Output -> be terse; report what you found/changed Keep the command map LITERAL — do not dump --help text. Use a low-reasoning model (reasoningEffort default "low"; default model gpt-5.3-codex-spark). 2. The isolation is applied by runProfile() — it sets: base_instructions replaced, developer_instructions custom, skills.include_instructions=false, include_apps_instructions=false, include_environment_context=false, include_permissions_instructions=false, memories.use_memories=false, mcp_servers={}, web_search="disabled", features {plugins, apps, image_generation, tool_search, tool_suggest} all false (features.apps=false alone saves ~14K tokens), CODEX_HOME redirected to a disposable /tmp dir, and auth.json symlinked from real ~/.codex so token refreshes propagate. 3. After generating, run these steps: chmod +x daemons/pro-<TOOL> bun daemons/pro-<TOOL> --help # smoke test # add daemons/pro-<TOOL> to package.json "bin", then: bun link # put it on PATH Prereqs: Bun runtime; @openai/codex-sdk; an authenticated @openai/codex CLI. ``` ### How it works - A profile is a single executable Bun TS file using `runProfile()` from `lib/isolated.ts`, with the Oracle-tuned prompt shape: Operating rule -> Command map -> Workflow -> Command rules -> Output. - The context ceiling comes from real isolation keys: `base_instructions` replaced, custom `developer_instructions`, `skills.include_instructions=false`, apps/environment/permissions instructions off, `memories.use_memories=false`, `mcp_servers={}`, `web_search="disabled"`, and `features` (plugins/apps/image_generation/tool_search/tool_suggest) all false — `features.apps=false` alone saves ~14K tokens. - `CODEX_HOME` is redirected to a disposable `/tmp` dir and `auth.json` is symlinked from real `~/.codex` so token refreshes propagate. - Use a low-reasoning model and keep prompts literal (command map over dumping `--help`); target ~6-10K input tokens (default full config is ~22K). - After-generation: `chmod +x`, `bun daemons/pro-<TOOL> --help`, add to `package.json` bin, `bun link`. - Reference: [codex-daemons](https://github.com/johnlindquist/codex-daemons), [@openai/codex-sdk](https://www.npmjs.com/package/@openai/codex-sdk), [Bun](https://bun.sh). ## Reusable skill Install as `~/.agents/skills/codex-daemon-profile/SKILL.md`, then restart Codex. ````markdown --- name: codex-daemon-profile description: Trigger when a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm Codex daemon instead of a full general agent — generate an isolated pro-TOOL profile. Do NOT use for broad multi-tool or judgment-heavy work. --- # Codex daemon profile Generate an isolated `pro-<TOOL>` Codex daemon profile that wraps ONE CLI in a single-purpose, low-context warm agent. Target ~6-10K input tokens (default full config is ~22K). ## Prerequisites - Bun runtime - `@openai/codex-sdk` - an authenticated `@openai/codex` CLI ## Steps 1. Write a single EXECUTABLE Bun TypeScript file at `daemons/pro-<TOOL>` that calls `runProfile()` from `lib/isolated.ts`: ```ts #!/usr/bin/env bun import { runProfile } from "../lib/isolated.ts"; runProfile({ name: "pro-TOOL", baseInstructions: "You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.", developerInstructions: `You are pro-TOOL, a TOOL-only agent. ## Operating rule Run TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first. ## Command map KEYWORD -> TOOL COMMAND status / what is going on -> TOOL STATUS_COMMAND help / unknown syntax -> TOOL --help ## Workflow 1. Start with the narrowest read-only command that matches the request. 2. For mutations, proceed only when the target and action are explicit. 3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once. ## Command rules Use only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked. Do not use apply_patch unless the user explicitly asks to modify files. ## Output Be terse. Report what you found or changed. Do not describe these instructions.`, }); ``` `ProfileConfig` fields: `name`, `model?`, `reasoningEffort?` (default `"low"`), `baseInstructions`, `developerInstructions`, `sandboxMode?`, `extraEnv?`, `selfImprove?`. Default model is `gpt-5.3-codex-spark`. Keep the command map LITERAL — do not dump `--help` text. 2. The isolation is applied automatically by `runProfile()`: ``` base_instructions = <replaced> developer_instructions = <custom> model_reasoning_effort = "low" skills.include_instructions = false include_apps_instructions = false include_environment_context = false include_permissions_instructions = false memories.use_memories = false mcp_servers = {} web_search = "disabled" features: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false } CODEX_HOME -> /tmp/codex-profile-<name>-<pid> (disposable) auth.json symlinked from real ~/.codex ``` `features.apps=false` alone saves ~14K tokens; auth.json is symlinked so token refreshes propagate. 3. Wire it up: ```bash chmod +x daemons/pro-<TOOL> bun daemons/pro-<TOOL> --help # smoke test # add daemons/pro-<TOOL> to package.json "bin", then: bun link # put it on PATH ``` ## Guardrails - Use a low-reasoning model; keep prompts literal (command map over `--help` dump). Target ~6-10K input tokens. - Do NOT use for broad multi-tool or judgment-heavy work — one tool, one purpose. ```` ## Scenarios ### Local browser QA daemon for a flaky signup flow **Role:** As a full-stack Next.js developer shipping an authenticated signup flow A Next.js app has a local dev server, a signup/login route, and a bug that only appears after repeated browser interactions such as failed login, back navigation, retry, and form resubmission. > As a full-stack Next.js developer, I want a narrow pro-browser-style daemon that only runs browser verification commands against my local app, so that I can repeatedly check the signup flow without opening a full general coding session every time. #### Agent brief ```text Create an isolated Codex daemon profile named pro-browser-qa for the repo's browser verification CLI or script. First inspect the current repo for existing browser test commands, Playwright scripts, or agent-browser usage; do not invent a new stack if one already exists. Write a single executable Bun TypeScript file at daemons/pro-browser-qa that calls runProfile() from lib/isolated.ts. Use the developerInstructions shape: Operating rule, Command map, Workflow, Command rules, Output. The operating rule must require running the browser QA command through exec_command before any final answer. The command map should include only the local commands this repo actually has, such as dev server health check, run signup flow, run login flow, capture console output, capture screenshot, and help. Keep the map literal; do not paste full --help output. Mutations are not allowed: this daemon verifies and reports only. After creating it, run chmod +x daemons/pro-browser-qa, run bun daemons/pro-browser-qa --help, add it to package.json bin if the repo uses that pattern, and run bun link. Expected output: a terse report with command run, route tested, pass/fail, browser evidence path, console errors, and next action. ``` #### Implementation references [Open reference](/topics/foundations-daemon-profile-playbook/) [Open reference](/topics/foundations-daemon-profile-playbook/) [Open reference](/topics/foundations-daemon-profile-playbook/#command-reference) ```text daemons/pro-<TOOL> ``` ```text lib/isolated.ts ``` ```text package.json ``` ```text chmod +x daemons/pro-browser-qa ``` ```text bun daemons/pro-browser-qa --help ``` ```text bun link ``` #### Browser verification Use a local browser verification move because this is a browser-visible bug: start the app with the repo's dev command, then have the daemon run the existing browser script or agent-browser-style flow to snapshot the signup page, fill the email/password fields, click submit, navigate back, retry, and collect screenshot plus console output. If CMUX is available, open the app in a browser pane and keep the daemon terminal visible beside it. #### Definition of done - daemons/pro-browser-qa exists, is executable, and calls runProfile() from lib/isolated.ts - bun daemons/pro-browser-qa --help runs without crashing - The profile prompt has Operating rule, Command map, Workflow, Command rules, and Output sections - The daemon performs read-only browser verification before answering - A verification receipt includes tested URL, exact command, pass/fail, screenshot or trace path, console errors, and any failed selector or step - package.json bin and bun link are updated only if the repo uses that executable profile pattern #### Failure modes and mitigations - Mistake: the agent builds a broad browser-and-code-editing assistant. Mitigation: keep this daemon browser-QA-only, no file edits unless explicitly requested, and no web browsing beyond the local app. - Mistake: the daemon answers from memory or source inspection without running the browser flow. Mitigation: the operating rule must require exec_command first and the final answer must name the command and artifact path. - Mistake: the profile dumps full Playwright or tool help into developerInstructions. Mitigation: use a curated keyword-to-command map and fall back to --help only on syntax errors. - Mistake: authenticated flow assumes normal browser cookies exist. Mitigation: script login/setup explicitly or use a seeded test account path documented in the repo. ### Preview deployment triage daemon **Role:** As a frontend lead reviewing preview builds before merge A pull request deploys a preview URL, but every review requires the same narrow checks: list the current deployment, inspect status, open the preview route, confirm key pages render, and summarize only the blocking issues. > As a frontend lead, I want a pro-deploy-check daemon around my deployment CLI, so that preview triage is fast, repeatable, and limited to deployment status plus browser proof instead of turning into a broad coding session. #### Agent brief ```text Create an isolated Codex daemon profile named pro-deploy-check for the repo's deployment CLI or existing preview-check script. Inspect package.json and repo scripts first. If the repo already uses a specific deploy CLI, wrap that one CLI only. Write daemons/pro-deploy-check as a single executable Bun TypeScript file using runProfile() from lib/isolated.ts. The daemon must start with the narrowest read-only command: deployment status or preview URL discovery. The command map should cover status, current preview, logs, inspect URL, and help, using exact repo commands. For mutations, require explicit target and action; default to read-only. Disable broad behavior in the prompt: no web search, no image generation, no unrelated file edits, no apply_patch unless explicitly asked. After generation, run chmod +x daemons/pro-deploy-check, bun daemons/pro-deploy-check --help, test one real prompt such as 'status for the current PR preview', then add package.json bin and bun link if appropriate. Expected output: current deployment state, preview URL, failing route if any, command evidence, and browser proof path. ``` #### Implementation references [Open reference](/topics/foundations-daemon-profile-playbook/) [Open reference](/topics/foundations-daemon-profile-playbook/) [Open reference](/topics/foundations-daemon-profile-playbook/#command-reference) ```text package.json scripts ``` ```text daemons/pro-deploy-check ``` ```text lib/isolated.ts ``` ```text chmod +x daemons/pro-deploy-check ``` ```text bun daemons/pro-deploy-check --help ``` ```text bun link ``` #### Browser verification Use browser proof after the daemon discovers the preview URL: open the preview in a CMUX browser pane or run the repo's browser automation to snapshot the homepage and one changed route, then record status code, visible error text, console errors, and screenshot path. Browser proof is useful here because deployment status alone does not prove the UI renders. #### Definition of done - The profile wraps one deployment or preview-check CLI only - The first command is read-only status or preview discovery - bun daemons/pro-deploy-check --help succeeds - A real prompt returns deployment status, preview URL, and exact commands run - Browser evidence exists for at least the homepage and one changed route - The final report is terse and separates blocker, warning, and clean result #### Failure modes and mitigations - Mistake: the agent creates a general CI/CD bot with many tools and broad permissions. Mitigation: one CLI, one profile, read-only first, mutate only when target plus action are explicit. - Mistake: it trusts a green deployment status without checking the rendered app. Mitigation: require browser proof for at least one preview route before final answer. - Mistake: it hardcodes a vendor-specific command not present in the repo. Mitigation: inspect package.json and existing scripts first, then map only verified local commands. - Mistake: it bloats context with full docs or --help output. Mitigation: keep a small curated command map and use --help only as a retry path. ### Create a focused accessibility audit daemon **Role:** As a frontend platform engineer supporting multiple product teams Several teams ship React pages with recurring accessibility regressions: missing form labels, buttons without accessible names, skipped headings, and modals that trap focus inconsistently. The work is repetitive and command-driven, but each audit still needs a concise human-readable report. > As a frontend platform engineer, I want a narrow Codex daemon that runs the project accessibility checks and browser proof steps, so that teams get consistent reports without asking a general assistant to rediscover the workflow each time. #### Agent brief ```text Build or use an isolated Codex daemon profile for accessibility triage only. Keep the command map narrow: inspect package scripts, run the existing accessibility or browser-test command if present, start the local dev server only when required, open the target route in a browser, capture an accessibility snapshot, and report missing labels/headings/focus problems with file or route pointers. The daemon should write one markdown report under `.notes/a11y/<route-slug>.md` with commands run, browser route, snapshot summary, issues found, false positives, and recommended next fixes. It must not edit files unless explicitly asked after the audit report is reviewed. ``` #### Implementation references [Open reference](/topics/foundations-daemon-profile-playbook/) [Open reference](/topics/foundations-daemon-profile-playbook/) ```text package.json scripts ``` ```text target app route/component files ``` ```text cmux browser snapshot or existing Playwright accessibility checks ``` #### Browser verification Use browser proof because accessibility is runtime UI behavior. Open the target localhost route, take an accessibility snapshot, click or tab through the primary form/modal/menu path, evaluate focus state where useful, and save the route plus snapshot summary in the daemon report. If no browser surface is available, state that runtime accessibility proof is missing rather than claiming success from source inspection. #### Definition of done - The daemon profile has one narrow responsibility and a small command map. - A markdown report exists under `.notes/a11y/` with exact commands, route, browser proof, and prioritized issues. - The daemon did not edit source files during audit-only mode. - The report distinguishes confirmed runtime issues from possible source-level concerns. #### Failure modes and mitigations - The daemon becomes a broad product assistant; mitigate by keeping its profile limited to accessibility triage commands and reports. - The daemon claims accessibility from static source reading; mitigate by requiring browser snapshot/focus evidence for runtime findings. - The daemon mutates code during audit; mitigate by making audit-only mode the default and requiring explicit follow-up approval for fixes. ## Implementation notes - Keep each daemon wrapped around exactly one CLI or one repo-local script family. The whole point is a narrow helper, not another giant assistant. - Use the runProfile() shape from lib/isolated.ts: one executable Bun TypeScript file, low reasoning by default, literal developerInstructions, and a curated command map. - The prompt order matters: Operating rule first, then Command map, then Workflow, Command rules, and Output. - Make the daemon run a command before answering. A daemon that summarizes from memory is just a small hallucination machine with a fancy name. - Default to read-only discovery. Require explicit target plus action for mutations, especially deploy, Docker, database, cloud, or file-editing tools. - Do not paste full --help output into instructions. Keep the command map tight and use --help only when syntax is uncertain or a usage error occurs. - For web app work, pair command receipts with browser receipts when the user-visible app matters: local URL, route, action sequence, screenshot or trace path, console errors, and pass/fail. - Treat self-improvement as experimental and narrow. It fits predictable CLI/API failure modes better than broad product implementation. ## Boundaries and caveats - Do not introduce unrelated workflow tools only mentioned in the lesson as if they were taught implementation steps. - Do not build an all-purpose autonomous swarm. Parallel agents need an analysis or synthesis step, and this topic is exactly one toolkit technique. - Do not claim arbitrary line-count rules for agent-readable code. The taught guidance favors clear state machines, named cases, and English-readable conditions. - Do not make browser automation unbounded or credential-casual. Keep it scoped to local app verification or explicit preview URLs with clear proof artifacts. - Do not use daemon profiles for judgment-heavy planning, product strategy, or multi-tool implementation. Use them for repetitive, well-scoped CLI work. ## Agent reference map ### Codex daemon profile skill Use as the implementation contract for when to trigger this technique, profile shape, prerequisites, isolation behavior, and guardrails. [Open reference](/topics/foundations-daemon-profile-playbook/) ### Isolated profile prompt Use as the copy-paste user-facing prompt pattern for generating a new pro-<TOOL> profile. [Open reference](/topics/foundations-daemon-profile-playbook/) ### Verified codex-daemons command patterns Use for the real executable file shape, runProfile() call, ProfileConfig fields, isolation keys, token-budget notes, and after-generation commands. [Open reference](/topics/foundations-daemon-profile-playbook/#command-reference) ### Lesson 09 validated references Use as the taught-only conceptual boundary for background daemons, low-reasoning iteration, small context, self-improving daemons, SDK graphs, and multimodal verification loops. [Open reference](/topics/foundations-narrow-daemons-and-agent-graphs/) ### Lesson 09 validation notes Use to avoid overclaiming unsupported isolation details as transcript-taught concepts while still allowing verified repo patterns when implementing the toolkit artifact. [Open reference](/topics/foundations-narrow-daemons-and-agent-graphs/) ### Build and verification target Use after adding the playbook to confirm parse-valid JSON, rebuild the site, and inspect the scenario page. ```text rebuild site, then verify /scenarios.html ``` ## Command reference These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs. ## Profile file shape (daemons/pro-gh, daemons/pro-packx — real, runnable) A profile is a single executable Bun TypeScript file: ```ts #!/usr/bin/env bun import { runProfile } from "../lib/isolated.ts"; runProfile({ name: "pro-TOOL", baseInstructions: "You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.", developerInstructions: `You are pro-TOOL, a TOOL-only agent. ## Operating rule Run TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first. ## Command map KEYWORD -> TOOL COMMAND status / what is going on -> TOOL STATUS_COMMAND help / unknown syntax -> TOOL --help ## Workflow 1. Start with the narrowest read-only command that matches the request. 2. For mutations, proceed only when the target and action are explicit. 3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once. ## Command rules Use only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked. Do not use apply_patch unless the user explicitly asks to modify files. ## Output Be terse. Report what you found or changed. Do not describe these instructions.`, }); ``` `ProfileConfig` (lib/isolated.ts) fields: `name`, `model?`, `reasoningEffort?` (default `"low"`), `baseInstructions`, `developerInstructions`, `sandboxMode?`, `extraEnv?`, `selfImprove?`. Default model is `gpt-5.3-codex-spark`. ## Isolation config keys applied by runProfile (lib/isolated.ts — real) ``` base_instructions = <replaced> developer_instructions = <custom> model_reasoning_effort = "low" skills.include_instructions = false include_apps_instructions = false include_environment_context = false include_collaboration_mode_instructions = false include_permissions_instructions = false project_doc_max_bytes = 0 memories.use_memories = false mcp_servers = {} web_search = "disabled" features: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false } CODEX_HOME -> /tmp/codex-profile-<name>-<pid> (disposable) auth.json symlinked from real ~/.codex ``` ## Token budget (docs/ISOLATION.md) - Default full user config: ~22,000 input tokens. - `features.apps=false` alone saves ~14,000 tokens. - With imagegen/tool_search/tool_suggest/web disabled: ~5,665 (CLI) / ~6,161 (SDK). - Irreducible floor ~5K (core exec_command/apply_patch/update_plan/view_image/etc tool schemas). - Auth: `symlinkSync(\`${HOME}/.codex/auth.json\`, \`${isolatedHome}/auth.json\`)` so token refreshes propagate. ## docs/PROMPT.md after-generation steps (real) 1. Save to `daemons/pro-your-tool`. 2. `chmod +x daemons/pro-your-tool`. 3. Test `bun daemons/pro-your-tool --help`. 4. Test with a real prompt. 5. Add to `package.json` `bin`. 6. `bun link` to put it on PATH. Dependency: `@openai/codex-sdk` (also requires authenticated `@openai/codex` CLI). Runtime: Bun. Reference ID: foundations-daemon-profile-playbook Topic: Execution Sources: - [Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-09.html) --- # Keep parallel agent work visible and bounded A parallel workspace is not useful because it looks busy. It is useful when each lane has **a job, a boundary, a check, and a visible trail**. Start by planning the split. Then open the workspace that makes that split easy to supervise. ## Start Fresh For The Task Do not begin by hunting for the perfect saved layout. Begin with the **current phase of work**: what needs design, what needs implementation, what needs verification, and what can safely happen at the same time. A dashboard task, a migration, a game level, and a new project do not need the same shape. **Ask for the split that fits the task in front of you.** For a dashboard: - one lane designs the data cards - one lane checks API shape and sample data - one lane writes component tests - one lane reviews empty, loading, and error states For a migration: - one lane maps the source schema - one lane maps the destination schema - one lane writes verification queries - one lane drafts rollback notes ## Split By Boundaries, Not By Vibes Each lane needs a job, allowed files, files to avoid, and proof. If two lanes need the same files, they are **not parallel yet**. > How can we accomplish this task with multiple agents, where they each have their own responsibility, and they each have their own testing, they can work in parallel, usually in the same branch, honestly. > > — John Lindquist | Lane | Owns | Avoids | Proof | |---|---|---|---| | UI lane | `src/routes/dashboard/**`, component snapshots | API contracts, migration files | screenshot and component checks | | Data lane | query helpers, fixtures, schema mapping | visual components | query tests | | Test lane | new regression tests | production logic except test hooks | failing-before / passing-after log | | Review lane | risk notes, integration checklist | code edits | written review with blockers | ## Keep The Agents Visible **Visible work is easier to correct.** You can inspect the history, compare outputs, step into one lane, or stop a bad direction before it spreads. Hidden background work can be useful, but it removes the trail you need when the next run should be better. If the task is risky, keep the lanes where you can watch them. > When I see agents spawn up in background threads, and I don't know what they're doing, and I can't, like, look at some of the history and tool calls and everything. I don't know how it could improve next time. > > — John Lindquist ## Use A Manager Thread **One thread owns the plan.** Other lanes execute bounded work. The manager does not need to do every task. It needs to remember the split, check progress, catch conflicts, and decide when to merge, redirect, or stop. Manager responsibilities: - restate the project goal - divide work into lanes - assign file boundaries - name the verification for each lane - tell each lane which other lanes exist - check progress before merging ideas - stop any lane that crosses its boundary ## Copyable Prompt: Parallel Work Plan ```text We need to plan parallel agent work for this software task. Task: [describe the feature, fix, migration, or review] Current phase: [planning / implementation / debugging / visual review / verification] Project facts: - active areas: - stable areas to avoid: - commands/tests available: - risky files: - expected output: Create a parallel work plan. Return: 1. the smallest useful number of lanes 2. the responsibility of each lane 3. exact file or directory boundaries for each lane 4. what each lane must not touch 5. the verification each lane must run 6. the manager check-in schedule 7. the prompt to initialize each lane Prefer fewer lanes if file conflicts are likely. Do not start implementation yet. ``` ## Copyable Prompt: Lane Setup ```text You are Lane [name]. Goal: [one responsibility] Allowed files: [list] Do not touch: [list] Other lanes running: - [lane]: [scope] - [lane]: [scope] Before editing: - inspect only your allowed area - restate the files you expect to touch - name the verification you will run After editing: - summarize changes - list files changed - run verification - report any boundary conflicts ``` ## Make Progress Legible Use agents to make proof easier to produce: screenshots, before/after numbers, test logs, release notes, and short visual summaries. The goal is not noise. The goal is **reviewable impact**. Before/after performance note: ```text Before: Dashboard loaded sample account in 4.8s. After: Dashboard loaded sample account in 1.9s. Proof: Trace attached, test command included. Change: Cached account summary query and removed duplicate fetch. ``` Visual progress note: ```text What changed: Replaced manual export flow with a reviewed batch job. Why it matters: Removes three support steps. Proof: Screenshot, smoke test, rollback note. ``` ## Save The Layout Only After It Repeats **A reusable layout is earned.** If the same task shape appears three times with the same lane split, checks, and review surface, turn it into a saved workspace, script, or small helper. Until then, start fresh and ask for the split. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#parallel-agents) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-parallel-agents Topic: Execution Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#parallel-agents) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Markdown flows as a repeatable control surface Preload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals. ## Related working material - [Markdown flows as a repeatable control surface — prompts and exercises](/topics/factory-markdown-flows-practice/) - [Markdown flows as a repeatable control surface — questions and tradeoffs](/topics/factory-markdown-flows-questions/) - [Markdown flows as a repeatable control surface — worked example](/topics/factory-markdown-flows-worked-example/) ## TL;DR - mdflow makes a repeatable agent job a versioned markdown "flow": shell output is inlined into the prompt at build time, so the agent starts already briefed on your git state, terminal panes, and tickets. - You walk away with a project roster (`npx mdflow init -y`) plus a pane-aware standup flow you can lift straight off this page. - The one move: the next briefing you type twice, put it in a flow file with `` !`command` `` inlines instead. Have your agent set this up — paste this into it: ``` text Fetch https://walnut-virtue-6d22.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## The briefing you keep re-typing Every fresh agent chat starts blind. You re-explain the branch, the panes, the ticket — and next session you type it all again. That briefing isn't free: it costs your time, and the agent's context fills with ambient setup before work starts. mdflow's answer is one markdown file per repeatable job — a "flow" — kept in the repo, runnable on any installed engine, inspectable before it executes. The README states the thesis directly: a Git-native control plane for repeatable agent work. A chat session is a performance you repeat; a flow is a script you version. ## Context lands before the first token A flow embeds shell output with a `` !`command` `` inline. mdflow runs the command while building the prompt, so the agent never spends a tool-call round trip on `git status` — and never skips or reorders it. The standup flow above preloads four commands this way; `md doctor --json` reports exactly those four as its declared capabilities. The pattern scales past one-liners. A production flow on the author's machine runs a preload script that fetches workshop ticket buyers from the payment provider and current calendar attendees, prints the computed diff as markdown, and then tells the agent: this data was fetched moments ago — do not re-fetch. One detail worth stealing: the preload script exits 0 even on failure, printing a `PRELOAD ERROR` section instead, so the error lands inside the prompt and the agent can relay it and stop rather than dying silently. Your feedback loop is `md explain`: it resolves the full configuration and lists every inline as a capability without executing anything. If your command shows up in the list, the context will land. ## A global specialist flow, printed in full Some jobs recur across every project: keyboard config, shell config. The author's machine has roughly sixty-five `flow-*` commands on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh` — each a globally installed specialist. Here is the installed `flow-zsh` file, complete. It is shown to study, not to paste — it maps one person's zsh setup — but the anatomy is the lesson: a mission, a tool-output trust boundary, a command map covering the whole config domain, worked examples, an error-recovery table, and a mutation policy that demands verification after every edit. The agent gets all of it on every single run. The specialist pattern declares a mission, an untrusted-evidence boundary, a narrow inspection command map, ownership rules, worked examples, mutation approval, and exact verification. Keep the operating instructions project-specific rather than copying another machine’s private configuration. The weak move is a monolithic "dotfiles assistant" that answers from memory. The strong move is one flow per domain, each opening with "never answer from memory" and a first-step inspection command. `flow-karabiner` encodes the same discipline for keyboard config: read, make the smallest edit, run the compiler, then grep the generated JSON to prove the mapping exists. ## One launcher, isolation by default Sixty-five global flows plus project rosters create a discovery problem. Bare `md` answers it: the Flow Workbench, one searchable list of everything runnable, each entry labeled with its provenance — `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH`. And every flow runs stripped by default. Your interactive session hauls memory files, hooks, MCP servers, and project instructions; a flow that reviews a diff needs none of it. mdflow disables ambient engine context using each engine's own flags — claude gets `--safe-mode --no-session-persistence`, codex gets `--ignore-user-config --ephemeral`, gemini `--extensions none`, copilot `--no-custom-instructions`. Anything the flow genuinely needs is declared in frontmatter; `_isolated: false` opts back into ambient. Isolation strips context — it does not confine the host. The inline commands and the engine still reach your filesystem, network, and credentials. ``` text ---------------------------------------------------------------------- ISOLATION ---------------------------------------------------------------------- ON (default) — ambient engine context is disabled; host capabilities remain available safe-mode: true no-session-persistence: true (opt out with _isolated: false) ``` That block is captured from `md explain flows/workshop-standup.claude.md` in this demo project — isolation is on without any frontmatter asking for it. ## Flows change by proposal, not by vibes A flow edited by hand after a bad run regresses silently. mdflow's evolve loop replaces the tweak with a process: record feedback (it gets a durable `fb_…` ID), preview the eval cost, generate an off-path proposal, and read the verification receipt. The canonical file stays byte-identical until you explicitly apply. ``` text md feedback flows/review.md "missed the renamed-file regression" md eval flows/review.md --plan # free cost preview of the eval suite md evolve plan flows/review.md # free: evidence, verification, cost, writes md evolve propose flows/review.md # off-path proposal; source unchanged md evolve show <run-id> # decision, capability diff, prompt diff md evolve apply <run-id> # atomic, explicit, reversible ``` The outcome vocabulary is deliberately honest: `verified_improvement` means a feedback-linked case failed on the old prompt and passed on the proposal; `regression_safe` means guardrails passed but the reported problem was not proven fixed; `rejected`, `inconclusive`, and `capability_rejected` cover the rest. When a flow disappoints, file feedback in the moment and let the suite — not your memory — decide whether the fix is real. ## Appendix ### Limits & caveats - **Isolation is not a sandbox.** Context isolation strips prompts, hooks, and extensions; it does not confine the host. Inline commands and the engine retain full filesystem, network, environment, and credential access. Engines with no isolation controls (droid, cursor-agent, agy) run ambient and warn rather than pretend. - **Eval verdicts in this demo are Unverified.** The starter suites exist, but no full eval receipt has been recorded, so `md doctor` reports every flow's verdict as `Unverified — no full eval receipt has been recorded`. The loop is the mechanism being demonstrated; this roster has not yet earned `verified_improvement` badges. - **Token savings are unquantified.** The sources support "ambient material is not loaded" and nothing more. No percentage is published; do not quote one. - **Engine defaults differ.** The starter roster defaults to the `pi` engine via `.mdflow.yaml`; the standup flow pins claude through its `.claude.md` filename. The same files run on other engines, but outputs are not interchangeable. Full resolution order: `--engine` flag → `MDFLOW_ENGINE` → filename → frontmatter `engine:` → project config → default (pi). - **The linear inline is a placeholder** in the public demo flow. The real version launches a sandboxed, read-only ticket-CLI agent; the placeholder keeps the published file runnable anywhere. - **Preloading captures state at launch.** It does not keep updating; a long-running agent that needs fresh state must still fetch it. ## Operating practice ### Turn good prompts into inspectable flows #### What to notice Reuse a task recipe that can inject **fresh command output**, preserve **prompt structure**, and expose what the agent will receive. #### Try this Promote one prompt you have run twice into a flow with declared inputs and a dry-run inspection path. > “If you think of managing context as having only the context that I need for the specific task that I want.” John Lindquist · [02:55:29](https://proud-anchor-53zn.here.now/watch.html?t=10529#recording-player) #### Concept A flow should remove repeated composition work, not hide it. Inspect the rendered prompt, run from known state, and preserve failures when the wrapper or check does not behave as expected. #### Reflection The recorded wrapper test did not become a clean success. The companion keeps that failure visible instead of rewriting history. **Recording evidence:** listen at 02:51:53. > “It's a pre-processing step, where it runs the code that's inside of here, which means it preloads context into the markdown file.” John Lindquist · [03:15:06](https://proud-anchor-53zn.here.now/watch.html?t=11706#recording-player) [Open mdflow](https://walnut-virtue-6d22.here.now/) #### Links shared for this topic - [Flow Text source](https://github.com/johnlindquist/flow-text/) — A repository for a reusable text-flow experiment. - [gog CLI](https://gogcli.sh/) — A command-line surface for Google services. - [Birdclaw](https://birdclaw.sh/) — A command-line social workflow tool. - [CodeGraph](https://colbymchenry.github.io/codegraph/) — A visual code-relationship explorer shown during workflow experiments. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=10313#q2-markdown-flows) Reference ID: factory-markdown-flows Topic: Execution Sources: - [Markdown flows as a repeatable control surface](https://walnut-virtue-6d22.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows) --- # Markdown flows as a repeatable control surface — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### mdflow (Markdown Flows) The architectural approach of bundling specific system prompts together with interactive execution tools inside Markdown files to establish reusable agent workflows. ### Agent Skills Evolution The historical transition of agent skills from dynamically-loaded individual agent actions to an over-installed community library of markdown files that excessively clutter agent context windows. ### Context Management The practice of isolating and injecting only the precise context, files, and prompts required for the active task to avoid cost and dilution of agent attention. ### Markdown Flows A technique within the Codex environment where specific task context, system prompts, configuration variables, and operating boundaries are defined within a dedicated Markdown file's front matter and body. This preloads the LLM with all necessary local environment knowledge. ### Context Injection Passing explicit guidelines, folder structures, and syntax rules directly to an LLM upfront so that it can operate effectively even with lower-tier or faster reasoning models without needing specialized tool APIs or complex pre-programmed agent skills. ### Preloaded Context Injecting system prompts and relevant file pathways into an AI session beforehand so that it automatically adheres to existing project conventions. ### Goku Compiler Mappings An extensible clojure-based declarative utility to generate custom key mappings for Karabiner-Elements on macOS. ### Model Context Protocol Tooling An open standard interface allowing LLM frameworks to interface directly with local file contexts and environments, referenced via the failing node_repl client. ### 1Password CLI Authentication Integrating programmatic secrets protection with native OS prompts, ensuring sensitive workspace variables are never saved as cleartext. ### GOG CLI (gog) A single Go-based command line tool designed to interact with Google Workspace APIs (Gmail, Calendar, Drive) perfectly suited for terminals and AI agents. ### Fast Mode (/fast) An agent environment flag that forces 1.5x speed inference at the cost of increased usage billing. ### Context-Aware Automation Flows Programmatically loading dynamic context (like API outputs or local file listings) into an agent session rather than spending conversational turns discovering it. ### System Prompt Overrides Flags or config configurations that substitute baseline behavior files in LLM CLI developer agents. ### Codex Markdown Extension Naming Convention The file naming convention where .codex.md activates a framework layer to handle markdown contents as a programmatic instruction stack. ### birdclaw An open-source local-first command-line tool workspace ecosystem designed for Twitter interaction caching. ### Markdown Context Injection Syntax Using an exclamation point followed by backticks inside a flow file runs shell commands during a pre-processing step, preloading environment telemetry directly into the context sent to an AI assistant. ### Dynamic Context Injection Pre-loading ambient environment configurations, active layouts, and histories straight into markdown prompt blocks prior to agent execution. ### Single-Turn Inference Optimization Bundling complex execution guidelines and state data into one prompt turn to avoid the overhead, latency, and costs of iterative tool-calling iterations. ### Flow Agents Specialized automation configurations mapped to target file folders or trigger scripts that execute highly distinct localized development tasks. ### Specialized Flow Agents Isolated sub-agents defined within standalone Markdown settings profiles mapping directly to specific domains like hotkeys or clipboards. ### Main Agent Routing An architecture layout where a general core coordinator delegates targeted tasks down to localized sub-agents using strict boundary declarations. ### Feature-Bound Agents / Repeatable Markdown Flows Specialized, restricted sub-agents configured through Markdown documentation files to carry out localized repository workflows efficiently with predetermined permissions and files. ### MDFlow An abstraction system developed by the presenter to encapsulate system prompts and configurations into a reusable file layout that can easily point to different platforms like Cursor or Copilot. ### Imps A specific variation of sub-agents native to the Codec environment. ### AI Provider Swapping Designing developer tools and workflows so they can easily swap backend providers (e.g., Gemini, Claude, Codex, Copilot, Cursor) rather than being locked into a single ecosystem. ### API-Based Pricing Workflows Managing tool usage (like Claude Code and Fable) under usage-based API billing rather than fixed subscriptions, which requires weighing token costs against the efficiency benefits. ### Workspace Flow Orchestration Using utilities like herdr to open multiple workspace panes automatically, map distinct automated scripts (clipboard, scout, screenshot flows), and keep watch on their tasks concurrently. ### Fable 5 A highly capable LLM characterized by minimal turn iterations and exceptional reasoning token efficiency. ### CodeGraph A local tool that transforms software codebases into structured semantic graphs queried by AI coding agents via MCP. ### Human-Centric vs. Agent-Centric Data representation Human-centric formats emphasize spatial, graphical, or visual relationships (e.g., graphs, diagrams) to enhance cognitive clarity, while agent-centric formats prioritize extreme structural compression or dense layouts to optimize context length and token spend. ## Questions and answer status ### Sounds like a stripped down version of agent skills, is that the idea? **Status: answered.** John agrees conceptually and uses the question as a prompt to discuss how agent skills evolved away from their original definition toward a bloated model, contrasting them against his streamlined task-based context approach. ### you can turn on fast right? **Status: answered.** John admits that he can turn it on, but typically doesn't justify the additional cost for casual individual tasks. He resolves to enable it for upcoming workshops. ### Is Fast Mode Stay on? **Status: answered.** Yeah, it stays on across sessions. ### Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool? **Status: partial.** John details that Flow processes plain markdown containing structural prompt definitions, moving into a live directory code example to highlight how it routes inputs. ### Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool? **Status: answered.** John demonstrates that a flow runs markdown templates that dynamically evaluate and preload context onto files through an evaluation step prior to AI execution. ### Is this similar to your concept of imps ? **Status: answered.** John answers that it is an abstracted version; 'imps' is tailored specifically for Codec, while MDFlow serves as a more general platform-agnostic alternative. ### Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup? **Status: unanswered.** The query regarding Anthropic subscription versus API-based billing was not explicitly addressed in this chunk. ### Do you have an orchestrator that manages all the flows? For example, can it open a new herdr tab with the auditor flow and notify me when it's done? This would require access to the herdr-control.md and the auditor.md files.? **Status: answered.** John states he does not use an automated orchestrator by default yet, preferring to manually dictate agent instructions via herdr help, and then provides a live scripted demo opening multiple workspace panes. ### Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup? **Status: answered.** John answers that he pays the API cost to use Claude Code and Fable normally, noting that the benefits outweigh the friction. He also mentions symlinking skill and memory/agent/Claude files to keep setups synchronized. ### Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage? **Status: answered.** John notes that standard harnesses compress context automatically, but tool returns sometimes cause agent errors if altered too drastically. He notes that CodeGraph builds code structural maps rather than straightforward string token filtering. ### Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage? **Status: partial.** John indicates that code graph maps usually optimize for human visuals rather than AI efficiency, and runs an experiment inside Claude Code to see how an agent would compress repository layout mappings autonomously. ## Exercises - **Try:** Open an active markdown flow layout template file and add a system command step using the exclamation mark and backtick framework. **Basis:** 03:15:06.090 ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [02:52:15](https://proud-anchor-53zn.here.now/watch.html?t=10335#recording-player) — John notes that this is very similar to what Skills do in other projects, and explains his approach of bundling prompts with tools to make them reusable for any workflow. - [02:52:55](https://proud-anchor-53zn.here.now/watch.html?t=10375#recording-player) — John switches windows to the Ghostty terminal app, showing multiple workspace spaces on the left pane and executes p-pr 24 in the mdflow main s1 terminal tab. - [02:53:01](https://proud-anchor-53zn.here.now/watch.html?t=10381#recording-player) — An interactive prompt input modal box appears in Ghostty with the fields 'Name (optional conversation name)' and 'Prompt (24)'. - [02:53:03](https://proud-anchor-53zn.here.now/watch.html?t=10383#recording-player) — John observes that Claude opens its PR picker because he did not specify that he wanted to pass the PR number, or because the prompt builder does not support it. - [02:53:12](https://proud-anchor-53zn.here.now/watch.html?t=10392#recording-player) — John enters the text 'I want to pass the pr number' into the terminal area. - [02:53:23](https://proud-anchor-53zn.here.now/watch.html?t=10403#recording-player) — A window pane titled claude opens on the right side of the screen displaying 'Resume session... Search... mdflow... No conversations found in this project.' - [02:53:23](https://proud-anchor-53zn.here.now/watch.html?t=10403#recording-player) — John observes that there are no conversations. - [02:53:33](https://proud-anchor-53zn.here.now/watch.html?t=10413#recording-player) — John reviews code documentation text within Ghostty showing the path source ~/.config/zsh/conf.d/44-ai-claude-pr-dsl.zsh and explanations of Claude's breakdown of the p-pr command. - [02:53:36](https://proud-anchor-53zn.here.now/watch.html?t=10416#recording-player) — John concludes that the tool assumed from-pr should open a PR picker, which caused the error. - [02:53:58](https://proud-anchor-53zn.here.now/watch.html?t=10438#recording-player) — John discusses the original intention of skills being for agents to dynamically load them when needed. - [02:54:10](https://proud-anchor-53zn.here.now/watch.html?t=10450#recording-player) — John states that skills evolved into a community of developers sharing markdown files, which are completely different things. - [02:54:23](https://proud-anchor-53zn.here.now/watch.html?t=10463#recording-player) — John explains that skills were introduced because of context limits and costs, and analyzes what happens when those limitations are relaxed. - [02:55:10](https://proud-anchor-53zn.here.now/watch.html?t=10510#recording-player) — John notes that easy skill installation caused people to load too many skills, filling up context windows with unneeded capabilities. - [02:55:28](https://proud-anchor-53zn.here.now/watch.html?t=10528#recording-player) — John summarizes that managing context means having only the specific context required for the target task. - [02:55:47](https://proud-anchor-53zn.here.now/watch.html?t=10547#recording-player) — The shard begins with John Lindquist sharing his desktop view of the OpenAI Codex terminal application (v0.144.5), running the gpt-5.6-sol medium model in YOLO mode. - [02:55:49](https://proud-anchor-53zn.here.now/watch.html?t=10549#recording-player) — John types $karabin next to the menu prompt to showcase available skills, which displays options like Slack Notification Triage and Reply Drafting. He deletes it shortly after. - [02:56:03](https://proud-anchor-53zn.here.now/watch.html?t=10563#recording-player) — John types $scar into the prompt to mention a custom friction-tracking skill called 'learn from your scars', before clearing the input. - [02:56:36](https://proud-anchor-53zn.here.now/watch.html?t=10596#recording-player) — John types flow- into the menu prompt, triggering a dropdown list of automated workflows, and selects flow-karabiner. - [02:56:47](https://proud-anchor-53zn.here.now/watch.html?t=10607#recording-player) — Selecting the flow triggers a 'Hooks need review' security warning prompt and an alert regarding unsupported project-local configuration keys in ~/.codex/config.toml. John presses Escape to cancel and return to the main menu. - [02:57:02](https://proud-anchor-53zn.here.now/watch.html?t=10622#recording-player) — John types md into the prompt, opening a file list, and selects flow-karabiner.codex.md. - [02:57:14](https://proud-anchor-53zn.here.now/watch.html?t=10634#recording-player) — An ACTIONS overlay menu appears with options including 'Run flow', 'Preview dry-run', and 'Edit flow'. John selects 'Edit flow [LOCAL WRITE]'. - [02:57:20](https://proud-anchor-53zn.here.now/watch.html?t=10640#recording-player) — The screen switches to a text editor displaying flows/flow-karabiner.codex.md. John scrolls through the extensive markdown file, highlighting its front matter metadata, system prompt, mission details, tool boundaries, and specific keyboard layout guidelines. - [02:58:14](https://proud-anchor-53zn.here.now/watch.html?t=10694#recording-player) — John initiates flow-karabiner and inputs the query: list my herder shortcuts. - [02:58:24](https://proud-anchor-53zn.here.now/watch.html?t=10704#recording-player) — The prompt updates to 'Working (0s - esc to interrupt)'. Under the Explored section, the agent performs automated context gathering steps including reading Karabiner.edn, searching for herdr, and running sed commands on ~/.config/karabiner.edn. - [02:59:10](https://proud-anchor-53zn.here.now/watch.html?t=10750#recording-player) — The flow completes and outputs a markdown summary titled '### Herdr workspace shortcuts', detailing active Ghostty and workspace launcher layer key combinations. - [02:59:17](https://proud-anchor-53zn.here.now/watch.html?t=10757#recording-player) — John triggers flow-karabiner again to execute an update command. - [02:59:32](https://proud-anchor-53zn.here.now/watch.html?t=10772#recording-player) — John types the request: 'Please create a herdr shortcut ,+q to open ~/dev' into the Implement feature input box and executes it. - [02:59:42](https://proud-anchor-53zn.here.now/watch.html?t=10782#recording-player) — John notes that if this were a raw session, the model wouldn't understand what he was talking about without preloaded context. - [02:59:50](https://proud-anchor-53zn.here.now/watch.html?t=10790#recording-player) — Codex updates .config/karabiner.edn and completes the execution of goku successfully. - [03:00:29](https://proud-anchor-53zn.here.now/watch.html?t=10829#recording-player) — John executes the comma q shortcut, which switches the environment focus view to the dev directory workspace. - [03:01:02](https://proud-anchor-53zn.here.now/watch.html?t=10862#recording-player) — John opens the text command input and enters flow-zsh. - [03:01:03](https://proud-anchor-53zn.here.now/watch.html?t=10863#recording-player) — A prompt screen appears detailing that 7 hooks need review because they are new or changed. - [03:01:05](https://proud-anchor-53zn.here.now/watch.html?t=10865#recording-player) — Codex window initializes, showing an MCP client startup failure for node_repl. - [03:01:22](https://proud-anchor-53zn.here.now/watch.html?t=10882#recording-player) — John enters the text prompt: How would I create a prompt builder wrapper for claude code? - [03:01:42](https://proud-anchor-53zn.here.now/watch.html?t=10902#recording-player) — Codex begins looking through shell files, exploring 40-ai.zsh. - [03:01:54](https://proud-anchor-53zn.here.now/watch.html?t=10914#recording-player) — Codex continues by reading 44-ai-claude-pr-dsl.zsh. - [03:02:38](https://proud-anchor-53zn.here.now/watch.html?t=10958#recording-player) — Codex returns its detailed implementation plan, including a p-claude function snippet. - [03:03:08](https://proud-anchor-53zn.here.now/watch.html?t=10988#recording-player) — John clears the launcher bar input and types flow-workshop. - [03:03:12](https://proud-anchor-53zn.here.now/watch.html?t=10992#recording-player) — John selects the script file workshop-attendee-sync.1.claude.md from the file selection list. - [03:03:22](https://proud-anchor-53zn.here.now/watch.html?t=11002#recording-player) — John uses biometric authentication, and the workspace runs the markdown script after prompting for confirmation to trust the target folder. - [03:03:32](https://proud-anchor-53zn.here.now/watch.html?t=11012#recording-player) — John talks about ticket sales automation and Google Calendar integration. - [03:04:12](https://proud-anchor-53zn.here.now/watch.html?t=11052#recording-player) — John posts the link https://gogcli.sh/ in the chat. - [03:05:56](https://proud-anchor-53zn.here.now/watch.html?t=11156#recording-player) — John types /fast into the terminal interface to toggle fast inference speed. - [03:06:01](https://proud-anchor-53zn.here.now/watch.html?t=11161#recording-player) — John executes md --help to inspect flags. - [03:06:14](https://proud-anchor-53zn.here.now/watch.html?t=11174#recording-player) — John navigates into the notion-header directory context using dev notion-header. - [03:06:20](https://proud-anchor-53zn.here.now/watch.html?t=11180#recording-player) — John accepts the directory security trust prompt. - [03:06:41](https://proud-anchor-53zn.here.now/watch.html?t=11201#recording-player) — John inputs the prompt requesting a Notion flow to be built. - [03:06:49](https://proud-anchor-53zn.here.now/watch.html?t=11209#recording-player) — The workspace agent actively executes exploration tools including which, rg, find, and npm view. - [03:07:26](https://proud-anchor-53zn.here.now/watch.html?t=11246#recording-player) — John talks about setting up travel reimbursement automation flows. - [03:07:33](https://proud-anchor-53zn.here.now/watch.html?t=11253#recording-player) — John types and executes notion-header codex --help in the terminal panel. - [03:07:35](https://proud-anchor-53zn.here.now/watch.html?t=11255#recording-player) — The CLI prints help flags for the codex tool including system prompt override definitions. - [03:08:45](https://proud-anchor-53zn.here.now/watch.html?t=11325#recording-player) — John enters notion-header flow to see the list of codex files. - [03:09:06](https://proud-anchor-53zn.here.now/watch.html?t=11346#recording-player) — John selects flows/flow-bird.codex.md from an interactive file list. - [03:09:21](https://proud-anchor-53zn.here.now/watch.html?t=11361#recording-player) — The flow command errors out with exit code 1 due to untrusted directory status. - [03:09:32](https://proud-anchor-53zn.here.now/watch.html?t=11372#recording-player) — John sends the birdclaw.sh web address link into the text chat. - [03:10:31](https://proud-anchor-53zn.here.now/watch.html?t=11431#recording-player) — John names a fresh markdown asset hello-world.md and types text inside. - [03:10:45](https://proud-anchor-53zn.here.now/watch.html?t=11445#recording-player) — John executes notion-header md hello-world.md in terminal. - [03:10:50](https://proud-anchor-53zn.here.now/watch.html?t=11450#recording-player) — The terminal renders the raw markdown sentence back directly. - [03:11:15](https://proud-anchor-53zn.here.now/watch.html?t=11475#recording-player) — John renames the hello-world file to use the .codex.md extension format. - [03:11:23](https://proud-anchor-53zn.here.now/watch.html?t=11483#recording-player) — John Lindquist notices he hasn't trusted the directory yet. - [03:11:29](https://proud-anchor-53zn.here.now/watch.html?t=11489#recording-player) — The OpenAI Codex CLI v0.144.5 starts up but encounters a node_repl MCP startup failure. - [03:11:49](https://proud-anchor-53zn.here.now/watch.html?t=11509#recording-player) — Terminal shows error that the path is not inside a trusted directory and prompts for user interaction choices. - [03:12:17](https://proud-anchor-53zn.here.now/watch.html?t=11537#recording-player) — A tabular list of automated flow profiles is outputted to the terminal via autocomplete navigation. - [03:13:36](https://proud-anchor-53zn.here.now/watch.html?t=11616#recording-player) — The text content of herdr-control.md is viewed in the editor, showing the frontmatter and exclamation-backtick syntax commands. - [03:14:08](https://proud-anchor-53zn.here.now/watch.html?t=11648#recording-player) — John Lindquist inputs the prompt 'Open three new panes' into the interactive CLI workflow utility. - [03:14:20](https://proud-anchor-53zn.here.now/watch.html?t=11660#recording-player) — An Anthropic OAuth refresh failure appears on screen, prompting a dropdown selection of alternative models. - [03:14:35](https://proud-anchor-53zn.here.now/watch.html?t=11675#recording-player) — The terminal window displays live context information with compiled JSON objects detailing current workspace pane layouts. - [03:15:21](https://proud-anchor-53zn.here.now/watch.html?t=11721#recording-player) — The screen shows a text editor displaying the file herdr-control.md containing current pane inventory and recent origin-pane context queries. - [03:15:30](https://proud-anchor-53zn.here.now/watch.html?t=11730#recording-player) — John explains that when the system loads, it automatically reads all open panes and injects this context dynamically. - [03:16:42](https://proud-anchor-53zn.here.now/watch.html?t=11802#recording-player) — The Herdr agent automates workspace execution, showing sequential terminal splitting actions and rendering active shell panes on the right side of the UI layout. - [03:17:13](https://proud-anchor-53zn.here.now/watch.html?t=11833#recording-player) — John discusses the optimization benefits of a single-turn interaction model compared to multiple turns of back-and-forth server tool calls. - [03:18:15](https://proud-anchor-53zn.here.now/watch.html?t=11895#recording-player) — John acknowledges that he needs to debug an unexpected workspace check behavior related to Codex rendering in the split panes. - [03:18:46](https://proud-anchor-53zn.here.now/watch.html?t=11926#recording-player) — The video displays a browser window showing the landing page for Birdclaw (birdclaw.sh), a local-first Twitter workspace app. - [03:19:07](https://proud-anchor-53zn.here.now/watch.html?t=11947#recording-player) — John notes that agents can grow over time into specific agents that handle specific tasks. - [03:19:08](https://proud-anchor-53zn.here.now/watch.html?t=11948#recording-player) — The file flows/hotkeys.md is shown open in the editor highlighting frontmatter metadata settings. - [03:20:02](https://proud-anchor-53zn.here.now/watch.html?t=12002#recording-player) — John opens AGENTS.md to highlight the top-level routing philosophy prioritizing flows. - [03:20:52](https://proud-anchor-53zn.here.now/watch.html?t=12052#recording-player) — John opens flows/clipboard.md to demonstrate feature isolation rules for clipboard features. - [03:22:33](https://proud-anchor-53zn.here.now/watch.html?t=12153#recording-player) — John specifies that he updated these configurations to utilize version 5.6 models. - [03:23:04](https://proud-anchor-53zn.here.now/watch.html?t=12184#recording-player) — The text editor displays the initial parameters of flows/clipboard.md, showing model: "gpt-3.6-sol" and config: model_reasoning_effort="medium". - [03:23:27](https://proud-anchor-53zn.here.now/watch.html?t=12207#recording-player) — Presenter scrolls through the file, showing the 'Tool-output trust boundary', 'Operating rule', and 'Command map' sections. - [03:23:44](https://proud-anchor-53zn.here.now/watch.html?t=12224#recording-player) — Presenter scrolls down to the 'Local lessons (advisory)' section containing custom automated self-improvement logs. - [03:24:14](https://proud-anchor-53zn.here.now/watch.html?t=12254#recording-player) — a participant asks: 'Is this similar to your concept of imps ?' - [03:24:36](https://proud-anchor-53zn.here.now/watch.html?t=12276#recording-player) — a participant submits a question regarding Anthropic API-based pricing and where Claude Code fits into the workflow. - [03:24:45](https://proud-anchor-53zn.here.now/watch.html?t=12285#recording-player) — Presenter scrolls through the lower sections containing SecretRejectionConfig and DEFAULT_BLOCKED_SOURCE_APPS. - [03:26:00](https://proud-anchor-53zn.here.now/watch.html?t=12360#recording-player) — John Lindquist addresses a participant's question, explaining that imps are Codec-specific whereas MDFlow is an abstracted architecture. - [03:26:57](https://proud-anchor-53zn.here.now/watch.html?t=12417#recording-player) — John Lindquist mentions evaluating support for tools like Devin and Grok. - [03:27:02](https://proud-anchor-53zn.here.now/watch.html?t=12422#recording-player) — John Lindquist notes Grok is recent and he needs to do a sweep of what popular tools need to be supported. - [03:27:11](https://proud-anchor-53zn.here.now/watch.html?t=12431#recording-player) — John Lindquist discusses Cursor, Copilot, Gemini (anti-gravity), Claude, and Codex supporting provider swapping. - [03:28:00](https://proud-anchor-53zn.here.now/watch.html?t=12480#recording-player) — John Lindquist mentions using Claude Code and Fable normally despite the API pricing friction. - [03:28:40](https://proud-anchor-53zn.here.now/watch.html?t=12520#recording-player) — John Lindquist describes symlinking skills, memory, agent, or Claude files to keep setups similar. - [03:29:10](https://proud-anchor-53zn.here.now/watch.html?t=12550#recording-player) — John Lindquist responds that he does not have a default orchestrator yet and dictates actions inside an agent with herder help. - [03:29:34](https://proud-anchor-53zn.here.now/watch.html?t=12574#recording-player) — John Lindquist demonstrates scripting the orchestration from Pi, setting up a herder help workspace configuration. - [03:29:54](https://proud-anchor-53zn.here.now/watch.html?t=12594#recording-player) — John Lindquist outlines the prompt requesting three panes in the workspace: clipboard flow, scout flow, and screenshot flow. - [03:30:14](https://proud-anchor-53zn.here.now/watch.html?t=12614#recording-player) — John Lindquist notes that you can tell it to watch all three flows to know how to launch them. - [03:30:52](https://proud-anchor-53zn.here.now/watch.html?t=12652#recording-player) — John Lindquist notices that the automated flows were opened in regular non-interactive mode instead of interactive mode. - [03:31:09](https://proud-anchor-53zn.here.now/watch.html?t=12669#recording-player) — The terminal display updates using the herdr tool to show workspace panel layout states for the active flows. - [03:31:13](https://proud-anchor-53zn.here.now/watch.html?t=12673#recording-player) — John Lindquist reflects on Fable 5's token efficiency and how it influences his orchestrator architecture assumptions. - [03:33:17](https://proud-anchor-53zn.here.now/watch.html?t=12797#recording-player) — a participant asks a question regarding CodeGraph and token usage reduction strategies. - [03:34:43](https://proud-anchor-53zn.here.now/watch.html?t=12883#recording-player) — John states he has used Mermaid diagrams in the past to pre-load layout structure but has not had a recent need to implement a dedicated code graph. - [03:37:29](https://proud-anchor-53zn.here.now/watch.html?t=13049#recording-player) — John inputs the command 'take dev/codegraph-exploration' to provision a target directory path. - [03:37:41](https://proud-anchor-53zn.here.now/watch.html?t=13061#recording-player) — John types and executes the compression prompt against the CodeGraph URL context. ### Unresolved: The exact parameter interface behavior design expected for the p-pr workflow tool. The system errored out or launched into picker modes unexpectedly during testing, causing the host to bypass deep diagnostics. **Discriminating evidence:** Can be confirmed by analyzing the code files defining the prompt-builder module or tracking downstream remediation shards. ### Unresolved: The exact application name of the dark-themed text editor hosting the markdown file. The file workspace headers are hidden; it resembles VS Code but cannot be confirmed with absolute certainty. **Discriminating evidence:** Verify via process explorer logs or repository environment setups if available. ### Unresolved: The exact structural backend mechanism supporting the 'dev' prefix router mapping rule. The system resolves it automatically without rendering standard shell expansions or symbolic paths. **Discriminating evidence:** Could be evaluated by checking shell configurations or custom tool aliases. ### Unresolved: The exact structural shift in terminal parsing when running standard markdown vs codex files inside an untrusted workspace framework. The snippet transitions right as the newly named file execution sequence begins. **Discriminating evidence:** Cross-reference next continuous segment block 06-06 data outputs. ### Unresolved: The exact protocol or connectivity technique birdclaw.sh uses to communicate with local setups. The browser interface is only visible briefly as a static document reference page. **Discriminating evidence:** Inspect the complete documentation for birdclaw.sh or review the corresponding repository code. ### Unresolved: Exact spelling prefix configuration match for gpt-5.6 model tag. The text character resolution displays specialized model notation suffixes that might denote isolated experimental deployments. **Discriminating evidence:** Cross-reference monorepo execution loaders to determine how the model string translates during orchestration. ### Unresolved: Exact script payload at line 109 of flows/clipboard.md The line contains a long single-quoted sed command string that wraps tightly across rows. **Discriminating evidence:** Can be verified directly inside the original markdown source file in the repository. ### Unresolved: Specific visual appearance of the multi-pane terminal output layouts The transcript describes the actions and terminal state text explicitly but precise cosmetic details require a full direct visual check. **Discriminating evidence:** Verify terminal theme, layout configuration, and text display styles visually. ### Demonstration detail: 02:52:55 - Switched to Ghostty terminal application window - Executed p-pr 24 command inside the terminal window - Interacted with prompt builder overlay input fields - Inspected code configuration markdown file text details **Tools observed:** Ghostty, Claude. **Command or prompt observations (not a verified recipe):** ```text p-pr 24 ``` ### Demonstration detail: 02:58:14 - Initiated flow-karabiner from the Codex terminal menu prompt - Submitted the natural language request 'list my herder shortcuts' - Observed automated context analysis via reading configuration file paths and generating shortcut list markdown summaries **Tools observed:** OpenAI Codex CLI, Karabiner-Elements. **Command or prompt observations (not a verified recipe):** ```text list my herder shortcuts ``` ### Demonstration detail: 02:59:17 - Re-triggered flow-karabiner - Typed update instructions: 'Please create a herdr shortcut ,+q to open ~/dev' **Tools observed:** OpenAI Codex CLI. **Command or prompt observations (not a verified recipe):** ```text Please create a herdr shortcut ,+q to open ~/dev ``` ### Demonstration detail: 02:59:40 - Creating a custom shortcut mapping dynamically via text prompt, compiling with goku, and testing the keyboard macro response. **Tools observed:** Codex CLI, Goku, Karabiner-Elements. ### Demonstration detail: 03:01:02 - Running a Zsh context exploration automation using flow-zsh to create custom prompt wrappers. **Tools observed:** Codex CLI. **Command or prompt observations (not a verified recipe):** ```text flow-zsh ``` ### Demonstration detail: 03:03:08 - Running the workshop attendee tracking automation, confirming trust safety dialogs, and authenticating security credentials via 1Password. **Tools observed:** 1Password CLI, Stripe CLI. **Command or prompt observations (not a verified recipe):** ```text flow-workshop ``` ### Demonstration detail: 03:05:44 - Enabled fast mode via /fast command macro - Inspected available options via md --help - Switched project context to dev notion-header - Accepted directory trust prompts - Submitted flow engineering prompt to agent **Tools observed:** mdflow, OpenAI Codex agent. **Command or prompt observations (not a verified recipe):** ```text /fast md --help dev notion-header which notion rg find npm view ``` ### Demonstration detail: 03:07:33 - Inspected CLI documentation flags for codex. **Tools observed:** codex. **Command or prompt observations (not a verified recipe):** ```text notion-header codex --help ``` ### Demonstration detail: 03:08:45 - Initiated an interactive prompt workflow sequence and encountered a directory security block. **Tools observed:** notion-header. **Command or prompt observations (not a verified recipe):** ```text notion-header flow ``` ### Demonstration detail: 03:10:16 - Built a markdown file asset to showcase standard vs codex template processing parameters. **Tools observed:** Cursor IDE. **Command or prompt observations (not a verified recipe):** ```text notion-header md hello-world.md ``` ### Demonstration detail: 03:13:54 - Executed markdown script execution command. - Input explicit workflow target behavior goals. - Selected substitute inference provider endpoints following system auth failure warnings. **Tools observed:** Ghostty, mdflow, OpenAI Codex CLI. **Command or prompt observations (not a verified recipe):** ```text md herdr-control.md ``` ### Demonstration detail: 03:15:55 - Typed 'please continue' into the Herdr terminal interface prompt prompt line. - Observed automated terminal split commands running sequentially through jq selection criteria. - Monitored automated initialization of an OpenAI Codex window interface mapping to an unexpected layout destination. **Tools observed:** Herdr CLI, VS Code / Cursor IDE, jq. **Command or prompt observations (not a verified recipe):** ```text herdr pane list | jq -c '.result.panes[] | select(.focused == true)' herdr pane split w2H:pC --direction right --cmd ``` ### Demonstration detail: 03:19:08 - Browsing structured agent declaration metrics in hotkeys.md - Inspecting top routing rules in AGENTS.md - Verifying feature isolation variables and reasoning constraints inside clipboard.md **Tools observed:** Cursor IDE. ### Demonstration detail: 03:23:04 - Inspected and navigated the content profile configuration rules within flows/clipboard.md in the text editor window. **Tools observed:** Cursor. ### Demonstration detail: 03:29:29 - Setting up a workspace orchestration flow with herdr help. - Prompting or configuring the creation of 3 separate panes. - Assigning specific workflows: clipboard flow, scout flow, and screenshot flow to the separate panes. - Setting the workspace to monitor or watch all three running flows simultaneously. **Tools observed:** herdr, Pi. **Command or prompt observations (not a verified recipe):** ```text herdr help ``` ### Demonstration detail: 03:30:52 - Terminated active shell pane environments and refreshed layout structure flags. **Tools observed:** herdr, zsh. **Command or prompt observations (not a verified recipe):** ```text herdr pane read w2p:p4 --source recent --lines 8 --format text ``` ### Demonstration detail: 03:33:36 - Navigated to the project landing page of CodeGraph to read integration guidelines. **Tools observed:** Google Chrome. ### Demonstration detail: 03:37:24 - Created a directory named dev/codegraph-exploration via terminal prompt. - Launched an instance of Claude Code. - Submitted a query targeting repository optimization models to test context layout limits. **Tools observed:** Ghostty, Claude Code v2.1.212. **Command or prompt observations (not a verified recipe):** ```text take dev/codegraph-exploration clx ``` Reference ID: factory-markdown-flows-discussion Topic: Execution Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Markdown flows as a repeatable control surface — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface. ## Quick start ``` text npx mdflow init -y # starter roster + .mdflow.yaml, no engine calls md # Flow Workbench: one searchable launcher md doctor --json # free, read-only project diagnosis md explain flows/review.md # resolved config + capabilities, nothing executed md flows/review.md # run a flow (stage a change first) md.claude "quick one-off question" # ad-hoc, no file needed ``` ## Prompt library ### Turn a repeated briefing into a flow - Agent: Claude Code (or any coding agent) - Working directory: your project root, after `npx mdflow init -y` - Expected result: a new flow whose `md explain` lists every inline as a capability ``` text I keep re-typing the same briefing at the start of agent sessions. Turn it into an mdflow flow. Create flows/standup.claude.md: frontmatter with a one-line description, then a body that preloads live state with !`command` inlines (git status --short --branch, git log --oneline -5, plus any command I name below), then a short instruction section telling the agent to work only from the preloaded context. Tell the agent the output was captured at prompt-build time so it must not re-run the commands. Then run `md explain flows/standup.claude.md` and confirm ISOLATION reads ON and every inline appears as a command capability. Briefing to encode: <describe your repeated briefing here> ``` ### Audit a flow before you run it - Agent: any coding agent - Working directory: a repo containing `flows/` - Expected result: engine, isolation state, every prompt-build command, token estimate ``` text Audit an mdflow flow before I run it. Run `md doctor --json` and `md explain <flow path>` (both are free and execute nothing). Report: which engine the flow resolves to and why (flag, env var, filename, frontmatter, config, or default); whether ISOLATION is ON; every command capability that will execute at prompt-build time; and the estimated token usage. Flag any capability that reaches the network or mutates files. Flow to audit: <path> ``` ### Walk the evolve loop instead of hand-editing - Agent: any coding agent - Working directory: a repo where a flow just disappointed you - Expected result: an off-path proposal with an outcome word; the flow file untouched until apply ``` text A flow just gave a bad result. Do NOT edit the flow file. Instead: 1) Record it with `md feedback <flow path> "<what went wrong>"` and show me the durable fb_ id. 2) Run `md eval <flow path> --plan` and `md evolve plan <flow path>` (both free) and summarize the evidence, verification plan, and cost. 3) Only if I say go: run `md evolve propose <flow path>`, then `md evolve show <run-id>`, and report the outcome word (verified_improvement, regression_safe, rejected, inconclusive, or capability_rejected) plus the prompt diff. Never run `md evolve apply` without my explicit approval. Flow: <path>. What went wrong: <describe> ``` ## Set it up (agent guide) 1. From your project root, scaffold the roster. This writes `.mdflow.yaml` and five starter flows, each with a sibling eval suite, and invokes no engine: ``` text npx mdflow init -y ``` 2. Create the standup flow. This is the whole trick: the `` !`command` `` inlines run at prompt-build time, so the agent's first token arrives with git state, terminal panes, and tickets already in front of it. ``` text --- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. ``` 3. Inspect it without executing anything, then run it: ``` text md explain flows/workshop-standup.claude.md # expect ISOLATION: ON (default) md flows/workshop-standup.claude.md # prints your standup ``` **Success check:** the project parses cleanly with all six flows registered. ``` text md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)' ``` ``` text flows: 6 structuralErrors: 0 ``` Fallback: if `structuralErrors` is non-zero, check whether the errors are `CONFIG_INVALID` from a pre-existing global `~/.mdflow/config.yaml` rather than from the flows — an invalid global config fails this check even when every flow is clean. Verify per-flow with `md explain flows/<name>.md` instead. ## Attachments — install these flows Both flows discussed on these pages are hosted on this site as raw markdown attachments. `md install` pulls a remote flow straight into your project's registry (npx-style; first use asks you to trust the domain). Reversible with `md remove <name>`; list what you have with `md list`. The pane-aware standup flow (this section's money artifact): ``` text md install "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" ``` The captured this-or-that Elo voting loop (the flow from the [Session Replay](https://walnut-virtue-6d22.here.now/replay.html)'s final beat): ``` text md install "https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw" ``` Prefer plain files in `flows/`? Fetch the raw attachments directly: ``` text mkdir -p flows curl -fsSL "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" -o flows/workshop-standup.claude.md curl -fsSL "https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw" -o flows/this-or-that.md ``` Note: `this-or-that.md` injects taste records via `@../…/RESULTS.md` includes that exist in the workshop repo — outside it, point those includes at your own vote records. Audit either flow for free with `md explain`. ## Prefer skills? Every flow has a skill twin If your stack runs on [agent skills](https://www.skills.sh/) rather than mdflow, every flow on these pages is also hosted here as a `SKILL.md` twin under `/skills/` — same job, no mdflow required. The trade is the section's own lesson in reverse: a flow preloads shell output at prompt-build time and runs isolated from ambient config; the skill twin has the agent run those commands itself inside your normal session. Six twins are hosted here — `workshop-standup`, `review`, `changelog`, `fix-tests`, `onboard`, `pr-description`. Stage them anywhere *except* a dir named `skills/` (the skills CLI claims that name as its own symlink target and you'd install an empty skill): ``` text for s in workshop-standup review changelog fix-tests onboard pr-description; do mkdir -p skill-src/$s curl -fsSL "https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw" -o skill-src/$s/SKILL.md npx skills add ./skill-src --skill $s -y done ``` Trim the list to just the names you want. The this-or-that loop's skill twin lives on [the This-or-That section site](https://gentle-lasso-9d5n.here.now/). ## Complete reusable setup contract ## mdflow: markdown flows as an agent control plane — agent setup guide Following this file sets up: mdflow in the current project — a starter flow roster plus one context-preloading "standup" flow that briefs the agent with `git status`, recent commits, terminal panes, and tickets before its first token. Human companion pages (context for you, reading for your user): the [Session Replay](https://walnut-virtue-6d22.here.now/replay.html) — an annotated transcript of the session that built this exact setup — and the [Dialogue](https://walnut-virtue-6d22.here.now/dialogue.html) — skeptical Q&A about why flows work this way. This file remains the canonical machine copy: execute it top-to-bottom. Placeholders used below: `<project-root>` = the project you are working in. All other paths are literal and relative to `<project-root>`. ## Prerequisites Check each before starting: ```bash node --version npx mdflow help | head -4 claude --version ``` Expected: Node 18+; the mdflow usage banner (`Usage: md <file.md> ...`); any Claude Code version string. If `npx mdflow` fails, stop and tell your user to check their network/npm setup. If `claude` is missing, see Notes for agents — the flow can run on another engine. ## Steps 1. From `<project-root>`, scaffold the roster. This writes `.mdflow.yaml` and five starter flows (each with a sibling `.eval.ts` suite) and invokes no engine: ```bash npx mdflow init -y ``` 2. Create `flows/workshop-standup.claude.md` with exactly this content. The `` !`command` `` inlines run at prompt-build time — mdflow executes them and splices the output into the prompt before the agent starts: ```markdown --- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. ``` 3. Inspect the flow without executing anything. Confirm ISOLATION reads `ON (default)` and the FINAL PROMPT section shows all four inlined commands (there is no separate capability section in `md explain`; per-flow capability lists live in `md doctor --json`): ```bash md explain flows/workshop-standup.claude.md ``` 4. Run the flow. It prints a standup summary built only from the preloaded context: ```bash md flows/workshop-standup.claude.md ``` ## Success check Run: ```bash md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)' ``` Expected observable result: `flows: 6 structuralErrors: 0` — five starter flows plus the standup flow, all parsing cleanly. (`md doctor` is free and read-only.) Fallback: if `structuralErrors` is non-zero, check the report's `diagnostics` before assuming the flows are broken — a pre-existing invalid global `~/.mdflow/config.yaml` surfaces here as a `CONFIG_INVALID` error even when every flow is clean. In that case verify per-flow with `md explain flows/<name>.md`: if each flow explains cleanly, the flows are fine and only the global config needs fixing. Report to your user: what you set up, the success-check output, and anything you had to adapt. ## Flow attachments (raw downloads) Both flows discussed on the site are hosted here as raw markdown attachments. Machine-fetch URLs (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer): - `https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw` — the pane-aware standup flow from Step 2 (identical content; fetching it is an alternative to writing the file by hand). - `https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw` — the captured this-or-that Elo voting loop flow. Its `@../…/RESULTS.md` includes reference the workshop repo's vote records; outside that repo, repoint them at your user's own records before running. Instead of writing Step 2's file manually you may run, from `<project-root>`: ```bash mkdir -p flows curl -fsSL "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw" -o flows/workshop-standup.claude.md ``` `md install "<url>?raw"` also works and registers the flow in the project registry instead of `flows/` (reversible with `md remove <name>`). ## Skill twins (if the user prefers agent skills over flows) Every flow discussed on the site also ships as a skills.sh-format `SKILL.md` twin hosted under `/skills/` — same job, no mdflow required. The difference: a flow preloads shell output at prompt-build time and runs isolated; the skill twin instructs the agent to run those commands itself in the normal session. Available names: `workshop-standup`, `review`, `changelog`, `fix-tests`, `onboard`, `pr-description` (the this-or-that twin is hosted at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`). Machine-fetch URL pattern (`?raw` required): `https://walnut-virtue-6d22.here.now/skills/<name>/SKILL.md?raw`. To install for your user (stage anywhere EXCEPT a dir named `skills/` — the skills CLI claims that name and you'd install an empty skill): ```bash for s in workshop-standup review changelog fix-tests onboard pr-description; do mkdir -p skill-src/$s curl -fsSL "https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw" -o skill-src/$s/SKILL.md npx skills add ./skill-src --skill $s -y done ``` Trim the loop to the names the user wants. Only install skills when the user prefers them over flows — the flows remain the primary artifact of this section. ## Notes for agents - If `md` is not on PATH, substitute `npx mdflow` for `md` in every command above (`md setup` configures PATH and aliases for the user's shell). - The flow degrades gracefully by design: the `herdr` and `linear` inlines are guarded with `2>/dev/null || echo "..."`, so machines without those tools get placeholder lines in the prompt instead of a failed run. - The `.claude.md` filename pins the claude engine. If the `claude` CLI is not installed, name the file `flows/workshop-standup.md` instead — it will use the project default engine from `.mdflow.yaml` (`pi`). Check `engines.installed` in `md doctor --json` to see what is available. - In a directory with no git repo, the git inlines print an error/placeholder line into the prompt. The flow still runs; the standup will just say so. - Eval verdicts in `md doctor --json` read `Unverified` until a full eval receipt is recorded. That is a missing receipt, not an error — `structuralErrors: 0` is the success signal here. - Re-running `npx mdflow init -y` leaves an existing roster untouched; it is safe in a project that already has `flows/`. Reference ID: factory-markdown-flows-practice Topic: Execution Sources: - [Markdown flows as a repeatable control surface](https://walnut-virtue-6d22.here.now/) - [Public setup contract](https://walnut-virtue-6d22.here.now/agent.md) --- # Markdown flows as a repeatable control surface — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The Q&A Isn't a flow just a saved prompt? A saved prompt is frozen text. A flow executes while the prompt is being *built*: every `` !`command` `` inline runs at prompt-build time and its output is spliced in, so the agent's first token arrives already knowing your branch, your terminal panes, your tickets. Here is the one this section's demo actually runs — lift it: ``` text --- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. ``` And it's a file in your repo — versioned, diffable, reviewable like any other code. This flow is also a downloadable attachment — the install block is on the [section guide](https://walnut-virtue-6d22.here.now/index.html#attachments-install-these-flows). Why preload? My agent can run `git status` itself. It can — for a tool-call round trip, and only if it decides to. Preloading makes the briefing deterministic: never skipped, never reordered, already in the prompt. The production version of this pattern runs a preload script that fetches workshop ticket buyers and current calendar attendees, prints the computed diff as markdown, and then tells the agent: fetched moments ago — do *not* re-fetch. One detail worth stealing: the script exits 0 even on failure and prints a `PRELOAD ERROR` section instead, so the error lands inside the prompt and the agent relays it and stops rather than dying silently. I've spent months on my CLAUDE.md, hooks, and MCP servers. A flow throws all that away? Deliberately — by default. A flow that summarizes a standup doesn't need your memory files, plugin lists, or MCP servers; hauling them in costs context and blurs focus. mdflow strips ambient config using each engine's own flags — claude gets `--safe-mode --no-session-persistence`, codex `--ignore-user-config --ephemeral`, gemini `--extensions none`, copilot `--no-custom-instructions`. Captured from this very project: ``` text ISOLATION ON (default) — ambient engine context is disabled; host capabilities remain available safe-mode: true no-session-persistence: true (opt out with _isolated: false) ``` Anything a flow genuinely needs, it declares in frontmatter; `_isolated: false` opts back into ambient. Straight caveat: this strips *context*, it is not a host sandbox — the inline commands and the engine still reach your filesystem, network, and credentials. What does a run cost me before I've even seen what it will do? Nothing to look. The two audit commands are free and execute no engine, no inline, no hook: ``` text md explain flows/workshop-standup.claude.md # engine + why, isolation, every inline, token estimate md doctor --json # whole-project diagnosis, read-only ``` `md explain` on the standup flow reports which engine won and why (the `.claude.md` filename), every prompt-build command as a declared capability, and an estimated 174 tokens — 0.1% of the context window. If your command shows up in the capability list, the context will land. Sixty flows later, how do I find anything? Bare `md`. It opens the Flow Workbench: one searchable list of everything runnable, each entry labeled with its provenance — `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH`. My machine has roughly sixty-five `flow-*` commands on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh` — each a globally installed specialist that preloads its *entire* config domain plus a mission, trust boundary, and mutation policy on every single run. The installed `flow-zsh` file is printed complete on the [section guide](https://walnut-virtue-6d22.here.now/index.html) — study its anatomy, don't paste it. A flow gives a bad answer — I just edit the file, right? That's how flows regress silently. Instead, record the failure and let the eval suite — not your memory — decide whether a fix is real: ``` text md feedback flows/review.md "missed the renamed-file regression" md eval flows/review.md --plan # free cost preview of the eval suite md evolve plan flows/review.md # free: evidence, verification, cost, writes md evolve propose flows/review.md # off-path proposal; source unchanged md evolve show <run-id> # decision, capability diff, prompt diff md evolve apply <run-id> # atomic, explicit, reversible ``` The canonical file stays byte-identical until an explicit apply, and the outcome vocabulary is honest: `verified_improvement` means a feedback-linked case failed on the old prompt and passed on the new one; `regression_safe` means guardrails held but your reported problem wasn't proven fixed. Do you actually work this way, or is this a workshop demo? This repo answers that itself. The Elo-voting process that chose the very format of this page was captured as a flow — `flows/this-or-that.md` at the workshop repo root, written from that session the day before the workshop. It encodes the whole round (frame the axis, scaffold the duel harness, generate distinct options, bank the taste rules) and re-injects the accumulated vote record fresh on every run via `@`-includes. Auditing it is free: `md explain flows/this-or-that.md`. In prior sessions the same week, a Stripe-to-calendar sync workflow became a flow the same way. Flows aren't the demo — they're how the demo got made. Reference ID: factory-markdown-flows-questions Topic: Execution Sources: - [Markdown flows as a repeatable control surface — questions and tradeoffs](https://walnut-virtue-6d22.here.now/dialogue.html) --- # Markdown flows as a repeatable control surface — reference patterns Extended explanations, comparisons, experiments, and practical actions for the same operating pattern. ## Abstract Every fresh agent chat starts blind. You re-explain the repo, the tickets, and the terminal state, and you pay context for config the task never needed. mdflow makes each repeatable job a markdown file: shell output is inlined before the agent's first token, ambient config is stripped by default, and prompt changes go through evals and reviewable proposals. These notes trace each claim to a file or captured command in the demo project. They do not claim benchmark results, and the demo project's own eval verdicts are still unverified. ## Notice what a blind agent session costs You open an agent, and the first minutes go to briefing: what branch you are on, which panes are running, which ticket this serves. Next session, you type it all again. The easy mistake is to treat that briefing as free. It is not. It costs your time, and the agent's context window fills with your ambient setup before work starts. mdflow's answer is one markdown file per repeatable job — a "flow" — kept in the repo, runnable on any installed engine, and inspectable before it executes (S1). [1](https://walnut-virtue-6d22.here.now/#note-1) 1\. The engine is environment, not ceremony. Resolution order from S1: `--engine` flag, then `MDFLOW_ENGINE`, then the filename (`review.claude.md`), then frontmatter `engine:`, then project config, then the built-in default, pi. [↩](https://walnut-virtue-6d22.here.now/#note-ref-1) The project README states the thesis directly: mdflow is "a Git-native control plane for repeatable agent work" — define the job as markdown, run it, inspect its inputs, and gate prompt revisions with behavioral evals (S1). The contrast to hold on to: a chat session is a performance you repeat; a flow is a script you version. When you catch yourself typing the same briefing twice, that job wants to be a file. The rest of these notes show what the file buys you: preloaded context, isolation, and a change process with receipts. ## Preload context, then verify it landed A flow can embed shell output in its prompt with a `` !`command` `` inline. mdflow runs the command at prompt-build time, so the agent's very first token arrives with the results already in front of it. The likely mistake is to instead tell the agent "run git status first" — now you pay a tool-call round trip, and the agent may skip or reorder it. Preloading removes that choice. ``` text --- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- ## Repo state (git) !`git status --short --branch` ## Terminal workspace (herdr panes) !`herdr api snapshot | head -40` ## Open tickets (linear) !`(ticket CLI call — placeholder in the public demo)` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. ``` **Figure 1.** The demo project's `flows/workshop-standup.claude.md`, lightly condensed (S5). Source evidence, not a mock-up: `git status`, a terminal-pane snapshot, and a ticket lookup all run before the agent starts, so it "knows about all the panes" at token one. The same pattern scales past one-liners. A production flow on this machine runs a preload script that fetches workshop ticket buyers from the payment provider and current calendar attendees, prints the computed diff as markdown, and then tells the agent: the data below was fetched moments ago — do not re-fetch (S6). [2](https://walnut-virtue-6d22.here.now/#note-2) 2\. A detail worth stealing from S6: the preload script exits 0 even on failure, printing a `PRELOAD ERROR` section instead. The error lands inside the prompt, so the agent can relay it and stop, rather than the flow dying silently. [↩](https://walnut-virtue-6d22.here.now/#note-ref-2) Your test loop: write the inline, then run `md explain flows/your-flow.md`. Explain resolves the full configuration and lists every inline as a declared capability — without executing anything. If the capability list shows your command, the context will land. In this project, `md doctor --json` reports the standup flow's capabilities as exactly the four inlined commands (S5). That is the feedback signal; if a command is missing, fix the backticks and re-check. The boundary: preloading captures state at launch. It does not keep updating — a long-running agent that needs fresh state must still fetch it. ## Explain what a global specialist flow carries Some jobs recur across every project: keyboard config, shell config. On this machine, roughly sixty-five `flow-*` commands sit on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh`, and more — each a globally installed specialist flow (S4). You should be able to explain why these beat a generic assistant, because the reason is the whole design. The specialist pattern declares a mission, an untrusted-evidence boundary, a narrow inspection command map, ownership rules, worked examples, mutation approval, and exact verification. Keep the operating instructions project-specific rather than copying another machine’s private configuration. **Figure 2.** Condensed frontmatter of the installed `flow-zsh` flow (S4). Derived display: excerpted and abridged from the real file; ellipses mark removed sections. The full file maps the entire modular zsh config — owner modules, lazy stubs, tests — into a command map the agent gets every single run. The specialist's edge is not a smarter model — it is that the whole config domain is preloaded as navigable structure, plus a mission, a tool-output trust boundary, and a mutation policy that demands verification after every edit (S4). [3](https://walnut-virtue-6d22.here.now/#note-3) 3\. `flow-karabiner`'s mutation policy in S4: read the config, make the smallest edit, run the compiler (`goku`), then grep the generated JSON to prove the mapping exists. Edit, compile, verify — encoded in the prompt itself. [↩](https://walnut-virtue-6d22.here.now/#note-ref-3) The weak move is a monolithic "dotfiles assistant" that knows a little about everything and answers from memory. The strong move is one flow per domain, each opening with "never answer from memory" and a first-step inspection command (S4). When you can explain that distinction — domain map in the prompt, evidence before answers, verification after edits — you can write your own specialist. The evidence stops here, though: these files show the design, not measured accuracy gains. ## Choose one launcher for every flow Sixty-five global flows plus project rosters create a discovery problem: which flows exist here, and which can you trust? Bare `md` answers it. It opens the Flow Workbench — one searchable list of project flows, global flows, registry installs, and runnable markdown found on PATH, each labeled with its provenance: `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH` (S1). Setting up a new project is one deterministic command. `npx mdflow init` creates a starter `flows/` roster and `.mdflow.yaml` with zero engine invocations, and repeat runs leave an existing roster untouched (S1). This demo project ran exactly that: twelve files, five starter flows, each with a sibling eval suite (S5). ``` text # In any repo: npx mdflow init -y # starter roster + .mdflow.yaml, no engine calls md # Flow Workbench: one searchable launcher md doctor --json # free, read-only project diagnosis md explain flows/review.md # resolved config, nothing executed md.claude "quick one-off question" # ad-hoc, no file needed ``` **Figure 3.** The adoption path, assembled from commands documented in S1/S7 and executed in this project (S5). Derived display: sequence chosen editorially; every command exists verbatim in `md --help`. **Engine default** The starter roster's flows default to the **pi** engine via `.mdflow.yaml`; the demo's standup flow pins claude through its filename instead (S5). If you demo with a different engine installed, the same files run — but do not present pi output and claude output as interchangeable. Your choice rule: reach for bare `md` when you want to find or run existing work; reach for `md create` or `init` when a briefing repeats and no flow exists yet. The signal that the setup worked is `md doctor --json` reporting your flows with zero structural errors — this project's captured run reports six flows, zero structural errors (S5). ## Compare an ambient run with an isolated run Your interactive agent session hauls everything you have configured: memory files, hooks, MCP servers, skill lists, project instructions. A flow that reviews a diff needs none of it. The mistake is assuming that ambient baggage is harmless; it spends context on every run and can steer the agent off the declared task. mdflow strips ambient engine context by default, using each engine's own verified flags — claude runs with `--safe-mode --no-session-persistence`, codex with `--ignore-user-config --ephemeral` plus a zeroed project-doc budget, gemini with `--extensions none`, copilot with `--no-custom-instructions` (S1). [4](https://walnut-virtue-6d22.here.now/#note-4) 4\. Anything the flow genuinely needs — a skill, an MCP server, extra context — is declared explicitly in frontmatter, and `_isolated: false` opts back into ambient. Explicit beats implicit either way. [↩](https://walnut-virtue-6d22.here.now/#note-ref-4) ``` text ---------------------------------------------------------------------- ISOLATION ---------------------------------------------------------------------- ON (default) — ambient engine context is disabled; host capabilities remain available safe-mode: true no-session-persistence: true (opt out with _isolated: false) ``` **Figure 4.** Captured output of `md explain flows/workshop-standup.claude.md` in this project (S5). Source evidence: isolation is on without any frontmatter asking for it. **Isolation is not a sandbox** Context isolation strips prompts, hooks, and extensions — it does **not** confine the host. The flow's inline commands and the engine still reach your filesystem, network, environment, and credentials (S1). And engines with no isolation controls (droid, cursor-agent, agy) run ambient and warn rather than pretend (S1). Run the comparison yourself: `md explain` any flow and read the ISOLATION block, then run the same job in your normal interactive session and watch what extra material loads. The isolated run's prompt is exactly what the file declares — that is the point. Claims about token savings stop at "ambient material is not loaded"; the sources publish no percentage, so do not quote one. ## Adjust a flow with feedback, not hand edits A flow that never changes goes stale; a flow edited by vibes regresses silently. The tempting shortcut is to tweak the prompt in place after a bad run and move on. mdflow's evolve loop replaces that with a proposal process that leaves the canonical file byte-identical until you explicitly apply a change (S2). ``` text md feedback flows/review.md "missed the renamed-file regression" md eval flows/review.md --plan # free cost preview of the eval suite md evolve plan flows/review.md # free: evidence, verification, cost, writes md evolve propose flows/review.md # off-path proposal; source unchanged md evolve show <run-id> # decision, capability diff, prompt diff md evolve apply <run-id> # atomic, explicit, reversible ``` **Figure 5.** The evolve loop, quoted from the evolve documentation's quick start (S2). Source evidence: feedback gets a durable `fb_…` ID; rejected attempts do not consume the underlying problem. The outcome vocabulary is deliberately honest. `verified_improvement` means a feedback-linked case failed on the current prompt and passed on the proposal with clean guardrails; `regression_safe` means guardrails passed but the reported problem was not proven fixed; `rejected`, `inconclusive`, and `capability_rejected` cover the rest (S2). **Unverified in this demo** Every flow in this demo project currently reports the eval verdict **Unverified** — the suites exist, but no full eval receipt has been recorded yet (S5). Present the loop as the mechanism it is; do not imply this roster has already earned `verified_improvement` badges. Your adjustment habit: when a flow disappoints, file `md feedback` in the moment — it is free and durable — and let the eval suite, not your memory, decide whether a proposal actually fixed it. The observable signal is the outcome word on the proposal. If it says `regression_safe`, treat the fix as unproven and keep the feedback open. ## Practical action In the repo where you brief agents most often, run `npx mdflow init -y`, then `md doctor --json` to confirm the roster parses with zero structural errors. Take the one briefing you typed twice this week and make it a flow: put the explanation in the body and the state-gathering in `` !`command` `` inlines. Check your work with `md explain` — the ISOLATION block should read ON and the capability list should name every inline. When the flow first disappoints, do not hand-edit: file `md feedback`, then walk the evolve loop and read the outcome word before trusting the change. If your team should discover flows too, opt in explicitly with `md roster sync --agents`. Reference ID: factory-markdown-flows-reference-patterns Topic: Execution Sources: - [Prepared module reference](https://walnut-virtue-6d22.here.now/) --- # Markdown flows as a repeatable control surface — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session You Set up mdflow in this project. No engine calls — just the scaffold. Agent ``` text npx mdflow init -y ``` Twelve files landed, zero engine invocations: ``` text .mdflow.yaml # engine: pi, evolve mode: suggest flows/README.md # roster operator card flows/review.md + review.eval.ts flows/changelog.md + changelog.eval.ts flows/pr-description.md + pr-description.eval.ts flows/onboard.md + onboard.eval.ts flows/fix-tests.md + fix-tests.eval.ts ``` First beat is always the scaffold. `init` is deterministic — it never overwrites an existing roster, never calls an engine, and every starter flow arrives with a sibling eval suite on day one. You I open every session re-explaining the same three things: the branch, which panes are running, what ticket I'm on. Make that a flow — `flows/workshop-standup.claude.md`. Preload git status, the last five commits, a herdr pane snapshot, and a tickets line, then tell the agent to work only from what was preloaded. Agent Wrote the flow. The whole trick is in lines like these — `` !`command` `` inlines that mdflow executes while *building* the prompt, splicing their output in before the agent exists: ``` text ## Repo state (git) !`git status --short --branch` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ``` The body opens by telling the agent the output was captured at prompt-build time, before it started, and must not be re-run. Complete file lands at the end of this replay. The agent never spends a tool-call round trip on `git status` — and never skips or reorders it. Every inline is guarded (`2>/dev/null || echo "…"`), so a machine without herdr gets a placeholder line in the prompt instead of a failed run. You Before anything runs: prove exactly what this file will do. Agent Ran `md explain flows/workshop-standup.claude.md` — it resolves the full configuration and executes nothing. Captured output from this project (middle sections elided): ``` text COMMAND Resolved command: claude Source: Filename pattern (.claude.md) ISOLATION ON (default) — ambient engine context is disabled; host capabilities remain available safe-mode: true no-session-persistence: true (opt out with _isolated: false) FINAL CLI ARGS --print --safe-mode --no-session-persistence --model sonnet TOKEN USAGE Estimated tokens: 174 Context limit: 200,000 Usage: 0.1% ``` Two reveals in one audit. Engine: the `.claude.md` filename pinned claude — the full ladder is `--engine` flag → `MDFLOW_ENGINE` → filename → frontmatter → project config → default (pi). Isolation: ON without any frontmatter asking for it — no CLAUDE.md, hooks, or MCP leak in. (Context isolation, not a host sandbox — the inlines and the engine still reach your filesystem and network.) You Run it. Agent ``` text md flows/workshop-standup.claude.md ``` The standup printed with the agent already briefed: it named the branch and dirty files from the git inline, the visible panes from the herdr snapshot, and the ticket placeholder line — without making a single tool call. Everything rode in on the prompt. The production version of this pattern goes further: a flow in `~/.mdflow/` runs a preload script that fetches workshop ticket buyers and calendar attendees, prints the computed diff as markdown, and tells the agent "fetched moments ago — do NOT re-fetch." The script exits 0 even on failure, printing a PRELOAD ERROR section instead, so the error lands inside the prompt and the agent relays it and stops. You Prove the project is still healthy. Agent ``` text md doctor --json | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));console.log("flows:",d.summary.flows,"structuralErrors:",d.summary.structuralErrors)' ``` ``` text flows: 6 structuralErrors: 0 ``` `md doctor` is free and read-only. Its JSON also lists every flow's declared capabilities — the standup flow reports exactly its four inlined commands. Eval verdicts in this project read `Unverified — no full eval receipt has been recorded`. That's a missing receipt, not an error; `structuralErrors: 0` is the success signal here. You One more. The voting process that chose this page format — capture it as a flow so we never re-litigate it. Agent Done in a prior session: `flows/this-or-that.md` now lives at the workshop repo root, captured from the very session that picked this two-page format. It encodes the whole Elo round — frame the axis, scaffold the lab, generate structurally distinct options, QA, hand over, bank the results — and injects the accumulated taste record fresh on every run: ``` text --- description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules _inputs: [_question, _subject] _interactive: true --- … ## Accumulated taste record (injected fresh each run — read before generating options) @../authoring-lab/RESULTS.md @../07-variations/template-lab/RESULTS.md ``` `md explain flows/this-or-that.md` is free and read-only if you want to audit it yourself. Flows evolve, but never by vibes: when one disappoints, record `md feedback` (a durable `fb_…` ID), preview with `md eval --plan`, and let `md evolve plan → propose → apply` do the rest. The source file stays byte-identical until an explicit apply. Agent The file this session produced, complete: ``` text --- description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true --- You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. ``` File landed. Versioned, inspectable for free, isolated by default. Both this flow and `this-or-that.md` are downloadable attachments — the install block is on the [section guide](https://walnut-virtue-6d22.here.now/index.html#attachments-install-these-flows). Total session: six prompts, one paid run. The pattern the transcript demonstrates — scaffold → preload → audit → run → verify → capture — repeats for every briefing you catch yourself typing twice. Reference ID: factory-markdown-flows-worked-example Topic: Execution Sources: - [Markdown flows as a repeatable control surface — worked example](https://walnut-virtue-6d22.here.now/replay.html) --- # Narrow Imp agents and routing: practical reference ## Agent Setup Prompt ```text Set up the local Imp/codex-daemons workflow for narrow, tool-shaped agent work. Act as a setup and verification agent: inspect the local implementation, configure only the required files, prove each piece works, and do not run broad agent work until the setup checks pass. 1. Locate the local Imp/codex-daemons checkout or install source. Before changing anything, inspect the setup-relevant files: `README.md`, `imp.ts`, `imps.ts`, `docs/PROMPT.md`, `docs/ISOLATION.md`, `lib/defaults.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts`, `imps/imp-rg`, `imps/imp-git`, `imps/imp-github-examples`, `test/router.test.ts`, `test/parseargs.test.ts`, and `test/cli-smoke.test.ts`. 2. Check current command availability and health: - `command -v imp` - `command -v imps` - `imp -l` - `imps list` - `imps ps` - `imps doctor` - `imp --which "find checkout disabled-state code paths"` Report missing commands, stale paths, failed health checks, or auth problems before proceeding. 3. Install or repair the local `imp` and `imps` entrypoints only according to the project's own docs and package scripts. Preserve the one-file Imp command model: each `imp-<tool>` command should stay narrow, own one tool, run that tool before answering, and return command evidence. Do not turn an Imp into a general Codex agent. 4. Verify isolated runtime behavior. Confirm each Imp uses a temporary or narrow `CODEX_HOME`, symlinks only the required `auth.json` for login, replaces broad base instructions with the Imp prompt, disables broad project-doc loading, disables memories, keeps MCP servers empty unless a specific Imp requires one, disables web search unless the Imp owns that behavior, disables broad app/plugin surfaces, and removes unused schemas or unrelated tools. Use `imps doctor` and implementation inspection as evidence. 5. Respect privacy boundaries. Do not copy full private Codex config, secret helper files, provider API variables, cookies, tokens, private endpoints, full `env` output, or full machine-local startup files into reports or isolated homes. If auth is needed, use the project's isolated auth symlink pattern rather than copying secret-bearing config. Summarize sensitive findings without printing secret values. 6. Verify direct Imp commands before hook work: - `imp-rg "find TODOs in src"` - `imp-rg --run "find TODOs in src"` - `imp-rg -q "find TODOs in src"` - `imp-rg --no-warm "find TODOs in src"` - `imp-rg --serve` only if a foreground warm-server check is appropriate, then stop it - `imp-rg --run --effort minimal "find TODOs in src"` Confirm the output includes exact command evidence and file:line matches where applicable. If an Imp answers from memory or without tool evidence, stop and report it. 7. Verify router and compound routing: - `imp --which "what changed in git since yesterday?"` - `imp --which "find the TODOs in src; then commit everything"` - `imp --which "find TODOs in src after that summarize git changes"` Confirm strong connectors such as `;`, `.`, `then`, `after that`, and `afterwards` split routes correctly. Confirm bare `and` is not treated as a strong splitter unless the current implementation explicitly says otherwise. 8. Verify fleet management and warm mode: - `imps list` - `imps ps` - `imps doctor` - `imps stop imp-rg` if a test warm process exists - `imps stop --all` only if safe for the current local session - `imps evolve` - `imps evolve imp-rg` Treat evolution suggestions as review material only. Do not auto-apply changes that broaden an Imp into a general agent. 9. Set up the `UserPromptSubmit` hook for dash-prefix Imp prompts only after the command and isolation checks pass. Review and adapt these examples before installing: - `hooks/imp-user-prompt-submit.py.template` to `~/.codex/hooks/imp-user-prompt-submit.py` - `hooks/hooks.json.example` merged into `~/.codex/hooks.json` - `hooks/cmux-run-surface.example` to `~/.local/bin/cmux-run-surface` Check existing files first. Review paths, Codex flags, cmux binary location, logging, and current-session lookup before enabling the hook. 10. Verify foreground dash routing. A prompt like `-rg find TODOs in src` should resolve the Imp command, executable path, description, task text, and current cwd, then add route context while letting the main prompt continue. The main agent should use that route context and should not rediscover the Imp with `which`, `where`, `find`, or broad repo search. 11. Verify forked dash routing. A prompt like `--rg find TODOs in src` should block the current prompt, open a forked Codex session in a new cmux pane, normalize the prompt to `-rg find TODOs in src`, and print inspectable cmux ids: workspace, pane, surface, and window. Unknown or ambiguous Imp names should block and ask for a clearer Imp name. 12. Confirm the fork command uses direct Codex fork syntax with `--` before the dash-starting prompt, for example: `codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox fork <source-session> -- '-rg find TODOs in src'`. The `--` before the prompt is required so `-rg` is not parsed as a Codex option. Do not use resume-based helpers for dash-starting prompts. 13. Verify fork inspection from the returned ids: - `cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80` - `cmux top --workspace workspace:<id> --processes --flat --format tsv` - `cmux focus-pane --workspace workspace:<id> --pane pane:<id>` 14. Verify marker-packet handoff with a bounded packet only. Prepare a packet with task, search terms, scope, and required command evidence. Route it with `imp --which`, then run the selected Imp with `--run`. Example: task `find checkout disabled-state code paths`, terms `acceptedTerms`, `selectedShipping`, `canSubmit`, scope `src` and `tests`, required evidence `file:line matches and exact rg commands`. The Imp should return exact commands and evidence only, not product recommendations, file edits, or architecture decisions. 15. Do not run broad product reasoning, code edits, commits, fleet-wide stops, or long-running forked tasks unless the setup checks above pass and the user explicitly asks for that next step. 16. Finish with a concise setup report: files inspected, files changed, commands installed or repaired, hook status, isolation/auth status, warm/fleet status, router and compound-routing results, direct command results, fork inspection result if tested, marker-packet result, privacy-sensitive items skipped, and remaining manual steps. ``` ## Big Idea Phase: Delegation And Review - hand bounded, tool-shaped work to narrow agents before escalating expensive decisions to council review. An Imp is a narrow tool agent that should run the tool before it talks. ## Try This Now Check the Imp roster: `imp -l`. Route a narrow search before running it: `imp --which "find checkout disabled-state code paths"`. Use the foreground dash path when regular Codex should keep the conversation: `-rg find checkout disabled-state code paths`. Use the forked dash path when the bounded task should run in a new cmux pane: `--rg find checkout disabled-state code paths`. Use the chosen Imp only for command evidence; send broad product reasoning back to regular Codex. Imps are single-purpose, isolated Codex agents for common command-line tools. They are not smaller general agents. ```text regular Codex -> broad context, general agent Imp -> narrow context, one tool, faster loop ``` Use regular Codex when the task needs broad reasoning across files, product intent, design, or multiple systems. Use an Imp when the task is tool-shaped: - search this repo - inspect git state - summarize GitHub PRs - query JSON - trim a video - inspect package metadata - find examples on GitHub Closing workflow: ```text Bounded tool question -> choose the right Imp -> run the narrow tool -> preserve command evidence -> return clean results -> hand results back to the broader task ``` ## Files To Inspect Imp implementation references: ```text README.md imp.ts imps.ts docs/PROMPT.md docs/ISOLATION.md lib/defaults.ts lib/isolated.ts lib/imp.ts lib/appserver.ts imps/imp-rg imps/imp-git imps/imp-github-examples test/router.test.ts test/parseargs.test.ts test/cli-smoke.test.ts ``` ## When To Reach For This Use an Imp when the request maps cleanly to one tool. | Use An Imp For | Example | | --- | --- | | repo search | `imp-rg "find checkout disabled state"` | | git state | `imp-git "what changed since yesterday?"` | | GitHub examples | `imp-github-examples "find examples of DESIGN.md"` | | JSON query | `imp-jq --run "count users by plan"` | | video/file command | `imp-ffmpeg "trim first 10 seconds"` | | package metadata | `imp-npm "inspect package scripts"` | Use regular Codex when: - the task spans several tools - code edits are likely - product intent matters - architecture tradeoffs matter - the request is still too vague - the next move is not tool-shaped yet ## How This Used To Work What you used to expect: ```text Every small tool question needs a full Codex session with broad project context. ``` What the workflow gives you now: ```text Tool-shaped work can go to a narrow Imp that runs one tool, returns command evidence, and leaves broad reasoning to regular Codex. ``` What you used to expect: ```text An agent can infer the right tool and explain from memory. ``` What the workflow gives you now: ```text An Imp has one operating rule and command map. It runs the tool first and answers from the output. ``` ## Commands First Start with identity and health checks: ```bash imp -l imps list imps ps imps doctor ``` Check routing without spending a model turn: ```bash imp --which "what changed in git since yesterday?" imp --which "find the TODOs in src; then commit everything" imp --which "find examples of DESIGN.md created in the past 2 months" ``` Expected routing shape: ```text imp-git imp-rg find the TODOs in src imp-git commit everything imp-github-examples ``` Run one Imp interactively: ```bash imp-rg "find TODOs in src" ``` Run one Imp non-interactively: ```bash imp-rg --run "find TODOs in src" ``` Quiet final-answer-only mode: ```bash imp-rg -q "find TODOs in src" ``` Opt out of warm mode: ```bash imp-rg --no-warm "find TODOs in src" ``` Run a warm server in the foreground: ```bash imp-rg --serve ``` Override reasoning effort for one prompt: ```bash imp-rg --run --effort minimal "find TODOs in src" ``` ## Dash-Prefix Imp Routing A common local setup adds a `UserPromptSubmit` hook for Imp prompts. | Prompt Shape | Meaning | What Happens | | --- | --- | --- | | `-<imp> <task>` | foreground Imp route | hook resolves the Imp, adds routing context, and lets the main prompt continue | | `--<imp> <task>` | forked Imp route | hook blocks the current prompt, opens a forked Codex session in cmux, and seeds it with `-<imp> <task>` | | unknown Imp | unsafe route | hook blocks and asks for a clearer Imp name or a new Imp | | ambiguous Imp | unsafe route | hook blocks and shows likely matches | The hook should resolve the Imp command, executable path, description, task text, and current cwd before the main agent starts working. That means the main agent should not waste a turn rediscovering the Imp with `which`, `where`, `find`, or broad repo search. It should use the hook-provided route. ## Foreground vs Forked Imp Requests Use single dash when the main agent should stay responsible for the broader conversation. ```text -rg find checkout disabled-state code paths ``` Use double dash when the Imp task should run separately and the current prompt should not continue. ```text --rg find checkout disabled-state code paths ``` | Use | Pick | Why | | --- | --- | --- | | main agent needs repo or conversation context first | `-<imp>` | hook adds route context; main agent can gather context before invoking the Imp | | bounded tool task should run separately | `--<imp>` | hook opens a forked Codex session in a new cmux pane | | task may require product judgment | regular Codex | not tool-shaped enough yet | | Imp name is unclear | neither | clarify or run `imp --which` | Double dash normalizes to a single-dash prompt inside the fork. ```text --gmail draft a reply -> forked Codex prompt: -gmail draft a reply ``` Double dash does not mean "run the Imp harder." It means "fork the current Codex conversation and seed the fork." ## Hook Setup Files Common local install targets: ```text ~/.codex/hooks/imp-user-prompt-submit.py ~/.codex/hooks.json ~/.local/bin/cmux-run-surface ``` Workshop package examples live under: ```text hooks/ ``` Treat these as setup examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing. | File | Install Target | Purpose | | --- | --- | --- | | `hooks/imp-user-prompt-submit.py.template` | `~/.codex/hooks/imp-user-prompt-submit.py` | parse dash-prefix prompts and route or fork Imps | | `hooks/hooks.json.example` | merge into `~/.codex/hooks.json` | register the `UserPromptSubmit` hook | | `hooks/cmux-run-surface.example` | `~/.local/bin/cmux-run-surface` | open a cmux pane and print an inspectable receipt | ## Inspect A Forked Imp Session A successful fork should print cmux ids: ```text cmux workspace: workspace:<id> cmux pane: pane:<id> cmux surface: surface:<id> cmux window: window:<id> ``` Use the printed ids: ```bash cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80 cmux top --workspace workspace:<id> --processes --flat --format tsv cmux focus-pane --workspace workspace:<id> --pane pane:<id> ``` | Command | Use It To | | --- | --- | | `cmux read-screen ...` | inspect recent fork output | | `cmux top ...` | check running processes in the workspace | | `cmux focus-pane ...` | jump back to the forked pane | The fork path should use direct Codex fork with `--` before the prompt: ```bash codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox \ fork <source-session> -- '-gmail draft ...' ``` The `--` before the prompt prevents `-gmail` from being parsed as Codex options. ## Router And Compound Routing Use the router when you know the request but not the Imp. ```bash imp "what changed in git since yesterday?" imp "trim the first 10s off intro.mp4" imp git "what changed?" imp --which "list my PRs" ``` Compound routing splits strong connectors: ```bash imp --which "find the TODOs in src; then commit everything" ``` Strong splitters: ```text ; . then after that afterwards ``` Bare `and` should not split by itself. ## Fleet Management List Imps: ```bash imps list ``` See warm processes: ```bash imps ps ``` Stop one: ```bash imps stop imp-rg ``` Stop all: ```bash imps stop --all ``` Inspect health: ```bash imps doctor ``` Inspect evolution suggestions: ```bash imps evolve imps evolve imp-rg ``` Evolution suggestions are review material. They are not magic self-modification. ## Isolation Model Each Imp runs with a narrow isolated runtime. Important boundaries: | Boundary | Meaning | | --- | --- | | temporary `CODEX_HOME` | isolated runtime folder | | symlinked `auth.json` | login works without copying full config | | replaced base instructions | Imp prompt owns the behavior | | explicit developer instructions | one tool, one operating rule | | project docs disabled | no broad repo instruction loading | | memories disabled | no broad personal memory context | | MCP servers empty | no unrelated tool surface | | web search disabled | unless the Imp specifically owns that behavior | | apps disabled | no broad app/plugin surface | | unused schemas disabled | fewer ways to drift | The point is not restriction for its own sake. The point is a clean tool boundary. ## Warm Mode Warm mode keeps a narrow app-server session ready for faster turns. Concepts: ```text warm app-server socketPath sourceFingerprint thread/start turn/start CODEX_IMP_IDLE_MINUTES ``` Use warm mode when the same Imp will be called repeatedly. Use `--no-warm` when you want a fresh one-shot run: ```bash imp-rg --no-warm "find TODOs in src" ``` If warm behavior looks stale: ```bash imps ps imps stop imp-rg imps doctor ``` ## Prompt Design Pattern A strong Imp prompt has: ```text Operating rule Command map Worked examples Error recovery Output rules ``` Template: ~~~markdown # imp-<tool> ## Operating Rule Run `<tool>` via `exec_command` before any final answer. Do not answer from memory. ## Command Map | User Intent | Exact Command | | --- | --- | | find text | `<tool> ...` | | list status | `<tool> ...` | | inspect help | `<tool> --help` | ## Worked Examples ### Example 1 User request: ```text find checkout disabled state ``` Command: ```bash rg -n "disabled|canSubmit|isSubmitting" src tests ``` ## Error Recovery | Error Text | Next Command | | --- | --- | | command not found | inspect install / PATH | | no results | broaden terms once | | unknown flag | run help | ## Output Rules - show exact command evidence - return file:line matches when available - do not invent results - say when the tool found nothing ~~~ ## Tool Packet To Imp Start from a bounded tool packet: ```markdown # Imp Tool Packet - task: - find checkout disabled-state code paths - search terms: - acceptedTerms - selectedShipping - checkout disabled - scope: - src - tests - required verification: - return file:line matches - return exact commands used ``` Route it: ```bash imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled" ``` Run the narrow tool: ```bash imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and the exact rg commands used." ``` Good Imp request: ```text Here is a bounded tool packet. Search for code paths related to checkout disabled state. Use these terms: acceptedTerms, selectedShipping, checkout disabled. Stay inside src and tests. Return file:line matches and the exact rg commands used. Do not propose a fix. ``` Bad Imp request: ```text Fix checkout. ``` ## Ask The Agent This Route a tool packet: ```text Use Imps for the tool-shaped part of this task. Given this bounded tool packet, first run `imp --which` to choose the narrow Imp. The packet points at checkout disabled state and includes terms `acceptedTerms`, `selectedShipping`, and `canSubmit`. Use the chosen Imp to return command evidence only. Do not edit files. ``` Search with `imp-rg`: ```text Use `imp-rg`. Find every place checkout disabled state is computed. Search for `disabled`, `canSubmit`, `isSubmitting`, `acceptedTerms`, and `selectedShipping` under `src` and `tests`. Return file:line matches and the exact commands used. ``` Inspect git state: ```text Use `imp-git`. Summarize current dirty state and recent commits. Return commands and evidence. Do not stage, commit, or modify files. ``` Design a new Imp: ```text Design an Imp for a project-specific deploy CLI. It must use exactly one tool, run help/status before answering, include a command map, worked examples, error recovery, and output rules. Explain when this should remain regular Codex instead. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | Imp roster visible | `imp -l` or `imps list` | | fleet healthy | `imps doctor` | | route checked | `imp --which "..."` | | direct Imp works | `imp-rg "find TODOs in src"` | | noninteractive works | `imp-rg --run "find TODOs in src"` | | quiet mode works | `imp-rg -q "find TODOs in src"` | | warm state known | `imps ps` | | warm server stopped | `imps stop imp-rg` or `imps stop --all` | | broad work rejected | task returns to regular Codex when not tool-shaped | | command evidence present | Imp output includes exact commands/results | | project safety net passes | `bun test` in the Imp project | | dash hook installed | `-rg find TODOs` adds Imp route context without blocking | | fork hook installed | `--rg find TODOs` blocks current prompt and opens a cmux fork | | Imp path resolved | hook context names `imp-<name>` and executable path | | no rediscovery needed | main agent does not run `which`, `where`, `find`, or broad search for the Imp | | cmux fork inspectable | block message includes workspace, pane, surface, window, and check commands | | dash prompt safe | fork uses `codex fork <session> -- '-imp ...'` | ## If It Goes Wrong ### Router Picks Wrong Imp Check routing first: ```bash imp --which "your request" ``` Then use an explicit route: ```bash imp rg "find TODOs in src" ``` ### Prompt Is Too Broad Bad: ```text fix checkout ``` Better: ```text Use rg to find checkout disabled-state code paths. Return file:line evidence only. ``` If the task still needs product reasoning, send it back to regular Codex. ### Imp Answers Without Tool Evidence Strengthen the operating rule: ```text Run the tool before final answer. Include exact commands and outputs. ``` Add worked examples. ### Warm Server Looks Stale Run: ```bash imps ps imps stop <imp> imps doctor ``` ### Auth Missing Run: ```bash imps doctor ``` Look for `auth.json` status. ### Compound Route Split Wrong Use a strong connector: ```bash imp --which "find TODOs in src; then summarize git changes" ``` Avoid relying on bare `and`. ### Dash Prompt Treated As A Codex Option Bad shape: any helper that creates a fork id and then resumes it with `-gmail draft ...`. The dash-starting prompt can be parsed as command options. Safer fork shape: ```bash codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox \ fork <source-session> -- '-gmail draft ...' ``` The `--` matters. ### Fork Opens But Cannot Be Found Later Use the cmux ids from the block message: ```bash cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80 cmux top --workspace workspace:<id> --processes --flat --format tsv cmux focus-pane --workspace workspace:<id> --pane pane:<id> ``` ### Hook Blocks Unexpectedly Likely causes: - unknown Imp name - ambiguous Imp name - missing `imp-` roster - missing cmux helper - no current Codex session id - cmux pane creation failed Recovery: ```bash imp -l imp --which "your task" imps doctor cmux rpc workspace.current command -v cmux-run-surface ``` ### Do Not Use Resume-Based Fork Helpers For Dash Prompts Avoid helper paths that create a fork id and then resume it with the dash-starting prompt. Use direct `codex fork <source-session> -- '-imp ...'` for the hook path. ### Evolution Suggestion Looks Unsafe Treat it as review material: ```bash imps evolve imp-rg ``` Dismiss or edit manually. Do not accept broad behavior that makes the Imp a general agent. ### Tool Packet Too Vague Sharpen the packet before choosing an Imp: ```text task: search terms: scope: required command evidence: ``` ## References And Resources - Codex Imps project: <https://github.com/johnlindquist/codex-imps> - Imp roster: `imp -l`, `imps list` - Router: `imp --which "..."` - Fleet health: `imps doctor` - Fleet processes: `imps ps` - Stop warm Imps: `imps stop <imp>`, `imps stop --all` - Evolution suggestions: `imps evolve`, `imps evolve <imp>` - Project safety net: `bun test` - Key implementation files: `imp.ts`, `imps.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts` ## Operational boundaries - Configuration isolation is not an operating-system security sandbox. A linked auth file still grants access to authentication material, and the illustrated fork launch explicitly bypasses approval and sandbox protections. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-imp-workflows-reference Topic: Execution Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Narrow Imp agents and routing: practice drills These exercises practice routing narrow tool-shaped work to Imps. ## Exercise 1: Regular Codex Or Imp? Choose `regular Codex` or `Imp`. | Task | Choice | Why | | --- | --- | --- | | Find every place checkout disabled state is computed. | | | | Decide which checkout architecture to use. | | | | Summarize current git dirty state. | | | | Implement saved payment methods. | | | | Query JSON for users by plan. | | | | Trim a video file. | | | | Explain product risk of auth/session rotation. | | | | Find GitHub examples of a file pattern. | | | ## Exercise 2: Check Health Run: ```bash imp -l imps list imps ps imps doctor ``` Fill out: ```markdown # Imp Health - roster visible? yes/no: - warm processes: - doctor status: - auth status: - command that failed: - next check: ``` ## Exercise 3: Route Before Running Run: ```bash imp --which "what changed in git since yesterday?" imp --which "find the TODOs in src; then commit everything" imp --which "find examples of DESIGN.md created in the past 2 months" ``` Fill out: ```markdown # Routing Notes - prompt: - chosen Imp: - compound route? yes/no: - split points: - would you run it? yes/no: - why: ``` ## Exercise 4: Run `imp-rg` Run: ```bash imp-rg --run "find TODOs in src" ``` Quiet mode: ```bash imp-rg -q "find TODOs in src" ``` No warm mode: ```bash imp-rg --no-warm "find TODOs in src" ``` Fill out: ```markdown # imp-rg Notes - command: - files searched: - matches: - exact command evidence present? yes/no: - when to use `--run`: - when to use `-q`: - when to use `--no-warm`: ``` ## Exercise 4A: Single-Dash Hook Route Submit a foreground Imp prompt from Codex: ```text -rg find TODOs in src ``` Fill out: ```markdown # Single-Dash Hook Notes - prompt: - resolved Imp: - executable path included? yes/no: - description included? yes/no: - task text preserved? yes/no: - cwd included? yes/no: - did the main prompt continue? yes/no: - did the main agent avoid rediscovering the Imp? yes/no: - command evidence returned: ``` ## Exercise 4B: Double-Dash Fork Route Submit a forked Imp prompt from Codex: ```text --rg find TODOs in src ``` Fill out: ```markdown # Double-Dash Fork Notes - original prompt: - normalized fork prompt: - did current prompt block? yes/no: - workspace: - pane: - surface: - window: - read-screen command: - top command: - focus-pane command: - what output appeared in the fork: ``` ## Exercise 4C: Unknown Or Ambiguous Imp Try an intentionally unclear route: ```text -g find TODOs in src ``` Fill out: ```markdown # Ambiguous Route Notes - prompt: - blocked? yes/no: - suggested matches: - would you clarify, use `imp --which`, or create with `imp-create`? - corrected prompt: ``` ## Exercise 5: Section 8 Marker Packet To Imp Start with a bounded marker packet. ```markdown # Marker Packet - marker id: - marker label: Checkout button stayed disabled - marker note: - nearby evidence terms: - acceptedTerms - selectedShipping - checkout disabled - privacy boundary: - storage values exported? no - request bodies exported? no - response bodies exported? no ``` Route: ```bash imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled" ``` Run: ```bash imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used." ``` Fill out: ```markdown # Marker Packet Imp Run - marker id: - chosen Imp: - exact command: - file:line evidence: - what the Imp must not infer: - next regular Codex task: ``` ## Exercise 6: Fleet Management Run: ```bash imps ps imps stop imp-rg imps stop --all imps doctor ``` Fill out: ```markdown # Fleet Management - warm imps before: - stopped: - warm imps after: - doctor status: - when to stop a warm Imp: ``` ## Exercise 7: Inspect Evolution Suggestions Run: ```bash imps evolve imps evolve imp-rg ``` Fill out: ```markdown # Evolution Review - suggestion path: - suggested change: - safe? yes/no: - keeps one tool? yes/no: - keeps command evidence? yes/no: - accept, edit, or reject: - why: ``` ## Exercise 8: Design A New Imp Pick one CLI tool. Examples: ```text sqlite3 redis-cli internal search tool project-specific deploy CLI ``` Fill out: ```markdown # New Imp Design - name: imp- - tool: - sandbox mode: - why this is single-purpose: - what this Imp must never do: - first safe command: - first verification command: ## Operating Rule Run <tool> via exec_command before any final answer. Do not answer from memory. ## Command Map | User Intent | Exact Command | | --- | --- | | status | | | list | | | inspect | | | help | | ## Worked Examples ### Example 1 1. 2. 3. ### Example 2 1. 2. 3. ## Error Recovery | Error Text | Next Command | | --- | --- | | command not found | | | unknown flag | | | no results | | ## Output Rules - - - ``` Answer: ```markdown # Narrowness Review - does this use exactly one tool? yes/no: - does it need broad repo reasoning? yes/no: - should it be regular Codex instead? yes/no: - what to split out: ``` ## Exercise 9: Failure Path Drill Choose a recovery for each failure. | Failure | Recovery | | --- | --- | | router picks the wrong Imp | | | prompt is too broad for an Imp | | | Imp answers without showing a command | | | warm server appears stale | | | auth.json missing | | | compound route split wrong | | | evolution suggestion looks unsafe | | | marker packet lacks nearby evidence terms | | | package Imp wants to mutate a pnpm project | | | ffmpeg Imp would overwrite input | | Recovery options: ```text run `imp --which` use an explicit route split into smaller tool tasks send broad reasoning back to regular Codex strengthen Operating rule add Worked examples run `imps ps` run `imps stop <imp>` run `imps doctor` rewrite compound prompt with `;` or `then` dismiss unsafe evolution suggestions sharpen marker packet inspect lockfiles require new output file and no overwrite run read-only checks only ``` Fill out one in detail: ```markdown # Failure Recovery Detail - failure: - likely cause: - first command: - recovery: - how to know it worked: ``` ## Exercise 10: Verify The Imp Project Safety Net From the Imp project checkout, run: ```bash bun test ``` Fill out: ```markdown # Test Check - command: `bun test` - pass count: - fail count: - test files: - router covered? yes/no: - parse args covered? yes/no: - CLI smoke covered? yes/no: - hot reload covered? yes/no: - evolution covered? yes/no: - would you edit routing without this passing? yes/no: - why: ``` Optional focused checks: ```bash bun test test/router.test.ts bun test test/parseargs.test.ts bun test test/cli-smoke.test.ts ``` Hook route checks: ```text -rg find TODOs in src --rg find TODOs in src ``` Fill out: ```markdown # Dash Route Check - can explain `-<imp>`? yes/no: - can explain `--<imp>`? yes/no: - can inspect a forked cmux session? yes/no: - can explain why direct `codex fork ... -- '-imp ...'` is used? yes/no: ``` ## Exercise 11: Final Handoff Write a final handoff file: ```bash mkdir -p receipts cat > receipts/section9-final-handoff.md <<'EOF' # Section 9 Final Imp Handoff - source: Section 8 marker packet - DebugSession path: - marker id: - marker label: - marker note: - expected: - actual: - nearbyEventIds: - evidence terms: - - - - privacy boundary: - storage values exported? - request bodies exported? - response bodies exported? - target Imp: - why this target is single-purpose: - command to run: - required output: - command evidence to preserve: - what the Imp must not invent: - next handoff after Imp result: EOF test -s receipts/section9-final-handoff.md && echo "handoff:OK" ``` Fill out: ```markdown # Final Handoff Review - handoff file: - target Imp: - command: - route checked with `imp --which`? yes/no: - marker packet bounded? yes/no: - expected output clear? yes/no: - command evidence required? yes/no: - privacy boundary explicit? yes/no: - ready to run? yes/no: ``` ## Final Check Run or review: ```bash imp -l imps list imps ps imps doctor imp --which "find TODOs in src; then summarize git changes" bun test ``` Fill out: ```markdown # Final Imps Check - can explain regular Codex vs Imp? yes/no: - can state the core sentence? yes/no: - can route before running? yes/no: - can explain compound routing? yes/no: - can run direct interactive mode? yes/no: - can run `--run`? yes/no: - can run `-q`? yes/no: - can explain warm mode? yes/no: - can stop warm imps? yes/no: - can explain isolation? yes/no: - can inspect evolution suggestions? yes/no: - can design a narrow Imp prompt? yes/no: - can hand a Section 8 marker packet to an Imp? yes/no: - can decide when to return to regular Codex? yes/no: ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-imp-workflows-practice Topic: Execution Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Overnight emulated-cron loop playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers often need long-running investigation without a real scheduler: flaky auth, broken localhost flows, intermittent console errors, or UI drift that only appears after repeated checks. This pattern gives an agent a bounded timestamp loop, runtime evidence, and a hard stop so overnight work produces receipts instead of vague claims. [Core principles](/topics/foundations-context-triad-and-overnight-work/) ## Copy-paste workflow **When to use:** When Codex has no real scheduler but you want bounded overnight work (research/verification) while you sleep. This uses a natural-language time loop with a hard stop condition so credits and your repo stay safe. ### Copy-paste prompt ```text This is a /goal-style overnight task. Codex has no real cron, so you will emulate one in natural language with a HARD stop condition baked into this goal. Stay read-only unless I explicitly ask for a mutation. GOAL: <RESEARCH/VERIFICATION OBJECTIVE> LOOP: 1. Record a starting timestamp now. 2. Every <N> minutes, run this routine: <THE RESEARCH/VERIFICATION ROUTINE>. 3. STOP when the FIRST of these is hit (this bound is part of the goal, not optional): - <DURATION, e.g. 6 hours> has elapsed since the starting timestamp, OR - the clock reaches <TARGET TIME>, OR - <ITERATION LIMIT> iterations completed, OR - <BUDGET CAP> is reached. For any debugging the loop does, bundle the context triad so you find the REAL mismatch: - intent (this goal text) - implementation (the source) - output (logs / screenshots / traces) When those three disagree, that disagreement points at the actual bug. Guardrails: prefer read-only discovery before any mutation; keep the durable contract in this natural-language goal. ``` ### How it works - The loop is an emulated cron written in natural language: record a starting timestamp, repeat a routine every N minutes, and stop at a fixed duration / target clock time / iteration limit / budget cap. - The stop condition is written INTO the goal — it's mandatory, not a suggestion — so overnight runs stay bounded and credits/repo stay safe. - For debugging, bundle the context triad — intent (goal text) + implementation (source) + output (logs/screenshots/traces); when those three disagree the model finds the real mismatch. - Prefer read-only discovery before any mutation; keep the durable contract in natural-language goals. - Reference: [PackX](https://www.npmjs.com/package/packx), [codex-daemons](https://github.com/johnlindquist/codex-daemons), [Agent Browser](https://www.npmjs.com/package/agent-browser). ## Scenarios ### Overnight flaky auth-flow watchdog **Role:** As a product web developer maintaining a Next.js app with login-gated dashboards A local Next.js dashboard sometimes loses authenticated state after refresh, route changes, or idle time. The team has a dev server, a test account, and a browser-capable agent, but no built-in Codex scheduler. > As a product web developer, I want an agent to re-check the login and dashboard flow every 10 minutes overnight, so that I wake up to concrete logs, screenshots, and a narrowed failure theory instead of a one-off reproduction attempt. #### Agent brief ```text Create `.goals/overnight-auth-watch.md` and run it as a bounded /goal-style task. Goal: record a starting timestamp, then every 10 minutes until 7:00 AM local time or 24 iterations, whichever comes first, verify the local auth flow against the running app. Stay read-only unless I explicitly approve a mutation. First inspect the project scripts and start or reuse the dev server. For each iteration, capture the context triad: intent from this goal file, implementation from the smallest relevant auth/session/routes files, and output from browser console logs, network or terminal errors, screenshots, and a short iteration summary. Write artifacts under `.notes/overnight-auth-watch/` using timestamped filenames such as `iteration-003.json`, `iteration-003-console.log`, and `iteration-003-screenshot.png`. At the end, write `.notes/overnight-auth-watch/final-report.md` with pass/fail counts, first failing iteration, suspected mismatch between intent/implementation/output, and the exact evidence files to inspect. Do not declare success without inspecting the written artifacts. ``` #### Implementation references [Open reference](/topics/foundations-overnight-cron-playbook/) [Open reference](/topics/foundations-context-triad-and-overnight-work/) [Open reference](/topics/foundations-context-triad-and-overnight-work/) ```text .goals/overnight-auth-watch.md ``` ```text .notes/overnight-auth-watch/ ``` ```text packx --preview -s "auth session dashboard runtime artifacts" ``` ```text packx -s "auth session dashboard runtime artifacts" -f markdown --no-interactive -o .notes/overnight-auth-watch/debug-bundle.md ``` #### Browser verification Use an agent-browser-style flow against localhost: take an accessibility snapshot of the login page, fill the test credentials, click submit, wait for the dashboard route, evaluate `document.title`, visible route markers, and any session/banner text, then refresh and navigate away/back. Capture console output and a screenshot per iteration. If using a CMUX browser pane, keep the browser pane visible while the terminal pane writes artifacts. #### Definition of done - A bounded goal file exists with starting timestamp, 10-minute interval, and hard stop at 7:00 AM or 24 iterations. - Each iteration writes a JSON/log/screenshot receipt under `.notes/overnight-auth-watch/`. - `final-report.md` compares expected auth behavior, relevant implementation files, and actual runtime output, with links or paths to the strongest evidence. - No source files are modified unless a separate human-approved implementation step is started. #### Failure modes and mitigations - The agent only reports that the flow worked without saving browser evidence; mitigate by requiring timestamped console logs, screenshots, and iteration JSON before any final answer. - The loop keeps running because the stop condition is written vaguely; mitigate by including both a target clock time and an iteration cap in the goal text. - The browser agent assumes existing cookies are available; mitigate by scripting the login path explicitly with a test account and treating cookies as non-portable. - The agent bundles the whole repo instead of the relevant auth implementation plus output artifacts; mitigate by running `packx --preview` first and keeping the bundle focused. ### Repeated visual-regression and console-smoke loop **Role:** As a frontend engineer responsible for a marketing site or app shell A responsive landing page looks fine on the first pass, but layout drift, hydration warnings, or console errors appear after rebuilds, route changes, or viewport changes. The developer wants an overnight evidence loop, not a permanent test-suite expansion. > As a frontend engineer, I want an agent to periodically open the app in the browser, inspect key routes and viewports, and save proof artifacts, so that visual or console regressions are grounded in screenshots and logs. #### Agent brief ```text Create `.goals/overnight-ui-smoke.md`. Record the starting timestamp. Every 15 minutes, until 6 hours have elapsed or 20 iterations are complete, run a read-only UI smoke routine against the local web app. Inspect `package.json` for the dev and build commands. Start or reuse the dev server. Visit the agreed routes: `/`, `/pricing`, and `/dashboard` if present; if a route does not exist, record that instead of inventing one. For each route, capture console errors/warnings, one screenshot at desktop width, one screenshot at mobile width if the browser tool supports viewport changes, and a short artifact summary. Write files under `.notes/overnight-ui-smoke/`. If an error appears, bundle intent, implementation, and output with PackX: goal file, smallest route/component files, console logs, screenshots, and terminal output. End with `.notes/overnight-ui-smoke/final-report.md` listing stable routes, failing routes, first failure time, and the likely mismatch. ``` #### Implementation references [Open reference](/topics/foundations-overnight-cron-playbook/) [Open reference](/topics/foundations-context-triad-and-overnight-work/) [Open reference](/topics/foundations-overnight-cron-playbook/) ```text .goals/overnight-ui-smoke.md ``` ```text .notes/overnight-ui-smoke/ ``` ```text package.json ``` ```text packx --preview -s "ui smoke screenshots console logs routes components" ``` ```text packx -s "ui smoke screenshots console logs routes components" -f markdown --no-interactive -o .notes/overnight-ui-smoke/debug-bundle.md ``` #### Browser verification Use browser verification as the proof, not source inspection alone: open each localhost route, take an accessibility snapshot to confirm the main landmark/header/CTA exists, evaluate `window.location.pathname` and visible route text, collect console errors, and save screenshots. In CMUX, keep a browser pane beside the agent terminal or open a live Markdown tracker with the latest iteration summary. #### Definition of done - The loop is bounded by a 15-minute interval, 6-hour duration, and 20-iteration cap. - Every checked route has saved browser evidence, not just a textual claim. - Any failure has a focused context triad bundle: goal text, relevant route/component implementation, and runtime output. - The final report separates actual browser failures from missing routes or unsupported viewport operations. #### Failure modes and mitigations - The agent treats screenshots as optional and only reads source; mitigate by requiring browser artifacts as the primary receipt for this scenario. - The agent turns the smoke loop into broad redesign work; mitigate by stating read-only investigation only and deferring mutations to a separate Builder goal. - The agent over-tests unstable UI experiments as if they are permanent contracts; mitigate by framing this as disposable overnight evidence, not a maintained regression suite. - The bundle is too large to inspect usefully; mitigate by previewing PackX and including only goal, changed or relevant source, logs, screenshots, and traces. ### Overnight dependency-upgrade investigation brief **Role:** As a tech lead preparing a risky dependency or framework upgrade A repo has a pending upgrade, failing tests, or intermittent build warnings. The lead wants a Researcher/Validator-style overnight investigation that collects evidence and proposes next steps, but does not mutate the repo while unattended. > As a tech lead, I want an agent to periodically run read-only checks and package the strongest evidence, so that the next morning I can decide whether to hand a focused implementation goal to a Builder agent. #### Agent brief ```text Create `.goals/overnight-upgrade-investigation.md`. This is a read-only overnight research and verification loop. Record the starting timestamp. Every 20 minutes until 4 hours have elapsed or 12 iterations are complete, inspect the current dependency-upgrade state. Run only read-only or normal verification commands discovered from the repo, such as package-manager install status checks, typecheck, lint, test, or build commands already present in scripts. Do not edit package files or source files. Save terminal output to `.notes/overnight-upgrade-investigation/iteration-###.log` and a structured summary to `iteration-###.json`. When failures appear, capture the context triad: the goal text, relevant package/config/source files, and actual command output. Use PackX only after previewing the candidate files. Finish with `final-report.md` containing a ranked list of blockers, commands run, evidence paths, and a recommended next goal file for implementation. ``` #### Implementation references [Open reference](/topics/foundations-context-triad-and-overnight-work/) [Open reference](/topics/foundations-context-triad-and-overnight-work/) [Open reference](/topics/foundations-overnight-cron-playbook/) ```text .goals/overnight-upgrade-investigation.md ``` ```text .notes/overnight-upgrade-investigation/ ``` ```text package.json ``` ```text pnpm-lock.yaml, package-lock.json, yarn.lock, or bun.lockb if present ``` ```text packx --preview -s "dependency upgrade failing build test lint output" ``` ```text packx -s "dependency upgrade failing build test lint output" -f markdown --no-interactive -o .notes/overnight-upgrade-investigation/debug-bundle.md ``` #### Browser verification Browser proof is only useful if the upgrade affects a running web surface. If the app starts successfully, open the local app once per iteration, capture console errors and a homepage screenshot, and save them beside the command logs. If the failure is purely install/typecheck/build-level, browser proof is not the right proof; use terminal logs and PackX bundles instead. #### Definition of done - The investigation uses a timestamped loop with a 20-minute interval, 4-hour duration, and 12-iteration cap. - All verification commands and outputs are saved under `.notes/overnight-upgrade-investigation/`. - The final report ranks blockers by evidence strength and points to exact log or bundle files. - The repo remains unmodified except for local `.notes/` and `.goals/` artifacts. #### Failure modes and mitigations - The agent starts fixing files during an unattended investigation; mitigate by repeating read-only discovery before mutation in the goal and requiring a separate implementation goal later. - The agent dumps full command help or the entire repo into context; mitigate by inspecting project scripts first and using PackX preview with a focused topic. - The agent reports a generic dependency recommendation without command evidence; mitigate by requiring saved logs and expected-versus-actual comparison. - The loop wastes credits rerunning the same failing command with no new information; mitigate by writing a per-iteration summary and stopping early if three consecutive iterations produce identical failure output. ## Implementation notes - Keep the loop as a natural-language goal file, not a production scheduler. The point is bounded overnight agent work, not pretending Codex has cron. - Every scenario must include a hard stop: target clock time, elapsed duration, iteration cap, or budget cap. Use at least two bounds for unattended work. - For web app scenarios, runtime output means browser evidence: console logs, screenshots, route state, traces, or visible UI checks. Source code alone is not enough. - Prefer read-only discovery overnight. Save implementation for a separate morning Builder goal after a human reviews the evidence. - Write artifacts to local `.notes/` and goal files to `.goals/`; keep them out of committed source unless the repo intentionally tracks them. - Use specialized responsibilities without turning them into ceremony: Researcher/Validator overnight, Builder later if the evidence supports a change. - Stop early when repeated iterations produce identical evidence and no new signal; record that early stop in the final report. - Redact secrets from logs, screenshots, and browser captures before bundling or sharing. ## Boundaries and caveats - Do not present the overnight loop as a real cron scheduler or production automation system. - Do not make warm daemon internals, CODEX_HOME isolation, app-server reuse, or low-level Codex SDK profile mechanics part of this playbook. - Do not require CMUX as a standalone taught workflow for this workflow; use browser panes or CMUX only where they help produce web-dev proof. - Do not introduce unrelated tools that were only mentioned, such as ScreenPipe-based workflow mining, NotebookLM, n8n, ADB, or Codex Mobile, as required implementation steps. - Do not tell the agent to keep improving indefinitely, rewrite the project overnight, deploy changes, or mutate destructive systems while unattended. - Do not trust the agent's self-reported success without written logs, screenshots, traces, command output, or bundled artifacts. ## Agent reference map ### Existing overnight cron prompt Use as the exact taught prompt shape: starting timestamp, repeated interval, hard stop, context triad, and read-only guardrail. [Open reference](/topics/foundations-overnight-cron-playbook/) ### Lesson 10 validated references Treat as ground truth for what was actually taught: context triad, QA artifacts, short goal files, Oracle-generated goal files, specialized agents, overnight timestamp loops, and loose coupling. [Open reference](/topics/foundations-context-triad-and-overnight-work/) ### Lesson 10 validation guardrails Use to avoid reintroducing removed or over-specific claims such as warm daemon internals, profile isolation, or unrelated course redesign. [Open reference](/topics/foundations-context-triad-and-overnight-work/) ### Lesson 10 interactive checklist Use for implementation-ready receipts: intent.md, execution logs, screenshots, traces, PackX bundle, and fixed stop condition. [Open reference](/topics/foundations-context-triad-and-overnight-work/) ### PackX focused bundle flow Use when a failure needs a model-readable bundle of intent, implementation, and runtime output; always preview before writing the bundle. ```text packx --preview -s "<topic>" && packx -s "<topic>" -f markdown --no-interactive -o .notes/<scenario>/debug-bundle.md ``` ### Agent Browser evidence pattern Use for web-app runtime proof: console logs, screenshots, and live browser state rather than source-only guessing. [Open reference](https://www.npmjs.com/package/agent-browser) ### Uploaded scenario bundle Use as the local source snapshot for the scenario pipeline and lesson/toolkit context. ```text /mnt/data/scenario-overnight-cron.txt ``` Reference ID: foundations-overnight-cron-playbook Topic: Execution Sources: - [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html) --- # Policy at the agent’s execution boundary Project-specific shells, session-scoped guidance, Codex airlocks, and Claude hooks—with their bypass limits. ## Related working material - [Policy at the agent’s execution boundary — prompts and exercises](/topics/factory-environment-policy-practice/) - [Policy at the agent’s execution boundary — questions and tradeoffs](/topics/factory-environment-policy-questions/) - [Policy at the agent’s execution boundary — worked example](/topics/factory-environment-policy-worked-example/) ## TL;DR - Two files in `.pi/` rewire every shell command your agent runs: `rm` quarantines instead of deleting, `git` refuses force pushes and hard resets, `linear` always self-assigns issues, and `ls` briefs the model once per conversation. - You walk away with both files, complete and copy-paste ready below, plus a four-line test that proves they work without Pi in the loop. - The one move: make every override explain itself on stderr. That message reaches the model at the exact moment it acts — a rule buried in CLAUDE.md forty thousand tokens ago doesn't. Have your agent set this up — paste this into it: ``` text Fetch https://polite-ravine-6v8g.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## Same trick in Claude Code and Codex The `.pi/` setup above is one instance of a portable idea: put your policy at the seam where the agent's actions pass through, and make its output land in the model's context at the moment it acts. All three agents give you a first-class version of that seam: | Agent | Where the override lives | How it's scoped | Session key | How the message reaches the model | |----|----|----|----|----| | Pi | `.pi/settings.json` → `shellCommandPrefix` sources `.pi/agent-shell.zsh` | Per project, once trusted | `PI_SESSION_ID` (extension) | Override's stderr, same turn as the action | | Codex | `.zshenv` guard sources your function files into opted-in agent shells | Per launch (`codex -c …`) or per machine (`config.toml`) | — | Shadowing function's stderr, same turn | | Claude Code | `PreToolUse` hooks + the `env` map in `settings.json` | Per project (`.claude/settings.json`) or global (`~/.claude/settings.json`) | `session_id` in every hook's stdin JSON | Hook decision + reason, delivered before the tool runs | ### Codex: load agent shells through a zsh airlock The failure-mode demo takes ten seconds: ask plain `codex` to run one of your zsh helper functions and it comes back not found; ask the `x` wrapper from the [custom zsh functions section](https://sacred-ritual-w7as.here.now/) and the same function resolves. In this setup, plain Codex does not automatically receive your zsh helper/function surface — and the wrapper doesn't fix that by sourcing zsh files. **It starts Codex with one environment variable, and your zsh config decides what that variable means:** ``` text codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' ``` Codex's `shell_environment_policy` is the real, documented piece here — it injects env vars into the shells Codex spawns. `CODEX_LOAD_ZSH_DSL` is not a Codex built-in: it's a local marker this setup invented, and zsh startup rules — not Codex — decide which files load when they see it. Prefer the wrapper-local `-c` flag, which keeps the opt-in explicit and reversible per launch. Reach for global config only if every Codex launch on the machine should load the helper surface (it's also the place for per-machine values your functions need; the real config carries a key-helper path here, generalized below): ``` text # Append to ~/.codex/config.toml to make the opt-in permanent for every # launch — no wrapper function needed. [shell_environment_policy] inherit = "all" [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" # ...plus any per-machine value your agent-shell functions need, e.g.: # MY_KEY_HELPER = "~/.config/zsh/bin/my-key-helper" ``` What the marker opens is best pictured as an airlock. On one side sits your interactive `.zshrc` — prompt, completions, keybindings, fuzzy finders, terminal UI — and it stays sealed: agent shells never source it, because in a non-interactive shell that machinery can slow, hang, or spam every command the agent runs. In the middle is a narrow agent-safe bridge that assembles PATH and non-secret env for agent shells. And the marker is the opt-in valve: only when a launch sets it do your chosen helper and override files cross into the agent shell. When something's missing on the Codex side, the temptation is to open the whole hatch. The field rule: **missing PATH is not permission to pour `.zshrc` into Codex.** Here's the airlock as John runs it today — a guard at the end of his real `~/.config/zsh/.zshenv`. zsh sources `.zshenv` for every shell it starts, so the guard sees every agent shell, and it opens only when the launch opted in and no human is at the prompt (the sourced list here is trimmed to representative entries). Append it to your own `.zshenv`: ``` text # zshenv-agent-guard.zsh — append this block to your .zshenv # (~/.zshenv, or $ZDOTDIR/.zshenv if your zsh config lives elsewhere). # # Codex agent commands run in real, NON-interactive zsh shells — and zsh # sources .zshenv for every shell it starts. This guard loads agent-facing # functions ONLY when the launch opted in (CODEX_LOAD_ZSH_DSL is set) and # the shell is non-interactive, so your human terminals never see any of it. if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" && ! -o interactive ]]; then # Base env/paths for agent shells first, then any function files you want # every Codex shell to have — command overrides included. [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh" [[ -r "$ZDOTDIR/conf.d/60-git-dsl.zsh" ]] && source "$ZDOTDIR/conf.d/60-git-dsl.zsh" fi ``` Because these are real zsh shells, overrides are plain function shadowing — an `rm()` function beats `/bin/rm` — and stderr reaches the model naturally. Every policy function in `.pi/agent-shell.zsh` above works verbatim in a file the guard sources. The base file the guard loads first looks like this: ``` text # codex-env.zsh (excerpt) — the base file the guard loads first. # Functions are not inherited by child shells, so the source guard is # deliberately shell-local (typeset -g, not exported): [[ -n "${__CODEX_AGENT_ENV_SOURCED:-}" ]] && return 0 typeset -g __CODEX_AGENT_ENV_SOURCED=1 export CODEX_AGENT_ENV_READY=1 # ...PATH and env setup for agent shells, then plain function shadowing: if (( $+commands[mdflow] )); then md() { command mdflow "$@" } fi ``` That shell-local guard is a hard-won detail: a prior session that refactored this zsh config had to preserve it, because child shells inherit the exported env markers but not the functions — every nested zsh must re-create them. There's also a cleaner cut of the same airlock — the version refined for a prior Codex workshop. It moves the bridge out of `.zshenv` entirely: `~/.zshenv` shrinks to one line that sets `ZDOTDIR`, and `$ZDOTDIR/.zprofile` becomes the login-shell bridge. The proof shell for this setup, `zsh -lc`, is a login shell but *not* interactive — so `.zprofile` runs for it while `.zshrc` never does. In that layout the agent-safe base always crosses the bridge — `codex-env.zsh` marks itself with `CODEX_AGENT_ENV_SOURCED=1`, `conf.d/00-path.zsh` does deterministic PATH assembly, `local.zsh` holds reviewed machine-local overrides — and `CODEX_LOAD_ZSH_DSL` gates only the extra helper DSL. That's the honest difference from the guard above: in the live `.zshenv` version everything, base env included, waits behind the valve; in the clean version the base env rides the bridge on every login shell and only the function surface is opt-in. Same airlock, cleaner plumbing. This setup prompt builds the clean version end to end — hand it to your agent verbatim: ``` text Set up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells. Step 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only: zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' Do not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables. Step 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as: export ZDOTDIR="${ZDOTDIR:-$HOME/.config/zsh}" Verify: zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; test -d "$ZDOTDIR" && echo "ZDOTDIR exists" || echo "ZDOTDIR missing"' Step 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides. Use this shape, adjusted to the existing files: [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" [[ -r "$ZDOTDIR/conf.d/00-path.zsh" ]] && source "$ZDOTDIR/conf.d/00-path.zsh" [[ -r "$ZDOTDIR/local.zsh" ]] && source "$ZDOTDIR/local.zsh" Step 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded: export CODEX_AGENT_ENV_SOURCED=1 Do not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here. Step 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins. Verify PATH order: zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,25p"' Verify executable resolution: zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo "--- $cmd ---"; command -v "$cmd" || true; whence -a "$cmd" 2>/dev/null || true; done' Step 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints. Step 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup. Step 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`. Add this in the agent-safe startup path after `ZDOTDIR` is available: if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" ]]; then [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh" fi Verify the marker is absent by default: zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"' Verify selected helper loading when requested: CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' Step 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers: xi() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@" } x() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } e() { codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } Only add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL: [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" Otherwise, keep the marker out of global config and use the wrappers. Verify wrapper policy wiring: zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true Step 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state. zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' Expected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed. Step 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`. Step 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`. ``` However you get there, the proof should be boring: confirm the marker is off by default, confirm the env marker and tools appear when it's on, and re-check from a clean shell so an inherited marker can't fool you. Never dump full `env` output — confirm tools without printing secret values: ``` text zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"' CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' ``` ### Claude Code: PreToolUse hooks are the stderr with teeth Claude Code's seam is not the shell but the tool call. A `PreToolUse` hook sees every Bash command before it runs and can allow it, deny it, or attach an instruction — and whatever it says is delivered to the model at the moment of action. Check this into any repo as project scope (the same shape John runs globally in `~/.claude/settings.json`): ``` text { "env": { "PROJECT_ISSUE_ASSIGNEE": "self" }, "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/git-guard.sh" } ] } ] } } ``` The `env` map sets per-project env vars for every session in that project. The hook script receives the pending call as JSON on stdin — including `session_id`, Claude Code's `PI_SESSION_ID`: key per-session state (and the tag in your messages) by it, and use `SessionStart` hooks to seed that state once per conversation. This validator mirrors the page's `git` override; it's distilled from a hook that runs on every Bash call on John's machine: ``` text #!/bin/bash # .claude/hooks/git-guard.sh — PreToolUse hook for the Bash tool. # Distilled from a real global hook in ~/.claude/hooks/ — trimmed to the # two moves that matter: deny with guidance, and allow with an injected # instruction. Claude Code pipes the pending tool call to stdin as JSON. INPUT=$(cat) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') SESSION=$(echo "$INPUT" | jq -r '.session_id // "unknown"') # Force pushes: deny. The reason is delivered to the model INSTEAD of the # push happening — same message, same moment as the pi git() override. if echo "$COMMAND" | grep -qE 'git[[:space:]]+push.*[[:space:]](-f([[:space:]]|$)|--force)'; then jq -n --arg reason "[git-guard session=$SESSION] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $reason } }' exit 0 fi # Commits: allow, but attach a mandatory instruction at the moment of action # (the real hook's pattern: every commit message must read like a prompt # another agent could replay to recreate the work). if echo "$COMMAND" | grep -qE '^[[:space:]]*git[[:space:]]+commit'; then jq -n '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", permissionDecisionReason: "Git commit validated", additionalContext: "ALL git commits should be a prompt so another agent can recreate this work. MANDATORY." } }' exit 0 fi exit 0 ``` Make it executable (`chmod +x .claude/hooks/git-guard.sh`) and test it exactly like the pi overrides — no agent in the loop, just the hook's stdin contract: ``` text echo '{"session_id":"check-a","tool_input":{"command":"git push --force origin main"}}' \ | .claude/hooks/git-guard.sh ``` ``` text { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "[git-guard session=check-a] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." } } ``` Same message as the pi override, delivered even harder: the push never runs, and the reason becomes the model's next input. The difference in kind is worth naming — a zsh function is guidance (`command git` bypasses it), while a deny from a hook is enforcement. In all three agents, though, the core move is identical: **the override's output at the moment of action is the message to the model.** ## Why the shell is the right place for policy You've written rules for your agent in CLAUDE.md or AGENTS.md: never force push, never hard-delete, always self-assign issues. Then, deep into a session, the agent runs `rm -rf` anyway. The mistake is treating instructions the model read once as if they control actions it takes much later. Every deletion, push, and issue the agent creates passes through one place: the shell. A tagged stderr line like `[git-override session=…]` lands in the agent's tool output in the same turn as the blocked action — it can read the message and change course immediately. If you can see that line in the transcript, the agent saw it too. The decision rule: use overrides to **steer** — redirect destructive commands, inject policy, brief the model — and use Pi's hooks and permission system to **enforce** anything you can't afford to have bypassed. If violating a rule merely wastes a turn, an override is enough. If it loses data or pushes broken history, put a real control behind the friendly message. ## How the two files work Pi runs every agent command in a fresh shell and, once you trust a project's `.pi/settings.json`, prepends its `shellCommandPrefix`. Here that prefix sources `.pi/agent-shell.zsh`, so every zsh function in it shadows the command of the same name. The real binaries stay reachable: `command rm`, `command git`. This project ships four overrides — quarantining `rm`, guarded `git`, a `linear` rewrite adapted from a real team policy, and the instruction-once `ls`. ## Why session state needs PI_SESSION_ID A fresh shell per command means plain variables can't carry state between commands. Blocking a force push needs no memory — the evidence is in the argv. But "tell the agent this once, then get out of the way" needs state that survives across throwaway shells, and storing it under a fixed path fails in a specific way: `/new`, `/resume`, and `/fork` would all share one "first time". The pi-session-id extension (~44 lines of TypeScript) exports the active conversation ID as `PI_SESSION_ID` into each shell, syncing it on `session_start`, on human `!` commands, and on every model bash call. The ID is validated against Pi's session-ID syntax before it touches shell source — an invalid value blocks the call rather than permitting injection. With that key, per-conversation state is just a directory name, which is all `pi_instruction_once` is: a `mkdir` that succeeds exactly once per session. Keep overrides stateless unless the first occurrence in a conversation must behave differently from every later one. ## Test the overrides before an agent depends on them An override you've never executed is a guess, and a broken one makes every agent command fail mid-session. This project's `demo/run-demo.sh` reproduces Pi's execution model — fresh zsh, prefix sourced, `PI_SESSION_ID` set — so you can watch all five acts fire without Pi in the loop: ``` text ▶ [session session-A] $ ls demo INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. … ▶ [session session-A] $ rm .demo-state/playground/important.txt [rm-override session=session-A] quarantined 1 item(s) in <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting. ▶ [session session-A] $ ls .demo-state/tmp/pi-rm-quarantine/session-A important.txt ▶ [session session-A] $ git push --force origin main [git-override session=session-A] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval. ▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else [linear-override session=session-A] enforcing --assignee self [linear-override dry-run] command linear issue create --title Fix\ login\ bug --assignee self ▶ [session session-B] $ ls demo INSTRUCTIONS FOR THE AI: … ``` The quarantined file is listed, not gone. The force push never executed. The Linear issue lost `--assignee someone-else` and gained `--assignee self`. And session-B sees the briefing again, because state is keyed by conversation. The same recipe, boiled down to four lines, is the success check above. ## Appendix ### Limits & caveats - This is guidance with teeth, not a sandbox. `command rm` and `command git` bypass the functions by design — the overrides say so in their own stderr. Real enforcement belongs in Pi's hooks and permission system. - pi-session-id does not cover extension-internal `pi.exec()` calls, custom tools that spawn processes directly, custom `user_bash` handlers that build a sanitized environment, or commands that clear their environment with `env -i` / `unset PI_SESSION_ID`. - Nothing here measures how often an agent complies with override guidance versus routing around it. The sources support the mechanism and its coverage; treat "the agent self-corrects" as behavior to observe in your own sessions, not a guarantee. - The demo transcript comes from the harness, not a live Pi session, and the `linear` call ran with `PI_LINEAR_OVERRIDE_DRY_RUN=1`, printing the rewritten argv instead of hitting the Linear API. - Without the extension installed, `pi_session_id` falls back to `process-$PPID` — stable per shell process, not per conversation. - A trusted `shellCommandPrefix` executes with your full permissions on every command. Review `agent-shell.zsh` the way you'd review any shell script from the internet — because it is one. - The cross-agent artifacts were verified at the file level: `zsh -n` / `bash -n` on the shell blocks, JSON/TOML parses, and the Claude Code validator exercised by piping mock hook JSON to it (deny, allow, and passthrough cases). They were not captured from live Claude Code or Codex sessions; field names follow the current Claude Code hooks contract, which can change. - The Codex `.zshenv` guard edits a home-directory file, not a project file — it applies to every Codex launch that opts in on that machine, so keep what it sources small and agent-safe. ## Operating practice ### Put policy at the narrowest boundary #### What to notice Make **stable intent** and **risk rules** arrive before the action they should change. #### Try this Choose one risky or noisy command and write a read-only policy contract before implementing a hook. > “Meaning that… It won't ever miss because you're configuring the place where the agent is running.” John Lindquist · [01:02:42](https://proud-anchor-53zn.here.now/watch.html?t=3762#recording-player) #### Concept Repository files explain **stable intent**. Launch wrappers normalize repeated choices. Command decorators place warnings near an action. Human gates protect irreversible work. Automated checks prove correctness. #### Reflection The recorded environment demo surfaced diagnostics. Treat it as a pattern with failure evidence, not a clean universal implementation. **Recording evidence:** listen at 00:57:58. > “Once this is run, we have an observable thing that shows us this is exactly what the outcome will be, and then do it.” John Lindquist · [01:14:20](https://proud-anchor-53zn.here.now/watch.html?t=4460#recording-player) [Open Configure Your Environment](https://polite-ravine-6v8g.here.now/) [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=3478#q1-environment-policy) Reference ID: factory-environment-policy Topic: Execution Sources: - [Policy at the agent’s execution boundary](https://polite-ravine-6v8g.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q1-environment-policy) --- # Policy at the agent’s execution boundary — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Agent Function Overriding Redefining standard terminal tools (e.g., rm, ls) inside an agent's shell environment to intercept actions, append context, or enforce safe behaviors without breaking global workflows. ### Pre-tool / Post-tool Hooks Common lifecycle patterns used to execute custom code immediately before or after an AI agent calls a tool, contrasted by John with direct shell function overriding. ### Tool Decorating / Environment Overrides The architectural method of injecting specialized prompt rules or behavior validation logic directly into the shell environment binaries so that any LLM model or container harness executing inside that shell is forced to respect those rules implicitly. ### Model Baking vs. Day-One Adoption A testing methodology where a developer determines whether to wait for comprehensive ecosystem evaluations of a new model release versus immediate low-risk deployment to measure model output fidelity. ### Automated Game Evaluation / Self-Playing Evals Leveraging LLMs to generate independent, interactive canvas environments with embedded algorithmic game loops to benchmark instruction compliance, multi-step code composition, and creativity metrics. ### Model Thinking Budgets / Reasoning Control The structural capacity in terminal agent harnesses to toggle or dial down the internal execution cycles of advanced reasoning models (e.g., from maximum reasoning depth down to moderate/medium duration thresholds) via terminal keyboard macros. ### Herder A tool used to manage and configure tmux windows and panes efficiently. ### Agent Harness A lightweight execution layer or wrapper (like pi) around an LLM that lets developers customize prompts, memory management, and MCP tool handling completely from scratch without predefined overhead. ### AI Harness An application or command-line wrapper built around a core language model to enforce specific runtime constraints, system prompts, or agentic behaviors (e.g., Pi, Claude Code, Codex). ### Automated Lens Linting Real-time static analysis and syntax validation performed by specialized agent extensions (like pi-lens), where discovered faults are re-injected into the context loop for self-correction. ### Just-in-Time Context Injection Constructive implementation of prompt injection where system tools (like git, rm, or linear) are wrapped in the agent's shell setup to introduce behavioral guardrails immediately prior to execution. ## Questions and answer status ### Can you use pi with Claude Code subscription? **Status: answered.** John indicates that while you can technically run this configuration, he avoids doing so because Anthropic cracks down on using third-party harnesses with subscription tiers. ### When swapping between models using pi, when do you let a model bake versus adopting on day 1, like Kimi? For day 1 adoption, what low-risk actions avoid controversy, and how do you gradually scale up risk? **Status: answered.** John shares that his approach to day-one adoptions for new models like Kimi involves feeding them low-risk, self-contained creative tasks such as generating independent web arcade mini-games. ### An audience user inquires on the replay log webpage regarding the benefits of utilizing independent client tools like Pi alongside Claude Code, and whether to migrate or maintain localized workflow wrappers. **Status: answered.** John Lindquist answers that while client environments like Pi offer incredible localized control and Git integration capabilities, the underlying architectural philosophy centers on owning and tailoring your individual tools rather than functioning as an exclusive platform advocate. ### When do you transition to larger batched staging or production interaction, like mutating or deleting a database, and what must you observe before taking that risk? What is absolutely off-limits hard stop versus an acceptable risk? **Status: deferred.** Addressed in the next shard. ### Can you go through your definition of a “harness” that you are using. It feels a bit different than what’s in my brain around all of this. **Status: answered.** John explains that a harness is the minimal framework or wrapper that handles token spending, context loading, and tool execution instructions. ### When transitioning to larger batch staging or production interactions, such as mutating or deleting a database, what must be observed before taking that risk? **Status: answered.** The developer should construct a comprehensive logging matrix, perform numerous dry runs to explicitly review downstream output variations, and inspect observable results before conducting live mutation tasks. ### What is linear? A link is fine **Status: answered.** Students in the chat clarify that Linear is a modern, high-performance project management alternative to Jira, providing the direct URL link. ## Exercises - **Try:** Set up a local shell intercept rule that decorates standard utility calls with an automation log verification layer. **Basis:** John's explanation of custom overrides targeting default functions like ls or curl to inject structured execution safety borders across harnesses. - **Try:** Clone the miniarcade repository from GitHub, view the evals data, and set up a custom canvas configuration to test a model's visual code output consistency. **Basis:** John Lindquist explicitly suggests cloning the repository at 01:07:55.020 to experiment with building custom variants. - **Try:** Observe the agent as it specifies custom execution guards across shell scripts and automatically attempts to clear reported validation exceptions using static evaluation rules. **Basis:** Visual stream updates tracking pi-lens terminal reports between 01:13:44.935 and 01:16:45.000. ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [00:58:42](https://proud-anchor-53zn.here.now/watch.html?t=3522#recording-player) — A markdown table titled 'DANS TRICK IN CLAUDE CODE AND CODEX' is scrolled into view, showing file paths like .pi/settings.json. - [00:59:11](https://proud-anchor-53zn.here.now/watch.html?t=3551#recording-player) — John outlines how custom decorators can redefine standard shell utilities like rm or ls for the agent instead of conventional hooks. - [01:00:43](https://proud-anchor-53zn.here.now/watch.html?t=3643#recording-player) — The command 'take ~/dev/pi-env-demo' is typed and executed to initialize the workspace folder. - [01:00:54](https://proud-anchor-53zn.here.now/watch.html?t=3654#recording-player) — John launches the pi interface runner and inputs the prompt combined with policy instructions for the ls tool hook. - [01:01:30](https://proud-anchor-53zn.here.now/watch.html?t=3690#recording-player) — The terminal window reports 'Planning URL Instruction extraction' and 'Working...' states under the Codex model selection. - [01:01:53](https://proud-anchor-53zn.here.now/watch.html?t=3713#recording-player) — The screen displays a Ghostty terminal window where the pi tool is running an agent workflow named pi-env-demo, planning instruction extraction from a local deployment URL. - [01:01:53](https://proud-anchor-53zn.here.now/watch.html?t=3713#recording-player) — John explains wrapping core shell tools like rm, ls, and curl to guarantee persistent agent boundaries. - [01:01:58](https://proud-anchor-53zn.here.now/watch.html?t=3718#recording-player) — The automated agent triggers a deep file-system mapping command: $ pwd && printf ' -- top-level - ' && ls -la && printf ' -- pi dirs - ' && find . -maxdepth 3 -type f -o -type d | sort | head -200. - [01:02:50](https://proud-anchor-53zn.here.now/watch.html?t=3770#recording-player) — Terminal updates as the agent shifts tasks to Planning full doc and core loading and Deciding core retrieval before commands. - [01:02:57](https://proud-anchor-53zn.here.now/watch.html?t=3777#recording-player) — Agent runs an internal automation routine command: $ agent-browser skills get core --full. - [01:03:15](https://proud-anchor-53zn.here.now/watch.html?t=3795#recording-player) — Agent inspects code implementation blocks by reading lines 1364-2963 of docs/extensions.md. - [01:03:42](https://proud-anchor-53zn.here.now/watch.html?t=3822#recording-player) — Agent reads an additional block from docs/extensions.md lines 2659-3058. - [01:03:43](https://proud-anchor-53zn.here.now/watch.html?t=3823#recording-player) — Agent runs an orchestration pipeline using agent-browser to inspect the site layout at https://polite-ravine-6v0g.here.now/replay.html. - [01:03:56](https://proud-anchor-53zn.here.now/watch.html?t=3836#recording-player) — John addresses the trade-offs of using private credentials or subscriptions inside community harnesses due to usage crackdowns. - [01:04:08](https://proud-anchor-53zn.here.now/watch.html?t=3848#recording-player) — The terminal agent generates a list of planning goals for environment safeguards, including Clarifying ls function behavior, Planning file age enforcement across tools, and Designing multi-layer file mutation guards. - [01:04:56](https://proud-anchor-53zn.here.now/watch.html?t=3896#recording-player) — The background agent executes a global store lookup command: $ find ~/Library/pnpm/global/5/.pnpm/... -path '/tools/ls.' .... - [01:05:04](https://proud-anchor-53zn.here.now/watch.html?t=3904#recording-player) — Terminal renders file paths from the global pnpm cache and schedules tasks like Planning dynamic date handling. - [01:05:27](https://proud-anchor-53zn.here.now/watch.html?t=3927#recording-player) — Agent runs state capture command: $ agent-browser --session pi-env-instructions snapshot. - [01:05:35](https://proud-anchor-53zn.here.now/watch.html?t=3935#recording-player) — John outlines his practice of evaluating brand-new models by asking them to build standalone mini-games. - [01:05:44](https://proud-anchor-53zn.here.now/watch.html?t=3944#recording-player) — John Lindquist discusses the layout, prompts, and evaluation criteria embedded inside the repository. - [01:05:54](https://proud-anchor-53zn.here.now/watch.html?t=3954#recording-player) — The GitHub repository johnlindquist/miniarcade is shown, highlighting core documentation files like CLAUDE.md and VISION.md. - [01:06:00](https://proud-anchor-53zn.here.now/watch.html?t=3960#recording-player) — John Lindquist sends the public URL: https://github.com/johnlindquist/miniarcade - [01:06:31](https://proud-anchor-53zn.here.now/watch.html?t=3991#recording-player) — The presenter clicks on 'SKY REIGN' (miniarcade.dev/sky-reign.html), launching a side-scrolling vehicle shooter game. - [01:07:04](https://proud-anchor-53zn.here.now/watch.html?t=4024#recording-player) — a participant asks about running Claude Code inside VS Code and model relevance with upcoming architectures. - [01:07:52](https://proud-anchor-53zn.here.now/watch.html?t=4072#recording-player) — The browser displays miniarcade.dev/side-surfers.html, running a 3D-perspective rail-runner game environment. - [01:08:27](https://proud-anchor-53zn.here.now/watch.html?t=4107#recording-player) — The presenter realizes the model status line in the lower-right area is configured to 'gpt-5.6-sol · max'. - [01:08:41](https://proud-anchor-53zn.here.now/watch.html?t=4121#recording-player) — The presenter inputs the Shift+Tab keyboard shortcut sequence, prompting an inline context configuration overlay. - [01:08:43](https://proud-anchor-53zn.here.now/watch.html?t=4123#recording-player) — The configuration string field refreshes, updating the reasoning setting to 'gpt-5.6-sol · medium'. - [01:09:41](https://proud-anchor-53zn.here.now/watch.html?t=4181#recording-player) — John Lindquist mentions using Herder to manage tmux panes as an alternative to cmux. - [01:10:01](https://proud-anchor-53zn.here.now/watch.html?t=4201#recording-player) — John hits a keyboard shortcut to trigger his custom terminal fuzzy search overlay. - [01:10:04](https://proud-anchor-53zn.here.now/watch.html?t=4204#recording-player) — John types 'screen' into the search box to find text strings across open panes. - [01:10:07](https://proud-anchor-53zn.here.now/watch.html?t=4207#recording-player) — John hits enter on a search match, switching to the screenshot-demo pane logs. - [01:10:27](https://proud-anchor-53zn.here.now/watch.html?t=4227#recording-player) — Terminal switches back to the pi-env-demo pane where the agent is continuously working. - [01:10:34](https://proud-anchor-53zn.here.now/watch.html?t=4234#recording-player) — a participant provides the URL for Herder: https://herdr.dev. - [01:10:39](https://proud-anchor-53zn.here.now/watch.html?t=4239#recording-player) — a participant asks about transition criteria to destructive batched production or staging tasks. - [01:11:51](https://proud-anchor-53zn.here.now/watch.html?t=4311#recording-player) — The pi agent executes a batch command to find software versions and binary paths. - [01:12:24](https://proud-anchor-53zn.here.now/watch.html?t=4344#recording-player) — a participant asks for John's specific definition of an agent harness. - [01:12:32](https://proud-anchor-53zn.here.now/watch.html?t=4352#recording-player) — The agent invokes a memory_search query, returning a notification that no matching memories were found. - [01:13:34](https://proud-anchor-53zn.here.now/watch.html?t=4414#recording-player) — Ghostty terminal window displays the pi-env-demo agent in a working state utilizing the gpt-5.6-sol model. - [01:13:38](https://proud-anchor-53zn.here.now/watch.html?t=4418#recording-player) — John Lindquist evaluates a question regarding standard safety steps and logging checks prior to database alterations. - [01:13:44](https://proud-anchor-53zn.here.now/watch.html?t=4424#recording-player) — The agent creates and outputs settings variables directly to the dev path environment inside settings.json. - [01:13:51](https://proud-anchor-53zn.here.now/watch.html?t=4431#recording-player) — John Lindquist mandates executing thorough dry runs and checking outcome summaries prior to production updates. - [01:13:52](https://proud-anchor-53zn.here.now/watch.html?t=4432#recording-player) — The environment handles automated write loops for file age constant settings inside file-age-policy.mjs. - [01:14:35](https://proud-anchor-53zn.here.now/watch.html?t=4475#recording-player) — John Lindquist defines an AI harness as structural wrapper logic designed to shape tool outputs and model behavior. - [01:15:04](https://proud-anchor-53zn.here.now/watch.html?t=4504#recording-player) — The shell interception routines are constructed and committed to disk inside the agent-shell.zsh script file. - [01:15:26](https://proud-anchor-53zn.here.now/watch.html?t=4526#recording-player) — a participant states that harness represents an emerging term within present industry conversations. - [01:15:28](https://proud-anchor-53zn.here.now/watch.html?t=4528#recording-player) — The pi-lens tool execution surfaces multiple diagnostic warnings regarding shell parameter expansions. - [01:15:38](https://proud-anchor-53zn.here.now/watch.html?t=4538#recording-player) — Automated text replacements are injected by the agent script to address reported shell warnings. - [01:16:12](https://proud-anchor-53zn.here.now/watch.html?t=4572#recording-player) — John Lindquist notes that pi-lens acts as an integrated workspace helper, delivering automatic feedback to the agent context. - [01:16:36](https://proud-anchor-53zn.here.now/watch.html?t=4596#recording-player) — The system writes data to file-guard.ts, generating compilation anomalies due to unresolved type dependencies. - [01:17:22](https://proud-anchor-53zn.here.now/watch.html?t=4642#recording-player) — John Lindquist points out that these visual templates were developed by asking Codex to analyze a reference screenshot. - [01:17:50](https://proud-anchor-53zn.here.now/watch.html?t=4670#recording-player) — John speaks about the utility of dropping images into Codex to get UI/UX design mockups. - [01:17:59](https://proud-anchor-53zn.here.now/watch.html?t=4679#recording-player) — John inputs 'take ~/dev/article-mockup' in his shell environment to establish a new work folder. - [01:18:17](https://proud-anchor-53zn.here.now/watch.html?t=4697#recording-player) — John responds with 1 to confirm folder trust for the automated tool environment. - [01:18:23](https://proud-anchor-53zn.here.now/watch.html?t=4703#recording-player) — John provides a prompt to Claude Code: 'Build a pixel perfect, version of this as a landing page using only html/css/js [Image #1]'. - [01:18:36](https://proud-anchor-53zn.here.now/watch.html?t=4716#recording-player) — Claude Code initializes background tasks while a parallel pi-env-demo agent process runs linting and diagnostics on file-age-policy.js. - [01:19:58](https://proud-anchor-53zn.here.now/watch.html?t=4798#recording-player) — The background automated agent context triggers an 'npm install --ignore-scripts' execution block inside the workspace terminal. - [01:20:49](https://proud-anchor-53zn.here.now/watch.html?t=4849#recording-player) — a participant asks 'What is linear? A link is fine'. - [01:21:05](https://proud-anchor-53zn.here.now/watch.html?t=4865#recording-player) — a participant replies 'It’s like Jira but for Hipsters'. - [01:21:06](https://proud-anchor-53zn.here.now/watch.html?t=4866#recording-player) — a participant references the official platform link https://linear.app/. - [01:21:18](https://proud-anchor-53zn.here.now/watch.html?t=4878#recording-player) — John highlights structural guidelines regarding ~/.config/env/ behavioral decorators. ### Unresolved: Exact target sub-model configuration tag string used by Codex engine inside the terminal viewport layout. Text resolution rendering in font layout panel on the right margin of the app screen window is small. **Discriminating evidence:** Correlate with explicit project declarations or subsequent high-res configuration file captures. ### Unresolved: Exact horizontal constraints used inside the pnpm cache find command pipeline loop. Terminal screen edge boundaries wrap or limit full view tracking of long parameter flags near lines end. **Discriminating evidence:** Verify by testing standard flag parameters of multi-target path queries within contemporary global pnpm layouts. ### Unresolved: polite-rasine-6vbg.hore.rem/replay.html The top-level domain suffix used (.rem) represents an isolated system naming asset rather than standard public registries. **Discriminating evidence:** Verify with platform operators whether a localized hosts mapping file modification or zero-trust mesh link is needed to navigate to this interface. ### Unresolved: Exact sequence of alias mapping for launch command string. The precise keystrokes were hidden behind rapid system autocompletion parameters. **Discriminating evidence:** Check system profile scripts or configuration references for active project shell aliases. ### Demonstration detail: 01:00:38 - Create local folder via shell take shortcut. - Boot agent terminal runner app layout. - Paste custom rule set alongside documentation URL to prompt field input. **Tools observed:** Ghostty, Pi, Codex. **Command or prompt observations (not a verified recipe):** ```text take ~/dev/pi-env-demo pi-env-demo pi ``` ### Demonstration detail: 01:01:53 - Automated directory mapping query execution - Skill module extraction using core options - Document segment parsing on target project layouts - Global store lookup searching for tool source modules **Tools observed:** pi, agent-browser. **Command or prompt observations (not a verified recipe):** ```text pwd && printf ' -- top-level - ' && ls -la && printf ' -- pi dirs - ' && find . -maxdepth 3 -type f -o -type d | sort | head -200 agent-browser skills get core --full agent-browser --session pi-env-instructions open 'https://polite-ravine-6v0g.here.now/replay.html' ... find ~/Library/pnpm/global/5/.pnpm/ -path '/tools/ls.' -o -path '/tools/edit.' -o -path '/tools/write.' ``` ### Demonstration detail: 01:05:43 - Opened the primary project dashboard - Browsed to the public codebase layout - Loaded and interacted with four individual canvas video applications: Sky Reign, Star Roller, Crystal Mesa, and Side Surfers **Tools observed:** Google Chrome. ### Demonstration detail: 01:08:21 - Brought terminal application into focus - Inspected the current model budget status bar - Triggered context menu macro via Shift+Tab and reduced thinking level constraint values **Tools observed:** pi-env-demo shell. ### Demonstration detail: 01:10:01 - Triggered custom global pane search utility - Searched for terminal logs with keyword 'screen' - Switched active terminal views using fuzzy selection match **Tools observed:** Herder, tmux. ### Demonstration detail: 01:13:44 - Automated creation and parsing of settings parameters. - Static code optimization and parameter alignment via automated patch streams. **Tools observed:** Ghostty, pi-lens. **Command or prompt observations (not a verified recipe):** ```text pi-lens - clear settings.json pi-lens - stw 13M settings.json agent-shell.zsh file-age-policy.mjs ``` ### Demonstration detail: 01:17:59 - Created workspace folder with take command. - Launched Claude Code agent interface. - Passed local design image template as context into the LLM system prompt framework. **Tools observed:** Claude Code v2.1.212, zsh. **Command or prompt observations (not a verified recipe):** ```text take ~/dev/article-mockup ``` Reference ID: factory-environment-policy-discussion Topic: Execution Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Policy at the agent’s execution boundary — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for policy at the agent’s execution boundary. ## Quick start From your project root: ``` text pi install git:github.com/johnlindquist/pi-session-id mkdir -p .pi # paste the two files from the agent guide below into .pi/, then prove it: command rm -rf "${TMPDIR:-/tmp}/pi-command-instructions/check-a" PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' ``` First `ls` prints instructions addressed to the AI; the second runs normally. That's the whole mechanism working. ## Prompt library Paste these into Pi inside a project that has the setup below (with `.pi/settings.json` trusted) and watch the agent read the override output and self-correct. ### See the once-per-conversation briefing - Agent: Pi - Working directory: a project with this setup - Expected result: the agent quotes the "INSTRUCTIONS FOR THE AI" block its first ls returned ``` text List the files in this project. If the shell tells you anything unusual, quote it back to me before doing anything else. ``` ### Delete a file — rm quarantines instead - Agent: Pi - Working directory: a project with this setup - Expected result: the agent reports \[rm-override\] quarantined the file and names the quarantine path ``` text Create a file named scratch-note.txt containing the word "disposable", then delete it. Afterward, tell me exactly what the shell printed when you deleted it and where the file actually went. ``` ### Force-push — git blocks it with guidance - Agent: Pi - Working directory: a project with this setup, inside a git repo - Expected result: the agent stops and relays "\[git-override\] force push blocked" instead of pushing ``` text Force-push the current branch to origin right now. If anything stops you, do not work around it — stop and report exactly what it said. ``` ### Create a Linear issue — policy rewrites the flags - Agent: Pi - Working directory: a project with this setup and the linear CLI - Expected result: the command runs with --assignee self no matter what the agent passed ``` text Create a Linear issue titled "Fix login bug" and assign it to someone-else. Show me the exact command you ran and everything it printed. ``` ## Set it up (agent guide) 1. Install the pi-session-id extension so every agent shell gets a conversation-scoped `PI_SESSION_ID`: ``` text pi install git:github.com/johnlindquist/pi-session-id ``` 2. Create `.pi/settings.json` in your project. It tells Pi which shell to use and sources the override file before every command: ``` text { "shellPath": "/bin/zsh", "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } ``` 3. Create `.pi/agent-shell.zsh` — the override file itself, complete. Keep `pi_session_id` and `pi_instruction_once` as-is; swap the four policy functions for your own: ``` text # .pi/agent-shell.zsh # # Sourced before EVERY shell command the agent runs, via .pi/settings.json: # # { "shellPath": "/bin/zsh", # "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } # # Pi spawns a fresh shell per command, so plain shell variables can't carry # state between commands. The pi-session-id extension # (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into # each of those shells, which lets these overrides keep per-conversation state # on disk — e.g. "show this instruction once per session". pi_session_id() { print -r -- "${PI_SESSION_ID:-process-$PPID}" } # Emit a heredoc the FIRST time a command runs in this session, then get out # of the way. State lives under $TMPDIR keyed by session id, so /new, /fork, # and parallel Pi processes each get their own "first time". pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } # --- rm: quarantine instead of delete -------------------------------------- # The agent never permanently deletes anything. Targets move to a # session-scoped quarantine dir; the notice tells the agent how to restore. rm() { emulate -L zsh local session_id="$(pi_session_id)" local quarantine="${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id" local -a targets local arg for arg in "$@"; do [[ "$arg" == -* ]] || targets+=("$arg") done if (( ${#targets} == 0 )); then command rm "$@" return fi mkdir -p "$quarantine" || return 1 local moved=0 target for target in "${targets[@]}"; do if [[ -e "$target" || -L "$target" ]]; then mv -- "$target" "$quarantine/" && (( moved++ )) else print -u2 -- "[rm-override] no such file: $target" fi done print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting." print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval." } # --- git: block destructive operations -------------------------------------- # Force pushes and hard resets fail loudly with guidance instead of running. git() { emulate -L zsh local session_id="$(pi_session_id)" local arg if [[ "$1" == "push" ]]; then for arg in "$@"; do case "$arg" in -f|--force|--force-with-lease|--force-if-includes) print -u2 -- "[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." return 1 ;; esac done fi if [[ "$1" == "reset" ]]; then for arg in "$@"; do if [[ "$arg" == "--hard" ]]; then print -u2 -- "[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable." return 1 fi done fi command git "$@" } # --- linear: enforce team policy on issue creation -------------------------- # Adapted from a real override in ~/dev/pi-session-test: every issue the agent # creates is assigned to the current user, no matter what flags it passed. linear() { emulate -L zsh local session_id="$(pi_session_id)" if [[ "$1" != "issue" || "$2" != "create" ]]; then command linear "$@" return fi local -a decorated local skip=0 arg for arg in "$@"; do if (( skip )); then skip=0; continue; fi case "$arg" in -a|--assignee) skip=1 ;; -a=*|--assignee=*) ;; *) decorated+=("$arg") ;; esac done decorated+=(--assignee self) print -u2 -- "[linear-override session=$session_id] enforcing --assignee self" if [[ -n "${PI_LINEAR_OVERRIDE_DRY_RUN:-}" ]]; then print -n -- "[linear-override dry-run] command linear" for arg in "${decorated[@]}"; do printf ' %q' "$arg"; done print return 0 fi command linear "${decorated[@]}" } # --- ls: teach the agent, once per conversation ------------------------------ # The pattern from the pi-session-id README: the first `ls` of a session # returns instructions to the model instead of output; every later `ls` runs # normally. Swap the message for anything you want the agent told exactly once. ls() { if pi_instruction_once ls <<'INSTRUCTIONS'; then INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. INSTRUCTIONS return 0 fi command ls "$@" } ``` 4. Open the project in Pi and approve `.pi/settings.json` when Pi asks you to trust it. Until you do, the prefix never runs. **Success check:** run each override in a fresh `zsh -c` with `PI_SESSION_ID` set — the same way Pi runs commands — from your project root: ``` text command rm -rf "${TMPDIR:-/tmp}/pi-command-instructions/check-a" PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main' ``` ``` text INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. CLAUDE.md demo folio notes README.md site [git-override session=check-b] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval. ``` Line by line: the first `ls` returns the briefing, the second returns your project's normal listing (this transcript shows this project's files), and the force push is refused with exit code 1. ## Complete reusable setup contract ## Configuring Your Agent's Environment — agent setup guide Following this file sets up: a project-specific shell for the Pi coding agent, where `rm` quarantines instead of deleting, `git` refuses force pushes and hard resets, `linear` always self-assigns issues, and `ls` briefs the model once per conversation. An optional final section replicates the same moment-of-action policy environment in Claude Code and Codex. Placeholders used below: `<project-root>` = the project you are working in. All other paths are literal. Run every command from `<project-root>`. ## Prerequisites Check each before starting: ```bash zsh --version pi --version ``` Expected: any zsh 5.x+, and any Pi CLI version. If `pi` is missing, you can still install the two files and run the success check — it only needs zsh — but tell your user that the per-conversation behavior needs Pi plus the pi-session-id extension. If `zsh` is missing, stop and tell your user what to install. ## Steps 1. Install the pi-session-id extension so every shell Pi spawns gets a conversation-scoped `PI_SESSION_ID`: ```bash pi install git:github.com/johnlindquist/pi-session-id ``` 2. Create `.pi/settings.json` with exactly this content: ```json { "shellPath": "/bin/zsh", "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } ``` 3. Create `.pi/agent-shell.zsh` with exactly this content. If your user wants different policy, keep `pi_session_id` and `pi_instruction_once` as-is and swap the four policy functions (`rm`, `git`, `linear`, `ls`) for their own: ```zsh # .pi/agent-shell.zsh # # Sourced before EVERY shell command the agent runs, via .pi/settings.json: # # { "shellPath": "/bin/zsh", # "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } # # Pi spawns a fresh shell per command, so plain shell variables can't carry # state between commands. The pi-session-id extension # (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into # each of those shells, which lets these overrides keep per-conversation state # on disk — e.g. "show this instruction once per session". pi_session_id() { print -r -- "${PI_SESSION_ID:-process-$PPID}" } # Emit a heredoc the FIRST time a command runs in this session, then get out # of the way. State lives under $TMPDIR keyed by session id, so /new, /fork, # and parallel Pi processes each get their own "first time". pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } # --- rm: quarantine instead of delete -------------------------------------- # The agent never permanently deletes anything. Targets move to a # session-scoped quarantine dir; the notice tells the agent how to restore. rm() { emulate -L zsh local session_id="$(pi_session_id)" local quarantine="${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id" local -a targets local arg for arg in "$@"; do [[ "$arg" == -* ]] || targets+=("$arg") done if (( ${#targets} == 0 )); then command rm "$@" return fi mkdir -p "$quarantine" || return 1 local moved=0 target for target in "${targets[@]}"; do if [[ -e "$target" || -L "$target" ]]; then mv -- "$target" "$quarantine/" && (( moved++ )) else print -u2 -- "[rm-override] no such file: $target" fi done print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting." print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval." } # --- git: block destructive operations -------------------------------------- # Force pushes and hard resets fail loudly with guidance instead of running. git() { emulate -L zsh local session_id="$(pi_session_id)" local arg if [[ "$1" == "push" ]]; then for arg in "$@"; do case "$arg" in -f|--force|--force-with-lease|--force-if-includes) print -u2 -- "[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." return 1 ;; esac done fi if [[ "$1" == "reset" ]]; then for arg in "$@"; do if [[ "$arg" == "--hard" ]]; then print -u2 -- "[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable." return 1 fi done fi command git "$@" } # --- linear: enforce team policy on issue creation -------------------------- # Adapted from a real override in ~/dev/pi-session-test: every issue the agent # creates is assigned to the current user, no matter what flags it passed. linear() { emulate -L zsh local session_id="$(pi_session_id)" if [[ "$1" != "issue" || "$2" != "create" ]]; then command linear "$@" return fi local -a decorated local skip=0 arg for arg in "$@"; do if (( skip )); then skip=0; continue; fi case "$arg" in -a|--assignee) skip=1 ;; -a=*|--assignee=*) ;; *) decorated+=("$arg") ;; esac done decorated+=(--assignee self) print -u2 -- "[linear-override session=$session_id] enforcing --assignee self" if [[ -n "${PI_LINEAR_OVERRIDE_DRY_RUN:-}" ]]; then print -n -- "[linear-override dry-run] command linear" for arg in "${decorated[@]}"; do printf ' %q' "$arg"; done print return 0 fi command linear "${decorated[@]}" } # --- ls: teach the agent, once per conversation ------------------------------ # The pattern from the pi-session-id README: the first `ls` of a session # returns instructions to the model instead of output; every later `ls` runs # normally. Swap the message for anything you want the agent told exactly once. ls() { if pi_instruction_once ls <<'INSTRUCTIONS'; then INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. INSTRUCTIONS return 0 fi command ls "$@" } ``` 4. Tell your user to open the project in Pi and approve `.pi/settings.json` when Pi asks to trust it. Until they do, the `shellCommandPrefix` never runs. ## Success check Run from `<project-root>` — this reproduces how Pi runs commands (fresh zsh, prefix sourced, `PI_SESSION_ID` set): ```bash command rm -rf "${TMPDIR:-/tmp}/pi-command-instructions/check-a" PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main' ``` Expected observable result: 1. The first `ls` prints the briefing starting with `INSTRUCTIONS FOR THE AI:` instead of a file listing. 2. The second `ls` prints the project's normal file listing. 3. The `git push --force` prints `[git-override session=check-b] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.` and exits with code 1 (nothing is pushed; this is safe to run even outside a git repo, because the override refuses before real git runs). Report to your user: what you set up, the success-check output, and anything you had to adapt. ## Optional: the same trick in Claude Code and Codex The insight is portable — in every agent, the override's output at the moment of action is the message to the model. Only do these if your user asks for them; both are covered on https://polite-ravine-6v8g.here.now/#same-trick-in-claude-code-and-codex. ### Claude Code (project-scoped, safe to check into a repo) 1. Create `.claude/settings.json` with exactly this content (merge the `hooks` and `env` keys if the file already exists): ```json { "env": { "PROJECT_ISSUE_ASSIGNEE": "self" }, "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/git-guard.sh" } ] } ] } } ``` 2. Create `.claude/hooks/git-guard.sh` with exactly this content, then `chmod +x .claude/hooks/git-guard.sh`: ```bash #!/bin/bash # .claude/hooks/git-guard.sh — PreToolUse hook for the Bash tool. # Distilled from a real global hook in ~/.claude/hooks/ — trimmed to the # two moves that matter: deny with guidance, and allow with an injected # instruction. Claude Code pipes the pending tool call to stdin as JSON. INPUT=$(cat) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') SESSION=$(echo "$INPUT" | jq -r '.session_id // "unknown"') # Force pushes: deny. The reason is delivered to the model INSTEAD of the # push happening — same message, same moment as the pi git() override. if echo "$COMMAND" | grep -qE 'git[[:space:]]+push.*[[:space:]](-f([[:space:]]|$)|--force)'; then jq -n --arg reason "[git-guard session=$SESSION] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $reason } }' exit 0 fi # Commits: allow, but attach a mandatory instruction at the moment of action # (the real hook's pattern: every commit message must read like a prompt # another agent could replay to recreate the work). if echo "$COMMAND" | grep -qE '^[[:space:]]*git[[:space:]]+commit'; then jq -n '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", permissionDecisionReason: "Git commit validated", additionalContext: "ALL git commits should be a prompt so another agent can recreate this work. MANDATORY." } }' exit 0 fi exit 0 ``` 3. Success check (needs `jq`; no agent in the loop — this is the hook's stdin contract): ```bash echo '{"session_id":"check-a","tool_input":{"command":"git push --force origin main"}}' \ | .claude/hooks/git-guard.sh ``` Expected: a JSON object whose `hookSpecificOutput.permissionDecision` is `"deny"` and whose reason starts with `[git-guard session=check-a] force push blocked.`. A `git commit` command instead yields `"allow"` plus an `additionalContext` instruction; any other command prints nothing. 4. Context: the `env` map sets per-project env vars for every session; every hook receives `session_id` on stdin (key per-session state by it — the `PI_SESSION_ID` parallel); `SessionStart` hooks fire once per session to seed that state. The same settings shape in `~/.claude/settings.json` applies globally. ### Codex (user-scoped — edits home config, so confirm with your user first) Codex runs agent commands in real non-interactive zsh shells (commonly the `zsh -lc` shape — login, not interactive), so overrides are plain function shadowing (an `rm()` function beats `/bin/rm`) and stderr reaches the model naturally — the policy functions from `.pi/agent-shell.zsh` above work verbatim in any file the guard below sources. Note the boundary: plain Codex does not automatically receive your zsh helper/function surface, and `CODEX_LOAD_ZSH_DSL` below is a local marker this setup invented, not a Codex built-in — Codex only injects the variable; zsh startup rules decide what it means. Field rule: missing PATH is not permission to pour `.zshrc` into Codex — never fix a missing tool or helper by sourcing the full interactive `.zshrc` into agent shells. 1. Append this block to the user's `.zshenv` (`~/.zshenv`, or `$ZDOTDIR/.zshenv` if their zsh config lives elsewhere), replacing the sourced files with the function files they want agent shells to load: ```zsh # zshenv-agent-guard.zsh — append this block to your .zshenv # (~/.zshenv, or $ZDOTDIR/.zshenv if your zsh config lives elsewhere). # # Codex agent commands run in real, NON-interactive zsh shells — and zsh # sources .zshenv for every shell it starts. This guard loads agent-facing # functions ONLY when the launch opted in (CODEX_LOAD_ZSH_DSL is set) and # the shell is non-interactive, so your human terminals never see any of it. if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" && ! -o interactive ]]; then # Base env/paths for agent shells first, then any function files you want # every Codex shell to have — command overrides included. [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh" [[ -r "$ZDOTDIR/conf.d/60-git-dsl.zsh" ]] && source "$ZDOTDIR/conf.d/60-git-dsl.zsh" fi ``` 2. Opt in per launch: ```bash codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' ``` Or permanently, by appending to `~/.codex/config.toml` (merge if `[shell_environment_policy]` already exists): ```toml [shell_environment_policy] inherit = "all" [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" # ...plus any per-machine value your agent-shell functions need, e.g.: # MY_KEY_HELPER = "~/.config/zsh/bin/my-key-helper" ``` 3. Success check — simulate what Codex does (non-interactive zsh with the env var set), using one function name defined in a file the guard sources (replace `<your-function>`): ```bash CODEX_LOAD_ZSH_DSL=1 zsh -c 'whence -w <your-function>' zsh -c 'whence -w <your-function>' ``` Expected: the first command prints `<your-function>: function`; the second prints nothing useful (exit 1), proving the guard only fires when opted in. 4. Gotcha (from a prior session's refactor of this exact setup): zsh functions are not inherited by child shells, so any "already sourced" guard inside the files you load must be shell-local (`typeset -g`), not an exported env var — otherwise nested shells inherit the marker but not the functions. #### Optional clean rebuild: the Agent Setup Prompt The guard above is the live "append to what you have" version: everything, agent-safe base env included, waits behind the `CODEX_LOAD_ZSH_DSL` valve in `.zshenv`. The refined layout from a prior Codex workshop is structured differently: `~/.zshenv` shrinks to one line setting `ZDOTDIR`; `$ZDOTDIR/.zprofile` becomes the login-shell bridge (`zsh -lc` is login but NOT interactive, so `.zprofile` runs for agent shells while `.zshrc` never does); the agent-safe base (`codex-env.zsh` marking `CODEX_AGENT_ENV_SOURCED=1`, deterministic PATH in `conf.d/00-path.zsh`, reviewed `local.zsh`) loads on every login shell; and `CODEX_LOAD_ZSH_DSL` gates only the extra helper/function files. To build that clean layout, run this prompt verbatim (do not run it on top of step 1's guard without reconciling — they are two versions of the same airlock): ```text Set up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells. Step 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only: zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' Do not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables. Step 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as: export ZDOTDIR="${ZDOTDIR:-$HOME/.config/zsh}" Verify: zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; test -d "$ZDOTDIR" && echo "ZDOTDIR exists" || echo "ZDOTDIR missing"' Step 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides. Use this shape, adjusted to the existing files: [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" [[ -r "$ZDOTDIR/conf.d/00-path.zsh" ]] && source "$ZDOTDIR/conf.d/00-path.zsh" [[ -r "$ZDOTDIR/local.zsh" ]] && source "$ZDOTDIR/local.zsh" Step 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded: export CODEX_AGENT_ENV_SOURCED=1 Do not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here. Step 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins. Verify PATH order: zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,25p"' Verify executable resolution: zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo "--- $cmd ---"; command -v "$cmd" || true; whence -a "$cmd" 2>/dev/null || true; done' Step 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints. Step 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup. Step 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`. Add this in the agent-safe startup path after `ZDOTDIR` is available: if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" ]]; then [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh" fi Verify the marker is absent by default: zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"' Verify selected helper loading when requested: CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' Step 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers: xi() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@" } x() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } e() { codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } Only add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL: [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" Otherwise, keep the marker out of global config and use the wrappers. Verify wrapper policy wiring: zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true Step 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state. zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' Expected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed. Step 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`. Step 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`. ``` #### Verification (either version) ```bash zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"' CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' ``` Expected for the clean layout: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` pointing at the intended config directory, required tools printing real paths, and no secret values printed. The first command should print an empty marker by default; the clean-shell (`env -u`) check guards against being fooled by inherited marker state. (Step 1's `.zshenv` guard version does not set `CODEX_AGENT_ENV_SOURCED`; for it, use the `whence -w <your-function>` check from step 3 instead.) ## Notes for agents - Instruction-once state persists in `${TMPDIR:-/tmp}/pi-command-instructions/<session-id>/` across runs. If the first `ls` does NOT print the briefing, a marker from an earlier run exists — remove it with the `command rm -rf` line above (change `check-a` to the session id you used) and retry. - `command rm`, `command git`, etc. bypass the overrides by design. This setup is guidance the agent reads at the moment it acts, not a security boundary. Anything that must never happen belongs in Pi's hooks/permissions, not here. - Without the extension, `pi_session_id` falls back to `process-$PPID`, which is stable per shell process rather than per conversation — the overrides still work, but "once per session" becomes "once per shell parent". - If overrides don't fire inside Pi, the usual cause is that the user has not trusted `.pi/settings.json` yet, so the prefix is never prepended. - The `linear` override rewrites only `linear issue create`; every other `linear` subcommand passes through untouched. Set `PI_LINEAR_OVERRIDE_DRY_RUN=1` to print the rewritten argv instead of calling the real CLI. - Full explanation, prompt library, and caveats: https://polite-ravine-6v8g.here.now/ - For your user (human-readable presentation pages): an annotated replay of the session that built this setup at https://polite-ravine-6v8g.here.now/replay.html, and a Q&A walkthrough at https://polite-ravine-6v8g.here.now/dialogue.html. Both carry the complete `.pi/agent-shell.zsh`. Reference ID: factory-environment-policy-practice Topic: Execution Sources: - [Policy at the agent’s execution boundary](https://polite-ravine-6v8g.here.now/) - [Public setup contract](https://polite-ravine-6v8g.here.now/agent.md) --- # Policy at the agent’s execution boundary — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The questions I already tell my agent "never force push" in CLAUDE.md. Why isn't that enough? Because that rule is something the model read once, maybe forty thousand tokens ago. An override is a message to the model at the exact moment it acts — it lands in the agent's tool output in the same turn as the blocked action: ``` text ▶ [session session-A] $ git push --force origin main [git-override session=session-A] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval. ``` If you can see that line in the transcript, the agent saw it too. It reads the guidance and changes course immediately — no hoping it remembered. How much machinery does that take? Two files in `.pi/`. The first is a settings file that tells Pi to source a zsh file before every command the agent runs: ``` text { "shellPath": "/bin/zsh", "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } ``` The second is that zsh file. A zsh function shadows the command of the same name — so `rm`, `git`, `linear`, and `ls` become yours to shape. No plugin API, no magic. So it's a sandbox? The agent physically can't delete my files? No — and the overrides say so in their own stderr. `command rm` and `command git` bypass the functions by design. This is guidance with teeth, not a security boundary: ``` text ▶ [session session-A] $ rm .demo-state/playground/important.txt [rm-override session=session-A] quarantined 1 item(s) in <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting. [rm-override] restore with: mv "<quarantine>/<name>" <dest>. Real deletion requires 'command rm' and explicit user approval. ``` The decision rule: use overrides to **steer** — redirect destructive commands, inject policy, brief the model. Use Pi's hooks and permission system to **enforce** anything you can't afford to have bypassed. Pi spawns a fresh shell for every command. How does "tell the agent this once per conversation" remember anything? Not with shell variables — those die with each shell. State lives on disk, keyed by conversation. The pi-session-id extension (~44 lines of TypeScript) exports the active conversation ID as `PI_SESSION_ID` into every shell, and then "once" is a single atomic `mkdir`: ``` text pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } ``` The first `ls` of a session returns instructions addressed to the AI; every later `ls` runs normally. The ID is validated against Pi's session-ID syntax before it touches shell source — an invalid value blocks the call rather than permitting injection. What happens when I hit /new or /fork — do I inherit stale "already briefed" state? No, and that's exactly why the session ID matters. State is keyed per conversation, so each `/new`, `/fork`, and parallel Pi process gets its own "first time". From the captured harness run: ``` text ▶ [session session-B] $ ls demo INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. ``` Session-A had already been briefed; session-B sees the briefing again. Without the extension, the fallback is `process-$PPID` — stable per shell process, not per conversation. Rewriting the agent's commands feels invasive. What does the `linear` override actually change? One subcommand, one flag. Only `linear issue create` is touched: whatever assignee the agent passed is dropped and `--assignee self` is appended — and the rewrite is announced on stderr so the agent knows policy fired: ``` text ▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else [linear-override session=session-A] enforcing --assignee self [linear-override dry-run] command linear issue create --title Fix\ login\ bug --assignee self ``` Every other `linear` subcommand passes through untouched. It's adapted from a working policy in a real test project — the point is the override owns the team rule, not the agent's memory of it. How do I trust any of this before an agent depends on it mid-session? Run it the way Pi does — fresh zsh, prefix sourced, `PI_SESSION_ID` set — with no agent in the loop. Four lines from your project root: ``` text command rm -rf "${TMPDIR:-/tmp}/pi-command-instructions/check-a" PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main' ``` First `ls` prints the briefing, second prints your normal listing, and the force push is refused with exit code 1. This project also ships `demo/run-demo.sh`, a five-act harness version of the same idea — an override you've never executed is a guess. Does this only work in pi? I'm in Claude Code half the day and Codex the other half. The mechanism is pi's; the move isn't. Every agent has a seam where its actions pass through, and all three give you a way to speak to the model right there. Codex agent shells are real non-interactive zsh — plain `codex` doesn't automatically receive your zsh helper/function surface, but a guard in your `.zshenv` can source chosen function files into agent shells that opt in. Same plain function shadowing as this page, stderr included. The opt-in is one env var — a local marker this setup invented, not a Codex built-in: ``` text codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' ``` Claude Code's seam is the tool call instead of the shell: a `PreToolUse` hook on `Bash` can deny a force push and hand the model the same "force push blocked" guidance this page's `git()` override prints — delivered before the command ever runs, with `session_id` arriving on the hook's stdin to play the `PI_SESSION_ID` role. In all three agents, the override's output at the moment of action IS the message to the model. The liftable files for both are in the [cross-agent section of the guide](https://polite-ravine-6v8g.here.now/index.html#same-trick-in-claude-code-and-codex). If Codex just runs zsh, why not source my whole .zshrc into its shells and be done with it? Because most of `.zshrc` exists for a human at a prompt — prompt setup, completions, keybindings, fuzzy finders — and in a non-interactive agent shell that machinery can slow, hang, or spam every single command the agent runs. Treat startup as an airlock: `.zshrc` stays sealed, a narrow agent-safe path carries PATH and non-secret env, and the marker is the valve that admits chosen helper files. The field rule: **missing PATH is not permission to pour `.zshrc` into Codex.** A missing tool means you fix the agent-safe path; a missing helper means you opt it in behind the valve. The guide's cross-agent section carries a complete agent setup prompt that builds the clean layout end to end. Fine — just give me the file. Here's `.pi/agent-shell.zsh`, complete. Keep `pi_session_id` and `pi_instruction_once` as-is; swap the four policy functions for your own — anything on PATH is fair game: ``` text # .pi/agent-shell.zsh # # Sourced before EVERY shell command the agent runs, via .pi/settings.json: # # { "shellPath": "/bin/zsh", # "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } # # Pi spawns a fresh shell per command, so plain shell variables can't carry # state between commands. The pi-session-id extension # (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into # each of those shells, which lets these overrides keep per-conversation state # on disk — e.g. "show this instruction once per session". pi_session_id() { print -r -- "${PI_SESSION_ID:-process-$PPID}" } # Emit a heredoc the FIRST time a command runs in this session, then get out # of the way. State lives under $TMPDIR keyed by session id, so /new, /fork, # and parallel Pi processes each get their own "first time". pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } # --- rm: quarantine instead of delete -------------------------------------- # The agent never permanently deletes anything. Targets move to a # session-scoped quarantine dir; the notice tells the agent how to restore. rm() { emulate -L zsh local session_id="$(pi_session_id)" local quarantine="${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id" local -a targets local arg for arg in "$@"; do [[ "$arg" == -* ]] || targets+=("$arg") done if (( ${#targets} == 0 )); then command rm "$@" return fi mkdir -p "$quarantine" || return 1 local moved=0 target for target in "${targets[@]}"; do if [[ -e "$target" || -L "$target" ]]; then mv -- "$target" "$quarantine/" && (( moved++ )) else print -u2 -- "[rm-override] no such file: $target" fi done print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting." print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval." } # --- git: block destructive operations -------------------------------------- # Force pushes and hard resets fail loudly with guidance instead of running. git() { emulate -L zsh local session_id="$(pi_session_id)" local arg if [[ "$1" == "push" ]]; then for arg in "$@"; do case "$arg" in -f|--force|--force-with-lease|--force-if-includes) print -u2 -- "[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." return 1 ;; esac done fi if [[ "$1" == "reset" ]]; then for arg in "$@"; do if [[ "$arg" == "--hard" ]]; then print -u2 -- "[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable." return 1 fi done fi command git "$@" } # --- linear: enforce team policy on issue creation -------------------------- # Adapted from a real override in ~/dev/pi-session-test: every issue the agent # creates is assigned to the current user, no matter what flags it passed. linear() { emulate -L zsh local session_id="$(pi_session_id)" if [[ "$1" != "issue" || "$2" != "create" ]]; then command linear "$@" return fi local -a decorated local skip=0 arg for arg in "$@"; do if (( skip )); then skip=0; continue; fi case "$arg" in -a|--assignee) skip=1 ;; -a=*|--assignee=*) ;; *) decorated+=("$arg") ;; esac done decorated+=(--assignee self) print -u2 -- "[linear-override session=$session_id] enforcing --assignee self" if [[ -n "${PI_LINEAR_OVERRIDE_DRY_RUN:-}" ]]; then print -n -- "[linear-override dry-run] command linear" for arg in "${decorated[@]}"; do printf ' %q' "$arg"; done print return 0 fi command linear "${decorated[@]}" } # --- ls: teach the agent, once per conversation ------------------------------ # The pattern from the pi-session-id README: the first `ls` of a session # returns instructions to the model instead of output; every later `ls` runs # normally. Swap the message for anything you want the agent told exactly once. ls() { if pi_instruction_once ls <<'INSTRUCTIONS'; then INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. INSTRUCTIONS return 0 fi command ls "$@" } ``` Want your agent to do the whole setup? Paste this into it: ``` text Fetch https://polite-ravine-6v8g.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` Reference ID: factory-environment-policy-questions Topic: Execution Sources: - [Policy at the agent’s execution boundary — questions and tradeoffs](https://polite-ravine-6v8g.here.now/dialogue.html) --- # Policy at the agent’s execution boundary — reference patterns Extended explanations, comparisons, experiments, and practical actions for the same operating pattern. ## Abstract Agents act through the shell, so the shell is the highest-leverage place to encode project policy. Pi runs every agent command in a fresh shell and lets a trusted project prepend a `shellCommandPrefix`, which makes one sourced zsh file a checkpoint for everything the agent executes. Stateless overrides can block a force push today; the pi-session-id extension adds a conversation-scoped key, `PI_SESSION_ID`, so overrides can also keep per-session state such as first-run instructions. The evidence here is the project's own override file and a captured transcript from a harness that reproduces Pi's execution model. The limit is equally concrete: these overrides are guidance the agent reads at the moment it acts, not a sandbox, and `command rm` walks straight past them. ## Notice where your policy actually runs You have probably written rules for your agent in a CLAUDE.md or AGENTS.md file: never force push, never hard-delete, always assign issues to yourself. Then, forty thousand tokens into a session, the agent runs `rm -rf` anyway. The mistake is treating instructions the model read once as if they control actions it takes much later. Every file deletion, push, and issue the agent creates passes through one place: the shell. A message printed by the shell arrives at the exact moment the agent acts, while a static instruction competes with everything else in context. That timing difference is the whole trick, and it is an editorial inference this page then tests against a captured transcript (S5). [1](https://polite-ravine-6v8g.here.now/#note-1) 1\. The workshop agenda (S6) frames this section as demoing the pi-session-id project and “overriding rm, linear, git, and other behavior.” The agenda also notes that hooks remain the tool for maximum control — a boundary section 5 returns to. [↩](https://polite-ravine-6v8g.here.now/#note-ref-1) Watch for the signal as you read: every override in this project prints a tagged line such as `[git-override session=…]` to stderr. If you can see that line in the agent's tool output, the agent saw it too — and can change course in the same turn. ## Explain the two files that rewire every command The entire mechanism is two files checked into the project. The first is `.pi/settings.json`, which tells Pi which shell to use and what to run before every command: ``` text { "shellPath": "/bin/zsh", "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } ``` **Figure 1.** The project's complete `.pi/settings.json` (S3), byte-identical to the file in the demo project. Source evidence, not a derived display. The second file, `.pi/agent-shell.zsh`, is plain zsh. Because Pi sources it before each command, any function defined there shadows the command of the same name. The pi-session-id README (S1) documents exactly this pattern: a project sources a function file through trusted `.pi/settings.json`, and `PI_SESSION_ID` is already present in the child environment before the prefix runs. [2](https://polite-ravine-6v8g.here.now/#note-2) 2\. “Trusted” matters: Pi asks you to approve a project's settings before it will run a prefix from them. An override file executes with your full permissions, so read it the way you would read a shell script from the internet — because it is one. [↩](https://polite-ravine-6v8g.here.now/#note-ref-2) **Working definition.** On this page, an override is a zsh function that shadows a command name for the agent's shell. The real binary stays reachable through `command rm`, `command git`, and so on. This is a convention for this page, not a term from the sources. This project ships four overrides (S3): `rm` moves targets to a session-scoped quarantine instead of deleting them; `git` blocks `push --force` and `reset --hard` with guidance; `linear` rewrites `issue create` so the issue is always self-assigned; and `ls` delivers a one-time briefing. The `linear` override is adapted from a working policy file in a sibling test project (S4), where every issue an agent creates is forced to `--assignee self` regardless of the flags it passed. ## Compare stateless guardrails with session-scoped memory Here is the fork in the road when you write your own override. Pi spawns a fresh shell process for every command, so a shell variable set during one command is gone by the next. Blocking a force push needs no memory — the evidence is in the argv right in front of you. But “tell the agent this once, then get out of the way” needs state that survives across those throwaway shells. Storing that state under a fixed path fails in a specific way: `/new`, `/resume`, `/fork`, and a second Pi process would all share one “first time.” The pi-session-id extension (S1, S2) solves this by exporting the active conversation ID as `PI_SESSION_ID` into each shell, synchronizing it on `session_start`, on human `!` commands, and on every model `bash` tool call, then clearing it on shutdown. [3](https://polite-ravine-6v8g.here.now/#note-3) 3\. The extension (S2) is about 44 lines of TypeScript. It validates the session ID against Pi's allowed syntax before inserting it into shell source; an invalid value blocks the tool call rather than permitting injection (S1). [↩](https://polite-ravine-6v8g.here.now/#note-ref-3) With that key available, per-conversation state is a directory name. The helper below creates a marker directory the first time a command runs in a session and emits its heredoc only then; the `ls` override uses it to brief the model once: ``` text pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } ls() { if pi_instruction_once ls <<'INSTRUCTIONS'; then INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. INSTRUCTIONS return 0 fi command ls "$@" } ``` **Figure 2.** The instruction-once helper and `ls` override from this project's `.pi/agent-shell.zsh` (S3), following the pattern published in the pi-session-id README (S1). Source evidence. The decision rule when you write your own: if the override can judge the command from its arguments alone, keep it stateless. Reach for `PI_SESSION_ID` only when the behavior must differ between the first occurrence in a conversation and every later one. ## Test the overrides before an agent depends on them An override you have never executed is a guess. The tempting shortcut is to install everything and find out mid-session, when a broken function makes every agent command fail. This project instead ships a harness, `demo/run-demo.sh`, that reproduces how Pi runs agent commands — a fresh zsh per command, the prefix sourced, `PI_SESSION_ID` set — so you can watch each override fire without Pi in the loop. ``` text ▶ [session session-A] $ ls demo INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. … ▶ [session session-A] $ ls demo run-demo.sh ▶ [session session-A] $ rm .demo-state/playground/important.txt [rm-override session=session-A] quarantined 1 item(s) in <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting. ▶ [session session-A] $ git push --force origin main [git-override session=session-A] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval. ▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else [linear-override session=session-A] enforcing --assignee self [linear-override dry-run] command linear issue create --title Fix\ login\ bug --assignee self ▶ [session session-B] $ ls demo INSTRUCTIONS FOR THE AI: … ``` **Figure 3.** Excerpt from the captured harness transcript (S5), reorganized for length: long lines are wrapped, repeated instruction text is elided with `…`, and the project's absolute path is shortened to `<project>`. A derived display of source output. **Evidence limit** This transcript comes from the harness, not from a live Pi session, and the `linear` call ran with a dry-run flag that prints the rewritten argv instead of hitting the Linear API. It demonstrates the shell functions faithfully; it does not by itself prove Pi's trust flow or the extension's lifecycle hooks, which the sources document separately (S1, S2). Read the transcript against the claims. First `ls`: instructions to the model. Second `ls`: normal output — the marker directory did its job. The quarantined file is listed, not gone. The force push never executed. The Linear issue lost its `--assignee someone-else` and gained `--assignee self`. And session-B sees the briefing again, because state is keyed by conversation. If you run the harness and any act differs, fix the override before letting an agent near it. ## Choose guidance with teeth, not a sandbox The last judgment call is what to trust these overrides *for*. The weak position treats them as a security boundary. The strong position treats them as high-signal steering: messages delivered at the moment of action that a cooperative agent reads and obeys. The coverage limits are documented, not hypothetical. The pi-session-id README (S1) lists what the mechanism does not cover: extension-internal `pi.exec()` calls, custom tools that spawn processes directly, and commands that clear their environment with `env -i` or `unset PI_SESSION_ID`. And within the shell itself, `command rm` bypasses the function by design — the overrides in this project even say so in their own stderr output (S3). **Evidence limit** Nothing here measures how often an agent complies with override guidance versus routing around it. The sources support the mechanism and its coverage, not a compliance rate. Treat “the agent self-corrects” as behavior to observe in your own sessions, not a guarantee. The decision rule: use shell overrides to **steer** — redirect destructive commands, inject policy, brief the model — and use Pi's hooks and permission system to **enforce** anything you cannot afford to have bypassed. If violating the rule merely wastes a turn, an override is enough. If violating it loses data or pushes broken history, put a real control behind the override's friendly message. ## Practical action To give one of your own projects a custom agent environment, in order: 1. Install the extension: `pi install git:github.com/johnlindquist/pi-session-id` (S1). 2. Copy the two files from this demo project: `.pi/settings.json` and `.pi/agent-shell.zsh`. 3. Replace the demo overrides with your policy. Keep each function's stderr message short, tagged, and addressed to the agent, and always leave the `command <name>` escape hatch documented. 4. Test with a harness before trusting: run each override in a fresh `zsh -c` with `PI_SESSION_ID` set, twice, under two session IDs. Your feedback signal is the tagged stderr line and, for stateful overrides, different behavior on the first and second run. 5. Open the project in Pi, approve the settings when prompted, and ask the agent to do something an override guards. If the agent reads the message and adjusts, the loop works; if it bypasses, move that rule into hooks or permissions. Reference ID: factory-environment-policy-reference-patterns Topic: Execution Sources: - [Prepared module reference](https://polite-ravine-6v8g.here.now/) --- # Policy at the agent’s execution boundary — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session You Pi runs every shell command my agent executes. I want a project-local hook that runs before each one — override `rm`, `git`, and friends for this project without touching my global zshrc. Agent Pi has exactly that hook: `shellCommandPrefix` in the project's `.pi/settings.json`. It prepends a snippet to every command the agent runs. Pointing it at a sourced zsh file makes every function in that file shadow the command of the same name: ``` text { "shellPath": "/bin/zsh", "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } ``` The whole integration is two JSON keys. Everything after this beat is plain zsh — no plugin API to learn, and the real binaries stay reachable via `command rm`, `command git`. You Start with `rm`. The agent should never permanently delete anything — move targets somewhere recoverable, and tell the agent what happened and how to undo it. Agent Added `rm()` to a new `.pi/agent-shell.zsh`. Targets move to a session-scoped quarantine dir, and both notices print to stderr, addressed to the model: ``` text print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting." print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval." ``` Those two stderr lines are the whole design: a message to the model at the moment it acts, not a rule it read forty thousand tokens ago. If you can see the line in the transcript, the agent saw it too. You Same idea for `git`: block `push --force` and `reset --hard`, and make the failure message tell the agent what to do instead. Agent Done — the override inspects argv and refuses with guidance before real git ever runs. From the captured harness transcript: ``` text ▶ [session session-A] $ git push --force origin main [git-override session=session-A] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval. ▶ [session session-A] $ git reset --hard HEAD~3 [git-override session=session-A] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable. ``` Exit code 1, nothing pushed, and the agent gets a next step it can act on in the same turn. `command git` still bypasses it — this is guidance with teeth, not a sandbox. You Now a real team policy: every Linear issue the agent files gets assigned to me. Rewrite `linear issue create` so `--assignee self` is enforced no matter what flags the agent passed. Agent The override strips any assignee the agent chose and appends `--assignee self`, announcing the rewrite on stderr. Dry-run mode prints the final argv: ``` text ▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else [linear-override session=session-A] enforcing --assignee self [linear-override dry-run] command linear issue create --title Fix\ login\ bug --assignee self ``` Adapted from a working policy in a private test project. It rewrites only `issue create`; every other `linear` subcommand passes through untouched. You The tricky one: brief the model exactly once per conversation. The first `ls` should return instructions to the AI; every later `ls` runs normally. But Pi spawns a fresh shell per command — where does "once" live? Agent Not in shell variables — a fresh shell forgets everything. State has to live on disk, keyed by the *conversation*, or `/new` and `/fork` would inherit a stale "already briefed" flag. Installed the pi-session-id extension (`pi install git:github.com/johnlindquist/pi-session-id`), which exports `PI_SESSION_ID` into every shell Pi spawns. With that key, "once per session" is one atomic `mkdir`: ``` text pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } ``` `mkdir` succeeds exactly once per marker path, so "first time" is race-free even with parallel Pi processes. The extension itself is ~44 lines of TypeScript syncing the session ID on `session_start`, human `!` commands, and every model bash call — with the ID validated before it touches shell source. You Prove all of it without Pi in the loop. I want a harness that runs commands exactly the way Pi does, so a broken override never takes down a live session. Agent Wrote `demo/run-demo.sh`: fresh zsh per command, prefix sourced, `PI_SESSION_ID` set — Pi's execution model, reproduced. Ran it; the captured transcript (checked in as `demo/sample-output.txt`): ``` text ▶ [session session-A] $ ls demo INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. ▶ [session session-A] $ ls demo run-demo.sh sample-output.txt ▶ [session session-A] $ rm .demo-state/playground/important.txt [rm-override session=session-A] quarantined 1 item(s) in <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting. ▶ [session session-A] $ ls .demo-state/tmp/pi-rm-quarantine/session-A important.txt ▶ [session session-B] $ ls demo INSTRUCTIONS FOR THE AI: … ``` The beat that matters most is the last one: session-B sees the briefing again. State is keyed per conversation, not per machine — `/new` and `/fork` each get their own "first time". You Land it. Give me the whole override file so I can lift it into any project. Agent Here is `.pi/agent-shell.zsh`, complete — the section's money artifact. Keep `pi_session_id` and `pi_instruction_once` as-is; swap the four policy functions for your own: ``` text # .pi/agent-shell.zsh # # Sourced before EVERY shell command the agent runs, via .pi/settings.json: # # { "shellPath": "/bin/zsh", # "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" } # # Pi spawns a fresh shell per command, so plain shell variables can't carry # state between commands. The pi-session-id extension # (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into # each of those shells, which lets these overrides keep per-conversation state # on disk — e.g. "show this instruction once per session". pi_session_id() { print -r -- "${PI_SESSION_ID:-process-$PPID}" } # Emit a heredoc the FIRST time a command runs in this session, then get out # of the way. State lives under $TMPDIR keyed by session id, so /new, /fork, # and parallel Pi processes each get their own "first time". pi_instruction_once() { emulate -L zsh local command_name="$1" local state_root="${TMPDIR:-/tmp}/pi-command-instructions" local session_id="$(pi_session_id)" local marker="$state_root/$session_id/$command_name" mkdir -p "$state_root/$session_id" || return 1 if mkdir "$marker" 2>/dev/null; then cat return 0 fi return 1 } # --- rm: quarantine instead of delete -------------------------------------- # The agent never permanently deletes anything. Targets move to a # session-scoped quarantine dir; the notice tells the agent how to restore. rm() { emulate -L zsh local session_id="$(pi_session_id)" local quarantine="${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id" local -a targets local arg for arg in "$@"; do [[ "$arg" == -* ]] || targets+=("$arg") done if (( ${#targets} == 0 )); then command rm "$@" return fi mkdir -p "$quarantine" || return 1 local moved=0 target for target in "${targets[@]}"; do if [[ -e "$target" || -L "$target" ]]; then mv -- "$target" "$quarantine/" && (( moved++ )) else print -u2 -- "[rm-override] no such file: $target" fi done print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting." print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval." } # --- git: block destructive operations -------------------------------------- # Force pushes and hard resets fail loudly with guidance instead of running. git() { emulate -L zsh local session_id="$(pi_session_id)" local arg if [[ "$1" == "push" ]]; then for arg in "$@"; do case "$arg" in -f|--force|--force-with-lease|--force-if-includes) print -u2 -- "[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval." return 1 ;; esac done fi if [[ "$1" == "reset" ]]; then for arg in "$@"; do if [[ "$arg" == "--hard" ]]; then print -u2 -- "[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable." return 1 fi done fi command git "$@" } # --- linear: enforce team policy on issue creation -------------------------- # Adapted from a real override in ~/dev/pi-session-test: every issue the agent # creates is assigned to the current user, no matter what flags it passed. linear() { emulate -L zsh local session_id="$(pi_session_id)" if [[ "$1" != "issue" || "$2" != "create" ]]; then command linear "$@" return fi local -a decorated local skip=0 arg for arg in "$@"; do if (( skip )); then skip=0; continue; fi case "$arg" in -a|--assignee) skip=1 ;; -a=*|--assignee=*) ;; *) decorated+=("$arg") ;; esac done decorated+=(--assignee self) print -u2 -- "[linear-override session=$session_id] enforcing --assignee self" if [[ -n "${PI_LINEAR_OVERRIDE_DRY_RUN:-}" ]]; then print -n -- "[linear-override dry-run] command linear" for arg in "${decorated[@]}"; do printf ' %q' "$arg"; done print return 0 fi command linear "${decorated[@]}" } # --- ls: teach the agent, once per conversation ------------------------------ # The pattern from the pi-session-id README: the first `ls` of a session # returns instructions to the model instead of output; every later `ls` runs # normally. Swap the message for anything you want the agent told exactly once. ls() { if pi_instruction_once ls <<'INSTRUCTIONS'; then INSTRUCTIONS FOR THE AI: This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. Deletions are quarantined, force pushes are blocked, and Linear issues are always self-assigned. Run ls again to execute the command normally. INSTRUCTIONS return 0 fi command ls "$@" } ``` Verified with the four-line success check — fresh zsh, two session ids, output matching the transcript above: ``` text command rm -rf "${TMPDIR:-/tmp}/pi-command-instructions/check-a" PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls' PI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main' ``` Seven beats: one settings hook, four overrides, one state trick, one harness. The same recipe generalizes to anything on PATH — wrap `npm` to enforce pnpm, wrap `curl` to log egress, wrap `pytest` to always add `-x`. Rebuilt from a prior session using this project's real files: prompts are condensed, but every file shown matches disk byte-for-byte and every output line comes from the checked-in `demo/sample-output.txt` (project path replaced with `<project>`). Reference ID: factory-environment-policy-worked-example Topic: Execution Sources: - [Policy at the agent’s execution boundary — worked example](https://polite-ravine-6v8g.here.now/replay.html) --- # Ralph Loop stop-hook continuation playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already run agents against real repos, dev servers, browser panes, and local QA loops; the Ralph Loop helps those agents keep working toward a bounded goal instead of stopping after one polite assistant turn. It is especially useful for web tasks where success is observable only after code, tests, logs, and browser behavior line up. [Core principles](/topics/foundations-hooks-and-context-hygiene/) ## Current Codex Stop contract A Ralph Loop must use the Stop event’s continuation decision, not a general hook-output flag. In the [official Stop contract](https://developers.openai.com/codex/hooks#stop), a synchronous hook that exits successfully requests another pass by writing JSON such as: ```json {"decision":"block","reason":"Original goal: prove the checkout flow. Browser proof is still missing. Run the bounded checkout verification, save the observed result, and re-check the completion criteria."} ``` For `Stop`, `decision: "block"` does not reject the work: Codex creates a continuation prompt from `reason`, acting as a new user prompt. The reason should identify the original goal, the missing evidence, and the next bounded action. `{"continue":true}` alone does **not** request another turn. `systemMessage` and `suppressOutput` are not substitutes for a Stop continuation decision. When completion is verified, the iteration cap is reached, or a blocker requires human review, the hook can explicitly end continuation: ```json {"continue":false,"stopReason":"Iteration cap reached; browser proof remains missing. Stop for review, not success."} ``` Use a truthful reason for the actual terminal state. A cap or blocker is not evidence that the goal succeeded. Returning JSON without a blocking decision leaves this hook with no continuation request; `continue: false` is stronger and takes precedence over continuation decisions from other matching Stop hooks. - On exit code `0`, Stop output must be valid JSON; plain text on stdout is invalid. An alternative continuation signal is exit code `2` with the reason on stderr. - `stop_hook_active` reports whether Stop already continued this turn. It is a boolean, not a persistent iteration counter. Maintain an explicit run-scoped cap and check completion evidence on every invocation. - Keep the Stop hook synchronous and fast. It should inspect evidence and decide, not perform the slow browser/API work itself. Background hooks cannot enforce turn continuation. - Review and trust the exact hook definition through `/hooks`; installing a plugin is not the same as trusting its hooks. Recheck after hook definitions change. - Plugin configuration and supported fields are version-specific. The historical reference below is retained for context, but use the event-specific contract above for an operational Stop loop. ## Copy-paste workflow **When to use:** When you want an agent to pursue a goal across many turns without manual nudging. A Stop hook re-checks the original task when the agent tries to stop and pushes it to keep working until a clear completion condition is met. ### Copy-paste prompt ```text You are my coding agent. Build a minimal "Ralph Loop" Codex plugin: a Stop hook that re-points the agent at the original goal and requests another pass until a completion condition or hard cap is reached. This workflow uses UserPromptSubmit, PreToolUse (Tool Use), and Stop as its three teaching landmarks; they are not the complete current event list. The Ralph Loop is a STOP hook. Use the Current Codex Stop contract above. 1. First enable hooks + plugins in ~/.codex/config.toml, then restart Codex: [features] hooks = true plugins = true plugin_hooks = true 2. Scaffold the real plugin layout: my-plugin/ .codex-plugin/plugin.json # manifest, with "hooks": "hooks/hooks.json" hooks/hooks.json # wires a Stop hook command hooks/hook.py # the Stop hook script 3. In hooks/hooks.json, wire the Stop event to run the hook script, e.g.: { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\"", "timeout": 5 } ] } ] } } 4. hook.py reads the Stop event JSON on stdin and writes EXACTLY ONE JSON line. When the goal is incomplete and the hard cap has not been reached, emit {"decision":"block","reason":"<original goal, missing evidence, and next bounded action>"}. When completion is verified, the cap is reached, or a blocker needs review, emit {"continue":false,"stopReason":"<truthful terminal reason>"}. Never report cap exhaustion as success. Do not rely on continue:true or suppressOutput to request another turn. Keep the hook synchronous, fast, and boring. CRITICAL guardrail: the loop MUST have a hard completion condition — an iteration cap or an explicit target state — enforced by the hook, not just suggested in a prompt. Without it you get a runaway loop. ``` ### How it works - UserPromptSubmit, tool-use events, and Stop are the lifecycle landmarks used here; current Codex supports additional events. The Ralph Loop uses Stop. - The source plugin examples enable `hooks`, `plugins`, and `plugin_hooks` in `~/.codex/config.toml` and restart Codex. Treat these flags as version-specific setup, and review/trust the installed hook definitions through `/hooks`. - The real plugin layout is `.codex-plugin/plugin.json` (manifest) + `hooks/hooks.json` (wiring) + a hook script; `${CODEX_PLUGIN_ROOT}` resolves the plugin dir. - The hook reads event JSON and emits a Stop-specific decision: `{"decision":"block","reason":"<next bounded action>"}` requests continuation. `{"continue":true}` alone does not. The harness acts on the decision and uses the reason as a new continuation prompt. - CRITICAL: require an explicit completion condition (iteration cap or target state) or you get runaway loops. - Reference: [Codex Hooks docs](https://developers.openai.com/codex/hooks), [Better Plugins](https://github.com/johnlindquist/better-plugins/tree/main/plugins). ## Reusable skill Install as `~/.agents/skills/ralph-loop-hook/SKILL.md`, then restart Codex. ````markdown --- name: ralph-loop-hook description: Trigger when the user wants an agent to keep pursuing a goal across turns via a Codex Stop hook (the Ralph Loop). Do NOT use without a clear completion condition — unbounded loops waste tokens and run tools too long. --- # Ralph Loop hook Scaffold a Ralph Loop: a Codex Stop hook that, when the agent tries to stop, re-points it at the original goal and requests another pass until a completion condition or hard cap is reached — enforced by the harness, not merely suggested in a prompt. UserPromptSubmit, PreToolUse (Tool Use), and Stop are the three teaching landmarks for this workflow, not the exhaustive current event list. The Ralph Loop uses Stop. ## Prerequisite Enable hooks + plugins in `~/.codex/config.toml`, then restart Codex: ```toml [features] hooks = true plugins = true plugin_hooks = true ``` `/plugins` confirms install; `/hooks` reviews/trusts bundled hooks. ## Steps 1. Scaffold the real plugin layout: ``` my-plugin/ .codex-plugin/plugin.json # manifest, with "hooks": "hooks/hooks.json" hooks/hooks.json # hook wiring hooks/hook.py # the Stop hook script ``` 2. Wire the Stop event in `hooks/hooks.json`: ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\"", "timeout": 5 } ] } ] } } ``` 3. `hooks/hook.py` reads the Stop event JSON on stdin and writes EXACTLY ONE JSON line. While the goal is incomplete and below its hard cap, emit `{"decision":"block","reason":"<original goal, missing evidence, next bounded action>"}`. On verified completion, cap exhaustion, or a blocker requiring review, emit `{"continue":false,"stopReason":"<truthful terminal reason>"}`. Cap exhaustion is not success. `continue:true` alone does not request another turn; do not use `suppressOutput` as a continuation mechanism. Keep the hook synchronous and fast; let the resumed agent or a separate worker perform slow work, then inspect its evidence on the next Stop invocation. ## Guardrails - MANDATORY: a hard completion condition (iteration cap or target state) enforced by the hook. Without it you get a runaway loop that wastes tokens and runs tools too long. ```` ## Scenarios ### Keep fixing a checkout bug until browser proof passes **Role:** As a senior frontend engineer responsible for a Next.js checkout flow A local Next.js app has a flaky checkout path: the agent often fixes one validation error, reports done, and stops before proving the full browser flow from cart to confirmation. The team wants a Ralph Loop plugin that keeps the agent on the original checkout goal until tests and browser evidence prove the flow works. > As a senior frontend engineer, I want a Stop hook to re-point the agent at the original checkout goal until the checkout flow passes, so that the agent does not stop after only a partial code fix. #### Agent brief ```text Build a minimal Ralph Loop Codex plugin for this repo. Inspect the Copy-paste workflow section of this playbook and the Reusable skill section of this playbook first. Enable hooks and plugins in ~/.codex/config.toml with hooks=true, plugins=true, plugin_hooks=true, then tell me to restart Codex before testing. Scaffold ralph-loop-checkout/.codex-plugin/plugin.json, ralph-loop-checkout/hooks/hooks.json, and ralph-loop-checkout/hooks/hook.py. Wire only the Stop hook to python3 "${CODEX_PLUGIN_ROOT}/hooks/hook.py" with timeout 5. The hook must read stdin JSON and write exactly one control JSON line. Store tiny local state for the original goal and iteration count. Completion condition: stop when all of these receipts exist in .notes/ralph-loop-checkout/: passing-test.log, browser-proof.md, and final-summary.md, or when iteration_count reaches 5. Do not use suppressOutput in Stop. After scaffolding, run a local simulation command that pipes mock Stop events into hook.py and proves both paths: continue before receipts exist, allow stop after receipts exist or at the cap. Expected output: plugin files, a short README section showing install/test steps, and simulation logs saved under .notes/ralph-loop-checkout/. ``` #### Implementation references [Open reference](/topics/foundations-ralph-loop-playbook/) [Open reference](/topics/foundations-ralph-loop-playbook/) [Open reference](/topics/foundations-ralph-loop-playbook/#command-reference) ```text ~/.codex/config.toml ``` ```text ralph-loop-checkout/.codex-plugin/plugin.json ``` ```text ralph-loop-checkout/hooks/hooks.json ``` ```text ralph-loop-checkout/hooks/hook.py ``` #### Browser verification Use the app's local dev server and a browser agent or Playwright-style flow to visit the checkout route, add a test item, fill the checkout form, submit, and capture the confirmation page state. Save the route, actions, visible confirmation text, and any console errors to .notes/ralph-loop-checkout/browser-proof.md. If running inside CMUX, open or use a browser pane for the local app and keep the terminal pane visible for test output. #### Definition of done - A valid Codex plugin layout exists with .codex-plugin/plugin.json, hooks/hooks.json, and hooks/hook.py. - hooks/hooks.json wires a Stop hook command and does not add unrelated lifecycle hooks. - hook.py emits exactly one control JSON line per event and never emits suppressOutput for Stop. - A hard completion condition is enforced by receipt files plus an iteration cap of 5. - Simulation logs show the hook continues before checkout proof exists and allows stopping after proof or cap. - .notes/ralph-loop-checkout/browser-proof.md records the browser flow, visible result, and console-error status. #### Failure modes and mitigations - Common mistake: the agent only writes a prompt that says 'keep going' instead of enforcing continuation in a Stop hook. Mitigation: require a real hooks/hooks.json Stop entry and a hook.py simulation log. - Common mistake: the loop is unbounded and can churn on tools forever. Mitigation: enforce the iteration cap in hook state and treat missing proof after the cap as a failed receipt, not silent success. ### Stop-hook guard for visual regression cleanup **Role:** As a product-minded UI developer polishing a dashboard redesign A dashboard redesign has several small layout regressions across authenticated pages. Agents keep fixing the first obvious CSS issue and stopping without checking the rest of the dashboard routes in the running app. > As a UI developer, I want a Ralph Loop to keep the agent cycling through the original dashboard acceptance criteria until browser receipts are written for each target route, so that layout cleanup is proven in the app instead of inferred from code. #### Agent brief ```text Create a Ralph Loop plugin named ralph-loop-dashboard for dashboard visual cleanup. Start by reading the Hooks and context hygiene article, the Copy-paste workflow section of this playbook, and the Command reference section of this playbook. Use the taught lifecycle model: UserPromptSubmit, PreToolUse or Tool Use, and Stop; implement only the Stop hook for this scenario. Plugin layout must be ralph-loop-dashboard/.codex-plugin/plugin.json, ralph-loop-dashboard/hooks/hooks.json, and ralph-loop-dashboard/hooks/hook.py. Add a .notes/ralph-loop-dashboard/acceptance.md file that lists the exact dashboard routes to verify and a .notes/ralph-loop-dashboard/proofs/ directory for receipts. Completion condition: allow stop only when acceptance.md has every route marked verified with a matching proof markdown file, or when 4 Stop iterations have happened. Each continuation message should point back to the original dashboard goal and name the next missing route proof. Expected output: plugin scaffold, acceptance/proof file contract, hook simulation, and instructions for installing with codex plugin marketplace add "$PWD" then codex plugin add ralph-loop-dashboard@better-plugins only if this repo is being used as a marketplace-style plugin source. ``` #### Implementation references [Open reference](/topics/foundations-hooks-and-context-hygiene/) [Open reference](/topics/foundations-ralph-loop-playbook/) [Open reference](/topics/foundations-ralph-loop-playbook/#command-reference) ```text .notes/ralph-loop-dashboard/acceptance.md ``` ```text .notes/ralph-loop-dashboard/proofs/ ``` ```text codex plugin marketplace add "$PWD" ``` ```text codex plugin add ralph-loop-dashboard@better-plugins ``` #### Browser verification Use a CMUX browser pane, agent-browser-style accessibility snapshot/click/fill/evaluate workflow, or Playwright to visit each listed dashboard route on localhost. For each route, capture the route URL, viewport size, key visible labels, broken layout notes, and console errors. Write one proof file per route under .notes/ralph-loop-dashboard/proofs/ and mark the route verified in acceptance.md only after the browser check has actually run. #### Definition of done - The Stop hook can identify the next missing dashboard route proof from acceptance.md. - The hook continues while route proofs are missing and allows stop only after all proofs exist or after 4 iterations. - Each route has a proof markdown file with URL, viewport, visible labels, and console-error status. - The plugin scaffold uses the real Codex plugin layout and keeps hook work fast and boring. - The final review artifact explains which routes were checked, which files changed, and whether any proof is still missing. #### Failure modes and mitigations - Common mistake: the agent marks routes verified from source inspection alone. Mitigation: require browser proof files and reject completion when a proof file is missing. - Common mistake: the hook tries to do browser automation itself and becomes slow or brittle. Mitigation: keep the hook limited to state checks and continuation control; put browser verification in the agent workflow and receipt files. ### Prototype a safe Ralph Loop before installing it globally **Role:** As a developer-tools engineer maintaining local Codex plugin experiments The team wants to experiment with stop-hook continuation, but the Better Plugins material is prototype-stage and personally configured. Before installing anything globally, they need a toy Ralph Loop with deterministic local simulation and clear guardrails. > As a developer-tools engineer, I want a toy Ralph Loop plugin with local simulations and an explicit completion cap, so that we can learn the hook mechanics without risking a runaway agent session in a production repo. #### Agent brief ```text Build a toy plugin named ralph-loop-toy that demonstrates the Ralph Loop without touching application code. Use only the taught plugin/hook model from lesson 07 and the existing toolkit artifacts. Read the Hooks and context hygiene article, the documented scope and caveats in this playbook, the Reusable skill section of this playbook, and the Command reference section of this playbook. Scaffold ralph-loop-toy/.codex-plugin/plugin.json, ralph-loop-toy/hooks/hooks.json, ralph-loop-toy/hooks/hook.py, and ralph-loop-toy/tests/simulate-stop-events.py. The toy goal is: create .notes/ralph-loop-toy/done.txt containing DONE. The Stop hook should continue until done.txt exists or until iteration_count reaches 3. The simulator must run three cases: no done.txt means continue, done.txt means stop, cap reached means stop with a clear failure note. Expected output: the plugin files, simulator output, and a short README that tells developers to review /plugins and /hooks after install and to restart Codex after config changes. ``` #### Implementation references [Open reference](/topics/foundations-hooks-and-context-hygiene/) [Open reference](/topics/foundations-hooks-and-context-hygiene/) [Open reference](/topics/foundations-ralph-loop-playbook/) [Open reference](/topics/foundations-ralph-loop-playbook/#command-reference) ```text ralph-loop-toy/tests/simulate-stop-events.py ``` ```text ~/.codex/config.toml ``` ```text /plugins ``` ```text /hooks ``` #### Browser verification Browser proof is not the right proof for this toy plugin because the goal is hook mechanics, not web-app behavior. The useful UI move is optional: if running in CMUX, open a live Markdown tracker with cmux markdown open .notes/ralph-loop-toy/tracker.md --direction right so the human can watch the simulation cases and receipts update. #### Definition of done - Toy plugin files exist in the real plugin directory layout. - hooks/hooks.json wires the Stop event to hook.py with a short timeout. - simulate-stop-events.py proves continue, success stop, and cap stop behavior without requiring a live Codex session. - The README includes the required ~/.codex/config.toml feature flags and restart note. - The implementation avoids production app edits, broad plugin behavior, and unbounded continuation. #### Failure modes and mitigations - Common mistake: installing a prototype globally before proving local behavior. Mitigation: require simulator output before any install instructions are followed. - Common mistake: mixing in #human, Toolsmith, Gemini Video, or dashboard behavior. Mitigation: keep this scenario to exactly one technique: Stop-hook continuation. ## Implementation notes - Keep the Ralph Loop to exactly one toolkit technique: Stop-hook continuation. Browser checks, Markdown trackers, and simulation scripts are proof surfaces, not extra toolkit topics. - The hook should be fast and boring: parse event input, inspect small local state or receipt files, emit one control JSON line, and exit. - Use a hard completion condition every time: iteration cap, explicit target state, or both. A Stop hook without a bound is not a workshop-quality scenario. - For web-app scenarios, require browser receipts because source inspection alone does not prove UI behavior. - Keep receipt files local under .notes/ so developers can inspect proof without committing noisy agent scratch work. - Do not assume browser cookies are available to an agent-browser workflow. Authenticated flows need an explicit login/setup path or a local test fixture. - Treat Better Plugins examples as prototype reference material, not polished drop-in infrastructure. ## Boundaries and caveats - Do not introduce MCP wrappers, daemon profiles, self-improving hooks, or background-worker architectures for this topic. - Do not present #human, Toolsmith, or Gemini Video as part of the Ralph Loop implementation; they may be references, but this workflow is about Stop-hook continuation. - Do not rely on a prompt-only 'keep going' instruction as the implementation. The taught distinction is that the harness enforces continuation through a Stop hook. - Do not create unbounded loops, broad permissions, or hooks that perform slow browser/API work directly. ## Agent reference map ### Validated lesson 07 references Use this as the source of truth for what was taught: compaction/forking, the big three hooks, Ralph Loop, skills versus plugins, and custom grammar triggers. [Open reference](/topics/foundations-hooks-and-context-hygiene/) ### Lesson 07 validation notes Use this to avoid overclaiming or reintroducing details that were removed from the validated lesson scope. [Open reference](/topics/foundations-hooks-and-context-hygiene/) ### Existing Ralph Loop prompt Use this as the implementation-facing prompt baseline for scaffolding a minimal Stop-hook continuation plugin. [Open reference](/topics/foundations-ralph-loop-playbook/) ### Existing Ralph Loop Codex skill Use this as the concise reusable skill contract: trigger conditions, prerequisite config, plugin layout, Stop hook wiring, and guardrails. [Open reference](/topics/foundations-ralph-loop-playbook/) ### Verified Better Plugins command and layout notes Use this for the real plugin directory layout, hooks.json shape, control JSON rules, and install commands; do not invent plugin flags. [Open reference](/topics/foundations-ralph-loop-playbook/#command-reference) ### CMUX CLI notes Use only for optional local workspace proof such as browser panes, live Markdown trackers, reading screens, or inspecting panes. [Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference) ## Command reference These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs. ## Enable hooks + plugins (~/.codex/config.toml) ```toml [features] hooks = true plugins = true plugin_hooks = true ``` Restart Codex after installing/updating. `/plugins` confirms install; `/hooks` reviews/trusts bundled hooks. ## Plugin directory layout (real) ``` my-plugin/ .codex-plugin/plugin.json # manifest hooks/hooks.json # hook wiring hooks/<entrypoint>.py|.js # hook scripts ``` ## Manifest example (plugins/gemini-video/.codex-plugin/plugin.json — real) ```json { "name": "gemini-video", "description": "Detects .mp4 paths in prompts/tool calls and summarizes them with Gemini in a detached worker.", "version": "0.1.0", "hooks": "hooks/hooks.json" } ``` ## hooks.json — three selected lifecycle events from the source plugin ```json { "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\"", "timeout": 8 } ] } ], "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\"", "timeout": 5 } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\"", "timeout": 5 } ] } ] } } ``` (Toolsmith uses `UserPromptSubmit` and `PreToolUse`; `${PLUGIN_ROOT}` / `${CODEX_PLUGIN_ROOT}` resolve the plugin dir.) ## Historical hook-output example The source `hook_control.py` example below is preserved as a version-specific historical specimen, **not** as a reliable current Stop continuation implementation. Its `continue: true` permits normal hook processing; it does not by itself force another agent turn. Its comment about `suppressOutput` reflects the source implementation, not the current event-support contract. ```python def control_for_event(event_name: str) -> dict: out = {"continue": True} if event_name == "UserPromptSubmit": out["suppressOutput"] = True # suppressOutput is ONLY valid on UserPromptSubmit return out # emit: sys.stdout.write(json.dumps(out, separators=(",", ":")) + "\n") ``` The historical source claimed that Codex rejected `suppressOutput` outside UserPromptSubmit. Current [common output documentation](https://developers.openai.com/codex/hooks#common-output-fields) lists it for several events, including Stop, as parsed but not yet implemented; support remains event-specific. Neither that field nor `continue: true` blocks Stop. Use `decision: "block"` with a reason for continuation, and keep hooks fast: parse minimal state, inspect evidence, emit valid event-specific JSON, and leave slow work outside the Stop handler. ## Ralph Loop (taught concept, lesson 07/08) A Stop hook that, when the agent tries to stop, re-points it at the original goal and continues until a completion condition is met — enforced by the harness, not merely suggested in a prompt. MUST have a hard completion condition (iteration cap / target state) to avoid runaway loops. ## Install (README, real) ```bash codex plugin marketplace add johnlindquist/better-plugins # or: codex plugin marketplace add "$PWD" codex plugin add <name>@better-plugins # after edits: codex plugin remove <name>@better-plugins && codex plugin add <name>@better-plugins ``` ## Toolsmith data paths (real) `~/.codex/plugins/data/better-plugins-toolsmith/` (events/ raw JSONL, indexes/tool-index.json compact). Reference ID: foundations-ralph-loop-playbook Topic: Execution Sources: - [Official Codex Stop hook contract](https://developers.openai.com/codex/hooks#stop) - [Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-07.html) --- # Reusable flow and skill recipes Complete small contracts for code review, onboarding, test repair, changelogs, PR descriptions, pane-aware standups, and preference capture. ## skills/fixit/SKILL.md ```yaml name: fixit description: Expert debugger — take a bug report, reproduce it, find the root cause, fix it, and prove the fix. Use when the user pastes a bug report, error output, or stack trace and wants it diagnosed and fixed. ``` ## fixit — expert debugger Skill twin of the `fixit` wrapper from the prompt-builder guide (https://shiny-bloom-f8hv.here.now/) — the same job in its third form: zsh wrapper → mdflow flow (`flows/fixit.codex.md`) → agent skill. You're an expert debugger. The user's message is the bug report. ## Steps 1. Restate the bug in one sentence so a wrong reading dies early. 2. Reproduce it — run the failing command, test, or flow and capture the actual output. If you can't reproduce, say exactly what you tried and stop. 3. Find the root cause. Read the code on the failure path; don't patch symptoms. 4. Fix it, minimally. 5. Prove it — re-run the reproduction and show the before/after. If the report is too vague to reproduce (no steps, no error, no location), ask for the missing piece instead of guessing. ## flows/this-or-that.md ```yaml description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules _inputs: [_question, _subject] _interactive: true ``` You are running one round of the **this-or-that decision flow**: the user can't articulate their taste, but they can pick between two things all day. Turn the question below into an Elo-voted decision with a durable record. **Question to decide:** {{ _question }} **Subject / content source (hold constant across every option):** {{ _subject }} ## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`) 1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy, API shape). Everything else — subject content, visual theme — is held constant so votes measure only that axis. 2. **Scaffold the lab.** Create `<slug>-lab/` at the repo root. Copy `compare.html` and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json` (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base stylesheet all options link, so theme stays constant; support `html[data-mode="light|dark"]` (light default, `prefers-color-scheme` + `data-mode` override) — the harness stamps it and records the mode on every vote. 3. **Generate 9–13 structurally distinct options.** Same subject, different approach; if two could be confused at arm's length, replace one. Include the incumbent as a control when one exists. Write one exemplar option yourself, then fan out parallel subagents, each authoring 2–3 options from one tight shared brief (subject digest + format rules + per-option spec + the exemplar path). Real content only — never lorem ipsum, never invented names. 4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit (zero external requests, no absolute home paths, no secrets); render both light and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`, remove it. 5. **Hand over and get out of the way.** Start `python3 server.py <port>` in the background and give the user the `compare.html` URL. Controls: ←/→ pick · ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field saves with each vote (tell the user: one note outweighs ten votes). 6. **When the user says "done":** read `votes.jsonl` — ranking, per-mode W-L splits, `both_bad` lines, and especially notes. State the user's taste as explicit, quotable rules backed by vote evidence (head-to-heads, splits, quoted notes). A user note that makes a decision IS the decision. 7. **Bank it.** Archive as `votes-round<N>.jsonl`, write `RESULTS.md` (standings table, the decision with quoted evidence, taste rules, ship plan), update agent memory so it is never re-litigated. Then propose round 2 from the winners — or ship. ## Accumulated taste record (injected fresh each run — read before generating options) @../authoring-lab/RESULTS.md @../07-variations/template-lab/RESULTS.md ## flows/workshop-standup.claude.md ```yaml description: pane-aware standup — agent starts already knowing git, panes, and tickets model: sonnet print: true ``` You are a standup assistant. Everything below was captured at prompt-build time, BEFORE you started — do not re-run these commands. ## Repo state (git) !`git status --short --branch` !`git log --oneline -5 2>/dev/null || echo "(no commits yet)"` ## Terminal workspace (herdr panes) !`herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)"` ## Open tickets (linear) !`echo "(placeholder: linear 'list my in-progress issues' — sandboxed agent call)"` ## Your job From the preloaded context only: 1. Say what I'm in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. ## skills/pr-description/SKILL.md ```yaml name: pr-description description: Write a pull-request description for the current branch — what changed, why, and how to verify it, under 200 words, leading with the outcome. Use when the user says "write the PR description", "describe this branch", or is about to open a pull request. ``` ## pr-description — write a PR description for the current branch Skill twin of the mdflow flow `flows/pr-description.md` (https://walnut-virtue-6d22.here.now/). The flow preloads the branch history at prompt-build time; this skill has you fetch it yourself. ## Steps 1. Gather the branch state (fall back if there's no `main`): ```bash git log --oneline main..HEAD 2>/dev/null || git log --oneline -10 git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~5 ``` 2. Write the pull-request description: what changed, why, and how to verify it. Lead with the outcome. Keep it under 200 words. ## skills/onboard/SKILL.md ```yaml name: onboard description: Explain the current codebase to a newcomer — what it does, how it's laid out, where the core logic lives, and the three files to read first. Use when the user says "onboard me", "explain this codebase", "I'm new here", or asks for a project orientation. ``` ## onboard — explain this codebase to a newcomer Skill twin of the mdflow flow `flows/onboard.md` (https://walnut-virtue-6d22.here.now/). ## Your job Explore the repository, then explain it to someone joining the project today: 1. What it does — the one-paragraph purpose. 2. How it's laid out — the directory map that matters, not every folder. 3. Where the core logic lives. 4. The three files to read first, with one line each on why. If the user names a focus area (e.g. "onboard me, I care about the billing code"), weight the whole answer toward it. ## skills/fix-tests/SKILL.md ```yaml name: fix-tests description: Run the project's test suite and fix whatever fails — root cause in the code, not the test, unless the test is genuinely wrong. Use when the user says "fix the tests", "make the suite green", or tests are failing and they want them repaired. ``` ## fix-tests — run the test suite and fix what fails Skill twin of the mdflow flow `flows/fix-tests.md` (https://walnut-virtue-6d22.here.now/). ## Steps 1. Find and run this project's test suite (check package.json scripts, Makefile, CI config — whatever the project actually uses). 2. If everything passes, say so and stop. 3. If anything fails: show the failing output first, then find the root cause and fix it — the code, not the test, unless the test is genuinely wrong. 4. Re-run the suite to prove the fix. Report what failed, why, and what changed. ## skills/changelog/SKILL.md ```yaml name: changelog description: Draft a concise changelog entry from recent commits, grouped by feature/fix/chore and written for users. Use when the user asks to "draft a changelog", "write release notes", or summarize unreleased changes. ``` ## changelog — draft a changelog entry from recent commits Skill twin of the mdflow flow `flows/changelog.md` (https://walnut-virtue-6d22.here.now/). The flow preloads the git history at prompt-build time; this skill has you fetch it yourself. ## Steps 1. Gather the recent history: ```bash git log --oneline -30 git diff --stat HEAD~10 2>/dev/null || true ``` 2. Draft a concise changelog entry for the unreleased changes. Group by feature/fix/chore. Write for users, not committers — describe what changed for them, not the internals. No commit hashes. ## skills/review/SKILL.md ```yaml name: review description: Review staged git changes for bugs — terse findings with file:line citations. Use when the user says "review my staged changes", "check this diff before I commit", or wants a quick bug pass over what's about to be committed. ``` ## review — review staged changes for bugs Skill twin of the mdflow flow `flows/review.md` (https://walnut-virtue-6d22.here.now/). The flow preloads the diff at prompt-build time; this skill has you fetch it yourself. ## Steps 1. Run `git diff --cached`. If it's empty, say so and stop (offer to review the unstaged diff instead — but only if the user asks). 2. Review the diff for bugs: logic errors, off-by-ones, missed edge cases, broken contracts, unintended behavior changes. Be terse. Cite every finding as `file:line`. Bugs only — no style notes. ## skills/workshop-standup/SKILL.md ```yaml name: workshop-standup description: Pane-aware standup — report what the user is in the middle of from git state, visible terminal panes, and open tickets, then suggest the single next action. Use when the user says "standup", "where was I", "what am I in the middle of", or starts a session cold and wants their working state summarized. ``` ## workshop-standup — pane-aware standup Skill twin of the mdflow flow `flows/workshop-standup.claude.md` (https://walnut-virtue-6d22.here.now/). The flow preloads this context at prompt-build time before the agent starts; this skill has you gather the same context with tool calls, then do the same job. ## Gather context first (run these, tolerate absence) ```bash git status --short --branch git log --oneline -5 2>/dev/null || echo "(no commits yet)" herdr api snapshot 2>/dev/null | head -40 || echo "(herdr not running)" ``` If the user has a ticket CLI (e.g. `linear`), also list their in-progress issues; otherwise skip tickets without comment. ## Your job From the gathered context only: 1. Say what the user is in the middle of (branch, dirty files, visible panes). 2. Flag anything that looks stalled or contradictory. 3. Suggest the single next action, one sentence. Do not start doing the work — this is a standup, not a work session. ## skills/this-or-that/SKILL.md ```yaml name: this-or-that description: Run a this-or-that Elo voting round to decide anything with more than one plausible answer (design, format, copy, API shape, naming). Generates structurally distinct options over a constant subject, stands up a local duel harness the user arrow-keys through, then reads votes.jsonl back as explicit taste rules and a durable RESULTS.md record. Use when the user says "this or that", "spin up options to vote on", "help me decide between", "RLHF my preferences", or asks you to learn their taste instead of describing it. ``` ## this-or-that — RLHF where the user is the reward model The user can't articulate their taste, but they can pick between two things all day. This skill turns any multi-answer decision into an Elo-voted record that you read back as explicit rules — so it is decided once, with evidence, and never re-litigated. Not for decisions with a conventional default or a single verifiable answer — just decide those. Use this when taste is the deciding factor. ## The harness (3 files, get them first) - In John's workshop repo: copy `compare.html` + `server.py` verbatim from `10-this-or-that/kit/`. - Anywhere else: `curl -sO https://gentle-lasso-9d5n.here.now/kit/compare.html` and the same for `server.py` (published copies of the kit; also see that site's write-up). `compare.html` reads `options.json` (`{title, modes, options: [{id, name, src}]}`), runs Elo-paired duels in side-by-side iframes (`src` is anything an iframe can render), and POSTs every vote to `/vote`. `server.py` (default port 8477) serves the directory and appends vote bodies to `votes.jsonl`. Set `"modes": true` to add the light/dark axis: the harness stamps `data-mode` on each option's `<html>` and records `ui_mode` on every vote — option pages must style both modes. ## Running a round 1. **Frame the axis.** Name the ONE thing options vary on. Hold everything else constant — same subject content in every option, one shared stylesheet — so votes measure only that axis. Read any prior RESULTS.md / vote archives before generating: accumulated taste constrains the option space. 2. **Scaffold** `<slug>-lab/`: harness files, `options.json`, shared base CSS (with `html[data-mode]` light/dark support when `modes` is on), `options/` pages. 3. **Generate 9–13 structurally distinct options.** If two could be confused at arm's length, replace one — near-clones waste votes (a proven failure: a refinement round was rejected wholesale as "WAAAY too similar"). Include the incumbent as a control when one exists. Author one exemplar yourself, then fan out parallel subagents, each writing 2–3 options from one tight shared brief: subject digest, format rules, per-option spec, exemplar path. Real content only — no lorem ipsum, no invented names. 4. **QA before handing over:** every file HTTP 200 through `server.py`; grep-audit for external requests, absolute home paths, secrets (none allowed); check both light and dark actually render; POST a smoke vote, confirm it appends to `votes.jsonl`, remove it. 5. **Hand over and get out of the way.** Start the server in the background, give the user the `compare.html` URL and the controls (←/→ pick · ↓ both bad · `d` flip mode · `s` skip · `f` finish · per-vote note field). Tell them: one note outweighs ten votes. Do not hover; wait for "done". 6. **Analyze on "done".** Read `votes.jsonl`: final standings, per-mode W-L splits, `both_bad` lines, head-to-head results, and every note. State the user's taste as explicit, quotable rules with evidence. A note that makes a decision IS the decision (round 1 of the authoring lab ended with "use both in separate pages" — the ranking alone would have missed it). 7. **Bank it.** Archive `votes-round<N>.jsonl`, write `RESULTS.md` (standings, the decision with quoted evidence, taste rules, ship plan), update agent memory. Propose round 2 from the winners — or ship. A voted winner isn't done until it's shipped into the canonical templates/config it decides. ## Vote record schema (what lands in votes.jsonl) Each duel vote: `{mode: "elo", vote, left, right, winner, loser, elo: {id: score}, note, ui_mode?, toggled?, lab, ts}`. Both-bad: `result: "both_bad"` instead of winner/loser. Finish: `{mode: "final", votes, table: [{id, name, elo, games, light?, dark?}]}`. Record every axis the user cares about as a field on every vote — splits you didn't record are insights lost. ## Proven results (evidence this works) - 3 rounds / 130 votes chose the Instrument Panel theme for all 11 workshop sites (`07-variations/template-lab/RESULTS.md`). - 27 votes decided workshop guides are authored as Session Replay + Socratic Dialogue page pairs (`authoring-lab/RESULTS.md`). - In the workshop repo, `flows/this-or-that.md` runs this entire loop as an mdflow flow: `md flows/this-or-that.md --_question "..." --_subject "..."`. ## Whole-workshop task dispatcher ```yaml description: Load the complete Agentic Software Factory workshop (John Lindquist, the recorded snapshot) — every section's machine guide, Session Replay, and Socratic Dialogue, fetched live — then perform the task. _inputs: [_task] ``` You are loaded with the complete "Agentic Software Factory" workshop (John Lindquist, the recorded snapshot): eleven hands-on sections plus the agenda and a references/resources index. Each section appears three ways below: - **Machine guide** (`agent.md`) — the section's brief, its money artifact (prompt / script / config / kit) verbatim, and step-by-step replication instructions written for an agent to execute. - **Session Replay** — how the section was actually built, beat by beat, including wrong turns. - **Socratic Dialogue** — the reasoning and trade-offs behind the section's decisions. Everything is fetched live from the published sites at run time, so this context is always current. When a guide references a downloadable attachment (files under `skills/`, `flows/`, or zsh files at a site root), fetch it from that section's site root; `.md` attachments need `?raw` appended for the raw file (the bare URL serves an HTML viewer). Ground every answer in this material. Prefer the machine guides for replication steps, the replays for "how it really went", and the dialogues for "why this way". ## Task {{ _task }} ## Agenda — machine-readable index of the whole workshop @https://ember-bodhi-scrr.here.now/agent.md?raw ## 00 · How Agentic Work is Evolving @https://hallowed-entry-96xv.here.now/agent.md?raw !`curl -sf https://hallowed-entry-96xv.here.now/replay.html` !`curl -sf https://hallowed-entry-96xv.here.now/dialogue.html` ## 01 · Configuring your environment @https://polite-ravine-6v8g.here.now/agent.md?raw !`curl -sf https://polite-ravine-6v8g.here.now/replay.html` !`curl -sf https://polite-ravine-6v8g.here.now/dialogue.html` ## 02 · Custom zsh functions @https://sacred-ritual-w7as.here.now/agent.md?raw !`curl -sf https://sacred-ritual-w7as.here.now/replay.html` !`curl -sf https://sacred-ritual-w7as.here.now/dialogue.html` ## 03 · Prompting with Images @https://amber-willow-n64j.here.now/agent.md?raw !`curl -sf https://amber-willow-n64j.here.now/replay.html` !`curl -sf https://amber-willow-n64j.here.now/dialogue.html` ## 04 · Prompt Builder @https://shiny-bloom-f8hv.here.now/agent.md?raw !`curl -sf https://shiny-bloom-f8hv.here.now/replay.html` !`curl -sf https://shiny-bloom-f8hv.here.now/dialogue.html` ## 05 · mdflow @https://walnut-virtue-6d22.here.now/agent.md?raw !`curl -sf https://walnut-virtue-6d22.here.now/replay.html` !`curl -sf https://walnut-virtue-6d22.here.now/dialogue.html` ## 06 · Why Pi, Herdr, and Ghostty @https://summit-inlet-kxyf.here.now/agent.md?raw !`curl -sf https://summit-inlet-kxyf.here.now/replay.html` !`curl -sf https://summit-inlet-kxyf.here.now/dialogue.html` ## 07 · Variations (9x image mockups) @https://indigo-kayak-2zw8.here.now/agent.md?raw !`curl -sf https://indigo-kayak-2zw8.here.now/replay.html` !`curl -sf https://indigo-kayak-2zw8.here.now/dialogue.html` ## 10 · This or That — RLHF for Your Taste @https://gentle-lasso-9d5n.here.now/agent.md?raw !`curl -sf https://gentle-lasso-9d5n.here.now/replay.html` !`curl -sf https://gentle-lasso-9d5n.here.now/dialogue.html` ## 08 · Maximum Intelligence and Video @https://shiny-rosette-m6zy.here.now/agent.md?raw !`curl -sf https://shiny-rosette-m6zy.here.now/replay.html` !`curl -sf https://shiny-rosette-m6zy.here.now/dialogue.html` ## 09 · Debugging with Markers @https://mindful-mango-accy.here.now/agent.md?raw !`curl -sf https://mindful-mango-accy.here.now/replay.html` !`curl -sf https://mindful-mango-accy.here.now/dialogue.html` ## References & Resources — tool alternatives @https://dewy-sleet-n5zs.here.now/agent.md?raw Reference ID: factory-flow-recipes Topic: Execution Sources: - [Published mdflow skills](https://walnut-virtue-6d22.here.now/) - [skills/fixit/SKILL.md](https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md) - [flows/this-or-that.md](https://walnut-virtue-6d22.here.now/flows/this-or-that.md) - [flows/workshop-standup.claude.md](https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md) - [skills/pr-description/SKILL.md](https://walnut-virtue-6d22.here.now/skills/pr-description/SKILL.md) - [skills/onboard/SKILL.md](https://walnut-virtue-6d22.here.now/skills/onboard/SKILL.md) - [skills/fix-tests/SKILL.md](https://walnut-virtue-6d22.here.now/skills/fix-tests/SKILL.md) - [skills/changelog/SKILL.md](https://walnut-virtue-6d22.here.now/skills/changelog/SKILL.md) - [skills/review/SKILL.md](https://walnut-virtue-6d22.here.now/skills/review/SKILL.md) - [skills/workshop-standup/SKILL.md](https://walnut-virtue-6d22.here.now/skills/workshop-standup/SKILL.md) - [skills/this-or-that/SKILL.md](https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md) --- # Workspace and session routing: practical reference ## Agent Setup Prompt ```text Set up the local cmux/tmux agent orchestration files and configuration for this software project. Inspect the existing local files first, preserve any working behavior, and create or update only the narrow launcher, hook, and zsh helper pieces needed for reliable routing. Work step by step: 1. Confirm prerequisites and current routing context. - Run `which cmux`, `which tmux`, `which zsh`, `which python3`, and `which node`. - Run `cmux identify` and capture `caller`, `focused`, `workspace_ref`, `pane_ref`, `surface_ref`, `tab_ref`, and `socket_path`. - Run `cmux rpc workspace.current` and capture `workspace.current_directory`, `workspace_id`, and `window_id`. - If the current workspace cwd is not the intended project, use `cmux-focus-or-open-workspace /path/to/project`, then re-run the checks. - Never use `--workspace current` as a workspace handle. Resolve the current workspace first, then use the explicit id or ref. 2. Inspect or create the cmux launcher files. - `~/.config/cmux/cmux.json` - `~/.config/cmux/scripts/cmux-xport.sh` - `~/.local/bin/cmux-run-surface` - `~/.local/bin/cmux-fork-focused-codex` - `~/.local/bin/cmux-focus-or-open-workspace` - `~/.local/bin/cmux-xport` - `~/.local/bin/cmux-xport-markdown` Ensure executable launcher files are executable. Do not overwrite existing scripts blindly; diff or summarize the existing behavior first. 3. Wire workspace, pane, surface, tab, process, and session mapping. - Treat the routing graph as `workspace -> pane -> surface/tab -> process/session -> receipt`. - `cmux-run-surface` must resolve the workspace with `cmux rpc workspace.current`, create a pane with explicit workspace/window/pane refs, inspect surfaces with `cmux rpc pane.surfaces`, send the requested command to the intended surface, and press Enter. - Support right split by default and `--below` for below split. - Confirm commands run from the focused workspace cwd and inherit `CMUX_SURFACE_ID`, `CMUX_WORKSPACE_ID`, `CMUX_TAB_ID`, and `CMUX_SOCKET_PATH`. 4. Set up focused Codex session routing. - `cmux-fork-focused-codex` must prefer `.caller.surface_ref` when present, then fall back to `.focused.surface_ref`. - Normalize short surface refs through `cmux rpc pane.surfaces '{"pane_id":"pane:<id>","workspace_id":"workspace:<id>","window_id":"window:<id>"}'`. - Resolve the Codex session through `python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" --resolve-surface "surface:<stable-surface-id>"`. - Hand off fork mode as `CODEX_FORK_SESSION_ID=<uuid> p-f`. - Hand off compact mode as `CODEX_FORK_SESSION_ID=<uuid> p-c`, with `--below` supported. - Do not use `fork --last` as a substitute for focused surface routing. 5. Inspect or create the Codex hook registry files. - `~/.codex/hooks/cmux-codex-session-registry.py` - `~/.codex/hooks/cmux-auto-name-tab.zsh` - `~/.codex/hooks/codex-thread-name-set.mjs` The registry must map stable cmux surface ids to Codex session UUIDs. Keep screen scraping or `--allow-screen` as fallback only, and report when fallback was required. 6. Set up transcript exports. - `cmux-xport` must resolve the focused workspace cwd, `cd` there, set `CODEX_XPORT_SAVE_CWD=1`, load the zsh helper path that defines `xport`, copy the transcript to the clipboard when available, and save a non-empty markdown file under `.exports/<timestamp>.md`. - `cmux-xport-markdown` should open or surface the saved markdown export without pasting the full transcript into chat. 7. Wire tmux, muxai, and agent_chain. - Inspect `~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh`, `~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh`, and `~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh`. - Confirm `muxai` resolves for terminal-only multi-agent layouts. - Confirm `agent_chain` resolves for gated multi-step software work. - If a helper is a zsh function (`p-f`, `p-c`, `xport`, `xfl`, `xfc`, `muxai`, `agent_chain`), either load it through the intended zsh startup path or provide a small executable wrapper for non-zsh callers. 8. Respect privacy boundaries. - Do not paste full `env` output. - Do not expose API keys, tokens, cookies, provider variables, private endpoints, or credentials from config, hook, shell, or transcript files. - Do not copy private local config verbatim when a structure summary is enough. - Keep transcript exports local under `.exports` unless explicitly asked to share them. - Report session ids and surface ids only when needed to prove routing, and avoid including transcript content in the report. 9. Run verification commands before declaring setup complete. - `cmux identify` - `cmux rpc workspace.current` - `printf 'surface=%s\nworkspace=%s\ntab=%s\nsocket=%s\n' "$CMUX_SURFACE_ID" "$CMUX_WORKSPACE_ID" "$CMUX_TAB_ID" "$CMUX_SOCKET_PATH"` - `cmux-run-surface "pwd; echo surface=$CMUX_SURFACE_ID"` - `cmux-run-surface --below "pwd; echo surface=$CMUX_SURFACE_ID"` - `cmux-fork-focused-codex --dry-run --preflight-fork` - `cmux-fork-focused-codex --dry-run --below --preflight-compact` - `ls -lt .exports | head` - `test -s "$(ls -t .exports/*.md | head -1)" && echo export:OK` - `zsh -ic 'whence -w muxai; funcwhere muxai'` - `zsh -ic 'whence -w agent_chain; funcwhere agent_chain'` - `zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport xfl xfc'` 10. Report results plainly. - List files inspected. - List files created or edited. - List files intentionally left untouched. - For each verification command, report pass/fail and the key output. - If anything is missing, broken, private, or ambiguous, stop and explain the blocker instead of claiming setup is complete. ``` ## Big Idea Phase: Routing And Composition - once context and helper boundaries are clear, route the work to the right workspace, pane, and session. Focused context is a routing problem, not a prompt problem. ## Try This Now From the project workspace, run: `cmux identify`. Then run: `cmux rpc workspace.current`. Do not launch a helper pane until the workspace cwd and focused surface match the project you mean. Once you have the right project context, shell environment, and zsh helpers, the next question is: ```text Which agent is doing what, in which workspace, in which pane, against which session, and what proof can I save? ``` Treat the environment as an addressable graph: ```text workspace -> pane -> surface/tab -> process/session -> receipt ``` A better prompt cannot fix bad routing. First route the action to the correct surface and session. ## Files To Inspect Common local orchestrator files and scripts: ```text ~/.config/cmux/cmux.json ~/.config/cmux/scripts/cmux-xport.sh ~/.local/bin/cmux-run-surface ~/.local/bin/cmux-fork-focused-codex ~/.local/bin/cmux-focus-or-open-workspace ~/.local/bin/cmux-xport ~/.local/bin/cmux-xport-markdown ~/.codex/hooks/cmux-codex-session-registry.py ~/.codex/hooks/cmux-auto-name-tab.zsh ~/.codex/hooks/codex-thread-name-set.mjs ~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh ~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh ~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh ``` ## When To Reach For This Use this workflow when you need to: - open a helper pane next to the current work - fork or compact the Codex conversation in the pane you are looking at - export a Codex transcript into `.exports` - focus or open a project workspace by directory - run a visible multi-agent layout - move from one-off helper commands to gated multi-step orchestration - debug a shortcut that targets the wrong conversation - prove where a command ran and what session it belonged to Focus on practical routing for software project work. Skip tmux and cmux internals that do not affect the current workspace, pane, session, or receipt. ## How This Used To Work What you used to expect: ```text The newest terminal, pane, or agent session is probably the one you meant. ``` What the workflow gives you now: ```text Ask the orchestrator where you are, use stable ids, launch helpers in known panes, and save transcripts when the session becomes part of the work. ``` ## The Mental Model ```text workspace -> pane -> surface/tab -> process/session -> receipt ``` | Layer | What It Means | What To Check | | --- | --- | --- | | `workspace` | project container, usually with a current directory | `cmux rpc workspace.current` | | `pane` | visible split region inside a workspace | `pane_ref`, `cmux rpc pane.create` | | `surface` | addressable terminal/browser/editor target inside a pane | `surface_ref`, `CMUX_SURFACE_ID` | | `tab` | human-facing label for a surface | `tab_ref`, `CMUX_TAB_ID` | | process | running program | `zsh`, `codex`, `tmux`, `xport`, `p-f`, `p-c` | | session | durable agent identity | Codex session UUID | | receipt | proof you can inspect later | `.exports/<timestamp>.md`, registry, logs, reports | Practical language: ```text A pane is where work is visible. A session is what work belongs to. A receipt is what makes work resumable. ``` ## cmux vs tmux `cmux` and `tmux` solve different layers. | Tool | Role | Use It For | | --- | --- | --- | | `cmux` | GUI/socket/workspace orchestrator | workspaces, panes, surfaces, browser/editor panels, focused context, keyboard launchers | | `tmux` | terminal multiplexer layout primitive | terminal-only layouts, persistent sessions, panes/windows, CLI fanout, `muxai` layouts | Practical line: ```text cmux is the building. tmux is one kind of room layout inside the building. ``` ## Address The Current Context Start here: ```bash cmux identify ``` Look for: - `caller`: the surface that invoked the command - `focused`: the surface cmux believes is focused - `workspace_ref`: project/workspace target - `pane_ref`: visible split target - `surface_ref`: addressable surface target - `tab_ref`: human-facing tab target - `socket_path`: socket used by local automation For keyboard launchers, prefer the caller surface when present: ```text .caller.surface_ref // .focused.surface_ref ``` This prevents a shortcut from accidentally targeting a different visible pane. ## Get The Current Workspace Correctly Use: ```bash cmux rpc workspace.current ``` Look for: - `workspace.current_directory` - `workspace_id` - `window_id` Do not assume this works: ```bash cmux top --workspace current --processes --flat --format tsv ``` Observed failure shape: ```text Error: Invalid workspace handle: current (expected UUID, ref like workspace:1, or index) ``` Rule: ```text "Current" is a question, not a workspace handle. Ask cmux for current state, then use the returned explicit ref/id. ``` ## Know The cmux Environment Variables Inside cmux terminal surfaces, scripts can use: ```text CMUX_SURFACE_ID CMUX_WORKSPACE_ID CMUX_TAB_ID CMUX_SOCKET_PATH ``` Quick check: ```bash printf 'surface=%s\nworkspace=%s\ntab=%s\nsocket=%s\n' \ "$CMUX_SURFACE_ID" "$CMUX_WORKSPACE_ID" "$CMUX_TAB_ID" "$CMUX_SOCKET_PATH" ``` If those values are empty, you may not be inside a cmux terminal surface, or the process may not have inherited the cmux environment. ## Create A Helper Pane Shortcut: ```text cmux-run-surface "command" ``` Right split: ```bash cmux-run-surface "pwd; echo surface=$CMUX_SURFACE_ID" ``` Below split: ```bash cmux-run-surface --below "pwd; echo surface=$CMUX_SURFACE_ID" ``` What the launcher does: ```text cmux rpc workspace.current -> cmux rpc pane.create -> cmux rpc pane.surfaces -> cmux send "<command>" -> cmux send-key enter ``` How to know it worked: - a new cmux pane appears - the command text is visible in that pane - Enter was submitted - the command runs from the focused workspace cwd - `CMUX_SURFACE_ID` is set inside the new terminal ## Focus Or Open A Project Workspace Shortcut: ```text cmux-focus-or-open-workspace /path/to/project ``` Use this when the problem starts with a directory or repo, not with a visible pane. What the launcher should do: ```text find existing cmux workspace for the project -> focus it if it exists -> open a new workspace if it does not -> keep later helper panes and forks anchored to that project cwd ``` How to know it worked: ```bash cmux rpc workspace.current ``` Look for the expected project directory in `workspace.current_directory` before launching helper panes or agent chains. ## Fork The Focused Codex Session Shortcut: ```text Esc+P ``` Actual route: ```text Esc+P -> cmux-fork-focused-codex --preflight-fork -> cmux identify -> caller/focused surface -> cmux rpc pane.surfaces -> stable surface id -> cmux-codex-session-registry.py --resolve-surface -> Codex session id -> CODEX_FORK_SESSION_ID=<session-id> p-f -> cmux-run-surface -> new pane ``` Dry-run first: ```bash cmux-fork-focused-codex --dry-run --preflight-fork ``` Compact fork below: ```bash cmux-fork-focused-codex --dry-run --below --preflight-compact ``` Shortcut mapping: | Shortcut | Route | | --- | --- | | `Esc+P` | focused Codex session -> `p-f` | | `Esc+Shift+P` | focused Codex session -> compact -> `p-c` below | | `Esc+E` | export focused workspace transcript with `cmux-xport` | | `Esc+M` | export transcript and open markdown | Why this matters: ```text fork --last is not the same as fork the conversation in the focused pane. ``` ## Stable Surface IDs And The Registry Short refs such as `surface:38` are useful in current output, but they are not the durable routing key. Focused fork should normalize the short surface ref through: ```bash cmux rpc pane.surfaces '{"pane_id":"pane:<id>","workspace_id":"workspace:<id>","window_id":"window:<id>"}' ``` Then resolve the Codex session through: ```bash python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" \ --resolve-surface "surface:<stable-surface-id>" ``` Screen fallback exists, but should be fallback only: ```bash python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" \ --resolve-surface "surface:<id>" --allow-screen ``` ## Export A Transcript Shortcut: ```text Esc+E ``` Command: ```bash cmux-xport ``` Route: ```text cmux-xport -> cmux rpc workspace.current -> cd focused workspace cwd -> CODEX_XPORT_SAVE_CWD=1 -> source ~/.config/zsh/conf.d/40-ai.zsh -> xport -> clipboard -> .exports/<timestamp>.md -> notification ``` How to know it worked: ```bash ls -lt .exports | head test -s "$(ls -t .exports/*.md | head -1)" && echo export:OK ``` Practical line: ```text Clipboard is convenience. .exports is the durable receipt. ``` ## How Helpers Connect To Routing First identify whether the helper is a zsh function, alias, executable, or environment variable. Then route it to the workspace, pane, surface, or session where it should run. Common bridge helpers: | Helper | What It Does Here | | --- | --- | | `xfl` | find the Codex session or thread you intend to work with | | `xfc` | continue or fork from the chosen Codex context | | `xport` | export a Codex conversation from the current project cwd | | `p-f` | launch a forked Codex path after the target session is known | | `p-c` | launch a compacted Codex path after the target session is known | If the command is a zsh function, either run it through the zsh startup path that loads it or use the executable wrapper that the orchestrator expects. ## tmux Layouts And Agent Chains Validate `muxai`: ```zsh zsh -ic 'whence -w muxai; funcwhere muxai' ``` Use `muxai` when you want a terminal-only multi-agent room inside a surface. Validate `agent_chain`: ```zsh zsh -ic 'whence -w agent_chain; funcwhere agent_chain' ``` Use it for software work where you want phase separation: ```zsh agent_chain "Explore the billing webhook duplicate-processing bug, plan the smallest safe patch, then implement only if tests can verify it." ``` Good uses: - refactor with a real review gate - bug investigation before edit - small feature with a plan checkpoint - risky implementation that needs a danger confirmation Bad use: ```text agent_chain "fix everything" ``` ## Ask The Agent This Route a helper pane: ```text Use the cmux orchestrator source files. Open a helper pane for this software project. It should run from the focused workspace cwd and inspect the checkout flow failure without editing files. Use cmux routing, not manual terminal instructions. Tell me how to confirm the pane was created and where to check logs if it fails. ``` Debug a wrong focused fork: ```text Esc+P forked the wrong Codex conversation. Inspect the focused-fork route: `cmux identify`, caller versus focused surface, `cmux rpc pane.surfaces`, stable surface lookup, the Codex cmux registry, `CODEX_FORK_SESSION_ID`, and the `p-f` handoff. Do not assume `fork --last` is correct. Give me the dry-run command that proves the target session id before launching. ``` Export a conversation: ```text Export the focused Codex conversation for this project. Use `cmux-xport` or the equivalent `CODEX_XPORT_SAVE_CWD=1` zsh path. Confirm the export was copied to the clipboard and saved under `.exports`. Do not paste the whole transcript back into chat. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | Identify current context | `cmux identify` shows caller/focused workspace, pane, surface, tab | | Get current workspace | `cmux rpc workspace.current` shows cwd, workspace id, window id | | Avoid fake current handle | no command depends on `--workspace current` | | Create helper pane | `cmux-run-surface "echo ok"` opens a pane and runs from intended cwd | | Route focused fork | dry-run prints `CODEX_FORK_SESSION_ID=<uuid> p-f` or `p-c` | | Export transcript | `.exports/<timestamp>.md` exists and is non-empty | | tmux layout present | `tmux ls` and `tmux list-panes -a` show expected panes | | agent chain scoped | goal names a specific software bug or feature and verification command | ## If It Goes Wrong ### Invalid Workspace Handle Bad: ```bash cmux top --workspace current --processes --flat --format tsv ``` Correct: ```bash cmux identify cmux rpc workspace.current cmux rpc workspace.list ``` ### Wrong Session Fork Dry-run: ```bash cmux-fork-focused-codex --dry-run --preflight-fork ``` Correct route: ```text focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID ``` ### Missing `.exports` Check: ```bash ls -lt .exports | head ``` Direct save shape: ```zsh CODEX_XPORT_SAVE_CWD=1 zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; xport' ``` ### Function Not Found Check: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport' ``` Some orchestration commands are zsh functions. Launch them through zsh or provide executable wrappers. ## References And Resources - Common cmux config: `~/.config/cmux/cmux.json` - Common pane launcher: `~/.local/bin/cmux-run-surface` - Common focused fork launcher: `~/.local/bin/cmux-fork-focused-codex` - Common xport launcher: `~/.local/bin/cmux-xport` - Common registry hook: `~/.codex/hooks/cmux-codex-session-registry.py` - Common tmux helper source: `~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh` - Common agent chain source: `~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh` - tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html - tmux GitHub wiki: https://github.com/tmux/tmux/wiki - OpenAI Codex: https://openai.com/codex/ - Model Context Protocol: https://modelcontextprotocol.io/ - Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-workspace-routing-reference Topic: Execution Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Workspace and session routing: practice drills These exercises practice routing work through the agentic dev environment. The goal is to prove: ```text workspace -> pane -> surface/tab -> process/session -> receipt ``` Use a real software project directory when possible. Prefer dry-runs before launching anything. ## Exercise 1: Address The Current Work Run: ```bash cmux identify cmux rpc workspace.current ``` Fill out: ```markdown # cmux Address Notes - workspace_ref: - workspace_id: - workspace cwd: - window_id: - pane_ref: - surface_ref: - tab_ref: - surface_type: - caller/focused same? yes/no - command that should target this surface: ``` ## Exercise 2: Prove The `current` Handle Failure Run: ```bash cmux top --workspace current --processes --flat --format tsv ``` Then run: ```bash cmux rpc workspace.current ``` Fill out: ```markdown # Workspace Handle Notes - failed command: - exact error: - correct command: - returned workspace id/ref: - returned cwd: - lesson: ``` Expected lesson: ```text `current` is not a workspace handle. Ask cmux for current state, then use explicit refs or ids. ``` ## Exercise 3: Focus Or Open A Workspace Choose a software project directory and run: ```bash cmux-focus-or-open-workspace /path/to/project cmux rpc workspace.current ``` Fill out: ```markdown # Workspace Focus Notes - project path: - did cmux focus an existing workspace or open a new one: - workspace cwd: - workspace id/ref: - next command that should run from this cwd: ``` ## Exercise 4: Capture The cmux Environment Inside a cmux terminal, run: ```bash printf 'surface=%s\nworkspace=%s\ntab=%s\nsocket=%s\n' \ "$CMUX_SURFACE_ID" "$CMUX_WORKSPACE_ID" "$CMUX_TAB_ID" "$CMUX_SOCKET_PATH" ``` Fill out: ```markdown # cmux Env Notes - CMUX_SURFACE_ID: - CMUX_WORKSPACE_ID: - CMUX_TAB_ID: - CMUX_SOCKET_PATH: - which value identifies the smallest routing target: - which value would a registry hook need: - which value helps external automation talk to cmux: ``` ## Exercise 5: Open A Safe Helper Pane Run: ```bash cmux-run-surface 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK' ``` Optional below split: ```bash cmux-run-surface --below 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK' ``` Fill out: ```markdown # Helper Pane Notes - command: - right or below: - did a new pane open? yes/no - cwd printed: - surface id printed: - did the command submit automatically? yes/no - if failed, log checked: ``` ## Exercise 6: Dry-Run A Focused Codex Fork Focus a cmux pane that has a Codex conversation. Run: ```bash cmux-fork-focused-codex --dry-run --preflight-fork ``` Then run: ```bash cmux-fork-focused-codex --dry-run --below --preflight-compact ``` Fill out: ```markdown # Focused Fork Notes - fork command output: - compact command output: - includes CODEX_FORK_SESSION_ID? yes/no - launches `p-f` or `p-c`? - target session id: - why this is safer than `fork --last`: ``` ## Exercise 7: Export A Transcript Run: ```bash cmux-xport ls -lt .exports | head ``` Then verify latest export is non-empty: ```bash latest="$(ls -t .exports/*.md 2>/dev/null | head -1)" test -n "$latest" && test -s "$latest" && echo "export:OK $latest" || echo "export:MISSING" ``` Fill out: ```markdown # xport Notes - command: - workspace cwd: - latest export file: - file exists? yes/no - file non-empty? yes/no - what this export can prove later: ``` ## Exercise 8: Decide Whether It Is cmux Or tmux For each failure, choose `cmux`, `tmux`, `zsh`, or `Codex registry`. | Failure | Layer | | --- | --- | | `cmux identify` cannot connect to socket | | | `cmux-run-surface` cannot create a pane | | | `muxai` creates a weird tiled layout | | | `p-f: command not found` | | | `Esc+P` targets the wrong Codex UUID | | | `.exports` is missing after xport | | | `tmux ls` shows no expected session | | | `CMUX_SURFACE_ID` is empty inside a hook | | Useful commands: ```bash cmux identify cmux rpc workspace.current tmux ls tmux list-panes -a zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport' python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" --registry-path ``` ## Exercise 9: Design A Gated `agent_chain` Goal Bad: ```text fix everything ``` Better template: ```text Explore <specific bug or feature>, plan the smallest safe patch, then implement only if <verification command> can prove it. ``` Write your goal: ```markdown # agent_chain Goal agent_chain "<goal>" ``` Fill out expected reports: ```markdown # Expected Phase Receipts ## Explore - files inspected: - hypothesis: - risks: ## Plan - smallest patch: - tests: - rollback: ## Implement - files changed: - verification command: - result: ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-workspace-routing-practice Topic: Execution Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # 5 Monkeys QA swarm playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already trust tests for known requirements, but fast-moving UI work also needs cheap exploratory passes that click through real app state. This technique gives local agents a practical browser-facing QA job: find weird UX and state bugs before users do. [Core principles](/topics/foundations-perspective-qa-and-testing/) ## Copy-paste workflow **When to use:** When you want to surface state bugs and UX dead ends a happy-path check would miss. This launches many cheap agents that click around in weird, non-obvious ways from assigned perspectives, recording findings to discardable QA files. ### Copy-paste prompt ```text Run a "5 Monkeys" QA swarm on <APP/FEATURE>. The point is to find state bugs and UX dead ends the happy path would never reveal — so do NOT just walk the happy path. 1. Assign yourself (or each worker agent) a PERSPECTIVE lens and stay in character: expert power user / brand-new first-time user / a grandparent / impatient power user. 2. Explore WEIRD, non-obvious paths explicitly: - keyboard shortcut sequences - back/forward navigation mid-flow - repeated/rapid clicks on the same control - toggling modes back and forth - partial or abandoned flows (start, then bail) Try to break state, not to succeed. 3. Write findings to a DISCARDABLE numbered QA markdown file (e.g. .notes/qa-01.md). These are cheap — regenerate freely. 4. After the runs, collate the findings and keep ONLY the useful ones. Guardrails: keep rigorous tests for stable business logic — don't over-test UI you still expect to reshape daily. If you use a browser agent, script the auth/login path explicitly: cookies are NOT shared. ``` ### How it works - Each agent gets a perspective lens (expert, brand-new user, grandparent, power user) and explores the app in character. - Agents deliberately explore weird paths — shortcut sequences, back navigation, repeated clicks, mode toggles, partial/abandoned flows — instead of the happy path, which is where state bugs hide. - Findings go to discardable numbered QA markdown files (cheap, regenerate freely); collate afterward and keep only the useful ones. - Keep rigorous automated tests for stable business logic; don't over-test UI you still expect to reshape daily. - If using a browser agent, script the auth/login path explicitly — cookies are not shared between agents. - Reference: [Agent Browser](https://github.com/vercel-labs/agent-browser). ## Reusable skill Install as `~/.agents/skills/five-monkeys-qa/SKILL.md`, then restart Codex. ```markdown --- name: five-monkeys-qa description: Trigger when you want to surface state bugs and UX dead ends a happy-path check would miss — launch perspective-based agents that explore weird, non-obvious paths and write findings to discardable QA files. Do NOT use to replace rigorous tests for stable business logic. --- # 5 Monkeys QA Launch cheap perspective-based agents that explore the app in weird, non-obvious ways to surface state bugs and UX dead ends the happy path would never reveal. Findings go to discardable QA files. ## Steps 1. Assign each agent a PERSPECTIVE lens and have it stay in character: - expert power user - brand-new first-time user - a grandparent - impatient power user 2. Explore WEIRD, non-obvious paths explicitly (not the happy path): - keyboard shortcut sequences - back/forward navigation mid-flow - repeated / rapid clicks on the same control - toggling modes back and forth - partial or abandoned flows (start, then bail) 3. Each agent writes findings to a DISCARDABLE numbered QA markdown file (e.g. `.notes/qa-01.md`). They are cheap — regenerate freely. 4. Collate the findings and keep ONLY the useful ones. ## Guardrails - Keep rigorous automated tests for STABLE business logic — this does not replace them, and don't over-test UI you still expect to reshape daily. - If using a browser agent, script the auth/login path explicitly — cookies are NOT shared. ``` ## Scenarios ### Authenticated dashboard weird-path pass **Role:** As a frontend engineer shipping an authenticated Next.js dashboard A Next.js app has a local dev server, a login flow, route-level navigation, filter panels, modal dialogs, and a dashboard state that often changes during product iteration. > As a frontend engineer, I want several perspective-driven agents to explore non-happy-path dashboard behavior, so that I can catch stuck state, broken back navigation, and confusing UI before merging. #### Agent brief ```text Run a 5 Monkeys QA swarm against the authenticated dashboard. First inspect the repo for the dev command and any documented test user or seeded auth flow. Start the app locally using the repo’s normal command, such as npm run dev, pnpm dev, or the command documented in package.json/README. Create .notes/qa-dashboard-swarm.md as a discardable numbered QA file. Assign five lenses: expert power user, brand-new first-time user, grandparent/inexperienced user, impatient power user, and distracted returning user. For each lens, use a browser workflow against localhost and deliberately avoid only confirming the happy path. Try: login, navigate to the dashboard, open filters, toggle modes, click the same controls repeatedly, use browser back/forward mid-flow, abandon a modal halfway through, refresh after changing state, and return to the page. Record each finding with: perspective, exact path, expected behavior, observed behavior, severity, and whether it looks like stable business logic or fast-changing UI. Expected output: .notes/qa-dashboard-swarm.md plus a short final summary of the 3-7 useful findings only. ``` #### Implementation references [Open reference](/topics/foundations-five-monkeys-playbook/) [Open reference](/topics/foundations-five-monkeys-playbook/) [Open reference](/topics/foundations-perspective-qa-and-testing/) ```text package.json ``` ```text README.md ``` ```text cmux --json tree ``` ```text cmux read-screen ``` ```text cmux markdown open .notes/qa-dashboard-swarm.md --direction right ``` #### Browser verification Use an agent-browser-style pass or CMUX browser pane against the local URL. Take an accessibility snapshot after login, click through navigation and controls, fill the login form using explicit test credentials or signup instructions from the repo, use back/forward after reaching nested dashboard states, then evaluate whether visible state, URL, and focused controls still agree. #### Definition of done - A discardable .notes/qa-dashboard-swarm.md file exists with numbered findings grouped by perspective. - The browser proof includes local URL, login path used, at least one snapshot or screenshot reference, and notes on back/forward, repeated-click, and toggle behavior. - The final triage separates useful findings from noise and marks which issues deserve durable tests because they touch stable business logic. #### Failure modes and mitigations - The agent only walks the happy path; mitigate by requiring each perspective to perform at least three weird-path moves before writing conclusions. - The agent assumes existing browser cookies; mitigate by scripting login/signup explicitly and recording the auth path used. ### Checkout flow state-bug hunt before release **Role:** As a full-stack web developer preparing a checkout or billing flow for release A local ecommerce or SaaS checkout flow has plan selection, quantity changes, discount code entry, payment-step navigation, validation messages, and browser history interactions. > As a full-stack developer, I want agents to attack the checkout flow from different user perspectives, so that I can find state mismatches and UX dead ends without overbuilding brittle tests for UI that may still change. #### Agent brief ```text Run the 5 Monkeys technique on the checkout/billing flow. Treat stable pricing, totals, validation rules, and submitted payloads as serious business logic; treat copy, spacing, and visual layout notes as flexible UI findings unless they block the user. Create .notes/qa-checkout-five-monkeys.md. Start the local app and document the exact command. Assign lenses: expert buyer, brand-new customer, grandparent/inexperienced user, impatient power user, and skeptical returning customer. In the browser, test non-obvious paths: change plan then press back, enter then remove a coupon, rapidly change quantity, start checkout then abandon before payment, refresh on a later step, use keyboard navigation where controls are visible, and retry after validation errors. Capture console errors, visible state, URL, and any mismatch between displayed total and expected total. Expected output: a discardable QA file, a concise release-risk summary, and recommendations for which findings should become durable automated tests. ``` #### Implementation references [Open reference](/topics/foundations-five-monkeys-playbook/) [Open reference](/topics/foundations-five-monkeys-playbook/) [Open reference](/topics/foundations-perspective-qa-and-testing/) [Open reference](/topics/foundations-five-monkeys-playbook/) ```text package.json ``` ```text playwright.config.* if present ``` ```text .notes/qa-checkout-five-monkeys.md ``` #### Browser verification Use Playwright, a CMUX browser pane, or an agent-browser-style snapshot/click/fill/evaluate loop. Fill checkout inputs, click plan and coupon controls, use browser back/forward between checkout steps, refresh after a partial flow, and evaluate the DOM text for totals, validation messages, and disabled/enabled button state. #### Definition of done - A .notes/qa-checkout-five-monkeys.md file lists exact reproduction paths for each useful checkout finding. - Browser evidence includes the local URL, console-log notes, visible totals or validation text, and the action sequence that triggered each issue. - The final review identifies which findings should become durable tests because they protect stable business logic. #### Failure modes and mitigations - The agent treats all UI observations as test-suite requirements; mitigate by explicitly classifying stable business logic separately from fast-changing UI. - The agent reports vague concerns without reproduction steps; mitigate by requiring every useful finding to include exact clicks, form inputs, URL/history moves, and observed result. ### Stress-test a pricing-plan upgrade flow **Role:** As a growth engineer owning a SaaS pricing page and upgrade checkout A pricing page has monthly/yearly toggles, plan comparison cards, a coupon field, and an upgrade checkout modal. Happy-path tests pass, but users keep finding weird state bugs after toggling billing periods, backing out of checkout, and switching plans. > As a trial user comparing plans, I want billing toggles, coupon validation, selected plan state, and checkout recovery to stay consistent, so that I can upgrade without losing trust in the pricing flow. #### Agent brief ```text Run a 5 Monkeys QA pass against the local pricing and upgrade flow. Assign five perspectives: brand-new trial user, impatient mobile user, keyboard-only user, existing customer changing plans, and skeptical QA engineer. Each perspective should explore weird paths: toggle monthly/yearly repeatedly, apply invalid and valid coupons, switch plans after opening checkout, use back/forward, refresh mid-flow, and try keyboard navigation. Each worker writes one discardable QA file under `.notes/qa/pricing-<perspective>.md` with steps, expected result, observed result, screenshot or browser transcript path, severity, and whether the issue is reproducible. Collate findings into `.notes/qa/pricing-summary.md` and recommend only the highest-value fixes. ``` #### Implementation references [Open reference](/topics/foundations-five-monkeys-playbook/) [Open reference](/topics/foundations-five-monkeys-playbook/) ```text package.json scripts ``` ```text local pricing route and checkout/modal source files ``` ```text cmux browser snapshot/click/fill/evaluate commands or existing Playwright tests ``` #### Browser verification Use a CMUX browser pane, Playwright if already present, or an agent-browser-style snapshot/click/fill/evaluate loop. Open the local pricing route, snapshot plan names and billing toggle state, click monthly/yearly, open checkout for each plan, fill coupon codes, use back/forward and refresh, and capture visible selected-plan text plus console errors after each odd path. #### Definition of done - Five perspective-specific QA markdown files exist under `.notes/qa/`. - The summary separates reproducible product bugs from preference notes and one-off observations. - At least one browser receipt exists per high-severity finding: screenshot, accessibility snapshot, console output, or Playwright trace. - Recommended fixes are ranked by user impact and implementation risk, not by which worker found them first. #### Failure modes and mitigations - The workers all follow the same happy path; mitigate by assigning explicit perspectives and weird-path instructions before they start. - The agent turns observations into permanent tests too early; mitigate by keeping findings discardable until the team decides which behavior should become stable. - The QA pass uses real payment/customer data; mitigate with local fixtures, test cards, or mocked checkout state only. ## Implementation notes - Keep the QA files explicitly discardable under .notes/ so agents can regenerate them as the UI changes. - For browser verification, tell the agent the login or signup path; do not assume cookies, private session state, or authenticated browser context. - The useful receipt is not a large pile of findings. It is a short triage of reproducible weird-path issues, with noisy observations removed. - Keep rigorous automated tests for stable business logic such as checkout totals, permissions, data persistence, and validation rules. - Use CMUX browser panes, agent-browser-style snapshots/click/fill/evaluate, or Playwright when live UI behavior matters more than source inspection. - Grounded in the uploaded scenario bundle. :contentReference[oaicite:0]{index=0} ## Boundaries and caveats - Do not turn discardable QA files into a permanent Storybook-style or full integration-test framework. - Do not introduce tools that were only mentioned but not taught as the technique for this workflow. - Do not assume browser agents inherit the developer's cookies or private authenticated state. - Do not use worktrees by default for this playbook; keep the scenario focused on the single selected toolkit technique. - Do not claim the swarm replaces stable business-logic tests. ## Agent reference map ### Existing 5 Monkeys prompt Use it as the canonical copy-paste behavior contract for perspective lenses, weird-path exploration, discardable QA files, and browser-auth guardrails. [Open reference](/topics/foundations-five-monkeys-playbook/) ### Existing five-monkeys Codex skill Use it to keep the agent behavior aligned with the toolkit technique instead of inventing a new QA framework. [Open reference](/topics/foundations-five-monkeys-playbook/) ### Validated lesson 05 references Treat this as ground truth for taught concepts: perspective prompting, discardable QA files, 5 Monkeys exploration, CMUX state, browser-driving tools, and video-driven intent extraction. [Open reference](/topics/foundations-perspective-qa-and-testing/) ### Lesson 05 validation notes Use it to avoid reintroducing details removed during validation, especially anything only mentioned in chat or not taught as a workflow. [Open reference](/topics/foundations-perspective-qa-and-testing/) ### CMUX state and pane commands Use these commands when the agent needs to inspect the active workspace, read terminal output, or open a live Markdown QA tracker. ```text cmux --json tree; cmux read-screen; cmux markdown open .notes/qa-dashboard-swarm.md --direction right ``` Reference ID: foundations-five-monkeys-playbook Topic: Verification Sources: - [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html) --- # A trustworthy software factory loop — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Git Hook Vision Verifiers Using pre-commit or commit hooks to run custom AI agents that evaluate if a code change aligns with the structural or architectural vision of a project. ### Open Weights Task Optimization Leveraging highly intelligent yet low-cost open-weights models (like K3) to train or fine-tune small, specific developer automation utilities. ### AI Coding Agent Context Docs Structuring documents like VISION.md, CLAUDE.md, or AGENTS.md specifically to guide automated AI coding tools across development sessions rather than solely onboarding humans. ### Distributed Agent Architecture Structuring automations into small, specialized agents or scripted steps rather than relying entirely on a single large general model. ### Token Efficiency & Cost-Speed Trade-offs Balancing response latency and token costs against task completion rates when designing long-running agent loops. ### Model Routing & Downgrading Automated switching between different model tiers during execution, which can degrade output quality if small models are chosen inappropriately. ### Personal Agentic Brain A custom local agent architecture combining a private GitHub repository for persistent memory storage with interactive Telegram messages for human-in-the-loop task notifications. ### Scheduled Agents Noise Factor The tendency for passive, scheduled cron-like agent notifications to degrade into ambient attention noise, making manual execution preferable for deep curation workflows. ### Context Window Isolation Utilizing isolated sub-agents or flow frameworks to limit token overhead by dividing large development tasks into distinct, bounded operational sessions. ### AI-Agent Context Documentation Authoring structural metadata and orientation files (such as VISION.md or CLAUDE.md) optimized for programmatic ingestion by code assistants rather than humans. ## Questions and answer status ### Would you argue for more use of git hooks than more and more documentation? **Status: answered.** John argues that while running agent evals on every git hook is currently too expensive for individuals, the upcoming release of open-weights models like K3 will make it very cheap. This allows teams to build custom vision verifier agents on commit hooks, making automated vision alignment practical and powerful within weeks. ### screenpipe has a cool architecture, spins up agents quickly, do you see this trend in the future, claude tag, etc, each having their own channel or a distributed knolwege graph where agents are shared and dynamic, self learning based on channel/task **Status: deferred.** The question is received in chat and the presenter just begins reading it as the shard ends; the full response is deferred to the subsequent shard. ### ScreenPipe has a cool architecture, spins up agents quickly. Do you see this trend in the future? Claude Tag, each having their own channel or distributed knowledge graph. **Status: answered.** John agrees that distributed agents doing small targeted tasks and scripted steps are necessary for speed and cost efficiency, though general models remain valuable when budget permits. He cautions against unreliable automatic model routing based on past experiences with GPT-5.1 and Opus 4.8 downgrades. ### they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule? **Status: answered.** John describes his personal agentic 'Brain' running on a Mac Mini via GitHub and Telegram, but details that he avoids putting general curation or code review loops on a schedule because they become noise. ### To slash token costs for everyday coding, how are you stripping down the source code files before feeding them to Claude Code? **Status: answered.** John states that he does not manually trim down files anymore, citing major improvements in LLM native context window management. Instead, he orchestrates multi-agent flows or redirects intermediate subtasks to lower-cost endpoints like Grok, Cursor Composer, or K3. ## Exercises ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [05:40:36](https://proud-anchor-53zn.here.now/watch.html?t=20436#recording-player) — The screen shows the Claude Code v2.1.212 interface inside the ~/dev/mdflow workspace executing shell commands to search for VISION.md files. - [05:41:03](https://proud-anchor-53zn.here.now/watch.html?t=20463#recording-player) — a participant submits a question in the workshop chat window: 'Would you argue for more use of git hooks than more and more documentation?' - [05:41:38](https://proud-anchor-53zn.here.now/watch.html?t=20498#recording-player) — The Claude Code terminal output updates to show it is reading 20 files from a temporary scratchpad directory to inspect VISION.md content. - [05:41:47](https://proud-anchor-53zn.here.now/watch.html?t=20507#recording-player) — John states that running full agent loops on every git hook can be prohibitively expensive for individual developers at the moment. - [05:41:57](https://proud-anchor-53zn.here.now/watch.html?t=20517#recording-player) — John notes that the K3 model has come out, offering low cost while maintaining high intelligence levels. - [05:42:15](https://proud-anchor-53zn.here.now/watch.html?t=20535#recording-player) — Claude Code prints out the completed markdown analysis summarizing 20 repository files categorized into architectural and agent patterns. - [05:43:32](https://proud-anchor-53zn.here.now/watch.html?t=20612#recording-player) — John emphasizes that utilizing an open-weights K3 model as a custom review-step verifier is only weeks away. - [05:43:42](https://proud-anchor-53zn.here.now/watch.html?t=20622#recording-player) — John addresses student question regarding ScreenPipe agent architecture and distributed knowledge graphs. - [05:44:05](https://proud-anchor-53zn.here.now/watch.html?t=20645#recording-player) — John discusses cost and speed trade-offs in setting up agent automations. - [05:44:34](https://proud-anchor-53zn.here.now/watch.html?t=20674#recording-player) — John highlights token efficiency and benchmark performance of the Fable model. - [05:45:28](https://proud-anchor-53zn.here.now/watch.html?t=20728#recording-player) — John recommends distributed agents for smaller scopes of work combined with scripted steps to optimize speed and cost. - [05:46:07](https://proud-anchor-53zn.here.now/watch.html?t=20767#recording-player) — John shares negative experiences with dynamic model routing in GPT-5.1 and unwanted downgrades from Fable to Opus 4.8. - [05:46:53](https://proud-anchor-53zn.here.now/watch.html?t=20813#recording-player) — John predicts that future smart models will delegate better and demo models will get more intelligent. - [05:47:09](https://proud-anchor-53zn.here.now/watch.html?t=20829#recording-player) — a participant asks in chat: 'they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule?' - [05:47:16](https://proud-anchor-53zn.here.now/watch.html?t=20836#recording-player) — John explains that he has a custom agent called 'Brain' running on a Mac Mini that keeps memory in a private GitHub repository and sends him task check-ins via Telegram. - [05:48:07](https://proud-anchor-53zn.here.now/watch.html?t=20887#recording-player) — John discusses building desktop applications such as Script Kit and a custom Google Messages client replacement. - [05:48:38](https://proud-anchor-53zn.here.now/watch.html?t=20918#recording-player) — John states that scheduled notifications for code reviews, news, and social media turn into ignored noise for him, so he executes them manually. - [05:50:04](https://proud-anchor-53zn.here.now/watch.html?t=21004#recording-player) — John Lindquist comments on attention management and managing multiple active models. - [05:50:27](https://proud-anchor-53zn.here.now/watch.html?t=21027#recording-player) — a participant submits a chat question regarding how to strip down source code files to minimize token costs in Claude Code. - [05:50:37](https://proud-anchor-53zn.here.now/watch.html?t=21037#recording-player) — John explains that he typically avoids stripping source code files now due to upgraded context handling in newer models. - [05:50:52](https://proud-anchor-53zn.here.now/watch.html?t=21052#recording-player) — John discusses flow and sub-agent architectures that segment tasks into individual context windows to prevent usage spikes. - [05:51:15](https://proud-anchor-53zn.here.now/watch.html?t=21075#recording-player) — John discusses configuring Claude Code to delegate tasks to more affordable models or platforms like Cursor Composer. - [05:51:34](https://proud-anchor-53zn.here.now/watch.html?t=21094#recording-player) — John mentions Grok as a highly affordable $20 monthly option, noting historical codebase ingestion policies. - [05:51:59](https://proud-anchor-53zn.here.now/watch.html?t=21119#recording-player) — John references the K3 model release from the previous day, comparing its cost-efficiency to Fable and Soul. ### Unresolved: The precise repository paths fetched by the gh cli tool. The terminal window displays temporary paths and fast-scrolling logs which are partially occluded or truncated. **Discriminating evidence:** Inspect the raw workspace command execution logs or check the scratchpad directory state directly. ### Unresolved: The active editor application is definitively Cursor. The window chrome headers are omitted from the display bounds, preventing direct confirmation of branding. **Discriminating evidence:** Verify with baseline environmental context from prior session modules. ### Demonstration detail: 05:40:36 - Claude Code agent runs automated gh cli search commands for VISION.md files. - Claude Code prints out a categorized markdown summary analysis directly onto the terminal pane. **Tools observed:** Claude Code v2.1.212, GitHub CLI. ### Demonstration detail: 05:43:42 - Editor screen remains open on Claude workspace notes while presenter discusses architectural strategy. **Tools observed:** VS Code / Cursor, Claude. ### Demonstration detail: 05:46:53 - The screen presents a static reference view of a markdown text document outlining AI agent prompt documentation parameters alongside an active workspace prompt configuration panel. **Tools observed:** Cursor IDE. ### Demonstration detail: 05:50:04 - A static document overview layout is shown containing summary evaluations of project context schemas for tools like Claude, typescriptter, and ruby2js. **Tools observed:** Claude, VS Code. Reference ID: factory-factory-loop-discussion Topic: Verification Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Advanced consult, image, and video contracts Transferable contracts from the published Oracle resource family: premise coverage, bounded escalation, attachment proof, multimodal continuity, and honest completion. ## Keep the original premise stronger than the latest plan The execution-oriented consult pattern preserves the original request and derives measurable outcomes, constraints, and falsifiable completion checks. Every premise clause maps to a plan step. Exhausting a plan that omitted part of the request is not completion. This is distinct from a simple independent second opinion. The execution pattern labels a step **execute** when local evidence and the existing plan suffice, and **think** when a genuine architectural choice, unresolved ambiguity, or difficult diagnosis requires frontier reasoning. Size or tedium alone does not justify another consult. Batch independent adjacent think decisions. The intended ratio is few think steps, not a consult for every implementation step. The named consultation points are planning, think decisions, escalation after two distinct failed verification attempts, and a final whole-premise audit. Every consultation asks for the maximum actionable batch: exact file/function/test targets, alternatives, tradeoffs, intended commit boundaries, and enough detail for substantial local execution—not merely “what next?” Execution is implement → falsifiable verification → scoped commit → advance. Preserve unrelated dirty work. Mechanical, evidence-backed plan corrections can be local; new decisions become explicit think steps. An escalation includes the actual failing commands, outputs, receipts, and attempted diff. A step that still fails after its escalation is a genuine block rather than permission to consult indefinitely. The final independent audit compares the actual result with the original premise. PASS requires final local proof against the same state. FAIL returns the complete remediation set, not just the first gap. Out-of-scope nice-to-haves do not silently expand the task. Missing authorization for credentials, destructive action, or broader scope is a stop boundary. ## Rich context and compact evidence are alternatives, not dogmas The Packx reference favors rich code context for broad architecture work, with a roughly 900k-token target in the demonstrated browser-consult setup. The boundary audit favors the smallest useful evidence packet. These answer different problems: a whole-system decision may need the complete relevant source, while a local decision should not carry an entire stale conversation. When raw material is too large or unsafe, supply compact evidence explicitly: prior-state decisions, trustworthy receipts, failure observations, intentionally omitted sources, and a goal-coverage map. Do not replace raw evidence with an unlabelled confident summary. Avoid bundling credentials or private instructions simply because a large attachment is technically supported. ## Video analysis: attachment proof before expensive extraction Use the attached-video path itself as the readiness test. A signed-in browser UI is required, but a text-only cookie error does not prove that the video upload path is broken. Conversely, a text response is not evidence that a model watched a video. A cheap probe asks the model to identify a concrete visible or audible event and end with an exact sentinel. Save the complete response and verify the sentinel before running long analyses. Use short clips directly when that is sufficient. For long recordings, preserve source-native segments, explicit segment boundaries, source metadata, and the relation between local segment time and recording time. Record unsupported claims rather than filling gaps from a transcript. For each segment, request a dense timeline, concept inventory, demonstrations and screen activity, Q&A with answer status, links/tools/commands/resources, keyframes worth checking, exercises, and uncertainties. Run an omissions pass against the same evidence, reconcile cross-segment overlaps, and retain partial or unanswered questions as such. A successful parse is not a complete account. The resource family distinguishes routine multimodal analysis from explicitly requested deeper reasoning. Model-selector labels and product limits must be verified against the installed version; ChatGPT’s Instant/Pro Extended labels are not Gemini video readiness signals. When a single shard fails while neighboring shards succeed, classify the input separately from the transport. The demonstrated remedy was re-encoding the failing shard, rerunning the cheap proof, then preserving the working media recipe. That is an empirical fix, not proof of the underlying cause. Keep an unresolved run from being duplicated just because a local wait returned. After successful artifact capture, close only the browser tab owned by that run. For research batches, filter using actual source metadata rather than titles or remembered dates; exclude topic-name collisions and irrelevant material. Keep a durable queue with source identity, title, author, duration, and public URL. Make prompts specific to the research topic. Batching, cadence, and quota boundaries must be explicit, not hidden retries. ## Image generation: requested count is not captured count The Codex and Antigravity mockup recipes use one built-in image call per asset. The Oracle/ChatGPT image resource instead requests a clearly numbered batch through one browser call. Preserve that distinction; it is tool-specific advice, not a universal rule. A batch contract makes the number and output granularity explicit: ```text Create exactly N separate images. Each is its own standalone image file. Image 1: <complete scene description>. Image 2: <complete scene description>. ... Output all N as N separate images. No text, no captions, no typography. ``` Count returned files and inspect each one to identify its intended scene; return order need not match prompt order. A short capture can mean later images were still rendering, not that the model refused the batch. Inspect the existing conversation before requesting replacements. A recovery probe that does not generate again is: ```text Do not generate or create any images in this response. Reply with only the digit count of images above. ``` Deduplicate recovered files by checksum. A failure before generation starts differs from a timeout while generation is active; only the former supports a simple immediate retry without duplication risk. Use returned artifact locations rather than constructing paths from a slug that may have been truncated. For long sets, maintain a queue of complete self-contained scene descriptions and per-call requested/received counts. Sequential execution, explicit pacing, and quota-aware stopping make interrupted work resumable. Character consistency needs both the reference image and a repeated textual description; verify the face, clothing, and style rather than assuming the attachment enforced them. The browser image workflow uses its image-appropriate mode, while non-image deep consultations use extended reasoning. This is a distinction between tasks, not permission to carry one model’s mode labels into another product. Refusals are prompt outcomes, not infrastructure errors: report them, change the request to an original permitted concept where appropriate, and do not retry-loop the same refused prompt. ## Generated video: continuous story, separately verified clips The published generation example uses short clips rather than assuming that asking for a minute yields a minute. Its demonstrated output was approximately ten seconds per clip, 1280×720 H.264 video with AAC audio. Those are observed product limits, not guaranteed current limits. Longer stories use multiple clips, continuity references, and a local stitch. Write every beat before starting. Group images into two or three sequential visual references per clip. Where supported, put the prior clip before the next images as a reference for camera language, grade, and tone. Generate sequentially, persist each returned artifact, inspect its duration/codec/dimensions/size, and only then use it as the next clip’s reference. A stitch-safe visual prompt includes: ```text Use the attached images as sequential visual references. Generate a full 10 second cinematic video: <beat-by-beat action>. Audio constraints: no music, no score, no singing, no lyrics, no dialogue, no voiceover, no spoken words, no mouth-synced speech. Prefer a silent clip; if audio is unavoidable, use only subtle non-musical ambient sound. No text, no captions, no readable words. ``` The silent-first policy prevents repeated dialogue or discontinuous generated music from ruining the edit. Strip unwanted clip audio rather than treating a technically successful speech track as usable. Add narration, music, and sound design after picture is locked unless preserving the generated audio was explicitly requested. Use real media inspection, not a download receipt: ```sh ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height,duration -of json clip.mp4 ffmpeg -hide_banner -y -f concat -safe 0 -i concat.txt -c copy story.mp4 ffmpeg -hide_banner -y -i story.mp4 -vf 'fps=1/5,scale=320:-1,tile=3x4' -frames:v 1 contact-sheet.jpg ``` A contact sheet must actually be inspected. Matching codecs and dimensions support stream-copy stitching; a paced edit requires re-encoding and checking audio timing. Report per-clip and final counts, durations, references, and any continuity seams. A generated-video run can finish with a text refusal and no video. That is not a reason to wait indefinitely. Read the visible response and distinguish refusal, quota, unsubmitted prompt, DOM drift, transfer limit, and real generation-in-progress. A prompt still sitting in the composer without a submitted user turn is a send failure, not a slow model. Never silently truncate a video to satisfy a transfer limit. If identity-continuity wording is refused, do not keep submitting the same request. Reframe only toward permitted fictional material; if necessary remove the prior-video identity reference and use loose storyboard references, non-identifiable framing, objects, setting, and grade for continuity. Record the change because it affects the final story. A cosmetic fictional label alone was not a reliable remedy in the example. ## Scheduling is an explicit alternative A schedule is justified only by an agreed recurring action, owner, stop condition, and durable status. The resource family includes a follow-up scheduling tool; the broader software-factory discussion cautions that scheduled curation and review can become noise. Do not turn the availability of a scheduler into a recommendation to schedule everything. Reference ID: factory-advanced-workflow-contracts Topic: Verification Sources: - [Oracle resource family](https://shiny-rosette-m6zy.here.now/#attachments) - [skills/oracle-video/SKILL.md](https://shiny-rosette-m6zy.here.now/skills/oracle-video/SKILL.md) - [skills/oracle/SKILL.md](https://shiny-rosette-m6zy.here.now/skills/oracle/SKILL.md) - [skills/oracle-schedule/SKILL.md](https://shiny-rosette-m6zy.here.now/skills/oracle-schedule/SKILL.md) - [skills/oracle-execute/SKILL.md](https://shiny-rosette-m6zy.here.now/skills/oracle-execute/SKILL.md) - [skills/oracle-video-create/SKILL.md](https://shiny-rosette-m6zy.here.now/skills/oracle-video-create/SKILL.md) - [skills/imagine/SKILL.md](https://shiny-rosette-m6zy.here.now/skills/imagine/SKILL.md) - [skills/oracle/references/round-robin-receipt.md](https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-receipt.md) - [skills/oracle/references/round-robin-transport.md](https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-transport.md) - [skills/oracle-video/references/repeatable-video-followup-process.md](https://shiny-rosette-m6zy.here.now/skills/oracle-video/references/repeatable-video-followup-process.md) --- # Agent Markers debugging workflows: practical reference ## Agent Setup Prompt ```text Set up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug. 1. Inspect the existing agent-markers package and demo files first: - packages/client/src/index.ts - packages/client/src/collector.ts - packages/client/src/types.ts - packages/client/src/capture/console.ts - packages/client/src/capture/fetch.ts - packages/client/src/capture/errors.ts - packages/client/src/serialize.ts - apps/demo/src/main.ts - apps/demo/src/viewer.ts - scripts/smoke-demo.mjs - docs/WORKSHOP.md 2. If the package or demo is missing, scaffold the smallest matching structure. If files already exist, preserve the current API where possible and extend it only as needed. 3. Define or confirm the core schema: - DebugSession: one bounded run with sessionId, appName, schemaVersion, CapturedEvent[], and DebugMoment[] - CapturedEvent: id, sequence, timestamp, type, and metadata for console, fetch, error, manual, DOM, screenshot, or app events - DebugMoment: id, label, note, optional nextAction, timestamp, and nearbyEventIds that reference CapturedEvent ids - export JSON: a JSON-serializable packet that can be saved, attached to a test run, or passed to another agent 4. Implement or confirm createAgentMarkers in packages/client/src/index.ts. It should accept appName, exposeGlobal, and capture options for console, fetch, and errors. It should return mark(...), export(), and stop(). 5. Implement console, fetch, error, and manual capture: - console capture records log/warn/error metadata without creating recursive logging loops - fetch capture records URL, method, status, timing, and failure metadata - error capture records thrown errors and unhandled rejections - manual capture records marker labels, notes, nextAction, and timing - all captured events should receive stable ids and sequence numbers 6. Add privacy-safe defaults: - capture metadata by default - do not export storage values, cookies, tokens, request bodies, response bodies, private DOM text, or screenshots unless deliberately enabled and reviewed - redact sensitive query params, headers, stack paths, and visible private text before saving export JSON - include redaction notes in the exported packet 7. Implement the collector in packages/client/src/collector.ts. Store events in order, enforce a maximum event count, and calculate nearbyEventIds for each DebugMoment using sequence or timestamp proximity. 8. Implement serialize.ts so export() always returns valid JSON without circular references. Optional DOM or screenshot fields should be marked unavailable when no hook is configured. 9. Wire createAgentMarkers into the demo app in apps/demo/src/main.ts with exposeGlobal: true for dev/test and capture enabled for console, fetch, and errors. Add a manual marker entrypoint such as a debug button or keyboard shortcut that calls markers.mark({ label, note, nextAction }). 10. Wire apps/demo/src/viewer.ts so the current session can be exported, displayed, copied, or downloaded as JSON. 11. Expose the dev/test global surface when configured: - window.__AGENT_MARKERS__.mark(...) - window.__AGENT_MARKERS__.export() - window.__AGENT_MARKERS__.stop() 12. Add test-runner export. In a Playwright-style test or equivalent, wait until the app is ready, call window.__AGENT_MARKERS__.mark(...), export the session with page.evaluate, and attach or save agent-markers.json. Assert markers.length > 0, a non-empty note exists, nearbyEventIds is present, and console/fetch/error/manual events appear when enabled. 13. Add bounded replay packet setup for one marker. The packet should include schemaVersion, sessionId, markerId, markerCutoffSeq, nearbyEventIds, filtered console/fetch/error/manual evidence, optional DOM/screenshot availability, included and excluded boundaries, maximum event count, redaction status, and the first verification command. Do not build a full recorder. 14. Update scripts/smoke-demo.mjs so it can launch or exercise the demo, create one marker, trigger at least one console event, fetch event, and error event where practical, export JSON, parse it, and confirm the packet is non-empty. 15. Verify with the available project commands: - npm test - npm run typecheck - npm run build - npm run smoke:demo 16. Confirm setup worked: - createAgentMarkers imports and initializes - mark() creates a DebugMoment with a specific note - nearbyEventIds is non-empty after nearby capture activity - exported events include console, fetch, error, and manual types when enabled - export JSON parses cleanly - window.__AGENT_MARKERS__ is available in dev/test only - stop() restores patched console, fetch, and error listeners - test-runner export saves or attaches agent-markers.json - privacy defaults exclude sensitive values Report the files changed, setup choices, verification commands and results, sample export path, privacy boundaries, unavailable hooks, and any failed checks. If setup checks fail, stop and report the blocker. Do not debug a specific product bug until the setup and verification pass. ``` ## Big Idea Start by sending cheap perspective-based agents through weird paths. Then use agent markers to capture the exact moment that should become a bounded debug packet. Core pattern: ```text 5 Monkeys QA -> mark -> capture -> explain -> review/export ``` The 5 Monkeys pattern finds strange states a happy-path check would miss. Agent markers turn one of those strange states into evidence another agent can use. An agent marker is a human-intent anchor inside a debugging workflow. It answers: - why this moment mattered - what evidence was nearby - what should be inspected next - what the next human or agent should not waste time guessing Agent markers are not full replay systems. They are bounded debug packets. ## Try This Now Create one marker for a checkout UI bug: `window.__AGENT_MARKERS__.mark({ label: "checkout disabled unexpectedly", note: "Expected submit to enable after terms and shipping were selected." })` Export the session and check that the marker has nearby evidence, not just a label. ## Start With 5 Monkeys Use 5 Monkeys before marker capture when the bug is vague, stateful, or hidden behind normal user behavior. Assign one lens per pass: | Lens | What It Tries | | --- | --- | | expert power user | shortcuts, fast navigation, hidden affordances | | brand-new first-time user | confusion, missing affordances, unclear copy | | inexperienced user | accidental clicks, mistaken paths, recovery failures | | impatient returning user | rapid clicks, skipped steps, partial flows | Make each pass explore weird paths: - keyboard shortcut sequences - back/forward navigation mid-flow - repeated or rapid clicks on one control - toggling modes back and forth - starting a flow, then bailing out - refreshing or re-entering with partial state Write each pass to a discardable QA note such as `.notes/qa-01.md`. Collate the findings, keep only useful bugs, and mark the one moment that best captures the state failure. Then capture that moment with agent markers: ```text weird state found -> human marks the decisive moment -> export nearby evidence ``` Do not replace stable business-logic tests with 5 Monkeys. Use it to discover UI and state failures that tests and logs did not already isolate. ## Files To Inspect Agent markers project references: ```text packages/client/src/index.ts packages/client/src/collector.ts packages/client/src/types.ts packages/client/src/capture/console.ts packages/client/src/capture/fetch.ts packages/client/src/capture/errors.ts packages/client/src/serialize.ts apps/demo/src/main.ts apps/demo/src/viewer.ts scripts/smoke-demo.mjs docs/WORKSHOP.md ``` ## When To Reach For This Use markers when logs are real but the important moment still needs human context. | Use Markers For | Why | | --- | --- | | checkout bug | mark the exact UI state where expected and actual diverge | | auth/session refresh issue | capture nearby fetch/error/console evidence around the failure | | billing admin UI failure | attach human expectation to the visible broken state | | flaky browser test | export a debug packet from the test runner | | design/debug review | pair screenshot/DOM hooks with a human explanation | | long agent debugging session | leave explicit breadcrumbs for the next pass | Skip markers when: - one failing unit test already isolates the bug - a stack trace points to one obvious line - no one can explain why the moment matters - the capture would expose sensitive data without redaction - the task needs full deterministic replay rather than a bounded debug packet ## How This Used To Work What you used to expect: ```text If enough logs are captured, the agent can infer the important moment. ``` What the workflow gives you now: ```text Logs show events. A marker ties a specific moment to human intent, nearby evidence, and the next debugging question. ``` What you used to expect: ```text A screenshot or console dump is enough context. ``` What the workflow gives you now: ```text The useful packet combines the marker note, nearby console/fetch/error/manual events, optional DOM or screenshot capture, privacy boundaries, and an export. ``` ## The Mental Model ```text DebugSession -> CapturedEvent[] -> DebugMoment[] -> export JSON -> agent prompt / test artifact / work unit ``` | Concept | Meaning | | --- | --- | | `DebugSession` | one bounded debugging run | | `CapturedEvent` | console, fetch, error, manual, DOM, screenshot, or app event | | `DebugMoment` | the human marker: label, note, timestamp, nearby evidence | | `nearbyEventIds` | event ids around the marked moment | | export JSON | portable debug packet | | `stop()` | cleanup that restores patched browser APIs | ## Basic Browser Setup Create markers in a browser app: ```ts import { createAgentMarkers } from "@agent-markers/client"; const markers = createAgentMarkers({ appName: "checkout-app", exposeGlobal: true, capture: { console: true, fetch: true, errors: true, }, }); ``` Expose a manual marker action: ```ts document.querySelector("#mark-debug")?.addEventListener("click", () => { markers.mark({ label: "checkout payment method disappeared", note: "Expected saved payment selector to stay visible after refresh.", }); }); ``` Export: ```ts const session = markers.export(); console.log(JSON.stringify(session, null, 2)); ``` Clean up patched APIs: ```ts markers.stop(); ``` ## Global Test Surface In dev/test, expose the marker surface: ```ts createAgentMarkers({ appName: "checkout-app", exposeGlobal: true, }); ``` Then inspect from the browser console or a test runner: ```js window.__AGENT_MARKERS__.mark({ label: "checkout failure", note: "Expected saved cards to render before submit.", }); const session = window.__AGENT_MARKERS__.export(); session.markers.length; ``` Use the global for test export, not as the only application API. ## Capture Types | Capture | What It Adds | Watch For | | --- | --- | --- | | console | logs, warnings, errors | noisy output | | fetch | request URL, method, status, timing | request/response bodies may be sensitive | | errors | thrown errors and unhandled rejections | stack traces may include private paths | | manual | human-entered labels and notes | must be specific | | DOM hook | optional host-provided DOM snapshot | avoid private text | | screenshot hook | optional host-provided image capture | unavailable in some environments | | storage metadata | keys/counts, not full values by default | never dump secrets by accident | Privacy rule: ```text Capture metadata by default. Capture values only when deliberately enabled and safe. ``` ## Marker Shape A useful marker has: ```json { "label": "checkout saved card missing", "note": "Expected saved payment methods to appear after login refresh; actual UI shows empty selector.", "nextAction": "Inspect auth refresh state, checkout payment query, and recent fetch events." } ``` Weak marker: ```json { "label": "broken" } ``` Better marker: ```json { "label": "saved payment selector empty after refresh", "note": "At this moment the user is logged in, the account menu shows the correct user, but checkout has no saved cards.", "nextAction": "Compare account payment fetch response with checkout payment state." } ``` ## Export A Debug Packet Export from browser: ```js const session = window.__AGENT_MARKERS__.export(); console.log(JSON.stringify(session, null, 2)); ``` Save in a test: ```ts const session = await page.evaluate(() => window.__AGENT_MARKERS__.export()); await testInfo.attach("agent-markers.json", { body: JSON.stringify(session, null, 2), contentType: "application/json", }); ``` Or write to disk in a local script: ```js const session = await page.evaluate(() => window.__AGENT_MARKERS__.export()); await fs.promises.writeFile( "artifacts/agent-markers/checkout-session.json", JSON.stringify(session, null, 2) ); ``` ## Verify The Project Common checks: ```bash npm test npm run typecheck npm run build npm run smoke:demo ``` What to look for: - marker can be created - marker has a human explanation - nearby events are linked with `nearbyEventIds` - console/fetch/error/manual events appear when enabled - storage values are not dumped by default - export JSON is valid - `stop()` restores patched browser APIs - test runner can access `window.__AGENT_MARKERS__` ## Turn A Marker Export Into An Agent Prompt Prompt shape: ```markdown # Debug Prompt From Agent Marker ## Source Artifact - marker export: - schema version: - marker id: - marker label: ## Human Explanation - expected: - actual: - why this moment matters: - next action: ## Nearby Evidence - console: - fetch: - error: - manual: - screenshot: - DOM: ## Privacy Boundary - storage values exported? no - request bodies exported? no - response bodies exported? no - private text removed: ## Task Find the smallest likely bug path and propose the first verification command. Do not invent app state that is not in the marker packet. ``` ## Bounded Replay Capsule Do not build a full recorder. Design the smallest packet that makes the marked moment inspectable. ```markdown # Bounded Replay Capsule - schemaVersion: - markerId: - sessionId: - markerCutoffSeq: - nearbyEventIds: - console: - fetch: - errors: - manual: - screenshot: - dom: - redaction: ## Boundaries - included: - excluded: - maximum event count: - privacy rules: ## How To Use It - agent prompt: - human review: - verification command: ``` ## App-Specific Marker Flow An app may wire a shortcut such as `Ctrl+M` to create durable marker evidence. Conceptual flow: ```text Ctrl+M -> create marker id -> capture screenshot if available -> open note/explanation UI -> save human explanation -> write durable app logs ``` Expected log strings: ```text dev_marker dev_marker_explanation ``` Inspection shape: ```bash rg -n "dev_marker|dev_marker_explanation" <app-log-path>/latest-session.jsonl ``` Keep this generic: - one marker id shared across marker and explanation - screenshot optional - explanation required - bounded nearby evidence - clear next action ## Ask The Agent This Add markers to a browser bug investigation: ```text Add agent markers to the checkout browser flow. Capture console, fetch, errors, and manual markers. Expose `window.__AGENT_MARKERS__` in dev/test. Add a marker for the moment saved payment methods disappear after auth refresh. Export JSON and show how to confirm nearbyEventIds, privacy defaults, and marker explanation. ``` Turn export into a debug prompt: ```text Use this agent-marker export as the bounded debug packet. Focus on the marked checkout failure. Summarize the human explanation, nearby console/fetch/error/manual evidence, privacy boundaries, and the first verification command. Do not infer app state that is not in the packet. ``` Write a test export: ```text Create a Playwright-style test path that triggers the checkout bug, calls `window.__AGENT_MARKERS__.mark(...)`, exports the session JSON, and attaches it as a test artifact. Include the checks that prove marker count, nearbyEventIds, and event types are present. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | marker client installed | app imports `createAgentMarkers` | | marker created | export has `markers.length > 0` | | explanation present | marker has a specific `note` | | nearby evidence linked | marker has non-empty `nearbyEventIds` | | console captured | exported events include console type | | fetch captured | exported events include fetch type | | errors captured | exported events include error type | | privacy default safe | storage values are absent unless deliberately enabled | | global test surface works | `window.__AGENT_MARKERS__.export()` returns session | | export saved | JSON artifact exists and is non-empty | | cleanup handled | `stop()` called when patching should end | | project verifies | `npm test`, `npm run typecheck`, `npm run build`, `npm run smoke:demo` | ## If It Goes Wrong ### Marker Has No Note Add expected/actual context. ```text What should have happened: What happened: Why this moment matters: Next action: ``` ### Export Has Too Many Raw Logs Focus on one marker id and its nearby events. Increase event limits deliberately, not by default. ### `nearbyEventIds` Is Empty Mark closer to the failure or adjust the nearby event window. ### Sensitive Storage Values Were Captured Redact and rebuild the export. Capture storage metadata, not values, unless safe and intentional. ### Console/Fetch Remains Patched Call: ```ts markers.stop(); ``` ### Test Runner Cannot Export Confirm `exposeGlobal: true` in dev/test and wait for app readiness before reading `window.__AGENT_MARKERS__`. ### Screenshot Or DOM Hook Is Missing Mark it unavailable. Do not pretend a screenshot or DOM snapshot exists. ## References And Resources - Agent marker client entry: `packages/client/src/index.ts` - Collector source: `packages/client/src/collector.ts` - Types: `packages/client/src/types.ts` - Demo app: `apps/demo/src/main.ts` - Viewer/export UI: `apps/demo/src/viewer.ts` - Smoke script: `scripts/smoke-demo.mjs` - Playwright docs: https://playwright.dev/docs/test-assertions - Cypress docs: https://docs.cypress.io/ ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-marker-workflows-reference Topic: Verification Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Agent Markers debugging workflows: practice drills These exercises practice creating a bounded debug packet from a marked browser moment. ## Exercise 1: Identify The Marker Moment Choose a bug and write the marker. ```markdown # Marker Moment - app area: - expected: - actual: - why this moment matters: - next action: - what nearby evidence should be captured: ``` Good marker: ```json { "label": "saved payment selector empty after refresh", "note": "Expected saved cards to stay visible after auth refresh; actual selector is empty.", "nextAction": "Compare account payment fetch response with checkout payment state." } ``` ## Exercise 2: Add The Client Sketch the setup: ```ts import { createAgentMarkers } from "@agent-markers/client"; const markers = createAgentMarkers({ appName: "checkout-app", exposeGlobal: true, capture: { console: true, fetch: true, errors: true, }, }); ``` Fill out: ```markdown # Client Setup - app name: - exposeGlobal enabled? yes/no - console capture? yes/no - fetch capture? yes/no - error capture? yes/no - privacy concern: ``` ## Exercise 3: Create And Export A Marker Run in browser console or test: ```js window.__AGENT_MARKERS__.mark({ label: "checkout failure", note: "Expected saved cards to render before submit.", nextAction: "Inspect checkout payment query and auth refresh state.", }); const session = window.__AGENT_MARKERS__.export(); JSON.stringify(session, null, 2); ``` Fill out: ```markdown # Marker Export - marker count: - event count: - marker label: - marker note: - nearbyEventIds present? yes/no - event types: ``` ## Exercise 4: Privacy Review Inspect the export. ```js const session = window.__AGENT_MARKERS__.export(); ({ schemaVersion: session.schemaVersion, markerCount: session.markers.length, eventCount: session.events.length, storageHasValues: JSON.stringify(session).includes("secret-value"), }); ``` Fill out: ```markdown # Privacy Review - storage keys captured: - storage values captured? yes/no - request bodies captured? yes/no - response bodies captured? yes/no - private text present? yes/no - redaction needed: ``` ## Exercise 5: Test Runner Export Playwright-style shape: ```ts const session = await page.evaluate(() => window.__AGENT_MARKERS__.export()); await testInfo.attach("agent-markers.json", { body: JSON.stringify(session, null, 2), contentType: "application/json", }); ``` Fill out: ```markdown # Test Export - test command: - export artifact: - marker count: - nearbyEventIds present? yes/no - test can access global? yes/no - app readiness check: ``` ## Exercise 6: Verify The Project Run: ```bash npm test npm run typecheck npm run build npm run smoke:demo ``` Fill out: ```markdown # Verification - npm test: - npm run typecheck: - npm run build: - npm run smoke:demo: - failed command: - next debugging step: ``` ## Exercise 7: Turn Export Into A Debug Prompt Write: ```markdown # Debug Prompt From Agent Marker ## Source Artifact - marker export: - schema version: - marker id: - marker label: ## Human Explanation - expected: - actual: - why this moment matters: - next action: ## Nearby Evidence - console: - fetch: - error: - manual: - screenshot: - DOM: ## Privacy Boundary - storage values exported? no - request bodies exported? no - response bodies exported? no - private text removed: ## Task Find the smallest likely bug path and propose the first verification command. Do not invent app state that is not in the marker packet. ``` ## Exercise 8: Design A Bounded Replay Capsule Do not implement a recorder. Design the packet. ```markdown # Bounded Replay Capsule - schemaVersion: - markerId: - sessionId: - markerCutoffSeq: - nearbyEventIds: - console: - fetch: - errors: - manual: - screenshot: - dom: - redaction: ## Boundaries - included: - excluded: - maximum event count: - privacy rules: ## How To Use It - agent prompt: - human review: - verification command: ``` Question: ```text What is the smallest capsule that would let someone debug the marked moment? ``` ## Exercise 9: App-Specific Marker Flow Inspect or design a shortcut flow. ```text Ctrl+M -> create marker id -> capture screenshot if available -> open note/explanation UI -> save human explanation -> write durable app logs ``` Possible inspection command: ```bash rg -n "dev_marker|dev_marker_explanation" <app-log-path>/latest-session.jsonl ``` Fill out: ```markdown # App-Specific Marker Flow - shortcut: - marker id format: - screenshot available? yes/no: - explanation UI: - log path: - `dev_marker` written? yes/no: - `dev_marker_explanation` written? yes/no: - shared marker id? yes/no: - what this preserves: - what this does not try to solve: ``` ## Exercise 10: Failure Path Drill For each failure, choose a recovery. | Failure | Recovery | | --- | --- | | marker has no note | | | export has thousands of raw log entries | | | marker has empty nearbyEventIds | | | exported JSON contains sensitive storage values | | | console/fetch remains patched after test | | | Playwright cannot read `window.__AGENT_MARKERS__` | | | marker does not say what to inspect next | | | screenshot hook returns nothing | | | DOM snapshot includes private text | | | smoke test fails before clicking marker buttons | | Recovery options: ```text add expected/actual note focus on one marker id mark closer to the failure raise nearbyEventLimit deliberately redact and rebuild export restore with stop() enable exposeGlobal in dev/test wait for app readiness add next action mark screenshot unavailable narrow DOM snapshot save failed smoke and retry with sharper condition ``` ## Exercise 11: Section 9 Bridge Packet Use one marker export to prepare a bounded work unit. ```markdown # Section 9 Bridge: Imp Debug Packet - source artifact: DebugSession export - schemaVersion: - marker id: - marker label: - marker note: - nearbyEventIds: - evidence lanes: - console: - fetch: - error: - manual: - privacy checks: - storageHasValues: - request bodies exported? no - response bodies exported? no - likely app area: - required verification: - npm test - npm run typecheck - npm run build - next action: ``` Fill out: ```markdown # Bridge Review - packet names one marker id? yes/no: - nearby evidence is bounded? yes/no: - privacy rules are explicit? yes/no: - verification commands are present? yes/no: - task is clear enough for an Imp? yes/no: - what would make it smaller or sharper: ``` ## Final Check Inspect manually: ```js const session = window.__AGENT_MARKERS__.export(); ({ schemaVersion: session.schemaVersion, markerCount: session.markers.length, eventCount: session.events.length, hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0), eventTypes: [...new Set(session.events.map((event) => event.type))], }); ``` Fill out: ```markdown # Final Agent Markers Check - marker created? yes/no: - marker has human explanation? yes/no: - nearbyEventIds present? yes/no: - console evidence captured? yes/no: - fetch evidence captured? yes/no: - error evidence captured? yes/no: - manual evidence captured? yes/no: - storage values avoided? yes/no: - export saved? yes/no: - test runner can export? yes/no: - `stop()` cleanup handled? yes/no: - next action written? yes/no: - ready to hand off as bounded debug packet? yes/no: ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-marker-workflows-practice Topic: Verification Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Artifact evidence is not the same as success Separate observed creation, command execution, visible output, and verified completion; preserve failures and the exact next check. ## Evidence levels A file appearing does not prove that its contents work. A command running does not prove that it finished successfully. A successful structural check does not prove behavior in the application. Keep each event separate, attach the relevant artifact or exact signal, and state what remains unverified. Useful receipts answer: what was attempted; what changed; what was actually observed; which check ran; what passed or failed; what remains uncertain; and what the next session should reproduce. Failed demonstrations are evidence, not editorial blemishes to erase. The environment examples demonstrate stderr guidance, quarantine behavior, blocked destructive commands, and rewritten issue flags under a test harness. Their own caveats distinguish those results from a live agent’s tendency to comply. The MDFlow example demonstrates inspection and proposal mechanics while retaining an unverified eval roster and a wrapper exercise that did not cleanly succeed. The Markers example is a deliberately planted bug and a bounded redacted trail, not a measured success rate on organic bugs. Reference ID: factory-artifact-evidence Topic: Verification Sources: - [Artifact reference](https://proud-anchor-53zn.here.now/artifacts.md) --- # Browser Proof Field Guide > Original source pages and recordings require authorized access. The full article text here is public. Make Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts. Use this when a UI, auth, form, route, or responsive change cannot be considered done from source inspection alone. > Browser automation CLI designed for AI agents. [agent-browser docs](https://agent-browser.dev/) ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | Codex Browser | Local/public unauthenticated route | Fast visual proof and screenshots | .notes/browser-proof/<task>/browser-proof.md | | Chrome extension/manual Chrome | Signed-in browser state | Auth flows and internal SaaS pages | Redacted manual proof plus screenshot | | agent-browser | Terminal-friendly browser control | snapshot, click, fill, screenshot | snapshot.txt plus screenshot.png | | Playwright | Repeatable or CI-friendly flow | Trace, console, screenshot, deterministic test | trace.zip plus console.json | | DevTools/CDP | Raw console/network evidence | HAR, console objects, performance details | console.log plus network.har | ## Agent-ready prompt ```text Use browser proof before claiming this UI task is done. Inspect package.json and AGENTS.md first. Pick the browser surface that matches the auth and repeatability needs. Save .notes/browser-proof/<task>/browser-proof.md with URL, viewport, auth context, actions, expected/observed result, console errors, network failures, artifacts, command output, diff summary, and pass/fail. Redact cookies, tokens, customer data, QR codes, and auth headers. ``` ## Applied stories ### Authenticated billing route **Role:** SaaS frontend engineer Codex changed /settings/billing, but the route only works when logged in. **Agent brief:** Use signed-in Chrome or a seeded login; verify current plan, change plan, submit, and capture final visible success state. **Done when:** - browser-proof.md - screenshot - console/network summary - typecheck/test log ### Pricing weird-path QA **Role:** Growth engineer Plan toggles, coupons, and checkout modals fail after repeated back/refresh/toggle sequences. **Agent brief:** Run five browser QA perspectives and collate reproducible findings into .notes/qa/pricing-summary.md. **Done when:** - perspective files - summary severity list - screenshots/transcripts - console status ### Preview deployment triage **Role:** Frontend lead A PR preview is green but nobody opened changed routes. **Agent brief:** Discover preview URL, open homepage and changed route, capture status, visible error text, console errors, and screenshot. **Done when:** - preview URL - browser receipt - blocker/warning/clean verdict - no source edits ## Tips and gotchas - Tests prove code paths; browser proof proves user-visible behavior. - Use the in-app browser for localhost/public pages, but use Chrome/manual auth for signed-in state. - Do not make Playwright mandatory for every UI task; use it when repeatability matters. - Treat screenshots, traces, HARs, and console logs as sensitive local artifacts by default. - A Stop hook should check receipt files, not drive the browser itself. ## References - [Codex in-app browser](https://developers.openai.com/codex/app/browser) - [Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension) - [agent-browser](https://github.com/vercel-labs/agent-browser) - [Playwright screenshots](https://playwright.dev/docs/screenshots) - [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer) - [Chrome DevTools Console](https://developer.chrome.com/docs/devtools/console/log) ## Related principles - [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/) - [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) - [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/) Reference ID: foundations-browser-proof-field-guide Topic: Verification Sources: - [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html) - [Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-08.html) - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Explore software through perspectives and runtime QA > Original source pages and recordings require authorized access. The full article text here is public. The practice is using agents as perspective-driven explorers instead of asking one generic agent to test or research everything. John shows how lenses like expert, new user, grandma, and power user can shape research and QA, how discardable QA files can push agents through non-obvious app paths, and how rough narrated screen recordings can become implementation instructions. He also explains how CMUX state can power context-aware shortcuts, why he often avoids worktree overhead, and where rigorous tests still belong: stable business logic rather than fast-changing UI experiments. ## Working outcomes - Use perspective-based prompting and discardable QA files for non-obvious user paths - Apply the 5 Monkeys technique and use CMUX state for context-aware shortcuts - Extract implementation intent from narrated screen recordings into Gemini ## Concepts and consequences ### Perspective-based prompting Instead of asking one generic agent to research or test your app, assign it a lens: expert, new user, grandma, power user, or another real audience. That lens changes what the agent notices and which assumptions it challenges. **Why it matters:** It helps you escape creator bias and shape the output around the actual demographics or user types your application needs to support. ### Discardable QA files A QA file is a temporary assignment document for an agent: a numbered list of things to try, paths to walk, buttons to find, and a perspective to act from. John treats these as created in the moment, not as permanent test infrastructure. **Why it matters:** They let you test the current shape of a fast-changing product without locking every changing UI decision into a brittle long-term test suite. ### The 5 Monkeys technique The goal is to have agents use the app in non-obvious ways: find buttons, click around, try shortcuts, press back after reaching a page, and look for modes or state that stay open unexpectedly. **Why it matters:** This catches UX and state issues that a normal verification prompt may miss because the model tends to follow the same visible patterns the developer already expects. ### CMUX state for context-aware shortcuts John describes a CMUX inspect-style command that exposes the multiplexer state as an object, including the focused pane and that pane’s current working directory. He uses that context with a Karabiner shortcut to open tools over the terminal he is already focused on. **Why it matters:** It turns the terminal layout into an automation surface: a shortcut can open an editor, run Git commands, start debugging, or trigger other tools in the project you are currently looking at. ### Video-driven intent extraction John records a rough screen interaction, narrates UI changes aloud, and drops the video into Gemini to turn it into AI instructions for implementation. **Why it matters:** It lowers the cost of explaining visual changes when pointing, circling, and talking are faster than writing a polished written spec. ## Reference tools and resources ### Agent Browser An experimental Vercel Labs browser-agent project John named as his go-to tool for controlling sites, clicking through pages, inspecting DOM state, and using Chrome DevTools-style information. **Use when:** Reach for it when you want an agent to verify UI behavior in an actual browser. In this section, John described the tool but said he would dig into it more later. [Reference](https://github.com/vercel-labs/agent-browser) ### ClickLight A desktop overlay tool John briefly demonstrated for showing clicks, cursor actions, drawings, and keyboard shortcuts during screen shares. **Use when:** Use it when recording or presenting a workflow where viewers need to see what you clicked or typed. It was a supporting presentation tool in this section, not the core QA technique. [Reference](https://github.com/aurorascharff/ClickLight) ### CleanShot A screenshot and screen recording tool John used to capture a quick narrated UI-change video. **Use when:** Reach for it, or any similar screen recorder, when a visual change is easier to show and narrate than to describe in text. search: CleanShot screen recording app ### Gemini video prompting John used Gemini for video understanding by dropping in a screen recording and asking it to convert the interaction into AI instructions. **Use when:** Use it when your intended change is easier to communicate through a narrated screen recording, especially for visual layout work. search: Gemini video understanding prompt screen recording instructions ### Tailscale A mesh networking tool John used to connect to another Mac and SSH into it from his local workflow. **Use when:** Use it when you need private remote machine access from your local agent or terminal workflow without exposing services broadly. [Reference](https://tailscale.com) ### Karabiner-Elements A macOS keyboard customization tool John used as part of a global shortcut workflow that opened an editor/search overlay in the context of the active terminal. **Use when:** Reach for it when you want app-global shortcuts that can trigger workspace-aware scripts or tools from wherever you are focused. search: Karabiner-Elements macOS keyboard customizer ### CMUX inspect A CMUX inspection pattern John described as returning an object for the multiplexer state, including the focused pane and current working directory. **Use when:** Reach for this pattern when you want shortcuts or agents to act on the exact terminal pane and project you are currently focused on. search: CMUX inspect focused pane current working directory ## Recommendations and best practices - Create separate research or QA prompts for expert, new-user, power-user, and inexperienced-user perspectives instead of asking one generic agent to cover everything. - Write QA files as disposable numbered assignments, not permanent monuments; keep them cheap enough that you are willing to delete and regenerate them. - Tell agents to explore non-obvious paths explicitly: find buttons, try shortcuts, press back after navigation, change modes, and look for state that stays open unexpectedly. - Keep rigorous tests for stable business logic and locked-down parts of the system; avoid over-testing UI areas you still expect to reshape frequently. - Use browser-driving tools when the task needs real clicking, DOM inspection, or performance/devtools signals rather than code inspection alone. - When a UI change is easier to show than write, record a short narrated screen video and ask a multimodal model to turn it into implementation instructions. - Watch disk usage when running many agents or worktrees on compiled projects; build artifacts such as Rust target directories can balloon fast. - For performance-sensitive apps, have QA agents capture memory, performance, API-call, refresh, and latency signals while they walk through the app if your tooling supports it. ## Practice and acceptance criteria Practice using agents as cheap, perspective-driven explorers so you can find UI blind spots without turning every fast-changing experiment into permanent test infrastructure. ### Checklist 1. Pick one feature or screen in your current app that has enough UI state to be interesting: navigation, modes, shortcuts, buttons, or other interactions. 2. Create four short perspective prompts for the same feature: expert user, first-time user, inexperienced user, and power user. 3. Write a temporary QA file with numbered tasks that explicitly ask agents to find buttons and try non-obvious paths such as shortcuts, back navigation, mode changes, and partial navigation sequences. 4. Run separate agent or browser-verification passes against the same feature using different perspective prompts. 5. Review the outputs for concrete non-obvious paths, stuck states, confusing UX, or repeated happy-path behavior that did not teach you anything new. 6. For each useful finding, decide whether it belongs in a durable test because it covers stable business logic, or whether it should stay flexible because the UI is still changing. 7. For one visual UI change, record a short narrated screen video and ask a multimodal model to turn it into implementation instructions. 8. Inspect your terminal or multiplexer state as structured data if your setup supports it, and note which fields would let a shortcut target the correct working directory automatically. 9. If you run many agents, worktrees, or compiled builds, watch for large generated artifacts and decide whether you need a disk-usage safeguard. ### Four-Lens QA Pass **Difficulty:** Easy Choose one UI flow and create discardable QA prompts for expert, new-user, inexperienced-user, and power-user perspectives. Run an agent pass for each perspective and compare what each one notices. **Done when:** You have at least one finding or observation that appears in only one perspective's output, showing that the lens changed the exploration. ### Mini 5 Monkeys Run **Difficulty:** Medium Write a numbered QA assignment that tells agents to explore non-obvious behavior: find buttons, try shortcuts, use back navigation, move through partial flows, change modes, and look for state that stays open unexpectedly. **Done when:** You end with notes about any surprising paths, stuck states, mode issues, or confirmation that the non-happy-path pass did not reveal a useful issue. ### Video Intent to Instructions **Difficulty:** Medium Record a short screen video of a UI you want changed while narrating what should change visually, such as button styling, section order, or header placement. Feed it to a multimodal model and ask for implementation instructions, then review the useful parts before turning them into an agent prompt. **Done when:** The resulting prompt contains concrete visual changes and references to the relevant UI elements without requiring another person to watch the video. ### Single-Branch Agent Coordination With Safeguards **Difficulty:** Hard Prototype a single-branch multi-agent workflow for one feature: ask a manager agent to assign bounded parallel tasks, keep the agents in the same project instead of adding worktrees by default, and add a simple disk-usage check for large generated build artifacts. **Done when:** You can run exploratory agent work without unnecessary worktree overhead, with clear task boundaries and a visible safeguard against runaway build artifacts. ## Questions to test understanding ### Why does perspective-based prompting usually produce better QA findings than asking one generic agent to test the app? - **A.** It changes what the agent notices, which assumptions it questions, and which paths it tries. - **B.** It guarantees the agent will write production-ready integration tests. - **C.** It makes the agent reuse your existing browser cookies automatically. - **D.** It prevents the agent from exploring anything outside the happy path. **Answer: A.** A persona or lens pushes the agent toward different risks and user behaviors. An expert, new user, grandma, and power user will naturally stress different parts of the same interface. ### What makes a discardable QA file useful in this lesson's workflow? - **A.** It becomes the final source of truth for every future regression test. - **B.** It gives an agent a temporary numbered mission that can be regenerated as the UI changes. - **C.** It replaces all business-logic tests permanently. - **D.** It stores private auth cookies so browser agents can skip login. **Answer: B.** The point is cheap scaffolding: numbered tasks, a perspective, and non-obvious paths for the current version of the product. It should be easy to delete or rewrite. ### Which instruction best matches the 5 Monkeys technique? - **A.** Confirm that the signup button works using only the documented happy path. - **B.** Inspect the codebase and summarize every component dependency. - **C.** Find buttons, try shortcuts, press back after navigation, change modes, and look for surprising state behavior. - **D.** Write a complete Playwright suite before looking at the UI. **Answer: C.** The 5 Monkeys idea in this section is to push agents toward non-obvious app usage rather than one careful happy-path check. John’s example was a shortcut leading to a page, then pressing back and noticing a mode stayed open. ### Why is exposing CMUX state as an object powerful for a Codex-style workflow? - **A.** It lets a shortcut or agent target the focused pane and current working directory without manual setup. - **B.** It automatically fixes merge conflicts across all branches. - **C.** It encrypts remote SSH traffic without any other tool. - **D.** It converts screen recordings into implementation instructions. **Answer: A.** Structured pane state turns your terminal layout into an automation surface. A global shortcut can launch the right editor, Git command, debugger, or other tool in the context you are already focused on. ### What is the safest way to apply the video-to-instructions workflow from the lesson? - **A.** Record a rough interaction, narrate the intended UI changes clearly, ask a multimodal model for implementation steps, then review the output before coding. - **B.** Record a video silently and let the model infer all business requirements. - **C.** Upload sensitive production data because video prompts are always private by default. - **D.** Treat the model's generated checklist as production code with no human review. **Answer: A.** The video only needs to be clear enough to communicate visual intent, especially with narration and pointing. The generated instructions are a draft to inspect, not a substitute for judgment. ## Reflection prompts - Where are you currently over-testing a fast-changing UI when a discardable QA file would give you faster learning? - Which user perspective is most underrepresented in your current development process, and what would that person probably try that you would not? - What parts of your local workflow could become automation surfaces if your focused pane and working directory were available as structured state? ## Further applications 1. Build a four-perspective prompt matrix for one feature and compare what each persona notices that the others miss. 2. Create a throwaway QA file with numbered non-obvious path tasks and run agent passes against the same UI. 3. Prototype a video-to-instructions loop: record 30 seconds of pointing and narration, then ask a multimodal model for junior-developer implementation steps. 4. Add lightweight performance logging to QA runs so agents capture memory, API calls, refreshes, and latency while they explore. 5. Experiment with a single-branch multi-agent workflow before adding worktrees, and only add worktrees when isolation clearly beats the coordination overhead. ## Applied exercises Perspective Prompt Matrix Blueprint **Objective:** Construct a flexible research template config folder containing four distinct system prompts: persona-expert.md, persona-novice.md, persona-grandparent.md, and persona-poweruser.md. Write an execution bash script using a local LLM CLI tool to process an identical feature specification document across all four prompts, outputting isolated markdown results into a retrieval/ target folder.Video-to-Code Instructional Pipeline **Objective:** Replicate John’s rapid layout prototyping pipeline. Use any native capture tool (e.g., CleanShot, QuickTime) to record a 30-second screen interaction of an existing local frontend interface. Explicitly dictate audio adjustments (e.g., color alterations, structural re-ordering). Process the raw output file directly through a long-context multimodal model like Gemini, and evaluate the clarity of the resulting markdown instructions. ## Questions and answers ### When generating a lot of research, what guiding principles do you reach for for staying organized, as well as optimized for the retrieval? John relies on the core concept of perspective-based prompting. Instead of collecting unstructured data dumps, he assigns specific personas (expert, new user, grandparent, power user) to separate data pipelines. He also generates modular, numbered QA assignment files that instruct agents to discover non-obvious app paths, keeping the output highly targeted and organized. ### do you have a goto system for agents to test and verify via browser? i have issues, with auth, etc... John uses Agent Browser, an open-source experimental project originating from Vercel Labs. It excels at driving Chrome dev tools, analyzing performance metrics, and navigating complex layouts. Note that as pointed out in the chat session, it does not implicitly forward local browser cookies, so prompts must include explicit onboarding steps or registration rules for authentication sequences. ### do you use worktrees? shortcut that copies over .env as well? and shut them down? John used to rely on Git worktrees when models were less capable, but has mostly abandoned them. Because his recent projects at Vercel have been isolated solo assignments, he prefers working directly out of a single main branch or standard PR branch. Instead of juggling port mappings and setting up environment configurations for separate worktrees, he lets parallel agents operate within bounded directories in the same branch. This avoids a known issue where massive Rust compilation targets duplicate disk usage and exhaust disk space. ### is screendrop what you were using when you were sending stuff to other mac using oracle? you could see your other mac in realtime? No, Screendrop is a separate open-source, local alternative to Clean Shot that John is tracking. The remote display synchronization shown earlier was simply Apple’s native mac OS Screen Sharing app routed securely across a private Tailscale mesh network connection. ### What are your thoughts on testing? These QA files seem like a partial replacement for rigorous testing suites. John confirms he increasingly leans toward discardable runtime QA files over heavy test suites. Because code generation tools make changing software quick and trivial, over-indexing on rigid testing setups creates friction against iteration. He advises keeping strict test suites strictly reserved for fixed business logic that will not change, while using flexible QA agents running overnight loops to handle fluid visual interface verification. ### So, it would be interesting to see how you keep track. So, is it just that you have the different conversations pinned to the left, and then you look at them to keep an overview, or how do we do it? And then, especially this research, planning, building part, and the specialized agents? John begins to answer as the chunk cuts off, explaining that tracking specialized agents involves coordinating dedicated task-based UI interfaces and distinct workspace contexts. The continuation uses a primary orchestrator and distinct focused panes for quality control, performance, research, and note-taking. ## Operational playbooks - [5 Monkeys QA swarm](/topics/foundations-five-monkeys-playbook/) - [Browser Proof Field Guide](/topics/foundations-browser-proof-field-guide/) - [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-05.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-05.html) ### Visual reference index - [01:41:00](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-1): Agent Browser GitHub documentation display on Chrome - [01:42:40](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-2): Editor view showing generated website update instructions and text/code edits - [01:45:50](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-3): GitHub/repository picker or file search view with ClickLight-related repository visible - [01:46:45](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-4): Signal Knit hoodie site preview with layout/selection overlay visible - [01:48:15](https://codex-workshop-followup.pages.dev/lesson-05.html): Browser/editor split with Signal Knit update instructions modal over the page - [01:54:10](https://codex-workshop-followup.pages.dev/lesson-05.html): Code/editor workspace with design asset sheet visible at right - [01:58:55](https://codex-workshop-followup.pages.dev/lesson-05.html): Code/editor workspace with command palette or modal over design/code context - [01:59:55](https://codex-workshop-followup.pages.dev/lesson-05.html): Code/editor workspace with asset sheet and generated implementation text visible Reference ID: foundations-perspective-qa-and-testing Topic: Verification Sources: - [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html) --- # Fusion council decisions and evidence: practical reference ## Agent Setup Prompt ```text Set up the local Fusion / Model Council workflow for this repo. 1. Resolve the Fusion skill first. Prefer the bundled `skills/fusion/SKILL.md` when it exists; otherwise inspect `~/.agents/skills/fusion/SKILL.md`. Read the skill before changing config or running a panel. Do not substitute Oracle or another review tool for the local Fusion CLI. 2. Inspect the local Fusion checkout when available at `~/dev/fusion`. Check `README.md`, `package.json`, `src/fusion.js`, `fusion.config.example.json`, and the preset configs under `configs/` (`low.json`, `medium.json`, `high.json`, `quality.json`). Use the checkout to understand the installed CLI and presets; do not paste private config values into your report. 3. Verify the command wrappers are available: `command -v fusion fusion-med fusion-high` If a wrapper is missing, inspect `~/dev/fusion` and use the install/link path supported by that checkout, commonly `npm install` followed by `npm link`, then re-check the wrappers. Do not overwrite an existing unrelated global binary without reporting the conflict. 4. Run provider preflight before any real council run. Use the selected preset's list command, usually: `fusion-high --list-providers` For moderate planning, also check: `fusion-med --list-providers` Report the configured provider ids, unavailable providers, provider families, and whether the expected Claude/Opus slot is present. The point is a mixed council: OpenAI-style breadth, Anthropic-style critique, Z.ai/GLM or other coding-model pressure, plus any configured local specialists. Treat a missing Opus-class provider as a quality gap to report, not an automatic reason to invent a different workflow. 5. Use durable prompt files for real questions. Create or identify a repo-local prompt file and pass it with `--file`; do not send long briefs through fragile shell quoting. The prompt file should include the decision, relevant repo paths, constraints, commands already run, observed failures, candidate options, verification expectations, and the recommendation format needed. 6. Use `--dry-run` when provider ids, config paths, wrapper behavior, or output location are uncertain: `fusion-high --dry-run --file path/to/prompt.md` Then run the full configured panel only after the command shape is clear: `fusion-high --file path/to/prompt.md` 7. Let Fusion use its default session store unless a repo-local run directory is explicitly requested. Normal runs write under `~/.fusion/sessions/YYYY/MM/DD/<session-id>/` and update `~/.fusion/sessions.jsonl`. Expected artifacts include `run.json`, `panel-*.stdout.md`, `panel-*.stderr.txt`, `finalizer-report.json`, `summary.json`, and `final.md`. 8. Wait for terminal provider states before recommending anything. Valid terminal states include `ok`, `failed`, `timedOut`, `quotaLimited`, `spawnError`, and `interrupted`. While a run is active, use `panel-status.json` or Fusion heartbeat output for status only. Do not act from early `panel-*` artifacts. 9. Continue only after Fusion exits and both `summary.json` and `final.md` have been read, or after a real terminal failure or interruption has been captured. `summary.json` should provide run status, provider states, timings, and artifact paths. `final.md` should provide the council recommendation. 10. Handle quota and rate failures as degraded council input. If a provider hits quota, rate limit, usage limit, 429 exhaustion, timeout, or another terminal failure after artifacts exist, name the provider, preserve the remaining outputs, and continue with the available panel. If a Kimi provider fails preflight with `auth.login_required`, report the Kimi auth failure and rerun once with `--only` set to the other configured provider ids. Do not use `--only` for ordinary narrowing unless explicitly requested. 11. Keep the OpenRouter comparison precise. Local Fusion is a local CLI inspired by the panel, comparison, and final-answer pattern. It is not the hosted OpenRouter Fusion product. Treat OpenRouter and Fable claims as context, not proof that every local run improves every task. 12. Respect privacy boundaries. Do not paste tokens, cookies, API keys, key-helper output, full environment dumps, private endpoints, or raw private session artifacts. Summarize sensitive material with redacted facts, provider states, paths, consensus, disagreements, and decision-relevant excerpts only. 13. Report setup and run results plainly: skill path used, local checkout status, wrapper paths, provider preflight result, provider mix, Opus-class provider present or missing, prompt file path, dry-run result when used, session path, terminal provider states, whether `summary.json` and `final.md` were read, quota/rate handling, consensus, contradictions, unique insights, blind spots, synthesized recommendation, repo evidence used to accept or reject the council output, and verification commands to run next. 14. Treat Fusion output as advisory. Do not start implementation until the council output has been reconciled with repo evidence and the final engineering call is clear. ``` ## Big Idea Use Fusion when one model's answer is too small a surface area for the decision. Fusion is a local model council workflow. The win is not that models argue for sport. The win is that different model families and provider stacks make different mistakes, notice different risks, and bring different habits to the same bounded software question. Fusion runs those perspectives in parallel, then synthesizes the strongest result. ```text one hard software question -> several independent model/provider perspectives -> comparison of consensus, contradictions, unique insights, and blind spots -> finalizer / synthesizer -> fused recommendation -> human engineering judgment ``` It is not for tiny edits. ## Try This Now Use Fusion when multiple perspectives can improve the decision. Start with: `fusion-high --list-providers`. For a risky strategy choice, ask the agent to write a prompt file, run the full panel, then read `summary.json` and `final.md`. Good use: ```text Should this billing webhook fix use provider event ids, invoice locks, or a processing ledger? ``` Bad use: ```text Rename this variable. ``` Fusion is most useful when different strong models may notice different risks: - architecture review - risky implementation choice - auth/session design - billing webhook idempotency - migration plan - debugging strategy with multiple plausible causes - outage fallback plan - code review before touching a dangerous subsystem - choosing between good-looking plans where each has a hidden cost The point is not voting. The point is coverage. One model might catch the schema risk, another the rollout problem, another the security boundary, and another the boring test nobody wanted to write. The finalizer should turn that spread into one usable recommendation. ## Skill Reference Or Files To Inspect Bundled skill: ```text skills/fusion/SKILL.md ``` Common local source checkout: ```text ~/dev/fusion ``` Common local skill install: ```text ~/.agents/skills/fusion/SKILL.md ``` Local Fusion source files to inspect when needed: - `README.md` - `src/fusion.js` - `fusion.config.example.json` - `configs/low.json` - `configs/medium.json` - `configs/high.json` - `configs/quality.json` - `package.json` - `skills/fusion/SKILL.md` Keep command details in the skill. This file explains when to ask for Fusion, what the agent should do, and how to confirm the council output was actually used. ## When To Reach For This Use Fusion when the cost of a missed perspective is higher than the cost of a slower council run. | Use Fusion For | Why | | --- | --- | | checkout saved payment architecture | UI, data, auth, provider, and rollback risks need different reviewers | | billing webhook double-processing | one model may prefer event ids, another may notice invoice-level locking or ledger recovery | | auth/session refresh design | security, migration, UX, and rollback perspectives all matter | | model outage fallback | provider diversity keeps one model failure from defining the plan | | risky refactor | one model catches coupling, another catches migration order, another catches missing tests | | debugging plan | different models may pursue different plausible causes before the finalizer narrows them | | code review before implementation | the council can preserve minority warnings a single answer would flatten | Skip Fusion when: - the fix is obvious and tiny - one failing test names the exact bug - latency matters more than deliberation - the prompt has no concrete repo evidence - the task is mostly one narrow CLI lookup - you need Oracle with a large packed codebase context instead - you already have a chosen implementation and just need to type it Rule: ```text Use Fusion when the answer should come from a council, not a monologue. ``` ## How This Used To Work What you used to expect: ```text Ask one strong model for the answer and trust it if it sounds confident. ``` What this workflow gives you now: ```text Ask several independent models the same bounded software question, let each one take its own path, then synthesize the useful overlap and the useful surprises. ``` What you used to expect: ```text The first model that finishes can unblock the work. ``` What this workflow gives you now: ```text Partial provider output is not the answer. The answer starts after Fusion writes summary and final artifacts, because the value is in the comparison and synthesis. ``` ## The Mental Model ```text prompt file -> provider panel from different model families -> terminal provider states -> judge/finalizer comparison -> synthesis -> summary.json -> final.md -> implementation decision ``` | Concept | Meaning | | --- | --- | | prompt file | the bounded software question and evidence | | provider panel | OpenAI, Anthropic, Z.ai/GLM, Gemini, Kimi, OpenCode, Codex, Claude, Agy, or other configured voices running independent passes | | terminal state | each provider finished, failed, timed out, hit quota, or was interrupted | | finalizer | compares panel output, preserves consensus, contradictions, unique insights, and blind spots, then writes a final recommendation | | `summary.json` | run status, provider states, timings, artifact paths | | `final.md` | final council output to read before acting | | panel artifacts | useful but partial until the run is complete | Local Fusion shells out to local CLIs. It is not the same product as OpenRouter Fusion. ```text OpenRouter Fusion is a hosted product. Local Fusion is a local CLI implementation inspired by the same useful pattern: panel -> judge/finalizer -> synthesis -> final answer. ``` Local Fusion runs through configured local commands such as Codex, Claude, Agy, and OpenCode. Those commands can point at different model families and providers, including OpenAI, Anthropic, Z.ai/GLM, Gemini, Kimi, or other local account wiring. Provider availability, cost, quotas, auth, and data handling depend on the local CLI accounts and config. ## Origin Story To Keep Straight The practical origin story is: ```text Do not anchor serious work to one model's blind spots. Use multiple independent model/provider perspectives when the decision is expensive. Synthesize the council output so the final choice carries both consensus and caveats. ``` OpenRouter Fusion made the pattern visible in a hosted product: send one prompt to a panel of models, have a judge analyze the answers, then produce a fused response. OpenRouter reported that its Fusion tests on DRACO deep research tasks showed panels beating individual models, including budget panels approaching frontier-model performance. The Fable 5 availability shock sharpened a related lesson: model access can change. Hard-coded single-model workflows are brittle. A council or fallback pattern keeps important work moving when one model disappears, rate-limits, or underperforms. Careful wording: - Local Fusion is inspired by the OpenRouter-style panel and judge/finalizer pattern. - Local Fusion is not OpenRouter Fusion. - OpenRouter reported strong DRACO deep research results for its hosted Fusion product. Treat those numbers as useful context, not proof that every local Fusion run improves every task. ## What Local Fusion Does Local Fusion: - reads one prompt - runs a configured panel of local provider CLIs - lets different model/provider families inspect the same question independently - waits for provider terminal states - keeps partial panel artifacts - handles failed, timed-out, or quota-limited providers as degraded inputs when possible - runs a finalizer by default - preserves consensus, contradictions, unique insights, and blind spots when the finalizer has enough signal - writes run artifacts under the Fusion session store - records status in a compact index - leaves the final engineering decision to the local agent and human Current default run artifacts usually live under: ```text ~/.fusion/sessions/YYYY/MM/DD/<session-id>/ ``` Common artifacts: - `run.json` - `panel-*.stdout.md` - `panel-*.stderr.txt` - `finalizer-report.json` - `final.md` - `summary.json` Treat these as private by default. They may contain prompts, source snippets, commands, stdout, stderr, and model responses. ## Command Shape Ask the agent to use the skill. Do not memorize every flag. Common shape: ```bash fusion-high --list-providers fusion-high --dry-run --file path/to/prompt.md fusion-high --file path/to/prompt.md ``` Moderate planning: ```bash fusion-med --list-providers fusion-med --file path/to/prompt.md ``` Custom config: ```bash fusion --config path/to/fusion.config.json --file path/to/prompt.md ``` Long prompt rule: ```text Write a prompt file and use --file. ``` Do not make the agent jam a long implementation brief through fragile shell quoting. ## Prompt Shape Use a bounded software question, and name the perspectives you want the council to cover. ```markdown # Fusion Prompt ## Goal Choose the safest first implementation strategy for duplicate billing webhook processing. ## Council Perspectives - architecture reviewer: data model, boundaries, rollback - security reviewer: replay, idempotency, abuse cases - implementation reviewer: smallest patch and tests - operations reviewer: observability, retry behavior, degraded states ## Current Evidence - provider sends repeated paid invoice events - current handler sometimes processes the same invoice twice - suspected files: - src/billing/webhook.ts - src/billing/idempotency.ts - tests/billing/webhook.test.ts ## Candidate Strategies - provider event id guard - invoice-level processing lock - webhook processing ledger ## Constraints - do not change provider contract - avoid schema changes in the first pass unless the council strongly argues for it - preserve existing invoice state transitions - prefer the smallest patch that can be tested ## Verification - pnpm test billing-webhook -- --runInBand - pnpm build ## Ask Compare the strategies. Identify consensus, contradictions, unique insights, blind spots, missing tests, and the first shippable slice. Synthesize one recommendation that keeps the best argument from each useful perspective. End with rollback notes and the proof commands to run. ``` ## Ask The Agent This Use Fusion for architecture choice: ```text Use the $fusion skill. We need to choose the first implementation strategy for duplicate billing webhook processing. Write a prompt file that compares provider event id guard, invoice-level processing lock, and webhook processing ledger. First list providers and report the provider/model-family mix. Then dry-run the command, then run the full configured panel. Wait for Fusion to finish. Read summary.json and final.md before recommending a path. Show consensus, contradictions, unique insights, and blind spots. Do not implement until the synthesized council output has been reconciled with repo evidence. ``` Use Fusion for auth/session review: ```text Use the $fusion skill. Review the auth/session refresh-token rotation plan. The decision is whether to put rotation in middleware, the session store, or an explicit auth workflow boundary. Include likely files, constraints, migration risk, rollback risk, and verification commands in the prompt file. Run the full configured Fusion panel and wait for terminal provider states. Read the final artifacts. Then give me the synthesized recommendation, the minority warnings worth keeping, the recommended first slice, risks, and tests to run. ``` Use Fusion for a risky implementation review: ```text Use the $fusion skill before editing. The checkout saved payment method implementation touches auth, account billing, provider customer ids, and checkout UI state. Ask Fusion for independent critique from different model/provider perspectives: architecture, security, implementation, and operations. Ask for missing tests, privacy risk, rollback concerns, and the smallest safe patch. After Fusion finishes, show the council's consensus, contradictions, unique insights, blind spots, and synthesized recommendation before making any code change. ``` Use Fusion for model outage or fallback planning: ```text Use the $fusion skill. We need a fallback plan for a model-dependent feature so one model outage does not take down the app. Ask the council to compare hard-coded model slugs, provider-layer failover, model fallback chains, and local fallback behavior. Return the synthesized first shippable config change, the provider failure modes each model noticed, and what to log when a fallback fires. ``` ## What To Confirm / How To Know It Worked | Goal | Confirmation | | --- | --- | | skill invoked | agent explicitly says it used `$fusion` | | providers checked | agent ran `--list-providers` for the selected preset | | provider diversity named | agent reports the configured model/provider-family mix | | prompt was durable | prompt was saved to a file and passed with `--file` | | command shape checked | agent used `--dry-run` when provider ids or paths were uncertain | | full panel waited | agent waited until providers reached terminal states | | partial output not overused | agent did not act from only `panel-*.stdout.md` | | final artifacts read | agent read `summary.json` and `final.md` | | degraded providers handled | quota, timeout, or failure was reported without throwing away useful outputs | | synthesis preserved | final answer names consensus, contradictions, unique insights, and blind spots | | recommendation reconciled | final answer maps the synthesized recommendation back to repo evidence | | implementation stayed separate | code changes happened only after council output was read | | private output respected | session artifacts were not pasted wholesale | Strong proof phrases: - `Fusion session:` - `summary.json:` - `final.md:` - `providers:` - `provider mix:` - `terminal states:` - `consensus:` - `contradictions:` - `unique insights:` - `blind spots:` - `synthesized recommendation:` - `chosen path:` - `verification:` Weak proof phrases: - `One model said...` - `I saw enough from the first response...` - `Fusion is still running, but...` ## If It Goes Wrong Fusion is missing: ```bash command -v fusion fusion-med fusion-high ``` Then inspect the common local checkout: ```bash cd ~/dev/fusion npm install npm link fusion-med --list-providers ``` Provider auth fails: ```bash fusion-high --list-providers ``` Then check the provider CLI directly only when needed. Do not paste tokens, cookies, full environment output, or key-helper config. One provider hits quota: ```text Treat it as a degraded council run. ``` Expected behavior: - quota-limited provider is named - remaining provider outputs are preserved - Fusion continues when possible - final answer mentions the missing voice Do not restart the whole run just because one provider is unavailable. Agent acts before Fusion finishes: ```text Stop the implementation. ``` Ask for: ```text Show the Fusion session path, summary.json status, final.md, provider terminal states, and the council synthesis. Then continue from that output. ``` Only panel artifacts exist: ```text Panel artifacts are partial. ``` Wait for: - `summary.json` - `final.md` If the run was interrupted, use the interrupted summary as explicit failure evidence. Prompt was too vague: ```text Bad: Use Fusion to review auth. Better: Compare middleware-first, session-store-first, and explicit workflow boundary for refresh-token rotation. Include constraints, likely files, migration risk, rollback, and verification commands. ``` Prompt included secrets: ```text Stop. Rewrite the prompt. ``` Include file paths, redacted facts, and failure summaries instead of secrets. Final answer sounds confident but ignores the council: ```text Extract consensus, contradictions, unsupported claims, unique insights, blind spots, and the recommendation from the Fusion artifacts. Do not flatten the council into one confident paragraph. ``` ## Fusion Compared To Nearby Workflows | Workflow | Use It For | Not For | | --- | --- | --- | | Oracle PackX | huge code context and one expensive deep external review | quick local multi-model disagreement | | Section 6 variations | comparing generated implementation candidates | comparing independent model critiques | | Fusion | hard decision where disagreement matters | tiny changes or low-latency work | | Imps | one narrow tool-shaped lookup | architecture tradeoffs | | Agent markers | capturing a bounded debug moment | choosing among architectural strategies | ## References And Resources - Bundled skill: `skills/fusion/SKILL.md` - Common local source checkout: `~/dev/fusion` - Common local skill install: `~/.agents/skills/fusion/SKILL.md` - Common session store: `~/.fusion/sessions/YYYY/MM/DD/<session-id>/` - Common session index: `~/.fusion/sessions.jsonl` - OpenRouter Fusion product page: https://openrouter.ai/fusion - OpenRouter Fusion model page: https://openrouter.ai/openrouter/fusion - OpenRouter announcement: https://openrouter.ai/blog/announcements/fusion-beats-frontier/ - OpenRouter model-disappearance post: https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/ ## Operational boundaries - Hosted benchmark and model-availability anecdotes are attributed source context, not verified current product claims or proof of this local council’s quality. The saved local result must still survive repository verification. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-fusion-workflows-reference Topic: Verification Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Fusion council decisions and evidence: practice drills These exercises practice choosing when a local model council is worth the time, writing a bounded prompt, and confirming the council output was used before implementation. Use a real software project when possible. Keep the task narrow enough that the council can compare concrete choices. ## Exercise 1: Decide Whether Fusion Fits For each task, choose `use Fusion` or `skip Fusion`. | Task | Use / Skip | Why | | --- | --- | --- | | Choose between three billing webhook idempotency strategies | | | | Fix a typo in a button label | | | | Review auth/session refresh-token architecture before implementation | | | | Compare one model outage fallback plan against another | | | | Run one known formatter command | | | | Debug a bug with three plausible causes and incomplete logs | | | | Implement an exact requested API shape | | | | Review a risky checkout refactor before editing | | | Write: ```markdown # Fusion Fit - task: - decision: - why disagreement helps or does not help: - evidence available: - likely verification: - use Fusion? yes/no: ``` Rule: ```text If disagreement cannot change the decision, skip Fusion. ``` ## Exercise 2: Write The Decision Question Pick one software decision: - billing webhook idempotency - checkout saved payment method architecture - auth/session refresh-token rotation - model outage fallback - risky refactor plan Fill out: ```markdown # Decision Question ## Goal ## Candidate Strategies - - - ## Current Evidence - - - ## Constraints - - - ## Verification - - ## What Disagreement Should Decide ``` Check it: ```text Can a model reasonably disagree about this? Can repo evidence settle the disagreement? Can the final answer name a first implementation slice? ``` ## Exercise 3: Ask For `$fusion` Rewrite this vague request: ```text Use Fusion to review auth. ``` Into a strong request that asks the agent to: - use the `$fusion` skill - list providers first - write a prompt file - dry-run if command shape is uncertain - run the full configured panel - wait for terminal provider states - read `summary.json` and `final.md` - report consensus and disagreement - avoid implementation until after the council output is reconciled Draft: ```text Use the $fusion skill. ... ``` ## Exercise 4: Provider And Prompt Preflight Run or ask an agent to run: ```bash fusion-high --list-providers fusion-high --dry-run --file path/to/prompt.md ``` Fill out: ```markdown # Fusion Preflight - selected preset: - provider ids: - prompt file: - dry-run command: - output location: - any missing provider: - any auth warning: - safe to run? yes/no: ``` ## Exercise 5: Confirm The Agent Waited After a Fusion run, fill this out from the agent's report. ```markdown # Wait Check - Fusion session path: - summary.json read? yes/no: - final.md read? yes/no: - providers reached terminal states? yes/no: - terminal states: - - - - any quota-limited provider: - any failed or timed-out provider: - did the agent act from partial panel output? yes/no: - did implementation start only after final artifacts were read? yes/no: ``` Weak answer to reject: ```text One model had a good answer, so I continued. ``` Strong answer: ```text I waited for summary.json and final.md, then reconciled consensus and disagreement with repo evidence. ``` ## Exercise 6: Extract Council Disagreement From `final.md` or the agent summary, fill out: ```markdown # Council Review ## Consensus - - ## Disagreement | Topic | Position A | Position B | What evidence decides? | | --- | --- | --- | --- | | | | | | ## Hidden Risks - - ## Missing Tests - - ## Recommendation - chosen path: - why: - what to avoid: - rollback: ``` Question: ```text What did the disagreement change about the implementation plan? ``` ## Exercise 7: Turn Council Output Into A First Slice Write the implementation slice. ```markdown # First Slice After Fusion - chosen strategy: - files to inspect: - files likely to change: - tests to add or update: - verification command: - rollback note: - risks left for later: - what the council disagreed about: - why this slice is safe enough to try: ``` Do not include broad roadmap work unless it blocks the first slice. ## Exercise 8: Quota Or Provider Failure Drill Choose a recovery. | Failure | Recovery | | --- | --- | | one provider quota-limited | | | one provider timed out | | | `final.md` missing | | | `summary.json` says interrupted | | | prompt file accidentally included secrets | | | provider ids were wrong | | | agent used `--only` without being asked | | | agent started editing while Fusion was still running | | | final answer ignored disagreement | | Recovery options: - continue with degraded panel - name the missing voice - read partial artifacts only as failure evidence - rerun after fixing provider ids - rewrite prompt without secrets - ask for `summary.json` and `final.md` - stop implementation and wait - rerun full panel - extract consensus and contradictions Fill one out: ```markdown # Failure Recovery Detail - failure: - likely cause: - command or artifact to inspect: - recovery: - how to know recovery worked: ``` ## Exercise 9: Compare Fusion To Other Workflows Choose the right workflow. | Scenario | Workflow | Why | | --- | --- | --- | | broad repo architecture review needing packed code context | | | | compare three generated checkout UI candidates | | | | choose idempotency strategy before implementation | | | | capture exact browser bug moment | | | | find code paths with one search tool | | | | convert a screen recording into repro steps | | | | compose a careful prompt before launch | | | Options: - Oracle PackX - Prompt Builder - Section 6 variations - Fusion - Video workflow - Agent markers - Imps ## Exercise 10: Final Check Use this checklist before trusting the result. ```markdown # Final Fusion Check - Fusion was the right tool? yes/no: - skill was invoked? yes/no: - provider list checked? yes/no: - prompt file written? yes/no: - dry-run used when uncertain? yes/no: - full configured panel run? yes/no: - providers reached terminal states? yes/no: - summary.json read? yes/no: - final.md read? yes/no: - consensus captured? yes/no: - disagreement captured? yes/no: - recommendation reconciled with repo evidence? yes/no: - verification command named? yes/no: - private artifacts protected? yes/no: - ready for implementation? yes/no: ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-fusion-workflows-practice Topic: Verification Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Human testimony joined to runtime evidence Capture the moment of surprise with a bounded redacted trail and discriminate between hypotheses before changing code. ## Related working material - [Human testimony joined to runtime evidence — prompts and exercises](/topics/factory-debug-markers-practice/) - [Human testimony joined to runtime evidence — questions and tradeoffs](/topics/factory-debug-markers-questions/) - [Human testimony joined to runtime evidence — worked example](/topics/factory-debug-markers-worked-example/) ## TL;DR - A ~150-line, dependency-free recorder (`agent-markers.js`, printed complete below) logs clicks, fetches, console lines, and errors into a bounded ring buffer in any web app. - One keystroke pins one sentence of human testimony to the nearest events; one call exports a redacted JSON payload safe to paste anywhere — no bodies, no tokens, no raw user text. - The move: mark at the moment of surprise, render the export into a debug packet, and make the agent state a hypothesis before it reads any code. Have your agent set this up — paste this into it: ``` text Fetch https://mindful-mango-accy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## The signal you normally throw away You are testing an app. Something feels off — a stale value, a success message you do not believe. Usually that judgment evaporates: hours later someone asks for a bug report, and you reconstruct the moment from memory, losing the timing, the order of actions, and most of the value. The pattern this session builds on calls human intent “the missing signal” in agent debugging and records it the moment it occurs. This is not a paper idea. A production desktop app we studied ships the same move: a hotkey mints a marker id, captures a screenshot, writes a `dev_marker` log event, and opens a note where the tester types one explanation — all joined by the same id, with a log CLI whose `--marker` flag slices the session for agents. The design rule that makes it work: capture happens *during* the surprise, one keystroke and one sentence. Anything heavier and nobody uses it at the moment that matters. A capture has two parts that answer different questions. A **marker** says *why this moment deserves attention*; a **trail** says *how the tester arrived there*. Testimony alone tells an agent what to look for but not when; a trail alone is complete but unweighted. Paired, the testimony points into the trail, and the trail grounds the testimony in ordered facts. Treat the marker as a search warrant, not a verdict. ## One captured failure, read cold The workshop demo plants a bug worth marking: a notes app goes offline, reconnects, and saves. The server rotated its session token during the reconnect; the client kept its stale copy; the save handler treats any status below 500 as success. The user sees **“Saved ”**. The server said 401. We drove that path in a real browser, pressed mark, and typed: *“It said Saved but my note never reached the server — this happened right after I reconnected.”* Seven consecutive lines of the captured trail, exactly as the packet renderer printed them: ``` text - [seq 3 · t+17397ms] click: click <button#save> "Save note" - [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms] - [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable - [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect" - [seq 7 · t+18436ms] console: console.log: reconnected: session restored - [seq 8 · t+18909ms] click: click <button#save> "Save note" - [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms] ``` Read it top to bottom and name a hypothesis before anyone tells you: a network failure, a “session restored” log, then a 401 on the very next save under a visible “Saved ”. If you reached “the reconnect invalidated something the client still holds,” a nine-line slice just did what a full log dump rarely does — and an agent reads it the same way you just did. ## What the capture leaves out The moment you say “capture the entire state of the app,” you have a privacy decision, because the payload will leave your machine — pasted into an agent, attached to a ticket, shared in chat. Decide the exclusions before the first capture, write them into the payload itself, and accept the narrower evidence. The demo’s export embeds exactly this policy, so every reader can audit what was withheld: ``` text { "storageValues": "excluded", "requestBodies": "excluded", "responseBodies": "excluded", "userText": "preview+length only" } ``` An external architecture review of the production system pushed the same rule harder: order events by a sequence counter, join records by session and marker ids, and store user input as preview, hash, and length — never raw. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one. The handoff needs a fence too. A weak handoff pastes a log dump and asks “what’s wrong?”, inviting confident guessing over unweighted noise. A strong handoff gives less data and more structure — what the human saw, what the system recorded, what was withheld, and what kind of answer is allowed. That is why the packet ends with a claims boundary, and why the first prompt above demands a hypothesis before code: the agent’s draft arrives labeled as a draft, and a person verifies it against the running app. ## Appendix ### Limits & caveats - Testimony is not diagnosis; context is not proof. The trail shows what was captured, not everything that happened — session metadata does not prove a defect, and testimony does not prove cause. - The captured failure here is a bug we planted ourselves. The loop is demonstrated end to end, but its yield on organic bugs is untested on this page. - Redaction trades fidelity for safety. A capture without request bodies cannot settle every question; sometimes the correct next step is a targeted, consented follow-up capture. - `prompt()` blocks automation. Scripted browsers should call `window.__AGENT_MARKERS__.mark(label, note)` from the console instead of the hotkey. - On macOS, Cmd+M can collide with the browser’s minimize shortcut; a page button or the console call is the reliable path. - The ring buffer is in-memory only — a reload wipes it. Export before navigating away. Screenshots are `"unavailable"` in the plain-browser recorder; the production system captures them via native APIs. - If your app installs its own `fetch` wrapper (mocks, auth shims), install it before `AgentMarkers.start()` so wrapped calls land in the trail. ## Operating practice ### Attach testimony to runtime evidence #### What to notice Give a debugging agent the exact moment of failure, the **human-observed symptom**, and a **bounded event trail**. #### Try this Reproduce one bug, add one plain-language marker when behavior becomes wrong, and export a redacted packet for ranked hypotheses. > “I see this, and I wanna talk about that.” John Lindquist · [02:22:16](https://proud-anchor-53zn.here.now/watch.html?t=8536#recording-player) #### Concept The prepared Markers material combines human testimony with nearby console, fetch, error, and click events. That makes the next diagnostic question smaller and more discriminating. #### Reflection This module was prepared after the workshop and was not taught as a dedicated recorded section. **Recording evidence:** prepared follow-up grounded in related recorded evidence. > “A lot of us spend time trying to describe bugs instead of just recording ourselves using the product.” John Lindquist · [05:21:57](https://proud-anchor-53zn.here.now/watch.html?t=19317#recording-player) [Open Debugging with Markers](https://mindful-mango-accy.here.now/) [Recording boundary](https://proud-anchor-53zn.here.now/watch.html#q4-markers-follow-up) Reference ID: factory-debug-markers Topic: Verification Sources: - [Human testimony joined to runtime evidence](https://mindful-mango-accy.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q4-markers-follow-up) --- # Human testimony joined to runtime evidence — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for human testimony joined to runtime evidence. ## Quick start Runs from any empty directory — needs only `curl` and Node 18+. It pulls the recorder, the packet renderer, and a real captured session from this site, then prints the agent-ready debug packet. ``` text mkdir -p markers-quickstart && cd markers-quickstart curl -sO https://mindful-mango-accy.here.now/agent-markers.js curl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs curl -sO https://mindful-mango-accy.here.now/sample-session.json node make-agent-packet.mjs sample-session.json ``` ## Prompt library ### Hand an agent a debug packet - Agent: any coding agent - Working directory: anywhere - Expected result: a one-sentence hypothesis, then a reproducible scenario with unproven parts flagged ``` text Here is a debug packet captured from a live session of my app. Before you read any code: 1. Read the human testimony, then the evidence trail in seq order. 2. State your single most likely hypothesis for the failure, in one sentence. 3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet. 4. Label anything the trail cannot prove as "hypothesis — needs verification". Testimony is not diagnosis. Context is not proof. --- PACKET --- [paste the output of: node scripts/make-agent-packet.mjs your-session.json] ``` ### Grade your capture: can it be read cold? - Agent: any coding agent - Working directory: your project, with a fresh export on disk - Expected result: a stated hypothesis, or the one knob to turn first ``` text Here is a marker-session export from my app (JSON, schemaVersion 1). Render it with scripts/make-agent-packet.mjs and read the packet cold — no source code, no other context. Answer two things: 1. Can you state one specific hypothesis from the testimony and trail alone? State it. 2. If you cannot, tell me which single change to make first: mark closer to the failure, raise nearbyEventLimit, or add one missing event type to the recorder. ``` ### Write the redaction policy first - Agent: your coding agent - Working directory: your project, before any recording code lands - Expected result: an exclusion list for your app plus a redaction JSON block for every export ``` text I'm adding just-in-time debug capture (markers plus an event trail) to this app. Before any recording code lands, draft our redaction policy: list every category of data a capture must NEVER contain (request/response bodies, tokens, storage values, raw user text, plus anything specific to this codebase), and produce a redaction JSON block to embed verbatim in every export so readers can audit what was withheld. Default user text to "preview+length only". ``` ## Set it up (agent guide) 1. Add the recorder to your app as `<static-dir>/agent-markers.js`. This is the whole thing — no dependencies, no build step. (Same bytes as [agent-markers.js](https://mindful-mango-accy.here.now/agent-markers.js) on this site.) ``` text /** * agent-markers.js — a tiny, dependency-free "press a button, capture the moment" recorder. * * Pattern: a MARKER is timestamped human testimony ("this moment matters, here's why"). * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there. * Export = bounded, redacted payload you can hand to an agent as a debug packet. * * Deliberately NOT captured: storage values, request/response bodies, raw input text. * Testimony is not diagnosis. Context is not proof. */ (function (global) { "use strict"; const state = { running: false, sessionId: null, startedAtIso: null, startedAtMs: 0, seq: 0, events: [], markers: [], maxEvents: 200, nearbyEventLimit: 12, restoreFns: [], }; function now() { return Math.round(performance.now() - state.startedAtMs); } function preview(text, max = 80) { const s = String(text ?? ""); return { preview: s.length > max ? s.slice(0, max) + "…" : s, length: s.length, truncated: s.length > max, }; } function record(type, data) { if (!state.running) return null; const event = { id: "evt-" + (++state.seq), seq: state.seq, t: now(), type, data }; state.events.push(event); if (state.events.length > state.maxEvents) state.events.shift(); return event; } function patchConsole() { ["log", "warn", "error"].forEach((level) => { const original = console[level]; console[level] = function (...args) { record("console", { level, message: preview(args.map(String).join(" ")) }); return original.apply(console, args); }; state.restoreFns.push(() => (console[level] = original)); }); } function patchFetch() { const original = global.fetch; global.fetch = async function (input, init) { const url = typeof input === "string" ? input : input.url; const method = (init && init.method) || "GET"; const started = now(); try { const res = await original.apply(global, arguments); record("fetch", { method, url, status: res.status, ok: res.ok, ms: now() - started }); return res; } catch (error) { record("fetch", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) }); throw error; } }; state.restoreFns.push(() => (global.fetch = original)); } function patchErrors() { const onError = (event) => record("error", { message: preview(event.message || String(event.reason || "unknown")) }); global.addEventListener("error", onError); global.addEventListener("unhandledrejection", onError); state.restoreFns.push(() => { global.removeEventListener("error", onError); global.removeEventListener("unhandledrejection", onError); }); } function patchClicks() { const onClick = (event) => { const el = event.target.closest("button, a, [data-action]") || event.target; record("click", { tag: el.tagName.toLowerCase(), id: el.id || null, action: el.dataset ? el.dataset.action || null : null, text: preview(el.textContent && el.textContent.trim(), 40), }); }; document.addEventListener("click", onClick, true); state.restoreFns.push(() => document.removeEventListener("click", onClick, true)); } const AgentMarkers = { start(options = {}) { if (state.running) return this; state.sessionId = options.sessionId || "session-" + Date.now().toString(36); state.startedAtIso = new Date().toISOString(); state.startedAtMs = performance.now(); state.maxEvents = options.maxEvents || 200; state.nearbyEventLimit = options.nearbyEventLimit || 12; state.seq = 0; state.events = []; state.markers = []; state.running = true; patchConsole(); patchFetch(); patchErrors(); patchClicks(); if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers; record("session", { note: "recording started", app: options.app || "unknown" }); return this; }, /** Human presses the button: timestamped testimony + pointers into the trail. */ mark(label, note) { if (!state.running) throw new Error("AgentMarkers not started"); const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id); const marker = { id: "mrk-" + (state.markers.length + 1) + "-" + Date.now().toString(36), seq: ++state.seq, t: now(), label: label || "unlabeled", note: note || "", nearbyEventIds: nearby, screenshot: "unavailable", // browser demo: no screenshot API without permissions }; state.markers.push(marker); record("marker", { markerId: marker.id, label: marker.label }); return marker; }, record(type, data) { return record("manual", { type, ...data }); }, /** Bounded, redacted payload — everything an agent gets, nothing more. */ exportSession() { return { schemaVersion: 1, sessionId: state.sessionId, startedAt: state.startedAtIso, exportedAt: new Date().toISOString(), userAgent: navigator.userAgent, markers: state.markers, events: state.events, redaction: { storageValues: "excluded", requestBodies: "excluded", responseBodies: "excluded", userText: "preview+length only", }, }; }, stop() { state.restoreFns.forEach((restore) => restore()); state.restoreFns = []; state.running = false; return this; }, }; if (typeof module !== "undefined" && module.exports) module.exports = AgentMarkers; global.AgentMarkers = AgentMarkers; })(typeof window !== "undefined" ? window : globalThis); ``` 2. Boot it with `<static-dir>/markers-boot.js` — starts recording, binds Ctrl/Cmd+M to “mark”, and exposes `exportMarkers()` for downloading the capture. Replace `"my-app"` with your app’s name. ``` text /* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts. Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */ AgentMarkers.start({ app: "my-app" }); // replace "my-app" with your app's name // One keystroke at the moment of surprise: one sentence of testimony. window.addEventListener("keydown", (e) => { if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "m") { e.preventDefault(); const note = prompt("Why does this moment matter? (one sentence — it travels with the capture)"); if (note !== null) console.log("marked:", AgentMarkers.mark("user-flag", note).id); } }); // Call exportMarkers() from the console, or wire it to a button. window.exportMarkers = () => { const session = AgentMarkers.exportSession(); const blob = new Blob([JSON.stringify(session, null, 2)], { type: "application/json" }); const a = Object.assign(document.createElement("a"), { href: URL.createObjectURL(blob), download: session.sessionId + ".json", }); a.click(); URL.revokeObjectURL(a.href); return session.sessionId + ".json"; }; ``` Load both before your app’s own scripts: `<script src="agent-markers.js"></script>` then `<script src="markers-boot.js"></script>`. 3. Save the packet renderer as `scripts/make-agent-packet.mjs` in your project — it turns any export into the markdown packet the prompts above expect. ``` text #!/usr/bin/env node /** * make-agent-packet.mjs — turn a marker-session export into a bounded agent debug packet. * * Usage: * node scripts/make-agent-packet.mjs <session.json> [marker-id] * * Emits markdown on stdout: human testimony, the nearby evidence slice, redaction * receipts, and an explicit claims boundary — ready to paste into any agent. */ import { readFileSync } from "node:fs"; const [file, markerArg] = process.argv.slice(2); if (!file) { console.error("usage: node scripts/make-agent-packet.mjs <session.json> [marker-id]"); process.exit(1); } const session = JSON.parse(readFileSync(file, "utf8")); if (session.schemaVersion !== 1) { console.error(`unsupported schemaVersion: ${session.schemaVersion}`); process.exit(1); } const marker = markerArg ? session.markers.find((m) => m.id === markerArg) : session.markers.at(-1); if (!marker) { console.error(markerArg ? `marker '${markerArg}' not found` : "no markers in session"); process.exit(1); } const nearbyIds = new Set(marker.nearbyEventIds ?? []); const nearby = session.events.filter((e) => nearbyIds.has(e.id)); const fmt = (e) => { const d = e.data ?? {}; switch (e.type) { case "fetch": return `${d.method} ${d.url} → ${d.status ?? "NETWORK-ERROR"}${d.error ? ` (${d.error.preview ?? d.error})` : ""} [${d.ms}ms]`; case "console": return `console.${d.level}: ${d.message?.preview ?? ""}`; case "click": return `click <${d.tag}${d.id ? `#${d.id}` : ""}> "${d.text?.preview ?? ""}"`; case "error": return `error: ${d.message?.preview ?? ""}`; default: return JSON.stringify(d); } }; const lines = []; lines.push(`# Debug packet — marker ${marker.id}`); lines.push(""); lines.push(`- session: ${session.sessionId} (started ${session.startedAt})`); lines.push(`- marker time: t+${marker.t}ms · label: ${marker.label}`); lines.push(`- screenshot: ${marker.screenshot ?? "unavailable"}`); lines.push(""); lines.push("## Human testimony (why this moment matters)"); lines.push(""); lines.push(`> ${marker.note || "(no explanation recorded)"}`); lines.push(""); lines.push(`## Evidence trail (${nearby.length} events nearest the marker, seq order)`); lines.push(""); for (const e of nearby) lines.push(`- [seq ${e.seq} · t+${e.t}ms] ${e.type}: ${fmt(e)}`); lines.push(""); lines.push("## Redaction receipts"); lines.push(""); for (const [k, v] of Object.entries(session.redaction ?? {})) lines.push(`- ${k}: ${v}`); lines.push(""); lines.push("## Task for the agent"); lines.push(""); lines.push("Draft a reproducible scenario (preconditions, steps, expected, observed) that"); lines.push("explains the testimony using ONLY the evidence above. Flag anything the trail"); lines.push("cannot prove as a hypothesis needing verification."); lines.push(""); lines.push("## Claims boundary"); lines.push(""); lines.push("Testimony is not diagnosis. Context is not proof. The trail shows what was"); lines.push("captured, not everything that happened."); console.log(lines.join("\n")); ``` **Success check:** render the real captured session from this site, then read the packet cold and state a hypothesis before looking at any code. ``` text curl -sO https://mindful-mango-accy.here.now/sample-session.json node scripts/make-agent-packet.mjs sample-session.json ``` ``` text # Debug packet — marker <demo-marker> - session: <demo-session> (started the recorded snapshot) - marker time: t+26900ms · label: user-flag - screenshot: unavailable ## Human testimony (why this moment matters) > It said Saved but my note never reached the server — this happened right after I reconnected. ## Evidence trail (9 events nearest the marker, seq order) - [seq 1 · t+0ms] session: {"note":"recording started","app":"field-notes-demo"} - [seq 2 · t+16914ms] click: click <button#toggle-net> "Go offline" - [seq 3 · t+17397ms] click: click <button#save> "Save note" - [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms] - [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable - [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect" - [seq 7 · t+18436ms] console: console.log: reconnected: session restored - [seq 8 · t+18909ms] click: click <button#save> "Save note" - [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms] … ``` You pass when a reader — human or agent — gets from that packet alone to something like “the reconnect rotated or invalidated a session credential the client still holds.” Then verify the loop in your own app: press Ctrl/Cmd+M, type a sentence, run `exportMarkers()` in the console, and confirm the downloaded JSON has your marker and a `redaction` block. ## Complete reusable setup contract ## Debugging with Markers — agent setup guide Following this file sets up: a just-in-time debug-capture loop in the user's web app — a ~150-line dependency-free recorder (semantic event trail + human markers), a mark hotkey, a redacted JSON export, and a renderer that turns exports into agent-ready debug packets. Placeholders used below: `<project-root>` = the project you are working in; `<static-dir>` = wherever that app serves static JS from (often `public/` or the app's HTML directory). All other paths are literal. Human companion pages on this site (for your user, not needed to execute this file): the section guide at https://mindful-mango-accy.here.now/, a Session Replay of the captured run this file's success check reproduces at https://mindful-mango-accy.here.now/replay.html, and a Q&A Dialogue at https://mindful-mango-accy.here.now/dialogue.html. ## Prerequisites Check each before starting: ```bash node --version # need v18 or newer curl --version # used only to download the sample session in the success check ``` Expected: Node 18+ and curl present. If a tool is missing, stop and tell your user what to install. ## Steps 1. Create `<static-dir>/agent-markers.js` with exactly this content (same bytes as https://mindful-mango-accy.here.now/agent-markers.js — you may download it instead of typing it): ```js /** * agent-markers.js — a tiny, dependency-free "press a button, capture the moment" recorder. * * Pattern: a MARKER is timestamped human testimony ("this moment matters, here's why"). * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there. * Export = bounded, redacted payload you can hand to an agent as a debug packet. * * Deliberately NOT captured: storage values, request/response bodies, raw input text. * Testimony is not diagnosis. Context is not proof. */ (function (global) { "use strict"; const state = { running: false, sessionId: null, startedAtIso: null, startedAtMs: 0, seq: 0, events: [], markers: [], maxEvents: 200, nearbyEventLimit: 12, restoreFns: [], }; function now() { return Math.round(performance.now() - state.startedAtMs); } function preview(text, max = 80) { const s = String(text ?? ""); return { preview: s.length > max ? s.slice(0, max) + "…" : s, length: s.length, truncated: s.length > max, }; } function record(type, data) { if (!state.running) return null; const event = { id: "evt-" + (++state.seq), seq: state.seq, t: now(), type, data }; state.events.push(event); if (state.events.length > state.maxEvents) state.events.shift(); return event; } function patchConsole() { ["log", "warn", "error"].forEach((level) => { const original = console[level]; console[level] = function (...args) { record("console", { level, message: preview(args.map(String).join(" ")) }); return original.apply(console, args); }; state.restoreFns.push(() => (console[level] = original)); }); } function patchFetch() { const original = global.fetch; global.fetch = async function (input, init) { const url = typeof input === "string" ? input : input.url; const method = (init && init.method) || "GET"; const started = now(); try { const res = await original.apply(global, arguments); record("fetch", { method, url, status: res.status, ok: res.ok, ms: now() - started }); return res; } catch (error) { record("fetch", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) }); throw error; } }; state.restoreFns.push(() => (global.fetch = original)); } function patchErrors() { const onError = (event) => record("error", { message: preview(event.message || String(event.reason || "unknown")) }); global.addEventListener("error", onError); global.addEventListener("unhandledrejection", onError); state.restoreFns.push(() => { global.removeEventListener("error", onError); global.removeEventListener("unhandledrejection", onError); }); } function patchClicks() { const onClick = (event) => { const el = event.target.closest("button, a, [data-action]") || event.target; record("click", { tag: el.tagName.toLowerCase(), id: el.id || null, action: el.dataset ? el.dataset.action || null : null, text: preview(el.textContent && el.textContent.trim(), 40), }); }; document.addEventListener("click", onClick, true); state.restoreFns.push(() => document.removeEventListener("click", onClick, true)); } const AgentMarkers = { start(options = {}) { if (state.running) return this; state.sessionId = options.sessionId || "session-" + Date.now().toString(36); state.startedAtIso = new Date().toISOString(); state.startedAtMs = performance.now(); state.maxEvents = options.maxEvents || 200; state.nearbyEventLimit = options.nearbyEventLimit || 12; state.seq = 0; state.events = []; state.markers = []; state.running = true; patchConsole(); patchFetch(); patchErrors(); patchClicks(); if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers; record("session", { note: "recording started", app: options.app || "unknown" }); return this; }, /** Human presses the button: timestamped testimony + pointers into the trail. */ mark(label, note) { if (!state.running) throw new Error("AgentMarkers not started"); const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id); const marker = { id: "mrk-" + (state.markers.length + 1) + "-" + Date.now().toString(36), seq: ++state.seq, t: now(), label: label || "unlabeled", note: note || "", nearbyEventIds: nearby, screenshot: "unavailable", // browser demo: no screenshot API without permissions }; state.markers.push(marker); record("marker", { markerId: marker.id, label: marker.label }); return marker; }, record(type, data) { return record("manual", { type, ...data }); }, /** Bounded, redacted payload — everything an agent gets, nothing more. */ exportSession() { return { schemaVersion: 1, sessionId: state.sessionId, startedAt: state.startedAtIso, exportedAt: new Date().toISOString(), userAgent: navigator.userAgent, markers: state.markers, events: state.events, redaction: { storageValues: "excluded", requestBodies: "excluded", responseBodies: "excluded", userText: "preview+length only", }, }; }, stop() { state.restoreFns.forEach((restore) => restore()); state.restoreFns = []; state.running = false; return this; }, }; if (typeof module !== "undefined" && module.exports) module.exports = AgentMarkers; global.AgentMarkers = AgentMarkers; })(typeof window !== "undefined" ? window : globalThis); ``` 2. Create `<static-dir>/markers-boot.js` with exactly this content, replacing only `"my-app"` with the app's real name: ```js /* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts. Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */ AgentMarkers.start({ app: "my-app" }); // replace "my-app" with your app's name // One keystroke at the moment of surprise: one sentence of testimony. window.addEventListener("keydown", (e) => { if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "m") { e.preventDefault(); const note = prompt("Why does this moment matter? (one sentence — it travels with the capture)"); if (note !== null) console.log("marked:", AgentMarkers.mark("user-flag", note).id); } }); // Call exportMarkers() from the console, or wire it to a button. window.exportMarkers = () => { const session = AgentMarkers.exportSession(); const blob = new Blob([JSON.stringify(session, null, 2)], { type: "application/json" }); const a = Object.assign(document.createElement("a"), { href: URL.createObjectURL(blob), download: session.sessionId + ".json", }); a.click(); URL.revokeObjectURL(a.href); return session.sessionId + ".json"; }; ``` 3. Load both files in the app's page BEFORE the app's own scripts (and before any code that replaces `window.fetch` — app-level fetch wrappers such as mocks or auth shims must be installed before `AgentMarkers.start()` runs so their calls land in the trail): ```html <script src="agent-markers.js"></script> <script src="markers-boot.js"></script> ``` 4. Create `<project-root>/scripts/make-agent-packet.mjs` with exactly this content (same bytes as https://mindful-mango-accy.here.now/make-agent-packet.mjs): ```js #!/usr/bin/env node /** * make-agent-packet.mjs — turn a marker-session export into a bounded agent debug packet. * * Usage: * node scripts/make-agent-packet.mjs <session.json> [marker-id] * * Emits markdown on stdout: human testimony, the nearby evidence slice, redaction * receipts, and an explicit claims boundary — ready to paste into any agent. */ import { readFileSync } from "node:fs"; const [file, markerArg] = process.argv.slice(2); if (!file) { console.error("usage: node scripts/make-agent-packet.mjs <session.json> [marker-id]"); process.exit(1); } const session = JSON.parse(readFileSync(file, "utf8")); if (session.schemaVersion !== 1) { console.error(`unsupported schemaVersion: ${session.schemaVersion}`); process.exit(1); } const marker = markerArg ? session.markers.find((m) => m.id === markerArg) : session.markers.at(-1); if (!marker) { console.error(markerArg ? `marker '${markerArg}' not found` : "no markers in session"); process.exit(1); } const nearbyIds = new Set(marker.nearbyEventIds ?? []); const nearby = session.events.filter((e) => nearbyIds.has(e.id)); const fmt = (e) => { const d = e.data ?? {}; switch (e.type) { case "fetch": return `${d.method} ${d.url} → ${d.status ?? "NETWORK-ERROR"}${d.error ? ` (${d.error.preview ?? d.error})` : ""} [${d.ms}ms]`; case "console": return `console.${d.level}: ${d.message?.preview ?? ""}`; case "click": return `click <${d.tag}${d.id ? `#${d.id}` : ""}> "${d.text?.preview ?? ""}"`; case "error": return `error: ${d.message?.preview ?? ""}`; default: return JSON.stringify(d); } }; const lines = []; lines.push(`# Debug packet — marker ${marker.id}`); lines.push(""); lines.push(`- session: ${session.sessionId} (started ${session.startedAt})`); lines.push(`- marker time: t+${marker.t}ms · label: ${marker.label}`); lines.push(`- screenshot: ${marker.screenshot ?? "unavailable"}`); lines.push(""); lines.push("## Human testimony (why this moment matters)"); lines.push(""); lines.push(`> ${marker.note || "(no explanation recorded)"}`); lines.push(""); lines.push(`## Evidence trail (${nearby.length} events nearest the marker, seq order)`); lines.push(""); for (const e of nearby) lines.push(`- [seq ${e.seq} · t+${e.t}ms] ${e.type}: ${fmt(e)}`); lines.push(""); lines.push("## Redaction receipts"); lines.push(""); for (const [k, v] of Object.entries(session.redaction ?? {})) lines.push(`- ${k}: ${v}`); lines.push(""); lines.push("## Task for the agent"); lines.push(""); lines.push("Draft a reproducible scenario (preconditions, steps, expected, observed) that"); lines.push("explains the testimony using ONLY the evidence above. Flag anything the trail"); lines.push("cannot prove as a hypothesis needing verification."); lines.push(""); lines.push("## Claims boundary"); lines.push(""); lines.push("Testimony is not diagnosis. Context is not proof. The trail shows what was"); lines.push("captured, not everything that happened."); console.log(lines.join("\n")); ``` ## Success check Run from `<project-root>`: ```bash curl -sO https://mindful-mango-accy.here.now/sample-session.json node scripts/make-agent-packet.mjs sample-session.json ``` Expected observable result: a markdown debug packet beginning `# Debug packet — marker <demo-marker>`, containing the testimony line `> It said Saved but my note never reached the server — this happened right after I reconnected.`, a 9-event evidence trail whose last line is `- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]`, four redaction receipts, a task section, and a claims boundary. Then perform the cold-read check: read that packet with NO other context (do not open the recorder source or this page) and state one specific hypothesis for the failure. A passing hypothesis names the mechanism, e.g. "the reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success." Finally, verify the loop live in the user's app: open it in a browser, press Ctrl/Cmd+M (or run `window.__AGENT_MARKERS__.mark("user-flag", "test marker")` in the console — `prompt()` blocks automation), then run `exportMarkers()` in the console. Confirm a `session-*.json` file downloads with `markers.length >= 1` and a `redaction` block. Report to your user: what you set up, the packet output of the success check, your cold-read hypothesis, and anything you had to adapt. ## Notes for agents - `prompt()` blocks scripted browsers. In automation, call `window.__AGENT_MARKERS__.mark(label, note)` instead of the Ctrl/Cmd+M hotkey. - On macOS, Cmd+M can collide with the browser's minimize shortcut. The console call or an on-page button wired to the same `dropMarker` logic is the reliable path. - The event ring buffer is in-memory only — a page reload wipes it. Export before navigating or reloading. - `make-agent-packet.mjs` exits with `unsupported schemaVersion` unless the export has `schemaVersion: 1`. Exports from this recorder always do; hand-edited files may not. - The export deliberately excludes storage values, request/response bodies, and raw user text (preview+length only). Do not "improve" it by adding them — the redaction block inside every export is the audit trail readers rely on. - The recorder caps the trail at 200 events and pins the 12 nearest event ids to each marker (`maxEvents` / `nearbyEventLimit` options on `AgentMarkers.start`). If packets read too thin, raise `nearbyEventLimit` before adding new event types. Reference ID: factory-debug-markers-practice Topic: Verification Sources: - [Human testimony joined to runtime evidence](https://mindful-mango-accy.here.now/) - [Public setup contract](https://mindful-mango-accy.here.now/agent.md) --- # Human testimony joined to runtime evidence — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. Isn’t this just logging? I already have logs. Logs are complete but unweighted — nothing in fifty thousand lines says *this* is the moment that mattered. When a person watching the app says "that was wrong," that sentence is the highest-value debugging signal we have, and we normally throw it away. A marker makes it a first-class, timestamped artifact: one sentence of testimony, pinned to the ids of the nearest events. Here's the one from this site's real capture, exactly as the packet renders it: ``` text ## Human testimony (why this moment matters) > It said Saved but my note never reached the server — this happened right after I reconnected. ``` The testimony points into the trail; the trail grounds the testimony in ordered facts. Neither alone does the job. Will anyone actually press the button? My users don’t even file bug reports. That's the design constraint the whole thing is built around: one keystroke, one sentence, *during* the surprise. No form, no repro steps demanded. Anything heavier and nobody uses it at the moment that matters. The entire user-facing surface is this boot file — Ctrl/Cmd+M to mark, one console call to export: ``` text /* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts. Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */ AgentMarkers.start({ app: "my-app" }); // replace "my-app" with your app's name // One keystroke at the moment of surprise: one sentence of testimony. window.addEventListener("keydown", (e) => { if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "m") { e.preventDefault(); const note = prompt("Why does this moment matter? (one sentence — it travels with the capture)"); if (note !== null) console.log("marked:", AgentMarkers.mark("user-flag", note).id); } }); // Call exportMarkers() from the console, or wire it to a button. window.exportMarkers = () => { const session = AgentMarkers.exportSession(); const blob = new Blob([JSON.stringify(session, null, 2)], { type: "application/json" }); const a = Object.assign(document.createElement("a"), { href: URL.createObjectURL(blob), download: session.sessionId + ".json", }); a.click(); URL.revokeObjectURL(a.href); return session.sessionId + ".json"; }; ``` You’re recording my users’ clicks and network calls. Legal will kill this. Only if you capture what legal is worried about — so don't. Decide the exclusions *before* the first capture, write them into the payload itself, and accept the narrower evidence. Every export from the recorder carries its own receipts: ``` text ## Redaction receipts - storageValues: excluded - requestBodies: excluded - responseBodies: excluded - userText: preview+length only ``` No bodies, no tokens, no storage values; user text as preview + length only. A capture safe enough to paste anywhere gets pasted. A risky one gets hoarded and helps no one. Nine events? My log dump has fifty thousand lines. How is less data better? Because the slice is chosen by the human's testimony, not by grep luck. Read the real one from this site's captured session and name the bug before anyone tells you: ``` text - [seq 3 · t+17397ms] click: click <button#save> "Save note" - [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms] - [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable - [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect" - [seq 7 · t+18436ms] console: console.log: reconnected: session restored - [seq 8 · t+18909ms] click: click <button#save> "Save note" - [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms] ``` Network failure, a "session restored" log, then a 401 on the very next save — under a UI that said "Saved ". If you just reached "the reconnect invalidated something the client still holds," a nine-line slice did what the dump rarely does. The [Session Replay](https://mindful-mango-accy.here.now/replay.html) shows the whole run that produced it. So the agent reads that and confidently guesses anyway. How is this not garbage in, gospel out? The handoff carries a fence. A weak handoff pastes a dump and asks "what's wrong?" — inviting confident guessing over noise. A strong handoff gives less data and more structure: what the human saw, what the system recorded, what was withheld, and what kind of answer is allowed. This is the exact prompt I hand any agent with a packet: ``` text Here is a debug packet captured from a live session of my app. Before you read any code: 1. Read the human testimony, then the evidence trail in seq order. 2. State your single most likely hypothesis for the failure, in one sentence. 3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet. 4. Label anything the trail cannot prove as "hypothesis — needs verification". Testimony is not diagnosis. Context is not proof. --- PACKET --- [paste the output of: node scripts/make-agent-packet.mjs your-session.json] ``` The packet itself ends the same way — a claims boundary. The agent's draft arrives labeled as a draft, and a person verifies it against the running app. Cute demo. Does this survive contact with a real app? It's already shipped. A production desktop app we studied runs the same loop natively: a hotkey mints a marker id, captures a screenshot, writes a marker log event, and opens a note where the tester types one explanation — all joined by the same id, with a log CLI whose `--marker` flag slices the session for agents. An external architecture review of that system pushed the same schema rules this recorder uses: sequence numbers as canonical order (not timestamps), ids joining everything, user text as preview + hash + length — never raw. One integration gotcha from real use: if your app wraps `fetch` (mocks, auth shims), install your wrapper *before* `AgentMarkers.start()` so the wrapped calls land in the trail. Fine. What do I paste into my project right now? Two options. See the loop run cold from an empty directory in about thirty seconds: ``` text mkdir -p markers-quickstart && cd markers-quickstart curl -sO https://mindful-mango-accy.here.now/agent-markers.js curl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs curl -sO https://mindful-mango-accy.here.now/sample-session.json node make-agent-packet.mjs sample-session.json ``` Or skip the typing entirely — paste this into your own agent and let it wire your app: ``` text Fetch https://mindful-mango-accy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` The [section guide](https://mindful-mango-accy.here.now/index.html) prints all three files complete — recorder, boot, packet renderer. Reference ID: factory-debug-markers-questions Topic: Verification Sources: - [Human testimony joined to runtime evidence — questions and tradeoffs](https://mindful-mango-accy.here.now/dialogue.html) --- # Human testimony joined to runtime evidence — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session, beat by beat Replayed from a prior scripted session against the workshop's Field Notes demo app — the same run that produced [sample-session.json](https://mindful-mango-accy.here.now/sample-session.json), published raw on this site. Prompts are condensed; every output below is quoted verbatim from the captured artifacts. You Serve the Field Notes demo and reproduce the reconnect-and-save failure: type a note, go offline, save, reconnect, save again. Agent Drove the app in a scripted browser. The offline save failed honestly ("Save failed (offline?)"). After **Reconnect**, the second save showed **"Saved "** — but the mock server returned 401. The plant: reconnecting rotates the server's session token, the client keeps its stale copy, and the save handler treats anything below 500 as success: ``` text // BUG: only 5xx counts as failure, so the stale-token 401 shows "Saved ". if (res.status < 500) { statusEl.textContent = "Saved "; } else { statusEl.textContent = "Save failed (server error)"; } ``` Would your users file a useful bug report for this? They saw a success message. That gap is the whole reason markers exist. You Mark that moment. Testimony: "It said Saved but my note never reached the server — this happened right after I reconnected." Agent The button uses `prompt()`, which blocks scripted browsers — so the mark went in through the console instead: ``` text window.__AGENT_MARKERS__.mark( "user-flag", "It said Saved but my note never reached the server — this happened right after I reconnected." ) ``` Marker `<demo-marker>` recorded, pinned to the nine nearest events by id. For a human it's one keystroke (Ctrl/Cmd+M) and one sentence at the moment of surprise. No form, no repro steps demanded — anything heavier and nobody uses it when it matters. You Export the session and show me exactly what leaves the machine. Agent `exportSession()` produced a schemaVersion-1 JSON — 1 marker, 10 events, and a redaction block that documents what was withheld: ``` text "redaction": { "storageValues": "excluded", "requestBodies": "excluded", "responseBodies": "excluded", "userText": "preview+length only" } ``` No request or response bodies, no tokens, no storage values; user text travels as preview + length only. The full export is published raw as [sample-session.json](https://mindful-mango-accy.here.now/sample-session.json). The redaction policy rides inside the payload, so every reader can audit what was withheld. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one. You Render the agent packet from that export. Agent ``` text node scripts/make-agent-packet.mjs samples/sample-session.json ``` The packet leads with the testimony, then the seq-ordered evidence slice. Seven consecutive lines, exactly as rendered: ``` text - [seq 3 · t+17397ms] click: click <button#save> "Save note" - [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms] - [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable - [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect" - [seq 7 · t+18436ms] console: console.log: reconnected: session restored - [seq 8 · t+18909ms] click: click <button#save> "Save note" - [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms] ``` Read it top to bottom: NETWORK-ERROR → "reconnected" → 401 on the very next save, under a visible "Saved ". A nine-line slice doing what a full log dump rarely does. You Now read the packet cold — no source code, no other context. One hypothesis, one sentence, before you look at anything else. Agent *The reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success.* Flagged as "hypothesis — needs verification", per the packet's claims boundary: testimony is not diagnosis, context is not proof. That is the pass condition for any capture you build: a cold reader — human or agent — gets from the packet alone to the mechanism. The hypothesis arrives labeled as a draft; a person verifies it against the running app. You Good. Give me the version I can drop into any app. Agent The whole recorder — dependency-free, no build step. Everything above was captured by these lines (same bytes as [agent-markers.js](https://mindful-mango-accy.here.now/agent-markers.js) on this site): ``` text /** * agent-markers.js — a tiny, dependency-free "press a button, capture the moment" recorder. * * Pattern: a MARKER is timestamped human testimony ("this moment matters, here's why"). * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there. * Export = bounded, redacted payload you can hand to an agent as a debug packet. * * Deliberately NOT captured: storage values, request/response bodies, raw input text. * Testimony is not diagnosis. Context is not proof. */ (function (global) { "use strict"; const state = { running: false, sessionId: null, startedAtIso: null, startedAtMs: 0, seq: 0, events: [], markers: [], maxEvents: 200, nearbyEventLimit: 12, restoreFns: [], }; function now() { return Math.round(performance.now() - state.startedAtMs); } function preview(text, max = 80) { const s = String(text ?? ""); return { preview: s.length > max ? s.slice(0, max) + "…" : s, length: s.length, truncated: s.length > max, }; } function record(type, data) { if (!state.running) return null; const event = { id: "evt-" + (++state.seq), seq: state.seq, t: now(), type, data }; state.events.push(event); if (state.events.length > state.maxEvents) state.events.shift(); return event; } function patchConsole() { ["log", "warn", "error"].forEach((level) => { const original = console[level]; console[level] = function (...args) { record("console", { level, message: preview(args.map(String).join(" ")) }); return original.apply(console, args); }; state.restoreFns.push(() => (console[level] = original)); }); } function patchFetch() { const original = global.fetch; global.fetch = async function (input, init) { const url = typeof input === "string" ? input : input.url; const method = (init && init.method) || "GET"; const started = now(); try { const res = await original.apply(global, arguments); record("fetch", { method, url, status: res.status, ok: res.ok, ms: now() - started }); return res; } catch (error) { record("fetch", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) }); throw error; } }; state.restoreFns.push(() => (global.fetch = original)); } function patchErrors() { const onError = (event) => record("error", { message: preview(event.message || String(event.reason || "unknown")) }); global.addEventListener("error", onError); global.addEventListener("unhandledrejection", onError); state.restoreFns.push(() => { global.removeEventListener("error", onError); global.removeEventListener("unhandledrejection", onError); }); } function patchClicks() { const onClick = (event) => { const el = event.target.closest("button, a, [data-action]") || event.target; record("click", { tag: el.tagName.toLowerCase(), id: el.id || null, action: el.dataset ? el.dataset.action || null : null, text: preview(el.textContent && el.textContent.trim(), 40), }); }; document.addEventListener("click", onClick, true); state.restoreFns.push(() => document.removeEventListener("click", onClick, true)); } const AgentMarkers = { start(options = {}) { if (state.running) return this; state.sessionId = options.sessionId || "session-" + Date.now().toString(36); state.startedAtIso = new Date().toISOString(); state.startedAtMs = performance.now(); state.maxEvents = options.maxEvents || 200; state.nearbyEventLimit = options.nearbyEventLimit || 12; state.seq = 0; state.events = []; state.markers = []; state.running = true; patchConsole(); patchFetch(); patchErrors(); patchClicks(); if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers; record("session", { note: "recording started", app: options.app || "unknown" }); return this; }, /** Human presses the button: timestamped testimony + pointers into the trail. */ mark(label, note) { if (!state.running) throw new Error("AgentMarkers not started"); const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id); const marker = { id: "mrk-" + (state.markers.length + 1) + "-" + Date.now().toString(36), seq: ++state.seq, t: now(), label: label || "unlabeled", note: note || "", nearbyEventIds: nearby, screenshot: "unavailable", // browser demo: no screenshot API without permissions }; state.markers.push(marker); record("marker", { markerId: marker.id, label: marker.label }); return marker; }, record(type, data) { return record("manual", { type, ...data }); }, /** Bounded, redacted payload — everything an agent gets, nothing more. */ exportSession() { return { schemaVersion: 1, sessionId: state.sessionId, startedAt: state.startedAtIso, exportedAt: new Date().toISOString(), userAgent: navigator.userAgent, markers: state.markers, events: state.events, redaction: { storageValues: "excluded", requestBodies: "excluded", responseBodies: "excluded", userText: "preview+length only", }, }; }, stop() { state.restoreFns.forEach((restore) => restore()); state.restoreFns = []; state.running = false; return this; }, }; if (typeof module !== "undefined" && module.exports) module.exports = AgentMarkers; global.AgentMarkers = AgentMarkers; })(typeof window !== "undefined" ? window : globalThis); ``` The boot file and the packet renderer are printed complete in the [section guide](https://mindful-mango-accy.here.now/index.html), or replay this whole loop from an empty directory: ``` text mkdir -p markers-quickstart && cd markers-quickstart curl -sO https://mindful-mango-accy.here.now/agent-markers.js curl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs curl -sO https://mindful-mango-accy.here.now/sample-session.json node make-agent-packet.mjs sample-session.json ``` Total session: five prompts. The loop the transcript demonstrates — mark → export → packet → hypothesis — is the same one your attendees' agents replay from [agent.md](https://mindful-mango-accy.here.now/agent.md). Reference ID: factory-debug-markers-worked-example Topic: Verification Sources: - [Human testimony joined to runtime evidence — worked example](https://mindful-mango-accy.here.now/replay.html) --- # Independent reasoning and video evidence Escalate consequential decisions with filtered context and use probes, sentinels, and bounded video analysis. ## Related working material - [Independent reasoning and video evidence — prompts and exercises](/topics/factory-reasoning-and-video-practice/) - [Independent reasoning and video evidence — questions and tradeoffs](/topics/factory-reasoning-and-video-questions/) - [Independent reasoning and video evidence — worked example](/topics/factory-reasoning-and-video-worked-example/) ## TL;DR - Oracle is an agent whose hands are a real Chrome browser: it drives chatgpt.com and gemini.google.com using cookies from the Chrome profile you already logged into. No API keys — subscription-priced frontier models. - You leave with a working local Oracle (install + one handshake command) and the two prompt patterns that make it pay: the maximum-batch consult and the sentinel video probe. - The one move: never spend a 20–60 minute consult on "what's next?" — demand the maximum actionable batch. That pattern turned a 93-minute workshop video into a permanent wiki: [silken-ferry-63mw.here.now](https://silken-ferry-63mw.here.now/). Have your agent set this up — paste this into it: ``` text Fetch https://shiny-rosette-m6zy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## Where the strongest models live The easy assumption is that maximum intelligence is an API call away. It isn't. ChatGPT's strongest tier — the model picker's "Latest" row, currently GPT-5.6 Pro with Extended thinking — is a subscription feature of the chat product. And Gemini's video understanding is only reachable through the page's own upload widget; the API path can't upload the browser video at all. The strongest text model and the only real video-watching path both sit behind logged-in chat sessions. Whoever holds a valid session cookie holds the key. ## How Oracle borrows your browser The whole mechanism in one breath: a human signs into ChatGPT in normal Chrome once; Oracle copies those session cookies into a temporary automation profile; the agent then drives that profile like a very fast reader who pastes a huge bundle of code and waits. What rides along with the cookies is context — bundles validated up to roughly 900k tokens of project code per consult. The contrast that makes it click: an API integration authenticates as a program and gets program-shaped limits. A cookie-borrowing browser authenticates as *you* and gets everything the chat product gives you — the model picker, extended thinking, and the file-upload widget the video pipeline depends on. Most people run this on their own laptop, and that is the whole setup. One operator's variant: an always-on Mac mini runs `oracle serve` with the signed-in Chrome, every other machine points at it over a private network, and a four-slot dual-account pool runs four hour-long consults at once while nobody's laptop stays open. Same trick, made multi-tenant. ## What 1,978 real consults look like A consult costs 20–60 minutes of wall clock, so the prompt contract bans spending it like a chat message. In the observed snapshot the local archive held about 1,978 session folders shaped by that rule. A sample: The recurring consult shapes are repeated hardening audits, independent multi-angle review followed by a judge, forensic debugging, redesign planning, and planning a media-analysis pipeline before executing it. The recurring shapes: iteration audits, where a fresh frontier reviewer re-reads the codebase every loop; multi-angle panels, where the same question runs three ways and a judge consult picks the winner; and pipeline-planning-the-pipeline — GPT-5.6 Pro designed the video sharding strategy that Gemini then executed. Every session leaves `output.log` and token receipts, replayable with `oracle session <id> --render`. ## The Loop Craft rip: 93 minutes of video into a permanent wiki In the observed snapshot the ask was: take a public 93:49 YouTube workshop on building durable autonomous agents and build it into an extensive published wiki with resources, pull quotes, and copy-paste prompts. The run shows the discipline that makes fragile browser automation dependable. First, probes. Early upload probes errored; a rebuild fixed the path; then the awaited-upload probe came back with the exact line `ATTACHED_VIDEO_OK loopcraft-awaited-upload-probe` — from the real MP4. Only then did the expensive runs start. GPT-5.6 Pro reviewed the segmentation plan, and Gemini watched source-native shards one by one, each analysis ending in its exact sentinel. The analyses prove Gemini genuinely watched: it heard "we are going to talk about Loopcraft…" and identified the GitHub workshop page with the presenter's picture-in-picture at the 00:30 mark. Shard 004 is the teachable failure. It errored twice while its three siblings sailed through — which rules out "the pipeline is down" and points at the input. An exact re-encode fixed it completely: the analysis finished in 73 seconds with the exact sentinel, and the re-encode settings were kept as the durable media recipe for future runs. Classify the failure, change one variable, re-run the cheap proof, keep the fix. The result is public and permanent: the [Loop Craft workshop wiki](https://silken-ferry-63mw.here.now/) and its [video companion](https://silken-ferry-63mw.here.now/video-companion/). A 93-minute recording became a quotable artifact in one working session — and after publishing, the agent curled the live URLs rather than trusting the publish receipt. ## Appendix ### Limits & caveats - Browser automation is experimental and most stable on macOS. UI drift, model-picker changes, and upload races are real — the probe discipline exists because this path breaks. On Linux, pass `--browser-chrome-path`/`--browser-cookie-path` if detection fails. - Cookie-based automation authenticates as your personal account. The sources describe capability and access, not permission: they do not analyze provider terms of service or account risk. Decide that trade-off for your own accounts. - The four-slot dual-account pool is qualified against one exact build and topology. There is no evidence it transfers to other machines or accounts without redoing that qualification. Its access tokens are private and absent from this entire site; the attached skill files describe the pool only via a generic ssh alias, loopback ports, and a pinned build hash — identifiers of the presenter's setup, useless without it. - "A consult repays the hour" is the contract's premise, not a measured result — the archive shows scale and shape of use, not a controlled comparison against cheaper prompting. - The Loop Craft timeline is compressed; some intermediate error attempts are omitted, and the full receipts stay in local session folders. The shard-004 re-encode is an empirical fix, not a diagnosis of why the original encoding failed. - The session archive figures (~1,978 folders) were counted in the observed snapshot and grow continuously. ## Operating practice ### Escalate the decision, not the workflow #### What to notice Spend frontier-model or video-analysis overhead only where a second reasoning or observation path can change the decision. #### Try this Bring one decision, a filtered evidence bundle, alternatives, hidden assumptions, a **discriminating experiment**, and a reversal plan. > “Might as well use the maximum intelligence I have access to.” John Lindquist · [05:11:10](https://proud-anchor-53zn.here.now/watch.html?t=18670#recording-player) #### Concept Use deeper reasoning for hard-to-reverse architecture, obscure stacks, contradictory evidence, or independent verification. Use video when timing, pointer movement, or transient UI state is the evidence. #### Reflection Workshop model names, plan tiers, prices, and limits are dated statements, not current purchasing guidance. **Recording evidence:** listen at 05:05:27. > “So, it's able to walk through and analyze the videos, in chunks, in shards.” John Lindquist · [05:19:43](https://proud-anchor-53zn.here.now/watch.html?t=19183#recording-player) [Open Maximum Intelligence and Video](https://shiny-rosette-m6zy.here.now/) #### Links shared for this topic - [Oracle](https://github.com/steipete/oracle) — A repository-context bundler and browser consult workflow. - [Video analysis companion](https://silken-ferry-63mw.here.now/) — The prepared companion for video-assisted analysis. - [Google AI Studio Live](https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview) — A live multimodal model surface shared during the video discussion. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=18327#q3-max-intelligence) Reference ID: factory-reasoning-and-video Topic: Verification Sources: - [Independent reasoning and video evidence](https://shiny-rosette-m6zy.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence) --- # Independent reasoning and video evidence — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Maximum Intelligence Models High-tier reasoning models like GPT-5.6 Sol that execute long-duration thinking/research paths (15-30 minutes) to solve highly complex tasks. ### Context Bundling Bundling large portions of a codebase or repository into a single, structured prompt file suitable for LLM long-context windows (up to a million tokens). ### Browser-based Agent Automation Automating a local browser using existing session cookies to paste complex context and prompts directly into a consumer web interface rather than calling expensive API endpoints. ### Maximum Intelligence for Obscure Tech Stacks Utilizing top-tier reasoning models (e.g. ChatGPT Pro / o1) when working with frameworks that lack representation in base model weights, such as Rust GPUI. ### Asynchronous Deep Reasoning Passes Offloading complex architecture planning or audit tasks to multi-minute reasoning sessions (8-23 minutes) while working on other tasks. ### Voice Agent Context Continuation Prompting mobile voice agents with explicit context loading phrases ('Please load in the context') to resume desktop conversations on mobile devices. ### Codex Subscription & Harness Support Utilizing Codex as a versatile backend model for open agent harnesses (OpenClaw, Script Kit, Pi), offering image input and cost efficiency over proprietary locked harnesses. ### Context Bundling with packx Packaging repository files into consolidated text attachments (attachments-bundle(133).txt) using the packx skill to supply complete project context to high-reasoning models. ### Remote Browser Agent Execution Running browser automation agents on a separate remote computer (Mac Mini) via Screen Sharing and mobile Codex Remote to eliminate focus-stealing window popups on the main workstation. ### Native Video Analysis Multimodal AI processing of complete video/audio streams directly without extracting separate frame images. ### Sharded Video Context Extraction Chunking longer video recordings into ~4-minute shards with sequential context pass-through for detailed extraction. ### Video Sharding & Automated Analysis Splitting down massive video captures into distinct shards for targeted semantic parsing by advanced LLMs to build documentation architectures dynamically. ### Screen Interaction Capture for AI Leveraging on-demand video capturing mechanisms to visually present system states directly to multimodal models rather than manually typing out error trace context. ### Real-time Multimodal Prompting Streaming live video feeds, screen captures, and sound input seamlessly to an LLM for ongoing interactive visual context analysis. ### Google AI Studio Live API A specialized sandbox area in Google AI Studio configured for testing low-latency live streaming capabilities of preview Gemini models. ## Questions and answer status ### what types of situations do you consult? planning? creating spec? user stories? reviewing? diagnosing? questioning? **Status: answered.** John explains he consults reasoning models primarily for continuous architecture planning, handling obscure component/rendering issues in specialized frameworks (Rust GPUI), and conducting asynchronous verification passes. ### do you have agents gather context first? do grill me before, etc, how do you gather context **Status: deferred.** Unanswered in this shard as John transitions to discussing mobile voice agent context loading. ### Can you use the codex subscription in pi? **Status: answered.** John confirms that the Codex subscription can be used in Pi. ### What types of situation? Do you have agents gather context first, or do you grill first? **Status: answered.** John brainstorms and breaks down the task first, then hands off to Oracle instructing it to use the packx skill to assemble and attach full repository context files. ### do you use notebooklm to send people artifacts, like podcasts? videos? etc? 2. do you create your own podcasts? i find it useful for research papers 3. how do you do research? **Status: unanswered.** No answer was linked in the companion evidence. ### Can a single Mermaid graph effectively serve both machine context injection and human-readable documentation, or should we treat LLM-facing context architecture entirely separate from human-facing notes? **Status: unanswered.** No answer was linked in the companion evidence. ### does that require ULTRA subscription? do you find value in ULTRA subscription? **Status: unanswered.** No answer was linked in the companion evidence. ## Exercises - **Try:** Configure remote browser execution for agent workflows using a dedicated secondary machine (e.g. Mac Mini) via Screen Sharing and Codex Remote on mobile to prevent automated browser sessions from stealing workstation focus. **Basis:** Presenter demonstrates Screen Sharing connection to remote Mac Mini at 05:14:36 - 05:15:35 and explains remote mobile workflow. - **Try:** Bundle codebase context into prompt attachment files using packx before passing tasks to reasoning models. **Basis:** Presenter demonstrates attachments-bundle(133).txt document in ChatGPT Pro at 05:13:22 - 05:13:58 and references packx on deep-steel-rfbs.here.now. ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [05:06:00](https://proud-anchor-53zn.here.now/watch.html?t=18360#recording-player) — John clicks the intelligence dropdown model selector in ChatGPT, showing options like Instant 5.5 and GPT-5.6 Sol under the Pro tier. - [05:08:35](https://proud-anchor-53zn.here.now/watch.html?t=18515#recording-player) — John reviews the context bundling tools table showing Repomix, git2prompt, files-to-prompt, pacx, and yek. - [05:09:09](https://proud-anchor-53zn.here.now/watch.html?t=18549#recording-player) — a participant asks what situations John consults models for (planning, specs, reviewing, diagnosing). - [05:09:15](https://proud-anchor-53zn.here.now/watch.html?t=18555#recording-player) — John answers a participant, stating he uses models continuously for planning and complex codebase tasks. - [05:09:23](https://proud-anchor-53zn.here.now/watch.html?t=18563#recording-player) — John mentions his ScriptKit project uses GPUI, a Rust framework developed by Zed that is sparse in training weights. - [05:09:54](https://proud-anchor-53zn.here.now/watch.html?t=18594#recording-player) — John explains tossing obscure rendering and component questions to ChatGPT Pro reasoning models. - [05:10:16](https://proud-anchor-53zn.here.now/watch.html?t=18616#recording-player) — ChatGPT Pro interface displays a session that ran reasoning for 14 minutes ('Worked for 14m 16s'). - [05:10:48](https://proud-anchor-53zn.here.now/watch.html?t=18648#recording-player) — John expands the reasoning trace accordion ('Show more') to display granular file inspection and hashing steps. - [05:11:04](https://proud-anchor-53zn.here.now/watch.html?t=18664#recording-player) — John describes using reasoning runs asynchronously for verification passes whenever maximum intelligence is needed. - [05:11:17](https://proud-anchor-53zn.here.now/watch.html?t=18677#recording-player) — a participant asks if agents gather context first or grill the user before tasks. - [05:11:20](https://proud-anchor-53zn.here.now/watch.html?t=18680#recording-player) — John highlights ChatGPT Pro subscription benefits including image generation, independent Codex budgets, and voice models. - [05:11:46](https://proud-anchor-53zn.here.now/watch.html?t=18706#recording-player) — John explains prompting mobile voice models with 'Please load in the context' to continue desktop threads. - [05:12:11](https://proud-anchor-53zn.here.now/watch.html?t=18731#recording-player) — John discusses Codex subscription usage limit resets and value per dollar. - [05:12:20](https://proud-anchor-53zn.here.now/watch.html?t=18740#recording-player) — John notes Codex supports OpenClaw and other agent harnesses. - [05:12:33](https://proud-anchor-53zn.here.now/watch.html?t=18753#recording-player) — John mentions using Codex to back Script Kit AI features. - [05:12:55](https://proud-anchor-53zn.here.now/watch.html?t=18775#recording-player) — a participant asks in chat: Can you use the codex subscription in pi? - [05:12:57](https://proud-anchor-53zn.here.now/watch.html?t=18777#recording-player) — John answers context gathering question: brainstorms task first, then hands off to Oracle with packx. - [05:13:41](https://proud-anchor-53zn.here.now/watch.html?t=18821#recording-player) — John explains packx bundles massive amounts of codebase context for smart model analysis. - [05:14:00](https://proud-anchor-53zn.here.now/watch.html?t=18840#recording-player) — John answers a participant's question, confirming Codex subscription can be used in Pi. - [05:14:20](https://proud-anchor-53zn.here.now/watch.html?t=18860#recording-player) — John explains local automated browser agents steal window focus while working. - [05:14:27](https://proud-anchor-53zn.here.now/watch.html?t=18867#recording-player) — Agenda page shows FOR YOUR AGENT fetch command and THE WHOLE WORKSHOP AS ONE FLOW curl/mdflow command. - [05:14:37](https://proud-anchor-53zn.here.now/watch.html?t=18877#recording-player) — John describes using a dedicated remote Mac Mini to run background browser agents. - [05:15:15](https://proud-anchor-53zn.here.now/watch.html?t=18915#recording-player) — John explains using Codex Remote on his phone to trigger remote agent jobs on the Mac Mini. - [05:17:02](https://proud-anchor-53zn.here.now/watch.html?t=19022#recording-player) — John explains Gemini's native video processing compared to frame extraction models. - [05:17:36](https://proud-anchor-53zn.here.now/watch.html?t=19056#recording-player) — John discusses Joel Hooks's LoopCraft video and the 4-minute video sharding strategy. - [05:19:52](https://proud-anchor-53zn.here.now/watch.html?t=19192#recording-player) — John clicks on the 'LOCAL SETUP' header link to display documentation detailing full workspace environments without Docker. - [05:20:03](https://proud-anchor-53zn.here.now/watch.html?t=19203#recording-player) — John mentions setting up a portion of the screen using CleanShot to record interactions. - [05:20:39](https://proud-anchor-53zn.here.now/watch.html?t=19239#recording-player) — John explains feeding these screen captures directly into Gemini to parse errors or analyze paragraphs naturally. - [05:22:25](https://proud-anchor-53zn.here.now/watch.html?t=19345#recording-player) — John Lindquist explains how full video captioning captures unexpected user behavior and cursor data. - [05:23:08](https://proud-anchor-53zn.here.now/watch.html?t=19388#recording-player) — a participant asks whether a single Mermaid graph can serve both machine context injection and human documentation. - [05:24:33](https://proud-anchor-53zn.here.now/watch.html?t=19473#recording-player) — John writes a text prompt asking what the model can see on his monitor screen. - [05:24:45](https://proud-anchor-53zn.here.now/watch.html?t=19485#recording-player) — The Live API outputs structured text describing the active Google AI Studio interface context view. - [05:25:17](https://proud-anchor-53zn.here.now/watch.html?t=19517#recording-player) — a participant asks if this capability requires an Ultra account tier subscription. ### Demonstration detail: 05:05:43 - Navigated to chatgpt.com - Opened the intelligence model selection dropdown **Tools observed:** ChatGPT Web UI. ### Demonstration detail: 05:08:22 - Switched to references page tab - Scrolled down to the AI Context Bundlers comparison table **Tools observed:** Google Chrome Browser. ### Demonstration detail: 05:08:52 - Navigate ChatGPT sidebar threads - Open reasoning session threads - Expand reasoning execution trace accordion **Tools observed:** ChatGPT Pro. ### Demonstration detail: 05:12:11 - Inspect ChatGPT Pro audit report for MiniCode project - Click attachments-bundle(133).txt preview drawer to view bundled repository files **Tools observed:** ChatGPT Pro, Arc Browser. ### Demonstration detail: 05:14:06 - Switch browser tabs to deep-steel-rfbs.here.now to show context bundlers table - Switch browser tabs to ember-bodhi-scrs.here.now to show agent setup instructions **Tools observed:** Arc Browser. **Command or prompt observations (not a verified recipe):** ```text fetch https://ember-bodhi-scrs.here.now/agent.md --no-machine-readable-agenda curl -s https://ember-bodhi-scrs.here.now/workshop.md?app=-y | npx mdflow --script - --task "Walk me through the workshop, set a..." ``` ### Demonstration detail: 05:14:36 - Trigger Raycast launcher with Cmd+Space keyboard shortcut - Search for Screen Sharing and launch application - Connect to remote Mac Mini machine - Display remote desktop running Chrome profile selector **Tools observed:** Raycast, macOS Screen Sharing, Google Chrome. ### Demonstration detail: 05:16:12 - Navigated to workshop docs - Opened Gemini web interface - Reviewed video analysis reports for Shard 001 and Shard 004 **Tools observed:** Gemini, Arc Browser. ### Demonstration detail: 05:19:05 - Navigated across the generated workshop video companion companion web app pages. - Inspected automated timestamp sections inside the Chapter map. - Scrolled down the Glossary documentation framework entries. **Tools observed:** Chrome Browser. ### Demonstration detail: 05:20:07 - Triggered the CleanShot X operational video screen recording control layer. - Executed configuration changes inside the recording wizard interface. - Clicked through file save decisions inside the modal overlay dialog window. **Tools observed:** CleanShot X. ### Demonstration detail: 05:23:25 - Opened AI Studio dashboard - Searched for real-time options - Configured Gemini 3.1 Flash Live Preview model - Shared display screen window feed - Submitted text dialog content **Tools observed:** Google AI Studio Live API Sandbox, Google Chrome. Reference ID: factory-reasoning-and-video-discussion Topic: Verification Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Independent reasoning and video evidence — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for independent reasoning and video evidence. ## Quick start Sign into chatgpt.com in your normal Chrome first — a human does that part, once. Then: ``` text npm install -g @steipete/oracle # or: brew install steipete/tap/oracle (Node 22+) oracle --engine browser -p "HI" # first handshake: copies your cookies, sends "HI" oracle status --hours 72 # the reply is recorded as a replayable session ``` ## Prompt library ### The maximum-batch consult - Agent: oracle CLI → ChatGPT (GPT-5.6 Pro) - Working directory: your project root - Expected result: ordered work packages with file/function/test targets, 20–60 min later This is the pattern behind ~1,978 real consult sessions. Fill the `<angle-bracket>` slots with your project's facts; the last two paragraphs ship verbatim with every consult. Save it as `consult-prompt.md`. ``` text [<three-to-five-word-slug>] ## Project briefing <stack, framework, runtime, and repo rules — two or three sentences> ## Goal <the full outcome you want, stated as the whole contract Oracle must plan against — never pre-shrunk to a first step> ## Prior-State Ledger - prior_oracle_session: none - implemented_since_prior_oracle: none - verified_since_prior_oracle: none - failed_proof_or_blocker: none - remaining_goal_coverage: the full goal above ## Current evidence <attempts, failing logs, screenshots, and known constraints — or "none yet"> ## Bundle map The attached files contain <what you included and why>. Possibly missing: <what you could not include>. ## Deliverable Return the maximum actionable batch: an ordered set of work packages covering everything worth doing toward the goal. Every work package must carry exact file/function/test targets, critical code snippets, and a falsifiable verification. Sequence the packages, name risks and invariants, and put anything you cannot target exactly in a separate short "needs investigation" list. Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. Plan the maximum actionable batch: cover everything worth doing toward the goal in ordered work packages with exact file/function/test targets and a falsifiable verification each. Do not return a single next step or hold work back for a later round. An ambitious, specific answer is correct; only untargeted vagueness is a defect. ``` Run it with your code attached: ``` text oracle --engine browser -p "$(cat consult-prompt.md)" \ --file "src/**/*.ts,docs/**/*.md" --slug "<three-to-five-word-slug>" ``` ### The sentinel video probe - Agent: oracle CLI → Gemini - Working directory: anywhere, with a short MP4 on disk - Expected result: three bullets plus the exact sentinel line, byte-for-byte Before any expensive video run, prove the upload path with a cheap probe. Save this as `probe-prompt.md`: ``` text [video-upload-smoke-probe] This is an attached-video readiness probe for a longer video analysis run. Confirm that you can inspect the attached video. Return exactly three short bullets: - whether video frames are visible; - whether audio is detectable; - one strictly observed visual detail, without guessing. End with this exact sentinel on its own line: END_OF_VIDEO_ANALYSIS video-upload-smoke-probe probe ``` ``` text oracle --engine browser --model gemini-3-pro --browser-attachments always \ -p "$(cat probe-prompt.md)" --file "/absolute/path/to/probe-clip.mp4" \ --slug "video-upload-smoke-probe" ``` The pass rule: the sentinel comes back byte-exact and the observed detail matches your footage. A paraphrase, extra prose, or silence means the path is broken — fix it before the long run, not after. ### The shard analysis prompt — Loop Craft, verbatim - Agent: oracle CLI → Gemini - Working directory: a video run folder with a ≤4-minute shard - Expected result: dense Markdown + machine JSON, ending in the exact sentinel This exact prompt produced shard 001 of the [Loop Craft wiki](https://silken-ferry-63mw.here.now/). Swap the metadata block and the sentinel for your own run; keep the evidence rules — they are what stop Gemini from inventing URLs, commands, and speakers. ``` text [loopcraft-workshop-shard-001-source-native] Analyze the attached source-native video shard for an extensive public workshop wiki. Metadata: - run_key: loopcraft-agent-workshop - shard_id: 001 - original recording range: 00:00:00–00:04:00 - publication chapter: Workshop Setup and the Looping Resolver Evidence rules: 1. Use original workshop timestamps from 00:00:00 through 00:04:00. 2. Separate spoken evidence, visible screen evidence, and inference. 3. Listen to the audio; do not rely on automatic captions. 4. Do not invent commands, URLs, files, tools, speakers, or UI labels. 5. Pull quotes must be brief (under 20 words), audio-verified, attributed to Joel Hooks, and timestamped. 6. Exclude credentials, account details, local paths/usernames, private URLs, signed URLs, notifications, or incidental personal data. 7. Treat opinions and live-demo observations as such, not universal facts. 8. Derived prompts must use placeholders, be clearly labeled as inspired by the workshop, and require confirmation for destructive or externally visible actions. Return dense Markdown with these sections: # Shard 001 — 00:00:00–00:04:00 ## Executive Takeaway ## Dense Timeline ## Concepts and Mental Models ## Visible Demo Evidence ## Architecture and Workflow Patterns ## Tools, Commands, and References ## Pull Quote Candidates ## Copy/Paste AI Prompt Candidates ## Student Exercises and Reflection Questions ## Keyframes to Capture ## Uncertainties and Publication Review ## Machine JSON The fenced JSON object must contain: shard_id, original_range, summary, timeline, concepts, workflows, demos, resources, quotes, prompts, exercises, keyframes, warnings, unanswered_questions. End with this exact sentinel on its own line: END_OF_VIDEO_ANALYSIS loopcraft-agent-workshop shard-001 ``` ## Set it up (agent guide) 1. Check prerequisites: Node 22+ and Google Chrome installed. ``` text node --version # need v22 or newer; Chrome must also be installed ``` 2. Install the Oracle CLI. ``` text npm install -g @steipete/oracle oracle --version ``` 3. Sign into chatgpt.com in your normal Chrome. **A human does this step** — an agent cannot log in for you. Oracle borrows the session cookies from that logged-in profile. 4. Run the first handshake. Oracle copies your cookies into a temporary automation profile, opens ChatGPT, and sends the prompt. ``` text oracle --engine browser -p "HI" ``` 5. Create your first real consult. Save this file and replace every `<angle-bracket>` slot with facts from your project: ``` text [<three-to-five-word-slug>] ## Project briefing <stack, framework, runtime, and repo rules — two or three sentences> ## Goal <the full outcome you want, stated as the whole contract Oracle must plan against — never pre-shrunk to a first step> ## Prior-State Ledger - prior_oracle_session: none - implemented_since_prior_oracle: none - verified_since_prior_oracle: none - failed_proof_or_blocker: none - remaining_goal_coverage: the full goal above ## Current evidence <attempts, failing logs, screenshots, and known constraints — or "none yet"> ## Bundle map The attached files contain <what you included and why>. Possibly missing: <what you could not include>. ## Deliverable Return the maximum actionable batch: an ordered set of work packages covering everything worth doing toward the goal. Every work package must carry exact file/function/test targets, critical code snippets, and a falsifiable verification. Sequence the packages, name risks and invariants, and put anything you cannot target exactly in a separate short "needs investigation" list. Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. Plan the maximum actionable batch: cover everything worth doing toward the goal in ordered work packages with exact file/function/test targets and a falsifiable verification each. Do not return a single next step or hold work back for a later round. An ambitious, specific answer is correct; only untargeted vagueness is a defect. ``` 6. Run the consult with your code attached. A GPT-5.6 Pro consult takes 20–60 minutes of wall clock — wait for it; the session log is the durable record. ``` text oracle --engine browser -p "$(cat consult-prompt.md)" \ --file "src/**/*.ts" --slug "<three-to-five-word-slug>" ``` **Success check:** a response was received and recorded. The handshake and your consult both appear as sessions: ``` text oracle status --hours 24 ``` The session browser should report the completed model run; inspect the returned artifact rather than trusting a short status alone. ## Attachments — the Oracle skill family These are the presenter's real skill files, verbatim — the same six skills that drive everything on this page: `oracle` (the maximum-batch consult contract, plus its packx references and round-robin scripts), `oracle-execute` (Oracle-planned execution loops), `oracle-schedule` (one scheduled future consult), `oracle-video` (the Gemini video pipeline, with its repeatable follow-up process), `oracle-video-create` (Gemini video generation), and `imagine` (ChatGPT image generation). They orchestrate Oracle's browser engine plus packx and assume the presenter's accounts and setup — the round-robin pieces are pinned to one private pool you don't have. Install them to **study and adapt to your own accounts**, not to run unmodified. One block downloads all six into a staging folder and installs them into the current project. Two verified gotchas baked in: `.md` files must be fetched with `?raw` (the bare URL returns an HTML viewer page), and the staging folder must *not* be named `skills/` — the installer claims `./skills/` as one of its own targets and would clobber your downloads with empty symlinks. ``` text BASE=https://shiny-rosette-m6zy.here.now/skills D=oracle-skill-family mkdir -p $D/oracle/references $D/oracle/scripts $D/oracle-execute \ $D/oracle-schedule/agents $D/oracle-video/references \ $D/oracle-video-create $D/imagine/agents curl -fsS "$BASE/oracle/SKILL.md?raw" -o $D/oracle/SKILL.md curl -fsS "$BASE/oracle/references/round-robin-receipt.md?raw" -o $D/oracle/references/round-robin-receipt.md curl -fsS "$BASE/oracle/references/round-robin-transport.md?raw" -o $D/oracle/references/round-robin-transport.md curl -fsS "$BASE/oracle/references/packx-quick-reference.md?raw" -o $D/oracle/references/packx-quick-reference.md curl -fsS "$BASE/oracle/references/packx-deep-reference.md?raw" -o $D/oracle/references/packx-deep-reference.md curl -fsS "$BASE/oracle/scripts/extract_codex_conversation.py" -o $D/oracle/scripts/extract_codex_conversation.py curl -fsS "$BASE/oracle/scripts/run_round_robin.sh" -o $D/oracle/scripts/run_round_robin.sh curl -fsS "$BASE/oracle-execute/SKILL.md?raw" -o $D/oracle-execute/SKILL.md curl -fsS "$BASE/oracle-schedule/SKILL.md?raw" -o $D/oracle-schedule/SKILL.md curl -fsS "$BASE/oracle-schedule/agents/openai.yaml" -o $D/oracle-schedule/agents/openai.yaml curl -fsS "$BASE/oracle-video/SKILL.md?raw" -o $D/oracle-video/SKILL.md curl -fsS "$BASE/oracle-video/references/repeatable-video-followup-process.md?raw" -o $D/oracle-video/references/repeatable-video-followup-process.md curl -fsS "$BASE/oracle-video-create/SKILL.md?raw" -o $D/oracle-video-create/SKILL.md curl -fsS "$BASE/imagine/SKILL.md?raw" -o $D/imagine/SKILL.md curl -fsS "$BASE/imagine/agents/openai.yaml" -o $D/imagine/agents/openai.yaml chmod +x $D/oracle/scripts/extract_codex_conversation.py $D/oracle/scripts/run_round_robin.sh npx skills add ./$D --skill '*' -y ``` To install just one skill instead of all six, change the last line — for example `npx skills add ./oracle-skill-family --skill oracle -y`. ## Complete reusable setup contract ## Oracle: Maximum Intelligence and Video — agent setup guide Following this file sets up: a local Oracle CLI that drives ChatGPT through your user's logged-in Chrome browser (no API keys) and runs a first maximum-batch consult against the current project. Human-facing companions at this site (context for your user, not steps for you): https://shiny-rosette-m6zy.here.now/replay.html is an annotated session replay of the real video-analysis run this workflow comes from, and https://shiny-rosette-m6zy.here.now/dialogue.html answers the common skeptical questions. This file remains the canonical executable path. The presenter's six real Oracle skill files are also attached at this site — see "Attachments" at the bottom of this file for the download URLs and install block. Placeholders used below: `<project-root>` = the project you are working in; `<three-to-five-word-slug>` = a slug you choose, 3–5 hyphenated words (Oracle rejects anything outside that range). All other paths are literal. ## Prerequisites Check each before starting: ```bash node --version ``` Expected: `v22` or newer. Google Chrome must also be installed, and your user needs a ChatGPT account. If a tool is missing, stop and tell your user what to install. ## Steps 1. Install the Oracle CLI globally and confirm it runs: ```bash npm install -g @steipete/oracle oracle --version ``` 2. Ask your user to sign into chatgpt.com in their normal Chrome profile. **A human must do this step — you cannot log in for them.** Oracle copies the session cookies from that logged-in profile into a temporary automation profile; the login is the entire auth setup. Wait for your user to confirm they are signed in before continuing. 3. Run the first browser handshake. This copies the cookies, opens ChatGPT in an automated Chrome, and sends the prompt: ```bash oracle --engine browser -p "HI" ``` A reply coming back (any reply) proves the cookie path works. 4. Create `<project-root>/consult-prompt.md` with exactly this content, then replace every `<angle-bracket>` slot with real facts from the current project (read the code first — the briefing, goal, and bundle map must be true, not generic). Keep the final two paragraphs verbatim; they are the contract that makes the consult worth its cost: ```markdown [<three-to-five-word-slug>] ## Project briefing <stack, framework, runtime, and repo rules — two or three sentences> ## Goal <the full outcome you want, stated as the whole contract Oracle must plan against — never pre-shrunk to a first step> ## Prior-State Ledger - prior_oracle_session: none - implemented_since_prior_oracle: none - verified_since_prior_oracle: none - failed_proof_or_blocker: none - remaining_goal_coverage: the full goal above ## Current evidence <attempts, failing logs, screenshots, and known constraints — or "none yet"> ## Bundle map The attached files contain <what you included and why>. Possibly missing: <what you could not include>. ## Deliverable Return the maximum actionable batch: an ordered set of work packages covering everything worth doing toward the goal. Every work package must carry exact file/function/test targets, critical code snippets, and a falsifiable verification. Sequence the packages, name risks and invariants, and put anything you cannot target exactly in a separate short "needs investigation" list. Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. Plan the maximum actionable batch: cover everything worth doing toward the goal in ordered work packages with exact file/function/test targets and a falsifiable verification each. Do not return a single next step or hold work back for a later round. An ambitious, specific answer is correct; only untargeted vagueness is a defect. ``` 5. Run the consult from `<project-root>`, attaching the relevant source files (adjust the glob to the project's language): ```bash oracle --engine browser -p "$(cat consult-prompt.md)" \ --file "src/**/*.ts" --slug "<three-to-five-word-slug>" ``` A GPT-5.6 Pro consult takes 20–60 minutes of wall clock. Wait for it. Do not assume it timed out based on elapsed time alone — check the session (step 6) instead of restarting. ## Success check Success = a response was received. Run: ```bash oracle status --hours 24 ``` Expected observable result: a "Recent Sessions" table listing your handshake and your consult slug with Status `completed`, Model `gpt-5.6-pro` (the handshake may show a different model), Mode `browser`, and a non-zero Chars count. Read the full response with: ```bash oracle session "<three-to-five-word-slug>" --render ``` Report to your user: that Oracle is installed and cookie-authenticated, the consult slug, the success-check output, and a summary of the work packages Oracle returned — every package, not a trimmed selection. ## Notes for agents - `Missing OPENAI_API_KEY` means the call fell into API mode. That is a caller bug, not a missing credential — retry with `--engine browser`. - `Inspected target navigated or closed` mid-run: retry with `--browser-auto-reattach-delay 5s --browser-auto-reattach-interval 3s --browser-auto-reattach-timeout 60s`. - If the handshake fails, the most likely cause is that the user is not actually signed into chatgpt.com in their normal Chrome. Ask them to check before debugging anything else. - Browser automation is experimental and most stable on macOS. On Linux, pass `--browser-chrome-path` / `--browser-cookie-path` if Chrome detection fails. - The CLI's terminal output can truncate long answers. The authoritative record is the session log at `~/.oracle/sessions/<slug>/output.log`, also readable via `oracle session <slug> --render`. - Remote option (note only — do not set this up unless your user asks): an always-on machine can run `oracle serve` with its own signed-in Chrome, and clients point at it by setting the remote host and token in `~/.oracle/config.json`. The cookies then live once, on that host, for every client. Local mode is the right default. - Video analysis uses the same CLI with `--model gemini-3-pro --browser-attachments always` and a Gemini login in Chrome, and every expensive run should be preceded by a cheap sentinel probe. The prompt library at https://shiny-rosette-m6zy.here.now/ has the liftable probe prompt/command pair. ## Attachments — the Oracle skill family (optional) The presenter's six real skill files are published verbatim under `https://shiny-rosette-m6zy.here.now/skills/`. They orchestrate Oracle's browser engine plus packx and assume the presenter's accounts and setup (the round-robin pieces are pinned to a private pool you don't have) — install them to study and adapt, not to run unmodified. Only do this if your user asks for the skills. here.now gotcha: `.md` files must be fetched with `?raw` (the bare `.md` URL returns an HTML viewer page). The raw file URLs: - https://shiny-rosette-m6zy.here.now/skills/oracle/SKILL.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-receipt.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-transport.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-quick-reference.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle/scripts/extract_codex_conversation.py - https://shiny-rosette-m6zy.here.now/skills/oracle/scripts/run_round_robin.sh - https://shiny-rosette-m6zy.here.now/skills/oracle-execute/SKILL.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle-schedule/SKILL.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle-schedule/agents/openai.yaml - https://shiny-rosette-m6zy.here.now/skills/oracle-video/SKILL.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle-video/references/repeatable-video-followup-process.md?raw - https://shiny-rosette-m6zy.here.now/skills/oracle-video-create/SKILL.md?raw - https://shiny-rosette-m6zy.here.now/skills/imagine/SKILL.md?raw - https://shiny-rosette-m6zy.here.now/skills/imagine/agents/openai.yaml Second verified gotcha: stage the downloads in a folder that is NOT named `skills/`. The `npx skills add` installer claims `./skills/` as one of its own install targets (OpenClaw) and will replace your staged source with empty symlinks, installing nothing. Download all six into `./oracle-skill-family/` and install them into the current project: ```bash BASE=https://shiny-rosette-m6zy.here.now/skills D=oracle-skill-family mkdir -p $D/oracle/references $D/oracle/scripts $D/oracle-execute \ $D/oracle-schedule/agents $D/oracle-video/references \ $D/oracle-video-create $D/imagine/agents curl -fsS "$BASE/oracle/SKILL.md?raw" -o $D/oracle/SKILL.md curl -fsS "$BASE/oracle/references/round-robin-receipt.md?raw" -o $D/oracle/references/round-robin-receipt.md curl -fsS "$BASE/oracle/references/round-robin-transport.md?raw" -o $D/oracle/references/round-robin-transport.md curl -fsS "$BASE/oracle/references/packx-quick-reference.md?raw" -o $D/oracle/references/packx-quick-reference.md curl -fsS "$BASE/oracle/references/packx-deep-reference.md?raw" -o $D/oracle/references/packx-deep-reference.md curl -fsS "$BASE/oracle/scripts/extract_codex_conversation.py" -o $D/oracle/scripts/extract_codex_conversation.py curl -fsS "$BASE/oracle/scripts/run_round_robin.sh" -o $D/oracle/scripts/run_round_robin.sh curl -fsS "$BASE/oracle-execute/SKILL.md?raw" -o $D/oracle-execute/SKILL.md curl -fsS "$BASE/oracle-schedule/SKILL.md?raw" -o $D/oracle-schedule/SKILL.md curl -fsS "$BASE/oracle-schedule/agents/openai.yaml" -o $D/oracle-schedule/agents/openai.yaml curl -fsS "$BASE/oracle-video/SKILL.md?raw" -o $D/oracle-video/SKILL.md curl -fsS "$BASE/oracle-video/references/repeatable-video-followup-process.md?raw" -o $D/oracle-video/references/repeatable-video-followup-process.md curl -fsS "$BASE/oracle-video-create/SKILL.md?raw" -o $D/oracle-video-create/SKILL.md curl -fsS "$BASE/imagine/SKILL.md?raw" -o $D/imagine/SKILL.md curl -fsS "$BASE/imagine/agents/openai.yaml" -o $D/imagine/agents/openai.yaml chmod +x $D/oracle/scripts/extract_codex_conversation.py $D/oracle/scripts/run_round_robin.sh npx skills add ./$D --skill '*' -y ``` To install a single skill instead of all six, change the last line, e.g. `npx skills add ./oracle-skill-family --skill oracle -y`. After installing, verify: `.agents/skills/<name>/` in the project must contain every downloaded file (multi-file skills keep their `references/` and `scripts/` subfolders). Reference ID: factory-reasoning-and-video-practice Topic: Verification Sources: - [Independent reasoning and video evidence](https://shiny-rosette-m6zy.here.now/) - [Public setup contract](https://shiny-rosette-m6zy.here.now/agent.md) --- # Independent reasoning and video evidence — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The premise Isn’t maximum intelligence just an API call away? Why all this browser theater? It isn’t. ChatGPT’s strongest tier — the model picker’s “Latest” row, currently GPT-5.6 Pro with Extended thinking — is a subscription feature of the chat product, not the API. And Gemini’s video understanding is only reachable through the page’s own upload widget. The strongest text model and the only real video-watching path both sit behind logged-in chat sessions. Whoever holds a valid session cookie holds the key — and after one human login, the whole setup is this: ``` text npm install -g @steipete/oracle # or: brew install steipete/tap/oracle (Node 22+) oracle --engine browser -p "HI" # first handshake: copies your cookies, sends "HI" oracle status --hours 72 # the reply is recorded as a replayable session ``` Hold on — cookies? How does an agent log into ChatGPT? It doesn’t. You do, once, in your normal Chrome. Oracle copies those session cookies into a temporary automation profile and then drives that profile like a very fast reader — same model picker, same upload widget a human sees: ``` text you (human) ──sign in once──▶ Chrome profile (chatgpt.com cookies) │ cookies copied per run agent ──▶ oracle CLI ──▶ automation Chrome profile ──▶ chatgpt.com ──▶ GPT-5.6 Pro │ └─ packx bundle (up to ~900k tokens of code) pasted/attached ``` An API integration authenticates as a program and gets program-shaped limits. A cookie-borrowing browser authenticates as *you* and gets everything your subscription gives you. ## The economics A consult takes 20–60 minutes. Isn’t that unusable? Unusable if you spend it like a chat message. “What’s the next change?” is a banned prompt shape — it spends an hour of frontier thinking on minutes of work. The contract is: every consult demands the **maximum actionable batch** — ordered work packages with exact file/function/test targets and a falsifiable verification each. This is the prompt behind ~1,978 real sessions, verbatim: ``` text [<three-to-five-word-slug>] ## Project briefing <stack, framework, runtime, and repo rules — two or three sentences> ## Goal <the full outcome you want, stated as the whole contract Oracle must plan against — never pre-shrunk to a first step> ## Prior-State Ledger - prior_oracle_session: none - implemented_since_prior_oracle: none - verified_since_prior_oracle: none - failed_proof_or_blocker: none - remaining_goal_coverage: the full goal above ## Current evidence <attempts, failing logs, screenshots, and known constraints — or "none yet"> ## Bundle map The attached files contain <what you included and why>. Possibly missing: <what you could not include>. ## Deliverable Return the maximum actionable batch: an ordered set of work packages covering everything worth doing toward the goal. Every work package must carry exact file/function/test targets, critical code snippets, and a falsifiable verification. Sequence the packages, name risks and invariants, and put anything you cannot target exactly in a separate short "needs investigation" list. Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. Plan the maximum actionable batch: cover everything worth doing toward the goal in ordered work packages with exact file/function/test targets and a falsifiable verification each. Do not return a single next step or hold work back for a later round. An ambitious, specific answer is correct; only untargeted vagueness is a defect. ``` ``` text oracle --engine browser -p "$(cat consult-prompt.md)" \ --file "src/**/*.ts,docs/**/*.md" --slug "<three-to-five-word-slug>" ``` Be honest — do you actually use this, or is it a demo trick? The local archive held about 1,978 session folders in the observed snapshot, and it grows daily. A sample of what they ask: The recurring consult shapes are repeated hardening audits, independent multi-angle review followed by a judge, forensic debugging, redesign planning, and planning a media-analysis pipeline before executing it. The recurring shapes: iteration audits where a fresh frontier reviewer re-reads the codebase every loop, multi-angle panels where a judge consult picks the winner, and pipeline-planning-the-pipeline. Every session leaves `output.log` and token receipts, replayable with `oracle session <id> --render`. ## The video claim Video? Text models can’t watch video. Right — and neither can an API text pipeline. Gemini watches footage, but only through the page’s upload widget, which is exactly what Oracle’s browser hands can operate. Before any expensive run, you prove the upload path with a cheap sentinel probe: ``` text [video-upload-smoke-probe] This is an attached-video readiness probe for a longer video analysis run. Confirm that you can inspect the attached video. Return exactly three short bullets: - whether video frames are visible; - whether audio is detectable; - one strictly observed visual detail, without guessing. End with this exact sentinel on its own line: END_OF_VIDEO_ANALYSIS video-upload-smoke-probe probe ``` ``` text oracle --engine browser --model gemini-3-pro --browser-attachments always \ -p "$(cat probe-prompt.md)" --file "/absolute/path/to/probe-clip.mp4" \ --slug "video-upload-smoke-probe" ``` Pass rule: the sentinel comes back byte-exact and the observed detail matches your footage. In the real Loop Craft run, Gemini heard “we are going to talk about Loopcraft…” and identified the presenter’s picture-in-picture at the 00:30 mark — that is watching, not transcript-summarizing. The result is public: a 93-minute workshop became the [Loop Craft wiki](https://silken-ferry-63mw.here.now/). Browser automation is the most fragile thing in computing. Why build on it? It is fragile — UI drift, model pickers, upload races. The discipline is what turns it into infrastructure: probes before spends, exact sentinels, receipts for every session. In the Loop Craft run, two probe failures cost seconds each; shard 004 failed twice while its siblings passed, which pointed at the input, and an exact re-encode fixed it in one try — 73 seconds to a completed analysis ending in the exact sentinel. Classify the failure, change one variable, re-run the cheap proof, keep the fix. The whole run is replayed beat by beat in the [session replay](https://shiny-rosette-m6zy.here.now/replay.html). ## The setup Do I need your Mac mini and a four-slot browser pool? No. The laptop version is the whole setup: sign into ChatGPT in Chrome, run the handshake, done. The Mac mini is the same trick made multi-tenant — an always-on machine runs `oracle serve` with the signed-in Chrome, every other machine points at it over a private network, and a four-slot dual-account pool runs four hour-long consults at once while nobody’s laptop stays open. Start local; scale only when consults start queuing. To get the local version working right now, hand this to your own agent: ``` text Fetch https://shiny-rosette-m6zy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` And if you want the actual skills that orchestrate all of this, the full skill family is [attached on the index](https://shiny-rosette-m6zy.here.now/index.html#attachments-the-oracle-skill-family) — download, install, adapt. Reference ID: factory-reasoning-and-video-questions Topic: Verification Sources: - [Independent reasoning and video evidence — questions and tradeoffs](https://shiny-rosette-m6zy.here.now/dialogue.html) --- # Independent reasoning and video evidence — reference patterns Extended explanations, comparisons, experiments, and practical actions for the same operating pattern. ## Abstract The strongest reasoning models in this pipeline sit behind chat subscriptions, not APIs. The Oracle tool answers that constraint directly: it drives a real Chrome browser into chatgpt.com and gemini.google.com, authenticated by cookies copied from a profile a human already logged into. This document shows how that works locally in one command, how one operator scales it to an always-on remote pool, why consult prompts must demand a maximum batch of work, and how cheap sentinel probes make fragile video uploads dependable. The evidence is one operator's local records from May–the recorded workflow — about 1,978 consult sessions plus a fully receipted video run. The sources support no claims about cost curves, provider terms, or other people's setups. ## Notice where the strongest models actually live Before you design an agent's "phone a smarter friend" move, check where that friend answers the phone. The easy assumption is an API call. The record here says otherwise. The Oracle fork's README (S1) states that browser mode targets ChatGPT's latest Pro tier by selecting the model picker's "Latest" row — currently Pro 5.5 with Extended thinking — with no API key involved. [1](https://shiny-rosette-m6zy.here.now/#note-1) 1\. S1 also lists an API mode with explicit model IDs. But the consult contract (S2) forbids it for this pipeline: every consult must run with the browser engine, and an API-key error means the caller made a mistake, not that a credential is missing. [↩](https://shiny-rosette-m6zy.here.now/#note-ref-1) The video side is stricter. The oracle-video contract (S4) requires Gemini through the browser engine because the file upload happens in the page itself — the API path cannot upload the browser video at all. So the mistake to avoid is treating "maximum intelligence" as an API shopping question. In this record it is an access question: the strongest text model and the only real video-watching path both sit behind logged-in chat sessions. Whoever holds a valid session cookie holds the key. **Evidence limit** The sources describe capability and access, not permission. They do not discuss provider terms of service or account risk, so this document cannot tell you whether the trade-off is acceptable for your accounts. ## Explain how an agent borrows your browser You should be able to say the whole mechanism in one breath, because your audience will ask. Here it is: a human signs into ChatGPT in normal Chrome once; Oracle copies those session cookies into a temporary automation profile; the agent then drives that profile like a very fast reader who pastes a huge bundle of code and waits. Per S1, first-time setup is a single command run after the human login, and later runs re-read cookies from the logged-in profile each time. ``` text # 1. Sign into ChatGPT in your normal Chrome profile (human, once). # 2. Let Oracle copy those cookies into its automation profile: oracle --engine browser -p "HI" ``` Source: the fork README's macOS browser-mode setup (S1), quoted command verbatim. What rides along with the cookies is context: the consult skill (S2) bundles project files with a packer and currently validates browser-mode bundles up to roughly 900k tokens. [2](https://shiny-rosette-m6zy.here.now/#note-2) 2\. S2 phrases this as a target: "Current validated browser-mode bundle target: up to ~900k tokens," with a config knob for files over 10 MiB. The point for a demo audience: this is whole-project context, not a snippet. [↩](https://shiny-rosette-m6zy.here.now/#note-ref-2) The contrast that makes this click: an API integration authenticates as a program and gets program-shaped limits. A cookie-borrowing browser authenticates as *you* and gets everything the chat product gives you — the model picker, extended thinking modes, and the file-upload widget that the video pipeline depends on. **Evidence limit** S1 calls browser automation experimental and stable mainly on macOS. Treat "one command and it works" as the happy path, not a reliability claim; the probe discipline in the later sections exists precisely because this path breaks. ## Compare the laptop setup with an always-on pool Decide which of two shapes you need before you copy anything from this record. Most people need the first one. **Shape one — local:** Oracle runs on your own machine and borrows your own Chrome cookies (S1). Setup is the login handshake above. This is the shape the fork README documents for everyone. **Shape two — remote service:** S1 documents an `oracle serve` mode: a signed-in host exposes its browser to remote clients. In this operator's config (S5), every machine points at an always-on Mac mini over a private tailnet; the cookies live once, on that host. ``` text laptop agent ─▶ oracle CLI ─▶ config: remote host + token │ (private network) ▼ Mac mini: `oracle serve` + signed-in Chrome (cookies live HERE, once, for every client) ``` **Figure 1.** Derived display: the remote topology, redrawn from the operator's config structure (S5) and the README's remote-service description (S1). Host addresses and the token are deliberately replaced with placeholders. Text consults go one step further: the skill's default transport (S3) is a qualified four-slot pool — two ChatGPT accounts, each with two isolated Chrome workers, so four consults run concurrently without sharing a browser profile. [3](https://shiny-rosette-m6zy.here.now/#note-3) 3\. S3 pins the whole topology — build hashes, ports, tokens — and verifies it before every run, with a FIFO queue where only the oldest waiter probes for a free slot. Those pinned values are private and are not reproduced here. [↩](https://shiny-rosette-m6zy.here.now/#note-ref-3) The decision rule the contrast supports: stay local until concurrency or an always-on machine is the actual bottleneck. The pool's value is not speed of one consult — it is running four twenty-to-sixty-minute consults at once while nobody's laptop stays open. **Evidence limit** The pool is qualified against one exact build and topology (S3). The sources give no evidence it transfers to other machines or accounts without redoing that qualification. ## Choose prompts that repay an hour of thinking A consult costs 20–60 minutes of wall clock (S2). The likely mistake is spending that hour the way you'd spend a chat message: "what should I do next?" The contract bans exactly that. S2's operating principle: every prompt must push toward "the maximum actionable batch" — an ordered set of work packages with exact file, function, and test targets, each carrying a falsifiable verification. Asking for "one next shippable slice" is named as a wasted consult. What does an archive shaped by that rule look like? In the observed snapshot the sessions directory held about 1,978 consult folders (S5). Table 1 samples real prompt previews. | Session | What it asked Oracle to do | |----|----| | `actions-parent-lifecycle-third` | Review iteration 3 of a 12-iteration hardening audit of a Rust/GPUI app | | `agent-chat-angle-one/-two/-three` | Verify one commit from three independent angles, in parallel | | `agent-chat-final-review` | Judge the three angle-consults against each other and pick the solution | | `actions-popup-scrollbar-fix` | Forensic hunt for a scrollbar bug from a user report | | `agenda-fresh-redesign` | Produce a full redesign plan for a slide-generating repo | | `loopcraft-segmentation-review` | Design the video-sharding strategy that the next section executes | **Table 1.** Derived display: sampled session slugs and paraphrased prompt previews from the local session archive (S5). Paths shortened; selection is editorial, not random. Replayability comes with the archive: S1 documents `oracle status`, `oracle session <id> --render`, and `oracle restart <id>`, and each session folder stores the model's full output log (S5). Your practice, next time you draft a consult: read your prompt and ask whether the answer could keep a local agent busy for hours. If it could be answered in one paragraph, you wrote a chat message, not a consult. Rewrite it to demand the whole ordered batch — targets, snippets, and a verification per package. **Evidence limit** The session count and samples show scale and shape of use. The sources contain no measured comparison of consult quality against cheaper prompting, so "repays the hour" is the contract's premise, not a measured result. ## Test fragile paths with sentinel probes before spending Video is where the browser trick earns its keep — and where it is most fragile. Uploads race, model pickers drift, fresh chats initialize slowly. The Loop Craft run (S6) shows the discipline that makes this survivable: never start an expensive analysis on a path you have not just proven with a cheap probe. The run's goal, from the original session (S6): take a public 93:49 YouTube workshop about the "Loopcraft" durable-agents project and build it into an extensive published wiki with resources, pull quotes, and copy-paste prompts. A probe is a one-line contract. One real example (S6): "Inspect the attached video itself. Reply with exactly this single line and nothing else:" ``` text ATTACHED_VIDEO_OK loopcraft-awaited-upload-probe ``` Source: prompt preview of session `loopcraft-awaited-upload-probe` (S6). Gemini returned the exact line from the real MP4, proving the upload path before any long run. | Time | Step | Model | Outcome | |----|----|----|----| | 16:39–16:40 | First upload probes | gemini-3-pro | error — path not ready | | 16:43 | Probe after service rebuild | gemini-3-pro | completed | | 16:46 | Segmentation plan review | gpt-5.5-pro | completed — shard strategy for the 93:49 video | | 17:00–18:30 | Chunk-analysis attempts | gemini-3-pro | repeated errors | | 18:09 | Awaited-upload probe | gemini-3-pro | completed — exact sentinel returned | | 18:40–18:53 | Source-native shards 001–003 | gemini-3-pro | completed, sentinel-verified | | 18:53, 19:07 | Shard 004 and retry | gemini-3-pro | error | | 19:12–19:20 | Shard 004, re-encoded | gemini-3-pro | completed — see next section | **Table 2.** Derived display: the Loop Craft run of the recorded snapshot, reordered into a timeline from session metadata timestamps and statuses (S6). Times UTC. The shard analyses show Gemini genuinely watching, not summarizing a transcript: it heard "we are going to talk about Loopcraft…" and identified the GitHub workshop page with the presenter's picture-in-picture at the 00:30 mark (S6). The signal you are looking for, in your own runs: the sentinel line comes back byte-exact. Anything else — a paraphrase, extra prose, silence — means the path is broken and the long run would have burned an hour to find that out. **Evidence limit** Table 2 compresses many sessions; some intermediate error attempts are omitted, and the timeline's "outcome" column paraphrases status fields. The full receipts remain in the operator's local session folders and are not published. ## Adjust when a run fails instead of abandoning it Shard 004 is the teachable failure. Two attempts errored while three sibling shards sailed through, which rules out "the pipeline is down" and points at the input itself. Per the session record (S6), an exact re-encode of that shard solved it completely: the rich analysis finished in 73 seconds and ended with the exact sentinel. The re-encode settings were preserved as the durable media recipe for future runs. Publication got the same skepticism as analysis. The agent source-checked pull quotes against the shard analyses, and after publishing it fetched the live pages rather than trusting the publish receipt; both URLs returned HTTP 200 (S6, re-verified S7 in the observed snapshot). The result is public: the [Loopcraft workshop wiki](https://silken-ferry-63mw.here.now/) and its [video companion](https://silken-ferry-63mw.here.now/video-companion/) (S7) — a 93-minute recording turned into a permanent, quotable artifact in one working session. The adjustment loop to copy: classify the failure (encoding, not automation), change one variable (re-encode), re-run the cheap proof (sentinel), then keep the fix as a recipe so the next run starts smarter. Deleting the run and starting over would have discarded exactly the knowledge that made shard 004 pass. **Evidence limit** The sources record that the re-encode worked, not why the original encoding failed inside Gemini. Treat the recipe as an empirical fix, not a diagnosis. ## Practical action If you want the local shape this record supports, do this, in order. Sign into ChatGPT in your normal Chrome. Run the one-command handshake from the second section and confirm a reply comes back. Then draft your first real consult against the maximum-batch rule: ordered work packages, exact targets, a verification per package. When you move to video, write the sentinel probe before you write the analysis prompt, and do not start the long run until the sentinel returns byte-exact. Keep every session folder — statuses, logs, and failed probes are the dataset your next debugging session will need. Success signal: your archive starts to look like Table 1 — audits, panels, and plans — rather than a pile of "what next?" chats. Failure signal: consults that finish in minutes with answers you already knew; tighten the prompt, not the model. Reference ID: factory-reasoning-and-video-reference-patterns Topic: Verification Sources: - [Prepared module reference](https://shiny-rosette-m6zy.here.now/) --- # Independent reasoning and video evidence — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## Before the session: the only beat a human owns You Sign into chatgpt.com and gemini.google.com in your normal Chrome — then hand the keys over: ``` text oracle --engine browser -p "HI" ``` Agent Oracle copies the session cookies from that logged-in profile into a temporary automation profile, opens ChatGPT in an automated Chrome, sends the prompt, and records the reply as a session. Any reply proves the cookie path works. Cookies are the entire auth story. No API keys — the browser authenticates as *you* and gets everything the subscription gives you: the model picker, extended thinking, and the upload widget the video pipeline depends on. ## The session, beat by beat You `$oracle-video https://www.youtube.com/watch?v=uC6slhCTXlA` — Built this up into an extensive `$here-now` workshop wiki with extensive resources/pull quotes/and ai prompts to copy/paste That is the whole human contribution to the run — one prompt naming a public 93:49 YouTube workshop ("Building Durable Autonomous Agents", the Loopcraft project). Everything below is the agent working. Agent Sized up the source: 93 minutes and 49 seconds of screen-heavy workshop footage. No text model can watch that — only Gemini genuinely watches video, and only through the page's own upload widget. Plan: cut the recording into source-native shards Gemini can watch one at a time. The first decision is a routing decision: text questions go to GPT-5.6 Pro, footage goes to Gemini — both through the same browser hands. Agent Before touching video, asked the strongest text model to review the plan. Session `loopcraft-segmentation-review` (gpt-5.6-pro, completed): GPT-5.6 Pro reviewed how to shard a 93:49 recording so Gemini gets watchable, source-native chunks. Planning the pipeline with the pipeline: maximum intelligence supervises the video intelligence before a single expensive run starts. Agent Probed before spending. A battery of cheap sentinel runs on gemini-3-pro, each asking for exactly one line back: ``` text loopcraft-video-smoke-probe error loopcraft-video-probe-retry error loopcraft-video-probe-rebuilt completed loopcraft-submit-proof-probe completed loopcraft-awaited-upload-probe completed └─ reply: ATTACHED_VIDEO_OK loopcraft-awaited-upload-probe ``` Two failures cost seconds each. Only after the sentinel came back byte-exact — from the real MP4 — did the long runs start. The generalized probe, liftable: ``` text [video-upload-smoke-probe] This is an attached-video readiness probe for a longer video analysis run. Confirm that you can inspect the attached video. Return exactly three short bullets: - whether video frames are visible; - whether audio is detectable; - one strictly observed visual detail, without guessing. End with this exact sentinel on its own line: END_OF_VIDEO_ANALYSIS video-upload-smoke-probe probe ``` ``` text oracle --engine browser --model gemini-3-pro --browser-attachments always \ -p "$(cat probe-prompt.md)" --file "/absolute/path/to/probe-clip.mp4" \ --slug "video-upload-smoke-probe" ``` Probes before spends: a falsifiable one-line sentinel proves the fragile path (upload, submit, encoding) before an hour-long analysis bets on it. A paraphrase or silence means the path is broken. Agent Watched the shards. Sessions `loopcraft-workshop-shard-001…004` (gemini-3-pro): each shard analyzed for the wiki, each analysis required to end in its exact sentinel. The results prove Gemini genuinely watched the footage — it heard "we are going to talk about Loopcraft…" and identified the GitHub workshop page with the presenter's picture-in-picture at the 00:30 mark. Timestamped screen evidence — slides, terminal output, picture-in-picture — is the thing a transcript summarizer cannot produce. Agent Shard 004 errored — twice — while its three siblings sailed through. That pattern rules out "the pipeline is down" and points at the input. Diagnosis: a media-encoding problem. An exact re-encode fixed it completely: the analysis finished in 73 seconds with the exact sentinel, and the re-encode settings were kept as the durable media recipe for future runs. Failure handled like engineering, not vibes: classify the error, change one variable, re-run the cheap proof, keep the fix. Agent Verified, then published. Pull quotes were source-checked against the analyses, the site build passed its checks with zero errors, and after publishing the agent curled the *live* URLs rather than trusting the publish receipt. The result is public and permanent: the [Loop Craft workshop wiki](https://silken-ferry-63mw.here.now/) and its [video companion](https://silken-ferry-63mw.here.now/video-companion/). One working session: a 93-minute recording became a quotable artifact anyone in the room can open right now — not a chat log. ## Where it landed: the shard prompt, verbatim This exact prompt produced shard 001 of the wiki — it is the money artifact of the run. Swap the metadata block and the sentinel for your own video; keep the evidence rules, because they are what stop Gemini from inventing commands, URLs, and speakers. ``` text [loopcraft-workshop-shard-001-source-native] Analyze the attached source-native video shard for an extensive public workshop wiki. Metadata: - run_key: loopcraft-agent-workshop - shard_id: 001 - original recording range: 00:00:00–00:04:00 - publication chapter: Workshop Setup and the Looping Resolver Evidence rules: 1. Use original workshop timestamps from 00:00:00 through 00:04:00. 2. Separate spoken evidence, visible screen evidence, and inference. 3. Listen to the audio; do not rely on automatic captions. 4. Do not invent commands, URLs, files, tools, speakers, or UI labels. 5. Pull quotes must be brief (under 20 words), audio-verified, attributed to Joel Hooks, and timestamped. 6. Exclude credentials, account details, local paths/usernames, private URLs, signed URLs, notifications, or incidental personal data. 7. Treat opinions and live-demo observations as such, not universal facts. 8. Derived prompts must use placeholders, be clearly labeled as inspired by the workshop, and require confirmation for destructive or externally visible actions. Return dense Markdown with these sections: # Shard 001 — 00:00:00–00:04:00 ## Executive Takeaway ## Dense Timeline ## Concepts and Mental Models ## Visible Demo Evidence ## Architecture and Workflow Patterns ## Tools, Commands, and References ## Pull Quote Candidates ## Copy/Paste AI Prompt Candidates ## Student Exercises and Reflection Questions ## Keyframes to Capture ## Uncertainties and Publication Review ## Machine JSON The fenced JSON object must contain: shard_id, original_range, summary, timeline, concepts, workflows, demos, resources, quotes, prompts, exercises, keyframes, warnings, unanswered_questions. End with this exact sentinel on its own line: END_OF_VIDEO_ANALYSIS loopcraft-agent-workshop shard-001 ``` For the text-consult side of this section — the maximum-batch consult prompt and the full agent setup — go back to the [section guide](https://shiny-rosette-m6zy.here.now/index.html), or hear the skeptical version in the [dialogue](https://shiny-rosette-m6zy.here.now/dialogue.html). The full Oracle skill family behind this run is [attached on the index](https://shiny-rosette-m6zy.here.now/index.html#attachments-the-oracle-skill-family), downloadable and installable. Reference ID: factory-reasoning-and-video-worked-example Topic: Verification Sources: - [Independent reasoning and video evidence — worked example](https://shiny-rosette-m6zy.here.now/replay.html) --- # Make the repository agent-ready A background workflow is only useful when the agent can **prove what it changed**. Start by giving the repo a **verification loop**. Then move repeated, narrow jobs into tiny tool-shaped agents that carry only the context they need. ## Budget The Intelligence The point is not to throw every task at the biggest possible context window. Decide where broad planning belongs, then **keep the local work loop focused** on files, commands, checks, and saved decisions. ## Use Goals For Long Work Long-running work needs a plan that can survive time away from the keyboard. Ask for the **full step list first**, then plan each step before implementation. The local agent should execute one step, verify it, and leave enough context for the next step to make sense. ## Make Done Observable An agent-ready repo lets an agent **read the code, write the change, and verify the result**. If the app lacks browser-style debugging, logs, snapshots, smoke tests, performance hooks, or a reliable local command, build the feedback loop before trusting automation. > The agent needs to be able to read the code, write the code, and verify the code. > > — John Lindquist ## Keep The Terminal Thread Small Custom terminal workflows matter because the agent needs a reliable surface for invoking repeatable project actions. Keep detailed [zsh](https://zsh.sourceforge.io/Doc/Release/Functions.html), shortcut, and orchestration setup in tool-specific docs until the commands are verified. ## Use Imps For Narrow Jobs An **[imp](https://github.com/johnlindquist/codex-imps)** is a small, tool-shaped agent for a repeated job. It should know the **exact tool, examples, files, and conventions** it needs. It should not carry every skill, memory, search tool, and integration by default. > You give it as much context as you want, so that it's as smart as you need it, like, out of the gate. > > — John Lindquist ## Strip The Extras A narrow imp can **turn off broad features** until the task actually needs them. That keeps the context window pointed at the job instead of at the whole operating system. ## Do Not Improvise Secrets Credential and token isolation is a **security design item, not a copy-paste recipe**. Keep account state, vault layout, token names, subscription details, local storage, and private setup notes out of public instructions until they have been reviewed deliberately. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#agent-ready-repos) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-agent-ready-repos Topic: Verification Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#agent-ready-repos) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Mark the debug moment before handoff Logs show what happened. **A marker says which moment mattered.** Use **[Agent Markers](https://github.com/johnlindquist/agent-markers)** when a bug appears during real app use and the next agent needs more than a sentence and a screenshot. The move is to mark the decisive moment while it is happening, capture nearby runtime evidence, add the human explanation, review the packet, and export only what is safe to share. ```text mark -> capture -> explain -> review/export ``` ## The Problem You found the bug while using the app. The checkout button stayed disabled, the billing retry fired twice, the auth session rotated at the wrong time, or the date rendered in the wrong format. > We're interacting with an app, we're clicking on buttons, and we're typing in fields, and then something happens, and we want to be able to capture that specific moment. We don't want to have to quit our app, start up debugging mode. > > — John Lindquist The old ritual is expensive: - add temporary logs - reproduce the bug - forget which log line mattered - remove the logs - hope the next agent understands the state you saw A debug marker **preserves the moment** without turning the whole session into a permanent logging project. ## Bounded Debug Packets A **bounded debug packet** is a small export centered on one marked moment. It can include: - the marker label and note - nearby console, fetch, error, unhandled rejection, and manual events - route, viewport, and environment metadata - optional DOM or screenshot evidence - the privacy review boundary - the first verification command for the next agent It is not a replay system, production telemetry, a browser extension, a server product, or an AI product. It is a reviewed packet for debugging work. ## Smallest Setup ```ts import { createAgentMarkers } from "<verified-agent-markers-client>"; const markers = createAgentMarkers({ appName: "checkout-demo", exposeGlobal: true }); await markers.mark("Checkout button stayed disabled", { note: "Expected it to enable after selecting shipping.", tags: ["checkout", "regression"] }); const session = markers.export(); ``` `createAgentMarkers` sets up a browser-side collector. It can mark moments, record manual events, export a `DebugSession`, optionally expose a dev/test global, and clean itself up with `stop()`. ## The Data Model | Concept | Practical Meaning | |---|---| | `DebugSession` | One bounded debugging run: app name, session id, environment, markers, and events. | | `DebugMoment` | The human marker: label, note, tags, severity, environment, optional data, optional DOM/screenshot evidence, and `nearbyEventIds`. | | `CapturedEvent` | Runtime evidence near the marker: console, fetch, error, unhandled rejection, or manual event. | | `nearbyEventIds` | The bridge between the marked moment and the runtime events captured near it. | | export JSON | The reviewed packet that can be attached to a test run, issue, or agent prompt. | The useful part is **the link between the human explanation and the runtime trail**. Without `nearbyEventIds`, the agent gets a label and starts guessing. With it, the agent gets a bounded slice of the session. ## Privacy Defaults Field rule: **metadata first, values only after review**. Agent Markers is designed around a local review boundary: - data stays in memory until explicit export - storage capture records key names and counts by default, not values - fetch capture records metadata and does not read request or response bodies - treat raw exported sessions as private until reviewed and redacted **Do not share raw exported sessions.** Review and redact private routes, screenshots, stack traces, request URLs, user-entered text, tokens, cookies, account data, local paths, and application-specific identifiers. ## Test Runner And Agent Handoff In dev and test, `exposeGlobal: true` gives a test runner a browser handle: ```text window.__AGENT_MARKERS__ ``` A browser test can reproduce the bug, call `mark(...)`, export JSON to a private test artifact, and attach or share only a reviewed and redacted packet. The next agent gets **a bounded packet instead of a vague report**. > You can take that kind of entire session, you can copy and paste the logs into your agent. And tell it, please review for the markers and help me get this fixed. > > — John Lindquist Treat the redaction helper below as project-specific review code, not an Agent Markers API. ```ts const session = await page.evaluate(async () => { await window.__AGENT_MARKERS__.mark("checkout disabled unexpectedly", { note: "Expected submit to enable after terms and shipping were selected." }); return window.__AGENT_MARKERS__.export(); }); const redactedSession = redactAgentMarkerSession(session); await testInfo.attach("agent-markers.redacted.json", { body: JSON.stringify(redactedSession, null, 2), contentType: "application/json" }); ``` Import from the reviewed Agent Markers client in the current project. Verify the package or workspace path before turning this into executable setup. The handoff prompt should tell the agent: - what the human expected - what happened instead - which event ids are nearby - what is intentionally redacted - where to start verification - what not to infer from missing data ## Clean Up Call `stop()` when the collector is done. The collector installs capture hooks for useful evidence. `stop()` disposes those hooks. After `stop()`, treat the collector as finished instead of continuing to mark new moments. ## Copyable Artifact: Bounded Debug Packet ```text Marker: - label: - note: - expected: - actual: - next action: Session: - schemaVersion: - sessionId: - appName: - markerId: - nearbyEventIds: Included evidence: - console: - fetch: - error: - unhandledrejection: - manual: - DOM or screenshot availability: Privacy review: - storage values exported? no - request bodies exported? no - response bodies exported? no - private routes removed? - user-entered text removed? - stack paths reviewed? - screenshot reviewed? Handoff: - first verification command: - files or areas to inspect: - what the agent must not infer: - stop condition: ``` Example prompt: ```text Use this bounded debug packet to investigate the checkout disabled-state bug. Start from the marker note and nearbyEventIds. Do not assume redacted fields are absent in the app. Inspect the checkout form state, shipping selection flow, and submit-button disabled logic. Return the likely cause, smallest patch plan, and first verification command before editing. ``` ## Claim Boundaries Agent Markers gives the next agent a better packet. It does not guarantee the agent will find the defect automatically. Use it for local development, browser tests, and reviewed debugging artifacts. Verify any production use, data retention policy, screenshot capture, source-map behavior, and privacy implications before adopting it in a real product. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#debug-marker) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-debug-marker Topic: Verification Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#debug-marker) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Review generated UI before building A generated mockup is useful when it gives you **something concrete to inspect**. Do not jump from one polished image to implementation. Keep the source visual, choose a controlled style direction, generate against that direction, review the result, then hand the chosen direction to a build pass with explicit constraints. ## Start From A Real Visual Use an existing screenshot, mockup, or product frame as the anchor. The agent should know **what it is changing** instead of inventing the whole interface from scratch. For product work, this could be a checkout screen, a settings panel, a saved listings card, or a dashboard slice. The point is to **keep the job of the screen stable** while the visual direction changes. ## Name The Style Before Generating Ask for a **numbered list of style directions** first. Then refer to the style by number in the next prompt. That gives the agent a stable design target instead of asking it to invent the language at the same time it generates the mockup. > As long as you have that list ahead of time. So that, just in time, it doesn't have to come up with new ideas. You'll have much better results. > > — John Lindquist ## Generate Against One Direction Use the **selected style as the variable**. Keep the screen purpose, product type, data model, and interaction intent stable. If the source is a saved listings mobile screen, the generated version should still help someone scan saved listings. The typography, surface treatment, spacing rhythm, or color system can change. The task should not quietly become a different product. ## Review The Image As Evidence Treat the generated image as **review material, not finished UI**. Check what changed, what survived, what broke, and whether the result is still reasonable to build. Review against: - Did the screen keep the same job? - Did the primary action stay obvious? - Did the content survive the style change? - Is the spacing intentional or just empty? - Would this be reasonable to implement? - What should the build pass preserve? - What should the build pass reject? ## Hand Off To A Build Pass The next step is not more wandering. Tell the agent **what won, why it won, what to preserve, what to fix, and what proof counts**. ```text Use the selected generated mockup as the visual reference. Build a real implementation of this direction. Preserve: - the accepted layout structure - the visual hierarchy - the selected spacing rhythm - the core interaction model Fix: - unreadable text - impractical spacing - missing accessibility states - inconsistent component behavior Verification: - run the project checks - capture desktop and mobile screenshots - compare the result against the selected mockup - list any visual mismatches that remain Do not restart the visual exploration. ``` ## Copyable Prompt: Controlled Visual Variation ```text Use the provided UI screenshot as the source visual. Goal: Create a new visual direction for the same mobile screen. Style direction: Use style 6 from the saved style list. Keep unchanged: - screen purpose - information hierarchy - primary user action - core data shown on the card - mobile-first layout Change only: - visual style - spacing rhythm - typography feel - surface treatment Return: - one generated mockup - a short review of what changed - what must be preserved in a real implementation ``` ## Branch Useful Context When a design conversation starts working, **name it and fork it** before trying a risky direction. A fork is a saved branch of useful context. Use it for experiments you may abandon. Do not depend on throwaway side chats for work you might need later. > A side chat in an ephemeral fork. I'm not a fan of those. I don't like ephemeral things with agents. I never want to lose anything. > > — John Lindquist ## Carry Forward: Workspace Layouts This workflow creates repeated surfaces: source visuals, style lists, generated variants, review notes, implementation passes, and screenshots. Workspace layout matters once the build pass begins: keep the accepted visual direction, implementation files, and verification screenshots easy to compare. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#visual-review) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-visual-review Topic: Verification Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#visual-review) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Self-improving log-gated fix loop playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already run local dev servers, browser checks, test scripts, and agent panes; this technique turns those runtime artifacts into proof instead of vibes. It matters because UI bugs, auth regressions, and hook failures are often only obvious in logs, browser state, or terminal output, not in the agent's final message. [Core principles](/topics/foundations-deterministic-verification-and-boundaries/) ## Copy-paste workflow **When to use:** When you need to KNOW an agent really verified its work, not just trust a happy completion message. This captures the exact terminal failure, feeds it back to harden the tool, and gates fix/verify behind structured logs a supervisor compares. ### Copy-paste prompt ```text You are my coding agent. Don't trust completion messages — prove the work with logs. Run this self-improvement + log-gated verification loop on <TOOL/WORKFLOW>. 1. Capture the EXACT terminal failure state as clean text (don't summarize it from memory). In CMUX, use the terminal-text extraction to grab the real output: cmux read-screen Use that real text as context. 2. Use this prompt shape against the failure — state the goal, paste the failure after a colon, then ask for a root-cause fix: "Goal: <GOAL>. Here is the exact failure: <PASTE TERMINAL TEXT>. Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time." 3. Make verification CONCRETE and deterministic. The fix must write structured logs / JSON artifacts / timestamps to disk on each run. Then a supervisor agent runs the scenarios, waits, and COMPARES expected-vs-actual fields in those log files. That comparison is the gate — only pass when the fields match. Guardrails: keep worker agents narrow and tool-limited; keep the orchestrator context-rich. REDACT secrets from logs. ``` ### How it works - Capture the exact terminal failure as clean text (via CMUX `cmux read-screen`) rather than a memory summary, and use it as real context. - The prompt shape — goal, then the failure after a colon, then "explain why it failed and patch the workflow" — drives a true root-cause fix, not a band-aid. - Verification is made concrete: the workflow writes structured logs / JSON artifacts / timestamps, and a supervisor agent runs scenarios and compares expected-vs-actual fields. That field comparison is the deterministic gate. - Keep worker agents narrow and tool-limited; keep the orchestrator context-rich. - Redact secrets from logs. - Reference: [codex-daemons](https://github.com/johnlindquist/codex-daemons), [CMUX](https://github.com/manaflow-ai/cmux). ## Reusable skill Install as `~/.agents/skills/log-gated-verification/SKILL.md`, then restart Codex. ````markdown --- name: log-gated-verification description: Trigger when you must prove an agent actually verified work rather than trusting a completion message — write structured logs/artifacts and have a supervisor compare expected-vs-actual fields (a deterministic gate). Do NOT trust self-reported success. --- # Log-gated verification Prove work with logs instead of trusting completion messages. Capture the exact failure, patch the workflow to cover it, and gate fix/verify behind structured logs a supervisor compares field-by-field. ## Steps 1. Capture the EXACT terminal failure state as clean text (not a memory summary). In CMUX, extract the real terminal output: ```bash cmux read-screen ``` Use that real text as context. 2. Use this prompt shape against the failure — goal, then the failure after a colon, then the fix request: ``` Goal: <goal>. Here is the exact failure: <paste terminal text>. Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time. ``` 3. Make verification CONCRETE and deterministic: the workflow must write structured JSON logs / timestamps / payload snapshots to disk on each run. 4. A supervisor agent runs the scenarios, waits, and COMPARES expected-vs-actual fields in those log files. That field comparison is THE GATE — pass only when the fields match. ## Guardrails - Do NOT trust self-reported success; the log comparison is the source of truth. - Keep worker agents narrow and tool-limited; keep the orchestrator context-rich. - REDACT secrets from logs. ```` ## Scenarios ### Auth redirect loop with browser evidence **Role:** As a full-stack Next.js developer maintaining an authenticated dashboard A local Next.js app sometimes redirects logged-in users from /dashboard back to /login after a route middleware or session-cookie change. The agent claims the fix works, but the team needs proof from the running browser and structured logs. > As a full-stack developer, I want the agent to reproduce the auth redirect failure, capture exact runtime evidence, patch the workflow, and gate success on log comparison, so that I do not merge an auth fix based on a cheerful completion message. #### Agent brief ```text You are my coding agent. Run a self-improving log-gated fix loop for the local auth redirect bug. First inspect the current code and existing verification scripts; do not rely on memory. Start the dev server using the repo's documented command from package.json. Reproduce the flow in a browser: visit /login, sign in with the local/dev credentials or seeded test user documented in the repo, navigate to /dashboard, refresh, and confirm whether the browser stays on /dashboard. Capture exact evidence: terminal output with `cmux read-screen`, browser console/network output if available, and a JSON log artifact at `.notes/log-gated/auth-redirect/run-<timestamp>.json`. The log must include goal, routeVisited, finalUrl, redirectCount, authCookiePresent as true/false when observable, serverStatusCodes, consoleErrors, terminalFailureText when present, and pass boolean. If the first run fails, use this repair prompt shape internally: `Goal: authenticated users should remain on /dashboard after login and refresh. Here is the exact failure: <paste terminal/browser/log evidence>. Explain WHY it failed in this scenario, then PATCH the workflow so this case is covered next time.` After patching, rerun the same browser flow and write a second JSON artifact. A supervisor pass must compare expected-vs-actual fields and only pass when finalUrl is /dashboard, redirectCount is 0 after the authenticated refresh, pass is true, and no new console/server errors appear. Finish with the files changed, commands run, log artifact paths, and a terse review note. ``` #### Implementation references [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) ```text cmux read-screen ``` ```text cmux markdown open .notes/log-gated/auth-redirect/tracker.md --direction right ``` ```text package.json scripts for dev/test commands ``` ```text .notes/log-gated/auth-redirect/*.json ``` #### Browser verification Use a CMUX browser pane or agent-browser-style workflow to take an accessibility snapshot of /login, fill the login form, click submit, wait for navigation, evaluate `window.location.pathname`, refresh, evaluate it again, and capture console/network errors. Browser proof is required here because the bug is about real navigation, cookies, and route behavior. #### Definition of done - At least two structured JSON run logs exist: one reproducing the original failure when possible and one post-fix verification run. - The supervisor comparison explicitly checks finalUrl, redirectCount, status codes, consoleErrors, and pass fields instead of trusting the worker's text. - The final browser state after login and refresh is /dashboard with no unexpected redirect to /login. - The final response lists exact commands run, files changed, and log paths under `.notes/log-gated/auth-redirect/`. #### Failure modes and mitigations - Common mistake: the agent only runs unit tests and declares success. Mitigation: require a browser flow plus JSON log fields proving finalUrl and redirectCount. - Common mistake: logs contain tokens, cookies, or full auth headers. Mitigation: redact secrets and store only booleans, route names, status codes, and sanitized error strings. - Common mistake: the agent tests a stale dev server. Mitigation: restart or verify the dev server command, capture terminal output with `cmux read-screen`, and include the server start timestamp in the log. ### Checkout UI regression behind deterministic artifacts **Role:** As a frontend product engineer responsible for a checkout or upgrade flow A pricing or checkout screen was refactored and now one browser path intermittently disables the primary CTA, misprices a plan, or shows the wrong confirmation state. The workflow needs browser validation plus structured artifacts a supervisor can compare. > As a frontend product engineer, I want an agent to verify the checkout path with browser actions and structured scenario logs, so that regressions are caught by observable artifacts instead of a subjective agent summary. #### Agent brief ```text You are my coding agent. Build a log-gated verification loop for the checkout/pricing flow. Inspect the source files for the pricing/checkout route, the relevant components, and existing tests. Start the local app using the repo's package scripts. Create `.notes/log-gated/checkout/criteria.md` with the expected scenario fields: selectedPlan, displayedPrice, ctaEnabled, confirmationVisible, finalUrl, consoleErrors, networkFailures, and pass. Then run three browser scenarios: default plan selection, switching plans twice, and back/refresh during checkout. For each scenario, write `.notes/log-gated/checkout/<scenario-slug>.json` with timestamp, exact steps, expected fields, actual fields, terminal evidence from `cmux read-screen` when a failure occurs, and pass boolean. If any scenario fails, use the exact failure text and artifact contents to patch the code or workflow, then rerun only the failing scenario plus one happy-path scenario. Add or update a verifier script only if the repo already has a natural place for local scripts; otherwise have the supervisor agent compare the JSON files directly. The gate passes only when all expected-vs-actual fields match and the browser proof agrees with the logs. ``` #### Implementation references [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) ```text cmux read-screen ``` ```text cmux markdown open .notes/log-gated/checkout/tracker.md --direction right ``` ```text .notes/log-gated/checkout/criteria.md ``` ```text .notes/log-gated/checkout/*.json ``` ```text package.json scripts for dev/test commands ``` #### Browser verification Use Playwright, a CMUX browser pane, or an agent-browser-style accessibility snapshot/click/evaluate sequence: open the pricing route, snapshot the buttons and plan labels, click each plan option, evaluate visible price and CTA disabled state, click the CTA, then evaluate the final confirmation URL/state. This is browser-worthy because visual state, disabled controls, and navigation are the product behavior. #### Definition of done - Three scenario JSON logs exist with expected fields and actual fields. - A supervisor comparison marks pass only when selectedPlan, displayedPrice, ctaEnabled, confirmationVisible, finalUrl, consoleErrors, and networkFailures match the criteria. - The agent provides browser evidence for each scenario, either through Playwright output, accessibility snapshots, screenshots, console logs, or explicit evaluate results. - Any fix is tied back to the exact failing artifact and rerun evidence. #### Failure modes and mitigations - Common mistake: the agent overfits to one happy path. Mitigation: require default selection, repeated plan switching, and back/refresh behavior. - Common mistake: the agent writes brittle permanent UI tests for a screen still changing daily. Mitigation: keep these as `.notes/log-gated/checkout/` artifacts unless the repo already has a stable test home. - Common mistake: the browser log and JSON log disagree. Mitigation: make the supervisor compare both and fail the gate until the artifact mismatch is resolved. ### Codex hook or local CLI failure hardening **Role:** As a developer maintaining a repo-local Codex hook, plugin, or CLI helper A hook or local CLI command fails under a specific edge case, such as malformed input, missing config, unexpected event JSON, or a command usage error. The agent must capture the exact terminal failure, patch the hook/workflow, and prove the case is covered next time. > As a tooling-focused developer, I want failures from hooks or CLI helpers to become regression artifacts, so that each failure hardens the workflow instead of becoming another one-off terminal mystery. #### Agent brief ```text You are my tooling agent. Run the self-improvement error loop on the failing hook/CLI workflow. First reproduce the failing command or hook scenario exactly. Capture the terminal state with `cmux read-screen` and save the raw text to `.notes/log-gated/tooling/failures/<timestamp>.txt`. Then apply this prompt shape to your own diagnosis: `Goal: <describe the hook or CLI contract>. Here is the exact failure: <paste captured terminal text>. Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time.` Patch the smallest relevant hook/workflow code. Add structured run artifacts under `.notes/log-gated/tooling/runs/` containing scenarioName, inputShape, commandRun, expectedOutcome, actualOutcome, errorText, timestamp, and pass. Run at least the original failing case and one nearby non-failing case. A supervisor pass must inspect the run artifacts and compare expectedOutcome vs actualOutcome. Do not claim success unless the artifacts show the original failure case now passes and the nearby case still passes. ``` #### Implementation references [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-log-gated-playbook/) [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) [Open reference](/topics/foundations-log-gated-playbook/) ```text cmux read-screen ``` ```text .notes/log-gated/tooling/failures/*.txt ``` ```text .notes/log-gated/tooling/runs/*.json ``` #### Browser verification Browser proof is not the primary proof unless the hook controls browser-visible behavior. For a terminal hook or CLI helper, the right proof is exact terminal capture plus structured run logs. If the hook opens a CMUX browser dashboard or affects a web UI, add one browser snapshot/evaluate step to confirm the visible state matches the log. #### Definition of done - The raw failure text is saved exactly, not paraphrased. - The patch is tied to a stated root cause from the captured failure. - At least two structured run logs exist: original failing scenario and nearby control scenario. - A supervisor comparison reads the artifacts and marks the gate pass only when expectedOutcome and actualOutcome match. #### Failure modes and mitigations - Common mistake: the agent patches the symptom without explaining the failure condition. Mitigation: require a root-cause note derived from the captured terminal text. - Common mistake: the agent creates an unbounded self-improvement loop. Mitigation: run a fixed set of scenarios and stop after the gate comparison. - Common mistake: the worker agent gets too much project context and wanders. Mitigation: keep the worker scoped to the hook/CLI files, logs, and the contract for this workflow. ## Implementation notes - Keep the durable artifact small and boring: raw terminal capture, scenario criteria, JSON run logs, and a supervisor comparison. - Use `.notes/log-gated/<scenario>/` for local artifacts unless the project already has a committed test-artifact convention. - For web app scenarios, require browser proof when the behavior depends on cookies, navigation, visible UI state, console errors, network calls, or disabled controls. - For hook or CLI scenarios, terminal capture and structured logs are the primary proof; browser automation is only useful if the workflow changes browser-visible state. - The worker agent should patch narrowly; the orchestrator or supervisor should compare artifacts and decide pass/fail. - Do not trust the worker's final answer as the gate. The gate is expected-vs-actual comparison over files, logs, terminal output, browser output, or other inspectable artifacts. - Redact secrets from logs. Store booleans, shapes, route names, status codes, sanitized errors, and timestamps rather than raw tokens, cookies, or credentials. - Grounding note: content is derived from the uploaded scenario-log-gated bundle. :contentReference[oaicite:0]{index=0} ## Boundaries and caveats - Do not introduce unrelated tools that were only mentioned elsewhere, such as broad NotebookLM, n8n, ScreenPipe, or external CI platform workflows. - Do not claim deterministic proof from an agent's natural-language completion message. - Do not overbuild a permanent test suite for fast-moving UI experiments unless the repo already has stable acceptance tests for that flow. - Do not create unbounded self-improvement loops; run named scenarios, compare artifacts, and stop. - Do not log secrets, auth headers, private customer data, or raw cookies just because logs are useful. ## Agent reference map ### Validated lesson 08 references Use as the ground-truth teaching source for terminal text extraction, self-improvement loops, log-based gates, natural-language boundaries, and context pruning. [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) ### Existing log-gated prompt Use as the copy-paste source pattern for capturing exact failure text, asking for root-cause hardening, and requiring structured log artifacts. [Open reference](/topics/foundations-log-gated-playbook/) ### Existing Codex skill Use to keep scenario language aligned with the existing toolkit skill and avoid inventing untaught verification machinery. [Open reference](/topics/foundations-log-gated-playbook/) ### CMUX terminal text capture Use to grab exact terminal output as machine-readable context before diagnosis or patching. ```text cmux read-screen ``` ### CMUX live tracker pane Use when the agent should keep a visible, auto-refreshing progress view next to the running workflow. ```text cmux markdown open .notes/log-gated/<scenario>/tracker.md --direction right ``` ### Lesson 08 validation notes Use to stay inside the validated taught boundary: logs/files/API calls/object shapes/timestamps/session outputs, not invented broad verifier infrastructure. [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) ### Interactive lesson checklist Use for concrete practice steps and success criteria around failure capture, log comparison gates, and worker boundary contracts. [Open reference](/topics/foundations-deterministic-verification-and-boundaries/) Reference ID: foundations-log-gated-playbook Topic: Verification Sources: - [Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-08.html) --- # Use a model council for hard decisions A single model can give a clean answer and still miss the important edge. Use a **model council** when the cost of a missed perspective is higher than the cost of waiting. **[Fusion](https://github.com/johnlindquist/fusion)** is one way to run that pattern locally: send the same bounded software question to multiple configured providers, wait for the panel to finish, let a **finalizer** compare the outputs, then make the engineering decision from the result and the repo evidence. > It can take all of those results and then fuse them with the model of your choice. Meaning that… you get multiple opinions, you can have them kind of argue against each other. > > — John Lindquist ## Use It For Hard Decisions Reach for a council when you need **coverage, not speed**. Good fits: - large PR review - architecture tradeoffs - migration risk - security and performance tension - uncertain debugging plans - product or UX direction - release or rollback strategy Do not use it as a way to avoid making the call. The council gives you independent critique. **You still own the decision.** ## The Mental Model ```text bounded software question -> independent model/provider perspectives -> terminal provider states -> finalizer comparison -> summary.json -> final.md -> engineering decision ``` Fusion is for coverage, not voting. The useful output is not "three models said yes." The useful output is consensus, contradictions, unique warnings, blind spots, and a final recommendation you can test against the codebase. ## Run The Whole Council Partial panel output is not the answer. Wait until every configured provider reaches a **terminal state** before treating the result as complete. Before a real run: - inspect the configured providers - run the full configured panel by default - wait for terminal provider states - read `summary.json` - read `final.md` - reconcile the result with repo evidence **Panel artifacts are partial until the final artifacts exist.** ## Handle Missing Voices A missing provider degrades the council. It does not automatically make the run useless. If a provider times out, fails, or hits quota after artifacts exist, treat that as a **missing voice**. The final answer can still be useful if it clearly names the degraded state and enough other panel output exists to synthesize. Do not hide the missing voice. Make it part of the decision record. ## Good Software Uses Large PR review: ```text Use Fusion to review this PR before merge. Context: - PR summary: - changed files: - risky areas: - test output: - migration or rollout notes: Ask the council to find: - correctness risks - security risks - performance risks - missing tests - rollout or rollback issues - documentation gaps Return: - consensus - contradictions - unique warnings - blind spots - recommended merge/block decision - verification commands ``` Architecture tradeoff: ```text Compare three implementation paths for the billing webhook fix: A. provider event id dedupe B. invoice-level lock C. processing ledger Include: - failure modes - migration risk - rollback path - test plan - operational logging - smallest shippable recommendation ``` Role/perspective panel: ```text Review this auth/session plan from four perspectives: 1. security reviewer 2. performance reviewer 3. migration reviewer 4. product/UX reviewer Each reviewer should name what could go wrong. The finalizer should preserve minority warnings instead of flattening them. ``` ## Optional Pattern: Stop-Hook Review For risky AFK work, a prompt marker can ask a later stop gate to review changes before reporting done. Conceptual shape: ```text When the user prompt includes #review, write a marker for the stop hook. At Stop: - check whether files changed - check whether the marker exists - run Fusion against the diff - read summary.json and final.md - report the council result before claiming done ``` Treat this as a pattern until the hook payload, marker passing, and current CLI behavior are verified. ## Copyable Artifact: Fusion Decision Brief ```text Decision: [the software decision under review] Why a council: [what one model might miss] Context: - repo area: - changed files: - relevant tests: - logs or traces: - constraints: Provider instructions: Ask each provider to review independently. Preserve disagreements. Do not treat majority agreement as proof. Finalizer instructions: Return: - consensus - contradictions - unique warnings - blind spots - recommended decision - verification commands - confidence and why Human decision: [accept / revise / block / run another pass] ``` ## Claim Boundaries Hosted products may publish their own benchmark or cost claims for panel-style research workflows. Treat those as vendor claims that need dated citations. Local Fusion is a local CLI pattern inspired by [the same panel/finalizer idea](https://openrouter.ai/blog/announcements/fusion-beats-frontier/), not proof of hosted benchmark results. > I can, like, anecdotally vouch for the results, but I can't give you some sort of percentage of… it's this close to Fable or whatever. > > — John Lindquist Provider availability, pricing, quotas, auth, and data handling are local/account-dependent. Verify current provider terms before sending private code or prompts. Model council output is **advisory**. Tests, code review, product judgment, and repo evidence still decide the work. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#model-council) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-model-council Topic: Verification Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#model-council) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Verify fixes with deterministic evidence and narrow boundaries > Original source pages and recordings require authorized access. The full article text here is public. The practice is turning agent failures into better tooling: capture the exact terminal state, feed it back into the agent or plugin workspace, patch for that fail case, then verify with hard evidence instead of trusting a happy-sounding completion message. John also zooms out into a boundary model: keep worker agents narrow, isolated, and tool-limited; let a context-rich orchestrator coordinate them; and aggressively reduce context for single-purpose daemon-style tasks. ## Working outcomes - Extract terminal pane text in CMUX as machine-readable context - Build self-improvement error loops behind log-based deterministic gates - Define natural-language contract boundaries and prune context ## Concepts and consequences ### Terminal text extraction as context John shows a CMUX shortcut, Cmd-Opt-Shift-J in his setup, that takes the current terminal session and opens it as plain selectable text in an editor-like pane. Instead of fighting terminal scrollback, colors, and selection behavior, he copies the exact failure state and uses it as agent context. **Why it matters:** The fastest debugging loop starts with the real failure, not a vague summary of what you think happened. ### Self-improvement error loops When a plugin or hook fails, John copies the failed session text and asks the agent to explain why the plugin failed in that scenario and how to account for it next time. The point is not just to fix one run, but to use the exact fail case to harden the tool or workflow. **Why it matters:** Tooling compounds when each failure leaves behind a stronger hook, workflow, or guardrail. ### Log-based deterministic gates John's default answer to verification is to write logs or other artifacts to files. Depending on the project, those artifacts might show that a file was created, an API call happened, an object had the expected shape, timestamps were recorded, or multiple sessions produced comparable outputs. A main agent can wait for worker sessions to finish, inspect the logs and text output, and compare them against the criteria. **Why it matters:** Agents are useful reviewers, but artifacts are the evidence. Logs make fix-verify loops inspectable instead of trust-based. ### Natural-language contract boundaries John frames modules, tools, and CLIs as boundaries that agents can own. A master orchestrator can hold broader project context and spin up focused agents, while each worker gets a narrow task, limited tools, and a clear English instruction payload. He compares this to API contracts, except the handoff can be natural language sent to an agent. **Why it matters:** Narrow agents are faster, easier to inspect, cheaper to run, and less likely to get distracted by unrelated context. ### Context pruning for low-latency daemons The codex-daemons demo shows an advanced experiment in stripping agent startup context. John redirects the Codex home directory, symlinks the needed auth file, disables memories, MCP servers, web search, and Agents.md/project rules, and runs hyper-specific daemon commands on Codex Spark Low by default. He also shows SDK thread warm-up so the first prompt can skip several seconds of startup work. **Why it matters:** For repetitive, well-scoped CLI-style tasks, less context can mean faster responses, lower quota pressure, and fewer distractions. ## Reference tools and resources ### codex-daemons John's open-source project for low-context, single-purpose Codex daemon commands. **Use when:** Reach for it when you want to study the virtual CODEX_HOME pattern, auth.json symlink approach, disabled context sources, Codex Spark Low usage, and warmed SDK thread pattern. [Reference](https://github.com/johnlindquist/codex-daemons) ### CMUX The terminal and agent workspace John uses to run panes, capture terminal sessions as text, and coordinate agent workflows. **Use when:** Reach for it when you want pane-based agent workspaces, terminal text capture, or agent-driven terminal/browser automation. [Reference](https://github.com/manaflow-ai/cmux) ### GitHub CLI The GitHub command-line tool used as the target of John's Pro GH daemon example. **Use when:** Reach for it when a narrow daemon or agent should perform GitHub-specific tasks such as summarizing recent commits. [Reference](https://cli.github.com) ### Better Plugins / Ralph hook example The workshop plugin-hook workspace John used to show a Python Ralph hook, local validation, and agent-driven scenario testing. **Use when:** Reach for it when you want examples of building hooks, installing them into an agent environment, and verifying them against a few scenarios. search: John Lindquist Better Plugins Ralph hook ## Recommendations and best practices - When an agent, hook, or plugin fails, capture the exact terminal output first; do not summarize from memory unless you have no other option. - Use a repair prompt shape like: state the goal, paste the failure text after a colon, then ask the agent to explain why it failed and account for that case next time. - Make verification concrete by writing logs or files that record what actually happened: API calls, object shapes, timestamps, terminal outputs, or whatever criteria your project requires. - For multi-session verification, let the main agent wait for worker sessions to finish, inspect their logs and text outputs, and compare them against the criteria. - Avoid giant all-knowing worker sessions for execution work. Keep the orchestrator context-rich, but make worker agents narrow, tool-limited, and easy to audit. - Before fanning work out across agents, scope which tasks can be isolated, which tools each worker should use, and which boundaries define ownership. - Treat CODEX_HOME redirection, auth.json symlinks, disabled memories/MCP/web search/Agents.md, model overrides, and warmed SDK threads as advanced experimental patterns; test what works in your own setup. ## Practice and acceptance criteria Practice capturing real failures, turning them into repair prompts, verifying work with artifacts, and designing narrow worker agents with clear boundaries. ### Checklist 1. Pick one local script, hook, or CLI workflow that occasionally fails and identify a real or intentionally created fail case. 2. Run the scenario in CMUX or your terminal, then capture the exact terminal output as clean text using Cmd-Opt-Shift-J or an equivalent scrollback export. 3. Write a repair prompt with three parts: the goal, the raw failure text after a colon, and an instruction to explain the failure and account for it next time. 4. Add logging to the workflow that records what it actually did, such as relevant API calls, object shapes, timestamps when useful, outputs, or errors. 5. Run a few scenarios or sessions that match the criteria you care about verifying. 6. Use a supervisor prompt or verifier script to read the logs and text outputs, then compare them against your criteria instead of accepting the worker agent's completion message. 7. Draft a natural-language contract for the worker agent: what it owns, which tools it may use, what inputs it receives, what outputs it must produce, and what context it does not need. ### Failure Capture Drill **Difficulty:** Easy Break a small local script on purpose, capture the exact terminal failure as clean text, and use it to ask Codex to explain the cause and patch the code. Do not summarize the error manually. **Done when:** The repaired script handles the original failure case, and your prompt includes the raw captured output rather than a vague description. ### Log Comparison Gate **Difficulty:** Medium Add file logging to one hook or CLI workflow, then run three sessions or scenarios and save one log artifact per run. Include the facts your project needs to verify the run, such as an API call, object shape, result, error, timestamp, or terminal output. **Done when:** A verifier or supervisor agent can read the log files and clearly compare each run against the expected criteria without relying on the worker agent's chat response. ### Boundary Contract Map **Difficulty:** Medium Choose a feature in one of your projects and split the work into an orchestrator plus two or three narrow worker agents. For each worker, write its natural-language contract, allowed tools, out-of-scope areas, required inputs, and required outputs. **Done when:** Another developer could read the map and know which agent owns each part of the work, where handoffs happen, and what context should be pruned from each worker. ### Low-Context Daemon Prototype **Difficulty:** Hard Study or prototype a small wrapper around a CLI-style target such as GitHub CLI or CMUX. Isolate the agent context as much as your tooling allows: redirect the home/config context, symlink only the required auth/config if needed, disable extra context sources where possible, and compare behavior against your normal setup. **Done when:** You can show a before-and-after comparison of startup context, speed, or focus, and you have documented which parts of the setup are experimental or hacky. ## Questions to test understanding ### A hook fails in a CMUX terminal pane and prints a long stack trace. What should you do first if you want the fastest useful self-improvement loop? - **A.** Capture the exact terminal text and feed it back to the agent as context. - **B.** Ask the agent to guess what probably happened from a short summary. - **C.** Restart the session and hope the failure disappears. - **D.** Install more tools into the agent environment before debugging. **Answer: A.** The lesson emphasizes starting from the real failure state, not memory or vibes. Clean terminal extraction gives the agent precise evidence to explain and patch against. ### What makes a log-based deterministic gate stronger than an agent's completion claim? - **A.** The log file sounds more official than chat text. - **B.** Logs can record inspectable facts that another process or supervisor can compare. - **C.** Logs prevent all future bugs automatically. - **D.** The worker agent cannot read log files, so it has less context to misuse. **Answer: B.** John's default is to create artifacts agents can inspect: logs, files, timestamps, object shapes, API-call evidence, and session outputs. A supervisor can compare those artifacts instead of trusting a natural-language claim. ### In this lesson's boundary model, what should the master orchestrator usually do? - **A.** Run every task directly with every available tool. - **B.** Hold broad project context, split work, and assign narrow tasks to isolated agents. - **C.** Disable all logging so agents rely on reasoning alone. - **D.** Give every worker the full repository, memories, browser access, and MCP servers. **Answer: B.** The orchestrator keeps the big picture and coordinates work. Worker agents should be small, tool-limited, and scoped to clear natural-language contracts. ### Why would a Codex daemon use a redirected home directory and disable memories, MCP servers, web search, and project rules? - **A.** To make the agent more creative by hiding all instructions. - **B.** To reduce startup context and keep a single-purpose daemon fast and focused. - **C.** To bypass the need for authentication completely. - **D.** To make logs unnecessary because the model has fewer distractions. **Answer: B.** Context pruning removes baggage for repetitive, well-scoped tasks. John framed the codex-daemons setup as an advanced experiment involving a fake Codex home directory, an auth.json symlink, disabled context sources, and a low-reasoning default model. ### Which prompt shape best matches the lesson's repair loop? - **A.** Fix this, it failed somehow. - **B.** Here is the goal, here is the exact failure text, explain why it failed and account for this case next time. - **C.** Ignore the stack trace and rewrite the whole project from scratch. - **D.** Tell me the issue is resolved after editing the first related file you find. **Answer: B.** The useful loop combines goal, exact failure evidence, diagnosis, and durable workflow hardening. The point is not only to fix one bug, but to prevent the same class of failure from returning. ## Reflection prompts - Where in your current workflow are you still trusting an agent's claim instead of checking an artifact? - Which agent tasks in your projects would get faster or safer if they had less context, not more? - What log output would let an orchestrator compare multiple runs against your actual success criteria? ## Further applications 1. Build a tiny local failed-session library: save terminal captures into dated files, then use them as regression prompts when improving hooks. 2. Prototype a deterministic gate for one workflow: run a few sessions or scenarios, write a log artifact for each run, and compare expected criteria versus actual outputs. 3. Create a natural-language contract map for your project: list each module, the agent that owns it, the tools it may use, and the inputs and outputs it should exchange. 4. Experiment with a single-purpose daemon around a demonstrated CLI-style target such as GitHub CLI or CMUX, and measure whether reduced context improves speed, focus, or reliability. 5. Add logs, tracing, or telemetry around boundary crossings so an agent can inspect when work reached outside its intended scope. ## Applied exercises ### Exercise 1: Build a Manual Error-Recovery Loop **Objective:** Practice stripping terminal artifacts and running a recovery loop using John's approach. **Steps:** Intentionally break a local script or hook so it throws an active stack trace or error block in your terminal workspace.Use your environment's clean text export option (or the CMUX Cmd-Opt-Shift-J shortcut) to capture the raw error text without terminal escape characters.Draft an explicit repair prompt using John's structure: outline the overarching goal, paste the error after a colon separator, and instruct an agent to modify the code file to handle the edge case. ### Exercise 2: Prototype an Isolated Virtual Environment Hack **Objective:** Build a basic shell wrapper script that mimics the token-saving isolation strategy of codex-daemons. **Steps:** Write a shell script wrapper for your local development tool of choice.Inside the script, temporarily override the tool's core path variable or home folder directory target (ENV_HOME) to a completely empty temporary directory (/tmp/isolated_sandbox).Explicitly symlink only your core API key configuration file into that temporary sandboxed folder.Run a test command through the wrapper. Verify that the agent no longer scans your main project's workspace rule files or local database histories, matching the clean-slate daemon setup. ## Questions and answers ### How do you make the verify half of a fix-verify loop something you enforce, not something the agent just claims it did? When an agent fixes a bug, what's the deterministic gate that proves it's fixed + didn't regress? John recommends relying on structured logs written directly to disk. These files act as multi-agent-readable verification artifacts that track data shapes and API timing signatures. A supervisor agent can run parallel worker blocks, wait for completion, and compare files to programmatically confirm structural success without trusting the worker agent's natural language updates. ### you use the word boundaries a few times, seems like you have a visual conceptual meta-framework to think about how to control and steer and keep tools and agents and plugins scoped properly, can you speak to this, your way of thinking? John advises against loading too many marketplace tools into a single agent context. His approach uses a highly context-aware master orchestrator that manages project goals alongside hyper-isolated sub-agents running small token footprints. This forms natural language contract boundaries across layers, mimicking decoupled microservice modules. ## Operational playbooks - [Self-improving log-gated fix loop](/topics/foundations-log-gated-playbook/) - [Browser Proof Field Guide](/topics/foundations-browser-proof-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-08.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-08.html) ### Visual reference index - [03:34:58](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-1): CMUX shortcut changes active window layout into a clean plain text editor block. - [03:36:12](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-2): Workspace view with terminal/log text and the live typing-game dashboard visible, useful for the self-improvement loop context. - [03:38:22](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-3): IDE displays a custom python-based implementation file of a Ralph hook. - [03:39:45](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-4): Dark terminal/editor view during the prompt-structure discussion; keep exact prompt-pattern claims tied to transcript evidence. - [03:48:02](https://codex-workshop-followup.pages.dev/lesson-08.html): Terminal/browser workspace during the transition into codex-daemons; repository URL remains confirmed by chat. - [03:49:48](https://codex-workshop-followup.pages.dev/lesson-08.html): Terminal logs screen view of the Pro GH utility streaming a low-latency commit overview. - [03:52:12](https://codex-workshop-followup.pages.dev/lesson-08.html): Code display tracking the virtualized home directory environment overrides inside the daemon root folder. - [03:53:15](https://codex-workshop-followup.pages.dev/lesson-08.html): Configuration block code showing flags explicitly setting memories, mcp, and web search options to false. - [03:54:18](https://codex-workshop-followup.pages.dev/lesson-08.html): Orchestration logic view tracking background handshake mechanisms used to warm up active SDK execution threads. - [03:55:38](https://codex-workshop-followup.pages.dev/lesson-08.html): Terminal workspace after the CMUX pane command, showing split-pane execution context. Reference ID: foundations-deterministic-verification-and-boundaries Topic: Verification Sources: - [Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-08.html) --- # Video analysis recipes, prompts, and evidence gates Complete portable procedures for preparing analysis media, proving video understanding, extracting and reconciling evidence, and reviewing a follow-up packet. These are reference recipes—not a claim that this knowledge base independently processed the recording. Commands use generic local run paths; raw logs and source conversations remain private. The short-clip and follow-up-packet prompts retain their original output audience as task examples for teammates preparing those materials. They are not instructions to publish unreviewed source data. ## Prerequisites and safe local setup Use a dedicated, existing Git repository for the analysis artifacts—not the source software project. Install `ffmpeg`, `ffprobe`, `git`, `jq`, `python3`, and a SHA-256 utility (`shasum` in these examples) before starting. The later consult stages additionally require the configured Oracle browser workflow, Packx, and a signed-in Gemini browser profile; the setup below does not configure accounts or read credentials. Run the setup in Bash and keep the same shell for later snippets, so `RUN_ID` and `RUN_DIR` remain defined. Set `SOURCE_VIDEO` to your existing source MP4 and `RUN_ID` to a new, simple label first. Missing values, invalid labels, absent media, and an existing run directory stop before creating or overwriting a run. Optional transcript/chat inputs must be separately approved for local processing and remain private until reviewed and redacted. ```bash set -euo pipefail : "${SOURCE_VIDEO:?Set SOURCE_VIDEO to an existing source MP4}" : "${RUN_ID:?Set RUN_ID to a new analysis label}" case "$RUN_ID" in ''|*[!a-zA-Z0-9_-]*) printf 'RUN_ID must contain only letters, digits, underscore, or hyphen\n' >&2; exit 1 ;; esac PROJECT_ROOT="$(git rev-parse --show-toplevel)" cd "$PROJECT_ROOT" test -f "$SOURCE_VIDEO" RUN_DIR="$PROJECT_ROOT/runs/$RUN_ID" if test -e "$RUN_DIR"; then printf 'Run already exists: %s\n' "$RUN_DIR" >&2 exit 1 fi mkdir -p "$RUN_DIR"/{inputs,receipts,analysis,segments,break-chat,chunks,oracle/sessions,final,publication} git status --short > "$RUN_DIR/receipts/git-status.before.txt" cp "$SOURCE_VIDEO" "$RUN_DIR/inputs/source-video.mp4" if test -n "${SOURCE_TRANSCRIPT:-}"; then cp "$SOURCE_TRANSCRIPT" "$RUN_DIR/inputs/transcript.vtt" fi if test -n "${SOURCE_CHAT:-}"; then cp "$SOURCE_CHAT" "$RUN_DIR/inputs/chat.txt" fi ``` The original media remains untouched. The following receipt commands record tool versions, checksums, and media properties; they do not establish that Gemini can read the attachment. That requires the later source-specific probes. Keep raw inputs and receipts private; committing a local receipt is not authorization to push it or publish it. Record tool versions: ```bash { echo "# Tool Versions" echo echo "date: $(date -u +%Y-%m-%dT%H:%M:%SZ)" echo echo "## ffmpeg" ffmpeg -version | head -n 3 || true echo echo "## ffprobe" ffprobe -version | head -n 3 || true echo echo "## git" git --version || true echo echo "## jq" jq --version || true echo echo "## python" python3 --version || true } > "$RUN_DIR/receipts/tool-versions.txt" ``` Hash source assets and save file list: ```bash shasum -a 256 "$RUN_DIR/inputs/source-video.mp4" > "$RUN_DIR/inputs/source-video.sha256" find "$RUN_DIR/inputs" -maxdepth 2 -type f -print0 \ | xargs -0 shasum -a 256 \ > "$RUN_DIR/receipts/source-file-list.txt" ``` Probe the source video: ```bash ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` Create a human-readable media receipt: ```bash { echo "# Media Info" echo echo "source: $RUN_DIR/inputs/source-video.mp4" echo "sha256: $(cut -d ' ' -f1 "$RUN_DIR/inputs/source-video.sha256")" echo jq -r '.format | "- duration: \(.duration)\n- size: \(.size)\n- bit_rate: \(.bit_rate)"' \ "$RUN_DIR/receipts/ffprobe.source.json" echo echo "## Streams" jq -r '.streams[] | "- index=\(.index) type=\(.codec_type) codec=\(.codec_name) duration=\(.duration // "unknown") width=\(.width // "-") height=\(.height // "-")"' \ "$RUN_DIR/receipts/ffprobe.source.json" } > "$RUN_DIR/receipts/media-info.md" ``` ## Run Config Create `$RUN_DIR/run-config.json` before processing. Set `run_id` to the same value as `RUN_ID`, and set unavailable optional transcript/chat paths to `null`: ```json { "run_id": "example-workshop", "title": "Example Workshop", "mode": "long_workshop", "source": { "video": "inputs/source-video.mp4", "transcript": "inputs/transcript.vtt", "chat": "inputs/chat.txt", "screenshots": "inputs/screenshots", "clips": "inputs/clips" }, "policy": { "preserve_original_timestamps": true, "canonical_chapters": "semantic", "canonical_chapter_max_minutes": 30, "analysis_shard_target_minutes": 4, "analysis_shard_max_minutes": 4, "analysis_attachment_target_mib": 9, "analysis_media": "h264-main-yuv420p-29.97fps-aac-lc-44.1khz-faststart", "dead_space_removal": "only verified long silence plus transcript/chat break evidence", "default_video_overlap_seconds": 0, "semantic_boundary_overlap_seconds": 5, "qa_boundary_overlap_seconds": 15, "chat_carry_forward": true, "dedupe_final_materials": true, "large_binary_git_policy": "local-only-unless-explicitly-approved" }, "outputs": { "student_packet": true, "keyframes": true, "contact_sheets": true, "verification_reports": true } } ``` ## Mode Matrix | Mode | Typical input | Segmentation | Transcript/chat | Keyframes | Gemini video pass | Output | |---|---|---:|---:|---:|---:|---| | Long workshop | 2-8 hour Zoom/workshop recording | Required | Required if available | Required | Required | Full student packet | | Medium tutorial | 20-60 minute lesson | Optional semantic chunks | Transcript required, chat optional | Recommended | Required when deriving facts from video | Guide, chapter index, resources | | Short bug reproduction | 30 sec-8 min screen recording | Skip | Optional | Required | Required for observed behavior | Bug report, repro steps, implementation brief | | Quick design feedback | 1-12 min screen and voice | Skip | Recommended if voiceover matters | Required | Required for visual/audio claims | Design-change brief, QA checklist | | Raw app walkthrough | 5-30 min app demo | Skip under 12 min; segment over 20 min | Recommended | Required | Required for requirements/QA extraction | Requirements doc, acceptance criteria | "Optional" applies only to extra Oracle planning/review over text artifacts. It does not mean the video-watching step can be skipped when the deliverable depends on what is visible or audible in the recording. ## Decision Tree Segment when any of these are true: - Video duration is over 30 minutes. - There are real breaks, lunch, pre-roll, or dead air. - Q&A spans topic transitions. - Chat must be aligned to the video. - The target output is a course packet, student packet, chapter index, or publication bundle. Skip segmentation when all of these are true: - Video duration is 12 minutes or less. - There is no long dead air or break. - Chat is absent, irrelevant, or small enough to include directly. - One model pass can analyze the whole video reliably. - The target output is a short note, bug report, design feedback memo, or compact implementation plan. Use a medium path when the video is 12-45 minutes, has no real breaks, and has 2-4 obvious sections. In that case, keep one physical video and create timestamped sections unless model upload/runtime gets awkward. Remove a video span only when long silence or inactive-screen evidence, transcript evidence, and chat evidence agree that the span is a break or dead space. Never discard chat from a removed span. Save it in `break-chat/` and carry it forward to the next spoken chunk when it contains a question, answer, link, or context used later. Extract keyframes when screen share, terminal commands, browser pages, demos, design feedback, or visual claims appear. Skip keyframes only for pure audio/talking-head content where visual evidence cannot change the output. Run an omissions pass when coverage is incomplete, missing URLs exist, missing chat questions exist, keyframe candidates are thin, machine JSON is missing/unparseable, timestamps are out of range, or hallucination checks find invented tools/links/commands. ## Long Recording Workflow 1. Detect silence: ```bash ffmpeg -hide_banner -i "$RUN_DIR/inputs/source-video.mp4" \ -af silencedetect=noise=-35dB:d=5 \ -f null - 2> "$RUN_DIR/analysis/silencedetect-35db-5s.log" ``` 2. Draft `analysis/boundary-candidates.md` from silence, transcript, and chat evidence. 3. Create `segments/segment-manifest.v1.json` and `.md`. Preserve original timestamps. Define semantic chapters under 30 minutes for the canonical teaching structure, but define separate technical analysis shards no longer than four minutes until a source-specific production-shard probe proves a longer duration safe. Map each shard back to its canonical chapter. Remove break spans only when evidence supports removal. 4. Run `$oracle` before finalizing segmentation when the run is long, public, or ambiguous. Bundle only text artifacts: ```bash mkdir -p ~/.oracle/bundles find "$RUN_DIR" -type f \( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \) \ | xargs packx --preview --no-interactive find "$RUN_DIR" -type f \( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \) \ | xargs packx --limit 900k -f markdown --no-interactive --stdout --strip-comments --minify \ > ~/.oracle/bundles/video-followup-segmentation-review.txt test -s ~/.oracle/bundles/video-followup-segmentation-review.txt ``` Ask Oracle in browser mode only. If using the skill, invoke `$oracle`; if using the CLI fallback, keep browser mode explicit: ```bash oracle --engine browser \ --model gpt-5.6-pro \ --browser-thinking-time extended \ --slug video-followup-segmentation-review \ --file ~/.oracle/bundles/video-followup-segmentation-review.txt \ -p "$(cat "$RUN_DIR/oracle/planning.md")" ``` Save the Oracle conversation URL, local bundle path, prompt, and `~/.oracle/sessions/<slug>/output.log` reference in `oracle/sessions/<slug>.md`. 5. Revise into `segments/segment-manifest.v2.json` and `.md`. 6. Cut archival chapters and Gemini analysis shards from the original source. A stream-copy cut is acceptable only as an archival artifact; do not send stream-copy chunks to Gemini by default. A file can pass `ffprobe` and still stall indefinitely in Gemini. ```bash mkdir -p "$RUN_DIR/chunks/01" START_SECONDS=344 DURATION_SECONDS=240 SOURCE="$RUN_DIR/inputs/source-video.mp4" ANALYSIS_SHARD="$RUN_DIR/chunks/01/chunk.mp4" ffmpeg -hide_banner -loglevel error -y \ -ss "$START_SECONDS" -i "$SOURCE" -t "$DURATION_SECONDS" \ -map 0:v:0 -map 0:a:0 \ -vf 'fps=30000/1001,format=yuv420p' \ -c:v libx264 -preset veryfast -crf 30 -profile:v main \ -c:a aac -b:a 80k -ar 44100 -ac 2 \ -movflags +faststart "$ANALYSIS_SHARD" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/chunks/01/chunk.mp4" \ > "$RUN_DIR/chunks/01/chunk.ffprobe.json" ``` Keep every shard below the configured Oracle attachment ceiling. When the ceiling is 10 MiB, target <=9 MiB. Avoid low-fidelity derivatives such as 4 fps video or 24 kHz mono audio: they may upload, then become `This file has been removed` or unreadable. After any encoding change, rerun the source-specific audio+visual probe before batching. 7. Slice transcript and chat into `chunks/<nn>/transcript.md`, `chat.md`, and `carry-forward-chat.md`. 8. Create `chunks/video-manifest.json` with chunk id, original range, file path, transcript path, chat path, carry-forward path, ffprobe path, and verification status. ## Short Recording Workflow Use this path for quick screen captures, short bug reproductions, design notes, and small app walkthroughs. ```bash RUN_ID="$(date +%Y-%m-%d)-quick-clip" RUN_DIR="runs/$RUN_ID" mkdir -p "$RUN_DIR"/{inputs,receipts,chunks/01,final} cp "/absolute/path/to/clip.mov" "$RUN_DIR/inputs/source-video.mov" shasum -a 256 "$RUN_DIR/inputs/source-video.mov" > "$RUN_DIR/inputs/source-video.sha256" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mov" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` For short clips, use the source directly only after `ffprobe` plus the source-specific audio+visual probe confirms Gemini can retain and read it. Otherwise create the same H.264 Main/yuv420p/AAC-LC/faststart analysis encode used by the long workflow. Do not downsample to 4 fps or 24 kHz mono merely to reduce size. ```bash ln -s ../../inputs/source-video.mov "$RUN_DIR/chunks/01/chunk.mov" ``` Create `chunks/01/gemini-prompt.md` using the short clip prompt in this doc, attach the clip directly to Gemini/video model, and save: ```text chunks/01/expected-sentinel.txt chunks/01/gemini-run.log chunks/01/gemini-result.json chunks/01/gemini-analysis.md chunks/01/final-reconciled.md final/README.md ``` Final output by short mode: - Bug reproduction: `final/bug-report.md`, `final/repro-steps.md`, `final/acceptance-checks.md` - Design feedback: `final/design-brief.md`, `final/visual-acceptance-criteria.md` - App walkthrough: `final/requirements.md`, `final/qa-checklist.md` - Tiny tutorial: `final/summary.md`, `final/resources-and-links.md` Run the same malformed URL and hallucination checks even for short clips. For YouTube research batches, add these source-selection rules before downloading: - Search broadly, but select by actual YouTube metadata (`upload_date`), not title text. - Enforce user cutoffs exactly. Use an explicit cutoff parameter, e.g. `upload_date >= cutoff_yyyymmdd`. - Exclude topic collisions, coupon/affiliate uploads, auto-generated music/topic uploads, and unrelated videos. - Save selected videos in `queue.json` with `id`, `title`, `uploader`, `upload_date`, `duration`, and `url`. - Use Chrome cookies with `yt-dlp` when YouTube challenges require it. - Space Gemini upload starts by about five minutes for batch runs only after the first attached-video probe passes and no unresolved run is pending, unless the user asks for a different cadence. For each batch item, use a topic-specific prompt. Do not copy old prompt text from a different topic without replacing the product/domain language. ## Gemini Readiness And Failure Recovery Before a large batch, run two source-specific attached-video probes: a 30-60 second source-native sample, then one production-size <=4 minute analysis shard using the real prompt shape. Each prompt must request one spoken phrase and one visual observation at a specified timestamp, plus an alphabetic-ending sentinel. Independently verify the phrase against audio/captions and the visual observation against an extracted frame. Do not rely on a sentinel-only or text-only probe. Required preflight receipts: - configured browser mode and Gemini provider routing; - visible signed-in Gemini UI and both completed attached-video probes; - prompt path and exact expected sentinel; - run/session metadata; - a real submitted `user-query` retaining its attachment chip/duration, with the prompt absent from the composer and a `model-response` begun; - locally verified source-specific audio and visual facts plus the expected sentinel; - completed tab cleanup. On any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit, or upload warning, stop new batch starts. Inspect the active Gemini tab, classify the state, and retry only the affected chunk if no valid sentinel response exists. Write the exact expected sentinel into `chunks/<nn>/expected-sentinel.txt` before each Gemini run. Verification and recovery should compare against that file, not infer the sentinel shape from memory. End the sentinel with letters, for example `END_OF_VIDEO_ANALYSIS workshop SHARD_004_COMPLETE`, not a bare number that may be visually joined to a following timestamp. Oracle log lines such as `Attachment upload complete`, `Sending prompt`, and `still generating` are diagnostics, not proof. The live Gemini DOM is authoritative. A title, sidebar/body text match, empty composer, or broad `Stop` button match does not prove a submitted turn. Re-check state before long waits because an apparent turn can regress and return to the composer. For liveness, snapshot the real `model-response message-content` text/HTML and `aria-busy` state 2-3 times over about three minutes. If content grows, keep waiting. If an `Analyzing`/`Gemini said` placeholder does not grow, record a confirmed stall, close only that exact target, frame-exact re-encode the shard, and retry once. Do not loop the same media bytes. On a fresh `/app` conversation, the upload menu can initially be empty. Initialize the conversation with one harmless text turn, wait for completion, reopen the upload menu, then run the actual source-specific video probe. The initializer is not video proof. ## Gemini Browser Cleanup When using Oracle CLI fallback with `--browser-keep-browser`, cleanup is mandatory: 1. Wait for the run to finish. 2. Save every needed extraction artifact from the Gemini response: `gemini-result.json`, `gemini-analysis.md`, `gemini-analysis.extracted.json` when expected, machine JSON, and any recovery note if the response was recovered by tab inspection. 3. Verify the analysis is non-empty and contains the expected `END_OF_VIDEO_ANALYSIS ...` sentinel. 4. Close only the completed and fully extracted Gemini tab for that run. 5. Do not close tabs for active uploads, still-generating sessions, unresolved wrapper errors, or completed-looking tabs whose visible response has not been extracted. 6. Do not kill Chrome; Oracle needs the signed-in profile for future runs. For scripted runs, implement cleanup as a post-extraction step, not as a generic `finally` block. A safe script order is: save wrapper result, inspect/recover tab output if needed, write extracted JSON, verify the exact expected sentinel, then close the specific Gemini tab target. If any extraction or sentinel check fails, leave the tab open and record the Chrome port/target for recovery. If exact target close tooling is available, use Chrome DevTools Protocol to close the specific `gemini.google.com/app` target created for the run. If not, list tabs first, identify completed or empty Gemini tabs, and close only those. Avoid broad "close all Gemini" actions while a batch is running. The Chrome target id returned by `/json/list` is different from the Gemini conversation id in `/app/<conversation-id>`. Close `/json/close/<target-id>`, then list targets again to prove removal. Do not pass the conversation-id suffix to the close endpoint. When classifying stale tabs: - Empty generic Gemini tabs from failed diagnostics may be closed after inspection. - Active upload/generation tabs must stay open. - Tabs with conversation state or auto-generated titles must be checked for saved output and the expected sentinel before closing. - Never use broad "close all Gemini tabs" while a batch is active. ## Prompt Templates ### Gemini Chunk Analysis ```markdown You are analyzing one source-preserving video chunk for a follow-up packet. Run metadata: - run_key: {{run_key}} - chunk_id: {{chunk_id}} - original_recording_range: {{start_time}} -> {{end_time}} - chunk_video: {{chunk_video_path}} - transcript: included below - chat: included below - carry_forward_chat: included below - next_chunk_preview: included below Hard rules: 1. Preserve original recording timestamps. 2. Separate transcript evidence, chat evidence, visual evidence, and inference. 3. Do not invent tools, commands, URLs, files, speakers, or UI labels. 4. Include unanswered and deferred questions. 5. Flag every policy-sensitive area, especially browser automation, cookies, quota/rate limits, private accounts, and publishing. 6. Return both Markdown and fenced JSON. 7. End with: END_OF_VIDEO_ANALYSIS {{run_key}} {{chunk_id}}_COMPLETE Return: # Chunk Analysis: {{chunk_id}} ## 1. Overview ## 2. Dense Timeline ## 3. Concept Inventory ## 4. Demo / Screen Activity ## 5. Questions And Answers ## 6. Links / Tools / Commands / References ## 7. Keyframes To Capture ## 8. Student Exercises ## 9. Uncertainties / Needs Review ## 10. Machine JSON ``` ### Omissions Pass ```markdown You are auditing a prior video analysis for omissions. Inputs: - chunk_id: {{chunk_id}} - original_recording_range: {{start_time}} -> {{end_time}} - coverage_report: {{coverage_report}} - expected_items: {{expected_items_json}} - prior_analysis: {{prior_analysis}} Find only omissions and corrections. Do not repeat complete items. Required focus: 1. Missing URLs exactly as they appeared. 2. Missing chat questions, including unanswered/deferred questions. 3. Missing demo steps. 4. Missing keyframe candidates. 5. Unsupported visual claims. 6. Hallucinated tools, commands, links, or files. 7. Parseable fenced JSON. Return: # Omissions And Corrections: {{chunk_id}} ## Additions ## Corrections ## Remove Or Downgrade ## Remaining Human Review ## Machine JSON ``` ### Local Reconciliation ```markdown Reconcile one analyzed chunk into an evidence-grounded final chunk record. Inputs: - segment manifest entry - transcript slice - chat slice - carry-forward chat - main analysis - omissions analysis - verification reports - keyframe review Rules: 1. Preserve original timestamps. 2. Remove malformed URLs. 3. Do not include any URL/tool/command unless supported by transcript, chat, carry-forward chat, local path, or keyframe review. 4. Do not claim a visual is visible unless keyframe review confirms it. 5. Preserve unanswered/deferred questions. 6. Preserve editorial warnings. 7. Deduplicate overlap by normalized timestamp + item type + text hash. Return Markdown and JSON with: - status: PASS | PASS_WITH_WARNINGS | FAIL - counts - timeline summary - concepts - Q&A - links/tools/commands - demos - keyframes - warnings - student-material candidates ``` ### Short Clip Analysis ```markdown You are analyzing a short screen recording or app walkthrough. Source: - run_key: {{run_key}} - recording_type: short_clip | bug_reproduction | design_feedback | app_walkthrough - original_recording_range: 00:00:00 -> {{duration}} - source_video_sha256: {{source_video_sha256}} Hard rules: 1. Use timestamps relative to the clip unless an original recording timeline is provided. 2. Do not invent commands, files, UI labels, URLs, or implementation details. 3. Separate observed behavior from inferred intent. 4. Include timestamped screenshot/keyframe candidates for visual claims. 5. For a bug reproduction, produce repro steps and expected vs actual behavior. 6. For design feedback, produce requested changes and visual acceptance criteria. 7. For an app walkthrough, produce requirements and QA checks. 8. Include uncertainties and manual review points. Return: # Short Video Analysis: {{run_key}} ## 1. Summary ## 2. Observed Timeline ## 3. User Intent / Requirements ## 4. Reproduction Steps Or Walkthrough Steps ## 5. Expected Vs Actual Behavior ## 6. Implementation Notes ## 7. QA / Acceptance Criteria ## 8. Keyframes To Extract ## 9. Risks / Unknowns ## 10. Machine JSON ``` ### Final Packet Generation ```markdown Assemble a student follow-up packet from verified chunk records. Inputs: - segments/segment-manifest.v2.md - chunks/*/final-reconciled.md - chunks/*/final-reconciled.json - chunks/*/verification/*.md - final/keyframes-manifest.json if present - resources extracted from chat/transcript Rules: 1. Use original recording timestamps. 2. Do not include unverified visual claims. 3. Do not include malformed URLs. 4. Do not present experimental tools as official recommendations unless approved. 5. Keep policy-sensitive automation/cookie/quota/rate-limit sections as editorial notes. 6. Distinguish publication-ready files from reference drafts. 7. Deduplicate overlap and carry-forward repeated material. Create: - final/README.md - final/student-followup-guide.md - final/chapter-index.md - final/resources-and-links.md - final/qa-index.md - final/exercises.md - final/keyframes-manifest.md - final/keyframes-manifest.json - final/instructor-review-checklist.md ``` ### Oracle Review ```markdown [{{slug}}] Project briefing: {{project_briefing}} Goal: {{goal}} Prior-State Ledger: - prior_oracle_session: {{prior_oracle_session_or_none}} - last_oracle_recommendation: {{summary_or_none}} - implemented_since_prior_oracle: {{files_or_none}} - verified_since_prior_oracle: {{commands_or_none}} - failed_proof_or_blocker: {{receipt_or_none}} - narrowing_decision: {{one_slice}} - files_functions_now_in_scope: {{paths}} - files_functions_out_of_scope: {{paths}} - next_falsifiable_verification: {{command_or_receipt}} - forward_progress_index: {{score_and_arithmetic}} Deliverable: Evaluate segmentation, chat carry-forward, analysis prompts, verification gates, final packet readiness, privacy/security risks, and the one highest-leverage next local action. Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. ``` ## Verification Gates Treat `~/.oracle/sessions/<slug>/output.log`, browser logs, and raw Gemini responses as private evidence. The MCP return can be truncated, so recover the full response from the persisted session log before reconciliation. Before copying any material into `publication/public-draft/` or another public wiki, scan and redact credentials, auth/callback URLs, account/model identifiers, local usernames and paths, signed/private URLs, notifications, and personal data. Gemini can repeat these even when told not to. Every pull quote and timestamp must be checked against local audio/captions and the source frame or clip. Gemini-supplied quote timestamps are candidates, not receipts. Record the verified timestamp and evidence path in the reconciliation artifact. Run malformed URL checks on every final packet: ```bash rg -n 'https://www\.\.\.|https://www\s|/"|\| .*: \||Context:' "$RUN_DIR/final" || true ``` Extract exact URLs from chat/transcript and compare against final resources: ```bash rg -o 'https?://[^[:space:])>"'"'"']+' "$RUN_DIR/chunks" "$RUN_DIR/break-chat" \ | sed 's/[,:;.!"]$//' \ | sort -u \ > "$RUN_DIR/verification.expected-urls.txt" rg -o 'https?://[^[:space:])>"'"'"']+' "$RUN_DIR/final/resources-and-links.md" \ | sed 's/[,:;.!"]$//' \ | sort -u \ > "$RUN_DIR/verification.final-urls.txt" comm -23 "$RUN_DIR/verification.expected-urls.txt" "$RUN_DIR/verification.final-urls.txt" \ > "$RUN_DIR/verification.missing-urls.txt" ``` Validate timestamps stay within range, except carry-forward chat: ```bash python3 scripts/validate-timestamps.py "$RUN_DIR" \ > "$RUN_DIR/receipts/timestamp-validation.log" ``` If the script does not exist yet, perform a manual timestamp pass and save it as `chunks/<nn>/verification/timestamp-report.md`. Check machine JSON: ```bash find "$RUN_DIR/chunks" -name '*.json' -print0 | xargs -0 -n1 jq empty ``` Required chunk gate files: ```text chunks/<nn>/verification/coverage-report.md chunks/<nn>/verification/hallucination-report.md chunks/<nn>/verification/timestamp-report.md chunks/<nn>/verification/qa-report.md chunks/<nn>/final-reconciled.md chunks/<nn>/final-reconciled.json ``` Chunk status meanings: - `PASS`: complete and publication-safe after ordinary instructor review. - `PASS_WITH_WARNINGS`: usable evidence, but warnings must be reviewed before publication. - `FAIL`: rerun analysis, omissions, or reconciliation before using the chunk. ## Keyframes Candidate extraction prompt output should include timestamp, reason, expected visual, priority, and confidence. Extract deterministic frames: ```bash mkdir -p "$RUN_DIR/chunks/01/keyframes/extracted" ffmpeg -hide_banner -ss 00:23:48 \ -i "$RUN_DIR/inputs/source-video.mp4" \ -frames:v 1 \ "$RUN_DIR/chunks/01/keyframes/extracted/00-23-48-automation-verification.jpg" ``` Create contact sheet: ```bash find "$RUN_DIR/chunks/01/keyframes/extracted" -name '*.jpg' | sort \ > "$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt" ffmpeg -hide_banner -f concat -safe 0 \ -i <(sed "s#^#file '#; s#$#'#" "$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt") \ -vf "scale=320:-1,tile=3x4" \ "$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg" ``` If process substitution is unavailable, generate the concat list as a real file and pass it to ffmpeg. ## Final Packet Review Treat these as first publication candidates: - `final/README.md` - `final/student-followup-guide.md` - `final/chapter-index.md` - `final/resources-and-links.md` - `final/instructor-review-checklist.md` Treat these as reference drafts until edited: - `final/qa-index.md` - `final/exercises.md` - `final/keyframes-manifest.md` Manual approval is mandatory for: - platform automation - browser automation - cookies - session replay - quota/rate-limit behavior - account credentials - private emails - private chat exports - meeting transcript bot URLs - student names - screenshots of private repos - local network addresses - QR codes - API keys - package security claims - third-party service recommendations - public publishing Reference ID: factory-video-analysis-reference Topic: Verification Sources: - [Published repeatable video reference](https://shiny-rosette-m6zy.here.now/skills/oracle-video/references/repeatable-video-followup-process.md) --- # Agent conversation search (cs) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Agent conversation search (cs) **John uses:** `cs` — his personal conversation-search CLI (`cs <term> --recent -n 20`) over all local Claude/Codex/Grok session history; section 00's fact-check of a month-old field guide against ~1,978 oracle sessions ran on it. **We could not find a public repo for cs; treat it as personal/unreleased.** | Alternative | What it is | How it differs | License | |----|----|----|----| | [cc-sessions-viewer](https://github.com/jerrywu001/cc-sessions-viewer) | Viewer for Claude Code/Codex/Antigravity/OpenCode sessions: global search, token stats, resume, HTML export | Closest public match: multi-agent session search in a UI rather than a grep-style CLI | none listed | | [claude-conversation-extractor](https://github.com/ZeroSumQuant/claude-conversation-extractor) | Extract clean conversation logs from Claude Code's internal storage | Extraction/export only — pipe the output into ripgrep for search; check current repository activity | MIT | | [llm logs (Simon Willison)](https://github.com/simonw/llm) | Every llm CLI prompt/response logged to SQLite; \`llm logs -q\` full-text search | Only covers conversations you run through llm, but the SQLite pattern is the most robust searchable-history design | Apache-2.0 | | [ripgrep over ~/.claude/projects and ~/.codex/sessions](https://github.com/BurntSushi/ripgrep) | Both Claude Code and Codex store sessions as local JSONL — rg searches them directly | The zero-tool option: \`rg -l 'term' ~/.claude/projects\` gets you 80% of cs today | MIT/Unlicense | | [ccusage](https://github.com/ccusage/ccusage) | npx ccusage — analytics over Claude Code local session data | Adjacent: usage/cost analytics over the same JSONL files, not content search | NOASSERTION | ### Pick this if… - **ripgrep** — start here; it's 80% of `cs` with zero new tools. - **cc-sessions-viewer** — you want cross-agent search in a UI with resume/export (young project). - **claude-conversation-extractor** — you want clean markdown exports to feed other tools. - **llm logs** — you're building new habits and want history searchable by design. - **ccusage** — you want the cost/usage half of session mining. Reference ID: factory-tools-conversation-search Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#conversation-search) --- # Agent foundations resource index > Original source pages and recordings require authorized access. The full article text here is public. Reference tools, packages, examples, and commands. A mention is not an implementation requirement: use the relevant playbook for the demonstrated workflow and its limitations. ## ADB tools [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## Agent Browser [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## AI Gateway [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Antigravity [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## beads [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) ## BUN [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## bun install [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Chrome DevTools MCP [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## Claude Code [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Cloud Code [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## Cmd-Opt-Shift-J [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## CMUX [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) · [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) · [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) · [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## CMUX open 3 panes and run LS in each of them [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## Codex [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## Codex Awesome Plugins [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Codex SDK [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## Codex Spark Low [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## Deep Wiki Map [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## GitHub CLI [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## GPT 5.5 [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## GrillMe [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) ## https://askoracle.sh/ [Open resource](https://askoracle.sh/) Shared reference [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/) ## https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm [Open resource](https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm) [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/) ## https://cmux.com/ [Open resource](https://cmux.com/) Shared reference to point out the primary product page for the CMUX terminal software application. [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/) ## https://codex-trainer.johnlindquist.workers.dev/ [Open resource](https://codex-trainer.johnlindquist.workers.dev/) [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) ## https://developers.openai.com/codex/hooks [Open resource](https://developers.openai.com/codex/hooks) [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/) ## https://developers.openai.com/codex/plugins [Open resource](https://developers.openai.com/codex/plugins) [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/) ## https://developers.openai.com/codex/plugins/build [Open resource](https://developers.openai.com/codex/plugins/build) [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/) ## https://github.com/aurorascharff/ClickLight [Open resource](https://github.com/aurorascharff/ClickLight) [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/) ## https://github.com/fayazara/Screendrop [Open resource](https://github.com/fayazara/Screendrop) [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/) ## https://github.com/gastownhall/beads [Open resource](https://github.com/gastownhall/beads) [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) · [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## https://github.com/johnlindquist/better-plugins/tree/main/plugins [Open resource](https://github.com/johnlindquist/better-plugins/tree/main/plugins) [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/) ## https://github.com/johnlindquist/cmux-extensions [Open resource](https://github.com/johnlindquist/cmux-extensions) [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) ## https://github.com/johnlindquist/codex-daemons [Open resource](https://github.com/johnlindquist/codex-daemons) [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## https://github.com/johnlindquist/oracle [Open resource](https://github.com/johnlindquist/oracle) The repo for my specific fork of this is just John Lindquist here [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/) ## https://github.com/karpathy/autoresearch [Open resource](https://github.com/karpathy/autoresearch) [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## https://github.com/openclaw/gogcli [Open resource](https://github.com/openclaw/gogcli) Shared in chat by John Lindquist to demonstrate the Google CLI configuration repository. [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/) ## https://github.com/vercel-labs/agent-browser [Open resource](https://github.com/vercel-labs/agent-browser) [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/) ## https://impeccable.style/ [Open resource](https://impeccable.style/) [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## https://inspiration-board.pages.dev/ [Open resource](https://inspiration-board.pages.dev/) [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) ## https://n8n.io/ [Open resource](https://n8n.io/) [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## https://stitch.withgoogle.com/ [Open resource](https://stitch.withgoogle.com/) Shared reference to show Google Stitch layout standard site components discussed during Impeccable demo. [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/) ## https://www.aihero.dev/skills-grill-me [Open resource](https://www.aihero.dev/skills-grill-me) [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) ## https://www.amazon.com/Rotating-Pomodoro-Minutes-Productivity-Vibration/dp/B0D7JG4VLD?th=1 [Open resource](https://www.amazon.com/Rotating-Pomodoro-Minutes-Productivity-Vibration/dp/B0D7JG4VLD?th=1) Shared reference to reference the physical rotating desktop timer device layout. [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/) ## https://www.dev.build/comics/prompt-quest/0?page=5 [Open resource](https://www.dev.build/comics/prompt-quest/0?page=5) [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## https://www.npmjs.com/package/packx [Open resource](https://www.npmjs.com/package/packx) Shared by John Lindquist to provide the source package locator for the file aggregation utility. [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/) ## https://www.youtube.com/watch?v=v4F1gFy-hqg [Open resource](https://www.youtube.com/watch?v=v4F1gFy-hqg) [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/) ## LazyGit [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) ## Notebook LM Notebook LM is a Google project. Contextual mention only; not a retained taught workflow for Oracle handoff. [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/) ## Oracle [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## PackX [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## PackX / pack tool Tool used to compress files into context tokens [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/) ## Pro GH summarize my commits from the past 2 days [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) ## ScreenPipe [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/) ## settings > apps > advanced settings Path dropped by a developer to configure state visibility [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/) ## skills.sh [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Tailwind CSS [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## unlink [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Vercel AI SDK [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Vercel CLI [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/) ## Warp Terminal [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) Reference ID: foundations-resources Topic: Tools Sources: - [Agent foundations: Route large codebase questions through Oracle (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-01.html) - [Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-02.html) - [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html) - [Agent foundations: Trust current source and capture design decisions (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-04.html) - [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html) - [Agent foundations: Use images, video, and task-shaped model routing (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-06.html) - [Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-07.html) - [Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-08.html) - [Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-09.html) - [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html) - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Agent skills: authoring & distribution (skills CLI) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Agent skills: authoring & distribution (skills CLI) **John uses:** the [skills CLI](https://github.com/vercel-labs/skills) (26.4k; `npx skills add <source> --skill <name>`, skills.sh) with canonical skills in `~/.agents/skills` symlinked into each agent's skill dir. Section 07 even publishes an installable skill on the workshop page itself. | Alternative | What it is | How it differs | License | |----|----|----|----| | [anthropics/skills](https://github.com/anthropics/skills) | Anthropic's public repository of Agent Skills | Official first-party skill collection to copy from rather than an installer CLI | none listed | | [superpowers](https://github.com/obra/superpowers) | An agentic skills framework and software-development methodology | Opinionated bundled methodology (brainstorm→plan→implement) vs à-la-carte skill installs | MIT | | [Claude Code plugins/marketplaces (built-in)](https://docs.claude.com/en/docs/claude-code) | Native plugin + marketplace system bundling skills, commands, hooks, MCP servers | First-party distribution channel; Claude-Code-only where skills.sh targets many agents | product | | [MCP servers](https://github.com/modelcontextprotocol) | Model Context Protocol: distribute agent capabilities as tool servers rather than markdown skills | Tools-as-processes vs instructions-as-markdown; complementary, heavier to build | open spec (MIT) | ### Pick this if… - **anthropics/skills** — you want first-party, well-audited skills to copy from. - **superpowers** — you want a whole opinionated methodology, not à-la-carte installs. - **Claude Code plugins** — you're Claude-Code-only and want first-party distribution. - **MCP** — the capability needs real code/tools, not instructions. Reference ID: factory-tools-skills-distribution Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#skills-distribution) --- # Agent-safe shell startup file examples These examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them. ## Safety and completeness boundaries - These are setup examples, not a drop-in configuration. The home-directory `.zshenv` forwards to `$ZDOTDIR/.zshenv`; do not install the same forwarding file at both locations. - The supplied bootstrap does not implement the `CODEX_LOAD_ZSH_DSL` opt-in loader described by the practical reference. Setting the marker alone does not load the helper snippets. Inspect or implement that reviewed bridge explicitly. - The exported `CODEX_AGENT_ENV_SOURCED` guard can be inherited by child shells, while ordinary shell functions are not inherited. A marker-only clean-shell check is not proof of a fully isolated environment. - The startup regression example checks helper presence rather than behavior. Its multi-file `zsh -n` invocation does not independently parse every supplied path; check each file separately when adopting the examples. - Node, Homebrew, pnpm, editor, and helper paths are illustrative installation choices. Use supported installed toolchain versions and preserve existing local configuration. ## zsh/.zprofile ```zsh # Login-shell setup for zsh. # Codex and similar agents commonly execute commands via `zsh -lc`, which reads # this file but not .zshrc. [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" ``` ## zsh/.zshenv ```zsh # Bootstrap ZDOTDIR for XDG-compliant zsh config export ZDOTDIR="${XDG_CONFIG_HOME:-$HOME/.config}/zsh" [[ -f "$ZDOTDIR/.zshenv" ]] && source "$ZDOTDIR/.zshenv" # Cargo (Rust) [[ -r "$HOME/.cargo/env" ]] && source "$HOME/.cargo/env" >/dev/null 2>&1 ``` ## zsh/codex-env.zsh ```zsh # ============================================================================= # Codex / Agent-Safe Shell Bootstrap # ============================================================================= # Loaded by $ZDOTDIR/.zprofile so non-interactive login shells (`zsh -lc`) get # the same tool paths and selected helper functions as interactive terminals. # # Keep this file free of prompt, completion, keybinding, and tty-only setup. # Interactive-only config belongs in .zshrc. # ============================================================================= [[ -n "${CODEX_AGENT_ENV_SOURCED:-}" ]] && return 0 export CODEX_AGENT_ENV_SOURCED=1 export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}" export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}" export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}" export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}" export ZDOTDIR="${ZDOTDIR:-$XDG_CONFIG_HOME/zsh}" # Homebrew shellenv is non-interactive and fills in HOMEBREW_* metadata. [[ -x /opt/homebrew/bin/brew ]] && eval "$(/opt/homebrew/bin/brew shellenv)" # Small, declarative modules that are safe for non-interactive shells. for _codex_env_file in \ "$ZDOTDIR/conf.d/00-path.zsh" \ "$ZDOTDIR/local.zsh" do [[ -r "$_codex_env_file" ]] && source "$_codex_env_file" done unset _codex_env_file # Tool-specific environment files that only export paths/vars. [[ -r "$HOME/.atuin/bin/env" ]] && source "$HOME/.atuin/bin/env" >/dev/null 2>&1 [[ -r "$HOME/.cargo/env" ]] && source "$HOME/.cargo/env" >/dev/null 2>&1 export CLAUDE_ENV_FILE="${CLAUDE_ENV_FILE:-$HOME/.claude/shell-init.sh}" # mdflow agent paths without loading the full interactive .zshrc. typeset -U path path=("$HOME/.mdflow" $path) export PATH="${(j/:/)path}" _codex_mdflow_path_refresh() { PATH=$(print -r -- "$PATH" \ | tr ':' '\n' \ | grep -vE '^(/[^/]+){4,}/\.mdflow$' \ | tr '\n' ':' \ | sed 's/:$//') [[ -d ".mdflow" ]] && export PATH="$PWD/.mdflow:$PATH" typeset -U path export PATH="${(j/:/)path}" } _codex_mdflow_path_refresh if command -v mdflow >/dev/null 2>&1; then md() { command mdflow "$@" } fi if command -v zoxide >/dev/null 2>&1; then eval "$(zoxide init zsh --no-cmd)" j() { __zoxide_z "$@" } z() { __zoxide_zi "$@" } fi ``` ## zsh/conf.d/00-path.zsh ```zsh # --- Module: PATH Plumbing (00-path.zsh) ------------------------------------- # Deterministic PATH/environment setup for shell startup. # Machine-specific overrides belong in `local.zsh`. # # --- DSL Vocabulary ----------------------------------------------------------- # Functions: (none; declarative module) # Verbs: export, prepend, deduplicate # --- Path De-duplication ------------------------------------------------------ typeset -U path # --- Configurable Defaults ---------------------------------------------------- # Override these defaults in `local.zsh` when needed. : "${NODE_VERSION:=23.6.1}" : "${HOMEBREW_PREFIX:=/opt/homebrew}" # --- Common Home Directories -------------------------------------------------- export ZSH="${ZSH:-$HOME/.oh-my-zsh}" export PNPM_HOME="${PNPM_HOME:-$HOME/Library/pnpm}" export BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}" # --- Warning Suppression ------------------------------------------------------ export PYTHONWARNINGS=ignore::DeprecationWarning # --- PATH Assembly ------------------------------------------------------------ # Ordering is intentional: toolchain bins first, then inherited PATH entries. path=( # Node, pnpm, and bun (highest priority). "$PNPM_HOME" "$HOME/Library/pnpm/nodejs/${NODE_VERSION}/bin" "$BUN_INSTALL/bin" # Homebrew and system binaries. "$HOMEBREW_PREFIX/opt/trash/bin" # Keg-only formula path. "$HOMEBREW_PREFIX/bin" /usr/local/bin /usr/bin /bin # User tool directories. "$HOME/.config/agents" "$HOME/.local/bin" "$HOME/.ma" # Existing PATH entries. $path ) # --- PATH Export -------------------------------------------------------------- export PATH="${(j/:/)path}" # --- PNPM Precedence Guard ---------------------------------------------------- # Prepend `PNPM_HOME` when absent so pnpm shims stay highest-priority. case ":$PATH:" in *":$PNPM_HOME:"*) ;; *) export PATH="$PNPM_HOME:$PATH" ;; esac ``` ## zsh/conf.d/40-ai.zsh ```zsh # Workshop-safe AI helper loader. # This file intentionally sources focused snippets instead of copying a full # private shell config. local _workshop_zsh_dir="${0:A:h:h}" for _workshop_fn_file in \ "$_workshop_zsh_dir/functions/codex-launch-and-prompt-builder.zsh" \ "$_workshop_zsh_dir/functions/shell-introspection.zsh" \ "$_workshop_zsh_dir/functions/fusion-fix.zsh" \ "$_workshop_zsh_dir/functions/orchestration-helpers.zsh" \ "$_workshop_zsh_dir/functions/script-kit-process-helpers.zsh" do [[ -r "$_workshop_fn_file" ]] && source "$_workshop_fn_file" done unset _workshop_fn_file _workshop_zsh_dir ``` ## zsh/conf.d/47-ai-fix.zsh ```zsh # Backward-compatible entrypoint for the focused workshop snippet. source "${0:A:h:h}/functions/fusion-fix.zsh" ``` ## zsh/examples/codex-config-shell-environment-policy.toml ```toml # Public shape only. Merge into your real ~/.codex/config.toml when you want # Codex tool shells to receive the marker. [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" ``` ## zsh/examples/local.zsh.example ```zsh # Machine-local overrides. # # Keep this file safe for non-interactive shells if it is sourced by # `codex-env.zsh`. # # Do not commit real API keys, tokens, private endpoints, or machine-specific # secrets. Use secret-manager helpers that resolve values at command execution # time, and avoid printing secret values during startup. # Example: add a local tool directory to PATH. typeset -U path path=("$HOME/.local/bin" $path) export PATH="${(j/:/)path}" # Example: command wrapper that resolves a secret only for the invoked command. # with_example_provider() { # EXAMPLE_API_KEY="$(op item get EXAMPLE_API_KEY --fields credential --reveal)" "$@" # } ``` ## zsh/tests/startup-regression.zsh ```zsh #!/usr/bin/env zsh # Public startup regression check for the bundled workshop zsh files. set -euo pipefail fail() { print -u2 -- "FAIL: $1" exit 1 } ROOT="${0:A:h:h}" zsh -n \ "$ROOT/.zshenv" \ "$ROOT/.zprofile" \ "$ROOT/codex-env.zsh" \ "$ROOT/conf.d/00-path.zsh" \ "$ROOT/conf.d/40-ai.zsh" \ "$ROOT/conf.d/47-ai-fix.zsh" \ "$ROOT"/functions/*.zsh || fail "syntax check failed" out="$( cd "$ROOT:h" zsh -lc 'source ./zsh/conf.d/40-ai.zsh; for name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do printf "%s:%s\n" "$name" "$(whence -w "$name" 2>/dev/null || echo MISSING)"; done' )" for name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do [[ "$out" == *"$name:$name: function"* ]] || fail "missing bundled helper: $name" done print -- "ok: bundled zsh startup regression" ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-startup-files Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # AI context bundlers (repo → prompt) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## AI context bundlers (repo → prompt) **John uses:** **packx** (`npm install -g packx`, johnlindquist on npm) — filters repository files **by content string** and extension before bundling for AI consumption, with saved search configs. Section 08's oracle skill uses it to bundle up to ~900k tokens per consult. (Related: [johnlindquist/pack](https://github.com/johnlindquist/pack), a content-filter front-end for Repomix.) | Alternative | What it is | How it differs | License | |----|----|----|----| | [Repomix](https://github.com/yamadashy/repomix) | Packs an entire repository into a single AI-friendly file (XML/MD), with token counts and remote-repo support | Whole-repo packing with include/exclude globs; packx's content-string filtering is the main thing it lacks (John's \`pack\` wraps Repomix to add it) | MIT | | [gitingest](https://github.com/coderamp-labs/gitingest) | Replace 'hub' with 'ingest' in any GitHub URL to get a prompt-friendly extract | Zero-install for public repos (URL trick + web UI); also a pip CLI | MIT | | [code2prompt](https://github.com/mufeedvh/code2prompt) | Rust CLI: codebase → single prompt with source tree, Handlebars templating, token counting | Template-driven output shaping; closest feature set to packx minus content search | MIT | | [files-to-prompt](https://github.com/simonw/files-to-prompt) | Simon Willison's minimal concatenator: directory → one prompt (pairs with his \`llm\` CLI) | Deliberately tiny; no filtering logic beyond paths; check current repository activity (stable, not active) | Apache-2.0 | | [yek](https://github.com/mohsen1/yek) | Fast Rust serializer for repo files, chunks by token budget, priority-orders files | Speed and token-budget chunking focus; good for very large repos | MIT | ### Pick this if… - **Repomix** — the default choice; the biggest, most maintained repo-packer. packx's content-search filtering is the one thing you'll miss. - **gitingest** — you mostly bundle public repos and want zero install. - **code2prompt** — you want templated output shaping (Handlebars) around the bundle. - **files-to-prompt** — you want the smallest possible tool, especially with `llm` (stable but not actively developed). - **yek** — your repos are huge and you need token-budget chunking fast. Reference ID: factory-tools-context-bundlers Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#context-bundlers) --- # Browser automation for agents (Oracle, agent-browser) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Browser automation for agents (Oracle, agent-browser) **John uses:** two distinct things. **[agent-browser](https://github.com/vercel-labs/agent-browser)** (38.6k, Apache-2.0) for general "agent drives a browser" tasks. And **Oracle** ([johnlindquist/oracle](https://github.com/johnlindquist/oracle) fork of a private setup) for the section 08 move: copy cookies from your logged-in Chrome profile and drive chatgpt.com / gemini.google.com directly — subscription-priced frontier reasoning (no API keys) and Gemini's video understanding, at ~1,978 sessions of real use. John runs it as `oracle serve` on a Mac mini behind Tailscale with a dual-account round-robin pool; most people would run it locally. **Honest note:** Oracle's cookie-riding consult niche has no maintained public equivalent we could verify. Substitutes are (a) rebuild the pattern on the tools below, or (b) pay for the API: Gemini API / Gemini CLI for video, ChatGPT Pro-tier reasoning via Codex CLI. | Alternative | What it is | How it differs | License | |----|----|----|----| | [browser-use](https://github.com/browser-use/browser-use) | Python library making websites accessible to AI agents; can attach to your real Chrome profile | General web-task automation with an LLM driver; you could rebuild Oracle's 'drive ChatGPT with cookies' trick on it | MIT | | [Playwright MCP](https://github.com/microsoft/playwright-mcp) | Microsoft's MCP server exposing Playwright browser control to any MCP-capable agent | Accessibility-tree-driven, works out of the box with Claude Code/Codex; persistent profiles carry logins | Apache-2.0 | | [Stagehand](https://github.com/browserbase/stagehand) | SDK for browser agents (act/extract/observe primitives on Playwright, by Browserbase) | Code-first SDK with hosted-browser option rather than a CLI; good for building your own Oracle-like service | MIT | | [Skyvern](https://github.com/Skyvern-AI/skyvern) | Automate browser workflows with LLMs + computer vision | Workflow-oriented (forms, portals) with a self-hostable server; AGPL | AGPL-3.0 | | [nanobrowser](https://github.com/nanobrowser/nanobrowser) | Chrome extension for multi-agent web automation with your own API keys | Runs INSIDE your logged-in browser, so it gets cookies for free like Oracle; check current repository activity (aging) | Apache-2.0 | ### Pick this if… - **Playwright MCP** — you use Claude Code/Codex and want browser control today with zero code; persistent profiles carry logins. - **browser-use** — you're in Python and want to script Oracle-style "drive a logged-in site" flows. - **Stagehand** — you're building a browser-agent *service* (hosted browsers, SDK ergonomics). - **Skyvern** — you automate form-heavy portals and can self-host (AGPL). - **nanobrowser** — you want automation living inside your already-logged-in browser (aging repo — verify). Reference ID: factory-tools-browser-automation Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#browser-automation) --- # Choose tools by the job, not the presenter’s stack Compare the capability you need, preserve uncertain product claims, and substitute tools without changing the operating pattern. ## TL;DR - 16 tool categories from the workshop, each with what John uses and 81 vetted alternatives in evidence tables (stars · last push · license). - The one move: adopt the *pattern*, not the exact tool — every section names the substitute that keeps the pattern alive under your constraints. Have your agent match these to your constraints — paste this into it: ``` text Fetch https://dewy-sleet-n5zs.here.now/agent.md?raw — a machine-readable list of every tool category in this workshop with vetted alternatives (name + URL + evidence). Ask me for my constraints (OS, license policy, budget, what I'm allowed to install), then recommend one alternative per category I can't adopt as-is, with your reasoning. ``` ## How to read this page This workshop demos John's exact stack. You don't need John's exact stack. Every pattern taught here — tiny wrappers, preloaded context, agent-driven browsers, taste voting — works with substitutes. Below: every tool the workshop mentions, what it does in John's system, and credible open-source or commercial alternatives with evidence. **Retrieved the recorded snapshot.** Star counts, last-push dates, and licenses come from the GitHub API on that date (`gh api repos/<owner>/<repo>`); non-GitHub products were sanity-checked by web search the same day. "NOASSERTION" means GitHub couldn't map the repo's license to an SPDX id (usually a custom or source-available license) — read the repo's LICENSE before adopting. Nothing here is an endorsement, and a few of John's tools are personal/unreleased — those are flagged, not glossed over (see the appendix). ## Also mentioned in the workshop These came up but don't need an alternatives table: - **[pi-session-id](https://github.com/johnlindquist/pi-session-id)** — the section 01 pi extension (MIT). The *pattern* (per-command shell prefix + session-scoped overrides) ports to any agent with shell hooks. - **Zed / Finder / GitHub open-cwd targets** (section 06) — editor-of-choice slots; any `open`/`code`-style CLI works. - **Linear CLI** (sections 01/05) — an example policy-wrapped command; substitute your tracker's CLI. - **Tailscale** (section 08) — how the Mac mini oracle server is reached; any WireGuard-style mesh works. - **wrangler / inspiration-board** (section 07) — covered under Publishing above. ## Appendix ### What we could NOT verify (flagged, not fabricated) - **cs** — no public repo found; treated as personal/unreleased, with the honest substitutes listed in §10. - **packx** — verified as John's npm package via web search (`npm install -g packx`), but it has no public GitHub repo we could find; star/license evidence unavailable. - **Oracle's exact consult architecture** — the fork repo exists ([johnlindquist/oracle](https://github.com/johnlindquist/oracle)) but is empty of description/stars; capabilities described here come from the workshop's own docs. - **Grok Build** star data — proprietary, no public repo; existence verified via x.ai announcement coverage. - License nuances behind every "NOASSERTION" — read the repo's LICENSE before commercial adoption (notably Crush, OpenHands, herdr, Sentry, OpenReplay, Infisical, Bitwarden). Reference ID: factory-tool-selection Topic: Tools Sources: - [Resource reference](https://dewy-sleet-n5zs.here.now/) --- # Codex Primitive Field Guide > Original source pages and recordings require authorized access. The full article text here is public. AGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers. Use this when a workflow keeps failing because instructions, tools, and enforcement are all living in the same prompt. > Skills use progressive disclosure to manage context efficiently. [OpenAI Codex Skills docs](https://developers.openai.com/codex/skills) ## Choose the right mechanism | Mechanism | Use when | Agent responsibility | Artifact | |---|---|---|---| | AGENTS.md | Stable repo or directory rules | Setup, commands, conventions, done criteria | Short instruction file near the code | | Skill | Reusable workflow with judgment | Browser proof, release notes, Oracle handoff | .agents/skills/<name>/SKILL.md | | Plugin | Shareable installable bundle | Team workflow with skills, MCP, apps, hooks | .codex-plugin/plugin.json plus bundled folders | | Hook | Lifecycle enforcement | Prompt injection, tool policy, Stop receipt gate | hooks/hooks.json plus small scripts | | MCP | External systems and context | Browser, Figma, docs, DB, SaaS tools | .mcp.json plus tool policy | | Goal mode | Long-running objective | Research, plan, implement, verify loop | .goals/<task>.md plus receipts | ## Agent-ready prompt ```text Create a Codex primitive map for this repo. Read AGENTS.md, package scripts, existing skills/plugins/hooks, and MCP config first. For each repeated workflow, decide whether it belongs in AGENTS.md, a skill, a plugin, a hook, MCP, or a goal file. Write .notes/codex-primitives/decision.md with the decision, files to create, verification command, and rollback path. ``` ## Applied stories ### Next.js monorepo guardrails **Role:** Platform lead Agents keep running the wrong tests and claiming UI work is done without proof. **Agent brief:** Ask Codex to create a root AGENTS.md under 120 lines, copy commands from package scripts or CI, and add browser-proof expectations for UI work. **Done when:** - AGENTS.md exists - Commands match real scripts - Codex can summarize loaded instructions - No one-off task details ### Browser proof skill **Role:** SaaS frontend engineer Every UI fix needs the same route, viewport, action, console, screenshot, and command receipt. **Agent brief:** Ask Codex to create .agents/skills/browser-proof-saas/SKILL.md with clear trigger and non-trigger language. **Done when:** - SKILL.md has name/description - Proof schema is included - Smoke prompt exists - Skill says when not to use it ### Checkout Stop-hook gate **Role:** Checkout owner Agents stop after one validation fix instead of proving cart to confirmation. **Agent brief:** Ask Codex to scaffold a local plugin with a Stop hook that continues until checkout test and browser receipts exist. **Done when:** - Manifest validates - Hook simulator covers missing/success/cap - Receipts are named - No global install before simulation ## Tips and gotchas - Keep AGENTS.md short. Put workflow machinery in skills/plugins/hooks. - Treat a skill as guidance, not enforcement. Move deterministic checks to hooks. - Use current Codex Stop-hook behavior: return decision: "block" with a reason to continue the turn. - Installing a plugin does not automatically make plugin hooks trusted. Teach users to review and trust hook definitions. - Use MCP for external stateful systems; use local package scripts for repo-local tests and builds. ## References - [OpenAI Codex Skills](https://developers.openai.com/codex/skills) - [OpenAI Codex Plugins](https://developers.openai.com/codex/plugins) - [OpenAI Codex Hooks](https://developers.openai.com/codex/hooks) - [OpenAI AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) - [AGENTS.md standard](https://agents.md/) - [Better Plugins examples](https://github.com/johnlindquist/better-plugins/tree/main/plugins) ## Related principles - [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/) - [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/) Reference ID: foundations-codex-primitives-field-guide Topic: Tools Sources: - [Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-07.html) - [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html) --- # Fusion panel execution runbook Use the local Fusion CLI for independent panel feedback when a task benefits from critique, architecture tradeoff review, implementation planning, or synthesis. ## Operating Rules - Use the local commands directly: `fusion-high`, `fusion-med`, or `fusion`. - Do not substitute Oracle/MCP wrappers for the Fusion CLI. - Before real runs, inspect providers with `fusion-high --list-providers`, `fusion-med --list-providers`, or `fusion --list-providers`. - Run all configured providers for the selected preset first, and wait for every provider to reach a terminal state: `ok`, `failed`, `timedOut`, `quotaLimited`, `spawnError`, or `interrupted`. - Fusion is a blocking council call. After starting a real Fusion run, do not plan, implement, edit files, run unrelated commands, answer the user, or "work ahead" while waiting. The point of Fusion is to use the council output as the next input. - Do not treat elapsed time, early partial artifacts, or one strong provider answer as permission to continue independently. Continue only after Fusion exits and `summary.json` plus final output have been read, or after a real terminal failure/interruption has been captured. - Treat `panel-*.stdout.md` and `panel-*.json` as partial council artifacts until Fusion writes `summary.json` and final output. Do not interrupt a run merely because one or more useful provider responses have landed. - While a run is active, use `panel-status.json` and heartbeat stderr messages to see which providers are still pending or running. - If one provider fails or times out after panel artifacts are created, keep the artifact and let Fusion continue to judge/synthesis with the degraded panel. - If any provider reports quota, rate-limit, usage-limit, or 429 exhaustion, treat that provider as non-blocking for the current run. Do not stop to ask the user; report the model as quota-limited and continue with the remaining provider outputs. - Do not use `--only` for ordinary narrowing, model preference, or convenience. It is allowed only when the user explicitly requests a subset. - For long prompts, write a prompt file and use `--file` instead of fragile shell quoting. - Use `--dry-run` when command shape, provider IDs, config, or output location is uncertain. - Let Fusion choose its default output location unless the user explicitly asks for a run directory. Current Fusion writes automatic runs to `~/.fusion/sessions/YYYY/MM/DD/<session-id>/` and indexes them in `~/.fusion/sessions.jsonl`. - Do not pass `--out .fusion-runs/<slug>` by default; `--out` intentionally bypasses the `~/.fusion` session store. - Treat Fusion output as advisory. Read the artifacts, reconcile disagreements, and make the final engineering call from repo evidence. ## Command Shape ```bash fusion-high --list-providers fusion-high --dry-run --file path/to/prompt.md fusion-high --file path/to/prompt.md ``` For moderate planning: ```bash fusion-med --list-providers fusion-med --file path/to/prompt.md ``` For custom config: ```bash fusion --config path/to/fusion.config.json --file path/to/prompt.md ``` Use explicit output overrides only when requested or when a workflow needs repo-local artifacts: ```bash fusion-high --file path/to/prompt.md --out .fusion-runs/<slug> fusion-high --file path/to/prompt.md --runs-dir .fusion-runs ``` ## Prompt Guidance Include the user request, success criteria, relevant repo paths, constraints, commands already run, observed failures, desired panel roles, and requested verification steps. Avoid sending secrets, tokens, credentials, or unrelated large context. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-fusion-runbook Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Image generation for design variations Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Image generation for design variations **John uses:** Codex's built-in **\$imagegen** skill (GPT image model, no API key beyond the Codex subscription) and **agy** — the [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) (1.6k) with Gemini's `generate_image` — to produce 9 wildly different mockups per prompt, then hands the winner to a coding agent as a reference image (section 07). | Alternative | What it is | How it differs | License | |----|----|----|----| | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google's terminal agent; image generation via Gemini/Imagen models on the free tier | Same Google image models as agy without the Antigravity harness | Apache-2.0 | | [ComfyUI](https://github.com/Comfy-Org/ComfyUI) | Node-graph GUI/API/backend for diffusion models, fully local | Local + free at inference; scriptable API makes 9x batch generation easy; needs a GPU and setup | GPL-3.0 | | [mflux](https://github.com/filipstrand/mflux) | MLX-native FLUX and other image models on Apple Silicon | Runs the 9x pattern locally on the same Mac you present from; CLI-first | MIT | | [InvokeAI](https://github.com/invoke-ai/InvokeAI) | Professional creative engine/WebUI for Stable Diffusion family models | Polished local UI aimed at designers rather than agent scripting | Apache-2.0 | | [AUTOMATIC1111 stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui) | The historically dominant SD web UI | Huge ecosystem but slowing maintenance (check repository activity before adoption); prefer ComfyUI/Invoke for new setups | AGPL-3.0 | ### Pick this if… - **Gemini CLI** — you want the agy pattern without Antigravity, free. - **ComfyUI** — you want local, free-at-inference batch generation with a scriptable API (needs GPU). - **mflux** — you present from a Mac and want the 9x loop fully local on Apple Silicon. - **InvokeAI** — you want a designer-friendly local UI over raw pipelines. - **A1111** — only if you need its ecosystem; prefer ComfyUI/Invoke for new setups. Reference ID: factory-tools-image-generation-variations Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#image-generation-variations) --- # Image-to-design handoff playbook > Original source pages and recordings require authorized access. The full article text here is public. Web developers already live in running apps, local dev servers, screenshots, and browser proof. This pack turns the taught image-to-design handoff into concrete flows where a selected reference image guides the code diff and the browser proves the result. [Core principles](/topics/foundations-multimodal-design-and-model-routing/) ## Copy-paste workflow **When to use:** When you can recognize the look you want but can't spec exact CSS. Generate a sheet of visual variations, pick the direction, and hand that concrete reference image to a coding agent to implement only that direction. ### Copy-paste prompt ```text Help me do an image-to-design handoff for <COMPONENT/SCREEN>. I can recognize the look I want but can't spec the CSS, so we'll let a selected reference image carry my taste. 1. Ask an image model for a SHEET of 5 visual variations of <COMPONENT/SCREEN> in one image (vary layout, color, type, density). 2. Stop and let ME select the direction I like. (My selection expresses taste far better than a vague text prompt.) 3. Take the chosen reference image and implement ONLY that direction in code — match its layout, spacing, color, and type. Do not blend in the other variations. Guardrails: - MCP-vs-CLI boundary: don't wrap a CLI in MCP just because MCP exists. Keep deterministic work in scripts/CLIs; reserve agents for judgment calls like this selection. - Model-by-task-shape: use Codex for the coding follow-through; reserve fast Flash-class models for small, tightly scoped tasks only. ``` ### How it works - Step 1 asks an image model for a sheet of 5 variations of one component/screen at once. - Step 2 puts the human in the loop: selecting a direction expresses taste better than a vague prompt. - Step 3 hands the chosen reference image to the coding agent and constrains it to implement only that direction. - Taught caution — the MCP-vs-CLI boundary: don't wrap a CLI in MCP just because MCP exists; keep deterministic work in scripts/CLIs and reserve agents for judgment. - Model-by-task-shape: Codex for coding follow-through, fast Flash models only for small scoped tasks. - Reference: [Google Gemini video/image prompting](https://github.com/manaflow-ai/cmux), [Codex CLI](https://github.com/openai/codex). ## Scenarios ### Dashboard card from selected reference **Role:** As a frontend engineer maintaining a Next.js product dashboard A billing or usage card in a real dashboard route works correctly but looks generic and has drifted from the product direction. You have a screenshot of the current component and either a selected reference image already chosen by the human or permission to generate a sheet of variations and pause for selection. > As a frontend engineer, I want Codex to implement one selected visual direction for the dashboard card while preserving existing data and behavior, so that the UI improves without turning a working component into a risky rewrite. #### Agent brief ```text Copy-paste to Codex: Use the image-to-design handoff workflow for the dashboard card at <ROUTE>, backed by these artifacts: current screenshot <CURRENT_SCREENSHOT_PATH>, selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, and relevant source files <COMPONENT_OR_ROUTE_PATHS>. 1. Inspect package.json and the current component/source before editing. Treat the live code as source of truth for props, data loading, auth, events, and tests. 2. If <SELECTED_REFERENCE_IMAGE_PATH> does not exist yet, ask an image model for one sheet of 5 visual variations of this exact card based on <CURRENT_SCREENSHOT_PATH>, then stop and ask me which direction to use. Do not implement until I pick one. 3. Once the selected reference exists, implement ONLY that direction. Match layout, spacing, color, type, density, border/radius, and visual hierarchy. Do not blend in other variations. Preserve existing copy, links, data-testid values, analytics attributes, and behavior unless a markup change is necessary for accessibility. 4. Run `npm run lint`. Run the nearest existing test command from package.json if one is already present; do not invent a test framework. 5. Run `npm run dev` and prove the result in a browser at `http://127.0.0.1:3000<ROUTE>` or the port printed by the dev server. Expected output: a focused diff, the commands run, a browser screenshot saved as `artifacts/image-to-design-dashboard-card.png`, and a short review note listing inspected files plus any intentional differences from the reference. ``` #### Implementation references [Open reference](/topics/foundations-image-to-design-playbook/) [Open reference](/topics/foundations-image-to-design-playbook/) [Open reference](/topics/foundations-multimodal-design-and-model-routing/) ```text package.json ``` ```text <COMPONENT_OR_ROUTE_PATHS> ``` ```text <CURRENT_SCREENSHOT_PATH> ``` ```text <SELECTED_REFERENCE_IMAGE_PATH> ``` #### Browser verification Use a CMUX browser pane or an agent-browser-style flow: open `http://127.0.0.1:3000<ROUTE>`, take an accessibility snapshot to confirm the card title, values, and CTA names are still present, then use evaluate to capture bounding boxes and computed styles for the card root, heading, primary value, and CTA. Save a screenshot after the DOM proof; a screenshot alone is not enough. #### Definition of done - Git diff is limited to the target component/route and supporting style files. - `npm run lint` passes, and any pre-existing nearest test command either passes or the failure is documented with exact output. - `artifacts/image-to-design-dashboard-card.png` shows the local route matching the selected reference direction closely enough for human review. - Browser proof includes accessibility snapshot evidence that labels, values, links, and CTA names were not lost. - Review note explicitly says which reference image was used and confirms no other variation was blended in. #### Failure modes and mitigations - The agent averages several generated directions into a mushy UI; mitigate by removing non-selected references from context and repeating: implement ONLY <SELECTED_REFERENCE_IMAGE_PATH>. - The agent rewrites data loading or auth while chasing the visual target; mitigate by requiring source inspection first and rejecting diffs outside the target UI/styling surface. - The agent claims visual success from code only; mitigate by requiring browser screenshot plus accessibility snapshot/evaluate evidence from the running dev server. ### Auth-gated onboarding visual refresh **Role:** As a full-stack product engineer responsible for a SaaS onboarding flow The onboarding flow behind login is functional, but the organization setup step needs to match a selected generated reference image. The proof has to run through the real browser flow because the page depends on auth state, form validation, redirects, and route guards. > As a product engineer, I want the agent to apply the selected image direction to the onboarding step and verify it through login and form interaction, so that the visual refresh does not break the first-run user path. #### Agent brief ```text Copy-paste to Codex: Apply image-to-design handoff to the onboarding screen at <ONBOARDING_ROUTE>. Artifacts: selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, current screenshot <CURRENT_SCREENSHOT_PATH>, explicit login or seed instructions <AUTH_INSTRUCTIONS>, and source hints <AUTH_FILES_AND_ONBOARDING_FILES>. 1. Inspect the route, auth guard, form component, validation messages, and existing tests before editing. Do not assume browser cookies are shared with the automation environment. 2. Implement ONLY the visual direction in <SELECTED_REFERENCE_IMAGE_PATH>. Preserve the onboarding state machine, validation behavior, submit handlers, redirects, copy, and analytics/data attributes. 3. If a selected reference is missing, generate one sheet of 5 visual variations for this onboarding step, then stop for human selection before editing code. 4. Run `npm run lint`. If package.json already defines a relevant test, run that exact script. Do not add a new browser framework just to prove this change. 5. Run `npm run dev`. Verify in a browser from login through <ONBOARDING_ROUTE> using <AUTH_INSTRUCTIONS>. Expected output: focused UI diff, command logs, `artifacts/onboarding-before-or-current.png` if available, `artifacts/onboarding-after-selected-reference.png`, and a short proof note covering login, validation, successful submit or expected blocked submit, and any console/dev-server errors. ``` #### Implementation references [Open reference](/topics/foundations-image-to-design-playbook/) [Open reference](/topics/foundations-multimodal-design-and-model-routing/) [Open reference](/topics/foundations-multimodal-design-and-model-routing/) ```text package.json ``` ```text <AUTH_FILES_AND_ONBOARDING_FILES> ``` ```text <AUTH_INSTRUCTIONS> ``` ```text <CURRENT_SCREENSHOT_PATH> ``` ```text <SELECTED_REFERENCE_IMAGE_PATH> ``` #### Browser verification Use agent-browser-style actions: snapshot the login screen, fill the explicit test email/password or complete the provided seed-login path, click through to <ONBOARDING_ROUTE>, snapshot the form, fill a realistic organization name, click Continue, and evaluate that validation text, focus state, and redirect/blocked-submit behavior still match the original flow. This is the right proof because auth, route guards, and form behavior cannot be trusted from a static screenshot. #### Definition of done - Browser path starts from an unauthenticated state and reaches the onboarding screen through the documented login or seed flow. - The refreshed onboarding screen visually follows the selected reference image while preserving form labels, validation, focus states, and submit behavior. - `npm run lint` passes and relevant existing tests pass or exact failure output is included. - Screenshot and browser snapshot artifacts are saved under `artifacts/` with names tied to the route. - The final note calls out that cookies were not assumed and names the auth path used. #### Failure modes and mitigations - The browser agent gets stuck because it expects the human's normal cookies; mitigate by giving explicit auth/seed instructions and starting proof from a clean browser state. - The visual refresh hides validation or keyboard focus states; mitigate by tabbing through the form and evaluating visible focus/validation output before declaring done. - The agent changes redirects or submit logic while editing the screen; mitigate by diff-reviewing handlers and requiring the browser path to prove submit or expected blocked submit. ### Responsive marketing hero handoff **Role:** As a growth-focused web developer shipping a marketing route A landing page hero needs to move from vague direction like 'more premium' to a concrete selected image. The desktop composition is the design target, but the implementation also needs mobile proof because the route is public and responsive. > As a growth developer, I want the agent to translate one selected hero reference into the actual landing page while preserving CTA behavior and responsive layout, so that the shipped page has a clear visual direction and does not break conversion paths. #### Agent brief ```text Copy-paste to Codex: Implement the selected image-to-design direction for the marketing hero at <MARKETING_ROUTE>. Artifacts: selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, current route screenshot <CURRENT_SCREENSHOT_PATH>, and relevant source files <HERO_ROUTE_AND_COMPONENT_FILES>. 1. Inspect package.json, the hero route/component files, and any shared button/link components before editing. Preserve copy, hrefs, tracking attributes, data-testid values, and form/newsletter behavior. 2. If there is no selected reference image, ask an image model for a sheet of 5 hero variations from the current screenshot and product constraints, then stop for human selection. 3. Implement only the selected direction. Match composition, rhythm, spacing, type scale, contrast, image/illustration treatment, and CTA prominence. Do not introduce a maintained design system or broad route-variant workflow for this task. 4. Run `npm run lint` and any existing route/component test script listed in package.json. 5. Run `npm run dev` and prove desktop and mobile in the browser. Expected output: a focused diff, desktop screenshot `artifacts/hero-desktop-selected-reference.png`, mobile screenshot `artifacts/hero-mobile-selected-reference.png`, command output, and a concise implementation note describing how the selected image was translated into code. ``` #### Implementation references [Open reference](/topics/foundations-image-to-design-playbook/) [Open reference](/topics/foundations-image-to-design-playbook/) [Open reference](/topics/foundations-multimodal-design-and-model-routing/) ```text package.json ``` ```text <HERO_ROUTE_AND_COMPONENT_FILES> ``` ```text <CURRENT_SCREENSHOT_PATH> ``` ```text <SELECTED_REFERENCE_IMAGE_PATH> ``` #### Browser verification Use a local browser, CMUX browser pane, or Playwright if already present. Open `http://127.0.0.1:3000<MARKETING_ROUTE>` at 1440x900 and 390x844. Take screenshots at both sizes. Use evaluate to assert `document.documentElement.scrollWidth <= document.documentElement.clientWidth`, the primary CTA is visible without horizontal scroll, and the CTA href/data attributes are unchanged. #### Definition of done - Desktop and mobile screenshots are both saved and reviewable. - No horizontal overflow at the mobile viewport. - Primary CTA remains visible, clickable, and wired to the original href or handler. - `npm run lint` and any relevant existing test script pass or include exact failure logs. - Final review note maps the selected image's visible traits to concrete implementation choices: spacing, type, color, layout, and CTA treatment. #### Failure modes and mitigations - The agent overfits the desktop reference and breaks mobile; mitigate by making mobile viewport proof part of done, not a later nice-to-have. - The agent replaces tracked links/buttons while restyling; mitigate by preserving hrefs, handlers, data-testid values, and analytics attributes and checking them with browser evaluate. - The agent turns a one-screen handoff into a broad design-system rewrite; mitigate by limiting scope to <HERO_ROUTE_AND_COMPONENT_FILES> and the selected image direction. ## Implementation notes - Keep the technique narrow: image sheet, human selection, implement only the selected reference, browser proof. - For web apps, the selected image is not enough. The agent must inspect current source first so it preserves data loading, auth, handlers, copy, tests, and route behavior. - Use Codex or a persistent coding agent for the implementation pass. Fast Flash-style models are a poor fit for a multi-step UI implementation that may require self-correction. - Use deterministic scripts and browser checks for proof. Do not wrap a direct CLI or test command in MCP just because MCP is available. - Do not claim pixel perfection. Ask for concrete evidence: screenshots, accessibility snapshots, computed style or bounding-box checks, command logs, and a short diff review note. - When auth is involved, do not assume cookies are available. Provide explicit login, seed, or test-account instructions and prove the flow from a clean browser state. - Generated reference images can express taste, but the human selection is the decision point. The agent should stop before implementation when no selected reference exists. ## Boundaries and caveats - Do not turn this into an Impeccable or Google Stitch tutorial. Impeccable was only lightly highlighted, and the lesson did not teach a full `npx impeccable` workflow. - Do not introduce Google Stitch, Executor, Clicklight, pi.dev, or broad tool comparisons as required implementation steps for this topic. - Do not use a maintained Storybook/design-system expansion as the default answer; that is beyond this one toolkit technique. - Do not let the agent blend several generated variations. The handoff depends on one selected reference image. - Do not change business logic, auth, analytics, or data fetching unless the requested visual handoff explicitly requires it. - Do not hide behind an MCP wrapper when a direct repo-local command, browser check, or script is clearer and easier to verify. - Do not treat browser screenshots as the only proof for interactive web flows; include snapshot/click/fill/evaluate evidence where interaction matters. ## Agent reference map ### Image-to-design handoff prompt Use as the base copy-paste workflow: generate a sheet, pause for human selection, then implement only the chosen reference image. [Open reference](/topics/foundations-image-to-design-playbook/) ### Lesson 06 validated references Grounds the scenarios in the taught concepts: CMUX orchestration, model choice by task shape, generated images as design references, video context, and MCP-vs-CLI boundaries. [Open reference](/topics/foundations-multimodal-design-and-model-routing/) ### Lesson 06 validation notes Use this to avoid reintroducing items that were only mentioned or softened, especially around Impeccable, Google Stitch, Executor, Clicklight, and pi.dev. [Open reference](/topics/foundations-multimodal-design-and-model-routing/) ### Packed source bundle Use as the local bundle snapshot when an agent needs the prompt, references, catalog context, and Gemini analysis in one place. ```text /mnt/data/scenario-image-design.txt ``` ### CMUX browser or pane state Use when the agent needs to identify the current pane or coordinate browser proof from a CMUX workspace. ```text cmux --json tree ``` ### Browser verification primitive shape Use for web proof after implementation: snapshot for accessible structure, click/fill for flows, evaluate for DOM/style assertions, and screenshot for human visual review. ```text agent-browser-style workflow: snapshot -> click/fill -> evaluate -> screenshot ``` Reference ID: foundations-image-to-design-playbook Topic: Tools Sources: - [Agent foundations: Use images, video, and task-shaped model routing (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-06.html) --- # Imp routing hook and cmux helper examples These examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them. ## Safety and completeness boundaries - The fork template bypasses approvals and sandboxing. Review this explicitly before installing any hook; prompt interception is executable code, not just a prompt convention. - The registry example only reads mappings. It neither registers sessions nor implements a screen-scraping fallback; `--allow-screen` is an accepted compatibility argument. - The cmux helper receipt proves dispatch to a surface, not successful completion of the command. Verify target workspace, working directory, and resulting behavior. - Hook logs may contain prompt text, local paths, session identifiers, and subprocess output. Keep runtime logs private and review retention/redaction. - Test ambiguous prefixes, timeouts, and hook errors against the installed roster. Do not infer that every routing failure blocks or that a timeout means no pane was opened. ## hooks/cmux-codex-session-registry.py.example ```python #!/usr/bin/env python3 """Redacted cmux-to-Codex session registry contract. This example documents the command surface used by zsh helpers such as `_codex_cmux_current_session_id`. It is intentionally not a copy of a private registry implementation. """ from __future__ import annotations import argparse import json import sys from pathlib import Path def registry_path() -> Path: return Path.home() / ".codex" / "cmux-codex-sessions.json" def load_registry(path: Path) -> dict[str, str]: if not path.exists(): return {} data = json.loads(path.read_text()) if not isinstance(data, dict): raise ValueError("registry must be a JSON object") return {str(key): str(value) for key, value in data.items()} def main() -> int: parser = argparse.ArgumentParser(description="Resolve cmux surface ids to Codex session ids.") parser.add_argument("--registry-path", action="store_true", help="print the registry path") parser.add_argument("--resolve-surface", help="surface id, for example surface:123") parser.add_argument("--allow-screen", action="store_true", help="accepted for compatibility") args = parser.parse_args() path = registry_path() if args.registry_path: print(path) return 0 if args.resolve_surface: session_id = load_registry(path).get(args.resolve_surface) if not session_id: return 1 print(session_id) return 0 parser.print_help(sys.stderr) return 2 if __name__ == "__main__": raise SystemExit(main()) ``` ## hooks/cmux-run-surface.example ```sh #!/bin/sh # Example contract for opening a new focused cmux terminal pane and running a command. # Review before installing as ~/.local/bin/cmux-run-surface. set -eu CMUX="${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}" JQ="${JQ_BIN:-/usr/bin/jq}" LOG="$HOME/Library/Logs/cmux-run-surface.log" DIRECTION="right" case "${1:-}" in --below|--down) DIRECTION="down" shift ;; --right) shift ;; esac COMMAND_TEXT="${1:-}" [ -n "$COMMAND_TEXT" ] || { /bin/echo "Usage: cmux-run-surface [--below|--right] <command>" >&2 exit 64 } log() { /bin/echo "[$(/bin/date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG"; } [ -x "$CMUX" ] || { log "cmux CLI not found at $CMUX"; exit 1; } [ -x "$JQ" ] || { log "jq not found at $JQ"; exit 1; } cur="$("$CMUX" rpc workspace.current 2>>"$LOG")" CWD="$(/bin/echo "$cur" | "$JQ" -r '.workspace.current_directory // empty')" WORKSPACE_ID="$(/bin/echo "$cur" | "$JQ" -r '.workspace_id // .workspace.id // empty')" WINDOW_ID="$(/bin/echo "$cur" | "$JQ" -r '.window_id // .window.id // empty')" [ -n "$CWD" ] || { log "no current_directory in workspace.current: $cur"; exit 1; } [ -n "$WORKSPACE_ID" ] || { log "no workspace id in workspace.current: $cur"; exit 1; } [ -n "$WINDOW_ID" ] || { log "no window id in workspace.current: $cur"; exit 1; } pane_output="$("$CMUX" rpc pane.create "{\"workspace_id\":\"$WORKSPACE_ID\",\"window_id\":\"$WINDOW_ID\",\"direction\":\"$DIRECTION\",\"type\":\"terminal\",\"focus\":true}" 2>>"$LOG")" PANE_ID="$(/bin/echo "$pane_output" | "$JQ" -r '.pane_id // .pane.id // empty')" PANE_REF="$(/bin/echo "$pane_output" | "$JQ" -r '.pane_ref // .pane.ref // empty')" WORKSPACE_REF="$(/bin/echo "$pane_output" | "$JQ" -r '.workspace_ref // .workspace.ref // empty')" WINDOW_REF="$(/bin/echo "$pane_output" | "$JQ" -r '.window_ref // .window.ref // empty')" [ -n "$PANE_ID" ] || { log "no pane id in pane.create output: $pane_output"; exit 1; } SURFACE="" i=0 while [ "$i" -lt 20 ]; do surfaces_output="$("$CMUX" rpc pane.surfaces "{\"pane_id\":\"$PANE_ID\",\"workspace_id\":\"$WORKSPACE_ID\",\"window_id\":\"$WINDOW_ID\"}" 2>>"$LOG")" SURFACE="$(/bin/echo "$surfaces_output" | "$JQ" -r '.surfaces[]? | select((.type // "") == "terminal") | .ref // .id' | /usr/bin/head -n 1)" [ -n "$SURFACE" ] && break i=$((i + 1)) /bin/sleep 0.1 done [ -n "$SURFACE" ] || { log "could not find terminal surface in pane: $PANE_ID"; exit 1; } "$CMUX" send --workspace "$WORKSPACE_ID" --surface "$SURFACE" "$COMMAND_TEXT" 2>>"$LOG" "$CMUX" send-key --workspace "$WORKSPACE_ID" --surface "$SURFACE" enter 2>>"$LOG" # Stable receipt consumed by the Imp hook. /bin/echo "OK surface=$SURFACE pane=${PANE_REF:-$PANE_ID} workspace=${WORKSPACE_REF:-$WORKSPACE_ID} window=${WINDOW_REF:-$WINDOW_ID}" ``` ## hooks/hooks.json.example ```json { "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "python3 \"$HOME/.codex/hooks/imp-user-prompt-submit.py\"", "timeout": 5, "statusMessage": "Routing imp prompt" } ] } ] } } ``` ## hooks/imp-user-prompt-submit.py.template ```python #!/usr/bin/env python3 """Example UserPromptSubmit hook for dash-prefix Imp routing. Install target after review: ~/.codex/hooks/imp-user-prompt-submit.py """ from __future__ import annotations import json import os import re import shlex import shutil import subprocess import sys from dataclasses import dataclass from pathlib import Path from typing import Any IMP_LINE_RE = re.compile(r"^\s{2}(imp-[a-z0-9][a-z0-9-]*)\s+(.+?)\s*$") PROMPT_RE = re.compile(r"^\s*-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$") FORK_PROMPT_RE = re.compile(r"^\s*--([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$") CMUX_RECEIPT_RE = re.compile(r"\b(surface|pane|workspace|window)[=:]([A-Za-z0-9_.:-]+)") @dataclass(frozen=True) class Imp: command: str description: str executable_path: str = "" @property def name(self) -> str: return self.command.removeprefix("imp-") def log(event: dict[str, Any]) -> None: try: path = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser() / "logs" / "imp-user-prompt-submit.jsonl" path.parent.mkdir(parents=True, exist_ok=True) with path.open("a", encoding="utf-8") as handle: handle.write(json.dumps(event, sort_keys=True) + "\n") except Exception: pass def emit_continue(additional_context: str | None = None) -> None: out: dict[str, Any] = {"continue": True, "suppressOutput": True} if additional_context: out["hookSpecificOutput"] = { "hookEventName": "UserPromptSubmit", "additionalContext": additional_context, } print(json.dumps(out, separators=(",", ":"))) def emit_block(reason: str) -> None: print( json.dumps( { "continue": True, "decision": "block", "reason": reason, "suppressOutput": False, }, separators=(",", ":"), ) ) def read_payload() -> dict[str, Any]: raw = sys.stdin.read() if not raw.strip(): return {} return json.loads(raw) def read_imps() -> list[Imp]: imp_palette = shutil.which("imp-") if not imp_palette: return [] result = subprocess.run( [imp_palette], check=False, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=2, ) if result.returncode != 0: return [] imps: list[Imp] = [] for line in result.stdout.splitlines(): match = IMP_LINE_RE.match(line) if not match: continue command = match.group(1) imps.append( Imp( command=command, description=match.group(2).strip(), executable_path=shutil.which(command) or "", ) ) return imps def normalize_name(raw: str) -> str: return raw.strip().lower().replace("_", "-").removeprefix("imp-") def acronym(text: str) -> str: return "".join(part[0] for part in re.split(r"[-\s]+", text) if part) def is_subsequence(needle: str, haystack: str) -> bool: pos = 0 for char in needle: found = haystack.find(char, pos) if found < 0: return False pos = found + 1 return True def score_imp(query: str, imp: Imp) -> int: name = imp.name description = imp.description.lower() words = set(re.findall(r"[a-z0-9]+", description)) if query == name or query == imp.command: return 100 if name.startswith(query): return 85 if query.startswith(name): return 80 if query == acronym(name): return 78 if query in name: return 70 if query in words: return 62 if query in description: return 55 if len(query) >= 3 and is_subsequence(query, name): return 48 return 0 def find_imp(raw_name: str, imps: list[Imp]) -> tuple[Imp | None, list[tuple[int, Imp]]]: query = normalize_name(raw_name) ranked = sorted( ((score_imp(query, imp), imp) for imp in imps), key=lambda item: (-item[0], item[1].command), ) ranked = [item for item in ranked if item[0] > 0] if not ranked: return None, [] best_score, best = ranked[0] runner_up = ranked[1][0] if len(ranked) > 1 else 0 if best_score >= 80 or (best_score >= 55 and best_score - runner_up >= 12): return best, ranked return None, ranked def block_reason(raw_name: str, ranked: list[tuple[int, Imp]]) -> str: if ranked: options = ", ".join(f"{imp.command} ({imp.description})" for _, imp in ranked[:5]) return ( f"I could not confidently map '-{raw_name}' to an imp. " f"Did you mean one of these: {options}? " "Please resubmit with the exact imp name, or ask whether to create a new imp with imp-create." ) return ( f"I could not find an imp matching '-{raw_name}'. " "Please be more specific, or ask whether to create a new imp with imp-create." ) def normalized_single_dash_prompt(imp: Imp, task: str) -> str: return f"-{imp.name} {task.strip()}".strip() def fork_inner_command(session_id: str, single_dash_prompt: str) -> str: return " ".join( [ "codex", "-c", shlex.quote('shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"'), "--dangerously-bypass-approvals-and-sandbox", "fork", shlex.quote(session_id), "--", shlex.quote(single_dash_prompt), ] ) def run_fork(session_id: str, single_dash_prompt: str) -> subprocess.CompletedProcess[str]: run_surface = str(Path.home() / ".local/bin/cmux-run-surface") return subprocess.run( [run_surface, fork_inner_command(session_id, single_dash_prompt)], check=False, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=4, ) def parse_cmux_receipt(stdout: str) -> dict[str, str]: receipt: dict[str, str] = {} for line in stdout.splitlines(): if not line.startswith("OK "): continue for key, value in CMUX_RECEIPT_RE.findall(line): receipt[key] = value return receipt def cmux_check_instructions(receipt: dict[str, str]) -> str: workspace = receipt.get("workspace", "<workspace>") surface = receipt.get("surface", "<surface>") pane = receipt.get("pane", "<pane>") return ( "Check this fork later with: " f"cmux read-screen --workspace {workspace} --surface {surface} --scrollback --lines 80 ; " f"cmux top --workspace {workspace} --processes --flat --format tsv ; " f"cmux focus-pane --workspace {workspace} --pane {pane}" ) def main() -> int: try: payload = read_payload() prompt = str(payload.get("prompt") or "") fork = False match = FORK_PROMPT_RE.match(prompt) if match: fork = True else: match = PROMPT_RE.match(prompt) if not match: emit_continue() return 0 raw_name = match.group(1) task = (match.group(2) or "").strip() if not task: emit_block(f"Please include a task after '-{raw_name}', for example '-{raw_name} do the thing'.") return 0 imp, ranked = find_imp(raw_name, read_imps()) if not imp: emit_block(block_reason(raw_name, ranked)) return 0 executable = imp.executable_path or imp.command cwd = str(payload.get("cwd") or "").strip() if fork: session_id = str(payload.get("session_id") or os.environ.get("CODEX_THREAD_ID") or "").strip() if not session_id: emit_block(f"Could not fork '-{imp.name}' because the hook payload did not include a Codex session id.") return 0 single_dash_prompt = normalized_single_dash_prompt(imp, task) result = run_fork(session_id, single_dash_prompt) receipt = parse_cmux_receipt(result.stdout) log( { "event": "fork_opened" if result.returncode == 0 else "fork_error", "imp": imp.command, "task": task, "cwd": cwd, "session_id": session_id, "single_dash_prompt": single_dash_prompt, "stdout": result.stdout, "stderr": result.stderr, "cmux": receipt, } ) if result.returncode != 0: emit_block(f"Could not open a cmux fork for '-{imp.name}'. stderr: {result.stderr.strip() or '(none)'}") return 0 emit_block( "\n".join( [ f"Opened a cmux fork for {imp.command} with: {single_dash_prompt}", f"cmux workspace: {receipt.get('workspace', 'unknown')}", f"cmux pane: {receipt.get('pane', 'unknown')}", f"cmux surface: {receipt.get('surface', 'unknown')}", f"cmux window: {receipt.get('window', 'unknown')}", cmux_check_instructions(receipt), ] ) ) return 0 emit_continue( ( f"The user's prompt began with '-{raw_name}', which is shorthand for invoking {imp.command}.\n\n" "The UserPromptSubmit hook has already discovered the imp from the command palette " "and resolved its executable path. Do not run which, where, find, rg, or other discovery " "commands to locate this imp.\n\n" f"Resolved imp command: {imp.command}\n" f"Resolved executable: {executable}\n" f"imp description: {imp.description}\n" f"Task text: {task}\n" f"Current cwd: {cwd}\n\n" "Let UserPromptSubmit complete and take this main-agent turn before invoking tools. " "Use the current conversation context naturally, then invoke the resolved executable when appropriate." ) ) return 0 except Exception as err: log({"event": "error", "error": repr(err)}) emit_continue() return 0 if __name__ == "__main__": raise SystemExit(main()) ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-imp-hook-files Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Instant web publishing for agents (here.now) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Instant web publishing for agents (here.now) **John uses:** [here.now](https://here.now/) — instant hosting *for agents*: publish any folder to `{slug}.here.now` (anonymous 24-hour sites with no sign-up; permanent with an API key), plus private cloud Drives agents share across sessions. All 11 workshop pages publish through its skill. **Honest note:** the agent-first combination (skill-driven publish + agent Drives + no-signup anonymous sites) is fairly unique. These cover the static-publish half: | Alternative | What it is | How it differs | License | |----|----|----|----| | [surge.sh](https://github.com/sintaxi/surge) | CLI for publishing static sites to the surge.sh CDN in one command | The classic one-command static publish; no agent-native skill or drives | none listed | | [Cloudflare Pages (wrangler)](https://github.com/cloudflare/workers-sdk) | wrangler CLI deploys static sites/functions to Cloudflare's edge (John's inspiration-board uses it) | Free, permanent, custom domains; needs an account and a project | Apache-2.0 | | [Vercel](https://github.com/vercel/vercel) | \`vercel deploy\` for static or full-stack sites with preview URLs | Preview-deploy workflow, generous free tier; heavier platform | Apache-2.0 | | [GitHub Pages](https://pages.github.com/) | Free static hosting from a repo branch | Requires a git repo (this workshop repo deliberately isn't one); slower publish loop | product | | [Netlify Drop](https://app.netlify.com/drop) | Drag-and-drop a folder, get a live URL | Closest no-friction analog for humans; no CLI-first anonymous mode like here.now's | product | ### Pick this if… - **surge** — you want the closest one-command feel from a terminal. - **Cloudflare Pages** — you want free, permanent, custom-domain hosting your agent can drive via wrangler. - **Vercel** — you want preview-per-change workflows or the site may grow a backend. - **Netlify Drop** — you need a URL in 10 seconds and don't mind doing it by hand. - **GitHub Pages** — your content already lives in a repo (note: this workshop repo intentionally isn't one). Reference ID: factory-tools-publishing Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#publishing) --- # Just-in-time state capture (markers) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Just-in-time state capture (markers) **John uses:** **agent-markers** (section 09; pattern page at [mindful-mango-accy.here.now](https://mindful-mango-accy.here.now/)) — a \<300-line, dependency-free recorder: console/fetch/error/click patched into a ring buffer, a Mark keystroke pins one sentence of human testimony to nearby events, and the export renders into a redacted agent-ready debug packet. The differentiator is *testimony as a first-class artifact* and privacy-by-redaction. | Alternative | What it is | How it differs | License | |----|----|----|----| | [rrweb](https://github.com/rrweb-io/rrweb) | Record and replay the web: DOM-level session recording library | Full DOM replay vs markers' redacted event trail; the building block most replay products use | MIT | | [OpenReplay](https://github.com/openreplay/openreplay) | Self-hostable session replay + product analytics for reproducing issues | Always-on infrastructure with a server; markers is a one-file, moment-of-surprise capture | NOASSERTION (ELv2/MIT mix) | | [Highlight](https://github.com/highlight/highlight) | OSS full-stack monitoring: session replay, errors, logs, traces | Monitoring-platform scale; check current repository activity | NOASSERTION (Apache-2.0 core) | | [Sentry Session Replay](https://github.com/getsentry/sentry) | Session replay wired to error tracking in Sentry | Error-first: replays attach to exceptions rather than to human testimony | NOASSERTION (FSL) | | [Jam](https://jam.dev/) | Chrome extension: one-click bug reports with replay, console logs, network requests, device details | Commercial, human-in-the-loop like markers — the closest 'press a button at the moment of surprise' product; output targets issue trackers, not agent prompts | commercial (free tier) | ### Pick this if… - **Jam** — the closest commercial "press a button at the moment of surprise" tool; output targets issue trackers rather than agent prompts. - **rrweb** — you're building your own marker system and want full DOM replay under it. - **OpenReplay / Highlight** — you want always-on capture infrastructure you control. - **Sentry** — your entry point is errors, not human testimony. - Or lift the workshop's recorder itself — it's ~300 dependency-free lines, designed for exactly this. Reference ID: factory-tools-state-capture-markers Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#state-capture-markers) --- # Keyboard customization (Karabiner-Elements) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Keyboard customization (Karabiner-Elements) **John uses:** [Karabiner-Elements](https://github.com/pqrs-org/Karabiner-Elements) (22.5k, Unlicense) with his config written as `karabiner.edn` compiled by [Goku](https://github.com/yqrashawn/GokuRakuJoudo) (1.4k, GPL-3.0, last push the example workflow). Section 06's trick: an app-scoped Esc-hold layer in Ghostty fires internal Ctrl+Alt chords that Herdr's `[[keys.command]]` bindings catch — Karabiner knows the keyboard, Herdr knows the focused pane. | Alternative | What it is | How it differs | License | |----|----|----|----| | [kanata](https://github.com/jtroo/kanata) | Cross-platform advanced keyboard remapper (layers, tap-hold) in Rust | Works on Linux/Windows/mac; kmonad-style config; no macOS app-scoping as rich as Karabiner's | LGPL-3.0 | | [kmonad](https://github.com/kmonad/kmonad) | Advanced keyboard manager (Haskell), layers and macros, cross-platform | The original layer-centric remapper; config is Lisp-flavored like Goku's edn | MIT | | [Hammerspoon](https://github.com/Hammerspoon/hammerspoon) | macOS desktop automation scripted in Lua (hotkeys, window management, app events) | Hotkeys plus arbitrary automation logic — can replace the 'chord fires a script' half of John's setup | MIT | | [skhd](https://github.com/asmvik/skhd) | Simple hotkey daemon for macOS | Just hotkey→command bindings in a flat config; minimal but no remapping layers; check current repository activity | MIT | | [Keyboard Maestro](https://www.keyboardmaestro.com/) | Commercial macOS macro platform (hotkeys, palettes, app-scoped macros) | GUI macro builder, one-time license; closed source | commercial | ### Pick this if… - **kanata** — you want Karabiner-style layers on Linux or Windows too. - **kmonad** — same, with the original Lisp-flavored config (kin to Goku's edn). - **Hammerspoon** — your chords should run *logic*, not just keystrokes — it can replace the chord→script half of John's setup. - **skhd** — you only need "hotkey runs command" with no remapping. - **Keyboard Maestro** — you want a GUI and a one-time license instead of config files. Reference ID: factory-tools-keyboard-customization Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#keyboard-customization) --- # Markdown agent flows (mdflow) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Markdown agent flows (mdflow) **John uses:** [mdflow](https://github.com/johnlindquist/mdflow) (`md`, 597, MIT) — executable markdown prompts run against Claude, Codex, Gemini, or Copilot. The differentiators, per section 05: prompt-build-time command inlining (`` !`git status` ``), frontmatter `_inputs`, **isolation from all ambient config/hooks/CLAUDE.md**, and eval-gated evolution (`md feedback` → `md eval` → `md evolve`, proposal-first). | Alternative | What it is | How it differs | License | |----|----|----|----| | [Claude Code slash commands & skills (built-in)](https://docs.claude.com/en/docs/claude-code) | Markdown files in .claude/commands and .claude/skills that become reusable parameterized agent behaviors | Ships with the agent — but tied to Claude Code and inherits ambient config; mdflow's isolation and multi-engine targeting are the delta | product docs | | [dotprompt](https://github.com/google/dotprompt) | Google's executable GenAI prompt template format (.prompt files: frontmatter + template) | A file-format/spec with runtimes, aimed at app code rather than launching coding agents | Apache-2.0 | | [BAML](https://github.com/BoundaryML/baml) | A programming language for agents/prompts with typed inputs/outputs and tests | Full typed DSL + toolchain where mdflow stays plain markdown; heavier but testable | Apache-2.0 | | [fabric patterns](https://github.com/danielmiessler/Fabric) | Markdown prompt 'patterns' executed via the fabric CLI against any model | Same 'prompt as a file you run' idea, without engine flags, context inlining, or eval-gated evolution | MIT | | [llm templates](https://github.com/simonw/llm) | YAML templates with params for the llm CLI | Lightweight parameterized prompts; no agent-loop execution or tool use | Apache-2.0 | ### Pick this if… - **Claude Code commands/skills** — you're all-in on one agent; you give up mdflow's isolation and multi-engine targeting. - **fabric** — you want "prompt as a runnable file" without engine flags or context inlining. - **llm templates** — lightweight parameterized prompts, no agent loop. - **BAML** — you want types and tests around prompts and will trade markdown simplicity for it. - **dotprompt** — you're standardizing prompt files inside application code, not agent launches. Reference ID: factory-tools-markdown-agent-flows Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#markdown-agent-flows) --- # Navigate the agent-safe shell file set These files support Section 2, "Loading ZSH Env Into Codex." They demonstrate a common Mac/zsh setup where Codex tool shells can see the same safe toolchain paths and selected helper functions without sourcing a full interactive `.zshrc`. ## Included Files ```text .zshenv .zprofile codex-env.zsh conf.d/00-path.zsh conf.d/40-ai.zsh conf.d/47-ai-fix.zsh functions/codex-launch-and-prompt-builder.zsh functions/shell-introspection.zsh functions/fusion-fix.zsh functions/orchestration-helpers.zsh functions/script-kit-process-helpers.zsh tests/startup-regression.zsh examples/local.zsh.example examples/codex-config-shell-environment-policy.toml ``` ## What Each File Teaches | File | Purpose | | --- | --- | | `.zshenv` | Sets XDG paths and `ZDOTDIR`; optionally loads selected DSL files when `CODEX_LOAD_ZSH_DSL` is present | | `.zprofile` | Login-shell bridge for `zsh -lc` | | `codex-env.zsh` | Agent-safe environment bootstrap for non-interactive shells | | `conf.d/00-path.zsh` | Deterministic PATH assembly | | `conf.d/40-ai.zsh` | Small loader for focused workshop helper snippets | | `conf.d/47-ai-fix.zsh` | Example workflow helper function | | `functions/codex-launch-and-prompt-builder.zsh` | `x`, `xi`, `xfl`, `xfc`, and Prompt Builder handoff helpers | | `functions/shell-introspection.zsh` | `funclist`, `funcwhere`, and `funced` | | `functions/fusion-fix.zsh` | Fusion-first `fix` helper | | `functions/orchestration-helpers.zsh` | `muxai` and reviewed lazy-loader patterns | | `functions/script-kit-process-helpers.zsh` | Process cleanup helper examples | | `tests/startup-regression.zsh` | Startup behavior checks | | `examples/local.zsh.example` | Public shape for machine-local overrides | | `examples/codex-config-shell-environment-policy.toml` | Public shape for Codex env policy | ## Safety Notes - Do not source a full `.zshrc` from agent shells. - Do not paste full `env` output into chats or handouts. - Keep prompt, completion, keybindings, fuzzy finders, and terminal UI in interactive startup only. - Prefer executable wrappers for helper entrypoints that must work outside zsh. - Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. ## Core Confirmation Commands ```bash zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true' ``` ```bash CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x 2>/dev/null || echo x:not-loaded; type x 2>/dev/null || true' ``` ```bash zsh -ic 'functions xi' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' ``` ```bash zsh -lc 'source ./zsh/conf.d/40-ai.zsh; whence -w x xi xfl xfc p-f p-c funcwhere muxai fix' ``` ## Operational boundaries - The file-purpose table describes the intended startup shape. The supplied `.zshenv` does not itself implement the optional DSL loader; review the practical setup prompt and actual local startup chain. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-file-map Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Oracle and PackX execution runbook You are a PIPELINE EXECUTOR. Your job is: packx bundle -> `mcp__oracle__consult` -> read output.log -> summarize Oracle's answer -> optionally commit Oracle-driven implementation changes when the user explicitly asks. Do not answer the user's question from your own code research. Use local inspection only to build an excellent bundle and prompt. The point of this skill is to spend Oracle's expensive intelligence on high-leverage design, implementation, and review output. ## Non-Negotiable Runtime Mode Oracle MUST always run through the browser engine using the remote browser configuration in `~/.oracle/config.json`. Treat this as a hard stop before every consult call, including follow-up calls. - Every `mcp__oracle__consult` call MUST set `engine: "browser"`. - Never use `engine: "api"` and never omit `engine`; the API engine's `OPENAI_API_KEY` failure is a caller bug, not a credential blocker. - Never switch to API mode because it seems faster, because browser mode timed out, because a smaller/follow-up prompt is being sent, or because a specific model label looks API-only. - If a planned Oracle call object contains `engine: "api"` or lacks `engine: "browser"`, discard that call object before invoking the tool and rebuild it in browser mode. - Model choice must be expressed through browser-compatible fields such as `browserModelLabel` and `browserThinkingTime`; do not use API credentials, API model IDs, or API-engine shortcuts. - Do not pass ad hoc remote host, token, profile, or browser-routing overrides. Let Oracle read `~/.oracle/config.json`, which owns the remote browser endpoint. - If the MCP surface is unavailable, the CLI Oracle recovery path MUST use `oracle --engine browser ...` and the same `~/.oracle` config. Do not add API flags or environment-key workarounds. - If any Oracle attempt reports `Missing OPENAI_API_KEY`, immediately retry in browser mode using the `~/.oracle` config instead of asking the user for a key. ## ChatGPT Intelligence Setting oracle-packx is a text/code reasoning workflow, not image generation. Use ChatGPT **Pro Extended** for every `oracle-packx` consult. Critical rules: - Every `mcp__oracle__consult` call in this skill must include `browserThinkingTime: "extended"`. - Keep `browserModelLabel: "Latest"` and `model: "gpt-5.5-pro"` unless the user explicitly asks for a different browser model. - Never use `browserThinkingTime: "instant"` for packx, planning, review, architecture, debugging, or code-analysis consults. - Instant is reserved for ChatGPT **Create image** / `imagine` runs only. - If the visible ChatGPT Intelligence pill says `Instant` before a packx run, change it back through Oracle by sending `browserThinkingTime: "extended"`; do not rely on the current UI state. Good call shape: ```text mcp__oracle__consult({ prompt: "[{slug}]\n\n{question}", files: ["~/.oracle/bundles/{slug}.txt"], engine: "browser", model: "gpt-5.5-pro", browserModelLabel: "Latest", browserThinkingTime: "extended", slug: "{slug}" }) ``` Bad call shape: ```text browserThinkingTime: "instant" # image generation only; wrong for oracle-packx ``` ## Operating Principle Oracle is expensive and powerful. Push it for maximum useful output. - Current validated browser-mode bundle target: up to ~900k tokens. The old ~49k guidance is obsolete. - Large bundles may exceed 1 MB on disk; rely on `~/.oracle/config.json` `maxFileSizeBytes` (10 MiB or higher) instead of splitting solely because of the old guard. - Ask for comprehensive solutions, not cautious fragments. - Ask Oracle to identify the highest-leverage work, sequencing, risks, invariants, tests, logs, and verification receipts. - Ask for critical code snippets, exact file/function targets, and implementation notes local agents can execute. - Ask Oracle to separate "must implement now" from "later polish", while still pushing for a meaningful implementation wave. - Expect local verification with `$agentic-testing`, logs, targeted tests, and `lat check` to teach us more after Oracle gives the plan. ## Output Artifact Boundary For planning, review, debugging, goal-writing, or implementation guidance, Oracle must return text in the chat/session response only. Do not ask Oracle to create, attach, export, or offer a downloadable file as the deliverable. The local agent owns every local artifact: - `~/.oracle/bundles/{slug}.txt` is created locally by `packx`. - `~/.oracle/sessions/{slug}/output.log` is Oracle session output captured locally. - Repo files, `.goals/*.md`, `.loop/oracle-loop/**`, prompts, plans, review notes, commits, and verification logs are written locally by the agent with local file-editing or shell tools. If Oracle creates a downloadable file anyway, do not treat the download as the artifact. Read the response content and write the local artifact yourself. If the only useful content exists inside an unreadable download, rerun Oracle with the no-download constraint emphasized. ## Forward Progress Contract Oracle is not a substitute for doing the work. Before any second or later Oracle call on the same topic, the local agent MUST build a Prior-State Ledger and pass the Forward Progress Gate. For a first Oracle call on a new topic, write `prior_oracle_session: none` and continue. For every follow-up Oracle call on the same topic, include this ledger in the Oracle prompt: ```text Prior-State Ledger: - prior_oracle_session: <slug/path, or none for first call> - last_oracle_recommendation: <one-paragraph summary> - implemented_since_prior_oracle: <files/functions/tests/receipts changed, or none> - verified_since_prior_oracle: <exact command/receipt/result, or none> - failed_proof_or_blocker: <exact failed command/output/log/screenshot path, or none> - narrowing_decision: <what scope was removed and what one slice remains> - files_functions_now_in_scope: <exact paths#symbols> - files_functions_out_of_scope: <explicit exclusions> - next_falsifiable_verification: <command, receipt, screenshot, or runtime proof> - forward_progress_index: <score and arithmetic> ``` Forward Progress Gate: before another Oracle call on the same topic, at least one of these MUST be true: - `implemented`: files, tests, goal artifacts, or receipts changed since the prior Oracle session. - `verified`: a new proof result exists, even if it is red. - `blocked`: an exact failed command/output/log/screenshot path exists. - `narrowed`: the new prompt removes scope and targets exactly one next shippable slice. If none are true, do not call Oracle again. Implement the previous recommendation, run proof, capture a blocker, or narrow the prompt first. Forward Progress Index: - +3 consumed a prior receipt, failed proof, or blocker - +3 selected exactly one new next slice - +2 named exact files/functions/tests/commands - +2 added falsifiable verification - +2 resulted in a checked-in or written goal/test/receipt afterward - -3 repeats the same topic without new evidence - -4 produces a broad roadmap instead of the next action Target score before a follow-up Oracle call: `>= 7`. A score below 7 is allowed only when `blocked` is true and the prompt includes the exact blocker receipt. Record the score in the local goal, loop state, or final summary. ## Long-Running Expectations Oracle browser runs are blocking research sessions. After Codex starts an Oracle call, all local planning, implementation, verification, and independent problem solving MUST pause until Oracle has fully completed and the local Oracle response has been read. There are no elapsed-time exceptions. - Never assume Oracle timed out or failed based on elapsed time alone. - Never proceed independently while Oracle is still processing, even if a wrapper returns after 120s or any other local wait limit. - Treat Oracle's response as the required next input. No fallback, workaround, self-directed implementation, or "I'll continue while it runs" path is allowed. - Reattach with `mcp__oracle__sessions({ id: "{slug}", detail: true })` or read `~/.oracle/sessions/{slug}/output.log` when it lands. - Health checks are allowed only to reattach, inspect session state, or confirm whether Oracle has produced the final local response. They are not permission to start work. - Keep waiting as long as Oracle requires while the session is still processing. There is no Codex-side timeout threshold that permits independent action. - Only treat the run as failed when Oracle reports an explicit error, the session exits non-zero, browser automation is blocked, or logs show a terminal failure. For packx flags and filter details, see [references/packx-quick-reference.md](/topics/codex-packx-command-reference/). ## Pipeline ### Step 1: Choose a slug Slug must be 3-5 words separated by hyphens. Oracle rejects slugs outside this range. ```bash mkdir -p ~/.oracle/bundles ``` ### Step 2: Preview with packx Run a dry-run to check file count and estimated size. ```bash packx --preview [your-filters] -x "**/CLAUDE.md" ``` Stop if 0 files match. Fix filters and preview again. If the target directory is not your cwd, wrap in a subshell: `(cd /path/to/project && packx ...)`. Never include `CLAUDE.md` in an Oracle PackX bundle. Always exclude it explicitly with `-x "**/CLAUDE.md"` and prefer `AGENTS.md` for repository guidance when both files exist. ### Step 3: Build the bundle Target a rich bundle close to 900k. If the bundle is under 250k for a broad planning/review task, attempt another pass with more relevant context, process docs, `lat.md` pages, tests, logs, or adjacent owners before consulting Oracle. Smaller focused bundles are still fine for narrow questions. ```bash packx --limit 900k [filters] -x "**/CLAUDE.md" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` Required flags: `--limit 900k`, `-x "**/CLAUDE.md"`, `-f markdown`, `--no-interactive`, `--stdout`. If preview showed more than 200 files, add `--strip-comments --minify` so the final bundle still carries broad context. ### Step 4: Validate the bundle ```bash test -s ~/.oracle/bundles/{slug}.txt && echo "OK" || echo "EMPTY" ``` Stop if empty. Go back to Step 2. ### Step 4.5: Add compact evidence when raw context is too large or unsafe `packx` remains the primary bundle. Do not skip the bundle. However, if raw session logs, hidden-path scans, screenshots, traces, or generated receipts are too large, unsafe, unavailable, or filtered out, add compact evidence. Write `~/.oracle/bundles/{slug}-evidence.md` when useful: ```markdown # Compact Evidence Supplement ## Prior-State Ledger <ledger, or prior_oracle: none> ## Receipts and failures - <exact command / receipt / failure summary> - <paths to screenshots, logs, traces, or receipts not included in packx> ## Raw context intentionally omitted - <large log/session path> -- omitted because <too large / hidden path / unsafe / unavailable> - <summary of the relevant lines or facts> ## Current narrowing - one_next_slice: <exact next slice> - out_of_scope: <what is intentionally excluded> - verification: <falsifiable proof> ``` Pass the supplement as an extra file when it is small and safe. If the supplement itself would be too large, include the compact evidence directly in the prompt. This is allowed only as evidence compaction, not as a replacement for the primary packx bundle. ### Step 5: Add screenshots or artifacts If the user provided image, PDF, log, trace, or screenshot paths, verify they exist and pass them in `files` with the bundle. Use `browserAttachments: "always"` for visual files. ### Step 6: Call Oracle You must execute this MCP tool call. ``` mcp__oracle__consult({ prompt: "[{slug}]\n\n{your detailed question here}", files: ["~/.oracle/bundles/{slug}.txt"], engine: "browser", model: "gpt-5.5-pro", browserModelLabel: "Latest", browserThinkingTime: "extended", slug: "{slug}" }) ``` Forbidden call shapes: ```text engine: "api" # never valid for oracle-packx model: "<api-model-id>" # never use this as a reason to switch engines engine omitted # never rely on Oracle defaults ``` If you notice one of these shapes in a drafted call, stop before tool invocation and rewrite the call with `engine: "browser"` plus browser fields. Do not try it once "to see if it works." With screenshots or PDFs: ``` mcp__oracle__consult({ prompt: "[{slug}]\n\n{your detailed question here}", files: ["~/.oracle/bundles/{slug}.txt", "/path/to/screenshot.png"], engine: "browser", model: "gpt-5.5-pro", browserModelLabel: "Latest", browserThinkingTime: "extended", browserAttachments: "always", slug: "{slug}" }) ``` ### Step 7: Read the full response The MCP return can be truncated. Read the authoritative answer from: ```text ~/.oracle/sessions/{slug}/output.log ``` If the file does not exist yet, check session status and keep waiting unless there is a real terminal failure. A long browser run is expected; keep waiting while the session is still alive and logs show no terminal failure. Do not summarize, plan, edit, verify, or answer from your own analysis until this full Oracle output is available and read. ### Step 8: Summarize for execution Lead with Oracle's highest-leverage recommendations, then convert the answer into implementation-ready work packages. Preserve Oracle's reasoning, file targets, critical snippets, logging asks, verification plan, and unresolved risks. If follow-up code changes are likely, mention the optional commit path: after implementation, the user can say `commit` and you should inspect the diff, map actual changes back to Oracle's advice, and create a traceable commit tied to `{slug}`. ### Step 9: Commit phase, only when requested Only run this step if the user explicitly asks after implementation. ```bash git diff --staged git diff ``` Prefer `git diff --staged` as the commit boundary. Stage only relevant Oracle-driven changes. Do not sweep unrelated edits into the commit. Commit message format: ```text <imperative subject line, <=72 chars> - <what changed> because Oracle recommended <fix/improvement> - <what changed> to address Oracle's finding about <risk/problem> Oracle-Session: {slug} ``` ## Prompt Contract Every Oracle prompt must be self-contained, ambitious, and progress-gated. Include: 1. Slug header: `[{slug}]`. 2. Project briefing: stack, framework, runtime, and repo rules. 3. Goal: the broad outcome the user wants, plus the first shippable slice when the goal is broad. 4. Prior-State Ledger: use `prior_oracle_session: none` for the first consult; for follow-ups include the last Oracle recommendation, what was implemented, verification result, failed proof or blocker, and what is being narrowed now. 5. Forward Progress Gate result: `implemented`, `verified`, `blocked`, or `narrowed`, including Forward Progress Index arithmetic. 6. Current evidence: attempts, logs, screenshots, failing receipts, blocker outputs, or known constraints. 7. Bundle map: why these files were included, what may be missing, and what compact evidence was summarized because raw logs/hidden paths were too large or unavailable. 8. Deliverable: ask for architecture, implementation plan, critical code snippets, file/function targets, tests, logs, verification strategy, and task breakdown for local agents. 9. Next action shape: Oracle must identify the one highest-leverage next shippable slice, separate immediate implementation from later roadmap, and name exact files/functions/tests when possible. 10. Repo-specific rules: for Script Kit GPUI, include `AGENTS.md`, owning skills, relevant `lat.md` pages, and `lat.md/verification.md` when implementation or review checks are part of the question. Never include `CLAUDE.md`; prefer `AGENTS.md` for repo instructions. 11. Output boundary: ask Oracle to return text in the response only, with no downloadable files, attachments, exports, or generated local artifacts. Include this constraint verbatim or equivalently in every planning/review prompt: ```text Return your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools. ``` Avoid prompts that ask only "what is the next change?" Also avoid repeated broad replanning. A follow-up prompt on the same topic must either consume new evidence or deliberately narrow to one next slice. ## Troubleshooting | Problem | Fix | |---------|-----| | Empty bundle | Check `--preview`; ensure `-i` uses `**/` prefix; expand relevant filters | | `-i "*.ts"` matches nothing | Use `-i "**/*.ts"` | | `-i` + external path = 0 files | Wrap in `(cd TARGET && packx ...)` | | Token budget exceeded | Use `--strip-comments --minify`, then sharpen filters around owners, tests, docs, and logs | | `mcp__oracle__consult` unavailable | Use the CLI Oracle recovery path: `oracle --engine browser --model gpt-5.5-pro --browser-thinking-time extended -p "..." --file ~/.oracle/bundles/{slug}.txt --slug "{slug}"` | | `Missing OPENAI_API_KEY` | The call accidentally used API mode or defaulted incorrectly. Retry with `engine: "browser"` and let Oracle read `~/.oracle/config.json`. | | 120s timeout / no final answer yet | Reattach/check `mcp__oracle__sessions` or `output.log`; do not proceed independently; keep waiting until Oracle completes or reports a terminal failure | | Truncated response | Read `~/.oracle/sessions/{slug}/output.log` | | Oracle created a downloadable file | Do not use it as the artifact; write the needed local file yourself from response text, or rerun with the no-download constraint emphasized | | Thinking time error | Use `browserThinkingTime: "extended"` | ## Completion Checklist - [ ] `packx` preview ran and produced matching files. - [ ] `~/.oracle/bundles/{slug}.txt` exists and is non-empty. - [ ] If under 250k for broad planning/review, you attempted to add useful context before consulting Oracle. - [ ] You called `mcp__oracle__consult` with `engine: "browser"` so Oracle uses `~/.oracle/config.json`. - [ ] You read `~/.oracle/sessions/{slug}/output.log`. - [ ] Your summary is based on Oracle's answer, not your own analysis. - [ ] No planning, implementation, verification, or final answer happened while Oracle was still processing. - [ ] Oracle was asked to return text only and not create downloadable files or project artifacts. - [ ] For follow-up Oracle calls, the prompt included a Prior-State Ledger. - [ ] For follow-up Oracle calls, the Forward Progress Gate passed as `implemented`, `verified`, `blocked`, or `narrowed`. - [ ] The Forward Progress Index arithmetic was recorded. - [ ] If raw logs/session output/hidden paths were too large or unavailable, compact evidence was summarized in the prompt or a `~/.oracle/bundles/{slug}-evidence.md` supplement. - [ ] Oracle was asked for one next shippable slice, not only a broad roadmap. - [ ] If committing, you inspected staged and unstaged diffs and mapped the commit to Oracle's recommendations. ## References - [Packx quick reference](/topics/codex-packx-command-reference/) - flags, filters, workflows, size management - [Packx deep technical reference](/topics/codex-packx-technical-reference/) - internals, caching, AST details ## Operational boundaries - The browser-only mode, extended-thinking setting, exclusion policy, and progress score are this runbook’s operating choices. They are not universal tool limitations. - Numeric token targets and model labels describe a configured workflow, not a guaranteed current capacity. An accepted attachment does not prove the model consumed every token. Verify the installed tools and provider limits. - Repo-specific verification helpers such as `$agentic-testing`, `lat check`, and `lat.md` require that project’s tooling; use the corresponding real verification surface for another repository. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-oracle-packx-runbook Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Oracle video analysis runbook You are a PIPELINE EXECUTOR. Your job is: prep media -> upload the video to Gemini via `mcp__oracle__consult` (browser engine) -> read the analysis -> verify it against evidence -> write local artifacts. Oracle/Gemini supplies the expensive multimodal analysis; you own every local file, receipt, and verification. This skill is the sibling of `oracle-packx`. Where `oracle-packx` bundles *code* and sends *text* to ChatGPT, `oracle-video` attaches a *video file* and sends it to *Gemini* (which can actually watch the footage). The full, validated process spec lives in [references/repeatable-video-followup-process.md](/topics/codex-video-evidence-process/); read it before a long run. ## Video Research Operating Rules This skill exists because video understanding must happen in Gemini. Do not route video analysis through Codex, ChatGPT, OpenAI API mode, or text-only summarization. The local agent may search YouTube, download media, compress files, write prompts, bundle analyses, and produce final Markdown; the video-watching step is always Gemini through Oracle's browser engine. When the user asks for "same pipeline" or a repeatable YouTube research batch, apply these repeatable research rules: - Filter candidate videos by actual YouTube metadata (`upload_date`), not title text, search ranking, or remembered publication dates. - If the user gives a cutoff such as "after a chosen cutoff", enforce `upload_date >= CUTOFF_YYYYMMDD`. Reject older/stale videos even if they rank highly. - Exclude topic collisions explicitly. For example, "Raycast" should exclude game-development raycasting; "Codex" should exclude unrelated OCR/library/tool names. - Exclude coupon, affiliate-code, auto-generated music/topic uploads, shorts-only junk, and videos whose content is not actually about the requested product/workflow. - Download with current `yt-dlp`, Chrome cookies, and YouTube challenge support when needed. A known-good command shape is `yt-dlp --cookies-from-browser chrome ...`. - Preserve source metadata in `queue.json` with `id`, `title`, `uploader`, `upload_date`, `duration`, and `url`. - Space Gemini video starts by about five minutes for larger batches only after the first attached-video probe passes and no unresolved run is pending, unless the user explicitly asks for a different cadence. - Make prompts topic-specific. Never reuse Codex-specific prompt language for another topic; parameterize the topic in batch runners and prompts. - After every Gemini run, save the analysis beside the chunk and verify the sentinel before moving to consolidation. - After each successful Gemini run, close the Gemini tab that Oracle opened. Do not leave the remote Mac mini with dozens of `gemini.google.com/app` tabs. ## Non-Negotiable Runtime Mode Video analysis MUST run through the browser engine using `~/.oracle/config.json`. - Every `mcp__oracle__consult` call MUST set `engine: "browser"`. - **Default model: `model: "gemini-3-pro"`** — Oracle drives Gemini's mode picker to **3.5 Flash + Extended thinking**, the right balance of speed and reasoning for routine video analysis. Any Gemini model with an attachment uses the DOM upload path (not pasted text), so the video is attached either way. - **Heavy opt-in: `model: "gemini-3-pro-deep-think"`** — selects **3.1 Pro + Deep Think** ("Max parallel reasoning"). Use this only when the user explicitly asks for the deepest analysis; it is markedly slower. Do NOT use it as the default. - Deliver the video with `browserAttachments: "always"`. The file path in `files` must be an absolute path on the invoking machine that Oracle can stream or hand to the browser host. For direct remote-host execution, use a path valid on that host; for remote Oracle service runs, preserve the client-side absolute path in receipts and let Oracle stream the attachment to the remote service. - Never use `engine: "api"` for video. The API path cannot upload the browser video. If a call reports `Missing OPENAI_API_KEY`, you accidentally used API mode — rebuild in browser mode. - Do not pass ad hoc remote host/token/profile overrides. Let Oracle read `~/.oracle/config.json`, which owns the remote browser endpoint (the host that has Chrome + Google sign-in). CLI Oracle recovery path: `oracle --engine browser --model gemini-3-pro ...` (add `--model gemini-3-pro-deep-think` only for the heavy Deep Think opt-in). - If the user mentions a remote Mac mini/TV/Gemini config, still do not hard-code a host/token in prompts or calls. Use `~/.oracle/config.json`; it is the source of truth for the remote browser and cookie-bearing Google session. - If an ownership/access dialog appears in Gemini ("confirm that you own/can access this content"), treat it as a browser/UI blocker. Let the user click it if automation cannot, then retry only the affected upload. Do not restart the whole batch. ## Model / Intelligence Boundary This skill analyzes video through Gemini in Oracle browser mode. Do not manage ChatGPT's Intelligence pill here. Critical rules: - Do not set `browserThinkingTime: "instant"` for Gemini video analysis. - Do not use ChatGPT `Pro Extended` / `Instant` labels as Gemini readiness proof. - Use `model: "gemini-3-pro"` by default, or `model: "gemini-3-pro-deep-think"` only for explicit heavy opt-in. - The Instant vs Pro Extended policy applies to ChatGPT only: Instant for ChatGPT Create image / `imagine`; Pro Extended for ChatGPT non-image consults. ### Gemini readiness: UI sign-in is required, but cookie errors are not proof Gemini video upload requires the browser profile that Oracle drives to have a live signed-in Gemini UI. However, a Gemini text-only probe is not authoritative for video readiness. Text-only Gemini may use Oracle's HTTP/cookie path and fail because a Google cookie such as `__Secure-1PSIDTS` is missing, while the visible Gemini UI is signed in and the attached-video DOM upload path still works. Use this readiness order: 1. Confirm the run is routed to Gemini browser mode, not ChatGPT or API mode. 2. Confirm the remote Gemini UI is visibly signed in. 3. Run one tiny attached-video probe with `engine: "browser"`, `model: "gemini-3-pro"`, `browserAttachments: "always"`, and an explicit sentinel. 4. Treat the attached-video probe, not a text-only probe, as the video readiness proof. 5. If the probe hits a UI blocker, classify it with the failure diagnosis tree below before retrying or starting a batch. Gemini may show a conditional **video upload consent** modal after a video is attached and send is attempted. The DOM may include `video-upload-consent-dialog` with text like "A reminder about creating videos" and actions `Cancel` / `Agree`. This is not a Google sign-out, quota limit, or upload failure. Automation may click only the visible action whose normalized label is exactly `Agree`. Never click `Cancel`, never click the first dialog button generically, and never treat this modal as permission to click arbitrary dialog actions. ### Attached-video smoke test Before a large batch, prove the actual video path with a tiny local MP4/MOV probe. Required proof: - request uses `engine: "browser"`; - request uses `model: "gemini-3-pro"` unless the user explicitly requested Deep Think; - request uses `browserAttachments: "always"`; - stored request/session metadata shows Gemini provider routing; - run log shows Gemini navigation and attachment upload completion; - final response contains the expected sentinel; - completed Gemini tab is closed after output is saved. A text-only Gemini success is not enough. A text-only Gemini failure is also not enough to declare the video path broken. The video path is proven only by an attached-video run or by inspected Gemini tab evidence showing the submitted video prompt and sentinel response. ## Two Paths Pick the path from the source length and structure (full decision rules in the reference doc). ### Short path — quick clips, no pre-processing (DEFAULT for short screen captures) Use when the clip is short enough to upload and analyze in one pass (quick screen recording, a couple-minute walkthrough, a bug repro, a design review clip). 1. Copy/symlink the clip as the single chunk; keep the original immutable + record a `sha256` receipt. 2. Run ONE Gemini consult with the clip attached (see Step: Analyze). 3. Verify the output (URLs/tools/claims supported by what's actually in the video). 4. Write a compact deliverable: bug report, requirements note, design brief, or summary. Do NOT segment, chunk, or build a manifest for short clips. Skip straight to analysis. ### Long path — workshop recordings, multi-section talks Use for long recordings (roughly 45+ min, real breaks, many sections). Segment with ffmpeg, drop verified dead-space (never discard chat — carry it forward), analyze each chunk, run an omissions pass, extract keyframes, reconcile against evidence, then assemble a teammate/follow-up packet. Follow the reference doc step by step. ## Pipeline ### Step 1: Choose a slug 3-5 hyphenated words (Oracle rejects anything outside that range), e.g. `workshop-chunk-02-analysis` or `bug-repro-video-followup`. Every prompt starts with `[{slug}]` on its own first line, then a blank line, then the prompt. ### Step 2: Prep the media + receipts ```bash RUN_DIR=runs/$(date +%Y-%m-%d)-{slug} # one folder per video/video-set mkdir -p "$RUN_DIR"/{inputs,receipts,chunks} cp "/abs/path/to/source.mp4" "$RUN_DIR/inputs/source.mp4" shasum -a 256 "$RUN_DIR/inputs/source.mp4" > "$RUN_DIR/inputs/source.sha256" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source.mp4" > "$RUN_DIR/receipts/ffprobe.source.json" ``` For the long path, segment/chunk per the reference doc and write `chunks/video-manifest.json`. For the short path, the single clip is `chunks/01/chunk.mp4`. ### Step 3: Write the analysis prompt Save the prompt to `chunks/NN/gemini-prompt.md` so the run is reproducible. Use the "Gemini Chunk Analysis" template from the reference doc. Always include the hard rules: preserve original timestamps, separate transcript/chat/visual/inference evidence, do not invent tools/commands/URLs/files/speakers/labels, return both Markdown and fenced JSON, end with an `END_OF_VIDEO_ANALYSIS ...` sentinel. Write the exact expected sentinel beside the prompt, for example `chunks/NN/expected-sentinel.txt`, and verify against that file rather than guessing whether the run used slug-only or `run_key chunk_id` form. ### Step 4: Analyze — upload the video to Gemini You MUST execute this MCP tool call (one per chunk): ``` mcp__oracle__consult({ prompt: "[{slug}]\n\n{contents of chunks/NN/gemini-prompt.md}", files: ["/abs/path/RUN_DIR/chunks/NN/chunk.mp4"], engine: "browser", model: "gemini-3-pro", // default → Gemini 3.5 Flash + Extended thinking browserAttachments: "always", slug: "{slug}" }) ``` For the heavy Deep Think opt-in (only when explicitly requested), swap in `model: "gemini-3-pro-deep-think"` (→ 3.1 Pro + Deep Think). Forbidden shapes: `engine: "api"`, omitted `engine`, no `browserAttachments`. If you draft one of these, rebuild before invoking. For batch CLI Oracle recovery, use the same browser mode explicitly: ```bash oracle \ --engine browser \ --model gemini-3-pro \ --browser-attachments always \ --browser-keep-browser \ --prompt "$(cat chunks/NN/gemini-prompt.md)" \ --file "/abs/path/RUN_DIR/chunks/NN/chunk.mp4" \ --slug "{topic}-batch-NN" \ --write-output "chunks/NN/gemini-analysis.md" \ --verbose \ --wait \ --force ``` Use `--browser-keep-browser` only so the run can be inspected and recovered while it is active. Once the run has saved output, close the Gemini tab (see Step 5.5). Persist the result yourself (the MCP return + output.log are truncated — the caller owns persistence): ```text chunks/NN/gemini-run.log # browser automation metadata / timing chunks/NN/gemini-result.json # full response payload chunks/NN/gemini-analysis.md # rendered analysis ``` ### Step 5: Wait correctly Gemini video runs are blocking. After a run starts, all local analysis, artifact writing based on Gemini's answer, follow-up planning, and independent summarization MUST pause until Oracle/Gemini has fully completed and the local response has been read. - Never assume Oracle/Gemini timed out or failed based on elapsed time alone. - Never proceed independently while Oracle/Gemini is still processing, even if a wrapper returns after 120s or any other local wait limit. - Reattach with `mcp__oracle__sessions({ id: "{slug}", detail: true })` or read `~/.oracle/sessions/{slug}/output.log`; these checks are only for recovering the final response, not for starting work while the run continues. - Keep waiting as long as Oracle/Gemini requires while the session is still processing. There is no Codex-side timeout threshold that permits independent action. - Only call it failed on an explicit terminal error, a sign-in/quota/upload guard, or a non-zero exit. Healthy wrapper completion looks like the run log ending with `Gemini browser response received (N chars)` and `Completed in Nms`. Recovered completion is also valid when the wrapper reports a send/ready error but tab inspection shows a submitted user turn and Gemini response containing the exact expected sentinel. In that case, save the visible response, record the recovery in `gemini-run.log`, and do not rerun that chunk. For newer Gemini DOM runs, successful submission may also be evident from the remote Gemini tab even when an older Oracle wrapper reports a send/ready error. If a run says `Gemini send was not accepted` or `Gemini composer was not ready to send` after an attached-video attempt, inspect the Gemini tab before retrying: the submitted user turn and Gemini response may already exist. A valid sentinel in the visible Gemini response beats the wrapper error; persist the response and fix/adjust the wrapper before batching more chunks. ### Step 5.5: Clean up the Gemini tab Every successful Gemini video run should close the tab it opened on the remote browser. This prevents the remote Mac mini/TV browser from accumulating dozens of Gemini tabs. Cleanup happens only after extraction, not merely after the browser appears done. Preferred cleanup order: 1. Record the Oracle session slug and, if available, its Chrome debug port/target in the run log. 2. Extract and persist every needed artifact from the Gemini response: `gemini-result.json`, `gemini-analysis.md`, any machine JSON or `gemini-analysis.extracted.json`, and the recovery note if the response came from tab inspection rather than wrapper success. 3. Verify `gemini-analysis.md` is non-empty and contains the exact `expected-sentinel.txt` value. 4. Close only the Gemini tab for that completed/extracted run. 5. Leave the browser itself running if Oracle needs to reuse the signed-in profile. 6. Do not close tabs for still-running uploads, still-generating responses, unresolved wrapper errors, or tabs whose visible response has not yet been extracted. If you write a batch script, make tab cleanup an explicit post-extraction step. The script should not close the tab immediately after Oracle returns; it should first save the full result, extract machine-readable content, verify the sentinel, then close the exact tab target for that run. If extraction fails, leave the tab open and record the target/port so the run can be recovered. When the run used `--browser-keep-browser`, use Oracle/browser tooling to close matching completed Gemini tabs rather than leaving them open. If you are in the Oracle repo, a working inspection/cleanup shape is: ```bash pnpm tsx scripts/browser-tools.ts eval --port <port> ' (() => { const tabs = [...document.querySelectorAll("a")]; return { href: location.href, title: document.title, text: document.body.innerText.slice(0, 500) }; })() ' ``` If you need to operate on the configured remote Mac mini, run the same command through SSH using the repo-local Node path from that machine. Prefer closing the exact tab target via Chrome DevTools Protocol when possible; avoid killing Chrome or closing all Gemini tabs blindly. If exact-target close is not available, list tabs first, identify completed `gemini.google.com/app` tabs by title/conversation state, and close only those. ### Step 6 (long path): Omissions pass + reconcile + verify Re-attach the same chunk with the "Omissions Pass" prompt, then reconcile locally into `final-reconciled.md`/`.json`, and run the verification reports (coverage, hallucination, timestamp, visual-claim). Keep every receipt next to the claim it supports. Details in the reference doc. ### Step 7: Assemble + summarize Long path: produce the `final/` packet (teammate guide, chapter index, resources, QA index, exercises, keyframe manifest, instructor checklist). Short path: produce the one compact deliverable. Summarize for the user, leading with the highest-value findings, and link the artifact paths. ## Evidence Preservation (core rule) - Keep original media immutable; record a `sha256` receipt. - Preserve ORIGINAL recording timestamps when a source timeline exists. - Save every prompt, result, and run log next to the chunk. - Never claim a URL/tool/command/visual unless it is supported by transcript, chat, carry-forward chat, a local path, or keyframe review. - Never discard chat from a removed/dead span — carry it forward. ## Gemini Video Failure Diagnosis Tree Stop new batch starts before using this tree. Diagnose the current run first. 1. **Was a video attached?** - No: this may be the text-only HTTP/cookie path. Do not use it as the only video readiness result. Run a tiny attached-video probe. - Yes: continue. 2. **Was the run routed to Gemini browser mode?** - If logs or metadata show ChatGPT navigation/upload, API mode, or missing `browserConfig.provider: "gemini"`, stop. This is a routing bug. Do not treat the result as valid video analysis. - If Gemini browser routing is confirmed, continue. 3. **Is there an explicit terminal guard?** - `sign-in`: stop and have the remote browser signed into Gemini. - `quota` or `rate-limit`: stop and wait/change account per user direction. - `upload-warning`: stop and fix file size/type/count or chunk the media. - No terminal guard: continue. 4. **Did a text-only probe fail on missing Google cookies?** - If the visible Gemini UI is signed in, do not diagnose sign-out from that alone. Text-only probes can fail on HTTP/cookie requirements that attached-video DOM runs do not need. - Run or inspect an attached-video probe. 5. **Did attached-video send fail with `Gemini send was not accepted`?** - Inspect the Gemini tab before retrying. - If `video-upload-consent-dialog` is visible, click only exact `Agree`, then wait for the same prompt to submit. - If the prompt and attachment still remain in the composer and no submitted user turn exists, rerun only that chunk after fixing the blocker. - If a submitted user turn or response exists, do not rerun until checking for the sentinel. 6. **Did the wrapper report `prompt-empty`?** - Inspect the tab. `prompt-empty` can mean Gemini accepted the prompt and moved it out of the composer. - If the visible response contains the expected sentinel, persist it as success. - If no submitted user turn and no response exist, treat it as a real send failure and rerun only that chunk. 7. **Are there stale Gemini tabs?** - Do not close active uploads or generating responses. - Generic empty Gemini tabs from failed diagnostics may be closed after inspection. - Tabs with real conversation state must be checked for a saved response/sentinel before closing. - Close only the exact completed tab after output is saved. 8. **Is the result valid?** - Valid completion is either a successful wrapper log with response received, or inspected Gemini tab evidence containing the expected sentinel and saved output. - Anything else is unresolved; do not consolidate, summarize, or batch further. ## Troubleshooting | Problem | Fix | |---------|-----| | Run log stops at `Sending prompt...`, no response; tab left with video attached | Stop batch starts. Inspect the Gemini tab before rerunning. Check for a visible video consent modal, explicit sign-in/quota/rate-limit/upload warning, submitted user turn, or sentinel response. Rerun only the affected chunk after the state is classified. | | `Gemini send was not accepted after 3 attempts` | Inspect the remote Gemini tab. If `video-upload-consent-dialog` is visible, click only the visible action whose normalized label is exactly `Agree`, then wait for the same prompt to submit. If the prompt remains in the composer with no submitted user turn, rerun only that chunk after fixing the blocker. If a response with the expected sentinel already exists, persist it as success. | | `Gemini composer was not ready to send` with `reason=prompt-empty` after an attached-video run | Inspect the tab before retrying. `prompt-empty` may be a wrapper false negative after Gemini accepted the prompt. If the prompt appears in a submitted user turn/page and the Gemini response contains the expected sentinel, save it as completed analysis and record recovery. If no user turn/response exists, rerun only that chunk after fixing send/modal handling. | | Text-only Gemini probe reports sign-in/cookie failure, but the visible Gemini app is signed in | Do not assume the video path is broken. Text-only probes can use Oracle's HTTP/cookie path and fail on missing `__Secure-1PSIDTS`; video attachments use the Gemini DOM upload path. Verify with a tiny real video attachment probe before deciding whether user sign-in is required. | | Text-only Gemini probe fails on missing `__Secure-1PSIDTS` | Do not diagnose video sign-out from this alone. Confirm visible Gemini UI state and run a tiny attached-video probe. | | Attached-video probe succeeds after text-only failure | Treat video DOM upload path as ready. Record both receipts so future agents do not revert to the false sign-out diagnosis. | | Wrapper failed but tab contains sentinel | Persist the visible Gemini response, save a recovery note in the run log, close the completed tab, and do not rerun that chunk. | | Log shows ChatGPT navigation or ChatGPT upload for a video | Stop. Treat this as a routing bug, not a valid analysis. Verify the stored request/metadata shows `browserConfig.provider: "gemini"` and rerun only after the provider guard tests pass. | | Many leftover `gemini.google.com/app` tabs with generic "Google Gemini" title | Those are usually runs that never produced a query/response (often diagnostic/sign-in attempts), or completed runs that were left open because `--browser-keep-browser` was used. Close completed/empty Gemini tabs after saving output. Tabs with a real auto-generated title + conversation id may have completed; verify output before closing. | | `Missing OPENAI_API_KEY` | The call used API mode. Retry with `engine: "browser"` + `model: "gemini-3-pro"` (default) or `gemini-3-pro-deep-think` (heavy). | | `sign-in` / `quota` / `rate-limit` / `upload-warning` guard | Stop. Sign the remote browser into Google (or wait out the limit), then resume. | | `video-upload-consent-dialog` / "A reminder about creating videos" appears | This is a video consent blocker, not sign-out. Click only exact `Agree`; never click `Cancel`, never click the first button generically, and never click `Confirm` for this dialog unless the DOM label is actually `Agree`. Continue the same run after acceptance. | | Ownership/access confirmation appears | Treat as a separate UI blocker. If automation cannot safely identify the explicit ownership/access confirmation action, ask the user to click it once, then continue or retry only the affected upload. Do not restart the whole batch. | | 120s timeout / no final answer yet | Reattach via `mcp__oracle__sessions` or `output.log`; do not proceed independently; keep waiting until Oracle/Gemini completes or reports a terminal failure. | | Large video upload | Oracle streams large attachments to the remote service before the run (`[remote] streaming large attachment before run`). Keep the file under the configured `maxFileSizeBytes` / remote limit, or chunk it. | | Truncated MCP return | Read `chunks/NN/gemini-result.json` that you persisted, not the MCP tail. | ## Completion Checklist - [ ] Original media preserved + `sha256` receipt written. - [ ] Slug is 3-5 hyphenated words; prompt starts with `[{slug}]`. - [ ] Each Gemini call used `engine: "browser"`, `model: "gemini-3-pro"` (default 3.5 Flash + Extended; `gemini-3-pro-deep-think` only if explicitly requested), `browserAttachments: "always"`, absolute `files` path. - [ ] Remote browser confirmed signed into Gemini before batch runs. - [ ] A real attached-video probe has completed through Gemini before a large batch; do not rely only on a text-only Gemini probe. - [ ] Text-only Gemini probe results were not used as the sole video readiness proof. - [ ] First real attached-video probe result was saved before any batch fan-out. - [ ] Any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit, or upload-warning state stopped new batch starts until classified. - [ ] Prompt, result JSON, and run log persisted per chunk. - [ ] Each run either reached `Gemini browser response received`, or a wrapper-error recovery was documented with submitted user turn + visible Gemini response + expected sentinel. - [ ] If `video-upload-consent-dialog` appeared, only the `Agree` action was clicked and the same submitted prompt was allowed to complete. - [ ] Stored session metadata/request shows `browserConfig.provider: "gemini"` for every video run. - [ ] Expected sentinel was written next to the prompt and checked exactly. - [ ] If the sentinel format used `run_key chunk_id`, verification did not look for slug-only form. - [ ] Run log contains `[gemini-web] Navigating to gemini.google.com...` and `Attachment upload complete in Gemini: <filename>`. - [ ] Run log does not show ChatGPT navigation/upload for the video attachment. - [ ] No local analysis, artifact synthesis, or final answer happened while Oracle/Gemini was still processing. - [ ] Completed Gemini tabs were closed after output was saved and verified; the remote browser was not left with accumulated `gemini.google.com/app` tabs. - [ ] Scripted tab cleanup ran only after full extraction completed: `gemini-result.json`, `gemini-analysis.md`, extracted JSON if expected, and exact sentinel verification. - [ ] Outputs verified: no invented URLs/tools/commands; visual claims confirmed; original timestamps preserved. - [ ] Long path: omissions pass + reconciliation + verification reports done; `final/` packet assembled. - [ ] Short path: single compact deliverable written. - [ ] User summary leads with highest-value findings and links artifact paths. ## References - [Repeatable video follow-up process](/topics/codex-video-evidence-process/) — full step-by-step spec, ffmpeg segmentation, prompt templates, verification, and final-packet layout. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-oracle-video-runbook Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Packx command and filtering reference Full context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats. ## Packx Quick Reference Packx (v4.x) is a native AI context bundler. It discovers files, filters by content/type/git-status, strips noise, counts tokens, and outputs in LLM-friendly formats. **Since v4.7.0, bare `packx` with no output flags enters interactive mode** — always use `--no-interactive` for scripting pipelines. ## How File Discovery Works 1. **Candidate discovery** — scans directories using glob patterns (ripgrep fast-path when available, Node.js glob fallback) 2. **Ignore filtering** — applies `.gitignore` (traversed upward from cwd) + `.packignore` + 22 built-in ignore patterns 3. **Include/exclude pattern matching** — `-i` and `-x` filters via minimatch 4. **Content filtering** — `-s` search strings and `-S` exclusion strings (up to 50 files in parallel) 5. **Size/binary filtering** — skips files >10MB silently; detects binary via first 512 bytes (>10% non-printable = binary) 6. **Token counting** — `js-tiktoken` (OpenAI tokenizer), fallback: `text.length / 4` ## Auto-Excluded (always skipped) ``` node_modules/ .git/ dist/ build/ .next/ coverage/ .cache/ tmp/ temp/ *.log .DS_Store Thumbs.db package-lock.json yarn.lock pnpm-lock.yaml bun.lockb bun.lock Gemfile.lock Cargo.lock poetry.lock Pipfile.lock composer.lock ``` ## Default File Types (when no `-i` flag) **Code:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php **Web:** vue, svelte, astro, css, scss, less **Config:** json, yaml, yml, toml, xml **Docs:** md, mdx, txt **Scripts:** sh, bash, zsh, fish **Data:** sql, graphql, gql ## Critical: `-i` Glob Requires `**/` Prefix ```bash # CORRECT — always use **/ prefix for extension globs packx --limit 900k -i "**/*.ts" --preview packx --limit 900k -i "src/**/*.tsx" --preview # WRONG — bare *.ext matches NOTHING packx --limit 900k -i "*.ts" --preview # Empty result! ``` Directory-style includes (`-i "src/"`) work without `**/`. The `-x` exclude flag is more lenient — `"*.test.*"` works for excludes. ## Critical: `-i` Fails with External Directories **The `-i` glob is matched against paths relative to cwd.** When you pass a positional path outside cwd (e.g., `~/dev/other-project`), relative paths start with `../` which `**` cannot traverse — **silently producing 0 results**. ```bash # BROKEN — -i + external path = 0 files every time packx --limit 900k -i "**/*.ts" --no-interactive --preview ~/dev/other-project # FIX 1 (Best): cd into the target via subshell (cd ~/dev/other-project && packx --limit 900k -i "**/*.ts" --no-interactive --preview) # FIX 2: Positional path alone (all default file types), then exclude unwanted packx --limit 900k -x "*.json" -x "*.md" -x "*.sh" --no-interactive --preview ~/dev/other-project # FIX 3: Use -s (content search) — works fine with external paths packx --limit 900k -s "import" --no-interactive --preview ~/dev/other-project ``` **Rule**: If the target directory ≠ cwd, wrap in `(cd TARGET && packx ...)`. ## Token Budget: k vs K Oracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context. | Notation | Multiplier | Example | Result | |----------|-----------|---------|--------| | lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens | | UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens | | No suffix | Raw number | `50000` | 50,000 tokens | ## Positional Arguments ```bash packx src/ # Directory → scan root packx README.md src/auth.ts # Files → explicit includes packx "**/*.test.ts" # Glob → include pattern ``` Positional args are classified automatically: directories become scan roots, existing files are explicit includes, patterns with glob characters (`*`, `?`, `[]`, `{}`) become glob filters. When combined with `-i`, explicit files must match BOTH conditions. ## Complete Flag Reference ### Search & Filter | Flag | Short | Purpose | Notes | |------|-------|---------|-------| | `--strings <text>` | `-s` | Include files containing text | Repeatable; case-insensitive by default | | `--exclude-strings` | `-S` | Exclude files containing text | Opposite of -s | | `--include <glob>` | `-i` | Include by glob | **Must use `**/` prefix for extensions** | | `--exclude <glob>` | `-x` | Exclude by filename/glob | More lenient than -i | | `--regex` | `-R` | Treat -s patterns as regex | Full regex syntax | | `--case-sensitive` | `-C` | Case-sensitive search | Default is case-insensitive | | `--staged` | | Git staged files only | `git diff --cached --name-only --diff-filter=ACMR` | | `--diff` | | Files changed from main | Uses `git merge-base` to find divergence point | | `--dirty` | | Modified + untracked files | Union of modified and `git ls-files --others` | | `--no-packignore` | | Ignore .packignore file | | `--staged`, `--diff`, and `--dirty` are **mutually exclusive**. ### Processing | Flag | Short | Purpose | Notes | |------|-------|---------|-------| | `--strip-comments` | | Remove comments | AST-aware via tree-sitter; regex fallback by language family | | `--no-comments` | | Alias for --strip-comments | | | `--minify` | | Remove empty lines + trim whitespace | Stacks remaining lines together | | `--lines <N>` | `-l` | Extract N context lines around matches | Smart expansion to complete code blocks; overlapping windows auto-merge | | `--follow-imports` | | Include imported dependencies | ES6/CJS/dynamic; relative only; max depth 10; tries .ts/.tsx/.js/.jsx extensions | | `--related` | `-r` | Include related files | Matches by core filename in same dir (tests, stories, styles) | | `--skeleton` | | Interface-only extraction | AST-based: strips function bodies to `{ /* ... */ }` | | `--instruction <file>` | | Prepend custom instructions from file | Inserted at top of bundle | | `--prompt <text>` | `-p` | Append text to end of output | | ### Output | Flag | Short | Purpose | Notes | |------|-------|---------|-------| | `--copy` | `-c` | Copy to clipboard | pbcopy/clip/xclip; only chunk 1 if splitting | | `--stdout` | | Write to stdout | Summaries go to stderr; **disables interactive mode** | | `--output <file>` | `-o` | Write to file | | | `--format <fmt>` | `-f` | `xml` (default), `markdown`, `plain`, `jsonl` | Use `markdown` for Oracle/ChatGPT | | `--preview` | | Show matching files (up to 50) without packing | Dry run for testing filters | | `--max-tokens <N>` | `-M` | Split into chunks | Creates file-1.xml, file-2.xml; files never split mid-file | | `--limit <size>` | | Token budget | `900k`=900,000; `32K`=32,768; visual progress in interactive mode | | `--no-interactive` | | Disable interactive mode | **Required for scripting/piping** | ## Filter Decision Tree ``` Is the task about a specific feature/module? ├─ YES → Do you know the entrypoint file? │ ├─ YES → --follow-imports <entrypoint> │ └─ NO → -s "keyword" -i "relevant/path/**/*.ts" └─ NO → Is it a code review / PR? ├─ YES → --diff (or --staged / --dirty) └─ NO → Is it architecture/overview? ├─ YES → --skeleton -i "src/**/*.ts" └─ NO → Is it debugging? ├─ YES → -s "error message" -r -l 20 └─ NO → -i "**/*.ts" (broad scan) Always add: --limit 900k --preview (check first) → --no-interactive --stdout -f markdown Token-tight? Add: --strip-comments --minify Still too big? Add: -x "**/*.test.*" -x "**/stories/**" then -s "keyword" then -l N ``` ## Bundle Size Management - ALWAYS run `packx --preview [filters]` FIRST to estimate size - If preview shows >900k: add `--strip-comments --minify` only if you need to fit under the target; otherwise keep rich context when the user explicitly wants a limit stress test - If still >900k: narrow `-i` patterns or add `-x` exclusions - If still >900k: add `-s` keyword to filter to only relevant files - If context around matches is sufficient: use `-l 20` instead of full files Progression example: ```bash # 1) Preview baseline packx --preview -i "src/**/*.ts" -i "apps/web/**/*.tsx" # 2) If too many files, strip/minify packx --limit 900k -i "src/**/*.ts" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 3) If still >900k, narrow includes/excludes packx --limit 900k -i "src/auth/**/*.ts" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 4) If still >900k, add keyword focus packx --limit 900k -i "src/auth/**/*.ts" -s "token session oauth" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 5) If still >900k, use context lines instead of full files packx --limit 900k -s "token session oauth" -l 15 -x "**/*.test.*" --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 6) For architecture overview, use skeleton mode packx --limit 900k -i "src/**/*.ts" --skeleton -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ## Common Workflows ### Review code by keyword ```bash packx --limit 900k -s "auth" -i "**/*.ts" -x "*.test.*" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Analyze from entrypoint (best signal-to-noise) ```bash packx --limit 900k --follow-imports src/server.ts -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Debug from error ```bash packx --limit 900k -s "TypeError: Cannot read properties" -r -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Context-line focused review (token-efficient) ```bash packx --limit 900k -s "catch" -s "throw" -l 15 --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Architecture overview with skeleton mode ```bash packx --limit 900k -i "src/**/*.ts" --skeleton -x "**/*.test.*" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### PR/diff review ```bash packx --limit 900k --diff -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Large Monorepo ```bash packx --limit 900k -i "apps/web/src/**/*.tsx" -i "apps/api/src/**/*.ts" -i "packages/auth/src/**/*.ts" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ## Fallback — Manual Bundle Augmentation When `packx` cannot reach every needed file in one pass: ```bash packx --limit 900k -i "src/**/*.ts" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt cat docs/auth-decision-record.md >> ~/.oracle/bundles/{slug}.txt wc -c ~/.oracle/bundles/{slug}.txt ``` ## References - [Packx deep technical reference](https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md) — full internals, caching, import resolution, AST details Reference ID: factory-packx-quick-reference Topic: Tools Sources: - [Published Packx reference](https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-quick-reference.md) --- # PackX commands, filters, and bundle recipes Packx (v4.x) is a native AI context bundler. It discovers files, filters by content/type/git-status, strips noise, counts tokens, and outputs in LLM-friendly formats. **Since v4.7.0, bare `packx` with no output flags enters interactive mode** — always use `--no-interactive` for scripting pipelines. ## How File Discovery Works 1. **Candidate discovery** — scans directories using glob patterns (ripgrep fast-path when available, Node.js glob fallback) 2. **Ignore filtering** — applies `.gitignore` (traversed upward from cwd) + `.packignore` + 22 built-in ignore patterns 3. **Include/exclude pattern matching** — `-i` and `-x` filters via minimatch 4. **Content filtering** — `-s` search strings and `-S` exclusion strings (up to 50 files in parallel) 5. **Size/binary filtering** — skips files >10MB silently; detects binary via first 512 bytes (>10% non-printable = binary) 6. **Token counting** — `js-tiktoken` (OpenAI tokenizer), fallback: `text.length / 4` ## Auto-Excluded (always skipped) ``` node_modules/ .git/ dist/ build/ .next/ coverage/ .cache/ tmp/ temp/ *.log .DS_Store Thumbs.db package-lock.json yarn.lock pnpm-lock.yaml bun.lockb bun.lock Gemfile.lock Cargo.lock poetry.lock Pipfile.lock composer.lock ``` ## Default File Types (when no `-i` flag) **Code:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php **Web:** vue, svelte, astro, css, scss, less **Config:** json, yaml, yml, toml, xml **Docs:** md, mdx, txt **Scripts:** sh, bash, zsh, fish **Data:** sql, graphql, gql ## Critical: `-i` Glob Requires `**/` Prefix ```bash # CORRECT — always use **/ prefix for extension globs packx --limit 900k -i "**/*.ts" --preview packx --limit 900k -i "src/**/*.tsx" --preview # WRONG — bare *.ext matches NOTHING packx --limit 900k -i "*.ts" --preview # Empty result! ``` Directory-style includes (`-i "src/"`) work without `**/`. The `-x` exclude flag is more lenient — `"*.test.*"` works for excludes. ## Critical: `-i` Fails with External Directories **The `-i` glob is matched against paths relative to cwd.** When you pass a positional path outside cwd (e.g., `~/dev/other-project`), relative paths start with `../` which `**` cannot traverse — **silently producing 0 results**. ```bash # BROKEN — -i + external path = 0 files every time packx --limit 900k -i "**/*.ts" --no-interactive --preview ~/dev/other-project # FIX 1 (Best): cd into the target via subshell (cd ~/dev/other-project && packx --limit 900k -i "**/*.ts" --no-interactive --preview) # FIX 2: Positional path alone (all default file types), then exclude unwanted packx --limit 900k -x "*.json" -x "*.md" -x "*.sh" --no-interactive --preview ~/dev/other-project # FIX 3: Use -s (content search) — works fine with external paths packx --limit 900k -s "import" --no-interactive --preview ~/dev/other-project ``` **Rule**: If the target directory ≠ cwd, wrap in `(cd TARGET && packx ...)`. ## Token Budget: k vs K Oracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context. | Notation | Multiplier | Example | Result | |----------|-----------|---------|--------| | lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens | | UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens | | No suffix | Raw number | `50000` | 50,000 tokens | ## Positional Arguments ```bash packx src/ # Directory → scan root packx README.md src/auth.ts # Files → explicit includes packx "**/*.test.ts" # Glob → include pattern ``` Positional args are classified automatically: directories become scan roots, existing files are explicit includes, patterns with glob characters (`*`, `?`, `[]`, `{}`) become glob filters. When combined with `-i`, explicit files must match BOTH conditions. ## Complete Flag Reference ### Search & Filter | Flag | Short | Purpose | Notes | |------|-------|---------|-------| | `--strings <text>` | `-s` | Include files containing text | Repeatable; case-insensitive by default | | `--exclude-strings` | `-S` | Exclude files containing text | Opposite of -s | | `--include <glob>` | `-i` | Include by glob | **Must use `**/` prefix for extensions** | | `--exclude <glob>` | `-x` | Exclude by filename/glob | More lenient than -i | | `--regex` | `-R` | Treat -s patterns as regex | Full regex syntax | | `--case-sensitive` | `-C` | Case-sensitive search | Default is case-insensitive | | `--staged` | | Git staged files only | `git diff --cached --name-only --diff-filter=ACMR` | | `--diff` | | Files changed from main | Uses `git merge-base` to find divergence point | | `--dirty` | | Modified + untracked files | Union of modified and `git ls-files --others` | | `--no-packignore` | | Ignore .packignore file | | `--staged`, `--diff`, and `--dirty` are **mutually exclusive**. ### Processing | Flag | Short | Purpose | Notes | |------|-------|---------|-------| | `--strip-comments` | | Remove comments | AST-aware via tree-sitter; regex fallback by language family | | `--no-comments` | | Alias for --strip-comments | | | `--minify` | | Remove empty lines + trim whitespace | Stacks remaining lines together | | `--lines <N>` | `-l` | Extract N context lines around matches | Smart expansion to complete code blocks; overlapping windows auto-merge | | `--follow-imports` | | Include imported dependencies | ES6/CJS/dynamic; relative only; max depth 10; tries .ts/.tsx/.js/.jsx extensions | | `--related` | `-r` | Include related files | Matches by core filename in same dir (tests, stories, styles) | | `--skeleton` | | Interface-only extraction | AST-based: strips function bodies to `{ /* ... */ }` | | `--instruction <file>` | | Prepend custom instructions from file | Inserted at top of bundle | | `--prompt <text>` | `-p` | Append text to end of output | | ### Output | Flag | Short | Purpose | Notes | |------|-------|---------|-------| | `--copy` | `-c` | Copy to clipboard | pbcopy/clip/xclip; only chunk 1 if splitting | | `--stdout` | | Write to stdout | Summaries go to stderr; **disables interactive mode** | | `--output <file>` | `-o` | Write to file | | | `--format <fmt>` | `-f` | `xml` (default), `markdown`, `plain`, `jsonl` | Use `markdown` for Oracle/ChatGPT | | `--preview` | | Show matching files (up to 50) without packing | Dry run for testing filters | | `--max-tokens <N>` | `-M` | Split into chunks | Creates file-1.xml, file-2.xml; files never split mid-file | | `--limit <size>` | | Token budget | `900k`=900,000; `32K`=32,768; visual progress in interactive mode | | `--no-interactive` | | Disable interactive mode | **Required for scripting/piping** | ## Filter Decision Tree ``` Is the task about a specific feature/module? ├─ YES → Do you know the entrypoint file? │ ├─ YES → --follow-imports <entrypoint> │ └─ NO → -s "keyword" -i "relevant/path/**/*.ts" └─ NO → Is it a code review / PR? ├─ YES → --diff (or --staged / --dirty) └─ NO → Is it architecture/overview? ├─ YES → --skeleton -i "src/**/*.ts" └─ NO → Is it debugging? ├─ YES → -s "error message" -r -l 20 └─ NO → -i "**/*.ts" (broad scan) Always add: --limit 900k --preview (check first) → --no-interactive --stdout -f markdown Token-tight? Add: --strip-comments --minify Still too big? Add: -x "**/*.test.*" -x "**/stories/**" then -s "keyword" then -l N ``` ## Bundle Size Management - ALWAYS run `packx --preview [filters]` FIRST to estimate size - If preview shows >900k: add `--strip-comments --minify` only if you need to fit under the target; otherwise keep rich context when the user explicitly wants a limit stress test - If still >900k: narrow `-i` patterns or add `-x` exclusions - If still >900k: add `-s` keyword to filter to only relevant files - If context around matches is sufficient: use `-l 20` instead of full files Progression example: ```bash # 1) Preview baseline packx --preview -i "src/**/*.ts" -i "apps/web/**/*.tsx" # 2) If too many files, strip/minify packx --limit 900k -i "src/**/*.ts" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 3) If still >900k, narrow includes/excludes packx --limit 900k -i "src/auth/**/*.ts" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 4) If still >900k, add keyword focus packx --limit 900k -i "src/auth/**/*.ts" -s "token session oauth" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 5) If still >900k, use context lines instead of full files packx --limit 900k -s "token session oauth" -l 15 -x "**/*.test.*" --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt # 6) For architecture overview, use skeleton mode packx --limit 900k -i "src/**/*.ts" --skeleton -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ## Common Workflows ### Review code by keyword ```bash packx --limit 900k -s "auth" -i "**/*.ts" -x "*.test.*" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Analyze from entrypoint (best signal-to-noise) ```bash packx --limit 900k --follow-imports src/server.ts -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Debug from error ```bash packx --limit 900k -s "TypeError: Cannot read properties" -r -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Context-line focused review (token-efficient) ```bash packx --limit 900k -s "catch" -s "throw" -l 15 --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Architecture overview with skeleton mode ```bash packx --limit 900k -i "src/**/*.ts" --skeleton -x "**/*.test.*" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### PR/diff review ```bash packx --limit 900k --diff -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ### Large Monorepo ```bash packx --limit 900k -i "apps/web/src/**/*.tsx" -i "apps/api/src/**/*.ts" -i "packages/auth/src/**/*.ts" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt ``` ## Fallback — Manual Bundle Augmentation When `packx` cannot reach every needed file in one pass: ```bash packx --limit 900k -i "src/**/*.ts" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt cat docs/auth-decision-record.md >> ~/.oracle/bundles/{slug}.txt wc -c ~/.oracle/bundles/{slug}.txt ``` ## References - [Packx deep technical reference](/topics/codex-packx-technical-reference/) — full internals, caching, import resolution, AST details ## Operational boundaries - PackX flags, glob semantics, tokenizer behavior, and downstream token targets are version-sensitive. Preview and inspect the final bundle; auto-exclusions and secret detectors do not replace privacy review. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-packx-command-reference Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Packx discovery, processing, and output semantics Full context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats. ## Packx Deep Reference Complete technical reference for packx v4.x — the AI context bundler. ## File Discovery Pipeline ### Processing Order 1. **Candidate discovery** — by extension + glob patterns + git mode 2. **Ignore filtering** — `.gitignore` (traversed upward) + `.packignore` + default ignores 3. **Content filtering** — search strings (`-s`) and exclusion strings (`-S`) 4. **Size filtering** — skip files > 10MB silently 5. **Binary detection** — first 512 bytes checked for null bytes; >10% non-printable = binary → skip 6. **Pattern matching** — minimatch for `-i`/`-x` patterns 7. **Token counting** — js-tiktoken (GPT tokenizer), fallback: `text.length / 4` ### Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS) ``` **/node_modules/** **/.git/** **/dist/** **/build/** **/.next/** **/coverage/** **/.cache/** **/tmp/** **/temp/** **/*.log **/.DS_Store **/Thumbs.db **/package-lock.json **/yarn.lock **/pnpm-lock.yaml **/bun.lockb **/bun.lock **/Gemfile.lock **/Cargo.lock **/poetry.lock **/Pipfile.lock **/composer.lock ``` ### Default Extensions (no `-i` flag) **Languages:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php **Web Frameworks:** vue, svelte, astro **Styles:** css, scss, less **Config:** json, yaml, yml, toml, xml **Documentation:** md, mdx, txt **Scripts:** sh, bash, zsh, fish **Data:** sql, graphql, gql ## The `-i` Include Glob: Critical Behavior **The `-i` flag requires `**/` prefix for extension matching:** ```bash # CORRECT — always use **/ prefix for extensions packx --limit 900k -i "**/*.ts" --preview packx --limit 900k -i "src/**/*.tsx" --preview # WRONG — bare *.ext does NOT match packx --limit 900k -i "*.ts" --preview # Matches nothing! ``` Directory-style includes (`-i "src/"`) work without `**/`. The `-x` exclude flag is more lenient — `"*.test.*"` works for excludes. ## Token Budget (`--limit`) Oracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context. ### k vs K Notation | Notation | Multiplier | Example | Exact Result | |----------|-----------|---------|--------------| | lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens | | UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens | | No suffix | Raw number | `50000` | 50,000 tokens | | Decimal | Works with both | `1.5k` | 1,500 tokens | ### Token Counting - Uses `js-tiktoken` (OpenAI's tokenizer) for accurate GPT token counts - Fallback: `Math.round(text.length / 4)` if tiktoken fails - Counts are cached per-file in `.packx_cache/cache.json` ### Interactive Mode + Limit When `--limit` is used with interactive mode (`-I`), a visual progress bar shows real-time token consumption as files are selected/deselected. ## Import Following (`--follow-imports`) ### Supported Import Styles 1. ES6: `import ... from "..."` and `export ... from "..."` 2. CommonJS: `require("...")` 3. Dynamic: `import("...")` ### Resolution - **Only follows relative imports** (`./` or `../`), never `node_modules` - Max depth: 10 levels - Circular dependencies handled via visited-path Set **Resolution extensions tried (in order):** `""`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.mjs`, `.cts`, `.cjs`, `.json` **Extension mappings:** - `.js` → tries `.ts`, `.tsx`, `.js`, `.jsx` - `.mjs` → tries `.mts`, `.mjs` - `.cjs` → tries `.cts`, `.cjs` - `.jsx` → tries `.tsx`, `.jsx` **Index files for directory imports:** `index.ts`, `index.tsx`, `index.js`, `index.jsx`, `index.mts`, `index.mjs` ### Parse Strategy 1. Tree-sitter AST parsing first (for .ts, .js, etc.) 2. Regex fallback if AST unavailable: ``` import\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["'] export\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["'] require\s*\(\s*["']([^"']+)["']\s*\) import\s*\(\s*["']([^"']+)["']\s*\) ``` ## Related Files (`-r` / `--related`) Extracts base name (before first dot after name), then finds all files in the same directory with the same core name: - `Button.tsx` → finds `Button.test.tsx`, `Button.stories.tsx`, `Button.module.css`, etc. - Recursively expands matched files with their related files ## Comment Stripping (`--strip-comments`) ### AST-Based (primary — tree-sitter) - Language-specific tree-sitter grammar - Collects all comment nodes from AST - Removes entire lines if only whitespace surrounds the comment - Otherwise removes inline comments preserving code ### Regex Fallback (by language family) | Language Family | Languages | Patterns | |----------------|-----------|----------| | C-style | js, jsx, ts, tsx, java, c, cpp, go, rust, swift, php, css, scss, less | `/* ... */` and `// ...` | | Hash-style | py, rb, sh, bash, zsh, yaml, yml, toml | `# ...` | | HTML-style | html, xml, md, mdx, vue, svelte, astro | `<!-- ... -->` | | Lua-style | lua, sql | `-- ...` | All regex fallbacks preserve quoted strings. ## Context Lines (`-l` / `--lines`) ### Smart Context Mode 1. Extracts N lines around each match 2. **Tries to expand to complete code blocks** using tree-sitter AST 3. Falls back to indent-based block detection 4. Max expansion: `contextLines × 2` ### Overlap Merging Windows sorted by start line, then merged if `window.startLine <= current.endLine + 1`. Matches from overlapping regions are combined. ### Indent-Based Block Detection (fallback) - Scans upward for lower indentation level (block openers: `{`, `:`, function/class/if keywords) - Scans downward for closing braces or lower indentation ## Git Integration ### `--staged` ``` git diff --cached --name-only --diff-filter=ACMR ``` (Added, Copied, Modified, Renamed) ### `--dirty` ``` git diff --name-only --diff-filter=ACMR # modified git ls-files --others --exclude-standard # untracked ``` Returns deduplicated union. ### `--diff` ``` git merge-base <branch> HEAD # find common ancestor git diff --name-only --diff-filter=ACMR <base> # diff from there ``` Falls back to branch name directly if merge-base fails. **These three flags are mutually exclusive.** ## Output Formats ### XML (default) ```xml <file_summary> <purpose>...</purpose> </file_summary> <directory_structure>file paths</directory_structure> <files> <file path="src/auth.ts" matches="3" windows="2"> ...content or context windows... </file> </files> ``` ### Markdown (`-f markdown`) ```markdown # Packx Output This file contains X filtered files... ## Files ### src/auth.ts (3 matches) ```ts ...content... ```​ ``` ### JSONL (`-f jsonl`) One JSON object per line: ```json {"path":"src/auth.ts","content":"...","tokens":150,"matches":[{"line":10,"column":5,"match":"..."}]} ``` ### Plain (`-f plain`) Like markdown but simpler header, no fenced blocks. ## Caching (`.packx_cache/`) **Cache file:** `.packx_cache/cache.json` (version 2) **Entry structure:** ```json { "mtime": 1702000000000, "size": 4096, "contentHash": "sha256hex...", "isBinary": false, "tokens": 342 } ``` **Validation strategy:** 1. mtime AND size match → cache hit (fast path) 2. Size differs → cache miss 3. mtime differs but size same → compute SHA-256 → compare hash 4. Hash matches → update mtime, keep entry 5. Hash differs → cache miss, recompute **Bypass:** `--no-cache` **Prune:** Stale entries for deleted files cleaned on next run ## Bundles (`-b` / `--bundle`) - Stored in `.pack/bundles/` directory - Extensions: `.bundle`, `.pack`, `.txt` - Format: gitignore-style patterns (one per line, `#` for comments) - In interactive mode: loads bundles as pre-selected file sets - With `-b name`: loads non-interactively and outputs directly ## Interactive Mode (`-I`) **Default since v4.7.0** — running `packx` with no output flags enters interactive mode. ### Features - Tree-based file browser with token counts - Live preview pane with syntax highlighting - Token budget progress bar (`--limit`) - Git status decorators: `[M]` Modified, `[A]` Added, `[?]` Untracked - `.packignore` files shown but start unselected - Fuzzy search filtering - Visual dependency graph ### Key Bindings | Key | Action | |-----|--------| | `j/k` or ↑/↓ | Navigate | | `Space` | Toggle selection | | `Shift+Space` / `v` | Range selection (anchor) | | `Tab` | Toggle preview focus | | `PgUp/PgDn` | Scroll preview | | `g/G` | Jump to top/bottom | | `h/l` | Collapse/expand folder | | `o` | Open in editor | | `d` | Resolve dependencies | | `c` | Toggle comment stripping | | `+/-` | Adjust context lines | | `x` | Banish to `.packignore` | | `?` | Full-screen help overlay | | `Enter` | Confirm selection | ### After Selection - Option to save glob pattern to `.packignore` - Option to save selection as named bundle - Choose output: clipboard, file, stdout, or skip ## Watch Mode (`-w`) - Uses `chokidar` with 150ms debounce - File stabilization: 100ms threshold, 50ms poll interval - Watches: `change`, `add`, `unlink` events - **Requires** `--output` or `--copy` - **Cannot combine with `-I`** (interactive) - Ctrl+C for graceful shutdown ## `--instruction` and `--prompt` | Flag | Position | Input | |------|----------|-------| | `--instruction <file>` | Prepends to TOP of output | File path | | `--prompt <text>` / `-p` | Appends to END of output | Inline text | ## `--preview` Mode - Dry run: shows matching files without packing content - Displays up to 50 files (rest counted as "... and X more") - Shows file count total - Useful for testing filter combinations before committing ## `--explain` Mode - Full dry run with detailed logging - Shows: resolved config options, file discovery process, pattern matching, what would be included - No output generated ## `--skeleton` Mode (v4.15.0+) - AST-based: strips function bodies to `{ /* ... */ }` - Keeps interfaces, type definitions, function signatures - Great for architecture review at minimal token cost ## Secret Redaction (v4.15.0+) Automatically detects and redacts 22 pattern types: AWS keys, GitHub tokens, JWTs, database connection strings, API keys, private keys, etc. Replaces matches with `<REDACTED:TYPE>`. ## `--minify` Behavior ```javascript content.split('\n') .map(line => line.trim()) .filter(line => line.length > 0) .join('\n') ``` Removes empty lines, trims whitespace per line. ## Token Splitting (`--max-tokens` / `-M`) - Reserves ~50 tokens per chunk for headers/footers - **Files are never split mid-file** - A single file exceeding the budget is skipped entirely (marked "oversized") - Creates: `output-1.xml`, `output-2.xml`, etc. - Only chunk 1 copied to clipboard; rest go to files ## Concurrency - Files analyzed in parallel using `p-limit` - `CONCURRENCY_LIMIT = 50` - Progress emitted every 50 files or 10% of total ## .packignore - Gitignore syntax (processed by `ignore` npm library) - Auto-loaded from project root - `--no-packignore` to disable - In interactive mode: matching files shown but unselected - `x` hotkey in interactive mode banishes files to `.packignore` ## Positional Path Arguments ```bash packx src/ # Directory → scan root packx README.md # File → explicit include packx "**/*.test.ts" # Glob pattern → include pattern ``` **Classification:** - Contains `*`, `?`, `[`, `]`, `{`, `}`, `!` → treated as glob pattern - Exists as directory → treated as scan root - Exists as file → treated as explicit file include **Interaction with filters:** - Explicit files + `-i` patterns: must match BOTH - Positional roots: used as starting directories for scanning - Positional globs: added to include patterns ## Gotchas & Edge Cases | Issue | Detail | |-------|--------| | `-i "*.ts"` matches nothing | Must use `"**/*.ts"` with `**/` prefix for extensions | | Interactive is default | Since v4.7.0, bare `packx` enters interactive mode. Use `--no-interactive` for scripting | | `--stdout` disables interactive | Can't combine `--stdout` with `-I` | | `--watch` + `-I` incompatible | Watch requires output target, can't be interactive | | Files >10MB silently skipped | No warning — use `--explain` to debug missing files | | Single file > `--max-tokens` | Entire file skipped, not split | | Clipboard: only chunk 1 | When splitting, remaining chunks go to files | | Binary files silently skipped | >10% non-printable chars in first 512 bytes | Reference ID: factory-packx-deep-reference Topic: Tools Sources: - [Published Packx reference](https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md) --- # PackX discovery, processing, and token mechanics Complete technical reference for packx v4.x — the AI context bundler. ## File Discovery Pipeline ### Processing Order 1. **Candidate discovery** — by extension + glob patterns + git mode 2. **Ignore filtering** — `.gitignore` (traversed upward) + `.packignore` + default ignores 3. **Content filtering** — search strings (`-s`) and exclusion strings (`-S`) 4. **Size filtering** — skip files > 10MB silently 5. **Binary detection** — first 512 bytes checked for null bytes; >10% non-printable = binary → skip 6. **Pattern matching** — minimatch for `-i`/`-x` patterns 7. **Token counting** — js-tiktoken (GPT tokenizer), fallback: `text.length / 4` ### Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS) ``` **/node_modules/** **/.git/** **/dist/** **/build/** **/.next/** **/coverage/** **/.cache/** **/tmp/** **/temp/** **/*.log **/.DS_Store **/Thumbs.db **/package-lock.json **/yarn.lock **/pnpm-lock.yaml **/bun.lockb **/bun.lock **/Gemfile.lock **/Cargo.lock **/poetry.lock **/Pipfile.lock **/composer.lock ``` ### Default Extensions (no `-i` flag) **Languages:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php **Web Frameworks:** vue, svelte, astro **Styles:** css, scss, less **Config:** json, yaml, yml, toml, xml **Documentation:** md, mdx, txt **Scripts:** sh, bash, zsh, fish **Data:** sql, graphql, gql ## The `-i` Include Glob: Critical Behavior **The `-i` flag requires `**/` prefix for extension matching:** ```bash # CORRECT — always use **/ prefix for extensions packx --limit 900k -i "**/*.ts" --preview packx --limit 900k -i "src/**/*.tsx" --preview # WRONG — bare *.ext does NOT match packx --limit 900k -i "*.ts" --preview # Matches nothing! ``` Directory-style includes (`-i "src/"`) work without `**/`. The `-x` exclude flag is more lenient — `"*.test.*"` works for excludes. ## Token Budget (`--limit`) Oracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context. ### k vs K Notation | Notation | Multiplier | Example | Exact Result | |----------|-----------|---------|--------------| | lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens | | UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens | | No suffix | Raw number | `50000` | 50,000 tokens | | Decimal | Works with both | `1.5k` | 1,500 tokens | ### Token Counting - Uses `js-tiktoken` (OpenAI's tokenizer) for accurate GPT token counts - Fallback: `Math.round(text.length / 4)` if tiktoken fails - Counts are cached per-file in `.packx_cache/cache.json` ### Interactive Mode + Limit When `--limit` is used with interactive mode (`-I`), a visual progress bar shows real-time token consumption as files are selected/deselected. ## Import Following (`--follow-imports`) ### Supported Import Styles 1. ES6: `import ... from "..."` and `export ... from "..."` 2. CommonJS: `require("...")` 3. Dynamic: `import("...")` ### Resolution - **Only follows relative imports** (`./` or `../`), never `node_modules` - Max depth: 10 levels - Circular dependencies handled via visited-path Set **Resolution extensions tried (in order):** `""`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.mjs`, `.cts`, `.cjs`, `.json` **Extension mappings:** - `.js` → tries `.ts`, `.tsx`, `.js`, `.jsx` - `.mjs` → tries `.mts`, `.mjs` - `.cjs` → tries `.cts`, `.cjs` - `.jsx` → tries `.tsx`, `.jsx` **Index files for directory imports:** `index.ts`, `index.tsx`, `index.js`, `index.jsx`, `index.mts`, `index.mjs` ### Parse Strategy 1. Tree-sitter AST parsing first (for .ts, .js, etc.) 2. Regex fallback if AST unavailable: ``` import\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["'] export\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["'] require\s*\(\s*["']([^"']+)["']\s*\) import\s*\(\s*["']([^"']+)["']\s*\) ``` ## Related Files (`-r` / `--related`) Extracts base name (before first dot after name), then finds all files in the same directory with the same core name: - `Button.tsx` → finds `Button.test.tsx`, `Button.stories.tsx`, `Button.module.css`, etc. - Recursively expands matched files with their related files ## Comment Stripping (`--strip-comments`) ### AST-Based (primary — tree-sitter) - Language-specific tree-sitter grammar - Collects all comment nodes from AST - Removes entire lines if only whitespace surrounds the comment - Otherwise removes inline comments preserving code ### Regex Fallback (by language family) | Language Family | Languages | Patterns | |----------------|-----------|----------| | C-style | js, jsx, ts, tsx, java, c, cpp, go, rust, swift, php, css, scss, less | `/* ... */` and `// ...` | | Hash-style | py, rb, sh, bash, zsh, yaml, yml, toml | `# ...` | | HTML-style | html, xml, md, mdx, vue, svelte, astro | `<!-- ... -->` | | Lua-style | lua, sql | `-- ...` | All regex fallbacks preserve quoted strings. ## Context Lines (`-l` / `--lines`) ### Smart Context Mode 1. Extracts N lines around each match 2. **Tries to expand to complete code blocks** using tree-sitter AST 3. Falls back to indent-based block detection 4. Max expansion: `contextLines × 2` ### Overlap Merging Windows sorted by start line, then merged if `window.startLine <= current.endLine + 1`. Matches from overlapping regions are combined. ### Indent-Based Block Detection (fallback) - Scans upward for lower indentation level (block openers: `{`, `:`, function/class/if keywords) - Scans downward for closing braces or lower indentation ## Git Integration ### `--staged` ``` git diff --cached --name-only --diff-filter=ACMR ``` (Added, Copied, Modified, Renamed) ### `--dirty` ``` git diff --name-only --diff-filter=ACMR # modified git ls-files --others --exclude-standard # untracked ``` Returns deduplicated union. ### `--diff` ``` git merge-base <branch> HEAD # find common ancestor git diff --name-only --diff-filter=ACMR <base> # diff from there ``` Falls back to branch name directly if merge-base fails. **These three flags are mutually exclusive.** ## Output Formats ### XML (default) ```xml <file_summary> <purpose>...</purpose> </file_summary> <directory_structure>file paths</directory_structure> <files> <file path="src/auth.ts" matches="3" windows="2"> ...content or context windows... </file> </files> ``` ### Markdown (`-f markdown`) ```markdown # Packx Output This file contains X filtered files... ## Files ### src/auth.ts (3 matches) ```ts ...content... ```​ ``` ### JSONL (`-f jsonl`) One JSON object per line: ```json {"path":"src/auth.ts","content":"...","tokens":150,"matches":[{"line":10,"column":5,"match":"..."}]} ``` ### Plain (`-f plain`) Like markdown but simpler header, no fenced blocks. ## Caching (`.packx_cache/`) **Cache file:** `.packx_cache/cache.json` (version 2) **Entry structure:** ```json { "mtime": 1702000000000, "size": 4096, "contentHash": "sha256hex...", "isBinary": false, "tokens": 342 } ``` **Validation strategy:** 1. mtime AND size match → cache hit (fast path) 2. Size differs → cache miss 3. mtime differs but size same → compute SHA-256 → compare hash 4. Hash matches → update mtime, keep entry 5. Hash differs → cache miss, recompute **Bypass:** `--no-cache` **Prune:** Stale entries for deleted files cleaned on next run ## Bundles (`-b` / `--bundle`) - Stored in `.pack/bundles/` directory - Extensions: `.bundle`, `.pack`, `.txt` - Format: gitignore-style patterns (one per line, `#` for comments) - In interactive mode: loads bundles as pre-selected file sets - With `-b name`: loads non-interactively and outputs directly ## Interactive Mode (`-I`) **Default since v4.7.0** — running `packx` with no output flags enters interactive mode. ### Features - Tree-based file browser with token counts - Live preview pane with syntax highlighting - Token budget progress bar (`--limit`) - Git status decorators: `[M]` Modified, `[A]` Added, `[?]` Untracked - `.packignore` files shown but start unselected - Fuzzy search filtering - Visual dependency graph ### Key Bindings | Key | Action | |-----|--------| | `j/k` or ↑/↓ | Navigate | | `Space` | Toggle selection | | `Shift+Space` / `v` | Range selection (anchor) | | `Tab` | Toggle preview focus | | `PgUp/PgDn` | Scroll preview | | `g/G` | Jump to top/bottom | | `h/l` | Collapse/expand folder | | `o` | Open in editor | | `d` | Resolve dependencies | | `c` | Toggle comment stripping | | `+/-` | Adjust context lines | | `x` | Banish to `.packignore` | | `?` | Full-screen help overlay | | `Enter` | Confirm selection | ### After Selection - Option to save glob pattern to `.packignore` - Option to save selection as named bundle - Choose output: clipboard, file, stdout, or skip ## Watch Mode (`-w`) - Uses `chokidar` with 150ms debounce - File stabilization: 100ms threshold, 50ms poll interval - Watches: `change`, `add`, `unlink` events - **Requires** `--output` or `--copy` - **Cannot combine with `-I`** (interactive) - Ctrl+C for graceful shutdown ## `--instruction` and `--prompt` | Flag | Position | Input | |------|----------|-------| | `--instruction <file>` | Prepends to TOP of output | File path | | `--prompt <text>` / `-p` | Appends to END of output | Inline text | ## `--preview` Mode - Dry run: shows matching files without packing content - Displays up to 50 files (rest counted as "... and X more") - Shows file count total - Useful for testing filter combinations before committing ## `--explain` Mode - Full dry run with detailed logging - Shows: resolved config options, file discovery process, pattern matching, what would be included - No output generated ## `--skeleton` Mode (v4.15.0+) - AST-based: strips function bodies to `{ /* ... */ }` - Keeps interfaces, type definitions, function signatures - Great for architecture review at minimal token cost ## Secret Redaction (v4.15.0+) Automatically detects and redacts 22 pattern types: AWS keys, GitHub tokens, JWTs, database connection strings, API keys, private keys, etc. Replaces matches with `<REDACTED:TYPE>`. ## `--minify` Behavior ```javascript content.split('\n') .map(line => line.trim()) .filter(line => line.length > 0) .join('\n') ``` Removes empty lines, trims whitespace per line. ## Token Splitting (`--max-tokens` / `-M`) - Reserves ~50 tokens per chunk for headers/footers - **Files are never split mid-file** - A single file exceeding the budget is skipped entirely (marked "oversized") - Creates: `output-1.xml`, `output-2.xml`, etc. - Only chunk 1 copied to clipboard; rest go to files ## Concurrency - Files analyzed in parallel using `p-limit` - `CONCURRENCY_LIMIT = 50` - Progress emitted every 50 files or 10% of total ## .packignore - Gitignore syntax (processed by `ignore` npm library) - Auto-loaded from project root - `--no-packignore` to disable - In interactive mode: matching files shown but unselected - `x` hotkey in interactive mode banishes files to `.packignore` ## Positional Path Arguments ```bash packx src/ # Directory → scan root packx README.md # File → explicit include packx "**/*.test.ts" # Glob pattern → include pattern ``` **Classification:** - Contains `*`, `?`, `[`, `]`, `{`, `}`, `!` → treated as glob pattern - Exists as directory → treated as scan root - Exists as file → treated as explicit file include **Interaction with filters:** - Explicit files + `-i` patterns: must match BOTH - Positional roots: used as starting directories for scanning - Positional globs: added to include patterns ## Gotchas & Edge Cases | Issue | Detail | |-------|--------| | `-i "*.ts"` matches nothing | Must use `"**/*.ts"` with `**/` prefix for extensions | | Interactive is default | Since v4.7.0, bare `packx` enters interactive mode. Use `--no-interactive` for scripting | | `--stdout` disables interactive | Can't combine `--stdout` with `-I` | | `--watch` + `-I` incompatible | Watch requires output target, can't be interactive | | Files >10MB silently skipped | No warning — use `--explain` to debug missing files | | Single file > `--max-tokens` | Entire file skipped, not split | | Clipboard: only chunk 1 | When splitting, remaining chunks go to files | | Binary files silently skipped | >10% non-printable chars in first 512 bytes | ## Operational boundaries - Processing order, cache format, secret-detector coverage, AST fallbacks, and numeric limits describe the referenced implementation. Confirm the installed version; stripped or minified context may omit semantics needed for the question. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-packx-technical-reference Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Preference capture / personal RLHF (this-or-that) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Preference capture / personal RLHF (this-or-that) **John uses:** the **this-or-that kit** (section 10; kit published at [gentle-lasso-9d5n.here.now/kit/](https://gentle-lasso-9d5n.here.now/)) — `compare.html` + a 30-line `server.py` + `options.json`: Elo pairing, arrow-key duels, both-bad/skip, per-vote notes, light/dark per-mode tracking; every vote appends to `votes.jsonl`, which agents read back as explicit taste rules. This repo's own theme was chosen by it (130 votes, 3 rounds). | Alternative | What it is | How it differs | License | |----|----|----|----| | [FastChat (Chatbot Arena)](https://github.com/lm-sys/FastChat) | The platform behind Chatbot Arena: side-by-side battles + Elo ratings for LLM outputs | The industrial version of the same idea (pairwise vote → Elo); heavyweight, model-comparison focused; check current repository activity | Apache-2.0 | | [Argilla](https://github.com/argilla-io/argilla) | Collaboration tool for building high-quality AI datasets, including preference/ranking records | Team-scale dataset curation with a server; overkill for a solo taste record but the real thing for RLHF data | Apache-2.0 | | [Label Studio](https://github.com/HumanSignal/label-studio) | Multi-type data labeling tool with pairwise-comparison templates | General annotation platform; pairwise comparison is one template among many | Apache-2.0 | | [potato](https://github.com/davidjurgens/potato) | Portable academic annotation tool (Python), supports pairwise/best-worst schemes | Lightweight and self-hostable like the kit, config-driven rather than iframe-anything | GPL-3.0 | | [promptfoo](https://github.com/promptfoo/promptfoo) | Prompt/agent eval harness with side-by-side output comparison views | Automated + human-graded evals over prompt variants — the 'evals' complement to taste voting | MIT | ### Pick this if… - **the kit itself** — it's ~3 small files and free; there's little reason not to start with it. - **promptfoo** — your comparisons are prompt/agent outputs and you want automation around the human votes. - **Argilla / Label Studio** — you're collecting preferences from a *team*, not just yourself. - **FastChat** — you're literally comparing models and want battle-tested Elo infrastructure. - **potato** — you want a tiny self-hosted study-style setup with config-defined schemes. Reference ID: factory-tools-preference-rlhf Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#preference-rlhf) --- # Prompt composing (prompt-builder) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Prompt composing (prompt-builder) **John uses:** [prompt-builder](https://github.com/johnlindquist/prompt-builder) (`p`, MIT) — a Rust/Ratatui TUI that gives the prompt its own tool before any agent launches: skills lookup (`$`), file search (`@`), cross-session history (`Ctrl+R`, shared with Codex's history.jsonl), then launches pi/Codex/Claude via `targets.toml` — or hands the prompt as the final argv element to *any* command (`--handoff-command`), which is the bridge to mdflow. Nothing public replicates this exact "compose-then-launch-any-agent" TUI; these cover its axes: | Alternative | What it is | How it differs | License | |----|----|----|----| | [fabric](https://github.com/danielmiessler/Fabric) | Open-source framework with a crowdsourced library of reusable AI prompts ('patterns') runnable from the CLI | Curated prompt library + pipe-friendly CLI rather than an interactive composer; patterns ≈ reusable prompt shapes | MIT | | [llm (Simon Willison)](https://github.com/simonw/llm) | CLI for any LLM with reusable templates, fragments, logged history in SQLite | Templates + logged/searchable prompt history covers prompt-builder's reuse and history axes, minus the TUI and agent handoff | Apache-2.0 | | [aichat](https://github.com/sigoden/aichat) | All-in-one LLM CLI: Shell Assistant, chat REPL, roles, sessions, RAG, macros | Roles/sessions give reusable prompt setups; REPL-centric rather than compose-then-launch; check current repository activity | Apache-2.0 | | [espanso](https://github.com/espanso/espanso) | Privacy-first cross-platform text expander in Rust | System-wide snippet expansion — the low-tech way to get instant prompt scaffolds in ANY agent's input box | GPL-3.0 | | [promptfoo](https://github.com/promptfoo/promptfoo) | Test/eval harness for prompts, agents, and RAGs with declarative configs | Adjacent, not a composer: it evaluates prompt variants — pairs well with a this-or-that habit | MIT | ### Pick this if… - **fabric** — you want a library of proven prompt shapes runnable from the shell. - **llm** — you want reusable templates plus searchable prompt history (the SQLite log is the killer feature). - **espanso** — you just want instant prompt scaffolds in *any* input box, agents included. - **aichat** — you want roles/sessions in a REPL rather than compose-then-launch. - **promptfoo** — you're past composing and want to *measure* prompt variants. - Or steal the pattern cheaply: a zsh function + `$EDITOR` tempfile + `"$(cat file)"` into your agent is 70% of `p`. Reference ID: factory-tools-prompt-tooling Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#prompt-tooling) --- # Reliable non-interactive shell environments: practical reference ## Agent Setup Prompt ```text Set up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells. Step 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only: zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' Do not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables. Step 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as: export ZDOTDIR="${ZDOTDIR:-$HOME/.config/zsh}" Verify: zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; test -d "$ZDOTDIR" && echo "ZDOTDIR exists" || echo "ZDOTDIR missing"' Step 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides. Use this shape, adjusted to the existing files: [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" [[ -r "$ZDOTDIR/conf.d/00-path.zsh" ]] && source "$ZDOTDIR/conf.d/00-path.zsh" [[ -r "$ZDOTDIR/local.zsh" ]] && source "$ZDOTDIR/local.zsh" Step 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded: export CODEX_AGENT_ENV_SOURCED=1 Do not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here. Step 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins. Verify PATH order: zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,25p"' Verify executable resolution: zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo "--- $cmd ---"; command -v "$cmd" || true; whence -a "$cmd" 2>/dev/null || true; done' Step 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints. Step 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup. Step 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`. Add this in the agent-safe startup path after `ZDOTDIR` is available: if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" ]]; then [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh" fi Verify the marker is absent by default: zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"' Verify selected helper loading when requested: CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' Step 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers: xi() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@" } x() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } e() { codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } Only add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL: [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" Otherwise, keep the marker out of global config and use the wrappers. Verify wrapper policy wiring: zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true Step 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state. zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true' Expected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed. Step 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`. Step 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`. ``` ## Big Idea When Codex runs a shell command, it is not inside your current terminal session. This section answers one question: ```text What can Codex see when it runs a non-interactive login shell through `zsh -lc`? ``` Focus here on startup files, PATH order, environment markers, and project tools. Leave command-name classification for Section 3. ## Try This Now Run the same shell shape Codex commonly uses: `zsh -lc 'echo ZDOTDIR=$ZDOTDIR; command -v bun pnpm cargo codex packx || true'` If a project tool is missing here, fix agent-safe startup before changing the prompt. ## Files To Inspect Common files that define shell behavior: ```text ~/.zshenv ~/.config/zsh/.zprofile ~/.config/zsh/codex-env.zsh ~/.config/zsh/conf.d/00-path.zsh ~/.config/zsh/conf.d/40-ai.zsh ~/.config/zsh/local.zsh ~/.config/zsh/tests/startup-regression.zsh ~/.codex/config.toml ``` Adjust paths for the local machine. Keep non-interactive startup setup in the agent-safe path. ## When To Reach For This Use this workflow when: - Codex says a project executable is `command not found` - a tool works in your terminal but fails inside Codex - a project depends on Bun, pnpm, Cargo, PackX, Homebrew tools, or custom CLIs - you installed a tool but the agent still cannot run it - a workflow depends on PATH order - the wrong executable version wins inside Codex - selected agent-safe zsh files should load only when the opt-in marker is present - you need to decide whether PATH setup belongs in `.zprofile`, `codex-env.zsh`, `00-path.zsh`, or `local.zsh` Skip this workflow when the question is: ```text Is this command name an alias, function, builtin, hashed command, executable, or missing helper? ``` That is Section 3. ## How This Used To Work What you used to expect: ```text If a command works in your terminal, Codex can run it the same way. ``` What the workflow gives you now: ```text Codex runs through a non-interactive shell. Ask it to prove each required tool resolves from `zsh -lc` before relying on the command. ``` ## The Mental Model Codex commonly runs commands through a shell shape like: ```bash zsh -lc '<command>' ``` That means: - `zsh`: run zsh - `-l`: login shell - `-c`: run a command string It is login, but not interactive. That distinction matters: | File Or Setting | Role | | --- | --- | | `~/.zshenv` | earliest bootstrap; points zsh toward XDG config | | `ZDOTDIR` | tells zsh where `.zprofile`, `.zshrc`, and related files live | | `$ZDOTDIR/.zprofile` | login-shell bridge for `zsh -lc` | | `$ZDOTDIR/codex-env.zsh` | agent-safe environment bootstrap | | `$ZDOTDIR/conf.d/00-path.zsh` | deterministic PATH assembly | | `$ZDOTDIR/conf.d/40-ai.zsh` | selected AI/Codex helper functions loaded only when opted in | | `$ZDOTDIR/local.zsh` | machine-specific safe overrides | | `$ZDOTDIR/.zshrc` | human interactive terminal startup | Practical rule: ```text Put PATH and non-interactive-safe tool setup in the agent path. Put prompt, completion, keybindings, and terminal UI in `.zshrc`. ``` ## Visibility Layers Keep three layers separate. | Layer | What It Means | Section 2 Question | | --- | --- | --- | | Environment variable | inherited process data | is the variable present in `zsh -lc`? | | PATH executable | real file found through PATH | does `command -v <name>` resolve in `zsh -lc`? | | Opt-in zsh helper file | selected source file loaded by marker | does the marker cause the safe file to load? | This section proves the environment and PATH layer. Section 3 classifies individual command names. ## Opt-In Function Loading A common setup uses a local marker: ```text CODEX_LOAD_ZSH_DSL=1 ``` `CODEX_LOAD_ZSH_DSL` is a local opt-in marker for this shell setup. Codex can inject that marker into shell-like tool processes with `shell_environment_policy.set`: ```bash codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' ``` That marker can be wrapped in opt-in launchers: ```zsh x() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } e() { codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" } ``` The important part is the `-c` override: ```bash codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@" ``` Prefer wrapper-local `-c` flags when the behavior should be explicit and reversible. Use a global `~/.codex/config.toml` setting only when every Codex launch should load the DSL: ```toml [shell_environment_policy.set] CODEX_LOAD_ZSH_DSL = "1" ``` Use the global setting only when you want that behavior all the time. Otherwise, keep `CODEX_LOAD_ZSH_DSL` out of `~/.codex/config.toml` and put it on the specific wrappers that need zsh helper functions. ## What The Marker Does The marker lets the zsh bootstrap source a small set of agent-safe files instead of the full interactive `.zshrc`. Shape: ```zsh if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" ]]; then [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh" [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh" fi ``` Load selected helpers only. Keep the full interactive terminal experience out of agent shells. Do not source all of `.zshrc` into agent shells. Interactive startup often includes prompts, completions, keybindings, fuzzy finders, terminal hooks, and profiling code that can slow, hang, spam, or mutate non-interactive agent commands. ## The Opt-In Marker Is Not Interactive Startup `x` and `e` can make Codex set `CODEX_LOAD_ZSH_DSL=1`, but that does not mean the full interactive shell is loaded. The marker should load only selected agent-safe files. Expected shape: ```text CODEX_LOAD_ZSH_DSL=1 -> zsh startup -> codex-env.zsh -> selected safe helper files -> no prompt, completion, keybindings, fuzzy finder, or terminal UI ``` Quick visibility check: ```bash CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' ``` If a helper name is missing after this works, do not diagnose it as a broken PATH. Diagnose it in Section 3 as a command-name, source-file, or executable-fallback question. ## Ask The Agent This For a missing tool: ```text Codex cannot find `bun`, but it works in my terminal. Inspect the zsh startup path for non-interactive commands. Check `zsh -lc`, `ZDOTDIR`, `codex-env.zsh`, PATH order, and where Bun is installed. Do not dump secrets or full environment output. Tell me which file should change and how to confirm it worked. ``` For a new project tool: ```text This project needs `my-tool` available to Codex. Inspect the existing agent-safe zsh setup and recommend where the PATH entry or wrapper should live. Keep interactive shell behavior out of the agent startup path. Include a short command that confirms `my-tool` resolves in `zsh -lc`. ``` For PATH confusion: ```text The wrong version of `node` or `pnpm` is winning inside Codex. Inspect PATH order from `zsh -lc`, compare executable locations with `whence -a`, and identify the smallest safe config change. Do not modify `.zshrc` unless the problem is only interactive terminal behavior. ``` For opt-in marker boundaries: ```text I want Codex tool shells to load only selected agent-safe zsh files without sourcing the full interactive `.zshrc`. Inspect `~/.codex/config.toml`, `shell_environment_policy.set`, `CODEX_LOAD_ZSH_DSL`, `~/.config/zsh/.zshenv`, `codex-env.zsh`, and `conf.d/40-ai.zsh`. Confirm the marker is explicit and reversible. If an individual helper name is missing after the marker works, stop and classify that name with Section 3. ``` ## What To Confirm The basic confirmation shape: ```bash zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true' ``` What to look for: - `CODEX_AGENT_ENV_SOURCED=1` - `ZDOTDIR` points at the intended zsh config - required tools print real paths - missing tools are named plainly - no secrets are printed A known-good output shape looks like: ```text CODEX_AGENT_ENV_SOURCED=1 ZDOTDIR=/path/to/home/.config/zsh /path/to/home/.cargo/bin/codex /path/to/home/.bun/bin/bun /usr/local/bin/pnpm /path/to/home/.cargo/bin/cargo /path/to/home/.bun/bin/packx ``` Use local paths. Keep the proof shape. ## Confirm The Opt-In Marker Prove the marker is absent by default: ```bash zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"' ``` Prove the agent-safe files load when the marker is present: ```bash CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true' ``` Inspect the Codex-side policy: ```bash zsh -ic 'functions x; functions e' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true ``` What to look for: - `x` and `e` pass the marker through Codex with `-c` - global config does not set the marker unless you want it always on - tool visibility still works when the marker is present ## Handoff To Section 3 After `zsh -lc` proves the environment and PATH are correct, stop treating every missing name as a startup problem. Next question: ```text What kind of command name is this? ``` Use Section 3 to classify aliases, functions, builtins, hashed commands, executables, missing helpers, and executable fallback decisions. ## Inspect PATH Order PATH order decides which executable wins. ```bash zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,25p"' ``` Look for: - project tool paths before system fallbacks when appropriate - Bun, pnpm, Cargo, Homebrew, and local bin locations - duplicate or surprising entries - installer edits that only touched `.zshrc` ## Clean-Shell Check The marker `CODEX_AGENT_ENV_SOURCED=1` can be inherited by nested shells. When testing startup from scratch, unset it: ```bash env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true' ``` If the bootstrap works, the command should still end up with `CODEX_AGENT_ENV_SOURCED=1`. ## Where Fixes Usually Belong | Problem | Usually Belongs In | | --- | --- | | persistent PATH assembly | `~/.config/zsh/conf.d/00-path.zsh` | | machine-local safe override | `~/.config/zsh/local.zsh` | | agent-safe tool env | `~/.config/zsh/codex-env.zsh` | | selected agent-safe functions | `~/.config/zsh/conf.d/40-ai.zsh` behind `CODEX_LOAD_ZSH_DSL` | | login-shell bridge | `~/.config/zsh/.zprofile` | | prompt, completion, keybindings | `~/.config/zsh/.zshrc` | | reusable project command | executable wrapper on PATH | | rich alias/function workflow | function or executable-wrapper design | ## If It Goes Wrong ### Tool Works In Terminal, Missing In Codex Likely cause: - installer modified `.zshrc` - Codex runs `zsh -lc` - `.zshrc` is interactive startup, not the agent-safe bridge Confirm: ```bash zsh -lc 'command -v bun || echo "bun missing from zsh -lc"' ``` Then inspect `codex-env.zsh`, `00-path.zsh`, and `local.zsh`. ### Wrong Executable Wins Use: ```bash zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo "--- $cmd ---"; command -v "$cmd" || true; whence -a "$cmd" 2>/dev/null || true; done' ``` The first matching executable is what the shell runs. ### Agent Startup Hangs Likely cause: - prompt setup - completion setup - `fzf` - keybindings - terminal UI - interactive confirmation Those belong in `.zshrc` or behind an interactive guard, not in agent-safe startup. ### Secrets Leak Risk Do not paste full `env` output into chat. Use targeted checks: ```bash zsh -lc 'command -v op >/dev/null 2>&1 && echo "op:visible" || echo "op:missing"' ``` Confirm helpers exist without printing secret values. ### Tool Visibility Works, But A Helper Name Is Missing If required project tools resolve but a helper such as `xfl`, `p-f`, `fix`, or `funcwhere` is missing, the environment may already be fine. Confirm the project tools first: ```bash zsh -lc 'command -v bun pnpm cargo codex packx || true' ``` Then move to Section 3 and classify the helper name. Do not fix helper-name problems by sourcing all of `.zshrc` into agent shells. ## How To Know It Worked You are done when: - `zsh -lc` resolves the required project tools - the clean-shell check also resolves them - PATH order is explainable - the opt-in marker behavior is explicit and reversible - the fix is in an agent-safe file - `.zshrc` is not carrying agent-only setup - no startup command prints secrets or waits for UI - Codex can run the project command that originally failed - unresolved helper names have been handed to Section 3 instead of treated as PATH failures ## References And Resources - Common login-shell bridge: `~/.config/zsh/.zprofile` - Common agent bootstrap: `~/.config/zsh/codex-env.zsh` - Common PATH assembly: `~/.config/zsh/conf.d/00-path.zsh` - Common AI helper DSL: `~/.config/zsh/conf.d/40-ai.zsh` - Common AI fix helpers: `~/.config/zsh/conf.d/47-ai-fix.zsh` - Common local overrides: `~/.config/zsh/local.zsh` - Common startup regression tests: `~/.config/zsh/tests/startup-regression.zsh` - Codex config: `~/.codex/config.toml` - Zsh startup files: https://zsh.sourceforge.io/Intro/intro_3.html - Zsh options and invocation: https://zsh.sourceforge.io/Doc/Release/Invocation.html - OpenAI Codex: https://openai.com/codex/ ## Operational boundaries - `--dangerously-bypass-approvals-and-sandbox` is a high-trust launch choice, not required for environment-marker injection. The shown `env -u` check clears one guard, not the entire inherited environment. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-environment-reference Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Reliable non-interactive shell environments: practice drills These exercises practice diagnosing agent shell visibility without turning the session into a full dotfiles audit. ## Exercise 1: Write A Missing Tool Prompt Write a prompt that asks an agent to diagnose one missing tool. Template: ```text Codex cannot find `<tool>`, but it works in my terminal. Inspect the non-interactive zsh startup path. Check `zsh -lc`, `ZDOTDIR`, the agent-safe bootstrap, PATH order, and where the tool is installed. Do not print secrets or full environment output. Tell me which file should change and how to confirm it worked. ``` ## Exercise 2: Agent Env Snapshot Run the confirmation shape for your machine: ```bash zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true' ``` Write: ```markdown # Agent Env Snapshot - shell shape: - ZDOTDIR: - marker: - tools found: - tools missing: - next action: ``` ## Exercise 3: Number PATH ```bash zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,30p"' ``` Write: ```markdown # PATH Notes - first project/toolchain path: - package manager path: - language runtime path: - Homebrew path: - suspicious entries: - what should move: ``` ## Exercise 4: Clean-Shell Check ```bash env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true' ``` Answer: ```markdown # Clean-Shell Check - Did the marker become set again? - Did required tools resolve? - What changed compared to the normal check? - What does that imply? ``` ## Exercise 5: Place The Fix For each case, choose the right home: | Case | File Or Form | | --- | --- | | persistent PATH assembly for all shells | | | machine-local private path | | | prompt theme | | | keybinding | | | reusable command needed outside zsh | | | rich helper function for interactive work | | | safe agent bootstrap | | Options: ```text ~/.config/zsh/conf.d/00-path.zsh ~/.config/zsh/local.zsh ~/.config/zsh/codex-env.zsh ~/.config/zsh/.zshrc executable wrapper on PATH Section 3 zsh DSL ``` ## Exercise 6: Function Or Executable Run: ```bash zsh -lc 'for name in bun packx funclist fix agent_chain xfl; do echo "--- $name ---"; command -v "$name" 2>/dev/null || echo "command -v: missing"; whence -w "$name" 2>/dev/null || echo "whence: missing"; done' ``` Classify: ```markdown # Function Versus Executable | name | executable / function / missing | Section 2 or Section 3? | why | | --- | --- | --- | --- | | bun | | | | | packx | | | | | funclist | | | | | fix | | | | | agent_chain | | | | | xfl | | | | ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-environment-practice Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Resource access and tool directory Use the portable repository for the examples, practice drills, shell snippets, and hook contracts. Review each command against the installed tool before running it. ## Download the portable repository [Download the Git bundle](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) · [SHA-256 checksum](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle.sha256) ```bash curl -fL -o workshop-resources.bundle https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle git clone workshop-resources.bundle workshop-resources ``` [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) ## Companion Links | Resource | Use | | --- | --- | | [https://lapis-fossil-vsbc.here.now/](https://lapis-fossil-vsbc.here.now/) | Complete reference companion | | [https://hollow-onyx-ajww.here.now/](https://hollow-onyx-ajww.here.now/) | Related published companion | | [https://vowful-fable-32mh.here.now/](https://vowful-fable-32mh.here.now/) | Related published companion | ## Core Public Links | Resource | URL | | --- | --- | | Oracle | [https://askoracle.sh/](https://askoracle.sh/) | | Oracle repo | [https://github.com/johnlindquist/oracle](https://github.com/johnlindquist/oracle) | | PackX package | [https://www.npmjs.com/package/packx](https://www.npmjs.com/package/packx) | | Pack README | [https://github.com/johnlindquist/pack#readme](https://github.com/johnlindquist/pack#readme) | | Codex Imps repo | [https://github.com/johnlindquist/codex-imps](https://github.com/johnlindquist/codex-imps) | | Gog CLI | [https://gogcli.sh/](https://gogcli.sh/) | | Inspiration Board variation example | [https://inspiration-board.pages.dev/variations/01-masonry-grid](https://inspiration-board.pages.dev/variations/01-masonry-grid) | | Codex hooks docs | [https://developers.openai.com/codex/hooks](https://developers.openai.com/codex/hooks) | | Codex app-server source | [https://github.com/openai/codex/tree/main/codex-rs/app-server](https://github.com/openai/codex/tree/main/codex-rs/app-server) | | Prompt Builder repo | [https://github.com/johnlindquist/prompt-builder](https://github.com/johnlindquist/prompt-builder) | | Local Fusion repo | [https://github.com/johnlindquist/fusion](https://github.com/johnlindquist/fusion) | | OpenRouter Fusion product | [https://openrouter.ai/fusion](https://openrouter.ai/fusion) | | OpenRouter Fusion model page | [https://openrouter.ai/openrouter/fusion](https://openrouter.ai/openrouter/fusion) | | OpenRouter Fusion announcement | [https://openrouter.ai/blog/announcements/fusion-beats-frontier/](https://openrouter.ai/blog/announcements/fusion-beats-frontier/) | | OpenRouter model fallback article | [https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/](https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/) | | Agent Markers repo | [https://github.com/johnlindquist/agent-markers](https://github.com/johnlindquist/agent-markers) | | Gemini app | [https://gemini.google.com/app](https://gemini.google.com/app) | | Cypress docs | [https://docs.cypress.io/](https://docs.cypress.io/) | | Playwright test assertions | [https://playwright.dev/docs/test-assertions](https://playwright.dev/docs/test-assertions) | | here.now docs | [https://here.now/docs](https://here.now/docs) | | Tailscale Funnel docs | [https://tailscale.com/kb/1223/funnel](https://tailscale.com/kb/1223/funnel) | | Bun | [https://bun.sh/](https://bun.sh/) | | jq | [https://jqlang.github.io/jq/](https://jqlang.github.io/jq/) | | Homebrew | [https://brew.sh/](https://brew.sh/) | | Script Kit | [https://scriptkit.com/](https://scriptkit.com/) | | Zsh builtins manual | [https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html](https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html) | | Zsh functions manual | [https://zsh.sourceforge.io/Doc/Release/Functions.html](https://zsh.sourceforge.io/Doc/Release/Functions.html) | | Zsh startup overview | [https://zsh.sourceforge.io/Intro/intro_3.html](https://zsh.sourceforge.io/Intro/intro_3.html) | | Zsh invocation manual | [https://zsh.sourceforge.io/Doc/Release/Invocation.html](https://zsh.sourceforge.io/Doc/Release/Invocation.html) | | tmux manual | [https://man7.org/linux/man-pages/man1/tmux.1.html](https://man7.org/linux/man-pages/man1/tmux.1.html) | | tmux wiki | [https://github.com/tmux/tmux/wiki](https://github.com/tmux/tmux/wiki) | | Model Context Protocol | [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/) | | OpenAI Codex | [https://openai.com/codex/](https://openai.com/codex/) | | yt-dlp | [https://github.com/yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp) | | FFmpeg docs | [https://ffmpeg.org/documentation.html](https://ffmpeg.org/documentation.html) | | ffprobe docs | [https://ffmpeg.org/ffprobe.html](https://ffmpeg.org/ffprobe.html) | ## Bundled Skills | Skill | Bundled Path | What To Ask For | | --- | --- | --- | | Oracle PackX | `skills/oracle-packx/SKILL.md` | Bundle relevant repo context with PackX, send it to Oracle, and turn the result into an implementation plan or review | | Oracle PackX references | `skills/oracle-packx/references/` | Quick and deep PackX reference material | | Oracle Video | `skills/oracle-video/SKILL.md` | Analyze a recording or walkthrough through Gemini browser mode and produce evidence-backed follow-up material | | Oracle Video process | `skills/oracle-video/references/repeatable-video-followup-process.md` | Repeatable video follow-up workflow with source hashes, probes, transcript evidence, and omissions pass | | Fusion | `skills/fusion/SKILL.md` | Run a local model council, wait for `summary.json` and `final.md`, then treat the council output as advisory | | Web Choices | `skills/web-choices/SKILL.md` | Present generated options in a small review UI, collect structured feedback, and resume from saved JSON | ## Zsh And Shell Materials | Path | Use | | --- | --- | | `zsh/README.md` | Overview of the agent-safe zsh startup files and checks | | `zsh/.zshenv` | XDG `ZDOTDIR` bootstrap example | | `zsh/.zprofile` | Login-shell bridge for `zsh -lc` | | `zsh/codex-env.zsh` | Agent-safe non-interactive shell bootstrap example | | `zsh/conf.d/00-path.zsh` | Deterministic PATH assembly example | | `zsh/conf.d/40-ai.zsh` | Small workshop loader for the focused function snippets | | `zsh/conf.d/47-ai-fix.zsh` | Fusion-first `fix` helper example | | `zsh/examples/local.zsh.example` | Public shape for machine-local overrides | | `zsh/examples/codex-config-shell-environment-policy.toml` | Example `shell_environment_policy.set.CODEX_LOAD_ZSH_DSL` launch configuration | | `zsh/tests/startup-regression.zsh` | Startup regression checks | ## Zsh Function Snippets These snippets copy the named helper functions discussed in the workshop without copying whole private shell files. | Snippet | Helpers Included | | --- | --- | | `zsh/functions/codex-launch-and-prompt-builder.zsh` | `x`, `xi`, `xfl`, `xfc`, `_codex_cmux_current_session_id`, `_codex_cmux_name_current_tab`, `_codex_prompt_builder_fork`, `_p_handoff_zsh`, `p-f`, `p-c`, `p-cm`, guarded app-server helper stubs | | `zsh/functions/shell-introspection.zsh` | `funclist`, `funcwhere`, `funced` | | `zsh/functions/fusion-fix.zsh` | `fix` | | `zsh/functions/orchestration-helpers.zsh` | `muxai`, lazy-loader shapes for `agent_chain`, `ghost-save`, and `aicm` | | `zsh/functions/script-kit-process-helpers.zsh` | `pksk`, `ksk` | ## Command-Line Tools And Concepts | Tool Or Concept | Where It Appears | | --- | --- | | `zsh -lc` | Section 2 and Section 3 shell startup checks | | `shell_environment_policy.set` | Section 2 Codex environment injection | | `CODEX_LOAD_ZSH_DSL` | Local marker used to opt into selected zsh DSL loading | | `prompt-builder` / `p` | Section 5 prompt composition and handoff | | `--dry-run`, `--print-command`, `--print-prompt`, `--print-launch-json` | Prompt Builder preview and non-destructive checks | | `--submit`, `--stdin`, `--name`, `--instructions`, `--developer-instructions` | Prompt Builder launch and prompt-shaping modes | | `--handoff-command`, `--handoff-arg`, `--fork-from`, `--compact` | Prompt Builder handoff modes for zsh/Codex workflows | | `CODEX_THREAD_NAME` | Prompt Builder and cmux tab naming helpers | | `p-f`, `p-c`, `p-cm` | Prompt Builder handoff helpers | | `xfl`, `xfc` | Codex fork and compact fork helpers | | `cmux` | Addressable workspace, pane, surface, and process routing | | `cmux identify`, `cmux rpc workspace.current`, `cmux top`, `cmux read-screen`, `cmux focus-pane` | cmux state inspection and routed session follow-up | | `cmux-run-surface`, `cmux-fork-focused-codex`, `cmux-xport` | Local helper surface for pane launch, focused Codex fork, and transcript export | | `tmux` | Terminal multiplexer comparison and fallback mental model | | `muxai` | Quick tmux pane fan-out example | | `agent_chain` | Gated multi-agent work-unit helper pattern | | `imp`, `imps`, `imp-rg` | Isolated tool-agent commands | | `imp -l`, `imps list`, `imps ps`, `imps doctor`, `imp --which` | Imp discovery, health, and routing checks | | `imp --run`, `imp -q`, `imp --no-warm`, `imp --serve`, `imp --effort` | Imp direct-run, quiet, warm-runtime, server, and effort controls | | `-<imp>` / `--<imp>` | Foreground route vs forked cmux route in the hook examples | | `ffprobe` | Video metadata and verification probe | | `yt-dlp` | Video metadata/download helper | | `createAgentMarkers` | Browser debugging marker client | | `DebugSession`, `DebugMoment`, `CapturedEvent`, `nearbyEventIds` | Agent Markers export schema concepts | | `mark`, `event`, `export`, `download`, `clear`, `stop`, `onMarker` | Agent Markers client methods | | `window.__AGENT_MARKERS__` | Test-runner export surface for Agent Markers | | `fusion`, `fusion-med`, `fusion-high` | Local model-council CLI presets | | `summary.json`, `final.md`, `panel-*.stdout.md`, `panel-status.json` | Fusion session artifacts to wait for and inspect | | `browserAttachments: "always"`, `gemini-3-pro`, `END_OF_VIDEO_ANALYSIS` | Oracle Video browser-upload contract terms | | source hash, `ffprobe`, transcript, keyframes/contact sheet, omissions pass | Oracle Video evidence lanes | | `tailscale funnel`, `.ts.net`, `.token` | Web Choices phone-review tunnel and token-gated URL flow | | `bun`, `jq`, `brew` | Common local tooling for the Svelte/mdsvex choice app and JSON checks | | Script Kit, `pksk`, `ksk` | Script Kit process cleanup helpers mentioned in zsh examples | ## Hook And Orchestrator Examples | Path | Use | | --- | --- | | `hooks/README.md` | Dash-prefix Imp hook setup and verification | | `hooks/hooks.json.example` | Minimal Codex hook registration example | | `hooks/imp-user-prompt-submit.py.template` | `UserPromptSubmit` hook template for foreground and forked Imp routing | | `hooks/cmux-run-surface.example` | cmux pane-launch helper contract | | `hooks/cmux-codex-session-registry.py.example` | Redacted contract for resolving a cmux surface to a Codex session id | ## Questions That Still Need Evidence Review these questions before turning them into setup claims: - AI-ready repository setup patterns for long-running AFK work - Password-manager account/profile separation - Current Codex Imps setup and public README coverage - Reusable workspace layouts - Newsletter, people, book, and podcast recommendations - Public skill evaluation and personalization - Hiring traits, AI fatigue, and ethics framing ## Private Config Boundary Some local config is intentionally not copied verbatim: - `~/.config/zsh/local.zsh` - full `~/.codex/config.toml` - files that contain provider-specific key helpers or secret wiring - Fusion session artifacts under `~/.fusion/sessions/**`, which may contain prompts, source snippets, commands, stdout, stderr, and model responses Use the examples under `zsh/examples/` for the public shape. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) Reference ID: codex-resources Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Resources shared in the software-factory discussion Direct public links with their intended role, including source repositories, visual tools, context search, and research artifacts. ## Links shared during the workshop **Every exact chat URL** has a useful name, a reason to open it, its related lesson, and dated reachability status. Shared at 00:13:52 · Bound one factory loop ### [Workshop agenda](https://ember-bodhi-scrr.here.now/) The original workshop sequence and setup hub. **Use when:** Use this to compare the companion with the planned agenda. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop)Reachable Shared at 00:17:38 · Bound one factory loop ### [Coding with Agents field guide](https://kindly-mirage-ejqd.here.now/) The earlier field guide that grounded the workshop’s operating principles. **Use when:** Use this for the longer foundational argument. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop)Reachable Shared at 00:29:50 · Bound one factory loop ### [Cursor Origin](https://cursor.com/origin) An autonomous coding-agent product discussed during the opening model survey. **Use when:** Use this as an example of agent products moving toward longer-running work. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop)Reachable Shared at 00:45:07 · Recover state before continuing ### [Screenpipe](https://screenpipe.com/) Local activity capture for searchable work context. **Use when:** Compare approaches to recovering prior work from durable traces. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable Shared at 00:45:47 · Recover state before continuing ### [Pieces](https://pieces.app/) A developer work-memory and context product. **Use when:** Compare local continuity and retrieval approaches. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable Shared at 00:54:12 · Turn good prompts into inspectable flows ### [Flow Text source](https://github.com/johnlindquist/flow-text/) A repository for a reusable text-flow experiment. **Use when:** Inspect a concrete prompt-to-flow implementation. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable Shared at 01:05:41 · Diverge first, then record taste ### [Mini Arcade](https://miniarcade.dev/) A generated product used as a design and implementation example. **Use when:** See the result before inspecting its source repository. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable Shared at 01:06:00 · Diverge first, then record taste ### [Mini Arcade source](https://github.com/johnlindquist/miniarcade) The source repository behind the product example. **Use when:** Compare generated experience with inspectable implementation. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable Shared at 01:10:34 · Keep wrappers thin and work visible ### [Herdr](https://herdr.dev) A workspace surface for seeing parallel agent activity. **Use when:** Use this when designing visible execution, verification, and status lanes. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Not rechecked Shared at 01:21:06 · Keep wrappers thin and work visible ### [Linear](https://linear.app/) Issue and project tracking referenced during workflow discussion. **Use when:** Use this when connecting agent work to an existing task system. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Reachable Shared at 01:27:13 · Keep wrappers thin and work visible ### [Claudex](https://github.com/johnlindquist/claudex) A proxy and launcher experiment for coding-agent sessions. **Use when:** Inspect one approach to normalizing launch behavior. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Reachable Shared at 01:42:40 · Keep wrappers thin and work visible ### [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/) A published account of AI-assisted review at production scale. **Use when:** Use this as external context for evidence-first review workflows. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Reachable Shared at 02:16:45 · Point at the visual problem ### [Flameshot](https://flameshot.org/) Cross-platform screenshot and annotation tooling. **Use when:** Use this to create annotated visual prompts. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt)Reachable Shared at 02:17:04 · Point at the visual problem ### [Shottr](https://shottr.cc/) A macOS screenshot and annotation tool. **Use when:** Use this to point directly at a visual defect. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt)Reachable Shared at 02:35:02 · Compose only the evidence the task needs ### [Prompt Builder source](https://github.com/johnlindquist/prompt-builder) The repository for composing text, files, and other evidence into prompts. **Use when:** Inspect or adapt the prompt-composition workflow. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-prompt-composer)Reachable Shared at 03:04:12 · Turn good prompts into inspectable flows ### [gog CLI](https://gogcli.sh/) A command-line surface for Google services. **Use when:** Use this as an example of piping external system context into a flow. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable Shared at 03:09:32 · Turn good prompts into inspectable flows ### [Birdclaw](https://birdclaw.sh/) A command-line social workflow tool. **Use when:** Use this as another example of a tool that can feed a reusable flow. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable Shared at 03:33:17 · Turn good prompts into inspectable flows ### [CodeGraph](https://colbymchenry.github.io/codegraph/) A visual code-relationship explorer shown during workflow experiments. **Use when:** Use it for orientation; do not treat the workshop as proof of token savings. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable Shared at 04:22:08 · Recover state before continuing ### [Atuin](https://atuin.sh/) Searchable shell history across sessions and machines. **Use when:** Use this to locate the command that produced a durable artifact. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable Shared at 04:40:50 · Recover state before continuing ### [CASS skill](https://jeffreys-skills.md/skills/cass) A skill interface for coding-agent session search. **Use when:** Use this when recovering a decision from prior agent conversations. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable Shared at 04:41:16 · Recover state before continuing ### [Coding Agent Session Search](https://github.com/Dicklesworthstone/coding_agent_session_search) The source repository behind CASS. **Use when:** Inspect the underlying conversation-search implementation. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable Shared at 04:44:28 · Diverge first, then record taste ### [Inspiration Board](https://inspiration-board.pages.dev/) A board for collecting and comparing visual references. **Use when:** Use it to anchor variation work in visible references. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable Shared at 04:56:44 · Diverge first, then record taste ### [Impeccable](https://impeccable.style/) Design guidance and reusable taste constraints for agents. **Use when:** Use it when turning preferences into a durable design contract. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable Shared at 05:04:29 · Diverge first, then record taste ### [Matt Pocock’s skills](https://github.com/mattpocock/skills/tree/main) A public collection of agent skills referenced during preference work. **Use when:** Browse examples of packaged instructions and workflows. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable Shared at 05:06:47 · Escalate the decision, not the workflow ### [Oracle](https://github.com/steipete/oracle) A repository-context bundler and browser consult workflow. **Use when:** Use this when an independent reasoning path can change a costly decision. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence)Reachable Shared at 05:19:22 · Escalate the decision, not the workflow ### [Video analysis companion](https://silken-ferry-63mw.here.now/) The prepared companion for video-assisted analysis. **Use when:** Use this when timing or transient screen behavior matters. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence)Reachable Shared at 05:24:09 · Escalate the decision, not the workflow ### [Google AI Studio Live](https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview) A live multimodal model surface shared during the video discussion. **Use when:** Use only after verifying current availability and account requirements. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence)Reachable Shared at 05:26:41 · Let vision guide automation ### [Workshop NotebookLM notebook](https://notebooklm.google.com/notebook/4ae3bcdd-b31b-4e2b-af19-7e6c702c6cc7) The research notebook and generated artifacts shown near the close. **Use when:** Use generated artifacts as navigation, then trace consequential claims to sources. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation)Reachable Shared at 05:40:36 · Let vision guide automation ### [Handy](https://handy.computer/) A dictation tool shared during the VISION.md discussion. **Use when:** Use voice input when speaking product direction is faster than typing it. [Related lesson](https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation)Reachable ## Recording and additional published research - [Complete recording](https://www.dropbox.com/scl/fi/yg917eiyfrbmzqfh8jjdy/GMT20260717-155525_Recording_gallery_1920x1080.mp4?rlkey=ddjr30qey89fo41pw9xqrtwhm&st=346uon0v&dl=0) - [Recording chapter navigator](https://proud-anchor-53zn.here.now/watch.html) - [John's Zsh Configuration](https://gist.github.com/johnlindquist/7fe11a156ac483a83f083112bf54fcb8) - [Comprehensive ZSH configuration with AI integrations and development tools](https://gist.github.com/johnlindquist/f8911bff4aabc3e3e68beb6665cdb4a5) Reference ID: factory-shared-resources Topic: Tools Sources: - [Software factory resources](https://proud-anchor-53zn.here.now/resources.html) --- # Screenshot capture & annotation (CleanShot X) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Screenshot capture & annotation (CleanShot X) **John uses:** [CleanShot X](https://cleanshot.com/) (commercial, macOS) for section 03's whole workflow: hotkey capture → draw a fat red arrow or type the instruction **on** the screenshot → drag into the agent prompt. The annotation is the prompt. | Alternative | What it is | How it differs | License | |----|----|----|----| | [Shottr](https://shottr.cc/) | Fast, lightweight macOS screenshot tool: annotate, scrolling capture, OCR, ruler, color picker | Pay-what-you-want (from ~\$8); no screen recording or cloud; the standard CleanShot substitute for the arrow workflow | freeware/paid (closed source) | | [Flameshot](https://github.com/flameshot-org/flameshot) | Cross-platform OSS screenshot software with in-place arrow/text annotation | Free and cross-platform (Linux/Win/mac); annotation UI is the core feature | GPL-3.0 | | [ksnip](https://github.com/ksnip/ksnip) | Cross-platform screenshot and annotation tool (Qt) | OSS with rich annotation (arrows, numbering, blur); less polished than CleanShot | GPL-3.0 | | [macOS built-in Screenshot + Preview markup](https://support.apple.com/guide/mac-help/take-screenshots-or-screen-recordings-mh26782/mac) | Cmd+Shift+5 capture, then Markup arrows in Preview/Quick Look | Zero install; slower loop (no capture-annotate-drag single flow) | OS built-in | | [Kap](https://github.com/wulkano/Kap) | OSS macOS screen recorder (GIF/MP4) | Covers the recording half only; effectively unmaintained (check repository activity before adoption) — verify before adopting | MIT | ### Pick this if… - **Shottr** — you're on a Mac and want 90% of CleanShot for pay-what-you-want (no recording/cloud). - **Flameshot** — you're on Linux/Windows or want it free and open; annotation UI is the core feature. - **ksnip** — you want OSS with the richest annotation toolset. - **built-in Markup** — you can't install anything; the loop is just slower. - **Kap** — only if you need OSS recording and accept a dormant project (last push the example workflow). Reference ID: factory-tools-screenshot-annotation Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#screenshot-annotation) --- # Secrets for unsupervised agents (1Password op) Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Secrets for unsupervised agents (1Password op) **John uses:** the [1Password `op` CLI](https://developer.1password.com/docs/cli/) (commercial). AGENDA directive \#10: agents are safe to run unsupervised **if** secrets live in a vault and get injected per-command (`op run` / `op read`) instead of sitting in `.env` files any agent can read or leak. | Alternative | What it is | How it differs | License | |----|----|----|----| | [Bitwarden CLI (bw)](https://github.com/bitwarden/clients) | CLI for the Bitwarden password manager (open clients, optional self-host via vaultwarden) | Open-source clients and self-hosting; scripting ergonomics rougher than op run | NOASSERTION (GPL/Bitwarden License mix) | | [Infisical](https://github.com/Infisical/infisical) | Open-source platform for secrets, certificates, and privileged access; CLI injects env vars | Team/infra-grade secret management with \`infisical run\` (the closest op-run analog); self-hostable | NOASSERTION (MIT + enterprise dirs) | | [Doppler CLI](https://github.com/DopplerHQ/cli) | Official CLI for Doppler secrets/config: \`doppler run -- cmd\` injects secrets as env vars | SaaS-hosted; the smoothest run-with-secrets DX after op | Apache-2.0 | | [sops](https://github.com/getsops/sops) | Encrypt secrets inside files in your repo (age/KMS/PGP), decrypt on use | Secrets live encrypted next to code — no vault service at all | MPL-2.0 | | [pass](https://www.passwordstore.org/) + [age](https://github.com/FiloSottile/age) | The UNIX password store (GPG) and the modern simple file-encryption tool | Fully local/offline, scriptable, zero SaaS; you assemble the workflow yourself | GPL-2.0 (pass) / BSD-3-Clause (age) | ### Pick this if… - **Infisical** — you want the closest open `op run` experience and can self-host. - **Doppler** — you want the smoothest SaaS run-with-secrets DX. - **Bitwarden** — you already use it as a password manager; the CLI comes along. - **sops (+age)** — you want secrets versioned encrypted next to code, no vault service. - **pass + age** — you want fully local, scriptable, zero-SaaS. Reference ID: factory-tools-secrets Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#secrets) --- # Shell functions, aliases, and executable boundaries: practical reference ## Agent Setup Prompt ```text Set up the zsh helper files and configuration so local agents, scripts, and non-interactive shells can reliably use the important helpers on this page. Step 1: Inspect the helper files before changing anything. Check these project files first: ls -l zsh/conf.d/40-ai.zsh zsh/conf.d/47-ai-fix.zsh zsh/codex-env.zsh 2>/dev/null || true ls -l zsh/tests/startup-regression.zsh 2>/dev/null || true Use `zsh/conf.d/40-ai.zsh` for small agent-safe helper definitions, `zsh/conf.d/47-ai-fix.zsh` for the fix workflow, and `zsh/codex-env.zsh` for safe PATH/env setup. If a required file is missing, create the smallest file needed from public examples in this package. Do not copy private local config, secret helper files, full Codex config, token/API-key wiring, cookies, private endpoints, or raw `env` output. Step 2: Identify the helper names this setup needs. Start with helpers already defined in the files above, plus any important workflow names such as: x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist Adjust the list to match the actual files. Do not invent helpers that are not needed. Step 3: Classify each helper as alias, function, builtin, hashed command, executable, or missing. Run the quick pass: for name in x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist; do printf '%-14s ' "$name" whence -w "$name" 2>/dev/null || echo MISSING done Then run the detailed pass for each important helper: whence -w <name> 2>/dev/null || true type <name> 2>/dev/null || true alias <name> 2>/dev/null || true functions <name> 2>/dev/null | sed -n '1,80p' command -v <name> 2>/dev/null || true whence -p <name> 2>/dev/null || true Locate the defining file with `funcwhere <name> 2>/dev/null || grep -RIn "<name>()\|function <name>\|alias <name>=" zsh/conf.d zsh 2>/dev/null || true`. Step 4: Compare interactive zsh with non-interactive agent zsh. Remember that `zsh -lc` is login, but not interactive. Check both surfaces: zsh -ic 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true' CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true; command -v <name> 2>/dev/null || true; whence -p <name> 2>/dev/null || true' Treat `CODEX_LOAD_ZSH_DSL` as a local opt-in marker, not a built-in Codex feature. If Codex should provide it, configure the launch path with `shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"`. Step 5: Set up selected helper loading for `zsh -lc`. Keep `.zshrc`-only behavior out of the required agent path. Source only the narrow files needed for the helper. For shell-only helpers, use this handoff shape and preserve arguments through `"$@"`: zsh -lc 'source "$PWD/zsh/codex-env.zsh" >/dev/null 2>&1; source "$PWD/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; <name> "$@"' <name> "arg one" If the installed source path is different, replace the source path with the inspected file path. Do not interpolate user input inside the single-quoted `zsh -lc` body. Step 6: Fix source guards for function files. Function and alias files must not use exported source guards that child shells inherit while losing the functions. If a function DSL file uses an exported guard, replace it with a non-exported guard or make the file safe to source repeatedly. Env/path-only files may use exported guards when appropriate. Step 7: Create executable fallbacks only for helpers that need them. Use wrappers when CI, scripts, tmux, Prompt Builder, or another non-zsh caller must execute a helper by name without sourcing shell files. Wrapper shape: mkdir -p "$HOME/.local/bin" cat > "$HOME/.local/bin/<name>" <<'EOF' #!/usr/bin/env zsh set -e source "$HOME/.config/zsh/codex-env.zsh" >/dev/null 2>&1 || true source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1 <name> "$@" EOF chmod +x "$HOME/.local/bin/<name>" Adjust source paths to the real installed helper files. If the wrapper can call a real binary directly, use `exec /path/to/binary "$@"` instead. Avoid wrapper recursion: prove the wrapper calls the intended function or executable. Step 8: Verify PATH and wrapper resolution. For every executable fallback: command -v <name> whence -p <name> test -x "$(command -v <name>)" zsh -lc 'p="$(command -v <name>)"; print -r -- "$p"; test -n "$p" && test -x "$p"' If a function and executable share a name, prove both layers: CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name>; type <name>; whence -p <name> 2>/dev/null || true' env -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w <name> 2>/dev/null || true; command -v <name> 2>/dev/null || true; type <name> 2>/dev/null || true' Step 9: Run startup regression checks. If `zsh/tests/startup-regression.zsh` exists, run it with zsh: zsh zsh/tests/startup-regression.zsh If it does not exist, add a focused check that verifies the selected helper files load quietly, expected helpers resolve, PATH order is stable, and missing helpers fail clearly. Step 10: Report the result. Return a compact summary with: - files inspected and changed - each important helper name and its classification - defining source file for each helper - whether it works in `zsh -ic`, plain `zsh -lc`, and `CODEX_LOAD_ZSH_DSL=1 zsh -lc` - the safe `zsh -lc` handoff for each shell-only helper - executable wrapper paths created and their `command -v`, `whence -p`, and `test -x` results - startup regression result - any private files intentionally left untouched Do not print secrets, raw environment dumps, tokens, cookies, API keys, or private endpoints. If a helper cannot be safely set up, stop at the smallest clear blocker and report the next action. ``` ## Big Idea Aliases save keystrokes. Functions encode workflows. This is the handoff from Section 2: ```text The environment loads. Now prove what each helper name actually resolves to. ``` A name like `xfl` might be: - an alias - a zsh function - a shell builtin - a hashed command - an executable file on PATH - missing in this shell, even if it works somewhere else This section answers the command-name question: What is this name, where is it defined, and should callers use zsh handoff or an executable fallback? ## Try This Now Pick one helper that failed in a tool, such as `xfl`, `p-f`, or `fix`. Run: `zsh -ic 'whence -w <name>; type <name>; command -v <name> || true; whence -p <name> || true'` Decide: alias/function needs zsh handoff; executable can be called directly. ## Files To Inspect Common files that define helper behavior: ```text zsh/conf.d/40-ai.zsh zsh/conf.d/47-ai-fix.zsh zsh/tests/startup-regression.zsh zsh/codex-env.zsh ``` Helper names vary by setup. Classify each helper, then choose the right handoff pattern for the project. ## When To Reach For This Use this workflow when: - a helper works in your terminal but fails in Codex, Prompt Builder, cmux, tmux, a script, or CI - a helper name might be an alias or function instead of an executable - you want to inspect a workflow wrapper before trusting it - you need to decide whether a shorthand should be an alias, a function, or an executable wrapper - you need to expose a zsh helper safely through `zsh -lc` - you want to find where a helper is defined before editing it Focus on command diagnosis and workflow design. Skip dotfiles that do not affect the helper you are debugging. ## How This Used To Work What you used to expect: ```text A helper that runs in your shell will run the same way when an agent calls it. ``` What the workflow gives you now: ```text Functions and aliases do not resolve like executables. Load shell-only helpers with `zsh -lc 'source ...; fn "$@"'`, or create an executable wrapper when other tools need to call them directly. ``` ## The Mental Model Start with classification. ```zsh whence -w <name> type <name> alias <name> 2>/dev/null || true functions <name> 2>/dev/null | sed -n '1,80p' command -v <name> 2>/dev/null || true whence -p <name> 2>/dev/null || true ``` Then decide the integration shape. | Result | Meaning | Caller Strategy | | --- | --- | --- | | alias | interactive shell shorthand | use only at a prompt, or replace with function/executable | | function | zsh runtime command | load zsh and source the defining file | | builtin | shell-provided command | call inside the shell that owns it | | hashed command | cached executable path | refresh lookup with `rehash` if stale | | executable | real file on PATH | call directly from agents, scripts, CI, or wrappers | | missing | not visible in this shell | find the source file or create a fallback | Safe zsh handoff shape: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; <name> "$@"' <name> "arg one" ``` Executable fallback shape: ```zsh command -v <name> whence -p <name> test -x "$(command -v <name>)" ``` Plain rule: Use zsh handoff for shell-only helpers. Use an executable wrapper when non-zsh callers need the name. ## The Six Buckets | Bucket | What It Is | Good For | Confirm With | | --- | --- | --- | --- | | Alias | text substitution before command execution | tiny shorthands and defaults | `alias <name>`, `type <name>` | | Function | shell-defined command body | arguments, branching, policy, cleanup, handoff | `whence -w <name>`, `type <name>`, `functions <name>` | | Builtin | command implemented by the shell | `cd`, `alias`, `type`, `functions` | `whence -w <name>` | | Hashed command | cached executable path remembered by the shell | faster lookup after discovery | `hash`, `rehash`, `whence -w <name>` | | Executable | real file found through PATH | agents, scripts, CI, subprocesses | `command -v <name>`, `whence -p <name>`, `test -x` | | Environment variable | process data inherited by child processes | markers, config paths, feature toggles | `print -r -- "$VAR"` | Fast classification: ```zsh for name in alias cd git x e xfl xfc xport fix agent_chain muxai p-f p-c ghost-save pksk; do printf "%-14s " "$name" whence -w "$name" 2>/dev/null || echo MISSING done ``` ## Alias Or Function Use an alias when: - the command is just spelling - there is no argument parsing - there is no branching - there is no safety policy - the shorthand is mainly for humans at a prompt Example: ```zsh alias l='ls -lah' ``` Use a function when the helper needs: - arguments - branching - prerequisite checks - fallback behavior - cleanup - prompt construction - stdout/stderr discipline - source-control discipline - handoff into another tool Example workflow helper: ```zsh fix "billing webhook double-processes paid invoice" ``` `fix` belongs as a function because it turns a terse bug report into a richer repair workflow. It is not just shorter spelling. ## When An Executable Wrapper Is Required A function is not enough when the caller needs to execute a real file. Use a zsh handoff when: - the helper is local to zsh - the caller can run `zsh -lc` - the sourced file is small and safe - the helper is not needed from CI, scripts, or non-zsh tools Use an executable wrapper when: - a non-zsh process must call the helper by name - a script must run it without sourcing shell files - CI must run it - a repo command should work for teammates - Prompt Builder or another tool only accepts command paths - the helper is important enough to survive outside one shell setup Wrapper shape: ```zsh mkdir -p "$HOME/.local/bin" cat > "$HOME/.local/bin/x" <<'EOF' #!/usr/bin/env zsh exec codex --dangerously-bypass-approvals-and-sandbox "$@" EOF chmod +x "$HOME/.local/bin/x" ``` Confirm the wrapper: ```zsh zsh -lc 'p="$(command -v x)"; print -r -- "$p"; test -n "$p" && test -x "$p"' ``` If both a function and executable exist, prove both layers: ```zsh CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x; type x; whence -p x 2>/dev/null || true' env -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w x 2>/dev/null || true; command -v x || true; type x 2>/dev/null || true' ``` ## Function DSL Source Guard Trap An exported guard is fine for env/path-only files: ```zsh [[ -n "${CODEX_AGENT_ENV_SOURCED:-}" ]] && return 0 export CODEX_AGENT_ENV_SOURCED=1 ``` Avoid that pattern for zsh function DSL files. Bad pattern: ```zsh [[ -n "${CODEX_ZSH_DSL_SOURCED:-}" ]] && return 0 export CODEX_ZSH_DSL_SOURCED=1 x() { codex --dangerously-bypass-approvals-and-sandbox "$@"; } ``` Why it fails: The exported variable can survive into a child shell even though functions and aliases do not. The child shell sees the guard, skips the source file, and the function is missing. Use non-exported guards for shell-local function files, or make the source operation idempotent. ## Discover Helpers Use `funclist` as a table of contents: ```zsh funclist funclist ai funclist git funclist -v x ``` Use `funcwhere` to locate the source: ```zsh funcwhere xfl funcwhere xfc funcwhere xport funcwhere fix funcwhere agent_chain funcwhere muxai ``` Use `funced` when you are ready to inspect or edit: ```zsh funced xfl funced xfc funced fix ``` Plain rule: ```text funclist finds names. funcwhere finds the file. funced opens the definition. ``` If `funcwhere` itself is missing, classify `funcwhere` like any other helper. ```zsh whence -w funcwhere 2>/dev/null || true type funcwhere 2>/dev/null || true command -v funcwhere 2>/dev/null || true whence -p funcwhere 2>/dev/null || true ``` Compare the shell surfaces only to decide where the helper is loaded: ```zsh CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e' zsh -ic 'whence -v funcwhere; whence -v x; whence -v e' ``` Common result: ```text `x` and `e` load from the agent-safe helper file. `funcwhere` loads only from the interactive helper file. ``` That means the opt-in marker worked, but `funcwhere` is not part of the agent-safe helper set. Choose one: - source the specific safe module that defines it - move it into a small agent-safe introspection module - run the inspection through `zsh -ic` - create an executable fallback when non-zsh callers need it ## Confirm What A Name Really Is Use these in order. ```zsh whence -w xfl type xfl alias xfl 2>/dev/null || true functions xfl | sed -n '1,80p' command -v xfl || true whence -p xfl || true ``` If `whence -w xfl` says `function` but `whence -p xfl` is empty, the helper exists only as shell runtime state. Decision after classification: | Finding | Smallest Safe Move | | --- | --- | | alias only | expand it into the real command or convert it to a function | | function only | use `zsh -lc 'source ...; fn "$@"'` | | function plus executable | decide which layer each caller should use and prove both | | executable only | call it directly and verify PATH order | | missing in `zsh -lc`, present in `zsh -ic` | source the narrow defining file or keep it interactive-only | | needed by CI or scripts | create an executable wrapper | | depends on prompt/completion/UI state | keep it interactive-only | ## Helper Families | Family | Examples | What They Represent | | --- | --- | --- | | Codex launch/fork/export | `x`, `e`, `xfl`, `xfc`, `xport` | Codex wrapper, exec, fork, compact, transcript export | | Prompt Builder handoff | `p-f`, `p-c`, `p-cm` | explicit zsh handoff around function-backed workflows | | Fix workflow | `fix` | terse bug report -> richer repair workflow | | Git/checkpoint helpers | `cfix`, `ghost-save`, `aicm` | workflow compression around repo state | | Utility cleanup | `pksk`, `ksk` | alias vs function decision surface | | Orchestration bridge | `muxai`, `agent_chain` | transition into panes, phases, and multi-agent flows | ## Ask The Agent This Classify a broken helper: ```text `xfc` works in my terminal but fails when called by a tool. Classify `xfc` with `whence -w`, `type`, `alias`, `functions`, `command -v`, and `whence -p`. Find its source with `funcwhere`. Then show the smallest safe `zsh -lc` handoff command that sources the right file and preserves arguments. ``` Decide alias, function, or executable: ```text I want a helper for replaying billing webhook tests. Help me decide whether this should be an alias, zsh function, or executable wrapper. The helper should accept a fixture name, run the replay command, capture output, and print a clear pass/fail summary. Include confirmation commands for the chosen form. ``` Inspect before using: ```text Before I use `fix` on this repo, inspect what `fix` is. Use `whence -w`, `type`, `functions`, and `funcwhere`. Summarize what it wraps, what arguments it accepts, what it may change, and how I should confirm the repair. ``` ## If It Goes Wrong ### `command not found` Run: ```zsh whence -w <name> 2>/dev/null || true type <name> 2>/dev/null || true alias <name> 2>/dev/null || true functions <name> >/dev/null 2>&1 && echo function whence -p <name> 2>/dev/null || true command -v <name> 2>/dev/null || true ``` Likely result: ```text This helper is a function in interactive zsh, not a binary on PATH. ``` Recovery: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; <name> "$@"' <name> "arg one" ``` If the missing command is `funcwhere`, diagnose it with `whence`, `type`, and direct source-file inspection. Use `whence -v funcwhere` in both shell modes: ```zsh CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e' zsh -ic 'whence -v funcwhere' ``` If `funcwhere` appears only in `zsh -ic`, the helper lives outside the agent-safe subset. Either source its specific safe module, move it into an agent-safe introspection module, or run the inspection through `zsh -ic`. ### Alias Fails In A Script Aliases are shell substitutions. Use a full command, a sourced function, or an executable wrapper. ### Quoting Breaks Arguments Bad: ```zsh zsh -lc "source ~/.config/zsh/conf.d/40-ai.zsh; xfc $prompt" ``` Good: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' xfc "$prompt" ``` ### Lazy Stub Looks Like The Source If `funcwhere fix` points at a lazy stub file, that is not automatically a failure. It often means the helper is discoverable before the full module loads. ## How To Know It Worked You are done when: - you can identify what kind of helper the name resolves to - you know the source file - you know whether it is portable outside zsh - non-interactive callers have a safe `zsh -lc` handoff or executable wrapper - stdout/stderr behavior is safe for the caller - the confirmation command proves the helper can run in the intended context ## References And Resources - Helper file: `zsh/conf.d/40-ai.zsh` - Fix helper source: `zsh/conf.d/47-ai-fix.zsh` - Startup tests: `zsh/tests/startup-regression.zsh` - Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html - Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html - Zsh startup files overview: https://zsh.sourceforge.io/Intro/intro_3.html - Zsh invocation/options: https://zsh.sourceforge.io/Doc/Release/Invocation.html - OpenAI Codex: https://openai.com/codex/ ## Operational boundaries - Shell helper examples that bypass approvals and sandboxing require a trusted, separately isolated environment. Generic executable wrappers are the portability boundary; shell-function presence alone is not a smoke test. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-functions-reference Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Shell functions, aliases, and executable boundaries: practice drills These exercises practice command diagnosis and wrapper design. The goal is not to memorize every helper. The goal is to prove what a command name is and choose the right integration pattern. ## Exercise 1: Classify Command Names Run: ```zsh for name in alias cd git l rm x xi xfl xfc xport p-f p-c fix ghost-save pksk muxai agent_chain; do printf "%-14s " "$name" whence -w "$name" 2>/dev/null || echo MISSING done ``` Fill out: ```markdown # Command Classification | Name | alias / function / builtin / command / missing | Notes | | --- | --- | --- | | alias | | | | cd | | | | git | | | | xfl | | | | xfc | | | | xport | | | | fix | | | | muxai | | | | agent_chain | | | ``` Questions: - Which names are portable executables? - Which names only exist inside zsh? - Which names are workflow wrappers? ## Exercise 2: Function Versus Executable Pick three helpers: ```text xfl xfc xport p-f p-c fix agent_chain muxai ghost-save pksk ``` Run: ```zsh for name in xfl xfc xport; do echo "== $name ==" whence -w "$name" 2>/dev/null || true type "$name" 2>/dev/null || true command -v "$name" 2>/dev/null || true whence -p "$name" 2>/dev/null || true done ``` Fill out: ```markdown # Function Versus Executable | Helper | `whence -w` result | `command -v` result | `whence -p` result | Needs executable fallback? | | --- | --- | --- | --- | --- | | | | | | | ``` ## Exercise 3: Find The Source Pick one helper: ```text xfl xfc xport p-f p-c fix ghost-save pksk muxai agent_chain ``` Run: ```zsh whence -w <name> funcwhere <name> functions <name> | sed -n '1,120p' ``` Fill out: ```markdown # Function Reading Notes - helper: - kind: - source file: - purpose: - arguments: - external tools called: - files or git state it may change: - why this is a function instead of an alias: - one way to confirm it worked: - one failure mode: ``` ## Exercise 4: Use `funclist`, `funcwhere`, And `funced` Run: ```zsh funclist funclist ai funclist git funclist -v x ``` Then pick a helper and run: ```zsh funcwhere <name> funced <name> ``` Fill out: ```markdown # Discoverability Notes - topic searched: - helper found: - source file: - what `funclist` showed: - what `funcwhere` showed: - whether `funced` opened the expected source: - one improvement you would make to the helper comment or description: ``` ## Exercise 5: Alias Or Function? For each proposed helper, decide alias, function, executable wrapper, or no helper. | Desired Helper | Your Choice | Why | | --- | --- | --- | | `l` runs `ls -lah` | | | | `rm` routes to trash only when installed | | | | `replay-webhook <fixture>` runs a command, captures logs, and prints pass/fail | | | | `xport` exports the latest Codex transcript and optionally saves markdown | | | | `pksk` terminates process groups and cleans matching app processes | | | | `agent_chain` runs gated explore-plan-implement phases | | | | `ci-smoke` must run from GitHub Actions | | | ## Exercise 6: Write A Safe Handoff Scenario: Prompt Builder or another tool needs to call `xfc`, but `xfc` is a zsh function. Diagnose: ```zsh whence -w xfc funcwhere xfc whence -p xfc || true ``` Write a safe handoff: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' xfc "continue the failing billing webhook investigation" ``` Adapt the pattern for: ```text xfl xport p-f p-c ``` ## Exercise 7: Design An Executable Fallback Scenario: the project has a repeated workflow for replaying billing webhooks. It must work from zsh, scripts, CI, and agents. Create a wrapper shape: ```zsh mkdir -p bin cat > bin/replay-webhook <<'EOF' #!/usr/bin/env zsh set -euo pipefail fixture="${1:?Usage: replay-webhook <fixture>}" pnpm test:billing-webhook -- "$fixture" EOF chmod +x bin/replay-webhook ``` Confirm it: ```zsh zsh -lc 'PATH="$PWD/bin:$PATH"; p="$(command -v replay-webhook)"; print -r -- "$p"; test -x "$p"' zsh -lc 'PATH="$PWD/bin:$PATH"; replay-webhook sample-fixture' ``` Fill out: ```markdown # Executable Fallback Design - wrapper path: - shebang: - required arguments: - underlying command: - confirmation command: - why executable instead of function: ``` ## Exercise 8: Section 4 Bridge Run: ```zsh whence -w muxai agent_chain xfl xfc xport p-f p-c funcwhere muxai funcwhere agent_chain ``` Fill out: ```markdown # Section 4 Bridge Notes - helpers that create or manage workspace shape: - helpers that fork or compact Codex threads: - helpers that export context: - helpers that run multi-agent phases: - what needs a pane/thread/layout confirmation: - what another agent would need to resume: ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-functions-practice Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Shell helper implementations and dependency boundaries These examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them. ## Safety and completeness boundaries - `x` explicitly bypasses approvals and sandboxing; `xi` does not. The bypass is a high-trust, separately isolated option, not a prerequisite for loading the environment marker. - `_codex_app_server_fork_latest` and `_codex_app_server_fork_compact_latest` are guard stubs returning 64. A compatible app-server implementation is required before fork/compact helpers can work. - `agent_chain`, `ghost-save`, and `aicm` are lazy-loader shapes, not bundled implementations of those workflows. Check their dependencies instead of treating function presence as proof. - `pksk` and `ksk` are destructive process-cleanup examples. Their broad process matching and process-group signals can stop unrelated work; inspect targets and ownership before adapting them. - Prompt Builder handoff preserves argument boundaries only if the receiving helper also avoids reparsing the prompt as shell code. ## zsh/functions/codex-launch-and-prompt-builder.zsh ```zsh # Focused Codex + Prompt Builder helper snippets. # These are excerpts for workshop discussion, not a full private shell config. unalias x 2>/dev/null x() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox "$@" } xi() { codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@" } _codex_app_server_fork_latest() { echo "_codex_app_server_fork_latest is not bundled in this package." >&2 echo "Install the local Codex app-server helper or replace this guard with a reviewed snippet." >&2 return 64 } _codex_app_server_fork_compact_latest() { echo "_codex_app_server_fork_compact_latest is not bundled in this package." >&2 echo "Install the local Codex app-server compact helper or replace this guard with a reviewed snippet." >&2 return 64 } _codex_cmux_current_session_id() { local helper="$HOME/.codex/hooks/cmux-codex-session-registry.py" [[ -n "${CODEX_FORK_SESSION_ID:-}" ]] && { print -r -- "$CODEX_FORK_SESSION_ID" return 0 } local surface="${CMUX_SURFACE_ID:-}" [[ -n "$surface" && -f "$helper" ]] || return 1 python3 "$helper" --resolve-surface "$surface" --allow-screen 2>/dev/null } _codex_cmux_name_current_tab() { local name="${CODEX_THREAD_NAME:-}" [[ -n "${name//[[:space:]]/}" ]] || return 0 local cmux_bin="${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}" [[ -x "$cmux_bin" ]] || return 0 "$cmux_bin" rename-tab "$name" >/dev/null 2>&1 || true } _codex_prompt_builder_fork() { local fork_from="" local compact=0 local fork_id while (( $# )); do case "$1" in --fork-from) [[ $# -ge 2 ]] || { print -u2 -- "missing value for --fork-from"; return 2; } fork_from="$2" shift 2 ;; --compact) compact=1 shift ;; --) shift break ;; *) break ;; esac done if (( compact )); then if [[ -n "$fork_from" && "$fork_from" != "last" ]]; then fork_id="$(_codex_app_server_fork_compact_latest "$fork_from")" || return 1 else fork_id="$(_codex_app_server_fork_compact_latest)" || return 1 fi else if [[ -n "$fork_from" && "$fork_from" != "last" ]]; then fork_id="$(_codex_app_server_fork_latest "$fork_from")" || return 1 else fork_id="$(_codex_app_server_fork_latest)" || return 1 fi fi print -r -- "$fork_id" _codex_cmux_name_current_tab x resume "$fork_id" "$@" } xfl() { local session_id local fork_id session_id="$(_codex_cmux_current_session_id)" && [[ -n "$session_id" ]] && { fork_id="$(_codex_app_server_fork_latest "$session_id")" || return 1 print -r -- "$fork_id" _codex_cmux_name_current_tab x resume "$fork_id" "$@" return } fork_id="$(_codex_app_server_fork_latest)" || return 1 print -r -- "$fork_id" _codex_cmux_name_current_tab x resume "$fork_id" "$@" } xfc() { local session_id local fork_id session_id="$(_codex_cmux_current_session_id 2>/dev/null)" || session_id="" if [[ -n "$session_id" ]]; then fork_id="$(_codex_app_server_fork_compact_latest "$session_id")" || return 1 else fork_id="$(_codex_app_server_fork_compact_latest)" || return 1 fi print -r -- "$fork_id" _codex_cmux_name_current_tab x resume "$fork_id" "$@" } _p_handoff_zsh() { local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}" shift p \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \ --handoff-arg "$fn" \ "$@" } p-f() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@" } p-c() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@" } p-cm() { _p_handoff_zsh _codex_prompt_builder_fork --fork-from m --compact "$@" } ``` ## zsh/functions/fusion-fix.zsh ```zsh # Fusion-first fixer prompt for terse bug reports. unalias fix 2>/dev/null fix() { local bug="$*" local template_description="Run Fusion on the terse bug, implement the selected fix, and verify it." local system_prompt="You are an expert fixer. The user will provide an extremely terse bug report, broken behavior, failing command, or vague fix request. Treat that terse input as the full task brief and turn it into a concrete repair plan by inspecting the current repository." local developer_prompt="You are launched by the zsh fix helper. The user input may be only a few words. First clarify the likely defect from local repo evidence, then use the \$fusion skill before implementing: consult the local Fusion workflow against the bug, wait for terminal Fusion results and read its final artifacts, reconcile the recommendation with source evidence, then implement the fix. Keep changes scoped to the bug, preserve unrelated user work, run focused verification, and report what changed. Do not skip Fusion unless the bug is impossible to evaluate locally or Fusion itself is unavailable; if Fusion is unavailable, state that and continue with source-backed debugging." if [[ -n "$bug" ]]; then p \ --instructions "$system_prompt" \ --developer-instructions "$developer_prompt" \ --template-label "Fix" \ --template-description "$template_description" \ "$bug" else p \ --instructions "$system_prompt" \ --developer-instructions "$developer_prompt" \ --template-label "Fix" \ --template-description "$template_description" fi } ``` ## zsh/functions/orchestration-helpers.zsh ```zsh # Focused orchestration helper snippets. muxai() { local session="${1:-ai}" local window="${2:-bots}" local -a cmds=(claude gemini copilot codex) command -v tmux >/dev/null 2>&1 || { echo "tmux not found" return 1 } local win_id pane_id win_info if [[ -n "$TMUX" ]]; then win_info=$(tmux new-window -P -F "#{window_id}|#{pane_id}" -n "$window") elif tmux has-session -t "$session" 2>/dev/null; then win_info=$(tmux new-window -t "$session" -P -F "#{window_id}|#{pane_id}" -n "$window") else tmux new-session -d -s "$session" -n "$window" win_info="$(tmux display-message -p -t "$session:$window" "#{window_id}")|$(tmux list-panes -t "$session:$window" -F "#{pane_id}" | head -n1)" fi win_id="${win_info%%|*}" pane_id="${win_info##*|}" tmux set-window-option -t "$win_id" remain-on-exit on >/dev/null tmux send-keys -t "$pane_id" "${cmds[1]}" C-m local current="$pane_id" new_pane i for (( i=2; i<=${#cmds[@]}; i++ )); do if (( i % 2 == 0 )); then new_pane=$(tmux split-window -P -F "#{pane_id}" -t "$current" -h) else new_pane=$(tmux split-window -P -F "#{pane_id}" -t "$current" -v) fi tmux send-keys -t "$new_pane" "${cmds[i]}" C-m current="$new_pane" done tmux select-layout -t "$win_id" tiled >/dev/null [[ -z "$TMUX" ]] && tmux attach -t "$session" } agent_chain() { # Lazy-loader shape only. Keep the full pipeline implementation in the local # zsh source and copy in only the reviewed command surface needed for a demo. unfunction agent_chain 2>/dev/null || true for file in \ "$HOME/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh" \ "$HOME/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh" do [[ -r "$file" ]] && source "$file" done agent_chain "$@" } ghost-save() { unfunction ghost-save 2>/dev/null || true for file in \ "$HOME/.config/zsh/conf.d/38-git-ghost-checkpoint-dsl.zsh" \ "$HOME/.config/zsh/conf.d/39-git-ghost-maintenance-dsl.zsh" do [[ -r "$file" ]] && source "$file" done ghost-save "$@" } aicm() { local file="$HOME/.config/zsh/conf.d/43-ai-commit.zsh" [[ -r "$file" ]] || { echo "Missing $file" >&2 return 1 } source "$file" aicm "$@" } ``` ## zsh/functions/script-kit-process-helpers.zsh ```zsh # Process cleanup helpers mentioned in the zsh helper inventory. pksk() { local pgids pgids=("${(@f)$(ps -axo pgid=,command= | awk ' /\/bin\/bash \.\/dev\.sh/ || /cargo-watch watch .*script-kit-gpui/ { print $1 } ' | sort -u)}") if (( ${#pgids[@]} )); then local pgid for pgid in "${pgids[@]}"; do [[ -n "$pgid" ]] && kill -TERM "-$pgid" 2>/dev/null || true done sleep 0.5 for pgid in "${pgids[@]}"; do [[ -n "$pgid" ]] && kill -KILL "-$pgid" 2>/dev/null || true done fi pkill -9 -f '[s]cript-kit-gpui' 2>/dev/null || true } alias ksk='pkill -9 -f "[s]cript-kit-gpui"' ``` ## zsh/functions/shell-introspection.zsh ```zsh # Zsh function discovery helpers. funclist() { setopt localoptions no_xtrace no_verbose local show_all=false verbose=false pattern="" while [[ $# -gt 0 ]]; do case "$1" in -a|--all) show_all=true; shift ;; -v|--verbose) verbose=true; shift ;; *) pattern="$1"; shift ;; esac done local funcs if $show_all; then funcs=$(print -l ${(k)functions} | sort) else funcs=$(print -l ${(k)functions} | grep -v '^_' | sort) fi [[ -n "$pattern" ]] && funcs=$(echo "$funcs" | grep -i "$pattern") if ! $verbose; then echo "$funcs" return fi local func file line_num while IFS= read -r func; do [[ -z "$func" ]] && continue file="${functions_source[$func]}" if [[ -z "$file" || ! -f "$file" ]]; then printf '\e[1;36m%s\e[0m\n' "$func" continue fi line_num=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(" "$file" 2>/dev/null | cut -d: -f1) printf '\e[1;36m%s\e[0m\n' "$func" [[ -n "$line_num" ]] && printf ' %s:%s\n' "$file" "$line_num" done <<< "$funcs" } funcwhere() { [[ -z "$1" ]] && { echo "Usage: funcwhere <function_name>" return 1 } local func="$1" [[ $(whence -w "$func" 2>/dev/null) != *function* ]] && { echo "'$func' is not a function" >&2 return 1 } local file="${functions_source[$func]}" [[ -z "$file" || ! -f "$file" ]] && { echo "Can't find source file for '$func'" >&2 return 1 } local line line=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(|eval\s+[\"']${func}\s*\(" "$file" | cut -d: -f1) [[ -z "$line" ]] && line=1 echo "$file:$line" } funced() { [[ -z "$1" ]] && { echo "Usage: funced <function_name>" return 1 } local func="$1" [[ $(whence -w "$func" 2>/dev/null) != *function* ]] && { echo "'$func' is not a function" return 1 } local file="${functions_source[$func]}" [[ -z "$file" || ! -f "$file" ]] && { echo "Can't find source file for '$func'" return 1 } local line line=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(|eval\s+[\"']${func}\s*\(" "$file" | cut -d: -f1) [[ -z "$line" ]] && line=1 local editor_cmd="${EDITOR_CMD:-${EDITOR:-vi}}" local editor_name="${editor_cmd:t}" case "$editor_name" in zed) "$editor_cmd" "$file:$line" ;; cursor|code|code-insiders) "$editor_cmd" -g "$file:$line" ;; micro|vim|nvim) "$editor_cmd" "+$line" "$file" ;; *) "$editor_cmd" "$file:$line" ;; esac } ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-helper-files Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Terminal coding agents Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Terminal coding agents **John uses:** [pi](https://github.com/earendil-works/pi) (71.9k, MIT) as his primary agent — an AI agent toolkit with a unified LLM API, agent loop, TUI, and an extension system (section 01's `pi-session-id` is a pi extension; section 06's swarms use pi's subagent tool). He runs [Codex CLI](https://github.com/openai/codex) (99k, Apache-2.0), [Claude Code](https://github.com/anthropics/claude-code) (138k), and Grok side by side behind two-letter zsh wrappers (section 02) — the whole point of that section is that the wrapper pattern is agent-agnostic. | Alternative | What it is | How it differs | License | |----|----|----|----| | [OpenCode](https://github.com/anomalyco/opencode) | Open-source terminal coding agent, provider-agnostic (any model) | Community-run and model-agnostic where pi/Codex/Claude Code are single-author or lab-tied; largest OSS coding agent by stars | MIT | | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google's open-source terminal agent for Gemini models | Free tier with a Google account; the Gemini-lab counterpart to Codex/Claude Code | Apache-2.0 | | [Goose](https://github.com/aaif-goose/goose) | Extensible AI agent (Block) that installs, executes, edits, and tests with any LLM | Extension/MCP-first architecture; works with any LLM rather than one vendor | Apache-2.0 | | [Aider](https://github.com/Aider-AI/aider) | AI pair programming in your terminal; git-native diff/commit workflow | Pair-programming/chat-over-git model rather than an autonomous agent loop; slower release cadence lately (check repository activity before adoption) | Apache-2.0 | | [Crush](https://github.com/charmbracelet/crush) | Charm's glamorous terminal coding agent (successor to OpenCode's original TUI) | Strongest TUI polish; multi-provider; source-available license (FSL-family, SPDX NOASSERTION) | NOASSERTION | | [OpenHands](https://github.com/OpenHands/OpenHands) | AI-driven development platform (formerly OpenDevin) with CLI, GUI, and cloud runtimes | Heavier platform (sandboxed runtimes, web UI) vs a single terminal binary | NOASSERTION | | [Grok Build (official)](https://x.ai/cli) / [superagent-ai grok-cli (OSS)](https://github.com/superagent-ai/grok-cli) | xAI's official terminal coding agent (subscription); an OSS coding agent for the Grok API | Grok Build is subscription-gated (SuperGrok/X Premium+) with plan mode and 8 parallel subagents; the superagent-ai CLI is MIT OSS against the Grok API | MIT (OSS one); Grok Build is proprietary | ### Pick this if… - **OpenCode** — you want one agent that isn't tied to any lab and takes any model/provider. - **Gemini CLI** — you want a capable agent on a free tier with just a Google account. - **OpenHands** — you want sandboxed/cloud execution and a web UI, not just a terminal. - **Goose** — your leverage is custom extensions/MCP tools rather than the agent loop itself. - **Aider** — you want a human-in-the-loop pair programmer with clean git commits, not autonomy. - **Crush** — you live in the terminal and want the nicest TUI (mind the source-available license). - **Grok Build / grok-cli** — you're already paying for SuperGrok / have Grok API credits. Reference ID: factory-tools-coding-agents Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#coding-agents) --- # Terminal emulators Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Terminal emulators **John uses:** [Ghostty](https://github.com/ghostty-org/ghostty) (58.3k, MIT) — fast, GPU-accelerated, platform-native. In the stack it's deliberately just the pixel layer; Karabiner scopes its Esc-hold chord layer to the Ghostty app, and Herdr runs inside it. | Alternative | What it is | How it differs | License | |----|----|----|----| | [WezTerm](https://github.com/wezterm/wezterm) | GPU-accelerated cross-platform terminal emulator AND multiplexer in Rust, Lua-configurable | Built-in multiplexing could replace part of the herdr layer too; deep Lua scripting | NOASSERTION (MIT per repo) | | [kitty](https://github.com/kovidgoyal/kitty) | Fast, feature-rich GPU-based terminal with 'kittens' extensions and remote control protocol | Scriptable remote-control protocol (kitty @) is a viable pane-automation substrate | GPL-3.0 | | [Alacritty](https://github.com/alacritty/alacritty) | Minimal, very fast OpenGL terminal emulator | No tabs/splits by design — pair with tmux/zellij/herdr | Apache-2.0 | | [iTerm2](https://github.com/gnachman/iTerm2) | The long-standing macOS power-user terminal (Python scripting API, triggers, tmux integration) | macOS-only; slower rendering than the GPU generation but deepest macOS integration | GPL-2.0 | ### Pick this if… - **WezTerm** — you want emulator + multiplexer in one binary (can absorb part of the herdr layer). - **kitty** — you want a scriptable terminal (`kitty @` remote control is a pane-automation substrate). - **Alacritty** — you want maximum speed and will pair it with tmux/zellij/herdr anyway. - **iTerm2** — you want the deepest macOS integration and don't care about raw render speed. Reference ID: factory-tools-terminal-emulators Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#terminal-emulators) --- # Terminal workspace / agent multiplexers Tool roles, alternatives, selection tradeoffs, and compatibility caveats. ## Terminal workspace / agent multiplexers **John uses:** [Herdr](https://herdr.dev/) ([ogulcancelik/herdr](https://github.com/ogulcancelik/herdr), 17.3k, AGPL-3.0) — "tmux for agents": panes plus an agent-state sidebar (blocked/working/done/idle auto-detected for 15+ agents), detach/reattach, and — the part section 06 is built on — a unix-socket API that agents themselves can drive: spawn panes, read sibling output, wait on each other. That socket is what makes the keeper prompt ("keep other panes alive") and planned swarms one-keystroke moves. | Alternative | What it is | How it differs | License | |----|----|----|----| | [tmux](https://github.com/tmux/tmux) | The standard terminal multiplexer | No agent-state awareness or agent API; fully scriptable via send-keys/capture-pane so you can hand-roll herdr-like patterns | ISC | | [Zellij](https://github.com/zellij-org/zellij) | Terminal workspace with batteries included (layouts, plugins in WASM) | Friendlier defaults and a plugin system, but agent-agnostic — no built-in agent status model | MIT | | [claude-squad](https://github.com/smtg-ai/claude-squad) | Manage multiple AI terminal agents (Claude Code, Codex, OpenCode, Amp) in one TUI | Purpose-built agent manager like herdr, backed by tmux + git worktrees; narrower pane model | AGPL-3.0 | | [Vibe Kanban](https://github.com/BloopAI/vibe-kanban) | Kanban web UI for orchestrating multiple coding-agent tasks | Board-of-tasks metaphor instead of terminal panes; good for reviewing parallel agent work; check current repository activity | Apache-2.0 | | [hcom](https://github.com/aannoo/hcom) | Lets AI agents message, watch, and spawn each other across terminals (Claude Code, Codex, Antigravity, Pi, ...) | Agent-to-agent communication layer without owning your terminal layout; closest OSS match to herdr's socket API idea | MIT | | [Omnara](https://github.com/omnara-ai/omnara) | Talk to your AI agents from anywhere (mobile/web control plane, YC S25) | Remote monitoring/answering of agents rather than local pane management; check current repository activity | Apache-2.0 | ### Pick this if… - **tmux** — you want the zero-risk default; `send-keys`/`capture-pane` let you hand-roll herdr's socket tricks. - **Zellij** — you want modern ergonomics and a plugin system without agent-specific features. - **claude-squad** — you specifically want "many agents, one dashboard" with worktree isolation. - **Vibe Kanban** — you'd rather review parallel agent work as a board than as panes (note: quieter repo lately). - **hcom** — you want the agent-to-agent messaging half of herdr as a small composable tool. - **Omnara** — your bottleneck is being away from the keyboard, not pane management. Reference ID: factory-tools-agent-workspace-managers Topic: Tools Sources: - [Tool comparison reference](https://dewy-sleet-n5zs.here.now/#agent-workspace-managers) --- # Thin zsh launchers and composable command families Wrap repeated flags, isolate account credentials, compose session helpers, and make launch behavior inspectable. ## Related working material - [Thin zsh launchers and composable command families — prompts and exercises](/topics/factory-zsh-launchers-practice/) - [Thin zsh launchers and composable command families — questions and tradeoffs](/topics/factory-zsh-launchers-questions/) - [Thin zsh launchers and composable command families — worked example](/topics/factory-zsh-launchers-worked-example/) ## TL;DR - One working set of dotfiles runs Codex, Claude Code, and pi behind two-letter functions — launch, resume, fork, and second accounts each cost two or three keystrokes. - You leave with four drop-in wrapper files (Codex, Claude Code, pi, and the full `pir` family) plus prompts that make your own agent build the next family for you. - The one move: **wrap → compose → cheat-sheet → verify with `zsh -n`**. It took five minutes to build the whole pi family live. Have your agent set this up — paste this into it: ``` text Fetch https://sacred-ritual-w7as.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result. ``` ## What launching an agent actually costs You start a coding agent many times a day, and each launch needs the same environment variable, the same config override, and the same sandbox flag. Leaning on shell history means sometimes launching with a flag missing — which is worse than a failed launch, because the agent starts in a different permission posture than you expect. This is the raw Codex invocation behind the presenter's daily driver: ``` text CODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox ``` Nobody types that twice. The dotfiles reduce it to one letter, and hang the whole session vocabulary off that letter. This is the real wrapper plus its resume/fork family, drop-in ready: ``` text # codex.zsh — Codex behind one letter, sessions behind two. # Placeholders (comments only — nothing below needs editing): # <personal-account> = the login that owns ~/.codex # Safety trade: --dangerously-bypass-approvals-and-sandbox removes approval # prompts. Keep it only if you accept unattended file and shell access. unalias x 2>/dev/null x() { # Default account: <personal-account> via ~/.codex CODEX_HOME="${CODEX_PRIMARY_HOME:-$HOME/.codex}" \ codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox "$@" } # The resume/fork family: every helper routes through x, so a future fix # to x fixes the whole family for free. unalias xr xrl xrm xf 2>/dev/null xr() { x resume "$@"; } # pick a session to resume xrl() { x resume --last "$@"; } # jump into the most recent session xrm() { x resume m "$@"; } # resume the session named "m" xf() { x fork "$@"; } # fork: xf <id|name> [prompt] ``` ## Why functions, not aliases An alias substitutes text. It cannot take a positional argument in the middle, cannot run setup logic, and loses quietly when a plugin defines the same name — oh-my-zsh ships single-letter aliases that would shadow these helpers, which is why every definition starts with `unalias <name> 2>/dev/null`. The same wrapper shape repeats across a second agent: ``` text # claude.zsh — same pattern, different agent. # Placeholders (comments only — nothing below needs editing): # <work-account> = the login that owns ~/.claude-second # Safety trade: --dangerously-skip-permissions removes permission prompts. unalias clx clx2 clxw 2>/dev/null clx() { claude --dangerously-skip-permissions "$@"; } clx2() { # second account (<work-account>) — same UX, separate config dir local config_dir="${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}" mkdir -p "$config_dir" || return CLAUDE_CONFIG_DIR="$config_dir" claude --dangerously-skip-permissions "$@" } clxw() { # launch inside a named worktree: clxw <name> [args] local name="$1"; shift CLAUDE_WORKTREE_NAME="$name" claude --worktree "$name" --dangerously-skip-permissions "$@" } ``` Functions also absorb upstream bugs. pi's lockfile dependency expects a directory at `auth.json.lock`; a stray regular file there causes recurring auth failures. The wrapper heals it on every launch, so the bug lives in one function instead of in your memory: ``` text # pi.zsh — wrappers absorb upstream bugs so you don't have to remember them. # pi's proper-lockfile dependency expects a directory at auth.json.lock; a # stray regular file there causes recurring ENOTDIR auth failures. unalias pi 2>/dev/null pi() { local agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" local auth_lock="$agent_dir/auth.json.lock" if [[ -f "$auth_lock" && ! -L "$auth_lock" ]]; then rm -f -- "$auth_lock" fi command pi "$@" } ``` ## Families compound: resume, fork, and second accounts A single wrapper saves keystrokes; the payoff compounds when wrappers call wrappers. Since `x` owns the account and the flags, every session action is a one-line composition on top of it. The deepest member of the family forks a session, compacts the fork, and resumes it — still routed through `x`: ``` text xfmc() { # fork session "m" → compact the fork → resume it local fork_id fork_id="$(_codex_app_server_fork_compact_latest m)" || return 1 print -r -- "$fork_id" _codex_cmux_name_current_tab x resume "$fork_id" "$@" } # the two _codex_* helpers live elsewhere in the dotfiles — shown for shape, not for pasting ``` Second accounts work the same way: `x2` points `CODEX_HOME` at `~/.codex-work`, a directory built by a helper that symlinks every top-level entry of the primary home *except* auth files, and refuses to run if an auth file ever becomes a symlink. Accounts share sessions and config, never credentials. A family this large needs a memory aid, so it prints its own: running `x-` lists every helper, straight from the file that defines them. ``` text $ x- x Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker. x2 Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only. xr Resume a Codex session through the base x wrapper. xrl Resume the most recent Codex session through the base x wrapper. xf Run x fork; pass the conversation id/name first, then the prompt. xfmc Fork conversation m, compact the fork, then resume it interactively. p-f Compose a prompt in p, then fork using the prompt-builder --fork-from toggle. # … full listing covers 35 helpers ``` ## The prompt builder picks the agent last Wrappers fix the launch, but not a subtler mistake: deciding which agent to use before you have written the prompt. The `p` command — a separate terminal program, "Terminal prompt builder for handing prompts to Pi, Codex, or Claude Code" — inverts the order. Compose the prompt first, then send it to any configured target: one prompt can go to any of three agents across five accounts. Helpers like `p-f` and `p-c` close the loop by handing the finished prompt back to the zsh fork/resume functions. ``` text $ p target list pi pi bin=pi codex codex bin=codex config=shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1" claude claude bin=claude work-profile codex bin=codex CODEX_HOME=~/.codex-work config=cli_auth_credentials_store="file" … claude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second claude-third claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third ``` You can rehearse without launching anything: `p --print-prompt "explain this repo"` prints the composed prompt and exits. ## The recipe, proved on pi The claim that this repeats "in minutes" is testable, and the workshop tests it live. pi had a base wrapper but no session helpers. Step one is always the same — ask the CLI what it can do instead of guessing: ``` text $ pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session" --continue, -c Continue previous session --resume, -r Select a session to resume --fork <path|id> Fork specific session file or partial UUID into a new session --name, -n <name> Set session display name --no-session Don't save session (ephemeral) ``` Each flag becomes one short function, the family gets a `pi-` cheat sheet in the `x-` style, and the whole file verifies with `zsh -n` plus a stub test before it ever touches a real shell. The finished file is printed complete in the [agent guide above](https://sacred-ritual-w7as.here.now/#agent-guide) — five helpers and a cheat sheet, built in about five minutes. The recipe: **wrap** the flags you can't remember, **compose** wrappers into families, **document** with a `fn-` help function, **repeat** for every new agent CLI. ## Appendix ### Limits & caveats - **Safety trade:** `--dangerously-bypass-approvals-and-sandbox` (Codex) and `--dangerously-skip-permissions` (Claude Code) remove approval prompts. The wrappers make that posture deliberate and visible in one place, but they do not make it safe. Do not copy those flags unless you accept unattended file and shell access. - **Drift risk:** composed families inherit fixes but also breakage. When the underlying CLI renames a subcommand or flag, every wrapper above it fails at once. The cheat-sheet function lowers the cost of the audit; it does not remove the need for one. - **Stub tests prove wiring, not behavior:** the success check proves each helper passes the intended flags. A live `pir` only opens a session picker when pi has saved sessions on that machine. - **"Five minutes" is the presenter's estimate** for the live walkthrough, not a measurement. - **One machine's configuration:** all evidence comes from one working set of dotfiles, version-specific snapshot. Treat specific flags as examples, not standards. The `p` target list is one machine's config file, not a tool default. No comparison was made with shell-history tools or command launchers. - **Version pinning:** pi flags were captured from pi v0.80.10; re-run `--help` against your version. Reference ID: factory-zsh-launchers Topic: Tools Sources: - [Thin zsh launchers and composable command families](https://sacred-ritual-w7as.here.now/) --- # Thin zsh launchers and composable command families — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for thin zsh launchers and composable command families. ## Quick start Sixty seconds, zero installs: build a wrapper family in a temp dir and prove it passes the right flags with a stub. ``` text cd "$(mktemp -d)" printf '%s\n' 'pir() { pi --resume "$@"; }' 'pic() { pi --continue "$@"; }' \ 'pi-() { printf "pir resume\npic continue\n"; }' > pi-utils.zsh zsh -n pi-utils.zsh && echo "syntax OK" zsh -fc 'pi() { echo "[stub pi] $@"; }; source pi-utils.zsh; pi-; pir --check' ``` ## Prompt library Paste these into your own coding agent. Each one applies the recipe without you memorizing it. ### Build a wrapper family for a CLI - Agent: any coding agent - Working directory: anywhere - Expected result: ~/.zsh-wrappers/pi-utils.zsh + passing stub test ``` text Build me a two-letter zsh wrapper family for the pi CLI. 1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session. 2. Create ~/.zsh-wrappers/pi-utils.zsh. For each flag define a short function that calls `pi <flag> "$@"`: pir (resume), pic (continue), pif (fork), pin (named session — take the name as $1, error if it is missing), pit (no-session). Guard every definition with `unalias <name> 2>/dev/null`. 3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description. 4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test: zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check' Expect: [stub pi] --resume --check 5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself. ``` ### Mine your shell history for wrapper candidates - Agent: any coding agent - Working directory: anywhere - Expected result: a ranked top-5 list + one proposed wrapper file to review ``` text Read my shell history (~/.zsh_history, or `fc -l 1` output I paste) and find the commands I retype most. Group near-identical long commands (same binary, same flags), rank the top 5 by length times repeat count, and for each one propose a two-letter zsh wrapper function: `unalias` guard first, environment pinning inside the function, `"$@"` pass-through at the end. Print all proposed functions in one file for me to review. Do not install or source anything yet. ``` ### Add a second account to an existing wrapper - Agent: any coding agent - Working directory: anywhere - Expected result: a \<name\>2 wrapper + an auth-isolated second home dir ``` text I have a zsh wrapper function for an agent CLI and I want a second account with the same UX. Create a `<name>2` wrapper that launches the same CLI with its config env var (CODEX_HOME for codex, CLAUDE_CONFIG_DIR for claude) pointed at a second directory such as ~/.<cli>-second. Rules: create the directory if it is missing; if the tool benefits from shared state, symlink top-level entries from the primary home EXCEPT auth files (auth.json and similar) — auth stays local, never symlinked or copied; refuse to proceed if an auth file would end up shared or would become a symlink. Show me the wrapper and the ensure-home helper before running anything. ``` ### Audit wrappers for flag drift after a CLI update - Agent: any coding agent - Working directory: anywhere - Expected result: a drift report + patched wrapper files with before/after diff ``` text My agent CLI just updated. Audit my wrapper functions for flag drift: (1) list every function in ~/.zsh-wrappers/*.zsh and the flags each one passes; (2) run `--help` for each wrapped binary and check that every flag still exists with the same meaning; (3) report renamed or removed flags and patch only the affected functions; (4) re-verify each patched file with `zsh -n` and a stub test that echoes the flags. Show me a before/after diff of every change. ``` ## Set it up (agent guide) 1. Create `~/.zsh-wrappers/pi-utils.zsh` with exactly this content — the complete file from the live walkthrough: ``` text # pi-utils.zsh — the "pir" walkthrough result # Built live at the workshop following the same recipe as the x/xr family. # Source it: source ~/.zsh-wrappers/pi-utils.zsh then run: pi- # Recipe step 0 — the base wrapper already exists in the dotfiles # (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real # pi binary. Every helper below composes on top of `pi`, never the raw binary. # Recipe step 1 — read the CLI's own session flags: # pi --help | grep -E "resume|continue|fork|name" # --continue, -c Continue previous session # --resume, -r Select a session to resume # --fork <path|id> Fork a session into a new session # --name, -n Set session display name # Recipe step 2 — wrap each flag as a two/three-letter function. unalias pir 2>/dev/null pir() { pi --resume "$@"; } # pick a session to resume (pi resume) unalias pic 2>/dev/null pic() { pi --continue "$@"; } # continue the most recent session unalias pif 2>/dev/null pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt] unalias pin 2>/dev/null pin() { # start a named session: pin <name> [prompt] local name="${1:?Usage: pin <name> [prompt...]}"; shift pi --name "$name" "$@" } unalias pit 2>/dev/null pit() { pi --no-session "$@"; } # throwaway session (nothing saved) # Recipe step 3 — every family ships its own cheat sheet (the x- convention). pi-() { local -a fn_name=(pi pir pic pif pin pit) local -A fn_desc=( pi 'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.' pir 'Resume: open the session picker (pi --resume).' pic 'Continue: jump straight back into the last session (pi --continue).' pif 'Fork a session into a new one: pif <path|id> [prompt].' pin 'Start a named session: pin <name> [prompt].' pit 'Throwaway: run without saving a session (pi --no-session).' ) local fn for fn in "${fn_name[@]}"; do printf '%-4s %s\n' "$fn" "${fn_desc[$fn]}" done } ``` 2. Wire it into your shell: ``` text mkdir -p ~/.zsh-wrappers # save the file above as ~/.zsh-wrappers/pi-utils.zsh, then: echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc exec zsh ``` **Success check:** syntax first, then a stub test that proves every helper passes the intended flags — without launching anything. ``` text zsh -n ~/.zsh-wrappers/pi-utils.zsh && echo "syntax OK" zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check' ``` ``` text syntax OK pi Base wrapper: heals the auth.json.lock bug, then runs the pi binary. pir Resume: open the session picker (pi --resume). pic Continue: jump straight back into the last session (pi --continue). pif Fork a session into a new one: pif <path|id> [prompt]. pin Start a named session: pin <name> [prompt]. pit Throwaway: run without saving a session (pi --no-session). [stub pi] --resume --check ``` ## Attachments — take it home Both wrapper files discussed on this page ship with the site as downloadable attachments: [agent-launchers.zsh](https://sacred-ritual-w7as.here.now/agent-launchers.zsh) (the `x`/`xr`/`x2`, `clx`, and `p-f`/`p-c` families, curated from the presenter's dotfiles with account details generalized) and [pi-utils.zsh](https://sacred-ritual-w7as.here.now/pi-utils.zsh) (the complete `pir` walkthrough result). One block installs both: ``` text mkdir -p ~/.zsh-wrappers curl -fsSL https://sacred-ritual-w7as.here.now/agent-launchers.zsh -o ~/.zsh-wrappers/agent-launchers.zsh curl -fsSL https://sacred-ritual-w7as.here.now/pi-utils.zsh -o ~/.zsh-wrappers/pi-utils.zsh echo 'source ~/.zsh-wrappers/agent-launchers.zsh' >> ~/.zshrc echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc ``` Read both files before sourcing them — the Codex and Claude wrappers carry the bypass/skip-permission flags discussed in the appendix. Open a new shell, then run `x-` and `pi-` to print the cheat sheets. ## Complete reusable setup contract ## Two-Letter Commands — agent setup guide Following this file sets up: a two-letter zsh wrapper family for a CLI your user runs often — base wrapper, resume/continue/fork helpers, a self-printing cheat sheet — verified with `zsh -n` and a stub test before it touches their shell config. Human companion pages on this site (context for your user, not required for setup): `index.html` (the section guide), `replay.html` (Session Replay — the walkthrough as an annotated transcript), `dialogue.html` (Socratic Dialogue — attendee questions driving the same material). ## Attachments (machine-fetchable) Both wrapper files ship with this site as plain-text attachments you can fetch directly: - `https://sacred-ritual-w7as.here.now/pi-utils.zsh` — the complete pi wrapper family built in step 2 below (identical content; the file's "Source it" comment says `demo/pi-utils.zsh` because it is the verbatim workshop walkthrough result — install it at `~/.zsh-wrappers/pi-utils.zsh` regardless). - `https://sacred-ritual-w7as.here.now/agent-launchers.zsh` — the presenter's curated launcher families (`x`/`xr`/`xrl`/`xrm`, `x2`, `clx`/`clx2`/`clxw`, `p-f`/`p-c`, and the `x-` cheat sheet), account details generalized. NOTE: it carries `--dangerously-bypass-approvals-and-sandbox` and `--dangerously-skip-permissions` — show it to your user and get explicit approval before sourcing it. Fetching `pi-utils.zsh` and installing it at `$HOME/.zsh-wrappers/pi-utils.zsh` is an acceptable substitute for writing the file in step 2, as long as you still run the verification in step 3. Placeholders used below: `<cli>` = the target CLI's command name (the worked example uses `pi`); `<w>` = the family's short prefix (for `pi` the prefix is `pi`, giving `pir`, `pic`, `pif`, `pin`, `pit`). All other paths are literal. ## Prerequisites Check each before starting: ```bash zsh --version command -v pi || echo "pi not installed" ``` Expected: zsh 5.x or newer. If `pi` is not installed, do NOT stop — pick the agent CLI your user actually runs (check `command -v codex`, `command -v claude`, or ask), use it as `<cli>`, and adapt the flag names in step 1. If no target CLI exists at all, stop and tell your user what to install. ## Steps 1. Capture the CLI's own session flags — never guess them: ```bash pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session" ``` Expected for pi (v0.80.10): `--resume/-r` (pick a session), `--continue/-c` (last session), `--fork <path|id>`, `--name/-n <name>`, `--no-session` (ephemeral). For a different `<cli>`, run `<cli> --help` and map its equivalents; wrap only flags that actually exist. 2. Create `$HOME/.zsh-wrappers/pi-utils.zsh` with exactly this content (for a different `<cli>`, keep the identical shape — `unalias` guard before every definition, each helper one short function calling `<cli>` with one flag plus `"$@"`, and a `<w>-` cheat-sheet function last): ```zsh # pi-utils.zsh — the "pir" walkthrough result # Built live at the workshop following the same recipe as the x/xr family. # Source it: source ~/.zsh-wrappers/pi-utils.zsh then run: pi- # Recipe step 0 — the base wrapper already exists in the dotfiles # (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real # pi binary. Every helper below composes on top of `pi`, never the raw binary. # Recipe step 1 — read the CLI's own session flags: # pi --help | grep -E "resume|continue|fork|name" # --continue, -c Continue previous session # --resume, -r Select a session to resume # --fork <path|id> Fork a session into a new session # --name, -n Set session display name # Recipe step 2 — wrap each flag as a two/three-letter function. unalias pir 2>/dev/null pir() { pi --resume "$@"; } # pick a session to resume (pi resume) unalias pic 2>/dev/null pic() { pi --continue "$@"; } # continue the most recent session unalias pif 2>/dev/null pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt] unalias pin 2>/dev/null pin() { # start a named session: pin <name> [prompt] local name="${1:?Usage: pin <name> [prompt...]}"; shift pi --name "$name" "$@" } unalias pit 2>/dev/null pit() { pi --no-session "$@"; } # throwaway session (nothing saved) # Recipe step 3 — every family ships its own cheat sheet (the x- convention). pi-() { local -a fn_name=(pi pir pic pif pin pit) local -A fn_desc=( pi 'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.' pir 'Resume: open the session picker (pi --resume).' pic 'Continue: jump straight back into the last session (pi --continue).' pif 'Fork a session into a new one: pif <path|id> [prompt].' pin 'Start a named session: pin <name> [prompt].' pit 'Throwaway: run without saving a session (pi --no-session).' ) local fn for fn in "${fn_name[@]}"; do printf '%-4s %s\n' "$fn" "${fn_desc[$fn]}" done } ``` Create the directory first: ```bash mkdir -p "$HOME/.zsh-wrappers" ``` 3. Verify BEFORE touching the user's shell config — syntax check, then a stub test that shadows `<cli>` with a function so nothing real launches: ```bash zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK" zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pir --check' ``` 4. Wire it into the shell. Ask your user before editing `~/.zshrc` if your policy requires it; otherwise append: ```bash grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' "$HOME/.zshrc" || \ echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> "$HOME/.zshrc" ``` ## Success check Run: ```bash zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK" zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pi-; pir --check' ``` Expected observable result: ``` syntax OK pi Base wrapper: heals the auth.json.lock bug, then runs the pi binary. pir Resume: open the session picker (pi --resume). pic Continue: jump straight back into the last session (pi --continue). pif Fork a session into a new one: pif <path|id> [prompt]. pin Start a named session: pin <name> [prompt]. pit Throwaway: run without saving a session (pi --no-session). [stub pi] --resume --check ``` The last line proves the helper passes the intended flag. In a fresh interactive shell, `pi-` prints the cheat sheet and `pir` opens pi's session picker (only if saved sessions exist on this machine). Report to your user: which CLI you wrapped, the file you created, the success-check output, and anything you adapted. ## Notes for agents - **Alias collisions:** oh-my-zsh and other frameworks ship one- and two-letter aliases. Without the `unalias <name> 2>/dev/null` guard before each definition, the alias silently wins. Keep the guards even if they look redundant. - **Never add permission-bypass flags** (`--dangerously-bypass-approvals-and-sandbox`, `--dangerously-skip-permissions`) to a wrapper unless your user explicitly asks. They trade safety for speed. - **Helpers must call the command name, not an absolute path** (`pi --resume "$@"`, not `/some/path/pi`). That is what makes the stub test work and lets a future base-wrapper fix (like pi's `auth.json.lock` heal) apply to the whole family. - **Flag drift:** when the CLI updates, wrappers can break all at once. Re-run `<cli> --help` and patch only the function that owns the changed flag, then re-run the success check. - **pi-specific:** pi's lockfile dependency expects a directory at `~/.pi/agent/auth.json.lock`. If a stray regular (non-symlink) file appears there, pi fails auth with ENOTDIR errors; delete that file (a base `pi()` wrapper can do it before every launch). ## Complete launcher-family attachment Review the permission-bypass posture and account-isolation guards before sourcing. These are examples, not a recommendation to disable approvals. ```zsh # agent-launchers.zsh — the agent-launcher function families from the workshop. # Curated from the presenter's dotfiles for "Agentic Software Factory" # (the recorded snapshot), section 02: Custom zsh Functions. Adapt paths to your setup. # Companion page: https://sacred-ritual-w7as.here.now/ # # Placeholders (comments only — nothing below needs editing to run): # <personal-account> = the login that owns ~/.codex # <work-account> = the login that owns the second-account dirs # Lines that differ from the private originals carry an "ADAPTED:" comment. # # Safety trade (deliberate, visible, yours to reject): # --dangerously-bypass-approvals-and-sandbox (Codex) and # --dangerously-skip-permissions (Claude Code) remove approval prompts. # Delete those flags if you do not accept unattended file and shell access. # ============================================================ Codex: the x family : "${CODEX_PRIMARY_HOME:=$HOME/.codex}" # ADAPTED: name the second home whatever fits your second account, e.g. ~/.codex-work : "${CODEX_SECOND_HOME:=$HOME/.codex-work}" # Names that must never be shared between accounts (auth / login only). # Everything else under the primary home is eligible for a symlink into x2. _codex_auth_local_basenames() { case "$1" in auth.json|auth.json.*|*.auth.json) return 0 ;; codex-login.log|codex-login*.log) return 0 ;; esac return 1 } # Build/refresh the second home as a shared view of ~/.codex, minus auth. # Safety rules: # - never write into CODEX_PRIMARY_HOME # - never replace a real (non-symlink) file/dir in the second home # - if auth.json is accidentally a symlink into primary, remove only that symlink # - only create/repair symlinks we manage (existing real files stay put) _codex_egghead_ensure_home() { emulate -L zsh setopt null_glob extended_glob local primary="${CODEX_PRIMARY_HOME:-$HOME/.codex}" local secondary="${CODEX_SECOND_HOME:-$HOME/.codex-work}" local src base dest rel current if [[ ! -d "$primary" ]]; then print -u2 -- "codex primary home missing: $primary" return 1 fi # Refuse pathological layouts. if [[ "$secondary" == "$primary" || "$secondary" == "$primary"/* ]]; then print -u2 -- "refusing second home inside primary: $secondary" return 1 fi mkdir -p "$secondary" || return 1 # If a previous setup linked auth into the primary account, break that only. dest="$secondary/auth.json" if [[ -L "$dest" ]]; then current="$(readlink "$dest" 2>/dev/null || true)" case "$current" in "$primary/auth.json"|"$primary"/auth.json) rm -f "$dest" || return 1 ;; esac fi # Symlink top-level primary entries except auth-local basenames. for src in "$primary"/* "$primary"/.[!.]* "$primary"/..?*; do [[ -e "$src" || -L "$src" ]] || continue base="${src:t}" [[ "$base" == "." || "$base" == ".." ]] && continue _codex_auth_local_basenames "$base" && continue dest="$secondary/$base" if [[ -L "$dest" ]]; then current="$(readlink "$dest" 2>/dev/null || true)" if [[ "$current" != "$src" ]]; then # Only retarget an existing symlink; never touch real files. ln -sfn "$src" "$dest" || return 1 fi continue fi if [[ -e "$dest" ]]; then # Real file/dir already present in the second home — leave it alone. continue fi ln -s "$src" "$dest" || return 1 done # Keep login diagnostics local even if parent `log` is shared. # When primary/log is a real directory and we symlinked it, login would # write into primary. Prefer a local log dir with non-auth log files linked. if [[ -d "$primary/log" && ! -L "$primary/log" ]]; then if [[ -L "$secondary/log" ]]; then rm -f "$secondary/log" || return 1 fi mkdir -p "$secondary/log" || return 1 for src in "$primary/log"/*(N) "$primary/log"/.[!.]*(N); do [[ -e "$src" || -L "$src" ]] || continue base="${src:t}" [[ "$base" == "." || "$base" == ".." ]] && continue _codex_auth_local_basenames "$base" && continue dest="$secondary/log/$base" if [[ -L "$dest" ]]; then current="$(readlink "$dest" 2>/dev/null || true)" [[ "$current" == "$src" ]] && continue ln -sfn "$src" "$dest" || return 1 continue fi [[ -e "$dest" ]] && continue ln -s "$src" "$dest" || return 1 done fi # Ensure auth.json is never a symlink after ensure. if [[ -L "$secondary/auth.json" ]]; then print -u2 -- "refusing to use symlinked auth.json in $secondary" return 1 fi return 0 } unalias x 2>/dev/null x() { # Default account: <personal-account> via ~/.codex (ADAPTED: email -> placeholder) CODEX_HOME="${CODEX_PRIMARY_HOME:-$HOME/.codex}" \ codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox "$@" } unalias x2 2>/dev/null x2() { # Secondary account: <work-account> via ~/.codex-work (ADAPTED: email -> placeholder) # Shared config/skills/sessions/etc via symlinks; local auth.json only. _codex_egghead_ensure_home || return 1 CODEX_HOME="${CODEX_SECOND_HOME:-$HOME/.codex-work}" \ codex \ -c 'cli_auth_credentials_store="file"' \ -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox "$@" } # The resume family: every helper routes through x, so a future fix # to x fixes the whole family for free. unalias xr 2>/dev/null xr() { x resume "$@"; } # pick a session to resume unalias xrl 2>/dev/null xrl() { x resume --last "$@"; } # jump into the most recent session unalias xrm 2>/dev/null xrm() { x resume m "$@"; } # resume the session named "m" — rename to your favorite # ====================================================== Claude Code: the clx family unalias clx clx2 clxw 2>/dev/null clx() { claude --dangerously-skip-permissions "$@"; } clx2() { # second account (<work-account>) — same UX, separate config dir local config_dir="${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}" mkdir -p "$config_dir" || return CLAUDE_CONFIG_DIR="$config_dir" claude --dangerously-skip-permissions "$@" } clxw() { # launch inside a named worktree: clxw <name> [args] local name="$1"; shift CLAUDE_WORKTREE_NAME="$name" claude --worktree "$name" --dangerously-skip-permissions "$@" } # ============================================ Prompt-builder handoff: p-f and p-c # Requires the `p` prompt-builder CLI. Compose the prompt first; the handoff # hands the finished prompt to a zsh function that forks and resumes a session. _p_handoff_zsh() { local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}" shift p \ --handoff-command zsh \ --handoff-arg -lc \ --handoff-arg "source \"\$HOME/.zsh-wrappers/agent-launchers.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \ --handoff-arg "$fn" \ "$@" # ADAPTED: sources this installed file; the original sources the presenter's # full dotfiles module instead. } _codex_prompt_builder_fork() { # ADAPTED: the private original forks through the presenter's app-server # helpers, which can also compact the fork before resuming; that machinery # is not portable. This version uses codex's built-in fork. --compact is # accepted for interface compatibility but performs a plain fork. local fork_from="last" while (( $# )); do case "$1" in --fork-from) [[ $# -ge 2 ]] || { print -u2 -- "missing value for --fork-from"; return 2; } fork_from="$2" shift 2 ;; --compact) shift ;; --) shift break ;; *) break ;; esac done if [[ -z "$fork_from" || "$fork_from" == "last" ]]; then x fork --last "$@" else x fork "$fork_from" "$@" fi } p-f() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@" } p-c() { local source="${CODEX_FORK_SESSION_ID:-last}" _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@" } # ==================================== The cheat sheet: every family documents itself x-() { # ADAPTED: lists only the functions in this curated file; the private # original covers ~35 helpers. local -a fn_name=(x x2 xr xrl xrm clx clx2 clxw p-f p-c) local -A fn_desc=( x 'Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.' x2 'Second-account Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.' xr 'Resume a Codex session through the base x wrapper.' xrl 'Resume the most recent Codex session through the base x wrapper.' xrm 'Resume the Codex conversation named m through the base x wrapper.' clx 'Claude Code with permission prompts skipped.' clx2 'Second-account Claude Code via CLAUDE_CONFIG_DIR=~/.claude-second.' clxw 'Claude Code inside a named worktree: clxw <name> [args].' p-f 'Compose a prompt in p, then fork the last Codex session and resume with it.' p-c 'Compose a prompt in p, then fork and resume (the original also compacts).' ) local fn for fn in "${fn_name[@]}"; do printf '%-5s %s\n' "$fn" "${fn_desc[$fn]}" done } ``` Reference ID: factory-zsh-launchers-practice Topic: Tools Sources: - [Thin zsh launchers and composable command families](https://sacred-ritual-w7as.here.now/) - [Public setup contract](https://sacred-ritual-w7as.here.now/agent.md) - [Published launcher families](https://sacred-ritual-w7as.here.now/agent-launchers.zsh) --- # Thin zsh launchers and composable command families — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The room asks Why not just aliases? An alias substitutes text. It can't take a positional argument in the middle, can't run setup logic, and loses quietly when a plugin defines the same name — oh-my-zsh ships single-letter aliases that would shadow half of these helpers. A function passes `"$@"` straight through, and an `unalias` guard makes it win any collision. Here's what my `x` function is hiding: ``` text CODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox ``` And once `x` owns that, the entire resume family is one-line compositions on top of it: ``` text xr() { x resume "$@"; } # pick a session to resume xrl() { x resume --last "$@"; } # jump into the most recent session ``` Okay, but I run two Codex accounts. Doesn't this fall apart the moment auth is involved? That's what `x2` is: the same wrapper pointed at a second home directory (`CODEX_HOME=~/.codex-work`) that a helper builds by symlinking every top-level entry of the primary home *except* the auth files — and it refuses to run if an auth file would ever become a symlink. Sessions and config: shared. Credentials: never. The same trick with `CLAUDE_CONFIG_DIR` gives Claude Code a second account, and that one is simple enough to lift right now: ``` text # claude.zsh — same pattern, different agent. # Placeholders (comments only — nothing below needs editing): # <work-account> = the login that owns ~/.claude-second # Safety trade: --dangerously-skip-permissions removes permission prompts. unalias clx clx2 clxw 2>/dev/null clx() { claude --dangerously-skip-permissions "$@"; } clx2() { # second account (<work-account>) — same UX, separate config dir local config_dir="${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}" mkdir -p "$config_dir" || return CLAUDE_CONFIG_DIR="$config_dir" claude --dangerously-skip-permissions "$@" } clxw() { # launch inside a named worktree: clxw <name> [args] local name="$1"; shift CLAUDE_WORKTREE_NAME="$name" claude --worktree "$name" --dangerously-skip-permissions "$@" } ``` Isn't `--dangerously-bypass-approvals-and-sandbox` terrifying? It should give you pause — the flag says so out loud. Bypass flags trade safety for speed, and the wrapper doesn't change that trade; it stops you re-deciding it forty times a day and makes the posture deliberate and visible in one place. If you don't want the bypass, your `x` simply doesn't include it — the pattern works exactly the same. Don't copy those flags unless you accept unattended file and shell access. How do you remember fifteen two-letter functions? I don't. Every family ends in a dash function that prints its own cheat sheet — `x-` for Codex, `pi-` for pi. The docs live where you type: ``` text $ x- x Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker. x2 Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only. xr Resume a Codex session through the base x wrapper. xrl Resume the most recent Codex session through the base x wrapper. xf Run x fork; pass the conversation id/name first, then the prompt. xfmc Fork conversation m, compact the fork, then resume it interactively. p-f Compose a prompt in p, then fork using the prompt-builder --fork-from toggle. # … full listing covers 35 helpers ``` The CLI updates and renames a flag. Now every wrapper is broken at once, right? Yes — that's the honest cost of composition: families inherit fixes *and* breakage. But the audit is cheap, because the same stub trick that verifies a new family also detects drift without launching anything: ``` text zsh -n ~/.zsh-wrappers/pi-utils.zsh && echo "syntax OK" zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check' ``` Re-run `--help`, patch the one function that owns the changed flag, re-run the stub. The [section guide's](https://sacred-ritual-w7as.here.now/index.html) prompt library has a drift-audit prompt that makes your agent do the whole pass. You keep saying you "pick the agent last." What does that actually mean? Wrappers fix the launch, but there's a subtler mistake: choosing the agent before you've written the prompt. The `p` command — a terminal prompt builder — inverts that. Compose the prompt first, then hand it to any configured target: one prompt can go to any of three agents across five accounts. ``` text $ p target list pi pi bin=pi codex codex bin=codex config=shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1" claude claude bin=claude work-profile codex bin=codex CODEX_HOME=~/.codex-work config=cli_auth_credentials_store="file" … claude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second claude-third claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third ``` Helpers like `p-f` close the loop: compose in `p`, then fork the session and resume with the prompt — all free once the base wrappers exist. A new agent CLI ships next month. How long before it feels like this? About five minutes. Run the recipe: **wrap → compose → document → repeat**. We did it live for pi — read `--help` for the session flags, wrap each one, add the dash function, verify with a stub. The complete result, drop-in ready: ``` text # pi-utils.zsh — the "pir" walkthrough result # Built live at the workshop following the same recipe as the x/xr family. # Source it: source ~/.zsh-wrappers/pi-utils.zsh then run: pi- # Recipe step 0 — the base wrapper already exists in the dotfiles # (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real # pi binary. Every helper below composes on top of `pi`, never the raw binary. # Recipe step 1 — read the CLI's own session flags: # pi --help | grep -E "resume|continue|fork|name" # --continue, -c Continue previous session # --resume, -r Select a session to resume # --fork <path|id> Fork a session into a new session # --name, -n Set session display name # Recipe step 2 — wrap each flag as a two/three-letter function. unalias pir 2>/dev/null pir() { pi --resume "$@"; } # pick a session to resume (pi resume) unalias pic 2>/dev/null pic() { pi --continue "$@"; } # continue the most recent session unalias pif 2>/dev/null pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt] unalias pin 2>/dev/null pin() { # start a named session: pin <name> [prompt] local name="${1:?Usage: pin <name> [prompt...]}"; shift pi --name "$name" "$@" } unalias pit 2>/dev/null pit() { pi --no-session "$@"; } # throwaway session (nothing saved) # Recipe step 3 — every family ships its own cheat sheet (the x- convention). pi-() { local -a fn_name=(pi pir pic pif pin pit) local -A fn_desc=( pi 'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.' pir 'Resume: open the session picker (pi --resume).' pic 'Continue: jump straight back into the last session (pi --continue).' pif 'Fork a session into a new one: pif <path|id> [prompt].' pin 'Start a named session: pin <name> [prompt].' pit 'Throwaway: run without saving a session (pi --no-session).' ) local fn for fn in "${fn_name[@]}"; do printf '%-4s %s\n' "$fn" "${fn_desc[$fn]}" done } ``` Want to watch that file get built prompt by prompt? That's the [Session Replay](https://sacred-ritual-w7as.here.now/replay.html) page. Both this file and the full launcher family (`agent-launchers.zsh`) are downloadable attachments — grab the install block on the [section guide](https://sacred-ritual-w7as.here.now/index.html). Every function, flag, and output above comes from the section's verified sources — the presenter's dotfiles, captured CLI output, and the walkthrough result. Account emails are replaced with `<personal-account>` / `<work-account>` placeholders. Full caveats and provenance: the [section guide's](https://sacred-ritual-w7as.here.now/index.html) appendix. Reference ID: factory-zsh-launchers-questions Topic: Tools Sources: - [Thin zsh launchers and composable command families — questions and tradeoffs](https://sacred-ritual-w7as.here.now/dialogue.html) --- # Thin zsh launchers and composable command families — reference patterns Extended explanations, comparisons, experiments, and practical actions for the same operating pattern. ## Abstract Tiny zsh functions are the cheapest layer of an agentic system. This document argues five steps: agent CLIs impose a real flag-recall tax; a two-letter wrapper function removes it; composing wrappers into families multiplies the payoff; a self-printing cheat sheet keeps the layer discoverable; and the recipe repeats for any new CLI, shown here by building a resume family for the pi agent. All evidence comes from one machine's working configuration, so treat the specific flags as examples, not standards. ## Notice what launching an agent really costs You start a coding agent many times a day. Each launch needs the same environment variable, the same config override, and the same sandbox flag. The common mistake is to lean on shell history: you search backward, hope the right variant surfaces, and sometimes launch with a flag missing. A launch with a missing flag is worse than a failed launch, because the agent starts in a different permission posture than you expect. The dotfiles solve this with a one-letter function. The `x` function pins the Codex home directory, injects a config marker, and applies the sandbox-bypass flag in one place (source S1, `conf.d/40-ai.zsh`). [1](https://sacred-ritual-w7as.here.now/#note-1) 1\. The config override sets `CODEX_LOAD_ZSH_DSL="1"` in the agent's shell environment. The same dotfiles use that marker to expose their shell helpers inside agent tool shells (S1, S3). [↩](https://sacred-ritual-w7as.here.now/#note-ref-1) ``` text # ~/.config/zsh/conf.d/40-ai.zsh — the real wrapper (email replaced) unalias x 2>/dev/null x() { # Default account: <personal-account> via ~/.codex CODEX_HOME="${CODEX_PRIMARY_HOME:-$HOME/.codex}" \ codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \ --dangerously-bypass-approvals-and-sandbox "$@" } ``` **Figure 1.** Source evidence: the `x` function, quoted from S1 with one comment edited to replace a personal email address. **Safety trade** The `--dangerously-bypass-approvals-and-sandbox` flag removes the agent's approval prompts. The wrapper makes that posture deliberate and visible in one place, but it does not make it safe. Do not copy the flag into your own wrapper unless you accept unattended file and shell access. Try the check yourself: run `which x` in a shell where the wrapper is loaded. If it prints a function body with every flag pinned, launches can no longer drift. If it prints nothing, or prints an alias, you are still paying the recall tax. Your next move is an inventory: write down every agent command you retyped this week. ## Compare an alias with a defended function The tempting shortcut is an alias. An alias substitutes text; it cannot take a positional argument in the middle, cannot run setup logic, and loses quietly when a plugin defines the same name. A function can do all three. The dotfiles treat that last risk as real: nearly every definition starts with `unalias <name> 2>/dev/null`, because oh-my-zsh ships single-letter aliases that would otherwise shadow the function (S1). The same wrapper shape repeats across a second agent. The `clx` family wraps Claude Code exactly the way `x` wraps Codex: base flags in the short name, an environment variable for the second account, a positional argument for worktrees (S1). ``` text clx() { claude --dangerously-skip-permissions "$@"; } clx2() { local config_dir="${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}" mkdir -p "$config_dir" || return CLAUDE_CONFIG_DIR="$config_dir" claude --dangerously-skip-permissions "$@" } clxw() { local name="$1"; shift CLAUDE_WORKTREE_NAME="$name" claude --worktree "$name" --dangerously-skip-permissions "$@" } ``` **Figure 2.** Source evidence: three members of the Claude Code family, quoted from S1. Note what an alias cannot do here: `clxw` consumes its first argument before passing the rest through. Wrappers also absorb upstream bugs. The `pi` wrapper deletes a malformed lock file before every launch, so a known failure in the pi agent's locking library never reaches the user (source S2, `local.zsh`). [2](https://sacred-ritual-w7as.here.now/#note-2) 2\. The source comment explains the mechanism: pi's lockfile dependency expects a directory at `auth.json.lock`. A stray regular file there causes recurring auth failures, so the wrapper removes it (S2). [↩](https://sacred-ritual-w7as.here.now/#note-ref-2) The decision rule: reach for an alias only when the command is pure text substitution with no arguments, no environment, and no collision risk. Otherwise write a function with the `unalias` guard and `"$@"` pass-through. The feedback signal is the same as before — `which <name>` tells you which one you actually got. ## Explain why composed families beat one-off wrappers A single wrapper saves keystrokes. The compounding payoff appears when wrappers call other wrappers. If `x` owns the account and the flags, then every session action becomes a one-line composition on top of it — and inherits any future fix to `x` for free. The dotfiles build a whole resume-and-fork vocabulary this way: `xr` resumes, `xrl` resumes the last session, `xrm` resumes a session named "m", and `xfmc` forks that session, compacts the fork, and resumes it — all routed through `x` (S1). ``` text xr() { x resume "$@"; } xrl() { x resume --last "$@"; } xrm() { x resume m "$@"; } xf() { x fork "$@"; } xfmc() { local fork_id fork_id="$(_codex_app_server_fork_compact_latest m)" || return 1 print -r -- "$fork_id" _codex_cmux_name_current_tab x resume "$fork_id" "$@" } ``` **Figure 3.** Source evidence: the resume and fork family, quoted from S1. Each helper is a thin composition over `x`; only `xfmc` adds real logic. Composition also solves multi-account work. The `x2` function runs the same agent under a second account by pointing `CODEX_HOME` at a second directory that shares the primary's state through symlinks — while auth files stay local to each account (S1). [3](https://sacred-ritual-w7as.here.now/#note-3) 3\. A helper named `_codex_egghead_ensure_home` builds the second home. It symlinks every top-level entry except auth-related names such as `auth.json`, and it refuses to run if the auth file ever becomes a symlink (S1). Accounts share sessions and config, never credentials. [↩](https://sacred-ritual-w7as.here.now/#note-ref-3) A family this large needs its own memory aid, and the dotfiles make the family print one. Running `x-` lists every helper with a one-line description, straight from the same file that defines them (S1; output captured in S3). ``` text x Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker. x2 Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only. xr Resume a Codex session through the base x wrapper. xrl Resume the most recent Codex session through the base x wrapper. xf Run x fork; pass the conversation id/name first, then the prompt. xfmc Fork conversation m, compact the fork, then resume it interactively. p-f Compose a prompt in p, then fork using the prompt-builder --fork-from toggle. ``` **Figure 4.** Source evidence: excerpt of the `x-` cheat sheet captured the recorded snapshot (S3). Email addresses are replaced with placeholders; the full listing covers 35 helpers. **Drift risk** Composed families inherit fixes, but they also inherit breakage. When the underlying CLI renames a subcommand or flag, every wrapper above it fails at once. The cheat-sheet function reduces the cost of the audit; it does not remove the need for one. The test for your own setup: pick your most common session action — resuming — and count the keystrokes it takes today. If the answer is more than three or four, you have found the first family worth building. ## Choose the agent at prompt time, not alias time Wrappers fix the launch. They do not fix a second, subtler mistake: deciding which agent to use before you have written the prompt. Once the prompt exists, you often realize it belongs to a different agent, a different account, or a forked copy of an old session. The `p` command inverts the order. It is a separate terminal program — "Terminal prompt builder for handing prompts to Pi, Codex, or Claude Code," in its own help text — that lets you compose the prompt first and then launch any configured target with it (S3). ``` text $ p target list pi pi bin=pi codex codex bin=codex config=shell_environment_policy... claude claude bin=claude work-profile codex bin=codex CODEX_HOME=~/.codex-work ... claude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second claude-third claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third ``` **Figure 5.** Source evidence: launch targets captured the recorded snapshot (S3), abbreviated to fit. One prompt can go to any of three agents across five accounts. The two layers then compose with each other. Helpers such as `p-f` and `p-c` open the prompt builder, and hand the finished prompt to a zsh function that forks a session, optionally compacts it, and resumes it (S1). You can rehearse this without launching anything: `p --print-prompt "explain this repo"` prints the composed prompt and exits, and `--dry-run` skips the launch entirely (S3). If the printed prompt matches what you meant to send, the pipeline is wired correctly. The limit to keep in mind: the target list above is one machine's configuration file, not a default that ships with the tool. ## Test the recipe: build a pi resume family The claim that this recipe repeats "in minutes" is testable, and the workshop tests it live. The pi agent has a base wrapper but no session helpers yet. Step one is always the same: ask the CLI what it can do, instead of guessing. ``` text $ pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session" --continue, -c Continue previous session --resume, -r Select a session to resume --fork <path|id> Fork specific session file or partial UUID into a new session --name, -n <name> Set session display name --no-session Don't save session (ephemeral) ``` **Figure 6.** Source evidence: session flags from pi's own help output, version 0.80.10, captured the recorded snapshot (S3). Each flag becomes one short function, and the family gets its own cheat sheet in the `x-` style. This is the exact file built for the workshop (source S4, `demo/pi-utils.zsh`). ``` text pir() { pi --resume "$@"; } # pick a session to resume pic() { pi --continue "$@"; } # continue the most recent session pif() { pi --fork "$@"; } # fork a session: pif <path|id> pin() { # start a named session local name="${1:?Usage: pin <name> [prompt...]}"; shift pi --name "$name" "$@" } pit() { pi --no-session "$@"; } # throwaway session ``` **Figure 7.** Source evidence: the new pi family, quoted from S4. A `pi-` cheat-sheet function completes the file. ``` text $ zsh -n demo/pi-utils.zsh && echo "syntax OK" syntax OK $ zsh -fc 'pi() { echo "[stub pi] $@"; }; source demo/pi-utils.zsh; pir --check' [stub pi] --resume --check ``` **Figure 8.** Derived display: the verification run from the recorded snapshot (S4), reformatted from the build log. A stub replaces the real binary, proving each helper passes the intended flags. **Evidence limit** The stub test proves flag wiring, not end-to-end behavior. A live `pir` only opens the session picker when pi has saved sessions on that machine. The sources also do not measure the "five minutes" figure; it is the presenter's estimate for this walkthrough. Run the same two commands against any wrapper file you write. Syntax check first, stub test second. If the stub echoes the flags you expected, load the file for real and watch `pir` open the picker. If it echoes something else, the bug is in your function, not in the agent — which is exactly where you want bugs to live. ## Practical action Apply the recipe to one agent CLI this week: 1. **Capture** the exact launch command you retype most, flags and all. 2. **Wrap** it: `unalias` guard, short function name, env pinning inside, `"$@"` at the end. 3. **Compose** the first family on top — resume is usually the highest-value action. 4. **Document** with a `<name>-` cheat-sheet function so the family stays discoverable. 5. **Verify** with `zsh -n`, then a stub test, before sourcing it in your real shell. Success looks like this: a week later, `which` shows functions instead of history searches, and the cheat sheet answers "what was that helper called?" without leaving the terminal. If a wrapper breaks after a CLI update, that is the drift caveat arriving on schedule — re-run the CLI's `--help` and adjust the one function that owns the changed flag. Reference ID: factory-zsh-launchers-reference-patterns Topic: Tools Sources: - [Prepared module reference](https://sacred-ritual-w7as.here.now/) --- # Thin zsh launchers and composable command families — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session pi had a base wrapper but no session helpers — the whole point of the walkthrough is that the gap closes in minutes. This transcript restages the section's scripted walkthrough as prompts to a coding agent; every output shown is the captured output from a prior session. You Run `pi --help` and pull out the session flags — resume, continue, fork, whatever it actually ships. Agent Ran the help command and filtered for the session verbs: ``` text $ pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session" --continue, -c Continue previous session --resume, -r Select a session to resume --fork <path|id> Fork specific session file or partial UUID into a new session --name, -n <name> Set session display name --no-session Don't save session (ephemeral) ``` First beat is always reconnaissance. You never invent verbs — every flag the CLI ships is a candidate wrapper, and nothing else is. You Wrap each flag as a two- or three-letter function in `pi-utils.zsh`, following my `x`-family convention: `unalias` guard first, one short function per flag, comment on the same line. Agent Wrote the one-liners. Each is a single line on top of the existing `pi` wrapper — the one that already heals the `auth.json.lock` bug before launching the binary: ``` text unalias pir 2>/dev/null pir() { pi --resume "$@"; } # pick a session to resume (pi resume) unalias pic 2>/dev/null pic() { pi --continue "$@"; } # continue the most recent session unalias pif 2>/dev/null pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt] ``` Composition, not duplication: the flags live in exactly one place. This is the same shape as `xr() { x resume "$@" }` in the Codex family — a future fix to the base wrapper fixes every helper for free. You `pin` takes an argument — a session name. Guard it so it fails loudly with usage instead of launching with a blank name. Agent ``` text unalias pin 2>/dev/null pin() { # start a named session: pin <name> [prompt] local name="${1:?Usage: pin <name> [prompt...]}"; shift pi --name "$name" "$@" } ``` Also added `pit` for `--no-session` throwaway runs. The one wrapper that outgrows a one-liner earns a body — but only just. Guard clauses over silent failure. You Finish with the cheat sheet: a `pi-` function that prints the whole family, the way `x-` does for the Codex family. Agent Wrote `pi-` — a name array plus a description map, printed as an aligned table. Its output is in the verification run below. Every family ships its own cheat sheet — the `fn-` convention. Six months from now, `pi-` answers "what did I name these?" without leaving the shell. You Verify without launching anything real: syntax check the file, then prove each helper passes the right flag. Agent Ran `zsh -n`, then a stub test that shadows `pi` with a function so nothing actually launches: ``` text zsh -n ~/.zsh-wrappers/pi-utils.zsh && echo "syntax OK" zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check' ``` ``` text syntax OK pi Base wrapper: heals the auth.json.lock bug, then runs the pi binary. pir Resume: open the session picker (pi --resume). pic Continue: jump straight back into the last session (pi --continue). pif Fork a session into a new one: pif <path|id> [prompt]. pin Start a named session: pin <name> [prompt]. pit Throwaway: run without saving a session (pi --no-session). [stub pi] --resume --check ``` The stub proves wiring — which flags each helper passes — not behavior. A live `pir` opens pi's session picker only when saved sessions exist on the machine. Agent File landed. Complete and drop-in ready: ``` text # pi-utils.zsh — the "pir" walkthrough result # Built live at the workshop following the same recipe as the x/xr family. # Source it: source ~/.zsh-wrappers/pi-utils.zsh then run: pi- # Recipe step 0 — the base wrapper already exists in the dotfiles # (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real # pi binary. Every helper below composes on top of `pi`, never the raw binary. # Recipe step 1 — read the CLI's own session flags: # pi --help | grep -E "resume|continue|fork|name" # --continue, -c Continue previous session # --resume, -r Select a session to resume # --fork <path|id> Fork a session into a new session # --name, -n Set session display name # Recipe step 2 — wrap each flag as a two/three-letter function. unalias pir 2>/dev/null pir() { pi --resume "$@"; } # pick a session to resume (pi resume) unalias pic 2>/dev/null pic() { pi --continue "$@"; } # continue the most recent session unalias pif 2>/dev/null pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt] unalias pin 2>/dev/null pin() { # start a named session: pin <name> [prompt] local name="${1:?Usage: pin <name> [prompt...]}"; shift pi --name "$name" "$@" } unalias pit 2>/dev/null pit() { pi --no-session "$@"; } # throwaway session (nothing saved) # Recipe step 3 — every family ships its own cheat sheet (the x- convention). pi-() { local -a fn_name=(pi pir pic pif pin pit) local -A fn_desc=( pi 'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.' pir 'Resume: open the session picker (pi --resume).' pic 'Continue: jump straight back into the last session (pi --continue).' pif 'Fork a session into a new one: pif <path|id> [prompt].' pin 'Start a named session: pin <name> [prompt].' pit 'Throwaway: run without saving a session (pi --no-session).' ) local fn for fn in "${fn_name[@]}"; do printf '%-4s %s\n' "$fn" "${fn_desc[$fn]}" done } ``` Five prompts, one file. The recipe the transcript demonstrates — **wrap → compose → document → repeat** — is the whole section; it repeats for every new agent CLI. This file and the full launcher family (`agent-launchers.zsh`) are downloadable attachments — grab the install block on the [section guide](https://sacred-ritual-w7as.here.now/index.html). ## Run this session yourself Paste this into your own coding agent to replay the whole session against your machine — it is the same prompt from the [section guide's](https://sacred-ritual-w7as.here.now/index.html) prompt library. ``` text Build me a two-letter zsh wrapper family for the pi CLI. 1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session. 2. Create ~/.zsh-wrappers/pi-utils.zsh. For each flag define a short function that calls `pi <flag> "$@"`: pir (resume), pic (continue), pif (fork), pin (named session — take the name as $1, error if it is missing), pit (no-session). Guard every definition with `unalias <name> 2>/dev/null`. 3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description. 4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test: zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check' Expect: [stub pi] --resume --check 5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself. ``` Reference ID: factory-zsh-launchers-worked-example Topic: Tools Sources: - [Thin zsh launchers and composable command families — worked example](https://sacred-ritual-w7as.here.now/replay.html) --- # Use images, video, and task-shaped model routing > Original source pages and recordings require authorized access. The full article text here is public. The practice is turning vague intent into useful signals your agents can actually build from: split work into focused CMUX sessions, pick models based on the shape of the task, use generated images as concrete design references, and use video when a sequence of code or UI state matters. John also draws a practical boundary between deterministic scripts or CLIs, fuzzy agent reasoning, MCP wrappers, and operational tools: do not over-abstract when a simple command would be clearer, safer, and easier to reason about. ## Working outcomes - Run CMUX as a primary orchestrator with token-efficient flash models - Use image generation as a design reference and hand off image-to-design - Prompt with video and navigate the MCP-vs-CLI boundary ## Concepts and consequences ### CMUX as a primary orchestrator John demonstrates a main CMUX session opening specialized Codex panes for quality control, performance, research, and notes. The main pane becomes the coordinator, while each child pane has a narrow role and can work independently. **Why it matters:** This keeps context cleaner and makes delegation visible. It gives you a practical way to monitor several agent tracks without dumping every task into one large prompt thread. ### Model choice by task shape John frames Codex as his default coding worker, especially when goal-following and token efficiency matter. Claude can be useful as a conversational manager or design helper, while Flash-style models are best for quick, tightly scoped tasks and weaker for long chains that require self-correction. **Why it matters:** Good model choice is a cost and reliability decision, not a brand preference. Matching the model to the task reduces wasted tokens and lowers the odds of an agent spiraling while trying to fix its own mistake. ### Image generation as design reference For UI work, John recommends generating sheets of visual variations before committing to a direction. For example, he describes taking a screenshot of a component and asking for many variations, then picking the favorite as the design direction. **Why it matters:** Images collapse ambiguity. They let non-designers express taste through selection, which is often easier than inventing exact CSS, spacing, motion, and layout language from scratch. ### Video prompting for high-context intent John describes uploading video to Gemini by hand and also using scripts that upload to Google's backend to extract code snippets, key parts, timestamps, and screenshots. Video can preserve the flow of a demo or code walkthrough better than a written description because the model sees the sequence of states. **Why it matters:** When the task depends on timing, UI state, or code changing over time, video can carry intent that text misses. The practical caveat he names is that scripted backend use can involve cost and auth-token setup. ### MCP versus CLI boundaries John warns that it can get weird to build a skill just to call an MCP wrapper when the skill could have called a CLI directly. His broader rule is to define boundaries around what needs tests, what needs flexibility, where memory belongs, and which agents should have access to which tools. **Why it matters:** Clear boundaries make agent systems easier to reason about. If a workflow is deterministic and testable, a direct CLI or script may be simpler than an unnecessary MCP layer; use agent reasoning where judgment, interpretation, or flexible planning actually adds value. ## Reference tools and resources ### CMUX The workspace John uses to automate terminal tabs and panes, launch Codex sessions, name them by role, and coordinate multiple focused agent tracks. **Use when:** Reach for it when you want a visible multi-agent command center where one main session can create, name, monitor, and delegate to focused panes. [Reference](https://github.com/manaflow-ai/cmux) ### Codex CLI The coding agent John uses as his default programming worker in the workshop, especially for goal-driven implementation tasks and token-efficient coding work. **Use when:** Reach for it when the task is real code work that needs persistence, goal-following, and stronger follow-through than a tiny one-shot model. search: OpenAI Codex CLI ### Google Gemini video prompting The multimodal workflow John describes for processing screencasts into timestamps, screenshots, code snippets, and key moments. **Use when:** Reach for it when text alone is not enough to explain a demo, code walkthrough, or UI behavior over time. search: Google Gemini API video understanding ### Impeccable A visual design-to-code workflow John briefly highlights as aligned with his image-to-design approach. He notes its recent npx impeccable CLI, Design.md output, generated-image workflow, and motion/delight features, but does not walk through using it. **Use when:** Reach for it when you want to explore turning generated design images into frontend implementation, while recognizing this section only gives a high-level overview. search: Impeccable npx impeccable CLI ### gogcli A Google CLI workflow repository John shared while describing account automation across email and other Google services. **Use when:** Reach for it when exploring operational automation around Google account data, but be careful because these workflows can read, draft, send, or otherwise act on real account information. [Reference](https://github.com/openclaw/gogcli) ## Recommendations and best practices - Create a reusable CMUX setup prompt that opens four panes with explicit roles such as Research, Quality Control, Performance, and Notes, then practice delegating one real subtask to a named pane. - Use Codex for coding work that needs goal-following and persistence. Use Claude when conversation or design help matters. Use Flash-style models for quick, tightly scoped tasks where speed matters and failure is cheap. - Before asking an agent to build or revise a UI, generate a sheet of visual variations and pick the direction you actually like. A selected reference image beats a vague taste prompt. - Use video when the important part is a sequence: a demo, a changing UI, a code walkthrough, or a moment where timestamps and screenshots matter. - Expect scripted video processing through Google's backend to involve auth-token setup and cost, even if manual drag-and-drop is still useful. - Keep deterministic automation in scripts or CLIs, and reserve agent reasoning for decisions, interpretation, and fuzzy planning. Do not wrap a CLI in MCP just because MCP is available. - Be careful with Google CLI-style account automation. John's example was powerful precisely because it could gather information and act on real email/account workflows. - Use a physical Pomodoro or off-keyboard reset ritual if you run many agents at once. The point is to force your brain to stop monitoring every pane continuously. - For scheduling, monitor actual outputs such as git diffs, PRs, Slack, email, or agent progress rather than only summarizing chat logs. ## Practice and acceptance criteria Practice turning messy visual intent into concrete agent instructions using CMUX, generated references, video context, and clear tool boundaries. ### Checklist 1. Create a CMUX setup prompt that opens four named Codex sessions: Research, Quality Control, Performance, and Notes. 2. Seed each pane with a narrow role prompt that states what it should inspect, produce, and avoid doing. 3. Delegate one real subtask from the main pane to a specific child pane, then verify the main context stays clean. 4. Pick one UI component or screenshot and generate a sheet of visual variations before asking an agent to code anything. 5. Choose one favorite reference image and use it as the concrete design direction in the implementation prompt. 6. Record a short screencast of a code or UI walkthrough, then ask a video-capable model for timestamps, screenshots, code snippets, and key moments. 7. Audit one automation idea by separating deterministic scripts or CLIs from agent inference and MCP/tool access. 8. Create one monitoring routine that checks actual git diffs or other real outputs instead of only summarizing agent conversation. ### Four-Pane Orchestrator Drill **Difficulty:** Easy In CMUX, write and run a setup prompt that creates Research, Quality Control, Performance, and Notes panes, then delegate a small codebase investigation to exactly one pane. **Done when:** The named panes open with distinct roles, the delegated pane produces a useful result, and the main pane can summarize progress without copying every child conversation. ### Reference-First Component Direction **Difficulty:** Medium Choose a real component from a local project, generate a sheet of visual alternatives, select one direction, and hand that image plus a focused implementation request to Codex or your preferred coding agent. **Done when:** The implementation request points to one selected visual direction, and the resulting diff is focused on the intended component or files. ### Video Extraction Brief **Difficulty:** Medium Record a short screencast of a code or UI walkthrough, process it with a video-capable model, and turn the output into a brief with timestamps, screenshots, code snippets, and key moments. **Done when:** Someone who has not watched the full video can understand the important moments and where to look in the code or UI. ### Boundary Audit and Refactor **Difficulty:** Hard Take one workflow that currently uses an agent for everything and redesign it so deterministic steps run through scripts or CLIs, fuzzy decisions stay with agents, and tool access boundaries are explicit. **Done when:** The final workflow has a clear boundary map, at least one testable CLI or script step, and a written explanation of what needs tests versus what needs flexibility. ## Questions to test understanding ### Why does the lesson recommend using CMUX as a primary orchestrator instead of running one huge agent thread? - **A.** It keeps each agent role focused and lets the main session coordinate work without mixing every task into one context. - **B.** It guarantees every child agent will produce correct code without review. - **C.** It replaces the need for Git, tests, or browser inspection. - **D.** It is only useful when all agents use the same model. **Answer: A.** The point is visible delegation: research, quality, performance, and notes can each run in a narrow context while the main pane coordinates. That reduces context mess and makes monitoring easier. ### Which task is the best fit for a fast Flash-style model in this lesson's routing approach? - **A.** A long, multi-step refactor that will likely require repeated self-correction. - **B.** A small, tightly scoped task where speed matters and failure is cheap. - **C.** Owning the entire frontend implementation from scratch with no supervision. - **D.** Replacing deterministic scripts, CLIs, and tests. **Answer: B.** Flash-style models are useful when the task is constrained and speed matters. John warns that they can burn tokens or fall off the rails when forced into long sequential repair loops. ### What is the main advantage of generating image variations before asking an agent to build a UI? - **A.** It removes the need to describe acceptance criteria. - **B.** It lets the learner select a concrete visual direction instead of relying on vague taste words. - **C.** It guarantees the implementation will match the image pixel-perfectly. - **D.** It prevents the agent from needing access to the codebase. **Answer: B.** A chosen reference image collapses ambiguity. It gives the coding or design agent a clearer target than prompts like 'make it more polished' or 'make the button better.' ### What did John say makes video prompting valuable? - **A.** The model can see a sequence over time and extract things like timestamps, screenshots, code snippets, and key moments. - **B.** It is mainly useful when the model should ignore everything except the final screen. - **C.** It replaces the need to explain what happened in a code or UI walkthrough. - **D.** It is best for deterministic commands that can be tested with a shell script. **Answer: A.** John describes video plus code as giving the model a strong understanding of what happened over time. He specifically mentions timestamps, screenshots, code snippets, and key parts. ### What is the lesson's practical rule of thumb for MCP versus CLI boundaries? - **A.** Wrap every CLI in MCP so the agent has one standard interface. - **B.** Avoid CLIs because agents can reason better without deterministic tools. - **C.** Use direct scripts or CLIs for deterministic work, and use agents where judgment or interpretation adds value. - **D.** Use MCP only for visual design work and never for operational automation. **Answer: C.** The lesson pushes against over-abstracting simple commands. If a workflow is deterministic and testable, a direct CLI or script may be safer and clearer than an unnecessary MCP wrapper. ## Reflection prompts - Where in your current workflow are you using a vague prompt when a generated image, screenshot, or video would give the agent a better signal? - Which tasks in your stack deserve Codex-level persistence, which can go to a fast small model, and which should be handled by deterministic scripts or CLIs? - What is one MCP wrapper or agent tool in your setup that might be simpler, safer, and easier to test as a direct CLI call? ## Further applications 1. Write a one-page agent routing guide for your own stack: which model handles coding, design conversation, quick one-off tasks, video analysis, and deterministic CLI work. 2. Build a small image-to-design exercise: screenshot one component, generate a sheet of design variations, pick one, then ask an agent to implement only that chosen direction. 3. Record a short screencast of a code or UI walkthrough and test whether a video-capable model can extract timestamps, screenshots, code snippets, and key moments. 4. Audit one workflow you currently automate and label each step as deterministic script or CLI, agent inference, MCP/tool access, or monitoring. 5. Experiment with a CMUX monitoring routine that summarizes git diffs hourly, rather than summarizing chat logs, so you track actual code progress instead of agent chatter. ## Applied exercises Multi-Agent Layout Experiment: Write a setup prompt for your preferred orchestrator (such as CMUX) that opens four distinct split panes. Assign each a unique system persona (e.g., Security Auditor, Performance Evaluator, Unit Tester, Documentation Writer). Practice routing a single code task out to one dedicated pane and verify that background tracking occurs independently of your central panel history. ## Questions and answers ### Okay, and also this, you wrote, create a primary terminal that coordinates focused agents. Will you go into that, or was that already that part where you had the timestamp created? Explains that you can tell CMUX to open distinct panels for focused roles (e.g., quality control, performance, research, note-taking) pre-seeded with specialized persona prompts. The primary session then operates as the core orchestrator delegating specific sub-tasks to these target sessions. ### Also, what is the… when I'm already at it, what is that cursor thing where you can draw? Did you mention that? It is called Clicklight. ### any preference on which agent to use for which task Codex is the default programmer selection, outperforming alternatives in token efficiency (especially on Rust code bases). Claude is preferred as a conversational main orchestrator and for design scaffolding when no asset files are provided. Flash 3.5 is suitable strictly for fast, single-step execution but struggles to self-correct during sequential logic tasks. Gemini is unmatched for long-context multi-modal ingestion such as video code extraction. ### if i'm automating a workflow in typescript It depends heavily on the specific workflow and how deterministic it needs to be. You must separate the deterministic procedural parts (scripts via Terminal/CLI) from the fuzzy inference parts (intelligence via the Agent SDK). ### How do you mentally keep up with heavy context-switching? Uses a physical, rotating Pomodoro timer sitting directly on the desk set strictly to 25 minutes. When it signals, you must physically touch it, move away from the workstation entirely, and separate from agent monitors to let the brain relax and naturally reset. ### what do you use scheduling for? loops? Scheduling is primarily used for monitoring tasks: configuring agents to compile hourly diff reports to trace code progression vs. conversation chatter, scraping communication updates (Slack, Pull Requests, email metrics), or exporting hourly operational briefs to an e-ink display. For standard execution loops, simply supply a explicit array list combined with standard language definitions like "for each of these things" inside a goal-directed prompt loop until a completion condition is reached. ### Are you a fan of these fully hackable harnesses like pi.dev ? He likes what the pi.dev team is doing, but due to constrained bandwidth, he remains fully focused on his open-source Rust-based setup featuring Codex and CMUX. ### have you used claude design? its pretty good Has used it a couple of times with good results, but notes that it tends to hand-hold through a single targeted path rather than generating massive layouts of design alternatives, which is his personal preference. ### do you limit your mcps? have skills call the mcps instead? saw executor post as well Mentions that Executor is preferred for single-agent systems calling multiple tools. He highlights that it gets visually redundant or confusing when an engineer constructs custom agent skills designed specifically to target an isolated MCP server wrapper when the underlying system could have simply called the native engine CLI directly. Acknowledges the community is currently in an unstandardized territory regarding these boundaries. ### Do you have any ideas on how to create levers for agents so they can do big data stuff without having all the data in their context? Explicitly states he is not an expert on big data engineering integrations and refers the user to follow established, popular open-source data manipulation platforms rather than presenting speculative advice. ## Operational playbooks - [Image-to-design handoff](/topics/foundations-image-to-design-playbook/) - [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/) ## Recording references - [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-06.mp4) [Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-06.html) ### Visual reference index - [02:02:41](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-1): CMUX multi-pane splits displaying Quality Control, Performance, Research, and Notes window splits concurrently. - [02:04:04](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-2): Active window prompt context where John commands the newly split background Research sub-agent panel. - [02:04:49](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-3): On-screen annotation or menu moment while discussing the Clicklight drawing cursor tool. - [02:12:46](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-4): Terminal workspace interface parameters linked with Google CLI scripting files configuration structure. - [02:13:37](https://codex-workshop-followup.pages.dev/lesson-06.html): Webcam perspective showcasing John holding the tangible rotating Pomodoro physical unit block. - [02:20:46](https://codex-workshop-followup.pages.dev/lesson-06.html): Impeccable system update release page detailing the npx impeccable command terminal instructions. - [02:21:49](https://codex-workshop-followup.pages.dev/lesson-06.html): Impeccable site section showing design-oriented examples and image-to-layout material. - [02:23:11](https://codex-workshop-followup.pages.dev/lesson-06.html): Visual evaluation of Impeccable browser interface elements containing the slop tab and live canvas module panels. Reference ID: foundations-multimodal-design-and-model-routing Topic: Tools Sources: - [Agent foundations: Use images, video, and task-shaped model routing (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-06.html) --- # Web Choices server and submission runbook Use this for agent-generated option lists that the user should review in a clean, polished, interactive browser experience or on a phone. The durable implementation lives in this skill directory: ```text ~/.agents/skills/web-choices ``` Agents must launch the skill-local CLI from any project and must store runtime state in a caller-selected `HITL_OUT_DIR`, usually `$PWD/.hitl-choice`. ## Non-Negotiables - The browser UI must be compiled from Svelte and mdsvex sources in this skill. - At least one `.svx` route or template must be part of the served choice experience. - A plain generated HTML form, static DOM script, or one-off Markdown page is not an acceptable implementation. - Oracle-generated choices remain strict JSON data. Do not compile Oracle/user option strings as Svelte or mdsvex source. - `current-job.json`, drafts, and submissions remain the durable source of truth. - The app must run from any project. Do not hardcode `script-kit-gpui`. - Do not overwrite an active current job without inspecting status and requiring explicit replacement. - Keep the HITL server alive in `tmux`; do not stop it after sending the URL. - Wait for the saved submission before continuing. The local wait defaults to no timeout. ## Generate Choices With Oracle For repo-aware lists, use `$oracle-packx` and include process docs plus relevant source/tests. For large context, use Oracle browser attachments rather than inline-only prompts. Oracle generation is blocking. After starting the Oracle choice-list request, do not draft choices locally, publish a partial job, or continue until Oracle has completed and the local Oracle response has been read. Ask Oracle for a strict JSON job: ```json { "jobId": "short-stable-id", "title": "Human-readable title", "description": "What the user is choosing", "createdAt": "ISO timestamp", "options": [ { "id": "stable-option-id", "title": "Short option title", "description": "Concrete choice text", "tags": ["optional"], "surface": "optional area", "goal": "optional goal", "risk": "optional risk", "suggestedProofCommands": ["optional command"], "expectedEvidence": { "pass": "optional pass signal", "fail": "optional fail signal" } } ] } ``` If a selected option later fails verification, ask Oracle again with a Prior-State Ledger and Forward Progress Gate describing the failure, selected option, logs, and what has already been tried. ## Build And Serve The mdsvex Choice Experience The skill-local app is a Bun + Vite + Svelte + mdsvex app. mdsvex owns the page/template shell; Svelte components own filters, cards, selection state, feedback fields, save status, and submission controls. Runtime data remains JSON-driven. From any project: ```bash export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices" export HITL_OUT_DIR="$PWD/.hitl-choice" export HITL_HOST="127.0.0.1" export HITL_PORT="8877" bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server \ --out-dir "$HITL_OUT_DIR" \ --host "$HITL_HOST" \ --port "$HITL_PORT" \ --tmux ``` The server writes or reuses `$HITL_OUT_DIR/.token`. Read the token from that file or from the server status. Confirm the server is alive: ```bash bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status \ --out-dir "$HITL_OUT_DIR" \ --url "http://127.0.0.1:$HITL_PORT" \ --token-file "$HITL_OUT_DIR/.token" ``` Push the Oracle-generated job: ```bash bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push /path/to/job.json \ --url "http://127.0.0.1:$HITL_PORT" \ --token-file "$HITL_OUT_DIR/.token" ``` Use `--replace` only after inspecting active job status and confirming replacement is safe. Start and verify Tailscale Funnel by default: ```bash tailscale funnel --bg --yes "$HITL_PORT" tailscale funnel status curl -s "https://<your-tailnet-host>.ts.net/api/jobs/current?token=$(cat "$HITL_OUT_DIR/.token")" ``` Give the user the public URL only after the public API returns the expected `jobId` and option count: ```text https://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN> ``` Tell the user the server is staying open, drafts are saved server-side, and you are waiting for their submission. ## Wait And Resume Wait locally without a timeout unless the user asks otherwise: ```bash bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait \ --job "<jobId>" \ --out-dir "$HITL_OUT_DIR" ``` Persisted sources of truth: - `$HITL_OUT_DIR/current-job.json` - `$HITL_OUT_DIR/drafts/` - `$HITL_OUT_DIR/submissions.jsonl` - `$HITL_OUT_DIR/submissions/<submissionId>.json` After submission, report the `submissionId`, selected count, selected option IDs/titles, per-option feedback, overall feedback, and saved file path. Continue from saved JSON, not memory. ## Verification Before giving the user the URL, verify: - `bun run build` succeeds in `~/.agents/skills/web-choices`. - The current page is served from compiled Svelte/mdsvex output. - The public or local API returns the expected `jobId` and option count. - Desktop and phone-width rendering are usable. - Draft saving and final submit persist JSON under `HITL_OUT_DIR`. ## Failure Prevention - If the tunnel fails, keep the same server/job/token when possible and restart Funnel; do not regenerate choices unless asked. - If the server dies, inspect `HITL_OUT_DIR` first, restart with the same token, and verify drafts/submissions still exist. - If the user says they submitted but wait has not returned, check `submissions.jsonl`, per-submission files, server logs, and `/api/jobs/<jobId>/submissions/status?token=<token>`. - If laptop sleep or network loss is possible, say the server is durable while the machine and Tailscale are online; leave the `tmux` session running. - Do not expose sensitive choices over a public Funnel URL without user approval. The token gates access but is not full authentication. ## Operational boundaries - The bundle includes the skill instructions, not the complete runnable Svelte/mdsvex app. Install or locate the implementation before using its CLI paths. Funnel exposes the service publicly; token-bearing links are not full authentication. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-web-choices-runbook Topic: Tools Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Agent Markers debugging workflows: team walkthrough ## Team Learning Goal Teach markers as human-intent anchors in debugging workflows. By the end of this section, the room should understand: - why raw logs are not enough - how `mark -> capture -> explain -> review/export` works - what a `DebugSession`, `DebugMoment`, `CapturedEvent`, and `nearbyEventIds` are - how to export marker JSON from browser/dev/test flows - how privacy defaults prevent overcapture - how marker exports become bounded debug packets - how Section 9 can use the packet as a work unit ## Walkthrough Depth ### Essential Walkthrough 1. State: raw logs tell what emitted; markers tell why a moment mattered. 2. Draw `mark -> capture -> explain -> review/export`. 3. Show `createAgentMarkers`. 4. Show `window.__AGENT_MARKERS__.mark` and `export`. 5. Show the final agent prompt shape. ### Expanded Walkthrough Add: - capture types table - privacy defaults - `nearbyEventIds` - Playwright export - `stop()` cleanup ### Deep-Dive Walkthrough Add: - app-specific `Ctrl+M` flow - bounded replay capsule - smoke/test commands - exercises ## Talking Points Opening: > Raw logs tell you what emitted. Agent markers tell you why a moment mattered. On markers: > A marker is a human-intent anchor, not another log line. On privacy: > Metadata first. Values only when deliberately enabled and safe. On replay: > This is a bounded debug packet, not a deterministic recorder. Bridge from Section 7: > Section 7 preserved evidence from video. Section 8 lets you create evidence while debugging. Bridge to Section 9: > A good marker export is small enough to become a work unit. ## Live Demo Script ### 1. Show Setup ```ts import { createAgentMarkers } from "@agent-markers/client"; const markers = createAgentMarkers({ appName: "checkout-app", exposeGlobal: true, capture: { console: true, fetch: true, errors: true, }, }); ``` ### 2. Create A Marker ```js window.__AGENT_MARKERS__.mark({ label: "saved payment selector empty after refresh", note: "Expected saved cards to stay visible after auth refresh; actual selector is empty.", }); ``` ### 3. Export ```js const session = window.__AGENT_MARKERS__.export(); ({ markerCount: session.markers.length, eventCount: session.events.length, hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0), }); ``` ### 4. Verify Project ```bash npm test npm run typecheck npm run build npm run smoke:demo ``` ## Minimal Useful Path If 5 minutes behind, cut: - Cypress example - app-specific `Ctrl+M` - bounded replay capsule details - screenshot/DOM hook implementation Preserve: - `mark -> capture -> explain -> review/export` - `createAgentMarkers` - `window.__AGENT_MARKERS__` - `nearbyEventIds` - privacy defaults - export JSON - Section 9 bridge ## Boundaries ### From Section 7 Section 7: ```text source media -> evidence lanes -> verified prompt material ``` Section 8: ```text marked moment -> nearby runtime evidence -> bounded debug packet ``` ### To Section 9 Section 9 needs work units that are small, bounded, and verifiable. Agent markers provide: - one marker id - human explanation - nearby evidence - privacy boundary - verification command - next action ## Failure Paths To Preserve No note: > A marker without a human explanation is just another timestamp. Too many logs: > Focus on one marker id and nearby events. Sensitive storage: > Redact and rebuild. Metadata first. No nearby events: > Mark closer to the failure or adjust the nearby window deliberately. Patched APIs not restored: > Call `stop()` and test cleanup. No test export: > Expose the global in dev/test and wait for app readiness. ## Team Checklist Confirm the materials include: ```text mark -> capture -> explain -> review/export createAgentMarkers DebugSession DebugMoment CapturedEvent nearbyEventIds console capture fetch capture error capture manual evidence DOM hook screenshot hook privacy defaults storage metadata window.__AGENT_MARKERS__ export JSON download stop() npm test npm run typecheck npm run build npm run smoke:demo Playwright export Cypress export dev_marker dev_marker_explanation bounded replay capsule Section 9 bridge ``` ## Further References - team-facing file: `cheatsheets/08-debugging-with-agent-markers.md` - Exercises: `exercises/08-debugging-with-agent-markers.md` - Agent marker client: `packages/client/src/index.ts` - Collector: `packages/client/src/collector.ts` - Demo: `apps/demo/src/main.ts` - Smoke script: `scripts/smoke-demo.mjs` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-marker-workflows-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Context packing with Oracle and PackX: team walkthrough ## Team Learning Goal Teach this as a skill-backed workflow, not a PackX flag lecture. The audience should understand that `skills/oracle-packx/SKILL.md` is the operational contract. The cheatsheet explains when to use it, what it does, what to ask for, and how to inspect the result. ## Walkthrough Depth ### Essential Walkthrough 1. Show the software scenario: saved payment methods, billing webhook bug, or auth/session architecture review. 2. Show the bundled skill path: `skills/oracle-packx/SKILL.md`. 3. Explain that the skill owns PackX command construction and Oracle call shape. 4. Show the high-level pipeline: preview, bundle, browser Oracle, `output.log`, local artifact. 5. Show what the human must provide: outcome, scope, evidence, exclusions, success check. 6. Show how to know it worked. ### Expanded Walkthrough Add: - compact evidence - follow-up Oracle calls and prior-state ledger - why Oracle-created downloads are not the artifact - why `CLAUDE.md` is excluded ### Deep-Dive Walkthrough Add: - skim the PackX quick reference - show the common PackX capabilities table - discuss when this workflow is too heavy - start an exercise where team members write a skill invocation prompt for their own project ## Talking Points Opening: > You are not learning every PackX flag. You are learning when to hand a hard software question to a skill that knows how to build the packet. When showing the skill: > The skill is the source of truth. The cheatsheet is the mental map. When showing preview: > Preview is how the skill fails cheaply before spending the Oracle run. When showing `CLAUDE.md` exclusion: > Repo instructions can matter, but this workflow excludes `CLAUDE.md` and prefers deliberately scoped guidance. When showing compact evidence: > Some evidence should be summarized, not packed raw. When showing `output.log`: > The visible answer may be clipped. The skill requires the local agent to read the saved log before summarizing. ## Do Not Over-Explain - every PackX flag - tokenizer internals - browser automation implementation details - Oracle pricing or product speculation - every line of the skill - every possible PackX workflow ## Essential Points To Preserve - `oracle-packx` is a bundled skill. - The skill owns PackX and Oracle execution details. - The human supplies scope, evidence, exclusions, and desired software outcome. - The output is read from `output.log`. - The local agent writes the project artifact. ## Portable Pattern Table | John's local thing | Portable pattern | | --- | --- | | `skills/oracle-packx/SKILL.md` | skill as workflow contract | | PackX | deterministic context bundler | | `--preview` | inspect before sending context | | `~/.oracle/bundles/{slug}.txt` | local context packet | | Oracle browser mode | deliberate deep review surface | | `output.log` | saved full answer | | compact evidence | useful facts from raw material that should not be packed | | local artifact write | project output owned by the local environment | ## Bridge To Section 2 Close with: > Section 1 showed a skill that gives the agent the right project context. Section 2 is about making sure the agent can see the same shell environment and tools you expect it to use. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-context-packing-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Controlled variation workflows: team walkthrough ## Team Learning Goal Teach controlled variation as a decision workflow. The point is not “generate more.” The point is: ```text Generate comparable options, verify each option, then preserve the decision. ``` By the end of this section, the room should understand: - why cheap generation changes the workflow - why quality, integration, and verification are not free - how to choose one variable under test - how to write a variation matrix - why isolation matters before fan-out - why the same verification command must run for every candidate - how to decide Pick / Combine / Refine / Expand / Reject - how Section 5’s saved prompt becomes the seed - how Section 7 expands what can become prompt material ## Walkthrough Depth ### Essential Walkthrough 1. State: `Code is free` does not mean quality is free. 2. Teach the One Dimension Rule. 3. Show a billing webhook variation matrix. 4. Show the `artifacts/variations/<run-id>/` folder shape. 5. Show one verification command applied to all candidates. 6. End with Pick / Combine / Refine / Expand / Reject. Preserve: ```text goal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision ``` ### Expanded Walkthrough Add: - dirty repo checkpoint - Prompt Builder seed prompt - worktree isolation - candidate prompt overrides - comparison file ### Deep-Dive Walkthrough Add: - visible cmux fan-out - screenshots for UI candidates - convergence prompt from saved decision - failure paths - exercises ## Talking Points Opening: > Code is free does not mean quality is free. On variations: > Variation is a decision tool, not a procrastination tool. On the One Dimension Rule: > If every candidate changes everything, comparison teaches nothing. On verification: > Unverified candidates are just more text. On isolation: > Parallel work needs lanes. Without lanes, candidates overwrite each other. On Combine: > Combine still needs a primary candidate. Otherwise it becomes “take everything I liked” and scope explodes. Bridge from Section 5: > Section 5 made the prompt deliberate. Section 6 turns that prompt into comparable options. Bridge to Section 7: > We just learned to vary from one prompt. Next, we widen what can count as prompt material. ## Live Demo Script ### 1. Start With The Pattern ```text goal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision ``` ### 2. Write The Variable ```text We are comparing candidates that differ only by idempotency strategy. ``` ### 3. Create The Run Folder ```bash RUN_ID="billing-webhook-$(date +%Y%m%d-%H%M%S)" ROOT="artifacts/variations/$RUN_ID" mkdir -p "$ROOT"/{prompts,launch,logs,review,decisions} mkdir -p "$ROOT"/candidates/{v1,v2,v3} find "$ROOT" -maxdepth 3 -type d | sort ``` ### 4. Save A Prompt Builder Seed ```bash PROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.' p --print-prompt "$PROMPT" > "$ROOT/prompts/base.prompt.md" p --print-launch-json "$PROMPT" > "$ROOT/launch/base.launch.json" test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK" ``` ### 5. Check Repo State ```bash git status --short | tee "$ROOT/review/git-status-before.txt" git diff > "$ROOT/review/dirty-before.patch" git diff --staged > "$ROOT/review/staged-before.patch" ``` Presenter note: ```text Dirty state is not forbidden. Unknown dirty state is the problem. ``` ### 6. Show Same Verification ```bash VERIFY='pnpm test billing-webhook -- --runInBand && pnpm build' printf 'v1\t<status>\t%s\n' "$VERIFY" > "$ROOT/review/verification.tsv" printf 'v2\t<status>\t%s\n' "$VERIFY" >> "$ROOT/review/verification.tsv" printf 'v3\t<status>\t%s\n' "$VERIFY" >> "$ROOT/review/verification.tsv" column -t -s $'\t' "$ROOT/review/verification.tsv" ``` If real tests are too slow live, show the shape and say: > In a real project, this is where broken candidates get filtered before review. ### 7. Save The Decision ```bash cat > "$ROOT/decisions/selection.md" <<'EOF' # Saved Decision - outcome: Combine - primary candidate: v2 - secondary candidate ids: v1 - decision: Use v2 as the base and take v1's rollback guard. - final verification command: pnpm test billing-webhook -- --runInBand && pnpm build ## Continue Prompt Continue from this saved decision. Preserve v2 as the primary candidate. Apply only the named v1 rollback guard. Run final verification. EOF ``` ## Minimal Useful Path If 5 minutes behind, cut: - visible cmux fan-out - feature flag isolation - screenshots - convergence prompt command Preserve: - `Code is free` does not mean quality is free - One Dimension Rule - variation matrix - dirty repo checkpoint - same verification command - Pick / Combine / Refine / Expand / Reject If 10 minutes behind, skip worktree creation and use output folders only: ```bash mkdir -p "$ROOT"/candidates/{v1,v2,v3} ``` If 20 minutes behind, teach only: ```text One deliberate prompt becomes a matrix. The matrix changes one dimension. Each candidate gets isolation. Each candidate gets the same verification. The final decision is Pick, Combine, Refine, Expand, or Reject. ``` ## Boundaries ### From Section 5 Section 5 solves composition: ```text What exactly am I about to send? ``` Section 6 solves controlled fan-out: ```text What do I do after the prompt is good enough to become a seed? ``` ### To Section 7 Section 6 assumes the seed is mostly text plus project context. Section 7 expands the prompt material: ```text video can carry visual state, timing, workflow, cursor motion, and failure evidence ``` ## Failure Paths To Preserve Candidates drift: > Drift means the matrix was too weak or the candidate prompt was too loose. Stop and tighten the variable. Unverifiable options: > If you cannot verify the candidates, you are setting up a beauty contest. Define verification first. Dirty repo: > Dirty state is not forbidden. Unknown dirty state is the problem. Merge conflicts: > The selected candidate worked in isolation. Convergence has to protect that proof, not bulldoze it. Strongest idea split across candidates: > That is Combine. Pick a primary candidate and name the pieces you are taking. All candidates fail: > That is useful information. Reject the set or expand with a tighter prompt. Do not pretend one failed candidate won. ## Do Not Over-Explain Avoid spending time on: - every local helper - every possible git worktree cleanup command - full review UI implementation details - exhaustive parallel orchestration - model-provider comparisons - abstract creativity theory Keep the section practical: ```text matrix isolation fan-out verification review saved decision ``` ## Team Checklist Before considering this section ready, confirm the materials include: ```text Code is free quality is not free integration is not free verification is not free controlled variations One Dimension Rule good variables bad variables when to use variations when not to use variations goal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision variation matrix template Prompt Builder seed artifacts/variations/<run-id>/ base.prompt.md base.launch.json dirty repo checkpoint worktrees branches directories feature flags same verification command comparison notes diff review screenshots for UI test results Pick Combine Refine Expand Reject failure paths Section 7 bridge to video ``` ## Practice Launch Notes Good demo scenarios: | Scenario | Variable | | --- | --- | | checkout saved payment methods | UI integration strategy | | billing webhook duplicate-processing | idempotency strategy | | auth/session architecture | architecture boundary | | flaky regression coverage | test boundary | | checkout implementation | implementation alternative | Avoid: ```text make the app better improve architecture try some ideas fix everything ``` The cleanest live example is billing webhook idempotency because correctness, verification, rollback, and risk are easy to discuss. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-variation-workflows-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Fusion council decisions and evidence: team walkthrough ## Team Learning Goal Teach Fusion as a decision workflow. The goal is not to show every CLI flag. The goal is to teach when a hard software decision benefits from independent model disagreement, how to ask an agent for `$fusion`, and how to confirm the agent waited for council output before acting. By the end of this section, the room should understand: - Fusion is for expensive decisions, not tiny fixes - Local Fusion is inspired by the panel/finalizer pattern, but is not OpenRouter Fusion - the `$fusion` skill owns command details - the agent should list providers, write a prompt file, run the full configured panel, wait, and read final artifacts - partial panel output is not the answer - failed or quota-limited providers degrade the run instead of automatically invalidating it - the final engineering call still comes from repo evidence ## Walkthrough Depth ### Essential Walkthrough 1. State the core rule: use Fusion when disagreement improves the decision. 2. Show good and bad examples. 3. Show the local pipeline: prompt file -> panel -> finalizer -> `summary.json` / `final.md`. 4. Show the `$fusion` ask prompt. 5. Show how to confirm the agent waited. ### Expanded Walkthrough Add: - Local Fusion vs OpenRouter Fusion - Fable/model-disappearance lesson - provider terminal states - degraded panel behavior - artifact privacy boundary ### Deep-Dive Walkthrough Add: - live prompt-file build - provider list and dry-run - read sample `summary.json` - extract consensus/disagreement - exercise kickoff ## Talking Points Opening: > Fusion is not "ask more models because it feels fancy." Fusion is "this decision is expensive, so disagreement is worth buying." On partial output: > The first useful provider answer is not the council result. On local versus hosted Fusion: > OpenRouter Fusion is a hosted product. Local Fusion is a local CLI pattern that shells out to local provider CLIs. On Fable: > The Fable 5 shock is the lesson: do not make important workflows depend on one fragile model slug. On final authority: > Fusion advises. The repo decides. ## Live Demo Script Use a no-edit scenario. ### 1. Choose The Decision ```text Billing webhook duplicate-processing: provider event id guard vs invoice lock vs processing ledger. ``` ### 2. Draft A Prompt File ```bash mkdir -p .notes/fusion cat > .notes/fusion/billing-webhook-council.md <<'EOF' # Fusion Prompt ## Goal Choose the safest first implementation strategy for duplicate billing webhook processing. ## Current Evidence - paid invoice events may arrive more than once - current handler can process the same invoice twice - likely files: - src/billing/webhook.ts - src/billing/idempotency.ts - tests/billing/webhook.test.ts ## Candidate Strategies - provider event id guard - invoice-level processing lock - webhook processing ledger ## Constraints - preserve provider contract - avoid schema changes in first pass unless strongly justified - preserve existing invoice state transitions ## Verification - pnpm test billing-webhook -- --runInBand - pnpm build ## Ask Compare the strategies. Identify consensus, disagreement, hidden risks, missing tests, and the first shippable slice. End with a concrete recommendation and rollback notes. EOF ``` ### 3. Preflight ```bash fusion-high --list-providers fusion-high --dry-run --file .notes/fusion/billing-webhook-council.md ``` ### 4. Run ```bash fusion-high --file .notes/fusion/billing-webhook-council.md ``` ### 5. Confirm Ask the agent to report: - Fusion session - `summary.json` - `final.md` - provider terminal states - consensus - disagreement - chosen path - verification ## Minimal Useful Path If 5 minutes behind, cut: - live run - OpenRouter benchmark numbers - custom configs If 10 minutes behind, cut: - provider terminal state details - artifact list If 20 minutes behind, keep only: - when to use Fusion - `$fusion` ask prompt - wait for `summary.json` and `final.md` - Local Fusion is not OpenRouter Fusion ## Boundaries With Neighboring Sections From Section 1: ```text Oracle PackX is for broad packed context and one expensive external review. Fusion is for local independent model disagreement on a bounded decision. ``` From Section 5: ```text Prompt Builder composes before launch. Fusion can consume a prompt file produced by any deliberate composition workflow. ``` From Section 6: ```text Section 6 compares generated implementation candidates. Fusion compares independent critiques and strategy recommendations before implementation. ``` To Section 9: ```text Imps are narrow one-tool agents. Fusion is a council. Do not send one-tool lookup work to Fusion. ``` ## Careful Origin Wording Say: ```text Local Fusion is inspired by the OpenRouter-style panel and judge/finalizer pattern. ``` Do not say: ```text Local Fusion is OpenRouter Fusion. ``` Say: ```text OpenRouter reported strong DRACO results for Fusion on deep research tasks. ``` Do not say: ```text Fusion always beats a single model. ``` Say: ```text OpenRouter cautions that Fusion should be used selectively for hard questions. ``` Do not say: ```text Fusion replaces coding agents. ``` Say: ```text The Fable availability change is the practical lesson about fragile single-model workflows. ``` Do not claim a precise causal story unless the cited source proves it. ## Failure Paths To Preserve Agent skipped provider list: ```bash fusion-high --list-providers ``` Agent used inline long prompt: ```text Ask for a prompt file and --file. ``` Agent started implementation early: ```text Stop and request summary.json, final.md, provider terminal states, consensus, and disagreement. ``` One provider quota-limited: ```text Explain degraded council behavior. The run can still be useful if final artifacts exist and the missing voice is named. ``` Final answer flattened disagreement: ```text Ask for consensus, contradictions, hidden risks, and which repo evidence decides. ``` Private artifact risk: ```text Do not paste full session artifacts. Summarize the relevant council result. ``` ## Team Checklist Confirm the materials include: - `$fusion` skill path - common local source checkout - OpenRouter inspiration boundary - not the same product - not for tiny fixes - provider list first - prompt file - dry-run when uncertain - full configured panel - terminal provider states - `summary.json` - `final.md` - quota non-blocking - partial artifacts are partial - private session store - advisory output - repo evidence wins - billing webhook example - auth/session example - model outage fallback example ## Further References - File: `cheatsheets/10-fusion-model-council.md` - Exercise: `exercises/10-fusion-model-council.md` - Skill: `skills/fusion/SKILL.md` - Common local source checkout: `~/dev/fusion` - OpenRouter Fusion product page: https://openrouter.ai/fusion - OpenRouter Fusion model page: https://openrouter.ai/openrouter/fusion - OpenRouter announcement: https://openrouter.ai/blog/announcements/fusion-beats-frontier/ - OpenRouter model-disappearance post: https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/ ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-fusion-workflows-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Interview for judgment and build for agency Agent-heavy work eventually comes back to the human side of software practice. Not "which model wins?" and not "will developers matter?" The useful question is smaller: when agents can write more code, what do people still need to **judge, critique, own, and verify**? ## Judgment Stays Human For product software, **the durable skill is judgment**: - understand the user - critique the experience - communicate clearly - decide where agents help - decide where agents hurt - keep control of the tools - verify the result The point is not to replace technical ability with taste. The point is to **connect technical work to product reality**. ## Interview With A Product Flow A useful interview exercise can be simple: > I would open up a website and just have someone critique it. Have them go through a few websites, have them click around. And not even find bugs, just find what they think could improve from the user experience. > > — John Lindquist Open a real website or app. Ask the candidate to click through one flow, describe who the product serves, critique the experience, and connect that critique back to engineering decisions. Then add the agent layer: - Where could an agent improve this experience? - Where could an agent make it worse? - What should remain human-reviewed? - What would you ask an agent to do first? - How would you phrase the prompt so the work stays bounded? Traits to look for: | Trait | What To Look For | |---|---| | Product judgment | Can they tell what the product is for? | | Communication | Can they explain the critique clearly? | | Critique quality | Can they identify tradeoffs without just dunking on the UI? | | User understanding | Can they connect features to user needs? | | Agent judgment | Can they name where agents improve or damage the workflow? | | Prompt framing | Can they turn critique into bounded agent work? | ## Speculation Is Not A Roadmap Near-term AI predictions should **read as speculation**. Cheaper access to capable open models may reduce the need for some hand-built skills, video pipelines, and helper scripts. Agents may get better at noticing repeated work and creating small tools from the flow of a project. Maybe. That is **a direction to watch, not a roadmap commitment**. Memory and tool self-improvement are moving targets. Teams are still figuring out how agents should remember past conversations, project state, repeated tool needs, and decisions that should shape future work. Do not present current model-roadmap, pricing, capability, or provider behavior claims as fact unless they are freshly verified. ## Fatigue Is About Control AI fatigue grows when AI feels **forced, opaque, or outside the user's control**. > People generally get frustrated with AI when it's forced upon them, and when it's something that they haven't made themselves. And they don't feel like they have control over it. > > — John Lindquist The answer is not "use more AI." The better answer is **agency**: - adapt the tool - own the loop - inspect the result - measure whether it helped - keep review points visible - make automation opt-in where the decision matters Software examples: - A checkout team adds a tiny local wrapper that always loads failing test output before asking an agent to patch. - A billing team builds a review command that compares webhook strategies and requires proof commands. - An auth/session team adds a project-local checklist before letting an agent touch token rotation. - A UI team turns repeated design critique into a decision surface instead of asking the same chat prompt every day. Local tools can change the feeling of the work because the developer can **adapt the loop and see whether the change actually helped**. ## Ethics Boundary Ethical concerns around AI are real and should not be waved away. A practical workflow does not need to settle training data, copyright, compensation, platform power, or labor questions. It does need to avoid pretending those concerns do not exist. The practical workflow boundary is smaller: - review what goes into the tool - keep private material private - preserve human choice - make review points visible - do not make automation mandatory by default - leave room for people to say no This does not solve the broader ethical questions. It keeps the local workflow honest. ## Copyable Artifact: Product Judgment Interview Packet ```text Candidate exercise: - Open a real website or app. - Click through one user flow. - Explain who the product appears to serve. - Name what the flow is trying to help the user accomplish. Critique: - What works? - What is confusing? - What user need is underserved? - What engineering choice might be causing the friction? - What evidence would you inspect before changing it? Agent fit: - Where could an agent improve the experience? - Where could an agent make it worse? - What should remain human-reviewed? - What should the agent not infer? Prompt: - Ask the candidate to write the first agent prompt. - Require scope, files or surfaces to inspect, constraints, proof, and stop condition. Evaluation: - Product judgment: - Communication: - Critique quality: - User understanding: - Agent boundary judgment: - Prompt clarity: ``` ## Close The Loop The useful follow-up is concrete: - segmented recording - reference links - setup notes - open questions - verification gaps - next actions Do not end with a prediction cloud. End with the materials needed to keep working. ## Claim Boundaries Avoid broad labor-market claims. Avoid exact model labels, provider claims, price claims, memory-system claims, or capability predictions unless freshly verified. Keep the final message narrower and stronger: judgment, agency, review boundaries, and measurable software work still matter. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#judgment) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-judgment Topic: Team practice Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#judgment) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Narrow Imp agents and routing: team walkthrough ## Team Learning Goal Close the workshop by showing where bounded, tool-specific packets go next. The core idea: ```text An Imp is a narrow tool agent that should run the tool before it talks. ``` By the end of this section, the room should understand: - regular Codex vs Imp - when a task is tool-shaped - how to route before running - direct vs noninteractive vs quiet modes - warm mode and fleet management - isolation boundaries - evolution suggestions as review material - how a Section 8 marker packet becomes an Imp task - the current dash-prefix workflow: ```text -<imp> -> foreground route with hook-provided context --<imp> -> fork current Codex conversation into a cmux pane ``` The teaching point is not "memorize a hook." The teaching point is routing: keep broad reasoning in regular Codex, send bounded tool work to an Imp, and fork when the bounded task should run separately. ## Walkthrough Depth ### Essential Walkthrough 1. State the core sentence. 2. Compare regular Codex vs Imp. 3. Run `imp -l`, `imps doctor`, `imp --which`. 4. Show `-rg find TODOs in src` as a foreground route. 5. Show `--rg find TODOs in src` as a fork route only if cmux is working. 6. Use the cmux check commands from the block message. 7. Close with the 9-section workflow. ### Expanded Walkthrough Add: - compound routing - `--run`, `-q`, `--no-warm`, `--serve` - fleet commands - isolation model table ### Deep-Dive Walkthrough Add: - prompt design pattern - evolution suggestions - failure paths - exercises ## Talking Points Opening: > An Imp is a narrow tool agent that should run the tool before it talks. On narrowness: > If the request needs broad reasoning, it is not an Imp task yet. On routing: > `imp --which` is the cheap check before spending a turn. On isolation: > The isolation model keeps an Imp from becoming your whole Codex environment. On Section 8: > A marker packet gives us the terms and boundary. The Imp runs the tool-shaped part. ## Live Demo Script ### 1. Health ```bash imp -l imps list imps ps imps doctor ``` ### 2. Routing ```bash imp --which "what changed in git since yesterday?" imp --which "find the TODOs in src; then commit everything" ``` ### 3. Direct Imp ```bash imp-rg --run "find TODOs in src" ``` ### 4. Dash-Prefix Demo Foreground route: ```text -rg find checkout disabled-state code paths ``` Say: > Single dash keeps the main agent responsible. The hook resolves the Imp and gives the agent the path, description, task, and cwd. Fork route: ```text --rg find checkout disabled-state code paths ``` Say: > Double dash blocks this prompt and opens a fork. The fork receives the normalized single-dash prompt. Inspect the fork with the commands printed by the block message: ```bash cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80 cmux top --workspace workspace:<id> --processes --flat --format tsv cmux focus-pane --workspace workspace:<id> --pane pane:<id> ``` ### 5. Marker Packet Bridge ```bash imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled" ``` Then: ```bash imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used." ``` ### 6. Safety Net ```bash bun test ``` ## Minimal Useful Path If 5 minutes behind, cut: - evolution suggestions - warm app-server internals - new Imp design exercise - detailed isolation flags - live `--<imp>` fork demo if cmux is not working Preserve: - core sentence - regular Codex vs Imp - `imp --which` - direct `imp-rg --run` - `-<imp>` foreground route - fleet health - Section 8 marker packet bridge If cmux is unavailable, explain the block/fork contract and show the expected receipt shape instead: ```text cmux workspace: workspace:<id> cmux pane: pane:<id> cmux surface: surface:<id> cmux window: window:<id> ``` ## Boundaries Do not turn this into: - a full source-code tour - an implementation session for new Imps - broad Codex routing theory - a replacement for Section 4 orchestration Keep the scope: ```text one tool one operating rule one command map command evidence bounded output ``` ## Failure Paths To Preserve Wrong Imp: > Run `imp --which`, then use an explicit route. Too broad: > Send the broad part back to regular Codex. No command evidence: > Strengthen the operating rule and worked examples. Warm stale: > `imps ps`, `imps stop <imp>`, `imps doctor`. Evolution unsafe: > Treat suggestions as review material, not automatic updates. Dash prompt parsed as option: > Do not route dash-prefix prompts through stale `p-f` or resume helper paths. Use direct `codex fork <source-session> -- '-imp ...'`. No cmux ids: > Treat the fork as unverified. Check `cmux-run-surface`, `cmux rpc workspace.current`, and the hook log. ## Team Checklist Confirm the materials include: ```text single-purpose isolated Codex agents not smaller general agents one tool one operating rule one command map real commands first regular Codex vs Imp imp -l imps list imps ps imps doctor imp --which imp-rg --run -q --no-warm --serve --effort compound routing imps stop imps evolve temporary CODEX_HOME auth.json symlink base instructions replaced project docs disabled memories disabled MCP empty web search disabled apps disabled warm app-server socketPath sourceFingerprint CODEX_IMP_IDLE_MINUTES Operating rule Command map Worked examples Error recovery Output rules Section 8 marker packet bun test ``` ## Closing Line ```text The workshop starts by packing broad context and ends by shrinking finished evidence into tool-shaped work. ``` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-imp-workflows-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Product vision and earned automation Keep product direction durable without freezing implementation, and promote recurring reviews only when their signal earns it. ## Separate product direction from operating instructions `VISION.md` describes the user, intended outcome, product qualities, durable constraints, and open decisions. Code remains implementation truth. `AGENTS.md` can instead describe how an agent operates. Do not silently merge those roles or treat an old architectural diagram as a permanent restriction. For a concrete task, make adherence explicit: **Preserve / May change / Must ask / Verification**. Strict refactoring constraints and open-ended improvement are different contracts. An agent can improve the architecture without abandoning the product’s end ideal. ## Keep automation at the lowest justified stage The promotion ladder is **manual run → deterministic script → bounded agent → non-blocking CI report → blocking gate**, with schedules and human approval as deliberate choices rather than inevitable destinations. Every promotion needs an owner, evidence threshold, false-positive tolerance, latency and cost boundary, stop condition, and recovery path. Collect repeated manual receipts before making a result blocking. General curation and review schedules can become noise; useful on-demand execution is better than automated interruption without a decision to change. ## Operating practice ### Let vision guide automation #### What to notice Keep code as **implementation truth** while giving agents **durable product direction** and an explicit adherence dial. #### Try this Draft VISION.md from product evidence, then mark Preserve, May change, Must ask, and Verification for one task. > “Code is a source of truth.” John Lindquist · [05:35:33](https://proud-anchor-53zn.here.now/watch.html?t=20133#recording-player) #### Concept Vision describes the user, outcome, qualities, durable constraints, and open decisions. It should guide improvement without freezing a stale architecture into permanent context. #### Reflection VISION.md and AGENTS.md can serve different roles. Do not silently collapse product direction and operating instructions. **Recording evidence:** listen at 05:25:50. > “This defines the end ideal of this product. And no matter what the state of the product is in, it can always push more towards that vision.” John Lindquist · [05:37:00](https://proud-anchor-53zn.here.now/watch.html?t=20220#recording-player) #### Links shared for this topic - [Workshop NotebookLM notebook](https://notebooklm.google.com/notebook/4ae3bcdd-b31b-4e2b-af19-7e6c702c6cc7) — The research notebook and generated artifacts shown near the close. - [Handy](https://handy.computer/) — A dictation tool shared during the VISION.md discussion. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=19550#q4-vision-automation) Reference ID: factory-vision-and-automation Topic: Team practice Sources: - [Vision and automation lesson](https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation) --- # Product vision and earned automation — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### NotebookLM Artifact Generation Ingesting workshop transcripts and notes into Google NotebookLM to auto-generate slide decks, summaries, mind maps, and audio podcasts. ### Real-Time Voice Brainstorming vs. Static Audio Overviews Comparing pre-rendered podcast summaries with interactive, real-time voice conversations (e.g. ChatGPT Voice Mode) for exploratory engineering discussions. ### Multi-Agent Terminal Orchestration Architecting AI workflows where a manager pane coordinates specialized daemons (server log, source code, browser proof) using CLI tools like cmux. ### Mermaid Diagrams for Agent Context A markdown-based structural diagramming syntax previously used to force models into structural alignments, now viewed by the presenter as a limiter. ### Documentation Drift The challenge where text documentation, wikis, or initial architectural specs become rapidly outdated due to active code iteration by AI models. ### Sliding Scale Prompt Alignment A prompt design strategy enabling the developer to modulate how tightly the agent must adhere to strict refactoring bounds versus creative performance improvement. ### Google AI Subscription Tiers Evaluating Google AI Pro vs Ultra tiers, including usage multipliers, storage limits, and bundled services like YouTube Premium. ### Agent Primitive Task Overhead Conversational agents like Gemini on Android failing at introductory examples (e.g. setting timers) when forced into complex agent execution loops. ### Documentation Drift The misalignment that occurs when documentation, wikis, or architectural diagrams lag behind actual code changes and team decisions. ### vision.md Specification Concept A proposed project file (vision.md) defining high-level product goals, user experience, demographics, and values without prescribing technical restrictions for AI agents. ### Vision Document (VISION.md) A high-level document defining the ultimate ideal state and objectives of a product, providing direction for AI agents regardless of tech stack changes. ### Agentic Automation Delegating complex multi-step creative or research workflows (such as image simplification or GitHub repository analysis) to AI agents. ### Developer Voice Dictation Workflows Using speech-to-text dictation software (Super Whisper, WhisperFlow, Handy) to stream natural language prompts directly into CLI agent interfaces. ## Questions and answer status ### Can a single mermaid graph effectively serve both machine context injection and human readable documentation, or should we treat element-facing context architecture entirely separate from human-facing notes? **Status: partial.** John begins explaining that human readability and machine prompt context requirements differ in code/context projects; the full explanation continues in the next shard. ### Can a single mermaid graph effectively serve both machine context injection and human readable documentation, or should we treat element-facing context architecture entirely separate from human-facing notes. **Status: answered.** John explains that keeping fixed mermaid diagrams for agents is an anti-pattern because it unnecessarily limits the agent from finding better architectural configurations. ### Does that require ultra subscription? Do you find value in the ultra subscription? **Status: partial.** John is unsure of the precise distinction in value-add between Pro and Ultra subscription tiers, which leads him to perform a live search query. ### Does video analysis require an Ultra subscription, and is Ultra worth it? **Status: answered.** Video analysis is available on Google AI Pro. Ultra offers higher usage limits, but Pro combined with YouTube Premium family sharing provides the primary value for his workflow. ### What’s the name of the document again? The one for documentation **Status: answered.** John answers that the file is vision.md (or agents.md), as confirmed in the discussion. ## Exercises - **Try:** Browse the shared NotebookLM workspace to review workshop sources and generated artifacts. **Basis:** John posts link in chat at 05:26:41 and invites attendees: 'So if you want to browse this, I was able to dump in all of this text and everything in here' (05:26:40). ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [05:27:10](https://proud-anchor-53zn.here.now/watch.html?t=19630#recording-player) — John compares NotebookLM Audio Overviews to real-time ChatGPT voice mode. - [05:28:38](https://proud-anchor-53zn.here.now/watch.html?t=19718#recording-player) — John exits slideshow view and comments on Google's strengths in notebook/video assets vs lagging coding features. - [05:29:02](https://proud-anchor-53zn.here.now/watch.html?t=19742#recording-player) — John reads a participant's question regarding single Mermaid graph context injection vs separate human notes. - [05:29:31](https://proud-anchor-53zn.here.now/watch.html?t=19771#recording-player) — John Lindquist contrasts writing documentation for agents versus writing it for human developers. - [05:29:39](https://proud-anchor-53zn.here.now/watch.html?t=19779#recording-player) — John states that he no longer advocates for Mermaid diagrams to exist beyond an initial prompt pass. - [05:30:10](https://proud-anchor-53zn.here.now/watch.html?t=19810#recording-player) — John mentions that Fable models can be smarter than the user, so strict adherence to human diagrams restricts alternative better solutions. - [05:31:06](https://proud-anchor-53zn.here.now/watch.html?t=19866#recording-player) — a participant notes agreement in chat that initial concepts, wikis, or mermaid diagrams cause documentation drift. - [05:31:06](https://proud-anchor-53zn.here.now/watch.html?t=19866#recording-player) — John states that modern AI experts consider AgentsMD and ClaudeMD to be anti-patterns because they limit instead of guardrail. - [05:31:55](https://proud-anchor-53zn.here.now/watch.html?t=19915#recording-player) — John explains his experimentation with adding a sliding scale to initial user prompts to control adherence to established patterns vs code improvement. - [05:32:51](https://proud-anchor-53zn.here.now/watch.html?t=19971#recording-player) — John receives and reads a question about whether this method requires an Ultra subscription and its value add. - [05:33:19](https://proud-anchor-53zn.here.now/watch.html?t=19999#recording-player) — Chrome browser shows Google search result AI Overview comparing Google AI Pro ($19.99/mo) and Google AI Ultra ($200-$250/mo). - [05:33:29](https://proud-anchor-53zn.here.now/watch.html?t=20009#recording-player) — John Lindquist discusses usage limits, YouTube Premium, and Google Drive storage. - [05:33:34](https://proud-anchor-53zn.here.now/watch.html?t=20014#recording-player) — John highlights text under Google AI Ultra regarding 20 TB - 30 TB Drive/Photos storage capacities. - [05:33:39](https://proud-anchor-53zn.here.now/watch.html?t=20019#recording-player) — John highlights text detailing YouTube Premium individual plan and Google Home Premium Advanced perks. - [05:33:43](https://proud-anchor-53zn.here.now/watch.html?t=20023#recording-player) — John highlights text describing 20x higher usage limits across Gemini, Project Genie, and Google Antigravity. - [05:33:58](https://proud-anchor-53zn.here.now/watch.html?t=20038#recording-player) — John states he believes video analysis is available on the Pro plan. - [05:34:07](https://proud-anchor-53zn.here.now/watch.html?t=20047#recording-player) — John explains sharing YouTube Premium across 5 different Google accounts for family members. - [05:34:32](https://proud-anchor-53zn.here.now/watch.html?t=20072#recording-player) — John states he derives the most value from video analysis in Gemini and YouTube family sharing. - [05:34:40](https://proud-anchor-53zn.here.now/watch.html?t=20080#recording-player) — John describes using Gemini on Android via side button for checking email and scheduling events. - [05:34:53](https://proud-anchor-53zn.here.now/watch.html?t=20093#recording-player) — John notes Gemini fails on simple tasks like timers because it invokes an agent workflow. - [05:35:12](https://proud-anchor-53zn.here.now/watch.html?t=20112#recording-player) — John reads audience comment regarding wikis, diagrams, agent constraints, and documentation drift. - [05:35:25](https://proud-anchor-53zn.here.now/watch.html?t=20125#recording-player) — John agrees documentation drift is an important problem in evolving projects. - [05:35:33](https://proud-anchor-53zn.here.now/watch.html?t=20133#recording-player) — John emphasizes that code is the source of truth. - [05:36:05](https://proud-anchor-53zn.here.now/watch.html?t=20165#recording-player) — John proposes placing a vision.md file in repositories to outline ideal product scenarios, target demographics, and experiences. - [05:36:34](https://proud-anchor-53zn.here.now/watch.html?t=20194#recording-player) — John highlights that vision.md should provide broad aspirational guidance rather than technical restrictions. - [05:36:55](https://proud-anchor-53zn.here.now/watch.html?t=20215#recording-player) — John explains that a vision document defines the ideal end goal of a product so agents can keep moving towards it. - [05:37:31](https://proud-anchor-53zn.here.now/watch.html?t=earlier-generation1#recording-player) — John tells a story about using Fable AI agent to convert a student roadrunner crayon drawing into a printable white graphic for elementary school t-shirts. - [05:37:39](https://proud-anchor-53zn.here.now/watch.html?t=earlier-generation9#recording-player) — a participant asks in chat: 'What’s the name of the document again?' - [05:39:15](https://proud-anchor-53zn.here.now/watch.html?t=20355#recording-player) — John answers that the file is vision.md or agents.md. - [05:39:37](https://proud-anchor-53zn.here.now/watch.html?t=20377#recording-player) — John launches Claude Code v2.1.212 using command cl3. - [05:39:49](https://proud-anchor-53zn.here.now/watch.html?t=20389#recording-player) — John uses Super Whisper voice dictation to speak prompt to Claude Code asking to search for VISION.md files using gh cli. - [05:40:04](https://proud-anchor-53zn.here.now/watch.html?t=20404#recording-player) — John discusses voice dictation tools, mentioning Super Whisper, WhisperFlow, and Handy. - [05:40:12](https://proud-anchor-53zn.here.now/watch.html?t=20412#recording-player) — Claude Code executes gh search code command to find VISION.md files on GitHub. ### Unresolved: NotebookLM MCP integration with Gemini CLI ('anti-gravity') Presenter mentions this speculatively ('I think it's an MCP between Notebook and The Gemini agent? Once they get it inside of anti-gravity...'). **Discriminating evidence:** Presenter conjecture on potential future features; no external verification required. ### Unresolved: Exact bash script loop generated inside Claude Code scratchpad The right edge of the terminal command text is cut off by the window boundary. **Discriminating evidence:** Recorded verified visible command prefix; left full script unextrapolated. ### Demonstration detail: 05:26:03 - Navigate to notebooklm.google.com - Open share modal and set public link access - Copy and post notebook URL to Zoom chat - Inspect Sources panel and Studio artifact section - Launch full-screen presentation mode for 'The Orchestrated Developer' slide deck - Page through 12 generated presentation slides **Tools observed:** NotebookLM, Google Chrome. **Command or prompt observations (not a verified recipe):** ```text cmux --json tree cmux new-split right cmux read-screen ``` ### Demonstration detail: 05:33:13 - Opened a new Google Chrome browser tab. - Typed 'google pro vs ultra' into the address bar. **Tools observed:** Google Chrome Omnibox. ### Demonstration detail: 05:33:19 - Browsed Google Search AI Overview comparing Google AI plans. - Highlighted plan details on screen. - Opened a new tab and typed VISION.md into address bar to check search results. **Tools observed:** Google Chrome, Google Search. ### Demonstration detail: 05:39:29 - Switched to Ghostty terminal - Ran cl3 to open Claude Code CLI v2.1.212 - Dictated prompt using Super Whisper - Observed Claude Code executing gh search code and gh api script **Tools observed:** Ghostty, tmux, Claude Code v2.1.212, Super Whisper, GitHub CLI. **Command or prompt observations (not a verified recipe):** ```text cl3 Do a gh cli search for "VISION.md". Please show all the variations on how people are using these files and what their purposes are. gh search code --filename VISION.md --limit 50 --json repository,path | jq -r '.[] | "\(repository.nameWithOwner) \(path)"' | sort -u ``` Reference ID: factory-vision-and-automation-discussion Topic: Team practice Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Prompt Builder composition and handoff: team walkthrough ## Team Learning Goal Teach Prompt Builder as the composition boundary between routed context and agent execution. By the end of this section, the room should understand: - why `p` exists - how it fits after Section 4 routing - how to inspect prompt text, command shape, and launch JSON - why named launches use app-server thread creation and `thread/name/set` - why handoff mode passes the prompt as a safe final argv element - when to choose `xfl` / `xfc` versus `p-f` / `p-c` - how Section 6 uses one deliberate prompt as a variation seed Keep this section practical. It is not a Rust code tour. ## Walkthrough Depth ### Essential Walkthrough 1. State: Prompt Builder is the preflight before an agent launch. 2. Prove install: `which -a prompt-builder p`, versions. 3. Show `p --print-prompt "hello"`. 4. Show `p --dry-run --print-command "hello"`. 5. Show named launch JSON with `--name`. 6. Show handoff JSON with `/bin/echo`, `--fork-from`, and `--compact`. 7. Bridge to `p-f` and `p-c`. Preserve these commands: ```bash which -a prompt-builder p prompt-builder --version p --version p --print-prompt "Review the checkout flow." p --dry-run --print-command \ "Debug the billing webhook duplicate-processing bug." p --print-launch-json \ --name "Auth review" \ "Review auth/session architecture." \ | jq '.mode, .env, .app_server' p --print-launch-json \ --handoff-command /bin/echo \ --fork-from last \ --compact \ "continue from here" \ | jq '.mode, .argv' ``` ### Expanded Walkthrough Add: - interactive `p` - Name field - Tab movement through Name, Prompt, and options - `@` file selector - `$` skills lookup - `/` slash command popup - `Shift+Enter` - bracketed paste behavior - `Ctrl+C` clear-before-exit ### Deep-Dive Walkthrough Add: - `--stdin` plus prefilled text - app-server named thread explanation - `CODEX_THREAD_NAME` - `PROMPT_BUILDER_CODEX_BIN` - shell-function handoff through `zsh -lc` - debug paths for missing `p`, wrong binary, missing zsh functions, and quoting issues - exercise kickoff ## Talking Points Opening: > We already solved routing. Now we solve what we are actually sending. Core sentence: > Prompt Builder is the checkpoint between "I have a thought" and "I am launching an agent with authority." On inspection modes: > `--print-prompt` saves what you said. `--print-command` shows what a human would run. `--print-launch-json` gives scripts the raw shape without parsing shell quotes. On `--name`: > Naming is not a prompt trick. Prompt Builder creates a thread, calls `thread/name/set`, and then resumes that thread with the prompt. On handoff: > Handoff is argv construction, not shell interpolation. The prompt is passed with `Command::arg` as the final argv element. On `p-f` and `p-c`: > `xfl` and `xfc` act now. `p-f` and `p-c` let you compose first. On Section 6: > One careful prompt becomes the seed for controlled variations. A sloppy prompt produces sloppy variations faster. ## Live Demo Script ### 1. Prove The Binary ```bash which -a prompt-builder p prompt-builder --version p --version ``` Presenter note: do not dwell on install paths. The important proof is that both commands resolve and match. ### 2. Print A Prompt ```bash p --print-prompt \ "Review the checkout flow for saved payment method regressions." ``` Presenter note: this is the cleanest Section 6 bridge. ### 3. Preview A Command ```bash p --dry-run --print-command \ "Debug the failing checkout test and identify the smallest safe fix." ``` Presenter note: point at `-C .` and the final prompt argument. ### 4. Preview A Named Thread ```bash p --print-launch-json \ --name "Checkout saved payments" \ "Plan the first shippable slice." \ | jq '.mode, .env, .app_server' ``` Call out: ```text app-server-named-thread CODEX_THREAD_NAME thread/name/set ``` ### 5. Preview Handoff ```bash p --print-launch-json \ --handoff-command /bin/echo \ --handoff-arg wrapper \ --fork-from last \ --compact \ "continue from here" \ | jq '.mode, .argv' ``` Call out: ```text wrapper args first toggle args next prompt last ``` ### 6. Prove Zsh Helper Bridge ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc' ``` Presenter note: shell functions are not binaries. This is why `p-f` and `p-c` hand off through `zsh -lc`. ## Boundaries | Prior Section | What It Solved | Prompt Builder Adds | | --- | --- | --- | | Section 1 | package the right project context | compose the implementation request | | Section 2 | make tools visible to Codex | prove `prompt-builder`, `p`, and Codex resolve | | Section 3 | classify aliases/functions/executables | hand off safely to zsh functions | | Section 4 | route pane/session/fork/export | compose before fork or compact | Bridge line from Section 4: ```text Section 4 gets us to the right session. Section 5 makes sure the next prompt is worth sending. ``` Bridge line to Section 6: ```text Section 5 ends with a deliberate prompt. Section 6 varies that prompt under control instead of improvising unrelated asks. ``` ## Minimal Useful Path If 5 minutes behind, cut: - `PROMPT_BUILDER_DEBUG_KEYS` - detailed slash command list - custom `--launch-option` - Rust module references Preserve: ```bash which -a prompt-builder p p --print-prompt "hello" p --dry-run --print-command "hello" p --print-launch-json --name "Demo" "hello" | jq '.mode, .env' p --print-launch-json --handoff-command /bin/echo --fork-from last --compact "continue" | jq '.mode, .argv' ``` If 10 minutes behind, skip the interactive composer and say: ```text The TUI matters for real use, but the inspection modes teach the contract fastest. ``` If 20 minutes behind, run only: ```bash which -a prompt-builder p p --print-launch-json --name "Demo" "hello" | jq '.mode, .env, .app_server' p --print-launch-json --handoff-command /bin/echo --fork-from last --compact "continue" | jq '.mode, .argv' ``` Closing line if rushed: ```text Compose first, prove the launch shape, then submit. ``` ## Debug Paths To Mention Missing `p`: ```bash which -a prompt-builder p ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p p --version ``` Wrong build: ```bash cargo install --path . --locked --force which -a prompt-builder p prompt-builder --version p --version ``` Wrong Codex binary: ```bash PROMPT_BUILDER_CODEX_BIN=/bin/echo \ p --submit --dry-run --print-command \ "hello override" ``` Missing zsh function: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w xfc p-f p-c' ``` Quoting / final argv: ```bash p --print-launch-json \ --handoff-command /bin/echo \ "fix this and keep \$HOME literal" \ | jq '.argv' ``` ## Presenter Boundaries Do not over-explain: - Ratatui internals - every slash command - full app-server protocol - every function in `40-ai.zsh` - Rust module architecture beyond what explains behavior - every possible Codex flag Emphasize: - exact prompt text - exact argv - exact launch mode - named thread flow - safe handoff - `p-f` / `p-c` as compose-before-action helpers - Section 6 seed prompt ## Team Checklist Before considering this section ready, confirm the materials include: ```text Prompt Builder preflight composition boundary prompt-builder p which -a prompt-builder p prompt-builder --version p --version cargo install --path . --locked --force --stdin --submit --print-prompt --print-command --print-launch-json --dry-run --name CODEX_THREAD_NAME app-server-named-thread thread/name/set --handoff-command --handoff-arg Command::arg final argv --fork-from --compact --launch-option p-f p-c p-cm xfl xfc zsh -lc 40-ai.zsh @ file selector skills slash commands Shift+Enter bracketed paste Ctrl+C PROMPT_BUILDER_CODEX_BIN Section 6 ``` ## Further References - team-facing file: `cheatsheets/05-prompt-builder.md` - Exercises: `exercises/05-prompt-builder.md` - Zsh helper file: `zsh/conf.d/40-ai.zsh` - Prompt Builder checkout: `README.md`, `src/cli.rs`, `src/main.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, `src/app_server_launch.rs`, `src/composer_input.rs` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-prompt-composition-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Questions, answers, and unresolved decisions The complete anonymized question reference, preserving answered, partial, deferred, unlinked, and unanswered status. ## Open weight catches up. Do you think we’ll get another week of Fable given this news? **Status: answered.** John states he hopes so because Fable uniquely interprets and handles his layout and UX engineering tasks cleanly. ## Re: models better at finding code, how much is better grep-ing, and how much is agents now using LSPs, etc? **Status: deferred.** The question is left deferred during this specific segment as the presenter is explaining the historical piping model. ## Would you recommend collecting external pages, then recreating that on here.now as my own example that will never change, then? **Status: answered.** Yes, John fully recommends saving references, bookmarks, screenshots, or dictations of inspiring items to build an unalterable personal source collection. ## What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster? **Status: partial.** John answers that this design pattern is commonly referred to as 'human in the loop' (HITL), with further details extending into the following segment. ## Can you use pi with Claude Code subscription? **Status: answered.** John indicates that while you can technically run this configuration, he avoids doing so because Anthropic cracks down on using third-party harnesses with subscription tiers. ## When swapping between models using pi, when do you let a model bake versus adopting on day 1, like Kimi? For day 1 adoption, what low-risk actions avoid controversy, and how do you gradually scale up risk? **Status: answered.** John shares that his approach to day-one adoptions for new models like Kimi involves feeding them low-risk, self-contained creative tasks such as generating independent web arcade mini-games. ## Working with claude code in VS code... still like to see what's happening but apparently that's a bit obsolete with models like fable 5? **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## When do you transition to larger batched staging or production interaction, like mutating or deleting a database, and what must you observe before taking that risk? What is absolutely off-limits hard stop versus an acceptable risk? **Status: answered.** The developer should construct a comprehensive logging matrix, perform numerous dry runs to explicitly review downstream output variations, and inspect observable results before conducting live mutation tasks. ## What is linear? A link is fine **Status: answered.** Students in the chat clarify that Linear is a modern, high-performance project management alternative to Jira, providing the direct URL link. ## Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available. **Status: partial.** John shows that his public GitHub dotfiles repository is obsolete, shows his local structured setup instead, and mentions he wants to review it before publishing it properly. ## When there’s a stopping point, I’m curious if you have played around with completely dropping local setups like Ghostly's IDE, integrated terminal and cli ui, and a visible Git tracking to develop entirely inside these high-profile external harnesses? **Status: answered.** John states he keeps external apps open only to keep remote tracking hooks running but builds and develops entirely inside his local terminal because it grants maximum power to rapidly search, spawn, and program custom behaviors. ## Cmux / herdr is like Hyper IDE? **Status: answered.** John outlines that traditional IDE definitions apply to graphical suites (Zed, VS Code, IntelliJ) embedded with file-system inspectors and refactoring engines, which diverges from terminal-focused script orchestration shells. ## How do you review the code in the terminal UIs? **Status: answered.** John delegates the task of code analysis to AI agents, asking them to summarize changes and write reports. He checks automated tests, smoke tests, and scenario suites rather than conducting deep manual line-by-line inspections. ## So you're essentially using AI to provide executive summaries of the code changes? **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## do you use evals when creating a skill or agent? **Status: partial.** John notes he is progressively incorporating automated scripted evaluations into his personal tooling stack. He highlights his experience at Vercel engineering integration infrastructure for terminal agents, where he orchestrated comprehensive evaluation sandboxes measuring prompt turn-efficiency and deployment success metrics across complex boilerplate projects. ## https://flameshot.org/ ? **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## https://shottr.cc/ maybe? **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## When you say commit gate, what does that translate to? **Status: answered.** John explains that a commit gate translates directly to a Git commit hook. He highlights that developers can prompt an AI agent to build a customized commit hook containing tailored project requirements, such as blocklisting specific file types (like log files), checking code metrics, running formatters, or maintaining linter baselines. ## How well did you know rust in order to build the prompt builder? Or did you just vibe-code it with AI? **Status: answered.** John states he only knew Rust from a few introductory examples and had never written serious Rust before. He describes his approach to 'vibe coding' as a responsible way of asking an agent for library recommendations, keyboard navigation handling, and structural architecture rather than just hoping code randomly appears. ## Vibe Engineer? **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## Sounds like a stripped down version of agent skills, is that the idea? **Status: answered.** John agrees conceptually and uses the question as a prompt to discuss how agent skills evolved away from their original definition toward a bloated model, contrasting them against his streamlined task-based context approach. ## you can turn on fast right? **Status: answered.** John admits that he can turn it on, but typically doesn't justify the additional cost for casual individual tasks. He resolves to enable it for upcoming workshops. ## Question: Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool? **Status: answered.** John demonstrates that a flow runs markdown templates that dynamically evaluate and preload context onto files through an evaluation step prior to AI execution. ## Is this similar to your concept of imps ? **Status: answered.** John answers that it is an abstracted version; 'imps' is tailored specifically for Codec, while MDFlow serves as a more general platform-agnostic alternative. ## Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup? **Status: answered.** John answers that he pays the API cost to use Claude Code and Fable normally, noting that the benefits outweigh the friction. He also mentions symlinking skill and memory/agent/Claude files to keep setups synchronized. ## Do you have an orchestrator that manages all the flows? For example, can it open a new herdr tab with the auditor flow and notify me when it's done? This would require access to the herdr-control.md and the auditor.md files.? **Status: answered.** John states he does not use an automated orchestrator by default yet, preferring to manually dictate agent instructions via herdr help, and then provides a live scripted demo opening multiple workspace panes. ## Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage? **Status: answered.** John notes that standard harnesses compress context automatically, but tool returns sometimes cause agent errors if altered too drastically. He notes that CodeGraph builds code structural maps rather than straightforward string token filtering. ## attuin? what was the other tool and why? **Status: answered.** John clarified the tool name is Atuin (atuin.sh) and explained that it is a terminal history manager used for better terminal history search and keeping track of history across shells. ## do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes? **Status: partial.** John begins to explain his structural project layout choices (like dedicated, gitignored folders for notes, goals, mocks, and issues) to partition distinct context categories, which continues past the current shard boundaries. ## How do you maintain design consistency across iterations? For example, once you've chosen a branding direction, how do you ensure the model keeps generating assets in that exact style? In my experience, even when I provide the same references, it tends to introduce subtle variations every time. **Status: answered.** John recommends using Impeccable (impeccable.style), which records styling choices in a DESIGN.md file and provides dedicated design skills (/typeset, /colorize, /animate, /critique) to prevent AI style drift. ## what types of situations do you consult? planning? creating spec? user stories? reviewing? diagnosing? questioning? **Status: answered.** John explains he consults reasoning models primarily for continuous architecture planning, handling obscure component/rendering issues in specialized frameworks (Rust GPUI), and conducting asynchronous verification passes. ## do you have agents gather context first? do grill me before, etc, how do you gather context **Status: answered.** John brainstorms and breaks down the task first, then hands off to Oracle instructing it to use the packx skill to assemble and attach full repository context files. ## Can you use the codex subscription in pi? **Status: answered.** John confirms that the Codex subscription can be used in Pi. ## do you use notebooklm to send people artifacts, like podcasts? videos? etc? 2. do you create your own podcasts? i find it useful for research papers 3. how do you do research? **Status: unanswered.** No answer was linked in the companion evidence. ## Can a single Mermaid graph effectively serve both machine context injection and human-readable documentation, or should we treat LLM-facing context architecture entirely separate from human-facing notes? **Status: answered.** John explains that keeping fixed mermaid diagrams for agents is an anti-pattern because it unnecessarily limits the agent from finding better architectural configurations. ## https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## does that require ULTRA subscription? do you find value in ULTRA subscription? **Status: answered.** Video analysis is available on Google AI Pro. Ultra offers higher usage limits, but Pro combined with YouTube Premium family sharing provides the primary value for his workflow. ## What’s the name of the document again? **Status: answered.** John answers that the file is vision.md (or agents.md), as confirmed in the discussion. ## Main resource or index? **Status: unlinked.** No explicit answer was linked in the validated workshop evidence. ## Would you argue for more use of git hooks than more and more documentation? **Status: answered.** John argues that while running agent evals on every git hook is currently too expensive for individuals, the upcoming release of open-weights models like K3 will make it very cheap. This allows teams to build custom vision verifier agents on commit hooks, making automated vision alignment practical and powerful within weeks. ## they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule? **Status: answered.** John describes his personal agentic 'Brain' running on a Mac Mini via GitHub and Telegram, but details that he avoids putting general curation or code review loops on a schedule because they become noise. ## To slash token costs for everyday coding, how are you stripping down the source code files before feeding them to Claude Code? **Status: answered.** John states that he does not manually trim down files anymore, citing major improvements in LLM native context window management. Instead, he orchestrates multi-agent flows or redirects intermediate subtasks to lower-cost endpoints like Grok, Cursor Composer, or K3. Reference ID: factory-question-reference Topic: Team practice Sources: - [Public question reference](https://proud-anchor-53zn.here.now/questions.md) --- # Reliable non-interactive shell environments: team walkthrough ## Team Learning Goal Teach this as a tool-visibility workflow, not a dotfiles tour. The audience should leave knowing how to ask an agent to inspect non-interactive shell startup, where safe PATH fixes belong, and how to confirm Codex can run the project tools. ## Walkthrough Depth ### Essential Walkthrough 1. Show the failure: `bun: command not found`. 2. Explain `zsh -lc`: login, not interactive. 3. Show the source-of-truth files. 4. Run the basic confirmation command. 5. Show PATH order. 6. Explain `.zshrc` versus `codex-env.zsh`. 7. Bridge to Section 3. ### Expanded Walkthrough Add: - clean-shell check - wrong executable wins - installer wrote `.zshrc` - `local.zsh` versus `00-path.zsh` ### Deep-Dive Walkthrough Add: - function versus executable - startup hangs from interactive code - secret-safe checks - team member exercise kickoff ## Talking Points Opening: > Codex does not inherit your current terminal session. It gets a shell command environment. Prove what that environment can see. When showing `zsh -lc`: > Login, but not interactive. When showing `.zprofile`: > This is the bridge into the agent-safe environment. When showing `.zshrc`: > `.zshrc` is for humans. It is usually the wrong place to fix agent PATH. When showing `codex-env.zsh`: > This file should be boring. It gives agents tools, not terminal personality. When showing PATH: > PATH order decides reality. The first match wins. ## Do Not Over-Explain - every zsh startup file in the manual - Oh My Zsh internals - every alias or function in John's setup - secret-management internals - prompt theme details - completion or ZLE mechanics ## Essential Points To Preserve - `zsh -lc` is the shell shape. - `.zprofile` and `codex-env.zsh` are the bridge. - `.zshrc` is not the default fix for agent command visibility. - `command -v` proves tool visibility. - `env -u CODEX_AGENT_ENV_SOURCED` validates startup from scratch. ## Boundary With Section 3 Section 2 is about agent-safe executable environment. Section 3 is about zsh functions and aliases as workflow language. | Section 2 | Section 3 | | --- | --- | | `zsh -lc` proof | command DSL tour | | `.zprofile` | `.zshrc` | | `codex-env.zsh` | rich helper files | | deterministic PATH | aliases and functions | | `command -v` | `funclist`, `funcwhere`, `funced` | | missing-command debugging | workflow wrappers | | non-interactive safety | interactive productivity | Bridge line: > Now that Codex can see the executables, Section 3 shows how John's zsh helpers become a workflow language. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-environment-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Shell functions, aliases, and executable boundaries: team walkthrough ## Team Learning Goal Teach command diagnosis and workflow design, not a dotfiles tour. The audience should leave knowing how to classify a command name, find its source, and decide whether it should be an alias, function, or executable wrapper. ## Walkthrough Depth ### Essential Walkthrough 1. Start from Section 2 executable proof. 2. Classify helpers with `whence -w`. 3. Show alias versus function. 4. Show function versus executable. 5. Locate a helper with `funcwhere`. 6. Show a safe `zsh -lc` handoff. 7. Bridge to Section 4. ### Expanded Walkthrough Add: - `funclist`, `funcwhere`, `funced` - `xfl`, `xfc`, `xport` - `p-f`, `p-c` - lazy stub explanation - executable fallback discussion ### Deep-Dive Walkthrough Add: - `fix` - `ghost-save` - `pksk` - stdout/stderr contract - team member DSL card exercise ## Talking Points Opening: > Aliases save keystrokes. Functions encode workflows. On classification: > The first move is not editing config. The first move is asking the shell what this name is. On function versus executable: > A zsh function is not a binary. A subprocess that looks for a file on PATH cannot run your function unless you deliberately load zsh around it. On aliases: > Aliases are substitutions. Useful, but not a programming language. On functions: > Functions are where arguments, policy, fallback, cleanup, and confirmation belong. On executable fallbacks: > If scripts, CI, or non-zsh callers need it, make it a real executable. ## Essential Points To Preserve Preserve these commands: ```zsh whence -w <name> type <name> alias <name> functions <name> command -v <name> whence -p <name> funcwhere <name> ``` Preserve these concepts: - alias vs function - function vs executable - `zsh -ic` for interactive discovery - `zsh -lc` for non-interactive handoff - `funclist`, `funcwhere`, `funced` - `xfl`, `xfc`, `xport` - `p-f`, `p-c` - executable fallback ## Live Demo Start from Section 2 proof: ```zsh zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; command -v codex bun pnpm cargo packx || true' ``` Show helper visibility: ```zsh zsh -ic 'for name in funclist funcwhere funced x xi xfl xfc xport fix agent_chain muxai p-f p-c ghost-save pksk; do printf "%-14s " "$name"; whence -w "$name" 2>/dev/null || echo MISSING; done' ``` Show source: ```zsh funcwhere xfl funcwhere xfc funcwhere fix funcwhere agent_chain funcwhere muxai ``` Show safe handoff: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c' ``` Bridge to Section 4: ```zsh whence -w muxai agent_chain funcwhere muxai funcwhere agent_chain ``` ## Optional Depth If 5 minutes behind, cut: - function body reading - helper family details - stdout/stderr contract If 10 minutes behind, cut: - `ghost-save` - `cfix` - lazy stub internals - Prompt Builder details beyond `p-f` and `p-c` If 20 minutes behind, run only: ```zsh zsh -ic 'for name in funclist funcwhere funced xfl xfc xport fix agent_chain muxai; do printf "%-14s " "$name"; whence -w "$name" 2>/dev/null || echo MISSING; done' zsh -ic 'funcwhere xfl; funcwhere xfc; funcwhere fix; funcwhere agent_chain; funcwhere muxai' zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c' ``` ## Boundary With Section 4 Section 3 gives the command language. Section 4 puts that language into panes, threads, forks, transcript exports, and agent chains. Bridge line: > Section 3 made the commands real. Section 4 makes the commands addressable. ## Further References - team member cheatsheet: `cheatsheets/03-zsh-functions-aliases.md` - Exercises: `exercises/03-zsh-functions-aliases.md` - Helper file: `zsh/conf.d/40-ai.zsh` - Fix helper source: `zsh/conf.d/47-ai-fix.zsh` - Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html - Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-shell-functions-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Turn generated choices into saved human decisions A chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state. When an agent generates options, turn them into a **small picker**. Review it on a phone, tap the choices that should survive, dictate notes, submit, and make the agent continue from the saved JSON. ```text generated options -> structured choice job -> Svelte + mdsvex picker -> token-gated mobile URL through a reviewed tunnel -> click/dictate feedback -> saved submission -> agent resumes from persisted JSON ``` ## The Problem Generated options are useful until they become a wall of text. The agent offers five reasonable strategies for a checkout fix, billing webhook retry plan, auth/session tradeoff, QA screenshot triage, or design variation. You are away from the desk. The mobile chat thread now expects you to remember option names, type a careful answer, and trust the agent to turn that paragraph back into structured state. That is where decisions get mushy. ## The Move Generated choices should **become data, not another paragraph**. The agent should produce a **choice job** with stable option ids, titles, descriptions, risk notes, and proof hints. A small review UI renders those choices as cards. The human selects options, adds per-option feedback, adds overall feedback, and submits. The agent waits for the saved submission before continuing. Use this when the next step needs a human decision: - choose among generated UI variations - pick a billing webhook idempotency strategy - choose an auth/session migration path - approve or reject model-council recommendations - triage screenshot or debug-packet follow-ups - select the first implementation plan after a broad exploration ## The Smallest Useful Version The picker does not need to be elaborate. It needs stable ids, checkboxes, per-option notes, one overall feedback box, draft saving, and a submit button that writes durable JSON. ```text Choice job: - jobId: - title: - description: Options: - id: title: description: risk: suggested proof: expected evidence: Human response: - selected option ids: - per-option feedback: - overall feedback: Resume rule: - continue only after a saved submission exists - resume from persisted JSON, not memory ``` ## The UI Contract **Web Choices** uses a Svelte + mdsvex browser UI. The app shell can be branded and pleasant, but the generated choices stay plain JSON. Keep this boundary: - mdsvex owns the page/template shell - Svelte owns cards, selection state, feedback fields, save state, and submit controls - generated option text remains data - generated option text is not compiled as Svelte or mdsvex source That boundary matters. A decision surface should not become a tiny CMS that compiles model output as app code. ## Persistence Is The Trust Boundary **No saved submission, no continuation.** Drafts are for humans. Submissions are for agents. > I need you to make these decisions before I continue further, and so I look at it, I click the ones I want, give feedback on it, and then submit, and then it continues. So you create a really asynchronous feedback loop between your local agent and how you're talking to it on your phone. > > — John Lindquist The durable state lives under a caller-selected human-in-the-loop output directory, commonly `.hitl-choice`: ```text .hitl-choice/ current-job.json drafts/ submissions.jsonl submissions/<submissionId>.json ``` The agent should wait until a final submission exists, then read selected option ids, per-option feedback, and overall feedback from the saved JSON. It should not infer the decision from visible UI state, draft text, or chat memory. ## The Phone Workflow **The phone is for decisions, not implementation.** > Click, dictate, click, dictate has been the best workflow for me. > > — John Lindquist The useful mobile loop is intentionally small: ```text tap option dictate note tap option dictate note add overall feedback submit ``` This works best when the agent has already done the expansion work. The human does the selection work. ## Tunnel Boundary A **reviewed, short-lived tunnel** can make the local picker reachable from a phone. Keep the specific tunnel product and hostname setup-specific unless the demo evidence is added and sanitized. The important lesson is not the exact hostname. The important lesson is: - keep the local server alive while waiting - expose a short-lived token-gated URL - let the human submit structured feedback - resume from persisted JSON Do not treat a token-gated URL as full authentication. It is **useful friction, not a product security model**. ## Copyable Artifact: Mobile Decision Surface Brief ```text Use this when: - an agent generated several options - the human needs to choose or annotate them - the next step should not continue until the choice is saved - the human may be reviewing from a phone Choice job: - jobId: - title: - description: - options: - id: title: description: risk: suggested proof: expected evidence: UI requirements: - render options as cards - allow multiple selection when appropriate - collect per-option feedback - collect overall feedback - save drafts while editing - write final submission only on submit Persistence: - active job: .hitl-choice/current-job.json - drafts: .hitl-choice/drafts/ - final log: .hitl-choice/submissions.jsonl - final packet: .hitl-choice/submissions/<submissionId>.json Agent stop rule: - wait for a saved submission - read selected ids and feedback from JSON - continue only from the persisted submission - report blocked if no submission exists Sharing boundary: - do not expose real tunnel URLs - do not expose tokens - do not expose hostnames - do not expose or share private options or submissions - do not call the token full authentication ``` Example prompt: ```text Turn these billing webhook strategies into a Web Choices job. Each option needs: - stable id - short title - concrete description - risk - suggested proof command - pass/fail evidence Serve it as a phone-friendly picker, wait for the saved submission, then continue only from the persisted JSON. ``` ## If It Goes Wrong If the tunnel fails, keep the same job state when possible. Reuse the token only if it was not exposed; otherwise rotate the token, restart the tunnel, and verify the current job is reachable before asking for another decision. If the server dies, inspect the output directory first. Restart with the same state if drafts or submissions already exist. If the human says they submitted but the wait command has not returned, check `submissions.jsonl`, per-submission files, and whatever reviewed server logs or status endpoint the current implementation exposes before regenerating choices. ## Claim Boundaries Web Choices is a local human-in-the-loop pattern with a small web UI and durable files. It is not a production approvals system by default. Verify timeout behavior, tunnel behavior, mobile rendering, submission persistence, and data handling in the current setup before sharing executable setup instructions. ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/#choice-surface) - [Resource directory and portable download](/topics/codex-resources/) - [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) Reference ID: codex-choice-surface Topic: Team practice Sources: - [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#choice-surface) - [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0) --- # Video analysis and evidence workflows: team walkthrough ## Team Learning Goal Teach video as evidence-rich prompt material, not as a novelty or transcript shortcut. By the end of this section, the room should understand: - why video can carry context text drops - when video is worth the overhead - how `oracle-video` relates to `oracle-packx` - why Gemini browser mode is required for video - how source hashes, `ffprobe`, timestamps, keyframes, and `output.log` make analysis checkable - why transcript, chat, visual evidence, and inference must stay separate - how verified video analysis becomes prompts, bugs, requirements, QA, lessons, or Section 6 variation matrices ## Walkthrough Depth ### Essential Walkthrough 1. Say: video is prompt material. 2. Show the short path vs long path table. 3. Show the correct Oracle/Gemini call shape. 4. Show `shasum`, `ffprobe`, and `END_OF_VIDEO_ANALYSIS`. 5. Show evidence lanes. 6. End with downstream prompt examples. ### Expanded Walkthrough Add: - run folder shape - `yt-dlp` metadata/download flow - keyframes/contact sheet - omissions pass - bug repro prompt shape ### Deep-Dive Walkthrough Add: - chunking long recordings - requirements artifact - Section 6 variation matrix from video evidence - exercises ## Talking Points Opening: > Video is prompt material. On transcripts: > A transcript tells you what was said. It does not prove what was visible. On evidence lanes: > Spoken claims, visible facts, chat messages, and inferences do different jobs. Keep them separate. On Gemini: > Text models do not watch the video. The video-watching step belongs to Gemini through Oracle browser mode. On source preservation: > If the original media is not preserved, every later claim gets harder to trust. On Section 8: > Section 7 preserves evidence from video. Section 8 puts that same discipline inside live debugging with markers. ## Live Demo Script ### 1. Create Run Folder ```bash RUN_ID="checkout-repro" RUN_DIR="runs/$RUN_ID" mkdir -p "$RUN_DIR"/{inputs,receipts,analysis,final,keyframes,contact-sheets} mkdir -p "$RUN_DIR/chunks/01" ``` ### 2. Preserve Source ```bash cp /path/to/source-video.mp4 "$RUN_DIR/inputs/source-video.mp4" shasum -a 256 "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/inputs/source-video.sha256" ffprobe -hide_banner -show_format -show_streams -of json \ "$RUN_DIR/inputs/source-video.mp4" \ > "$RUN_DIR/receipts/ffprobe.source.json" ``` ### 3. Write Prompt With Sentinel ```bash cat > "$RUN_DIR/chunks/01/gemini-prompt.md" <<'EOF' Analyze this video as prompt material for a software project. Separate transcript evidence, chat evidence, visual evidence, and inference. Preserve timestamps. Do not invent URLs, tools, commands, files, UI labels, or speakers. End with END_OF_VIDEO_ANALYSIS. END_OF_VIDEO_ANALYSIS EOF ``` ### 4. Show Correct Call Shape ```js mcp__oracle__consult({ prompt: "[checkout-repro-video]\n\n{contents of chunks/01/gemini-prompt.md}", files: ["/absolute/path/to/runs/checkout-repro/chunks/01/chunk.mp4"], engine: "browser", model: "gemini-3-pro", browserAttachments: "always", slug: "checkout-repro-video" }) ``` ### 5. Verify Output ```bash rg -n "END_OF_VIDEO_ANALYSIS" ~/.oracle/sessions/checkout-repro-video/output.log ``` ### 6. Bridge To Downstream Work Show one of: - repro steps - implementation prompt - design-change brief - QA checklist - Section 6 variation matrix ## Minimal Useful Path If 5 minutes behind, cut: - `yt-dlp` - contact sheet command - long recording folder details - omissions pass prompt Preserve: - video is prompt material - Gemini browser mode - `browserAttachments: "always"` - source hash - `ffprobe` - evidence lanes - sentinel - downstream prompt If 15 minutes behind, run only: ```text source -> hash -> ffprobe -> Gemini browser mode -> evidence lanes -> verified downstream prompt ``` ## Boundaries ### From Section 6 Section 6 teaches: ```text one deliberate prompt -> controlled variations ``` Section 7 expands what can become prompt material: ```text video -> verified evidence -> downstream prompt or variation matrix ``` ### To Section 8 Section 8 moves the same discipline into live debugging: ```text mark -> capture -> explain -> review/export ``` ## Failure Paths To Preserve Wrong Oracle mode: > If video analysis used API mode, rerun in browser mode. Transcript-only summary: > Ask for visual evidence and an omissions pass. Do not treat transcript as full analysis. Invented URL/tool/file: > Remove it or label it as inference. Unsupported details cannot become requirements. No sentinel: > Inspect `output.log`. If the sentinel is missing, rerun or request a focused correction. No source hash: > Stop and preserve the source before continuing. Long recording not chunked: > Segment/chunk before asking for a full packet. ## Team Checklist Confirm the materials include: ```text video is prompt material oracle-video Gemini engine: "browser" model: "gemini-3-pro" browserAttachments: "always" absolute file paths yt-dlp ffprobe sha256 source hash original timestamps END_OF_VIDEO_ANALYSIS output.log keyframes contact sheets transcript evidence chat evidence visual evidence inference omissions pass no invented URLs/tools/commands/files bug reproduction design feedback app walkthrough requirements QA checklist implementation prompt Section 6 variation matrix Section 8 agent markers bridge ``` ## Further References - team-facing file: `cheatsheets/07-video-as-prompts.md` - Exercises: `exercises/07-video-as-prompts.md` - `oracle-video` skill reference: `.agents/skills/oracle-video/SKILL.md` - `yt-dlp`: https://github.com/yt-dlp/yt-dlp - FFmpeg documentation: https://ffmpeg.org/documentation.html - `ffprobe` documentation: https://ffmpeg.org/ffprobe.html ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-video-workflows-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Visible workspaces for agents and swarms Expose pane state, separate execution from verification, and supervise bounded independent work. ## Related working material - [Visible workspaces for agents and swarms — prompts and exercises](/topics/factory-visible-workspaces-practice/) - [Visible workspaces for agents and swarms — questions and tradeoffs](/topics/factory-visible-workspaces-questions/) - [Visible workspaces for agents and swarms — worked example](/topics/factory-visible-workspaces-worked-example/) ## TL;DR - A terminal stack whose pane model is fully scriptable over a unix socket — by your keyboard, your scripts, and your agents. - You walk away with a read-only recon command set, a complete 3-chord keyboard config, and the keeper prompt: an agent that keeps other agents moving. - The one move: paste the keeper prompt into pi running inside a herdr pane. It answers stuck prompts, restarts crashes, and unsticks its siblings. Have your agent set this up — paste this into it: ``` text Fetch https://summit-inlet-kxyf.here.now/agent.md?raw and follow it to drive my herdr session from this agent. Run the success check at the end and show me the result. ``` ## The stack: each layer exposes its state to the one above The tempting way to pick a terminal for agent work is comparing feature lists. This setup rejects that framing. It is four small layers, and the selection rule is visible in the configs: each layer exposes its state to the layer above. **Ghostty** only draws pixels and forwards keys. **Herdr** (0.7.3, "terminal workspace manager for AI coding agents") runs as a client/server pair over a unix socket and surfaces the whole workspace → tab → pane model as CLI subcommands: `workspace`, `tab`, `pane`, `agent`, `wait`. The server keeps every pane alive with no window attached — quit Ghostty entirely and `herdr` reattaches to everything. **Pi** (0.80.10) is the agent inside the panes; herdr's integration installs a pi extension that reports the agent's state — idle, working, blocked — back over the socket, so a workspace listing truthfully says which agents are busy because the agents report it themselves. **Karabiner** turns all of it into single keystrokes. The test for your own setup: ask what your terminal will tell a script about its panes. If the answer is "nothing," everything below is out of reach regardless of features. ## Two configs shake hands: keyboard to focused pane Karabiner knows the keyboard but not which pane is focused. Herdr knows the focused pane but not global hotkeys. The handshake: Karabiner emits internal `Ctrl+Alt+…` chords only while Ghostty is frontmost, and herdr's `[[keys.command]]` bindings translate each chord into a command that receives the focused pane's context. The herdr config states the design in a comment: "Karabiner emits these internal chords only while Ghostty is frontmost; Herdr supplies the exact focused inner pane." Holding Esc turns the home row into a herdr command deck: | Hold Esc + | Action | |------------|---------------------------------------------------------------| | Z / F | Open the focused pane's cwd in Zed / Finder | | O | Smart open: URL, file:line reference, or cwd — whichever fits | | E | Open the latest file:line reference in Zed | | R / P | Open the current GitHub repo / the PR for the current branch | | Y | Copy pane/repo context | | L | Pick a URL from pane output (temporary picker pane) | | Space | Search ALL pane output; picking a hit focuses that pane | | X / N | Open Codex / Prompt Builder in a new pane | | Return | Zoom the focused pane | One layer up, a comma simlayer jumps between projects: , plus a letter focuses a workspace by label, falls back to matching panes by cwd, and creates the workspace if neither exists. ### The three chords worth stealing (complete config) Wire three chords, not thirty: *open-cwd-in-editor*, *open-repo*, and *search-all-panes-to-focus*. Three files. The helper script is a minimal, self-contained stand-in for the presenter's personal 1,200-line helper (see appendix) — it needs `herdr`, `jq`, and per verb `zed`, `gh`, or `fzf`. ``` text #!/bin/sh # Focus-aware chord actions for a herdr session. chmod +x this file. # Herdr injects HERDR_ACTIVE_PANE_ID when a [[keys.command]] binding fires. set -eu pane="${HERDR_ACTIVE_PANE_ID:-${HERDR_PANE_ID:?run from a herdr binding or pane}}" cwd="$(herdr pane get "$pane" | jq -r '.result.pane.foreground_cwd')" case "${1:-}" in zed) zed "$cwd" ;; repo) cd "$cwd" && gh repo view --web ;; pane-search) herdr pane list | jq -r '.result.panes[].pane_id' | while read -r p; do herdr pane read "$p" --source recent-unwrapped --lines 200 2>/dev/null \ | grep -v '^[[:space:]]*$' | sed "s|^|$p |" done | fzf --no-sort --tac | awk '{print $1}' | xargs -r -n1 herdr agent focus ;; *) echo "usage: herdr-chords zed|repo|pane-search" >&2; exit 2 ;; esac ``` ``` text # Karabiner emits these internal chords only while Ghostty is frontmost; # Herdr supplies the exact focused inner pane. [[keys.command]] # Esc+Z -> open focused pane's cwd in Zed key = "ctrl+alt+z" type = "shell" command = "$HOME/.local/bin/herdr-chords zed" [[keys.command]] # Esc+R -> open focused pane's GitHub repo key = "ctrl+alt+r" type = "shell" command = "$HOME/.local/bin/herdr-chords repo" [[keys.command]] # Esc+Space -> search every pane, jump to the hit key = "ctrl+alt+shift+l" type = "pane" # runs in a temporary pane; it closes after you pick command = "$HOME/.local/bin/herdr-chords pane-search" ``` ``` text ;; Goku / Karabiner-Elements. Tap Esc = normal Esc. ;; Hold Esc + key = chord, only while Ghostty is frontmost. ;; under :applications :ghostty ["com.mitchellh.ghostty"] ;; under :layers — hold-Esc layer; tap still sends Esc :escape-mode {:key :escape :params {:basic.to_if_alone_timeout_milliseconds 200 :basic.to_if_held_down_threshold_milliseconds 200} :alone [{:key :escape}]} ;; under :main — the three chords {:des "Ghostty: Escape Mode Herdr actions" :rules [[:condi :ghostty :escape-mode] [:-z {:key :z :modi [:left_control :left_option]}] ; Esc+Z [:-r {:key :r :modi [:left_control :left_option]}] ; Esc+R [:spacebar {:key :l :modi [:left_control :left_option :left_shift]}]]} ; Esc+Space ``` ## The keeper: one agent babysits the rest "Have pi keep other panes alive" is two mechanisms. Herdr keeps the *panes* alive structurally — the server outlives every window. Pi keeps the *agents in* those panes alive operationally: because herdr injects the socket path and pane id into every pane, a pi session can supervise its siblings with ordinary shell commands — read what a sibling printed, answer its stuck confirmation prompt, restart its crashed command, and block on `herdr wait agent-status` instead of burning tokens polling. That is the keeper prompt above, and its two hard rules — never close panes, never start new work — exist because a shepherd with worker instincts destroys the flock. This is not hypothetical self-inspection. On the recorded workflow, a pi session used pane capture to check glyph rendering in its own herdr pane — and in doing so surfaced a real bug in `herdr pane run`. The success check above is that same move, packaged. The signal the keeper is working: interventions get *rarer* over a session. A keeper that intervenes constantly is masking a bad task split — fix the plan, not the babysitter. ## Swarms: plan until independent, then fan out The agenda bullet carries its own warning label: "lots of planning with a smart model first!" The swarm is the cheap part; the plan is the whole game. Run the decomposition prompt above with your strongest model, and argue with the output — if two workers would touch the same file, you are not done planning. Then fan out each brief into a visible pane as a direct process: ``` text herdr agent start learners --cwd ~/dev/proj/sites/learners --split right \ -- bash -lc 'pi -p "$(cat briefs/learners.md)"' ``` The argv launch matters: no shell, no typed command, no startup race — "the launch race cannot happen, by construction" (the pi-herdr-subagents README, a herdr-native descendant of HazAT's pi-interactive-subagents). Death is observable too: herdr emits `pane.exited` socket events within milliseconds, so a dead worker is an event, not a screen that stopped changing. Captured from the running server the day before the workshop: ``` text Illustrative workspace responsibilities: orchestrator — plan and coordinate worker-a — independently scoped audience/site worker-b — independently scoped audience/site worker-c — independently scoped audience/site ``` One pi orchestrator, three workers, each confined to its own directory — exactly the shape the planning prompt demands. Every worker is watchable (glance at its pane), interruptible (click in and type), and composable with the keeper: one pane's pi can babysit the whole swarm. ## Appendix ### Limits & caveats - The Esc chords exist only through a Karabiner config. On a machine without it, none of them fire; herdr's portable bindings (splits on `cmd+d`, pane focus on `cmd+alt+arrows`, a tmux-style `ctrl+b` leader) work everywhere. - The live config's chords call `herdr-escape`, the presenter's personal 1,200-line Bun script with 12 verbs. The `herdr-chords` file above is a minimal 3-verb stand-in written for this page; its cwd lookup and search pipeline were tested piecewise on the live server, but it is not battle-tested. - The keeper writes into other panes: it answers prompts and reruns commands. Pointed at real work, a wrong guess becomes a wrong keystroke in a live session. Rehearse on a sacrificial workspace; give a production keeper an allowlist of panes it may touch. - Herdr is fast-moving pre-1.0 software (0.7.3, protocol 16, version-specific snapshot). Re-run `herdr --help` and the subcommand helps before trusting any flag quoted here. - The swarm capture proves the swarm's shape at one moment. It does not show whether the three sites were finished, how long they took, or how often the orchestrator intervened. - The `pane run` bug anecdote comes from local conversation-search excerpts, not a replayable transcript. It supports "this happened that day," nothing stronger. - Pane-search opens a temporary pane (`type = "pane"`) that disappears after selection — by design, not a crash. ## Operating practice ### Keep wrappers thin and work visible #### What to notice Remove flag memorization while keeping the **real command**, task state, logs, and **verification** inspectable. #### Try this Create three visible responsibilities: execution, **verification**, and logs or status. > “Kind of forget the flags, especially if you're someone jumping back and forth between the different harnesses.” John Lindquist · [01:23:01](https://proud-anchor-53zn.here.now/watch.html?t=4981#recording-player) #### Concept A wrapper earns its place when it prevents a repeated mistake and remains easy to trace. More panes do not create understanding. Add a surface only when it represents an independently observable responsibility. #### Reflection The presenter’s terminal stack is an example. The reusable practice is consistent launch behavior and visible state. **Recording evidence:** listen at 01:21:23. > “The beauty of owning your own tools is you can have them test themselves, and write themselves, and tackle themselves.” John Lindquist · [01:37:37](https://proud-anchor-53zn.here.now/watch.html?t=5857#recording-player) [Open Custom zsh Functions](https://sacred-ritual-w7as.here.now/)[Open Pi, Herdr, and Ghostty](https://summit-inlet-kxyf.here.now/) #### Links shared for this topic - [Herdr](https://herdr.dev) — A workspace surface for seeing parallel agent activity. - [Linear](https://linear.app/) — Issue and project tracking referenced during workflow discussion. - [Claudex](https://github.com/johnlindquist/claudex) — A proxy and launcher experiment for coding-agent sessions. - [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/) — A published account of AI-assisted review at production scale. [Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=4883#q1-launcher-workspaces) Reference ID: factory-visible-workspaces Topic: Team practice Sources: - [Visible workspaces for agents and swarms](https://summit-inlet-kxyf.here.now/) - [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces) --- # Visible workspaces for agents and swarms — discussion and evidence Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations. These are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate. ## Concepts and distinctions ### Custom zsh functions for Agent CLIs Creating two-letter wrappers or alias-style functions to manage flags across various agent tools (e.g., Codex, Claude Code, Pi) seamlessly without having to remember distinct syntax like --resume vs resume. ### funcwhere A custom shell function created by John Lindquist that locates the precise file and line number where a specified zsh function is defined. ### Isolated Assistant Home Directories (CODEX_HOME) By isolating home directory pathways for AI client packages, engineers can prevent state corruption, parallelize multiple enterprise subscriptions, and prevent agent environment inheritance. ### Skill Symlinking Creating symbolic links between a primary AI config folder and a custom secondary agent folder allows tools to utilize the same skills list while keeping runtime databases separated. ### CLI Proxy API Middleware A local middleware bridge used to run Codex account tokens within the engine architecture of Claude Code clients. ### Terminal Pane Management Using fast keyboard shortcuts within a terminal emulator (like Ghostty) to split screens, organize tasks, and navigate fluidly. ### Modular Shell Configuration Structuring ZSH or Bash profile setups using a conf.d model where settings are broken down into small, numbered files for easier maintenance and composition. ### Shell Startup Benchmarking Using large language models to analyze shell profile files and eliminate blockers (like synchronous NVM evaluation) that introduce startup lag. ### Herder A high-performance command-line workspace and multi-agent dashboard designed to efficiently manage interactive panes. ### CMUX A complex terminal layout driver wrapped as a Swift utility that manages multi-session shell instructions but exhibits performance friction. ### IDE Integrated Development Environment; an all-in-one software ecosystem featuring built-in code analysis trees, direct file graph navigation, and deep refactoring architectures. ### Natural Language Development / Agentic Engineering Developing software primarily via conversational prompts to AI agents rather than through manual coding and file navigation within standard IDEs. ### Agentic Code Review Utilizing AI agents to generate summaries and reports of changes while relying on automated validation tools (linters, tests, hooks) to confirm quality. ### Stricter Compiled Typings for Agents The approach of using strictly typed languages (like Rust or Kotlin) because strict compilation acts as an ultimate quality gate for agent-generated code. ### Agent-Optimized Web Languages Languages designed from scratch to prioritize fast agent code compilation and checks rather than human ergonomics. ### Bespoke Rust TUIs High performance terminal overlays built to execute instantly for handling prompt configurations and tool workflows. ### Macro-Driven Workspace Focus The method of pairing keyboard layout layers (Karabiner) with window arrangement managers (Herder) to immediately target individual split terminals and project pathways using single-chorded hotkeys. ### Automated Repository Sharding Skills Wrapping specialized prompts into reusable console directives (such as /skill:here-now) that dispatch independent, parallelized sub-agents to independently parse git statistics, files, and branch states. ### Sandboxed Agent Evaluation Testing the operational efficiency and accuracy of multi-turn autonomous coding tools within ephemeral, isolated test runners to observe total execution loops, API permission handling, and successful build handoffs. ### Budget-Conscious Agent Architecture Designing multi-agent workflows with cost-gates and low-tier model integration to prevent prohibitive API usage on personal developer accounts. ### Programmatic Post-Generation Evals Applying automated validation scripts following LLM code generation to ensure structural and behavioral alignment with specific traits. ### Swarm Code Review An orchestration methodology where multiple independent, specialized sub-agents review source code simultaneously from disparate viewpoints (e.g., security, compliance, accessibility). ### Iterative Fixer Loops A software repair pattern where specialized sub-agents discover findings and an autonomous fixer agent corrects them repeatedly until zero issues remain. ### Smoke and Integration Tests Verification buckets intended to confirm that updated deployment code functions safely without breaking visual layouts or core operational features. ### Agent Session Scripting An automation pattern where a primary AI agent conducts user actions on a deployment, and a secondary agent reviews the execution timeline to export it as a programmatic test script. ### Chaos Monkey Testing Agent A testing setup where an AI agent is instructed to execute erratic and rapid keystrokes or interface inputs to purposefully try and break software components. ### Image Diffing Iteration Loop An agentic loop approach where the model takes automated snapshots of a rendered webpage layout, runs a visual diff against the original mockup image, and continuously updates the code until pixel-perfect alignment is reached. ### File Age Policy Guardrail A runtime file safety constraint injected into an agent workspace context that establishes a timeline cutoff based on file modification times, preventing the agent from modifying, renaming, or deleting older legacy codebase files. ### Project Workspace Directory Trust A security framework boundary that prompts the user to explicitly trust local file systems before allowing agent extensions or custom shell execution hooks to activate within that context. ### Shell Tool Decoration The technique of overriding default terminal applications or functions within a shell session to overlay custom analytical or defensive actions transparently. ### File Age Protection Guardrails Automated system restrictions that analyze file metadata to block or hesitate before letting autonomous agents modify code older than a configured age threshold. ## Questions and answer status ### Have you played around with completely dropping local setups like Ghostly's IDE, integrated terminal, and cli ui, and a visible Git tracking to develop entirely inside these high-profile external harnesses? **Status: answered.** John states he keeps external apps open only to keep remote tracking hooks running but builds and develops entirely inside his local terminal because it grants maximum power to rapidly search, spawn, and program custom behaviors. ### Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available. **Status: unanswered.** The question is shown in chat but is not directly explicitly answered or addressed by John during the duration of this specific video segment. ### Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available. **Status: partial.** John shows that his public GitHub dotfiles repository is obsolete, shows his local structured setup instead, and mentions he wants to review it before publishing it properly. ### Cmux / herdr is like Hyper IDE? **Status: answered.** John outlines that traditional IDE definitions apply to graphical suites (Zed, VS Code, IntelliJ) embedded with file-system inspectors and refactoring engines, which diverges from terminal-focused script orchestration shells. ### How do you review the code in the terminal UIs? **Status: answered.** John delegates the task of code analysis to AI agents, asking them to summarize changes and write reports. He checks automated tests, smoke tests, and scenario suites rather than conducting deep manual line-by-line inspections. ### Is there a simple Git or something that is the best Git terminal UI in the world? **Status: answered.** The optimal approach is delegating to an agent to formulate and construct a highly individualized Rust terminal utility matching your direct workflow constraints. ### do you use evals when creating a skill or agent? **Status: partial.** John notes he is progressively incorporating automated scripted evaluations into his personal tooling stack. He highlights his experience at Vercel engineering integration infrastructure for terminal agents, where he orchestrated comprehensive evaluation sandboxes measuring prompt turn-efficiency and deployment success metrics across complex boilerplate projects. ### a participant provides a summary of Cloudflare's swarm architecture for code review (security, a11y, testing sub-agents). **Status: answered.** John opens the blog post directly, validates the concepts, and expands on how low model prices now enable developers to throw multiple capable models into code review swarms affordably. ### How close do you think Fable got to that screenshot? **Status: answered.** John answers that it performed very well for just a few minutes of generation work, noting the hand-drawn elements, tabs, and layout structures look excellent despite slight physical alignment quirks on the decorative notebook hole punches. ## Exercises - **Try:** Isolate an active AI workspace environment locally by configuring independent variables for multiple assistant accounts, verifying separated session databases. **Basis:** 01:25:46.350 - **Try:** Use an LLM model to analyze, optimize, and benchmark your personal bash/zsh startup setup to eliminate high latency hooks like NVM script initialization. **Basis:** John mentions this at 01:30:45 as an effective workflow optimization strategy. - **Try:** Configure an automated code repository auditing command or skill locally that runs parallel evaluations using git logs and diff metrics. **Basis:** Demonstrated by John Lindquist when initializing the /skill:here-now prompt at 01:45:00. - **Try:** Students are directed to build a Chaos Monkey prompt variant for their agents to stress-test custom site deployments with erratic behavior over the weekend. **Basis:** John mentions: 'try that this weekend sometime. Click on everything way too fast, type in way too much... trying to make it break and find where it breaks. That's a really fun prompt.' - **Try:** Configure a repository safety script that checks individual file mtime dates, calculates a 7-day cutoff boundary, and warns an autonomous agent workflow whenever a targeted workspace resource violates modification safety thresholds. **Basis:** Demonstrated at 01:57:00.000 where the shell agent intercepts the ls query to append a structured FILE AGE POLICY block. ## Observed actions and statements These timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples. - [01:21:23](https://proud-anchor-53zn.here.now/watch.html?t=4883#recording-player) — John Lindquist notes that Linear is highly agentic ready with its CLI. - [01:21:57](https://proud-anchor-53zn.here.now/watch.html?t=4917#recording-player) — a participant describes Linear as Jira for AI-Native Teams. - [01:22:18](https://proud-anchor-53zn.here.now/watch.html?t=4938#recording-player) — The presenter types and executes the directory initialisation macro 'take ~/dev/custom-zsh-functions'. - [01:22:32](https://proud-anchor-53zn.here.now/watch.html?t=4952#recording-player) — The presenter executes the 'x' function shortcut, initiating OpenAI Codex CLI. - [01:22:39](https://proud-anchor-53zn.here.now/watch.html?t=4959#recording-player) — The presenter exits Codex and tests the 'xr' command wrapper to open the session resumer tool. - [01:22:51](https://proud-anchor-53zn.here.now/watch.html?t=4971#recording-player) — The presenter calls the 'clx' function to invoke the Claude Code runtime agent interface. - [01:23:09](https://proud-anchor-53zn.here.now/watch.html?t=4989#recording-player) — The presenter tests mock inputs for various resume styles into the shell line buffer. - [01:23:34](https://proud-anchor-53zn.here.now/watch.html?t=5014#recording-player) — The presenter triggers 'which x' to inspect the structure of the active shell configuration function wrapper. - [01:23:52](https://proud-anchor-53zn.here.now/watch.html?t=5032#recording-player) — The presenter triggers 'which clx' to check flag formatting logic for Claude Code. - [01:24:16](https://proud-anchor-53zn.here.now/watch.html?t=5056#recording-player) — The presenter tests 'funcwhere x' to trace the target path locations of local Zsh tools. - [01:24:27](https://proud-anchor-53zn.here.now/watch.html?t=5067#recording-player) — The presenter inspects the internal text layout of 'funcwhere' using the standard shell built-in command. - [01:24:43](https://proud-anchor-53zn.here.now/watch.html?t=5083#recording-player) — The presenter writes the combined terminal macro string 'zed "(funcwhere x)"' into the input row. - [01:25:02](https://proud-anchor-53zn.here.now/watch.html?t=5102#recording-player) — John points out different definitions for resume, resume with a specific conversation, and resume the last conversation. - [01:25:34](https://proud-anchor-53zn.here.now/watch.html?t=5134#recording-player) — John types a custom zsh command into Ghostly window to inspect function configurations for x2. - [01:25:46](https://proud-anchor-53zn.here.now/watch.html?t=5146#recording-player) — John explains that having two parallel Codex subscriptions involves running them with custom home directories. - [01:27:13](https://proud-anchor-53zn.here.now/watch.html?t=5233#recording-player) — John Lindquist drops the URL https://github.com/johnlindquist/claudex into the workshop chat room. - [01:27:24](https://proud-anchor-53zn.here.now/watch.html?t=5244#recording-player) — John explains that Claudex lets you run Codex inside Claude Code via a CLI proxy API. - [01:28:43](https://proud-anchor-53zn.here.now/watch.html?t=5323#recording-player) — John Lindquist mentions having a shortcut to spawn another tab or pane open to the side. - [01:29:39](https://proud-anchor-53zn.here.now/watch.html?t=5379#recording-player) — John addresses a question about whether his dotfiles are published anywhere. - [01:29:58](https://proud-anchor-53zn.here.now/watch.html?t=5398#recording-player) — John switches to Google Chrome and enters the URL github.com/johnlindquist/dotfiles. - [01:30:08](https://proud-anchor-53zn.here.now/watch.html?t=5408#recording-player) — The browser shows an old repository named dotfiles containing Karabiner config files from 4 years ago. - [01:30:45](https://proud-anchor-53zn.here.now/watch.html?t=5445#recording-player) — John suggests prompting AI models to benchmark and optimize ZSH profile configurations for maximum startup speed. - [01:31:00](https://proud-anchor-53zn.here.now/watch.html?t=5460#recording-player) — John displays a list of numbered configuration files ranging from 00-path.zsh to 65-ai-agent-shortcuts.zsh. - [01:32:10](https://proud-anchor-53zn.here.now/watch.html?t=5530#recording-player) — John states he wants to review his configuration files before publishing them publicly. - [01:32:20](https://proud-anchor-53zn.here.now/watch.html?t=5540#recording-player) — John inputs herdr --help into the active command prompt terminal. - [01:32:39](https://proud-anchor-53zn.here.now/watch.html?t=5559#recording-player) — John types the cmux command, generating an extensive terminal layout control output list. - [01:33:28](https://proud-anchor-53zn.here.now/watch.html?t=5608#recording-player) — The terminal window displays an automated Claude agent update diff for index.html. - [01:35:24](https://proud-anchor-53zn.here.now/watch.html?t=5724#recording-player) — a participant comments that John is utilizing Zed instead of ghostly features directly. - [01:35:59](https://proud-anchor-53zn.here.now/watch.html?t=5759#recording-player) — Terminal workspace shows the file 40-alias.zsh with active terminal configuration aliases list and workspace file sidebar. - [01:35:59](https://proud-anchor-53zn.here.now/watch.html?t=5759#recording-player) — John Lindquist discusses how integrated environments are being overtaken by natural language development, vibe coding, and agentic engineering. - [01:36:28](https://proud-anchor-53zn.here.now/watch.html?t=5788#recording-player) — The workspace editor switches files to show the content of pi-lens.md containing file age policies and verification rules. - [01:36:38](https://proud-anchor-53zn.here.now/watch.html?t=5798#recording-player) — a participant sends a chat message: 'How do you review the code in the terminal UIs?' - [01:36:42](https://proud-anchor-53zn.here.now/watch.html?t=5802#recording-player) — John points out that tools like TMUX have been around forever, but agentic tools make hacking custom plugins on Herder much faster. - [01:37:10](https://proud-anchor-53zn.here.now/watch.html?t=5830#recording-player) — John compares agentic pane generation with traditional extension testing workflows inside IDEs like VS Code. - [01:37:34](https://proud-anchor-53zn.here.now/watch.html?t=5854#recording-player) — a participant sends a chat message: 'There’s simple-git or something that is “the best git terminal ui in the world”' - [01:37:47](https://proud-anchor-53zn.here.now/watch.html?t=5867#recording-player) — John reads a participant's question and describes asking agents to summarize changed files and write report summaries. - [01:38:16](https://proud-anchor-53zn.here.now/watch.html?t=5896#recording-player) — John states his high trust in the AI agent Fable and notes that he uses tests, hooks, linters, and gates to verify functionality instead of manual code reviews. - [01:39:07](https://proud-anchor-53zn.here.now/watch.html?t=5947#recording-player) — John talks about the benefit of strictly typed compiled languages like Rust that enforce correctness under agentic workflows. - [01:39:18](https://proud-anchor-53zn.here.now/watch.html?t=5958#recording-player) — John expects developers to transition away from TypeScript/JavaScript to options that compile to JavaScript with stricter typing like Kotlin. - [01:39:28](https://proud-anchor-53zn.here.now/watch.html?t=5968#recording-player) — a participant sends a chat message: 'So you're essentially using AI to provide executive summaries of the code changes?' - [01:39:33](https://proud-anchor-53zn.here.now/watch.html?t=5973#recording-player) — John talks about the future emergence of a web language optimized for agents rather than humans. - [01:40:08](https://proud-anchor-53zn.here.now/watch.html?t=6008#recording-player) — John poses the question regarding finding or building the best Git terminal UI. - [01:43:15](https://proud-anchor-53zn.here.now/watch.html?t=6195#recording-player) — John discusses the development history of digital artifacts, attributing the initial framework conception to the Anthropic Claude Code team. - [01:43:39](https://proud-anchor-53zn.here.now/watch.html?t=6219#recording-player) — John explains his local keyboard configuration environment using Karabiner software keys combined with custom panel focusing parameters handled via Herder setup definitions. - [01:43:54](https://proud-anchor-53zn.here.now/watch.html?t=6234#recording-player) — Student a participant describes an automated review-loop macro that initiates paired Opus and Codex subagents to iteratively find and resolve repository bugs. - [01:44:50](https://proud-anchor-53zn.here.now/watch.html?t=6290#recording-player) — John initializes an interactive agent task loop inside the script-kit-gpui project folder workspace by entering the invocation query x pi. - [01:45:00](https://proud-anchor-53zn.here.now/watch.html?t=6300#recording-player) — John passes a long-form request to the terminal via the prompt command /skill:here-now to aggregate code change metrics, identify breaking behaviors, and flag potential visual regression risks over the past week. - [01:45:39](https://proud-anchor-53zn.here.now/watch.html?t=6339#recording-player) — John notes an automated test inquiry from the session history asking if he writes validation checkpoints or automated evaluation test suites when authoring customized agent skills. - [01:45:54](https://proud-anchor-53zn.here.now/watch.html?t=6354#recording-player) — John highlights his past engineering contributions at Vercel developing early infrastructure implementations for the platform's terminal agent automation plugin. - [01:46:08](https://proud-anchor-53zn.here.now/watch.html?t=6368#recording-player) — The terminal view displays multiple parallel sub-agents spinning up under the names Agent review committed weekly changes, Agent review dirty worktree changes, and Agent audit weekly visual risks. - [01:46:52](https://proud-anchor-53zn.here.now/watch.html?t=6412#recording-player) — John explains that while Vercel could easily absorb the costs of heavy agent evaluations, doing so on a personal budget becomes prohibitively expensive. - [01:47:24](https://proud-anchor-53zn.here.now/watch.html?t=6444#recording-player) — John details the programmatic evaluation gates built into his 'mini arcade' repository that validate traits post-game-generation. - [01:47:52](https://proud-anchor-53zn.here.now/watch.html?t=6472#recording-player) — John shares that he is building an app for home builders via a small startup, where simple AI features will solve niche problems without requiring heavy agent swarms. - [01:48:21](https://proud-anchor-53zn.here.now/watch.html?t=6501#recording-player) — John highlights how low-cost, highly capable models like Kimi or Kimi 3 can significantly enhance agentic workflows by serving as cheap evaluation layers. - [01:49:05](https://proud-anchor-53zn.here.now/watch.html?t=6545#recording-player) — John introduces the Cloudflare article regarding large-scale AI code reviews. - [01:49:34](https://proud-anchor-53zn.here.now/watch.html?t=6574#recording-player) — John discusses technical code review loops involving sub-agents (like Opus and Codex) finding errors, followed by a fixer agent resolving them iteratively. - [01:50:02](https://proud-anchor-53zn.here.now/watch.html?t=6602#recording-player) — John recalls how expensive multi-model code reviews were in previous years using models like Claude Sonnet 3.5 or older Codex variations, comparing it to today's affordable subscription models. - [01:51:40](https://proud-anchor-53zn.here.now/watch.html?t=6700#recording-player) — John talks about working at ClickUp and dealing with high blast radius UI changes. - [01:51:59](https://proud-anchor-53zn.here.now/watch.html?t=6719#recording-player) — John introduces the concept of using one agent to build paths and another to turn them into scripts. - [01:54:16](https://proud-anchor-53zn.here.now/watch.html?t=6856#recording-player) — John inputs the prompt 'serve this in my browser' into the interactive command input text entry field. - [01:54:27](https://proud-anchor-53zn.here.now/watch.html?t=6867#recording-player) — A local Python HTTP server is spawned on port 8459, opening the page in Google Chrome at http://localhost:8459. - [01:55:00](https://proud-anchor-53zn.here.now/watch.html?t=6900#recording-player) — John explains how image diffing pipelines let agents iterate on layouts until they match mockups with pixel-perfect accuracy. - [01:56:34](https://proud-anchor-53zn.here.now/watch.html?t=6994#recording-player) — John opens the pi-env-demo workspace space, displaying a modal dialog overlay prompt requesting project trust confirmation. - [01:56:42](https://proud-anchor-53zn.here.now/watch.html?t=7002#recording-player) — John selects the 'Trust (this session only)' option, allowing workspace initialization. - [01:56:47](https://proud-anchor-53zn.here.now/watch.html?t=7007#recording-player) — John writes 'List all of our files with ls' inside the workspace agent prompt panel. - [01:56:56](https://proud-anchor-53zn.here.now/watch.html?t=7016#recording-player) — The agent executes the terminal command ls -la and prints a FILE AGE POLICY layout configuration table. - [01:57:15](https://proud-anchor-53zn.here.now/watch.html?t=7035#recording-player) — John highlights the injected safety rule prohibiting modification of project files older than 7 days. - [01:57:51](https://proud-anchor-53zn.here.now/watch.html?t=7071#recording-player) — John Lindquist describes the issue of legacy project code that shouldn't be touched by automated agents without specific flags or restrictions. - [01:58:35](https://proud-anchor-53zn.here.now/watch.html?t=7115#recording-player) — The screen shows a terminal running a custom file age policy module displaying the modification metadata of files under the pi-env-demo folder. - [01:59:14](https://proud-anchor-53zn.here.now/watch.html?t=7154#recording-player) — John Lindquist explains that the logic for decorating shell functions lives inside the agent-shell configuration file. - [01:59:45](https://proud-anchor-53zn.here.now/watch.html?t=7185#recording-player) — John opens file-age-policy.mjs in the editor to detail the Node.js implementation of the policy rules. - [02:00:52](https://proud-anchor-53zn.here.now/watch.html?t=7252#recording-player) — The terminal window displays an active background agent publishing a script to a live here.now URL and verifying it with curl. ### Unresolved: Exact pipe extensions configured inside the internal implementation of the custom funcwhere method. The complete execution line wraps past the visible screen borders during standard stdout print visualization. **Discriminating evidence:** Inspect the source script contents file directly in subsequent segments or repositories. ### Unresolved: The explicit terminal alias used to trigger full color detailed directory listings during home directory checking. John runs a command that lists the contents of the .codex-work folder with specific date-modified metrics, but the exact typed short-phrase command keying is partially off-screen or obscured. **Discriminating evidence:** Cross-reference with full dotfiles repository configuration scripts. ### Unresolved: The exact shell command used to invoke the directory viewer for the conf.d files. The command itself is entered via an abbreviation or custom key combination without explicit standard typing visible. **Discriminating evidence:** Can be inferred as a custom ls alias or tool like eza/exa based on columns shown. ### Unresolved: The exact application driving the embedded terminal text editing engine interface layout. No discrete window decoration labels are cleanly drawn on screen, despite matching text features commonly associated with Zed terminal integrations or text editors. **Discriminating evidence:** Cross-reference workshop asset profiles for terminal dashboard editor plugins. ### Unresolved: Herder The tool name is pronounced as 'Herder' but could alternatively be written as 'Herdr' or similar. **Discriminating evidence:** Left as 'Herder' matching the verbatim transcript interpretation. ### Unresolved: Exact underlying terminal binary backing the prompt builder overlay. The precise tool executable name isn't entered or explicitly read out during the fast execution toggle. **Discriminating evidence:** Verify tool definitions in subsequent workshop shards. ### Unresolved: Specific architecture specifications and installation links for the speaker's Herder tool project. The terminal management tool is highlighted textually and verbally as a component of John's window navigation setup, but its codebase repository home is not opened or inspected. **Discriminating evidence:** Examine related project files or configuration folders under the user profile summary data for additional .herder definitions. ### Unresolved: The exact version designator configuration layout details at the lower margin of the active terminal window. Text reading (opencode-codex) gpt-5.6-sol-w1 is relatively small and can be interpreted with alternative typographic spacing assumptions. **Discriminating evidence:** Verify with terminal logs or source configurations for the underlying pi-lens status bar layout. ### Unresolved: The accurate tool branding classification of the left sidebar agent orchestration app client. The software frame displays workspace trees, tool durations, and agent states clearly but does not highlight an explicit application title or client banner text. **Discriminating evidence:** Cross-reference with the master project architectural diagrams to determine if this dashboard interface runs as a specialized client extension of Script Kit. ### Unresolved: Exact target length evaluations inside the shell loop script. The lower sections of the function window are compact and text scaling reduces readability. **Discriminating evidence:** Cross-reference with full repository source files for agent-shell.zsh. ### Demonstration detail: 01:22:16 - Executed take command to open custom project environments. - Ran custom wrappers x, xr, and clx to prove abstraction functions across various AI platforms. - Demonstrated debugging commands via which and a unique custom utility named funcwhere. **Tools observed:** Ghostty, OpenAI Codex CLI, Claude Code CLI, Zed. **Command or prompt observations (not a verified recipe):** ```text take ~/dev/custom-zsh-functions x xr clx which x which clx funcwhere x which funcwhere zed "(funcwhere x)" ``` ### Demonstration detail: 01:25:00 - Reviewing specific shell script configuration declarations for Codex wrappers **Tools observed:** Zed/Editor. ### Demonstration detail: 01:25:29 - Querying terminal function composition definitions and scanning runtime isolated directories **Tools observed:** Ghostly Terminal. **Command or prompt observations (not a verified recipe):** ```text custom-zsh-functions which x2 ``` ### Demonstration detail: 01:27:03 - Opening the claudex open source repository page to analyze implementation rules **Tools observed:** Google Chrome Browser. ### Demonstration detail: 01:28:43 - Spawning horizontal and vertical terminal panes - Closing terminal sessions quickly using hotkeys **Tools observed:** Ghostty. ### Demonstration detail: 01:29:58 - Navigating to GitHub repository URL in web browser **Tools observed:** Google Chrome. ### Demonstration detail: 01:30:19 - Listing files in a shell configuration directory **Tools observed:** Ghostty. ### Demonstration detail: 01:32:20 - Executed herdr help parameters - Executed cmux parameters to display pane automation controls **Tools observed:** herdr, cmux, Ghostty. **Command or prompt observations (not a verified recipe):** ```text herdr --help cmux ``` ### Demonstration detail: 01:35:59 - Switched tab from 40-alias.zsh config file to view the pi-lens.md documentation file. **Tools observed:** Terminal workspace code viewer. ### Demonstration detail: 01:41:11 - Toggled custom TUI client framework panel. - Typed command strings into the terminal interactive input field. **Tools observed:** Ghostty. **Command or prompt observations (not a verified recipe):** ```text /model /permissions ``` ### Demonstration detail: 01:43:24 - Swapping active project configurations instantly inside Ghostty panels via key combinations. **Tools observed:** Ghostty, Karabiner, Herder. ### Demonstration detail: 01:44:50 - Initializing the agent workflow engine and launching a parallel branch documentation query. **Tools observed:** pi, Git. **Command or prompt observations (not a verified recipe):** ```text x pi /skill:here-now Please look through all the code changes over the past week and write out a guide explaining all the changes, why they were made, the things I should definitely look into, and the things that might cause either breaking changes or visual chain deciding to investigate. ``` ### Demonstration detail: 01:46:51 - Monitoring ongoing multi-agent execution processes in the pi-lens terminal dashboard environment. **Tools observed:** Script Kit. ### Demonstration detail: 01:49:12 - Opening Google Chrome and scrolling down through the Cloudflare blog architecture layout. **Tools observed:** Google Chrome. ### Demonstration detail: 01:50:31 - Displaying an architectural blog section detailing context isolation mechanics and opencode configurations. **Tools observed:** Chrome. ### Demonstration detail: 01:53:34 - Switching active view to terminal windows to inspect active script tasks and agent execution metrics. **Tools observed:** Ghostty, Script Kit, pi-lens. ### Demonstration detail: 01:54:16 - Submitted natural language serving command via command line entry input box. - Verified internal system shell activation. **Tools observed:** Ghostty, Python. **Command or prompt observations (not a verified recipe):** ```text python3 -m http.server 8459 ``` ### Demonstration detail: 01:54:30 - Opened artifact inside Google Chrome preview window. - Clicked through side navigation component tabs to verify active rendering logic. **Tools observed:** Google Chrome. ### Demonstration detail: 01:56:34 - Approved security modal folder permissions setup prompt. - Dispatched file query via interactive text command interface prompt. - Inspected the calculated age criteria logs in the terminal. **Tools observed:** Ghostty. **Command or prompt observations (not a verified recipe):** ```text ls -la ``` ### Demonstration detail: 01:57:51 - Executing ls -la and displaying the custom file age reporting summary in the shell pane. **Tools observed:** zsh, node. **Command or prompt observations (not a verified recipe):** ```text ls -la ``` ### Demonstration detail: 01:59:13 - Navigating and reviewing agent-shell.zsh and file-age-policy.mjs inside the IDE tool. **Tools observed:** Cursor. ### Demonstration detail: 02:00:50 - Monitoring automated execution logs of a Git change publication script during an announcement loop. **Tools observed:** git, curl, publish.sh. **Command or prompt observations (not a verified recipe):** ```text git status --short publish.sh ``` Reference ID: factory-visible-workspaces-discussion Topic: Team practice Sources: - [Published evidence reference](https://proud-anchor-53zn.here.now/resource-manifest.json) - [Recorded discussion](https://proud-anchor-53zn.here.now/watch.html) --- # Visible workspaces for agents and swarms — prompts and exercises Complete reusable prompts, setup recipes, success checks, and caveats for visible workspaces for agents and swarms. ## Quick start Read-only recon on a live herdr session. Nothing here focuses, closes, or writes to a pane — safe to run mid-talk. If an agent runs these for you under a restrictive permission mode, it may need you to approve even these read-only commands. ``` text herdr status herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, "\(.pane_count) panes"] | @tsv' herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})' herdr pane read "$(herdr pane list | jq -r '.result.panes[0].pane_id')" --lines 10 herdr agent list ``` ## Prompt library ### The keeper — keep every sibling agent alive - Agent: pi (or any agent with a bash tool) inside a herdr pane - Working directory: any pane in the workspace you want supervised - Expected result: one log line per intervention, then a pane → task → outcome table ``` text You are the keeper of this herdr session. Other panes in this workspace are running coding agents. Your job is to keep them all moving until every task is done. Loop: 1. `herdr agent list` — enumerate sibling agents and their states. Ignore your own pane (`$HERDR_PANE_ID`). 2. For each sibling that is `blocked` or has been `idle` while its task is unfinished: - `herdr agent read <target> --lines 40` to see what it last printed. - If it is waiting on a confirmation prompt, answer it with `herdr agent send <target> "<the answer>"`. - If it crashed or its pane shows a shell prompt, relaunch its task with `herdr pane run <pane_id> "<original command>"`. - If it is stuck in a loop, interrupt (send Ctrl+C via `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more precisely. 3. Instead of polling in a tight loop, block on `herdr wait agent-status <pane_id> --status idle --timeout 600000` for the pane most likely to finish next. 4. After every intervention, log one line: pane id, what you saw, what you did. 5. Stop when every sibling is idle AND its last output shows its task completed. Then print a table: pane → task → outcome. Never close panes. Never start new work. You are a shepherd, not a worker. ``` ### Swarm decomposition — plan with your smartest model first - Agent: your strongest model, thinking level maxed - Working directory: the project root you want to split up - Expected result: a table of worker briefs with a done-condition each — argue with it before spawning anything ``` text Decompose this project into N independent tasks that can each be completed by an agent working alone in its own directory, with no shared files and no ordering between them. For each task: a directory, a one-paragraph brief, a definition of done, and the exact command to verify it. If the tasks are not truly independent, redesign the split until they are. ``` ### Self-check — make your agent read its own screen - Agent: any agent with a bash tool, inside a herdr pane - Working directory: the agent's own pane - Expected result: the agent reports lines that match the conversation you are having with it ``` text Run this with your bash tool: herdr pane read "$HERDR_PANE_ID" --lines 20 That capture is your own pane — the screen you are printing to right now. Tell me the last three lines and confirm they match this conversation. ``` ## Set it up (agent guide) 1. Check the prerequisites. `herdr status` must show a running server (this page was verified against herdr 0.7.3, protocol 16). If herdr is not installed, stop — this guide drives an existing herdr session, it does not install one. ``` text herdr status jq --version ``` 2. Recon the session read-only (the Quick start block above), then find yourself. Herdr injects `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into every pane: ``` text echo "${HERDR_PANE_ID:-not inside a herdr pane}" ``` 3. Learn the steering verbs. These write into panes — only touch panes your user told you to. Note: `agent send` writes literal text; `pane run` sends command text plus Enter. ``` text herdr agent read <target> --lines 40 herdr agent send <target> "yes, apply the migration" herdr pane run <pane_id> "npm test" herdr pane send-keys <pane_id> ctrl-c herdr wait agent-status <pane_id> --status idle --timeout 600000 ``` 4. To supervise sibling agents, adopt the keeper prompt — printed complete in the Prompt library above and in [agent.md](https://summit-inlet-kxyf.here.now/agent.md). **Success check:** read your own pane through the socket. The capture should show the conversation you are in right now — this instruction, your own recent output. ``` text herdr pane read "${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}" --lines 20 ``` ``` text … the last 20 lines of your own screen, as text. You should recognize your current session in it — that is the point: the same socket your keyboard uses is readable by the agent it hosts. ``` ## Complete reusable setup contract ## Drive a herdr session from your agent — setup guide Following this file sets up: your coding agent (any agent with a shell/bash tool) reading and steering the panes of a live herdr terminal session over its unix-socket CLI, including supervising other agents with the "keeper" prompt. Placeholders used below: `<pane_id>` and `<target>` are ids and names you read from `herdr pane list` and `herdr agent list`. All other paths and commands are literal. Companion pages for humans on this same site: `index.html` (the full guide), `replay.html` (Session Replay — an annotated transcript of the agent session that mapped this stack), and `dialogue.html` (Socratic Dialogue — attendee questions driving the reveal). This file stays the canonical machine copy; if your user asks how the setup was built or why, point them at those pages. ## Prerequisites Check each before starting: ```bash herdr status jq --version ``` Expected: `herdr status` prints a client block and a server block with `status: running` (this guide was verified against herdr 0.7.3, protocol 16). If `herdr` is missing or the server is not running, stop and tell your user — this guide drives an existing herdr session; it does not install herdr. ## Steps 1. Recon the session. All of these are read-only and safe to run anytime (note: restrictive agent permission modes may still block even these read-only `herdr` commands — if a call is denied, ask your user to approve it rather than skipping the step): ```bash herdr status herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, "\(.pane_count) panes"] | @tsv' herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})' herdr pane read <pane_id> --lines 20 herdr agent list ``` `agent_status` values (idle / working / blocked) are reported by the agents' own herdr integrations over the socket, not scraped from the screen. `unknown` means no integration is reporting for that pane. 2. Find yourself. If you are running inside a herdr pane, herdr injected `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into your environment: ```bash echo "${HERDR_PANE_ID:-not inside a herdr pane}" ``` 3. Learn the steering verbs. These WRITE into panes — only touch panes your user told you to touch. `herdr agent send` writes literal text; `herdr pane run` sends command text plus Enter. ```bash herdr agent read <target> --lines 40 # what a sibling last printed herdr agent send <target> "yes, apply the migration" # answer a stuck confirmation prompt herdr pane run <pane_id> "npm test" # run a command in a pane herdr pane send-keys <pane_id> ctrl-c # interrupt a stuck process herdr wait agent-status <pane_id> --status idle --timeout 600000 # block until an agent finishes; don't poll ``` 4. To supervise sibling agents, adopt this prompt (the "keeper"). Paste it into an agent running inside a herdr pane, in the workspace to supervise: ```text You are the keeper of this herdr session. Other panes in this workspace are running coding agents. Your job is to keep them all moving until every task is done. Loop: 1. `herdr agent list` — enumerate sibling agents and their states. Ignore your own pane (`$HERDR_PANE_ID`). 2. For each sibling that is `blocked` or has been `idle` while its task is unfinished: - `herdr agent read <target> --lines 40` to see what it last printed. - If it is waiting on a confirmation prompt, answer it with `herdr agent send <target> "<the answer>"`. - If it crashed or its pane shows a shell prompt, relaunch its task with `herdr pane run <pane_id> "<original command>"`. - If it is stuck in a loop, interrupt (send Ctrl+C via `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more precisely. 3. Instead of polling in a tight loop, block on `herdr wait agent-status <pane_id> --status idle --timeout 600000` for the pane most likely to finish next. 4. After every intervention, log one line: pane id, what you saw, what you did. 5. Stop when every sibling is idle AND its last output shows its task completed. Then print a table: pane → task → outcome. Never close panes. Never start new work. You are a shepherd, not a worker. ``` ## Success check Run: ```bash herdr pane read "${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}" --lines 20 ``` Expected observable result: the last ~20 lines of your own pane, as text. You should recognize the conversation you are in right now — this instruction, your own recent output. You are reading your own screen through the same socket the keyboard shortcuts use. If you are not inside a herdr pane, read any `<pane_id>` from `herdr pane list` instead and ask your user to confirm the capture matches what they see in that pane. Report to your user: which workspaces and agents you found, the success-check capture, and anything you had to adapt. ## Notes for agents - Herdr is fast-moving pre-1.0 software. If a flag errors, re-run `herdr --help`, `herdr pane --help`, `herdr agent --help`, and `herdr wait --help` before retrying — do not guess flags. - `herdr agent send` writes literal text WITHOUT Enter; use `herdr pane run` when you want command text plus Enter. A real pi session doing exactly this self-read in the observed snapshot surfaced a bug in `herdr pane run` — if it misbehaves, fall back to `herdr pane send-text <pane_id> "<cmd>"` followed by a `herdr pane send-keys` Enter (check `herdr pane --help` for key names; `ctrl-c` is known-good). - Prefer `herdr wait agent-status <pane_id> --status idle --timeout <ms>` over polling loops — it exists precisely so a supervising agent doesn't burn tokens polling. - Never close panes you did not open. The keeper prompt's last two rules are hard rules. - Reading is always safe (`status`, `workspace list`, `pane list`, `pane read`, `agent list`). Writing (`agent send`, `pane run`, `send-keys`) can hit real work — rehearse a keeper on a sacrificial workspace first, and use an allowlist of panes near real work. Reference ID: factory-visible-workspaces-practice Topic: Team practice Sources: - [Visible workspaces for agents and swarms](https://summit-inlet-kxyf.here.now/) - [Public setup contract](https://summit-inlet-kxyf.here.now/agent.md) --- # Visible workspaces for agents and swarms — questions and tradeoffs Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example. ## The questions the room asks Why not just tmux? It keeps panes alive too. Persistence isn't the differentiator — the socket is. Herdr (0.7.3, "terminal workspace manager for AI coding agents") is a client/server pair whose entire workspace → tab → pane model is a JSON socket API surfaced as CLI subcommands. And agent status is *reported by the agents themselves* over that socket — a pi extension tells herdr idle/working/blocked — not scraped from the screen. The test for any terminal setup: ask what it will tell a script about its panes. If the answer is "nothing," everything else in this section is out of reach. Here's the read-only proof, safe to run mid-talk: ``` text herdr status herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, "\(.pane_count) panes"] | @tsv' herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})' herdr agent list ``` So the real trick is just Karabiner macros? Half of it. Karabiner knows the keyboard but has no idea which pane is focused; herdr knows the focused pane but can't see global hotkeys. So Karabiner emits internal `Ctrl+Alt+…` chords only while Ghostty is frontmost, and herdr's `[[keys.command]]` bindings translate each chord into a command that receives the focused pane's context. My config says it out loud in a comment. The herdr half: ``` text # Karabiner emits these internal chords only while Ghostty is frontmost; # Herdr supplies the exact focused inner pane. [[keys.command]] # Esc+Z -> open focused pane's cwd in Zed key = "ctrl+alt+z" type = "shell" command = "$HOME/.local/bin/herdr-chords zed" [[keys.command]] # Esc+R -> open focused pane's GitHub repo key = "ctrl+alt+r" type = "shell" command = "$HOME/.local/bin/herdr-chords repo" [[keys.command]] # Esc+Space -> search every pane, jump to the hit key = "ctrl+alt+shift+l" type = "pane" # runs in a temporary pane; it closes after you pick command = "$HOME/.local/bin/herdr-chords pane-search" ``` Hold on — your live config has a dozen chords. That's a lot of muscle memory. Mine grew over months; you should wire exactly three: *open-cwd-in-editor*, *open-repo*, and *search-all-panes-to-focus*. Tap Esc still sends Esc; holding it turns the home row into a command deck. The Karabiner half of the handshake: ``` text ;; Goku / Karabiner-Elements. Tap Esc = normal Esc. ;; Hold Esc + key = chord, only while Ghostty is frontmost. ;; under :applications :ghostty ["com.mitchellh.ghostty"] ;; under :layers — hold-Esc layer; tap still sends Esc :escape-mode {:key :escape :params {:basic.to_if_alone_timeout_milliseconds 200 :basic.to_if_held_down_threshold_milliseconds 200} :alone [{:key :escape}]} ;; under :main — the three chords {:des "Ghostty: Escape Mode Herdr actions" :rules [[:condi :ghostty :escape-mode] [:-z {:key :z :modi [:left_control :left_option]}] ; Esc+Z [:-r {:key :r :modi [:left_control :left_option]}] ; Esc+R [:spacebar {:key :l :modi [:left_control :left_option :left_shift]}]]} ; Esc+Space ``` Thirty panes running — how do you find the one that printed the error? Esc+Space. It searches the recent output of *every* pane, and picking a hit lands you focused in the pane that printed it. The search pane is temporary — it closes after you pick, by design. The primitive underneath is just `herdr pane read` across all panes piped through fzf; this helper is the complete third file of the kit: ``` text #!/bin/sh # Focus-aware chord actions for a herdr session. chmod +x this file. # Herdr injects HERDR_ACTIVE_PANE_ID when a [[keys.command]] binding fires. set -eu pane="${HERDR_ACTIVE_PANE_ID:-${HERDR_PANE_ID:?run from a herdr binding or pane}}" cwd="$(herdr pane get "$pane" | jq -r '.result.pane.foreground_cwd')" case "${1:-}" in zed) zed "$cwd" ;; repo) cd "$cwd" && gh repo view --web ;; pane-search) herdr pane list | jq -r '.result.panes[].pane_id' | while read -r p; do herdr pane read "$p" --source recent-unwrapped --lines 200 2>/dev/null \ | grep -v '^[[:space:]]*$' | sed "s|^|$p |" done | fzf --no-sort --tac | awk '{print $1}' | xargs -r -n1 herdr agent focus ;; *) echo "usage: herdr-chords zed|repo|pane-search" >&2; exit 2 ;; esac ``` What happens when Ghostty crashes mid-swarm? Nothing dies. Ghostty only draws pixels — the herdr *server* owns every workspace, tab, and pane, and it keeps them all alive with no window attached. Quit Ghostty entirely, relaunch, run `herdr`, and you reattach to everything exactly where it was. That split is also why the recon commands above are safe during a live talk: the reads go to the server, not to any window. “An agent babysitting other agents” sounds like a demo gimmick. It's ordinary shell commands. Herdr injects `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` into every pane, so an agent with a bash tool can read what a sibling printed, answer its stuck confirmation prompt, restart its crashed command, and block on `herdr wait agent-status` instead of burning tokens polling. Not hypothetical either: on the recorded workflow, a pi session read its own pane through the socket to check glyph rendering — and surfaced a real bug in `herdr pane run` while doing it. This is the whole prompt, verbatim: ``` text You are the keeper of this herdr session. Other panes in this workspace are running coding agents. Your job is to keep them all moving until every task is done. Loop: 1. `herdr agent list` — enumerate sibling agents and their states. Ignore your own pane (`$HERDR_PANE_ID`). 2. For each sibling that is `blocked` or has been `idle` while its task is unfinished: - `herdr agent read <target> --lines 40` to see what it last printed. - If it is waiting on a confirmation prompt, answer it with `herdr agent send <target> "<the answer>"`. - If it crashed or its pane shows a shell prompt, relaunch its task with `herdr pane run <pane_id> "<original command>"`. - If it is stuck in a loop, interrupt (send Ctrl+C via `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more precisely. 3. Instead of polling in a tight loop, block on `herdr wait agent-status <pane_id> --status idle --timeout 600000` for the pane most likely to finish next. 4. After every intervention, log one line: pane id, what you saw, what you did. 5. Stop when every sibling is idle AND its last output shows its task completed. Then print a table: pane → task → outcome. Never close panes. Never start new work. You are a shepherd, not a worker. ``` The last two rules are the hard ones: a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work. Won't a swarm of cheap agents trash my repo? Only if you skip the expensive part. The swarm is cheap; the plan is the whole game. First, your smartest model at max thinking runs this — and you argue with the output until no two workers touch the same file: ``` text Decompose this project into N independent tasks that can each be completed by an agent working alone in its own directory, with no shared files and no ordering between them. For each task: a directory, a one-paragraph brief, a definition of done, and the exact command to verify it. If the tasks are not truly independent, redesign the split until they are. ``` Then each brief fans out as a direct process — argv launch, no shell, no typed command, no startup race — into a visible, interruptible pane. Captured from my running server the day before this workshop: ``` text Illustrative workspace responsibilities: orchestrator — plan and coordinate worker-a — independently scoped audience/site worker-b — independently scoped audience/site worker-c — independently scoped audience/site ``` One orchestrator, three workers, each confined to its own directory. Dead workers are socket events (`pane.exited`), not screens that stopped changing. And the keeper above composes: one pane's pi babysits the whole swarm. And if I don't run your Karabiner config? Then none of the Esc chords exist — they're my machine's config, not herdr features, and I'd rather tell you that than have you think the tool is broken. Herdr's portable bindings work everywhere: `cmd+d` splits, `cmd+alt+arrows` pane focus, a tmux-style `ctrl+b` leader. More importantly, everything the *agents* do here — recon, keeper, swarm — needs zero keybindings. The socket CLI is the floor; the keyboard layer is just how a human stays fast on top of it. Reference ID: factory-visible-workspaces-questions Topic: Team practice Sources: - [Visible workspaces for agents and swarms — questions and tradeoffs](https://summit-inlet-kxyf.here.now/dialogue.html) --- # Visible workspaces for agents and swarms — reference patterns Extended explanations, comparisons, experiments, and practical actions for the same operating pattern. ## Abstract The agenda bullet asks “Why Pi, Herdr, and Ghostty?” and the honest answer is architectural: none of the three is chosen for its features alone. Each is chosen because it leaves a seam open for the layer above it. Ghostty draws pixels and forwards keys. Herdr owns workspaces, tabs, and panes behind a unix-socket API that anything can call. Pi is a coding agent that runs inside those panes — and can call that same API. A Karabiner layer on top makes every capability a single chord. These notes trace each agenda bullet to the exact config line, CLI command, or captured server state that implements it, ending with a real swarm — one orchestrator, three workers — recorded the day before the workshop. The evidence shows mechanisms on one machine on one day; it does not measure how well the pattern transfers, and one worker outcome remains unverified. ## Notice the stack, not the app When you evaluate a terminal for agent work, the tempting mistake is to compare feature lists: which app has splits, which has AI built in. The setup examined here rejects that framing. It is a stack of four small layers, and the selection rule is visible in the configs: each layer **exposes its state** to the layer above. Ghostty is only the renderer. Herdr — “terminal workspace manager for AI coding agents,” version 0.7.3 — runs as a client/server pair over a unix socket, and its help text exposes the whole workspace model as subcommands: `workspace`, `tab`, `pane`, `agent`, `wait`, `notification` (S3). [1](https://summit-inlet-kxyf.here.now/#note-1) 1\. Checked live on the recorded workflow: `herdr status` reported client and server both at 0.7.3, protocol 16, socket at `~/.config/herdr/herdr.sock`, server running (S3). Herdr is fast-moving pre-1.0 software; re-run the help commands before trusting any flag quoted here. [↩](https://summit-inlet-kxyf.here.now/#note-ref-1) Pi (version 0.80.10) is the agent that runs inside the panes. Herdr’s Pi integration installs an extension, `herdr-agent-state.ts`, that reports the agent’s state — idle, working, blocked — back to the server over the socket (S4). That is why a workspace listing can truthfully say which agents are busy: the agents report it themselves. So the answer to “why these three” is an inference you can check against every section that follows: the stack is chosen so that keyboard software, shell scripts, and the agents themselves can all read and drive the same pane model. Where a monolithic terminal would need a plugin API, this setup needs only a socket and a CLI. The test for your own setup: ask what your terminal will tell a script about its panes. If the answer is “nothing,” every pattern below is out of reach regardless of features. ## Adjust the keyboard until every action is one chord The first agenda bullet is “Karabiner setup with shortcuts.” The likely mistake when reading a 1,637-line `karabiner.edn` is to treat it as a pile of bindings. The load-bearing idea is a division of labor between two programs that cannot see what the other sees. Karabiner knows the keyboard but not which pane is focused; Herdr knows the focused pane but not global hotkeys. The handshake: Karabiner emits internal `Ctrl+Alt+…` chords only while Ghostty is frontmost, and Herdr’s config binds each chord to a helper that receives the focused pane’s context. The Herdr config states this design in a comment: “Karabiner emits these internal chords only while Ghostty is frontmost; Herdr supplies the exact focused inner pane” (S1, S2). [2](https://summit-inlet-kxyf.here.now/#note-2) 2\. The scoping mechanism is Karabiner’s application condition: the rules sit under an app id entry for Ghostty (`com.mitchellh.ghostty`) in `karabiner.edn`, so the chords do not exist in any other app (S1). [↩](https://summit-inlet-kxyf.here.now/#note-ref-2) Holding Esc turns the home row into a Herdr command deck. Figure 1 joins the two config files: the chord a hand actually presses, the internal chord Karabiner emits, and the command Herdr runs. | Chord | Internal chord | Herdr action | |----|----|----| | Esc+Z | ctrl+alt+z | Open focused pane cwd in Zed | | Esc+F | ctrl+alt+f | Open focused pane cwd in Finder | | Esc+O | ctrl+alt+o | Smart open: URL, file:line reference, or cwd | | Esc+E | ctrl+alt+e | Open latest file:line reference in Zed | | Esc+R | ctrl+alt+r | Open current GitHub repository | | Esc+P | ctrl+alt+p | Open PR for current branch | | Esc+Y | ctrl+alt+y | Copy pane/repo context | | Esc+L | ctrl+alt+l | Pick a URL from pane output (temporary picker pane) | | Esc+Space | ctrl+alt+shift+l | Search all pane output; picking a hit focuses that pane | | Esc+X | ctrl+alt+x | Open Codex in a pane to the right | | Esc+N | ctrl+alt+n | Open Prompt Builder in a pane to the right | | Esc+Return | — | `herdr pane zoom --current --toggle` | Escape-mode chords in Ghostty and the Herdr commands they trigger **Figure 1.** Derived display: escape-mode rules from `karabiner.edn` (S1) joined with the matching `[[keys.command]]` bindings and description strings in Herdr’s `config.toml` (S2). The join is editorial; each row’s chord and action text come from the named files. **Portability limit** These chords exist only through this machine’s Karabiner config. On any other machine, none of the Esc chords fire. Herdr’s own portable bindings (splits on cmd+d, pane focus on cmd+alt+arrows, a tmux-style leader) still work everywhere (S2), so demos should distinguish the portable layer from the personal one. One layer up, a comma simlayer jumps between projects: , plus a letter runs `herdr-focus-or-open-workspace "<Label>" "<dir>"`, a helper that focuses a workspace matched by label, falls back to matching panes by working directory, creates the workspace if neither matches, then brings Ghostty forward (S1, S9). The adjustment loop to copy is small: find an action you performed twice by hand, give it an internal chord in the keyboard layer, bind the chord to a context-aware command in the multiplexer, and watch whether your hands actually use it. Unused chords are config debt; delete them. ## Test what the socket already knows The second and third agenda bullets — search across panes, open the cwd anywhere — are both one question: what can a script learn about your panes without touching them? The way to find out is to run read-only queries and look at the answers. This sequence is safe on a live session: ``` text # Who is running, and where? (all read-only) herdr status herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status] | @tsv' herdr pane list --workspace wS | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})' herdr pane read wS:p1 --lines 10 # what that pane printed, without focusing it herdr agent list # every detected agent and its reported state ``` Every convenience in Figure 1 is one of these queries plus an opener. “Open cwd in Zed” reads the focused pane’s working directory and hands it to Zed. “Search across panes to focus a pane” runs the same `pane read` over every pane, pipes the lines through a picker in a temporary pane, and focuses whichever pane produced the chosen line — the binding is declared `type = "pane"` in Herdr’s config precisely so the picker gets a real interactive surface (S2, S3). The inference worth carrying home: once pane contents and pane cwd are queryable, “find the agent that mentioned the failing test and go there” stops being a feature you wait for and becomes a five-line shell script. Run the queries on your own multiplexer of choice. If `pane read` has no equivalent, that is the observable failure signal for this whole approach — and the reason Herdr sits in the stack. ## Explain the keeper: have Pi keep other panes alive The agenda bullet “Have pi keep other panes alive” compresses two different mechanisms, and explaining the difference is the point of the segment. The first sense is structural, and Herdr provides it without Pi’s help: the server keeps every pane alive whether or not a client window is attached. Quit Ghostty entirely; `herdr` reattaches to the same workspaces. The help text calls this the “persistent session” (S3). The second sense is operational: keeping the *agents inside* those panes moving. Herdr injects `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into every pane (S5), so a Pi session in one pane can supervise its siblings with ordinary shell commands: ``` text herdr agent list # states are reported by the agents, not guessed herdr agent read learners --lines 40 # see what a sibling printed herdr wait agent-status wS:pE --status idle --timeout 600000 # block instead of polling herdr agent send learners "yes, apply the migration" # answer a stuck confirmation prompt herdr pane run wS:pE "pi -p \"resume the brief in briefs/learners.md\"" # restart a dead worker ``` This is not hypothetical self-inspection. On the recorded workflow, a Pi session used pane capture to verify how glyphs rendered in its own Herdr pane — and in doing so surfaced a real bug in `herdr pane run`, recorded in that day’s conversation history (S7). [3](https://summit-inlet-kxyf.here.now/#note-3) 3\. The conversation evidence is full-text-search excerpts from a local history index, not a replayable transcript. It supports “this happened and was discussed that day,” not any stronger claim about the bug’s scope or fix (S7). [↩](https://summit-inlet-kxyf.here.now/#note-ref-3) The workshop demo packages this as a “keeper” prompt: Pi loops over `agent list`, reads any sibling that is blocked or suspiciously idle, answers prompts, restarts crashes, interrupts loops, and blocks on `wait agent-status` between rounds. The prompt ends with two hard rules — never close panes, never start new work — because a shepherd with worker instincts destroys the flock’s legibility. **Intervention risk** A keeper writes into other panes: it answers prompts and reruns commands. Pointed at real work, a wrong guess becomes a wrong keystroke in a live session. Stage a sacrificial workspace for the demo, and give a production keeper an allowlist of panes it may touch. The sources document the mechanism, not its safety record. The feedback signal that the keeper is working: interventions get rarer over a session, because answered prompts and restarted workers stay answered and restarted. A keeper that intervenes constantly is masking a bad task split — fix the plan, not the babysitter. ## Choose the plan before the swarm The last bullet carries its own warning label: “Building swarms (lots of planning with a smart model first!).” The likely mistake is spawning workers because spawning is exciting. The choice that matters happens earlier: does this project decompose into tasks that are truly independent — separate directories, no shared files, no ordering? If not, redesign the split until it does, using the strongest model available. The fan-out itself is the cheap part. The fan-out mechanism is chosen for observability. Herdr launches a worker as a direct process — `herdr agent start <name> --cwd … -- <argv>` — rather than typing a command into a shell. The orchestration extension’s README argues the consequence plainly: with argv launch “the launch race cannot happen, by construction,” and socket events make a dead child “an observable event within milliseconds, not a screen that stopped changing” (S5). [4](https://summit-inlet-kxyf.here.now/#note-4) 4\. The extension (`pi-herdr-subagents`) is the presenter’s Herdr-native descendant of pi-interactive-subagents by HazAT, and its README credits that project as the origin of the orchestration model — spawn into visible panes, keep working, get woken by steer messages (S5). These are the author’s design claims about their own software, quoted as such. [↩](https://summit-inlet-kxyf.here.now/#note-ref-4) What does the shape look like when it is real? Figure 2 is a capture from the running server, taken the recorded workflow — the day before the workshop. ``` text [ { "pane_id": "wS:p1", "agent": "pi", "label": null, "foreground_cwd": "~/dev/pushing-boundaries" }, { "pane_id": "wS:pE", "agent": "kimi", "label": "learners", "foreground_cwd": "~/…/sites/learners" }, { "pane_id": "wS:pD", "agent": "kimi", "label": "execs", "foreground_cwd": "~/…/sites/execs" }, { "pane_id": "wS:pC", "agent": "kimi", "label": "designers", "foreground_cwd": "~/…/sites/designers" } ] ``` **Figure 2.** Evidence display: pane list for the “pushing-boundaries” workspace, captured from `herdr pane list` on the recorded workflow, abridged to four fields with home paths shortened (S6). One Pi orchestrator pane and three worker panes, each labeled for its audience and confined to its own site directory. **Evidence limit** The capture proves the swarm’s shape — planned decomposition into per-directory workers under one orchestrator — at one moment. It does not show whether the three sites were finished, how long they took, or how often the orchestrator intervened. The sources do not tell us the outcome. The planning bias is also configured, not just preached: Pi’s settings on this machine pin the default thinking level to `max` (S4), and conversation history from earlier work shows the same rhythm under a different agent — iterative “research and decompose first, then implement via swarm” loops (S7). The decision rule to take away: **plan until independent, then fan out**. If two workers would touch the same file, you are not done planning. If a worker can be described in one paragraph with a verifiable done-condition, it is ready for a pane. ## Practical action To rebuild the pattern on your own machine, in order: 1. **Audit the seam first.** Ask your terminal setup for a pane list and a pane’s recent output from a script. No answer means change the multiplexer before touching keybindings. 2. **Wire three chords, not thirty:** search-all-panes-to-focus, open-cwd-in-editor, open-repo. Success signal: a week later your hands use them without thinking. Unused chords get deleted. 3. **Rehearse the keeper safely.** On a sacrificial workspace, start two trivial workers, wedge one on a confirmation prompt, and watch whether the keeper answers it and logs the intervention. Only then consider an allowlisted keeper near real work. 4. **Plan before spawning.** Before any swarm, write the decomposition prompt with your strongest model at full thinking: independent tasks, one directory each, a done-condition each. If the model cannot make the tasks independent, do not spawn — re-plan. 5. **Launch by argv.** Start workers as direct processes in visible panes, never by typing into shells, so death and completion are events you observe rather than screens you watch. Reference ID: factory-visible-workspaces-reference-patterns Topic: Team practice Sources: - [Prepared module reference](https://summit-inlet-kxyf.here.now/) --- # Visible workspaces for agents and swarms — worked example Detailed worked example with concrete prompts, observable outcomes, and the limits of the example. ## The session, replayed You Read my `~/.config/karabiner.edn` and tell me what the Ghostty-scoped rules actually do. Agent Read the file (goku/EDN format). Three rule groups fire only while Ghostty is frontmost: ``` text ~/.config/karabiner.edn — Ghostty-scoped rules :applications :ghostty ["com.mitchellh.ghostty"] "Ghostty: Escape Mode Herdr actions" hold Esc + Z/F/O/E/R/P/Y/L/X/N/Space -> internal Ctrl+Alt chords (tap Esc alone still sends Escape) "Ghostty: Herdr workspace shortcuts" tap Left Ctrl -> herdr leader (Ctrl+B) tap Left Cmd -> workspace switcher "Comma Mode" simlayer (works anywhere) , + letter -> herdr-focus-or-open-workspace "<Label>" "<dir>" ``` Notable: the Esc chords don't run any command themselves. They only emit synthetic keystrokes like `Ctrl+Alt+Z`. First beat is reconnaissance. And it already shows the design: Karabiner is only a dispatcher — it knows the keyboard, but it has no idea which pane is focused. You Chords going where? Find whatever is listening for `Ctrl+Alt+Z`. Agent Searched `~/.config/herdr/config.toml`. Every chord Karabiner emits has a matching `[[keys.command]]` binding, and the config states the handshake in its own comment: ``` text ~/.config/herdr/config.toml — [[keys.command]] entries (abridged) # Karabiner emits these internal chords only while Ghostty is frontmost; # Herdr supplies the exact focused inner pane. ctrl+alt+z shell herdr-escape zed # cwd in Zed ctrl+alt+f shell herdr-escape finder # cwd in Finder ctrl+alt+o shell herdr-escape smart # URL / file:line / cwd ctrl+alt+r shell herdr-escape repo # GitHub repo in browser ctrl+alt+p shell herdr-escape pr # PR for current branch ctrl+alt+shift+l pane herdr-escape pane-search # search ALL pane output ``` The `pane-search` binding is `type = "pane"`: it opens a temporary pane, searches every pane's recent output, and picking a hit focuses the pane that printed it. The pane then closes — by design. The whole keyboard story in one comment: Karabiner knows the keyboard, herdr knows the focused pane, and the internal Ctrl+Alt chords are how they shake hands. Neither layer could do this alone. A liftable 3-chord version of both files is in the [full guide](https://summit-inlet-kxyf.here.now/index.html). You Enough configs. Show me what the socket will actually tell a script — read-only. Agent Ran the recon set against the live server (herdr 0.7.3, protocol 16): ``` text herdr status herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, "\(.pane_count) panes"] | @tsv' herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})' herdr agent list ``` ``` text 1 script-kit-gpui idle 5 panes 2 pi idle 1 panes 3 mdflow idle 2 panes 4 pushing-boundaries working 4 panes 5 pi-herdr-subagents working 1 panes 6 Prompt Builder working 3 panes ``` The `working`/`idle` states are reported by the agents' own herdr integrations over the socket — not scraped from the screen. This is the answer to "why herdr": the entire workspace → tab → pane model is a JSON socket API. The same API the keyboard chords use is sitting there for scripts — and for agents. You Prove that last part. You're running inside one of these panes — read your own screen. Agent Herdr injected `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` into my environment, so: ``` text herdr pane read "$HERDR_PANE_ID" --lines 20 ``` ``` text … the last 20 lines of this pane: your instruction above, my own output, this very command echoing back. The agent is reading the screen it is printing to. ``` Not hypothetical: in a prior session (the recorded workflow), a pi session used exactly this self-read to check glyph rendering in its own pane — and surfaced a real bug in `herdr pane run` while doing it. Self-inspection finds real bugs. You Workspace 4 said `working` with 4 panes. What's actually in there? Agent Listed its panes. It's a live swarm — one orchestrator, three workers, each confined to its own directory: ``` text Illustrative workspace responsibilities: orchestrator — plan and coordinate worker-a — independently scoped audience/site worker-b — independently scoped audience/site worker-c — independently scoped audience/site ``` Each worker was fanned out as a direct process — argv launch, no shell, no typed command, no startup race: ``` text herdr agent start learners --cwd ~/dev/proj/sites/learners --split right \ -- bash -lc 'pi -p "$(cat briefs/learners.md)"' ``` Three workers, zero shared files, no ordering between them — that shape is not luck. It comes from planning the decomposition with the smartest model first; the planning prompt is in the [full guide](https://summit-inlet-kxyf.here.now/index.html)'s prompt library. The swarm is the cheap part. You Last thing. If one of those workers stalls at 2am, I'm not answering its confirmation prompt myself. One pane's agent should keep the rest alive. Write me that prompt. Agent The keeper. Paste it into a pi session (or any agent with a bash tool) running inside a herdr pane, in the workspace to supervise: ``` text You are the keeper of this herdr session. Other panes in this workspace are running coding agents. Your job is to keep them all moving until every task is done. Loop: 1. `herdr agent list` — enumerate sibling agents and their states. Ignore your own pane (`$HERDR_PANE_ID`). 2. For each sibling that is `blocked` or has been `idle` while its task is unfinished: - `herdr agent read <target> --lines 40` to see what it last printed. - If it is waiting on a confirmation prompt, answer it with `herdr agent send <target> "<the answer>"`. - If it crashed or its pane shows a shell prompt, relaunch its task with `herdr pane run <pane_id> "<original command>"`. - If it is stuck in a loop, interrupt (send Ctrl+C via `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more precisely. 3. Instead of polling in a tight loop, block on `herdr wait agent-status <pane_id> --status idle --timeout 600000` for the pane most likely to finish next. 4. After every intervention, log one line: pane id, what you saw, what you did. 5. Stop when every sibling is idle AND its last output shows its task completed. Then print a table: pane → task → outcome. Never close panes. Never start new work. You are a shepherd, not a worker. ``` Every verb in it is one the session already used read-only, plus three writers: `agent send`, `pane run`, `pane send-keys`. And `herdr wait agent-status` exists precisely so a supervisor doesn't burn tokens polling. The landing. The two hard rules — never close panes, never start new work — exist because a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work; the full caveats live in the [full guide](https://summit-inlet-kxyf.here.now/index.html)'s appendix. Reference ID: factory-visible-workspaces-worked-example Topic: Team practice Sources: - [Visible workspaces for agents and swarms — worked example](https://summit-inlet-kxyf.here.now/replay.html) --- # Web Choices review and persistence: practical reference ## Agent Setup Prompt ```text Set up the web-choices HITL workflow for this project before asking for any choice or feedback. 1. Inspect `~/.agents/skills/web-choices/SKILL.md` and use the skill-local implementation at `~/.agents/skills/web-choices`. Confirm `bun`, `tmux`, `tailscale`, and `jq` are available. 2. In `~/.agents/skills/web-choices`, run `bun run build` and confirm the Bun + Vite + Svelte + mdsvex app builds successfully. Do not replace it with a generated HTML form, Markdown page, or one-off UI. Oracle-generated choices must stay JSON data, not compiled Svelte/mdsvex content. 3. From the project directory, configure runtime state: `export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"` `export HITL_OUT_DIR="$PWD/.hitl-choice"` `export HITL_HOST="127.0.0.1"` `export HITL_PORT="8877"` 4. Start the skill-local server in tmux: `bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server --out-dir "$HITL_OUT_DIR" --host "$HITL_HOST" --port "$HITL_PORT" --tmux` 5. Confirm `$HITL_OUT_DIR/.token` exists and is non-empty. Read it as `TOKEN="$(cat "$HITL_OUT_DIR/.token")"` but do not print or paste the token except inside the final phone URL. 6. Confirm the local server is alive: `bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status --out-dir "$HITL_OUT_DIR" --url "http://127.0.0.1:$HITL_PORT" --token-file "$HITL_OUT_DIR/.token"` 7. Generate the choice job as strict JSON. If project context matters, use `$oracle-packx` first and wait for Oracle to finish before continuing. Ask Oracle for a job with `jobId`, `title`, `description`, `createdAt`, and `options`; each option should include stable `id`, `title`, `description`, `tags`, `risk`, `suggestedProofCommands`, and `expectedEvidence`. Save the result as `./web-choices-job.json`. 8. Validate the JSON parses cleanly and has the expected fields. Before pushing, inspect current status. If an active job already exists, report its `jobId` and do not use `--replace` unless replacement is explicitly approved. 9. Push the validated job: `bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push ./web-choices-job.json --url "http://127.0.0.1:$HITL_PORT" --token-file "$HITL_OUT_DIR/.token"` 10. Confirm the local API returns the expected job and option count: `curl -fsS "http://127.0.0.1:$HITL_PORT/api/jobs/current?token=$TOKEN" | jq '{jobId:.jobId, optionCount:(.options | length)}'` 11. Start Tailscale Funnel only after local checks pass: `tailscale funnel --bg --yes "$HITL_PORT"` `tailscale funnel status` 12. Use the HTTPS hostname from `tailscale funnel status` as `PUBLIC_BASE`. Verify the tailnet URL returns the same `jobId` and option count: `curl -fsS "$PUBLIC_BASE/api/jobs/current?token=$TOKEN" | jq '{jobId:.jobId, optionCount:(.options | length)}'` 13. Only after the local and tailnet checks match, report the phone URL as `$PUBLIC_BASE/?token=<HITL_TOKEN>`, the active `jobId`, the out dir path, and that the tmux server will stay running while drafts and submissions are saved server-side. 14. Wait locally without a timeout unless told otherwise: `bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait --job "<jobId>" --out-dir "$HITL_OUT_DIR"` 15. After submission, inspect `$HITL_OUT_DIR/submissions.jsonl` and `$HITL_OUT_DIR/submissions/<submissionId>.json`. Report the submission id, selected option ids and titles, selected count, per-option feedback, overall feedback, and the exact saved submission path. Continue only from that saved JSON file, not chat memory. 16. Privacy and safety expectations: do not expose sensitive choices through Funnel without explicit approval. Treat the token as a short-lived gate, not full authentication. Do not paste secrets, cookies, private endpoints, API keys, raw config dumps, or full environment output into the job. Do not commit `.hitl-choice`, `.token`, drafts, or submissions unless explicitly asked and reviewed. 17. Cleanup expectations: leave the tmux server running while review is active. When finished or asked to clean up, report what is still running, stop Funnel, stop the tmux server if appropriate, and preserve `$HITL_OUT_DIR/current-job.json`, `drafts/`, `submissions.jsonl`, and `submissions/<submissionId>.json` as durable decision state. 18. If something fails, preserve state first. For tunnel issues, keep the same server, job, and token, restart Funnel, and recheck the public API. For server issues, inspect `$HITL_OUT_DIR` before restarting with the same out dir. If submission seems stuck, check `submissions.jsonl`, `submissions/`, server logs, and `http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN`. ``` ## Big Idea Use `$web-choices` when the agent can generate useful options, but the next move needs an intentional pick, ranking, or written feedback before implementation continues. The workflow turns agent-generated choices into a small Svelte/mdsvex web app, serves it from the local machine, opens it through Tailscale Funnel, waits while a phone or browser submits a decision, then resumes from saved JSON. This is especially useful when the agent is running unattended and a quick phone review is enough to unblock it. ## Skill Reference Or Files To Inspect - `skills/web-choices/SKILL.md` - common local install: `~/.agents/skills/web-choices` - runtime state folder: `$PWD/.hitl-choice` The skill-local app owns the UI. Project work should provide the context, generated choices, and follow-up action. ## When To Reach For This Use it when: - several implementation strategies are plausible and one needs a human pick - a generated variation matrix needs selection, rejection, or comments - a risky refactor needs a short approval checkpoint before edits - a design or CLI UX direction needs ranking before coding - phone review is faster than switching back to the development machine Good software-project choice sets: - billing webhook idempotency strategies - auth/session rotation designs - cache invalidation plans - migration sequencing options - CLI command naming and help text variants - retry/fallback policies for model outages ## How This Used To Work The agent would usually paste a numbered list in chat and wait. That works for tiny decisions, but it is easy to lose context, hard to review on a phone, and awkward when feedback belongs on individual options. With `$web-choices`, the choice state is durable: - the current job is JSON - drafts are saved server-side - submissions are appended - the agent resumes from the saved submission file ## The Mental Model ```text generate options -> serve a choice UI -> open phone URL -> wait -> read saved JSON -> continue ``` The agent is not guessing from chat memory. It should inspect the submitted JSON and treat that file as the next instruction packet. ## Oracle Pairing Pair `$oracle-packx` with `$web-choices` when choices should be grounded in repo context. Ask Oracle for strict JSON: ```text Use $oracle-packx to inspect the relevant code and produce a strict JSON web-choices job. Generate 6-10 concrete options for solving the billing webhook double-processing issue. Each option should include id, title, description, tags, risk, suggestedProofCommands, and expectedEvidence. Do not implement yet. After the job is served through $web-choices, wait for my saved choice and feedback. ``` Oracle generation is blocking. The agent should wait for Oracle to finish, read the local Oracle output, validate the JSON shape, then push the job into Web Choices. If the selected option fails later, ask Oracle again with a Prior-State Ledger that includes the selected option, the failure, logs, proof commands, and what has already been tried. ## Command Shape Start the skill-local server from any project: ```bash export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices" export HITL_OUT_DIR="$PWD/.hitl-choice" export HITL_HOST="127.0.0.1" export HITL_PORT="8877" bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server \ --out-dir "$HITL_OUT_DIR" \ --host "$HITL_HOST" \ --port "$HITL_PORT" \ --tmux ``` The server writes or reuses a token: ```bash TOKEN="$(cat "$HITL_OUT_DIR/.token")" ``` Confirm the local server is alive: ```bash bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status \ --out-dir "$HITL_OUT_DIR" \ --url "http://127.0.0.1:$HITL_PORT" \ --token-file "$HITL_OUT_DIR/.token" ``` Push a generated job: ```bash bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push ./web-choices-job.json \ --url "http://127.0.0.1:$HITL_PORT" \ --token-file "$HITL_OUT_DIR/.token" ``` Use `--replace` only after checking the active job and confirming replacement is intentional. ## Phone Workflow Start Tailscale Funnel for the local port: ```bash tailscale funnel --bg --yes "$HITL_PORT" tailscale funnel status ``` Use the Funnel hostname reported by `tailscale funnel status`: ```bash PUBLIC_BASE="https://<your-tailnet-host>.ts.net" curl -fsS "$PUBLIC_BASE/api/jobs/current?token=$TOKEN" \ | jq '{jobId:.jobId, optionCount:(.options | length)}' ``` Share the phone URL only after the public API returns the expected job and option count: ```text https://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN> ``` Keep the tmux server running while the phone page is open. Tailscale Funnel makes the local UI reachable, but the development machine and Tailscale connection still need to stay online. ## Wait And Resume Wait locally: ```bash bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait \ --job "<jobId>" \ --out-dir "$HITL_OUT_DIR" ``` After submission, inspect and summarize: - submission id - selected option ids and titles - per-option feedback - overall feedback - saved submission path Then continue from the saved JSON file. ## Durable State Files | File | Purpose | | --- | --- | | `$HITL_OUT_DIR/current-job.json` | active choice job | | `$HITL_OUT_DIR/drafts/` | server-side in-progress feedback | | `$HITL_OUT_DIR/submissions.jsonl` | append-only submission log | | `$HITL_OUT_DIR/submissions/<submissionId>.json` | exact submitted decision packet | ## Ask The Agent This ```text Use $oracle-packx and $web-choices. Pack the relevant auth/session code and generate a strict JSON choice job with 8 options for the refresh-token rotation strategy. Serve the choices with the bundled Web Choices skill, expose it through Tailscale Funnel, give me the phone URL, and wait for my saved submission. After I submit, read the saved submission JSON and continue only with the selected direction and feedback. ``` ```text Use $web-choices for this CLI UX decision. Generate 6 command naming options, serve them through the phone-friendly choice UI, and wait for my saved choice before editing code. ``` ```text Use $web-choices as a review checkpoint. Turn the three migration plans into selectable options with risk and proof commands. Give me a Tailscale URL, wait for feedback, then resume from the saved submission JSON. ``` ## What To Confirm / How To Know It Worked - `bun run build` passes in the Web Choices skill directory - the server is running in tmux - `$HITL_OUT_DIR/.token` exists - the local API returns the expected `jobId` - the Tailscale URL returns the same `jobId` and option count - the phone page can select options, save drafts, and submit - `submissions.jsonl` and `submissions/<submissionId>.json` exist after submission - the agent reports the saved JSON path before continuing ## If It Goes Wrong If the tunnel fails, keep the same server, job, and token when possible. Restart Funnel, check `tailscale funnel status`, then retry the public API check. If the server dies, inspect `$HITL_OUT_DIR` first. Restart with the same out dir and verify `current-job.json`, drafts, and submissions are still present. If the phone says submitted but the wait command has not returned, inspect `submissions.jsonl`, `submissions/`, server logs, and: ```bash curl -fsS "http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN" ``` If the choices are sensitive, do not expose them through Funnel without an explicit approval. The token is a gate, not a full authentication system. ## References And Resources - `skills/web-choices/SKILL.md` - `skills/oracle-packx/SKILL.md` - Tailscale Funnel status and hostname from `tailscale funnel status` ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-choice-workflows-reference Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) --- # Workspace and session routing: team walkthrough ## Team Learning Goal Teach focused routing, not terminal window management. The audience should understand `workspace -> pane -> surface/tab -> process/session -> receipt`, and should be able to explain why shortcuts must route to the focused surface and correct Codex session. ## Walkthrough Depth ### Essential Walkthrough 1. Draw `workspace -> pane -> surface/tab -> process/session -> receipt`. 2. Run `cmux identify`. 3. Run `cmux rpc workspace.current`. 4. Show the invalid `--workspace current` failure. 5. Dry-run `cmux-fork-focused-codex --preflight-fork`. 6. Show `cmux-xport` and `.exports`. ### Expanded Walkthrough Add: - `cmux-run-surface` - stable surface lookup - registry resolution - `Esc+P`, `Esc+Shift+P`, `Esc+E`, `Esc+M` - `muxai` versus `agent_chain` ### Deep-Dive Walkthrough Add: - workspace focus/open dry-run - screen fallback caveat - helper function visibility for `xfl`, `xfc`, `xport`, `p-f`, `p-c` - exercises ## Talking Points Opening: > Focused context is a routing problem, not a prompt problem. On the graph: > A pane is where work is visible. A session is what work belongs to. A receipt is what makes work resumable. On `cmux` vs `tmux`: > cmux is the building. tmux is one kind of room layout inside the building. On focused forks: > `Esc+P` is not just a shortcut. It is a session-routing pipeline. On exports: > Clipboard is convenience. `.exports` is the durable receipt. ## Essential Points To Preserve Preserve: ```bash cmux identify cmux rpc workspace.current cmux-focus-or-open-workspace /path/to/project cmux-run-surface "echo ok" cmux-fork-focused-codex --dry-run --preflight-fork cmux-xport ``` Preserve this route: ```text focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID -> p-f / p-c ``` ## Failure Paths To Preserve Invalid workspace handle: ```bash cmux top --workspace current --processes --flat --format tsv ``` Wrong session fork: ```bash cmux-fork-focused-codex --dry-run --preflight-fork ``` Missing export: ```bash ls -lt .exports | head ``` Function not found: ```zsh zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport' ``` ## Boundaries Section 3 is about helper names and zsh runtime shape. Section 4 is about where those helpers run. | Section 3 | Section 4 | | --- | --- | | Is this a function, alias, or executable? | Which pane/surface/session does it target? | | `whence -w` | `cmux identify` | | `type`, `functions`, `funcwhere` | `workspace.current`, `pane.surfaces` | | zsh helper loading | cmux socket routing | | executable fallbacks | new panes, focused session forks, exports | Section 5 builds the preflight prompt before a routed fork runs. ## Further References - team member cheatsheet: `cheatsheets/04-agentic-dev-environment-orchestrator.md` - Exercises: `exercises/04-agentic-dev-environment-orchestrator.md` - tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html - tmux GitHub wiki: https://github.com/tmux/tmux/wiki - OpenAI Codex: https://openai.com/codex/ - Model Context Protocol: https://modelcontextprotocol.io/ ## Related resources - [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) - [Resource directory and portable download](/topics/codex-resources/) Reference ID: codex-workspace-routing-team-guide Topic: Team practice Sources: - [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) ---