DEV Community: Quinn Wang

Which Setup Step Actually Blocks Your First Run?

Quinn Wang — Tue, 27 Oct 2026 13:12:25 +0000

The step that decides whether a new contributor finishes setup is rarely the step your README spends the most words on. I learned this the boring way: I timed every step of a first run, wrote one JSON line per step, and only then saw which step was really eating the first fifteen minutes. The fix that mattered was not better prose for that step, it was a two-second version check that failed loudly before the expensive work started. What follows is the harness I use now, plus the two habits that stopped me from guessing when a run failed.

Aggregate setup time is a polite fiction

When someone tells you setup takes ten minutes, ask them what they actually measured. They usually measured their own last successful run, on a warm cache, on the machine they have been using for a year. That number is not a distribution, it is a memory, and it says nothing about the person whose first run ends in a stack trace about engines. Would you rather fix a step that is slow, or a step that quietly decides whether people finish at all?

Averages hide the shape of the problem, which is why I stopped reporting totals. A step that passes for eight people in two minutes and fails for two people in forty is not a two-minute step; it is a fork in the road with the sign pointing the wrong way. What I want to know is narrow and answerable: which step is both slow and unreliable, because that is the only one worth changing this week.

A preflight timer that fits in one file

The harness is deliberately dull: bash, one JSONL file per run, no dashboard, no SDK, no telemetry I have to defend in a review. Each step records its wall time and a pass or fail, and the script keeps going after a failure, because the failure you did not record is the one that ruins your afternoon.

#!/usr/bin/env bash
# preflight.sh — time each setup step, record pass/fail as JSONL.
# Unexecuted template: replace the step list with what your repo actually needs.
set -uo pipefail

OUT="${1:-/tmp/preflight-$(date -u +%Y%m%dT%H%M%SZ).jsonl}"
LOG="${OUT%.jsonl}.log"
: > "$OUT"; : > "$LOG"

now_ms() { python3 -c 'import time; print(int(time.time()*1000))'; }

run_step() {
  local id="$1"; shift
  local start end status
  start=$(now_ms)
  if "$@" >>"$LOG" 2>&1; then status=pass; else status=fail; fi
  end=$(now_ms)
  printf '{"step":"%s","ms":%d,"status":"%s"}\n' \
    "$id" "$((end - start))" "$status" >> "$OUT"
}

run_step versions bash -lc 'node --version && python3 --version'
run_step clone    bash -lc 'git clone --depth 1 "$REPO_URL" /tmp/pf-repo'
run_step install  bash -lc 'cd /tmp/pf-repo && npm ci --no-audit --no-fund'
run_step build    bash -lc 'cd /tmp/pf-repo && npm run build --if-present'
run_step smoke    bash -lc 'cd /tmp/pf-repo && npm test -- --bail'

Running it five times on cold caches gives you something to argue with, and jq turns the pile into one sorted answer per step. The blocking field is my own blunt weighting: median milliseconds multiplied by the failure rate plus a small floor, so a fast step that always fails still surfaces near the top.

jq -s '
  group_by(.step)
  | map({step: .[0].step,
         runs: length,
         fails: (map(select(.status=="fail")) | length),
         p50_ms: (map(.ms) | sort | .[length/2 | floor])})
  | map(. + {blocking: (.p50_ms * ((.fails / .runs) + 0.1) | floor)})
  | sort_by(-.blocking)
' /tmp/preflight-*.jsonl

I do not treat that score as science, because it is not; it is a way to end a meeting where everyone has a different favourite step. If the top row is your install step and it fails half the time, you have learned more in one minute than a week of reading complaints. Where is the signal in your own setup, honestly?

The one fix that mattered was a version check

On one repo, five of seven failed runs died in the same place, and it was not the build. People were installing dependencies against a Node major that the lockfile did not want, and the error only appeared after a three-minute download. We had written three careful paragraphs about the right version in the README, which is a lovely artefact that nobody reads at nine in the morning. The fix was a step zero that costs two seconds and names the culprit out loud.

# step 0 — fail in two seconds instead of twenty minutes
want=$(awk '/^nodejs/ {print $2}' .tool-versions)
have=$(node --version 2>/dev/null | sed 's/^v//')
if [ "$have" != "$want" ]; then
  echo "node $have != pinned $want" >&2
  exit 64
fi

Wrap that in run_step versions and it lands in the log with almost no milliseconds and a clean fail, which is exactly what you want from a gate. The lesson generalises beyond Node: move the constraint out of prose and into a check that runs before the expensive work. A fast loud failure is a gift, while a slow quiet one is a support ticket with extra steps.

Is it me, or is it the repo?

The hardest question in a first fifteen minutes is whether the breakage belongs to the repository or to the laptop. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option are supplied by the operator and are the two pieces I reach for here; the terms, quotas and availability change over time, so check the current documentation before you plan around them. The server option is the useful one for triage: run the identical preflight.sh inside a known-good baseline, then diff two files instead of reading tea leaves.

# local run, then the same script against the baseline host
./preflight.sh /tmp/pf-local.jsonl
# run it again in the baseline environment you have access to

diff <(jq -r '"\(.step) \(.status)"' /tmp/pf-local.jsonl | sort) \
     <(jq -r '"\(.step) \(.status)"' /tmp/pf-baseline.jsonl | sort)

If the baseline passes everything and your laptop fails at install, stop rewriting the README and go look at your toolchain. The second piece is smaller: when a log is genuinely ambiguous, a model call can sort it into toolchain, network, permissions or unknown. I keep a keyword classifier as the default path and treat the model as an optional hook, so the script still works offline and on a locked-down runner.

classify() {
  local log="$1"
  grep -qiE 'EACCES|permission denied' "$log" && { echo permissions; return; }
  grep -qiE 'ECONNRESET|ETIMEDOUT|ENOTFOUND' "$log" && { echo network; return; }
  grep -qiE 'engine|unsupported|version' "$log" && { echo toolchain; return; }
  echo unknown   # swap for a model call; read endpoint and model id from current docs
}

What the numbers cannot tell you

One run is an anecdote, so I only trust a row after about five cold-cache runs, and I only trust a failure rate after roughly eight fresh machines across at least two operating systems. Wall clock on a shared CI box is noisy, and a baseline environment drifts away from your users' laptops over time, which makes it a reference point rather than proof. The score also cannot see humiliation: a step that takes four seconds and prints a wall of red text will lose you a contributor just as fast as a slow one.

So who should skip all of this? If your setup is already one command that passes on a clean container, you have solved the problem this article measures, and a devcontainer or Nix flake probably buys you more than a timing harness. If your dependencies are private or your network policy forbids an external baseline, you can still run the per-step timing locally, but the diff loses most of its value. Small teams of two or three contributors may also find that a pinned toolchain file alone gets them most of the way, with no JSONL at all.

If you want a baseline machine without provisioning one, the free server option is the cheapest way I have found to answer the is-it-me question, so run the script twice and compare two boring files. Then ask the only question that matters: which single step would you delete from a stranger's first fifteen minutes today?

The Slow Step Should Never Wait Its Turn

Quinn Wang — Mon, 26 Oct 2026 11:42:33 +0000

Fifteen minutes is a budget, not a vibe, and the fastest way to blow it is to schedule your slowest step last. I keep meeting the same first-run experience: three correct steps, written in the wrong order, defended by nobody. The steps are usually fine — the schedule is what leaks. So this is a post about ordering, with a harness you can point at your own setup tonight.

The loop I care about is deliberately small: prove the key works, get one reply from a model, get one answer from a server. Free model access and a free server option make that loop cheap enough to restart five times in an afternoon, which is exactly what a first-run budget needs. The setup I am pointing the harness at here uses MonkeyCode's free model access and free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Here is the naive version, and yes, it is the version I wrote first. Three awaits in a column, each waiting for the one above it, even though almost nothing about them depends on each other.

// serial.mjs — the shape of most quickstarts, including my own first draft
const key    = await checkAuth();     // one request
const reply  = await askModel();      // one request, but only after auth resolves
const health = await bootServer();    // a cold start, but only after the model replies

Ask the obvious question out loud: does the server boot need the model reply before it can begin? No. Does auth need the boot at all? Also no. So why is the slowest stage sitting at the bottom of the file? Because it was written last, and nobody re-read the file with a stopwatch in hand.

That is the whole teardown, and the fix that mattered is one line of scheduling, not three new features.

// the fix: the slow, idempotent stage starts first and runs beside the fast one
const [bootResult, authResult] = await Promise.all([boot(), auth()]);
const modelResult = authResult.status === "ok"
  ? await model()
  : { stage: "model", status: "skipped", ms: 0, note: "auth failed first" };

Wall clock goes from boot + auth + model to roughly max(boot, auth) + model. If your cold boot is the long pole — and it usually is, because a free server option will happily cold-start for you — you have just removed almost all of it from the critical path. If the boot is not the long pole, the harness tells you so and you delete that branch. Either way you stop guessing.

Here is the full harness, no dependencies, Node 18 or newer. Every stage has a name, its own budget, and an abort handle, so a hang becomes a labelled timeout instead of a silent stare at the terminal.

#!/usr/bin/env node
// envelope.mjs — three first-run probes under one 15-minute envelope.
// Env: MODEL_BASE_URL, MODEL_API_KEY, MODEL_NAME, SERVER_HEALTH_URL
// Optional: BUDGET_AUTH_MS, BUDGET_MODEL_MS, BUDGET_BOOT_MS, ENVELOPE_BUDGET_MS, LEDGER_PATH
import { writeFileSync } from "node:fs";

const BUDGET_MS = Number(process.env.ENVELOPE_BUDGET_MS ?? 900_000);
const STAGE_BUDGET = {
  auth:  Number(process.env.BUDGET_AUTH_MS  ?? 60_000),
  model: Number(process.env.BUDGET_MODEL_MS ?? 120_000),
  boot:  Number(process.env.BUDGET_BOOT_MS  ?? 240_000),
};

const t0 = performance.now();
const elapsed = () => Math.round(performance.now() - t0);

// Never throws: a failed stage returns a failed row, so one error cannot hide the others.
async function stage(name, fn) {
  const budget = STAGE_BUDGET[name];
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), budget);
  const started = performance.now();
  try {
    await fn(ctrl.signal);
    return { stage: name, status: "ok", ms: Math.round(performance.now() - started), note: "" };
  } catch (err) {
    const status = err.name === "AbortError" ? "timeout" : "error";
    return { stage: name, status, ms: Math.round(performance.now() - started), note: String(err.message ?? err) };
  } finally {
    clearTimeout(timer);
  }
}

const auth = () => stage("auth", async (signal) => {
  const key = process.env.MODEL_API_KEY;
  if (!key) throw new Error("MODEL_API_KEY unset — this is an auth failure, not a model failure");
  const res = await fetch(`${process.env.MODEL_BASE_URL}/models`, {
    headers: { authorization: `Bearer ${key}` }, signal,
  });
  if (!res.ok) throw new Error(`auth endpoint said ${res.status}`);
});

const model = () => stage("model", async (signal) => {
  const res = await fetch(`${process.env.MODEL_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${process.env.MODEL_API_KEY}` },
    body: JSON.stringify({
      model: process.env.MODEL_NAME,
      messages: [{ role: "user", content: "Reply with the single word: ready" }],
      max_tokens: 8,
    }),
    signal,
  });
  if (!res.ok) throw new Error(`model endpoint said ${res.status}`);
});

const boot = () => stage("boot", async (signal) => {
  const res = await fetch(process.env.SERVER_HEALTH_URL, { signal });
  if (!res.ok) throw new Error(`health endpoint said ${res.status}`);
});

// Schedule: the slow idempotent stage goes first, beside auth. Model waits for auth only.
const [bootRow, authRow] = await Promise.all([boot(), auth()]);
const modelRow = authRow.status === "ok"
  ? await model()
  : { stage: "model", status: "skipped", ms: 0, note: "auth failed first" };

const rows = [authRow, modelRow, bootRow];
const width = Math.max(...rows.map(r => r.stage.length));
for (const r of rows) {
  console.log(`${r.stage.padEnd(width)}  ${r.status.padEnd(7)}  ${String(r.ms).padStart(6)}ms  ${r.note}`);
}

const total = elapsed();
const bad = rows.filter(r => r.status !== "ok");
console.log(`\nverdict: ${bad.length ? "outside — " + bad.map(b => b.stage).join(", ") : "inside the envelope"}`);
console.log(`wall clock ${(total / 1000).toFixed(1)}s of a ${(BUDGET_MS / 1000).toFixed(0)}s budget`);

writeFileSync(process.env.LEDGER_PATH ?? "envelope-ledger.json",
  JSON.stringify({ runAt: new Date().toISOString(), totalMs: total, rows }, null, 2));

process.exitCode = bad.length === 0 && total <= BUDGET_MS ? 0 : 1;

Run it with the cheapest possible inputs, and do not commit the key:

MODEL_BASE_URL="$BASE" MODEL_NAME="$NAME" SERVER_HEALTH_URL="$HEALTH" \
  MODEL_API_KEY="$(cat ~/.secrets/trial-key)" node envelope.mjs

echo "exit code: $?"   # 1 means the envelope was missed, and the rows say where

The output format matters more than my numbers, which I am not going to pretend to know for your network. It looks roughly like this, with NN.Ns standing in for whatever your machine actually does:

auth    ok         NN.Ns
model   ok         NN.Ns
boot    ok         NN.Ns

verdict: inside the envelope
wall clock NN.Ns of a 900s budget

Now the part I actually care about: the ledger file behind the verdict. One run is an anecdote, but six runs on six mornings answer a much better question — is this stage slow, or was that one Tuesday slow? Compare totalMs across the file and read the row that keeps winning. Blaming the model for a cold boot is the most common misdiagnosis I have watched people make, and it costs them an afternoon of prompt tweaking that was never going to help.

Long pole in the ledger	First move
`boot` dominates	Start it first and let it warm while auth runs; consider a keep-warm ping before you sit down
`auth` dominates	Cache the exchange locally for the session; a 401 loop is not a model problem
`model` dominates	Shrink the probe to a two-token reply before you judge latency
Nothing dominates, but the total is over	The envelope is wrong, not the provider; write down what you actually need

A few honest limitations, because this harness is a stopwatch, not a diagnosis. Free tiers queue, rate-limit, and change underneath you, so a green run today is evidence about today only. The parallel branch assumes your server boot is idempotent and safe to cancel, which is not true for every service, and behind a corporate proxy you are mostly measuring the proxy. And the script proves which stage is slow without telling you why it is slow — you still have to read a log.

Who should skip this? Teams on committed infrastructure with stable latency and real monitoring, because the ledger is a downgrade from what they already have. Anyone whose first fifteen minutes are dominated by a compiler toolchain, since the harness will just confirm a truth you already resent. And anyone who wants to turn this into a leaderboard — it measures your network and your order of operations, not the quality of anybody's model.

If you want something free to break while you test the schedule, the free model access and free server option are a fair place to point the harness; check the current quotas in your own dashboard rather than trusting a number in a blog post, mine included. Then move one await and watch the wall clock change shape, because that is the whole trick.

Stopwatch the Cold Start, Not the Model

Quinn Wang — Tue, 20 Oct 2026 09:48:52 +0000

Stopwatch the Cold Start, Not the Model

The first conclusion I want to hand you is uncomfortable: in a brand-new AI-assisted workspace, the model is almost never your bottleneck. The cold start is, and it stays invisible because nobody writes timestamps down. Ask ten developers where their first fifteen minutes went and nine will blame the model, which is a polite way of saying they never measured. I now treat onboarding as a latency problem with a p99 budget, and the change that moved the number most was not a smarter model at all.

So let me show you the instrument first and the opinions second, because an argument about free tiers without a stopwatch is just vibes with a changelog attached. The script below is deliberately boring: it records a millisecond timestamp before and after each step you already run, then prints the deltas. Nothing in it is specific to any vendor, which is exactly why it survives the next time you switch tools.

#!/usr/bin/env bash
# scripts/cold-start.sh — timestamp every step of a fresh workspace bootstrap.
set -euo pipefail

LOG="${LOG:-cold-start.tsv}"
: > "$LOG"

now_ms() { python3 -c 'import time; print(int(time.time() * 1000))'; }
mark()   { printf '%s\t%s\n' "$(now_ms)" "$1" >> "$LOG"; }

mark "boot"

mark "install:start";  ./scripts/install-toolchain.sh;      mark "install:end"
mark "deps:start";     npm ci --no-audit --no-fund;          mark "deps:end"
mark "auth:start";     ./scripts/check-creds.sh;             mark "auth:end"
mark "model:start";    ./scripts/smoke-task.sh > /tmp/smoke.patch; mark "model:end"

mark "apply:start"
git apply --check /tmp/smoke.patch && git apply /tmp/smoke.patch
mark "apply:end"

The report is six lines of awk, and I keep it in the repo next to the script so the numbers are comparable across weeks. Reading a table beats remembering a feeling, especially when the feeling is "it seemed slow".

awk -F'\t' '
  NR==1 { start=$1; prev=$1; printf "%9s %9s  %s\n", "delta_ms", "total_ms", "step"; next }
  { printf "%9d %9d  %s\n", $1-prev, $1-start, $2; prev=$1 }
' cold-start.tsv

Now run it three times, with the container thrown away between runs, because a warm cache will happily lie to you. I use a throwaway image precisely so that "it works on my machine" cannot creep into the measurement.

for i in 1 2 3; do
  docker run --rm -v "$PWD:/w" -w /w node:22-slim ./scripts/cold-start.sh
  mv cold-start.tsv "cold-$i.tsv"
 done

The variance between those three runs matters more than the absolute number, and I learned that the hard way. If run one and run three differ by more than about thirty percent on the same step, you are not measuring your setup, you are measuring the network. That distinction changes what you fix, so please do not skip the repetition.

Here is how I bucket the deltas, and these thresholds are opinions you should tune rather than laws. The point of a table like this is to stop the argument before it starts, because "slow" is not actionable and "install took 412 seconds" is.

Bucket	Typical symptom	Act when	First move
install	toolchain download, version drift	over ~4 min	pin versions, cache the layer
deps	`npm ci` re-resolving a lockfile	over ~2 min	commit the lockfile, use `ci`
auth	silent 401 retries, wrong profile	any failure	fail loudly, never retry blind
model	first round trip, no output	over ~60 s	send a trivial prompt, not the real task
apply	patch rejected, whitespace noise	any failure	shrink the smoke task to one file

The one fix that mattered for me was not faster inference; it was turning the cold start into a single warm step that either succeeds or fails in under a minute. I put a warm target in the Makefile, and now every new machine, container, or teammate runs exactly one command before touching the real work.

warm:
    ./scripts/install-toolchain.sh --pinned
    npm ci --no-audit --no-fund
    ./scripts/smoke-task.sh > /dev/null   # cheap proof that creds and endpoint answer
    ./scripts/cold-start.sh --report      # keeps the number honest over time

Why does a smoke task beat a real task as the first move? Because a real task mixes three unknowns at once — your prompt, the endpoint, and the repository state — and you cannot debug three unknowns together. A tiny task that touches one file separates them, and it costs almost nothing when the environment is already broken. I have wasted entire afternoons on prompts that were fine while the credentials were quietly stale, and I would like you to skip that afternoon.

When the smoke patch never lands, the debugging order is fixed and short in my notes. First check that the endpoint answers a trivial request without touching the repo, then check that the repo is clean enough to accept a patch, then check the diff size. Ninety percent of the time the failure is in step one or two and the prompt was never the problem at all.

This is the workflow where MonkeyCode's free model access and free server option are genuinely relevant, and I want to be precise about what that means. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator describes the project as open source with a free tier that includes model access and a server option, and the free allowance has been quoted to me as ten million tokens; quotas move, so verify the current figure on the project's own page before you plan around it. What I actually used it for is unglamorous and that is the point: I ran the timed loop above against a hosted workspace so the install and dependency buckets were not my laptop's problem. Because the source is public, you can read what the server does with your prompt before you send anything you would not paste into a ticket.

Who should not use this approach? Anyone who needs a contractual SLA, anyone whose cold start is dominated by a proprietary build cache the free tier cannot see, and anyone working in a regulated environment where the answer to "where did the prompt go" must be a document rather than a repository. A free tier is a fine place to measure friction and a poor place to promise uptime, and confusing those two is how teams end up with a very confident incident report.

So before you benchmark another model, time your own first fifteen minutes and write the numbers into a file that other people can read. My guess is that your biggest bucket is not the one you have been blaming, and you will only find out if something is counting. If you want a place to run the stopwatch without provisioning anything, the free workspace is a reasonable first target — just bring the timer with you.

The First Fifteen Minutes: One Preflight, One Fix

Quinn Wang — Mon, 19 Oct 2026 08:30:32 +0000

The thing that decides whether a new AI coding setup survives contact with a real repo is almost never the model — it is whether the first fifteen minutes end in something you can verify. I have been tearing down first-run experiences for a while now, and the pattern keeps repeating: people lose the quarter hour to a handful of small uncertainties, then blame the tool for being slow. So instead of reviewing features, let me show you the stopwatch I use, the friction log it produces, and the single fix that actually moved the needle for me.

The premise is boring on purpose. You cannot improve a setup you have not timed, and most of us never time anything; we just remember that it "felt slow" and carry that feeling into the next tool we try. A clock turns a vague feeling into a row in a file, and a row in a file turns into an argument you can act on. Isn't that a better basis for a decision than vibes?

Clock every step before you judge anything

I start by sourcing a tiny timing helper into the shell session, so every step I take gets a timestamp without me thinking about it. The script is deliberately dumb: it records elapsed seconds and a note, and it never tries to be clever about what a "step" is. You decide that, and you decide it before you start, which is the whole point.

#!/usr/bin/env bash
# clock.sh — source me, then call mark after every step
set -uo pipefail

LOG="${CLOCK_LOG:-friction.tsv}"
[ -f "$LOG" ] || printf 'step\tseconds\tnote\n' > "$LOG"
CLOCK_T0=$(date +%s)

mark() {
  local now; now=$(date +%s)
  printf '%s\t%s\t%s\n' "$1" "$((now - CLOCK_T0))" "${2:-}" >> "$LOG"
  printf '[%3ss] %s %s\n' "$((now - CLOCK_T0))" "$1" "${2:-}"
}

Then a first run looks like this, with the setup command replaced by whatever the project's README currently tells you to run — I am not going to paste an install line I cannot verify against today's docs.

source ./clock.sh
mark "account"     "signed in, key copied to clipboard"
mark "install"     "ran the documented setup command"
mark "server"      "free server option selected"
mark "first-prompt" "opened editor, sent a trivial question"
mark "first-diff"  "got a change I could actually apply"
column -t -s $'\t' "$LOG"

The last row is the only one I really care about, because everything before it is preparation and everything after it is work. If first-diff lands at two minutes or at nineteen, that number describes the tool's design more honestly than any feature list. What would your own log say about the last three tools you tried?

Here is the shape of my log from a recent run through an AI coding setup that offers free model access plus a free server option. These rows are illustrative of the format, not measurements from a controlled benchmark — rerun the clock yourself before you quote anything.

step          seconds  note
account       42       key copied, no docs needed
install       96       two commands, one PATH fix
server        18       free server option, no card prompt
config        151      env vars invented by me, not documented
first-prompt  63       worked, but model choice unclear
first-diff    644      mostly me re-reading setup notes

Look at the two biggest numbers and notice that neither of them is the model. Config and re-reading together account for more than half the wall clock, and both are pure friction: nothing was learned, nothing was produced, and no token was spent. That is the leak I keep finding in onboarding budgets, and it is cheap to plug.

The one fix that mattered

The fix was not a tutorial and it was not better documentation — it was a preflight script that refuses to let me start until the boring questions are already answered. Instead of discovering an unreachable endpoint inside my editor, I discover it in a two-second terminal command that prints a clear OK or FAIL per check. Failure moves to the place where failure is cheap.

I wrote the version below against a generic OpenAI-compatible shape, so treat the paths as placeholders to adjust against the project's current API reference rather than gospel. The structure is what matters: check reachability, check that your credential is accepted, and exit non-zero so a wrapper can stop you.

#!/usr/bin/env bash
# preflight.sh — proposed, adapt paths to the current API docs
set -euo pipefail

: "${MC_BASE_URL:?export MC_BASE_URL first}"
: "${MC_API_KEY:?use a shell env var, never a committed file}"

fail=0

code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$MC_BASE_URL/health" || true)
if [ "$code" = "200" ]; then echo "OK   health"; else echo "FAIL health: $code"; fail=1; fi

if curl -s --max-time 5 -H "Authorization: Bearer $MC_API_KEY" \
     "$MC_BASE_URL/v1/models" | jq -e '.data | length > 0' >/dev/null 2>&1; then
  echo "OK   credential accepted"
else
  echo "FAIL credential or endpoint moved"; fail=1
fi

exit "$fail"

Wire it into a make target so the gate is the path of least resistance, and so skipping it requires a deliberate keypress rather than an oversight. A gate you have to think about bypassing is a gate that holds.

preflight:
    @./preflight.sh || (echo "stop here: fix the failing line before opening the editor"; exit 1)

first-run: preflight
    @echo "you have 15 minutes; make them count"

Does this feel like overhead? It is eleven lines and roughly two seconds, and in exchange the expensive part of your session starts with a known-good connection instead of an unknown one. That trade is the whole article.

Where the free server option earns its place

I run the preflight against the free server option because a remote endpoint fails in ways that are visible from curl, while a local misconfiguration tends to fail inside an editor where the error message is a shrug. Free model access is genuinely useful during the first fifteen minutes, when you are sending small, disposable prompts to learn the interface rather than doing serious work. The caveat is that free capacity is exactly the kind of thing that changes without notice, so check the project's current page for today's limits instead of trusting a number someone quoted last month. Want the details straight from the source? The MonkeyCode project page is the only place worth trusting for current availability.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Your situation	Preflight against free server	Preflight locally	Skip preflight entirely
Evaluating an unfamiliar tool	Yes — fastest signal	No	No
Repo contains secrets or customer data	No	Yes	No
Reproducible CI check	Unreliable; no SLA	Yes	No
One-off throwaway script	Yes	Overkill	Acceptable
Latency-sensitive workflow	Measure first, then decide	Yes	No

Limits, and who should walk away

This workflow measures setup friction, and it says nothing useful about code quality, model reasoning, or cost per task — do not let a clean preflight talk you into trusting output you have not reviewed. Free tiers change, endpoints move, and a health check that passed at nine in the morning proves nothing at five in the afternoon, so the script is a gate, not a guarantee. If you handle regulated data, need an SLA, or cannot tolerate a third-party endpoint seeing your prompts, this whole approach is the wrong shape for you and a local-only setup is the honest answer.

Who should try it? Anyone who has ever said "this tool feels slow" without a number behind the claim, and anyone onboarding a teammate who will ask the same five questions next Monday. Run the clock once, keep the log in the repo next to the Makefile, and let the friction show itself. Fifteen minutes of measurement buys you a much better argument than fifteen minutes of opinion — and honestly, what else were you going to do with that quarter hour?

Teardown: The First Fifteen Minutes, Minus One Step

Quinn Wang — Sun, 18 Oct 2026 07:11:02 +0000

The fix that mattered most in my last onboarding teardown was not a better doc, a faster model, or a smarter plugin — it was deleting a step. I keep relearning this, and I keep being surprised by how much of the first fifteen minutes evaporates once you remove the one gate that everyone hits before they can even ask a question. So this is not a review of a tool; it is the ledger I use to find that gate, and one concrete result from running it against a free-tier setup.

Half the posts I scrolled past this week were some version of "AI fatigue", and honestly, a lot of that fatigue is setup fatigue wearing a costume. You read a launch post, you carve out twenty minutes, and then you spend eighteen of them picking a provider, finding a key, and discovering your laptop's GPU situation. Isn't that the real tax? Not the inference bill — the pre-inference ceremony.

Instrument before you optimize

You cannot shorten a wait you never measured, so the first artifact is a ledger, not a benchmark. I stamp each step into a CSV as it happens, then read it back once the first accepted edit lands; the numbers are wall clock, not impressions. Run it in the same shell session where you are actually doing the setup, so the timestamps reflect the real pauses.

#!/usr/bin/env bash
# first15.sh — stamp each onboarding step, then read the ledger back.
set -euo pipefail
LEDGER="${LEDGER:-first15.csv}"

stamp() {
  printf '%s,%s,%s\n' "$(date -u +%FT%TZ)" "$1" "${2:-}" >>"$LEDGER"
}

case "${1:-}" in
  start)  : >"$LEDGER"; stamp "clock-start" "${2:-}" ;;
  mark)   stamp "$2" "${3:-}" ;;
  report) python3 - "$LEDGER" <<'PY'
import csv, sys
from datetime import datetime

rows = list(csv.DictReader(open(sys.argv[1])))
if len(rows) < 2:
    sys.exit("not enough stamps to report")

parse = lambda ts: datetime.fromisoformat(ts.replace("Z", "+00:00"))
start = parse(rows[0]["ts"])
prev = start
print(f'{"step":<26}{"delta_s":>9}{"total_s":>9}  note')
for r in rows[1:]:
    t = parse(r["ts"])
    print(f'{r["step"]:<26}{(t-prev).total_seconds():>9.1f}'
          f'{(t-start).total_seconds():>9.1f}  {r["note"]}')
    prev = t
print(f'\ntotal: {(prev-start).total_seconds():.1f}s across {len(rows)-1} transitions')
PY
    ;;
  *) echo "usage: $0 start|mark|report [step] [note]" >&2; exit 2 ;;
esac

A typical session looks like ./first15.sh start "free-tier trial", then a mark for each gate you pass: account, key, endpoint, first reply, first file changed. Here is the shape of the output I care about — schematic, not a measurement of your machine or anyone else's:

step                        delta_s  total_s  note
account-and-key                63.0     63.0  email verify included
endpoint-reachable              4.0     67.0  smoke request
first-reply                    19.0     86.0  one-line prompt
first-accepted-edit           241.0    327.0  wrong file, then right file

Look at where the minutes actually go. In my runs the account-and-key step is roughly a minute and the first reply is seconds, but the stretch between "it answered" and "it changed something I kept" is where four out of five minutes disappear — and that gap is a comprehension problem, not a latency problem.

The gate nobody logs

When I wrote the ledger down honestly, the biggest stall had a boring name: choosing what to ask first. People install the thing, get a cheerful reply, then freeze, because the blank prompt is a decision and decisions are slow. The fix was not a prompt library and it was definitely not a longer quickstart; it was constraining step four to a single named file with a single named change, so the first request has an obvious right answer.

The second gate was infrastructure — not speed, just existence. Every "do you have a GPU, a card, a quota?" question adds a branch to the first fifteen minutes, and branches are where people leave. That is where a free server option does real work in a teardown like this: it removes a branch rather than shortening one. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The project is open source and, per its own materials at the time of writing, advertises free model access plus a free server option and a free token allowance on the order of ten million tokens; I would re-check that allowance on the project page before you plan around it, because published quotas move.

What I will not tell you is how fast it is, which models sit behind it, or how it compares on a benchmark — I did not measure any of that here, and a number I invented would be worse than no number. What I can say is what the ledger says: with the hardware question removed, my schematic run loses its second-longest stall, and the remaining time goes into the only step that teaches you anything.

A smoke test before you commit twenty minutes

The cheapest habit I have is a thirty-second reachability check before installing anything. Substitute the base URL and model id from your own account page — the path below is illustrative, and I have not run this exact request against the current API, so treat it as a template rather than documentation:

BASE_URL="https://<endpoint-from-your-dashboard>"
curl -sS -o /tmp/first.json \
  -w 'http=%{http_code} total=%{time_total}s\n' \
  -H "Authorization: Bearer $MONKEYCODE_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"model":"<model-id>","messages":[{"role":"user","content":"reply with the word ready"}]}' \
  "$BASE_URL/v1/chat/completions"

If that prints a 200 and the word ready, the next fifteen minutes belong to your problem instead of your plumbing. If it prints a 401, you found the gate in one command instead of nine, and that is a win even though nothing worked. Keep /tmp/first.json around; when something breaks later, the diff between a working reply and a broken one is usually one header.

Who should walk away

Your situation	Verdict
Solo exploration, throwaway repo, no card	Worth the fifteen minutes
Regulated code, audit trail, SSO requirements	Check the terms first, probably not
You need pinned model versions for reproducibility	Not without a fallback path
Your team already has an approved provider	Adding a second one is a cost, not a feature
You want a benchmark winner	This article will not give you one

That last row matters. Free access and a free server are availability claims, not quality claims, and a teardown that measures onboarding friction says nothing about whether the output is any good on your codebase. If your code cannot leave your network, no amount of free is free.

If you keep any kind of onboarding ledger for your own projects, run it once on the tool you already pay for before you add another one. You might find that the step you were about to document is the step you should have deleted — and isn't that a cheaper fix than writing the doc?

Onboarding Budgets Leak Before the First Commit

Quinn Wang — Fri, 16 Oct 2026 05:13:04 +0000

The fifteen minutes you budget for a new AI coding setup rarely die from a missing feature, and they almost never die from a slow model. They die from three unnamed waits: a key you hold but have nowhere to put, a command that technically succeeds while producing nothing you can verify, and the absence of any rule telling you when to stop. I have watched those three waits eat entire afternoons, and I stopped trusting my memory about them a long time ago.

So this is not another review of what a tool can do. It is a measurement instrument you can run in your own terminal, plus the one fix that actually moved the needle for me. Call it a friction ledger, and yes, it is less exciting than a benchmark table, which is exactly why it works.

Name the three leaks before you time anything

Placement friction is the cost of getting a credential, an endpoint, and a model identifier into the same place at the same time. Verification friction is the cost of turning a successful HTTP response into something a human can inspect and replay. Recovery friction is everything you pay after a mistake, including the four minutes you spend wondering whether the mistake was yours or the tool's.

None of those show up in a "time to first token" chart, because a token is not a diff and a 200 is not evidence. What do you actually have after the happy path returns? If the answer is "a feeling," you have measured nothing, and the next person on your team will pay the same tax you just paid.

The ledger itself: forty lines of bash

A friction ledger records one row per step, with a monotonic-ish millisecond timestamp at the start and the end of that step. The point is not precision; the point is capturing the shape of the wait while you are still annoyed by it. Save this as friction.sh, then chmod +x friction.sh.

#!/usr/bin/env bash
set -euo pipefail

LEDGER="${LEDGER:-./friction.csv}"
STATE="${STATE:-./.friction.state}"

now_ms() { date +%s%3N; }

init() {
  [ -f "$LEDGER" ] || printf 'step,start_ms,end_ms,elapsed_ms,outcome,note\n' >"$LEDGER"
}

start() {
  init
  local step="${1:?usage: friction.sh start <step>}"
  printf '%s %s\n' "$step" "$(now_ms)" >"$STATE"
  echo "started: $step"
}

end() {
  local outcome="${1:-ok}" note="${2:-}"
  local started_step started_at
  read -r started_step started_at <"$STATE"
  printf '%s,%s,%s,%s,%s,"%s"\n' \
    "$started_step" "$started_at" "$(now_ms)" \
    "$(( $(now_ms) - started_at ))" "$outcome" "$note" >>"$LEDGER"
  echo "$started_step: $(( $(now_ms) - started_at ))ms ($outcome)"
}

summary() {
  awk -F, 'NR>1 {t+=$4; n++} END {printf "%d steps, %d ms total, %.0f ms mean\n", n, t, t/n}' "$LEDGER"
}

"$@"

Usage is deliberately boring, because a tool you have to think about is itself friction:

./friction.sh start credential-placement
# ... paste the key, wire the endpoint, pick the model ...
./friction.sh end ok "key in env file, not shell history"

./friction.sh start first-verifiable-output
./friction.sh end blocked "response arrived, no artifact on disk"

./friction.sh summary

One honest caveat about the instrument: it measures your environment and your habits, not the provider's engineering. A slow step might be your proxy, your laptop, or a corporate VPN doing what corporate VPNs do, and the ledger will happily record that as the product's fault. Keep the note column populated and you will at least remember which one it was.

Where a free tier fits into this, without the fantasy math

Free access changes the calculation because the cost of a wrong turn drops to nearly zero, which is precisely when people stop being careful. I have been using MonkeyCode, an open-source project whose operator describes it as offering free model access together with a free server option, and a free allowance he puts at ten million tokens. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Because that arrangement is described to me rather than audited by me, I treat it the way I treat any free tier: useful for measuring, dangerous for assuming. Verify the current terms on the project page before you plan a sprint around them, since free allowances move and nobody owes you a grandfather clause.

What the free server option is genuinely good for is the boring middle of the ledger. You want a place to run the first-verifiable-output step that is not your work laptop with three expired tokens in a config directory. What it is not good for is proving that your production topology will behave the same way, because it will not, and pretending otherwise is how teams ship surprises.

The one fix that mattered

Here is the change that cut my own ledger the most, and it had nothing to do with models. I collapsed three separate touchpoints — key, base URL, and model identifier — into one sourced file, so that there was exactly one place where a stale value could hide. Before that, every step in the ledger was quietly paying a config-hunting tax I had been blaming on the network.

# ~/.config/ai/env.sh — sourced, never copy-pasted into a shell history
: "${AI_KEY:?set AI_KEY before sourcing this file}"
: "${AI_MODEL:?set AI_MODEL before sourcing this file}"
export AI_BASE_URL="${AI_BASE_URL:-https://your-endpoint-here}"
export AI_KEY AI_MODEL

Then a preflight that fails loudly and early, before the fifteen-minute clock starts rather than nine minutes into it:

preflight() {
  local start elapsed
  start=$(date +%s%3N)
  for v in AI_BASE_URL AI_KEY AI_MODEL; do
    [ -n "${!v:-}" ] || { echo "missing: $v"; return 1; }
  done
  curl -sS -o /dev/null -w 'http %{http_code}\n' \
    -H "Authorization: Bearer $AI_KEY" "$AI_BASE_URL/models" || return 1
  elapsed=$(( $(date +%s%3N) - start ))
  echo "preflight ok in ${elapsed}ms"
}

Pair it with a step budget, and the ledger stops being a diary and becomes a decision. I use two thresholds: placement must finish inside one minute, and first verifiable output must finish inside five. If either blows past its budget twice in a row on the same step, I stop debugging and change the approach instead of the parameter.

Ledger observation	Read it as	Action
Placement under 60s, first artifact under 5 min	The seam is clean	Keep going, record the winning sequence
Same step over budget twice	Not a typo, a design gap	Switch approach or switch tool
`blocked` outcome with `no artifact on disk`	Verification friction	Write the expected file path down before the call
Fast `ok` rows, unreadable later	Theater	Add the `note` column or stop measuring

Limitations, and who should skip this entirely

The numbers in that table are placeholders from my own template and not measurements of any specific product, so please do not quote them as benchmarks. A CSV kept by one developer also hides the failures that matter at scale, like the teammate who never tells you they were blocked for three days. And if your code cannot leave your network for compliance reasons, no free server option is a relevant input, no matter how generous the allowance looks.

Who should not use this? Teams that need contractual guarantees, anyone unwilling to re-run the ledger after an environment change, and people who want a benchmark score to paste into a slide. A single measurement run is theater; the ledger earns its keep when it is boring and repeated.

If you want a cheap place to try the whole loop, the MonkeyCode project is open source and its free model access plus free server option is a reasonable sandbox for the first two ledger steps. Bring a stopwatch, trust your own rows over anyone's summary, and tell me which step ate your fifteen minutes — I suspect it was never the model.

# the whole article in two lines
./friction.sh start first-verifiable-output && ./friction.sh end ok "artifact on disk, path recorded"
./friction.sh summary

Time to First Verifiable Diff

Quinn Wang — Thu, 15 Oct 2026 11:23:50 +0000

Time to First Verifiable Diff

The onboarding number I actually trust is not how long the install takes, but how long it takes before a tool hands me a diff I can verify. Total install time tells you that something went wrong somewhere in the chain; it never tells you which link to cut, and that gap is why so many evaluations end in vibes. I keep running into conversations about AI fatigue, and I think a large share of it is not model quality at all, but onboarding friction that nobody bothered to localize. So I built a small instrument that localizes it, and the number it produces changed how I trial tools.

Earlier I wrote about clocking the first fifteen minutes, and I still believe the clock is worth holding. The problem is that a duration without a per-step ledger is a verdict, not a diagnosis. If the whole run took eleven minutes, do I fix the signup, the runtime, the docs, or my own prompt? You cannot answer that from a single stopwatch reading, and guessing wrong is how people conclude a tool is slow when it was actually their network.

Record the steps, then rank them

The harness below is a template, not a product wrapper, and I am not going to pretend I measured anything for you here. Every number it prints comes from your own first run, on your own machine, against your own network, which is the only measurement that transfers. It writes one JSON line per phase transition, so the ledger is append-only and replayable after the fact. Here is the recorder, with placeholder commands where the vendor-specific work would go.

#!/usr/bin/env bash
# step-ledger.sh — illustrative harness, not tied to any vendor CLI.
set -euo pipefail
LEDGER="${LEDGER:-./onboarding.jsonl}"
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)"

stamp() { # stamp <step> <phase> [note]
  printf '{"run":"%s","step":"%s","phase":"%s","ts":"%s","note":"%s"}\n' \
    "$RUN_ID" "$1" "$2" "$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)" "${3:-}" >> "$LEDGER"
}
begin() { stamp "$1" begin "${2:-}"; }
end()   { stamp "$1" end   "${2:-}"; }

begin signup  "no card, real email"
# ... whatever the tool asks for ...
end   signup

begin install "docs command, copy-pasted verbatim"
# ... paste the installer line from the docs ...
end   install

begin firsttask "ask for a one-line fix, nothing else"
# ... send the request and wait for output ...
end   firsttask

The rules matter more than the code. Copy the documented command verbatim, because paraphrasing from memory hides the moment the docs failed. Tag each step with a short note about what happened, since the note is what turns a bar on a chart into an actionable complaint. Never edit the ledger by hand, because a hand-edited measurement is a story, and stories are exactly what this exercise exists to replace.

Turn the log into a ranked complaint

A raw log is still just a log, so the second half of the instrument ranks the steps by cost and prints a total. Sorting descending is deliberate: the top line is the fix you should try first, and everything below it is noise until that one is addressed. The printer is short enough to read in one pass, which matters because you will want to trust it.

#!/usr/bin/env python3
"""ledger.py — turn onboarding.jsonl into a ranked friction ledger."""
import json, sys
from collections import defaultdict
from datetime import datetime

def ts(s): return datetime.strptime(s, "%Y-%m-%dT%H:%M:%S.%fZ")

rows = [json.loads(l) for l in open(sys.argv[1]) if l.strip()]
runs = defaultdict(dict)
for r in rows:
    runs[r["run"]].setdefault(r["step"], {})[r["phase"]] = (ts(r["ts"]), r["note"])

run = sys.argv[2] if len(sys.argv) > 2 else next(iter(runs))
total, ranked = 0.0, []
for step, phases in runs[run].items():
    if "begin" in phases and "end" in phases:
        d = (phases["end"][0] - phases["begin"][0]).total_seconds()
        ranked.append((d, step, phases["begin"][1]))
        total += d

for d, step, note in sorted(ranked, reverse=True):
    print(f"{d:7.1f}s  {step:<12} {note}")
print(f"{total:7.1f}s  TOTAL")

Run it and you get a shape like signup 3.9s, install 214.0s, firsttask 41.2s, and those figures are illustrative of the format rather than a claim about any tool. The interesting part is how often the largest line is not the model, not the signup, but the local runtime install. It is also the step people skip when they retry, which is why they conclude the second attempt was faster when the machine was simply warm.

The one fix that mattered

Here is the change that moved the number more than any other, and it has nothing to do with which model answered. Replace the first task with a task that must end in a verifiable diff, using a two-file fixture you already know the correct answer to. A chat reply is unfalsifiable in the first fifteen minutes; a diff against a failing test is not. So I start every trial like this.

mkdir -p fixture && cd fixture
printf 'def add(a, b):\n    return a - b\n' > calc.py
printf 'from calc import add\nassert add(2, 3) == 5\n' > test_calc.py
python -m pytest -q   # fails: this failure is your baseline

Now the first prompt is boring on purpose: fix the failing assertion and return a patch, not an explanation. You apply the patch, you rerun pytest, and the run either passed or it did not, which means the onboarding measurement ends with a boolean instead of an impression. I label this metric time to first verifiable diff, and it collapses a dozen vague first-run complaints into one number you can compare across tools without arguing about style. Should you trust a tool that needs forty minutes to reach a green test more than one that needs four, when the second one also answers every unrelated question beautifully?

Where a zero-cost tier changes the ledger

Two of the steps in that ledger are pure overhead, and neither of them teaches you anything about the tool. One is billing setup, and the other is provisioning a machine before you can see whether the edit loop even works for you. MonkeyCode, which I encountered as an open-source coding agent project, addresses both by being reachable without a payment step and by offering a free server option, so the first pass of the ledger can run without either of those entries. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The free model access is the part that keeps an evaluation cheap enough to abandon, which honestly is the property I care about most.

I am not going to quote a token allowance, a model list, or a server specification here, because I cannot verify those from where I sit and free tiers change quietly. The project's own pages are the only honest source for current limits and terms, so read them before you build anything that depends on them. Treat the free path as a way to get a first data point, never as the foundation of a pipeline whose reproducibility you actually need. A ledger you can rerun tomorrow is worth more than a discount you cannot predict.

Who should skip this approach

If your code cannot leave your network, the free-server path is irrelevant and the harness only helps you measure friction you were never going to pay. If your team needs SSO, audit logs, and deterministic model pinning, optimizing first-run minutes is optimizing the wrong axis, and the ledger will just document the wrong constraint. And if you already have a working loop you trust, the instrument is unnecessary, because you are no longer onboarding and there is nothing here to localize.

For everyone else, the transferable artifact is about sixty lines of shell and Python, and it survives whichever tool you abandon next quarter. If a zero-cost first pass makes that instrument cheap to run, start there, keep your own copy of the numbers, and let the top line of your ledger decide what you fix tomorrow.

Clock the First Fifteen Minutes

Quinn Wang — Sun, 11 Oct 2026 21:30:56 +0000

The first fifteen minutes of an AI coding session are the product test, not a warm-up you can skip. If you cannot name the friction in that window, you should not trust the diff that follows it. I treat that opening as a drill, because chatter is an easy way to lose an afternoon without a diff. Have you ever closed a setup feeling productive, only to find that nothing reviewable landed in the tree?

Models keep getting louder in public, while the first edit on a real repository stays oddly quiet. I would run those minutes like a short drill, with a clock I own and a budget set before any prompt. A model can sound clever and still burn the window on a wrong directory or a silent authentication hop. The one fix I would bet on is not a smarter prompt, and it is not a longer context window either.

It is a friction ledger that refuses the first real edit until four cheap checks each have a timestamp. Think of that opening quarter hour as a kitchen in the tense minutes just before service begins. You can hire a famous chef and still miss the plate if the oven is cold and the ticket is blank. The coding assistant is the chef in this picture, and the oven is the working tree you meant to change.

The ticket is the task you can replay later, and the clock is the only judge that does not flatter you. I split the drill into four beats, and I give each beat a budget before I type a single prompt. Reach means I can talk to a model without guessing which door actually opened underneath me. Place means the process cwd is the repository I intend to change, not a parent folder I opened by habit.

Read means git status is clean enough that a later diff belongs to this session and not to yesterday. Touch means a throwaway branch can be created and deleted, which puts git state back where it started. If any beat blows the budget I chose, I stop and write down why before I try the next door. Have you ever restarted a tool three times and still been unable to say which minute failed?

An unlabeled restart just moves the same fog forward, which is how a short setup becomes an afternoon. The script below is a proposal I have not executed against any vendor dashboard, so the numbers are your budgets. It writes a ledger outside the work tree, then checks place, read, and a reach note you measured by hand. Only after those beats pass does it create and delete a scratch branch, so touch is proof rather than a guess.

#!/usr/bin/env node
// Unexecuted proposal: time the first fifteen minutes. Not a vendor benchmark.
// node dx-drill.mjs --reach-ms 8000 --reach-note "plain reply, no file yet"
import { execFileSync } from "node:child_process";
import { appendFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const args = new Map();
for (let i = 2; i < process.argv.length; i += 2) {
  args.set(process.argv[i], process.argv[i + 1]);
}

const budgetMs = {
  place: Number(process.env.BUDGET_PLACE_MS || 30000),
  read: Number(process.env.BUDGET_READ_MS || 30000),
  reach: Number(process.env.BUDGET_REACH_MS || 120000),
  touch: Number(process.env.BUDGET_TOUCH_MS || 180000),
};

const ledgerPath = process.env.FRICTION_LEDGER || join(tmpdir(), "friction-ledger.jsonl");
const started = Date.now();

function stamp(step, ok, detail, measuredMs) {
  const wallMs = Date.now() - started;
  const elapsedMs = measuredMs ?? wallMs;
  const budget = budgetMs[step] ?? null;
  const row = {
    step,
    ok,
    elapsedMs,
    wallMs,
    budgetMs: budget,
    overBudget: budget != null && elapsedMs > budget,
    detail,
    at: new Date().toISOString(),
  };
  appendFileSync(ledgerPath, JSON.stringify(row) + "\n");
  if (!ok || row.overBudget) {
    console.error("stop:", step, JSON.stringify(row));
    process.exit(2);
  }
  console.log("pass:", step, elapsedMs + "ms");
}

function git(gitArgs) {
  return execFileSync("git", gitArgs, { encoding: "utf8" }).trim();
}

const cwd = process.cwd();
const top = git(["rev-parse", "--show-toplevel"]);
stamp("place", cwd === top, { cwd, top });

const status = git(["status", "--porcelain"]);
stamp("read", status.length === 0, { status: status || "clean" });

const reachMs = Number(args.get("--reach-ms"));
const reachNote = args.get("--reach-note") || "";
stamp(
  "reach",
  Number.isFinite(reachMs) && reachMs >= 0 && reachNote.length > 8,
  { reachNote },
  reachMs
);

const branch = "dx-drill-scratch";
let created = false;
try {
  git(["switch", "-c", branch]);
  created = git(["branch", "--show-current"]) === branch;
} finally {
  if (created) {
    git(["switch", "-"]);
    git(["branch", "-D", branch]);
  }
}
stamp("touch", created, { branch, restored: created });
console.log("ledger", ledgerPath);

Save that file as dx-drill.mjs at the repository root, and run it only after you have timed a plain reply. Pass your own latency and a short confession in --reach-ms and --reach-note after that plain reply. If you launch the file from a parent folder, place should fail before any scratch branch is created. I would read the stop line, then open the ledger path the script prints, instead of guessing from memory.

The reach flag is a confession, not a probe, and that is why the script refuses a note that is too short. A green HTTP status can still mean you reached a model you did not choose, or a queue that will miss your window. I want the note to say what I asked, how long the reply took, and whether any file or branch changed. Have you watched a fluent answer land in the wrong tree and then blamed the weights for a path mistake?

The operator asked me to time this drill against MonkeyCode's free model access and its free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator also describes the project as open source, which you should confirm on the project page itself. I do not have a measured quota, a hardware sheet, or a permanence promise here, so I will not invent figures.

I would not start that session by asking for a feature, a migration, or a clever refactor of a large file. I would start the ledger, confirm which door I opened, and only then ask for the same scratch branch and nothing else. If the free server path spends most of the fifteen minutes on provisioning, that is a useful result rather than a model failure. If the free model path answers quickly but never changes git state, the ledger keeps that failure apart from the server story.

The same drill still helps if you swap the product name for any other assistant you already have installed. That portability is deliberate, because a first-fifteen-minute test that only flatters one brand is not a test. I also will not claim that this setup is faster, cheaper, or more accurate than tools I have not measured side by side. Have you noticed how a smooth landing page can hide a slow first edit, and how a plain ledger makes that swap visible?

I would not use this approach if you need a compliance sign-off, a published benchmark, or a promise about free-tier duration. The script does not prove quality, safety, or cost, and the local budgets mostly catch a hung git. Teams without local git, a current Node, or git switch should skip it, because the drill assumes a repository you control. If your host forbids new branches, pick another reversible touch, and do not let the assistant choose that touch.

If a previous scratch branch is still around, touch will fail, and that failure is the drill doing its job. Point FRICTION_LEDGER outside the repository, delete the leftover branch, and rerun git status --porcelain until it is empty. Then time the two doors separately, once for free model access and once for the free server option, without averaging them. A blended score is how the first fifteen minutes become a story instead of a record you can argue with later.

If you want a next step, run the drill once on the free model door and the free server door you already have. Keep the ledger, then decide from your own timestamps whether those first fifteen minutes earned a second session. I would rather read a messy ledger than hear that a demo felt smooth, because smoothness is not a diff. The clock will not make the model wiser, but it will stop you from paying an afternoon for a setup you never named.

Echo the Marker Before You Edit

Quinn Wang — Sat, 10 Oct 2026 17:54:29 +0000

I do not trust an assistant in the first fifteen minutes until it can echo a marker I just wrote into the tree. A lively chat only proves that tokens can travel, which is a different question from whether this workspace is the one under discussion. If the marker never comes back, I stop the session and fix visibility before I ask for a single change. Would you keep driving if the mirror showed a street you do not recognize at all?

The first quarter hour usually fails in a quiet way, not with a dramatic crash you can screenshot for a teammate. You authenticate, pick a model, watch a spinner settle, and then paste a paragraph about a refactor you have been avoiding. The reply sounds confident and names a few files, yet it still misses the function that actually hurts. That miss usually means the tool is staring at a sample repo, a parent directory, or yesterday's checkout instead of this one.

I treat that miss as a visibility failure, not as a prompt that needs one more adjective and a second try. Another attempt only spends the session on a conversation that cannot see the code you actually care about. The one fix I keep is smaller than a new prompt template and ruder than most setup guides admit. Would you hire a contractor to remodel a kitchen they have not been shown how to enter?

The fix is a marker probe that runs before the first real request and refuses to continue when the echo is wrong or missing. I drop a tiny file into the working tree and fill it with a random token that training data could not have memorized. Then I ask the assistant to read that one file and repeat the token, with no advice and no edits attached. If the token comes back intact, I know this session can see this tree, and only then do I allow a change.

Think of the marker as a coat check ticket rather than a unit test for the product you are building. The attendant does not need to understand your coat, and the assistant does not need your architecture either. The only job is to hand the same ticket back, and a wrong ticket means you are standing at the wrong counter. Why would I let a stranger hem the sleeves before they can read the number printed on the stub?

The script below is a local proposal you can run, and I am not reporting a benchmark, a quota, or a lab result. It refuses to start outside a git work tree, writes a short random token, and prints a prompt that forbids edits. I try to keep the probe directory out of history when the ignore file is writable, so a passed check does not become junk. If your policy forbids even a scratch file, skip the script and do not weaken that rule just to watch a demo.

#!/usr/bin/env bash
# visibility-probe.sh — local proposal, not a measured benchmark.
set -euo pipefail

root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
if [[ -z "${root}" ]]; then
  echo "FAIL: not inside a git work tree"
  exit 2
fi

cd "${root}"
probe="${root}/.visibility-probe"
mkdir -p "${probe}"

if command -v openssl >/dev/null 2>&1; then
  token="$(openssl rand -hex 8)"
else
  token="$(od -An -N8 -tx1 /dev/urandom | tr -d ' \n')"
fi

printf '%s\n' "${token}" > "${probe}/MARKER"

if [[ -w "${root}/.gitignore" || ! -e "${root}/.gitignore" ]]; then
  if ! grep -qxF '.visibility-probe/' "${root}/.gitignore" 2>/dev/null; then
    printf '%s\n' '.visibility-probe/' >> "${root}/.gitignore"
  fi
fi

echo "cwd=${root}"
echo "marker_file=${probe}/MARKER"
echo "expected_token=${token}"
echo "Accept no edit until the echo check prints PASS."
cat <<'EOF'
Read only .visibility-probe/MARKER from the repository root.
Reply with the single token in that file and no other words.
Do not edit files. Do not explain the token. Do not propose a refactor.
EOF

After the assistant replies, I pipe that reply into a second command that compares it with the file on disk. A match is not a celebration, and a mismatch is not a mystery I solve by rephrasing the question in a longer voice. The checker strips whitespace so a trailing newline cannot fake a different workspace and push me to ignore later probes. What would you gain by negotiating with a reply that cannot repeat sixteen hex characters sitting in plain sight?

#!/usr/bin/env bash
# check-echo.sh — usage: pbpaste | ./check-echo.sh
set -euo pipefail

root="$(git rev-parse --show-toplevel)"
expected="$(tr -d '[:space:]' < "${root}/.visibility-probe/MARKER")"
got="$(tr -d '[:space:]')"

if [[ -n "${expected}" && "${got}" == "${expected}" ]]; then
  echo "PASS: marker echoed; this session can see this tree"
  exit 0
fi

echo "FAIL: expected [${expected}] but received [${got}]"
echo "Stop. Fix the folder mount before you request an edit."
exit 1

I run those two commands in order, and I read a FAIL line before I touch the original request again. On Linux I replace pbpaste with xclip reading the clipboard, because the probe should fit the machine I already trust. A PASS only means I may ask for one small change in a named file, and I still review the diff before I commit. Have you ever debugged a suggestion for ten minutes and then learned the tool was describing a sibling directory?

chmod +x visibility-probe.sh check-echo.sh
./visibility-probe.sh
# Copy the printed prompt into the assistant, then pipe only its reply.
pbpaste | ./check-echo.sh
# Linux alternative:
# xclip -selection clipboard -o | ./check-echo.sh

When the check fails, I do not open a second chat and hope, because luck is not a mounting strategy. I print the working directory, confirm the marker file still exists, and compare its contents with the string I thought I sent. Then I check whether the assistant was attached to a parent folder, a container path, or a sample that shares my project name. If those three glances still do not explain the miss, I stop rather than teaching myself that a blind session is normal.

When the echo should happen in a hosted room, I use MonkeyCode's free model access and its free server option for that single try. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I am leaning on those two availability facts only, not on names, allotments, hardware, or a promise that the offer stays forever. Run the probe there if that room is simplest, read PASS or FAIL yourself, and do not let the room decide what done means.

The probe has sharp edges, and I would rather name them than let a green PASS travel further than it deserves. An echoed token shows that this session can read that one file, not that every path is visible and not that writes will land. It will not catch a reply that repeats the marker and then invents an edit in a file it never opened. Anyone who needs a reviewed production change, an air-gapped process, or a ban on scratch files should skip this shortcut.

I also refuse to hide secrets in the marker, because a hosted model may log whatever string you ask it to repeat. Use random output from openssl or any other non-secret string, then delete the probe directory when the session ends. If the ignore append fails because the ignore file is read-only, remove the marker yourself before you commit anything. Does a fifteen-minute win still count if you spend the evening scrubbing a token out of the remote history?

If the echo passes, my next message stays boring on purpose: one named file, one failing command, and only the change that command needs. I do not ask for a tour or a redesign while the session is young, because the marker only bought specificity. You can delete the chat once the diff is saved or once the check fails, so those first minutes never turn into a diary. Is there a better use of a fresh session than proving it can see the file before it is allowed to touch one?

Write the Receipt Before the Chat

Quinn Wang — Fri, 09 Oct 2026 14:26:10 +0000

The one fix I trust for those first fifteen minutes is a local session receipt, written before any agent is allowed to speak. I kept treating the green ready badge as permission, and that habit is what burns the opening quarter hour. Would you let a contractor start painting before you wrote down which room they may enter? I would not, yet I keep opening coding agents with less paperwork than I give a house painter.

The friction showed up as a polite chat box, not as an error, which is why I trusted it for so long. The cursor blinked, the model picker looked alive, and I started describing the bug before I named the tree. Ten minutes later I had three suggestions and no record of the directory those suggestions were allowed to touch. Does a blinking cursor feel like progress to you, or does it feel like a waiter who never wrote the order down?

I used to spend that opening stretch negotiating with the tool about scope, as if conversation could replace a boundary. The agent would offer a patch for a file I had not opened, then ask whether I wanted a broader refactor. I would answer, because silence felt rude, and that answer became the only spec the session had. Have you noticed how a helpful coding tool turns your very first reply into an accidental contract?

The analogy that finally stuck was a coat check, not a dashboard, because dashboards flatter you. You do not get your coat back because the lobby looked elegant; you get it back because someone wrote a number. A coding session needs that same numbered stub before the conversation starts, or the lobby will eat the afternoon. I stopped asking which model felt smarter, and I started asking which stub I could still read after a crash.

What I write down first

The receipt is a small JSON file in the repo, created by a script I run before I open the agent at all. It records the working directory, the branch, the commit, the dirty paths, and the write roots I am willing to allow. It also records the execution surface I chose, because a local shell and a remote server are not the same room. If that file is missing or stale, the guard exits, and the chat never gets a chance to become my spec.

Free access is exactly where my first fifteen minutes get sloppy, because the price tag no longer slows my hand. I open the chat the way I open a sample, and I forget that a sample can still write into a real tree. A free server makes that mistake worse, since the files may land somewhere I cannot see from this laptop. Would you skip the coat check because the cloakroom was complimentary, or would you want the stub even more?

The guard I actually run

The script below is a proposal I have not executed against a live MonkeyCode server in this draft, so treat it as a sketch. I want the guard to be boring, local, and fail-closed, because a clever guard becomes another thing I have to debug at midnight. You can drop the file at the repo root, mark it executable, and run it before you touch the agent UI. If your team already has a workspace contract, keep that contract, and use this only as a personal preflight.

#!/usr/bin/env bash
# proposal: unexecuted preflight. Writes .session-receipt.json, then refuses a stale stub.
set -euo pipefail

root="$(git rev-parse --show-toplevel)"
cd "$root"

surface="${SESSION_SURFACE:-local}"          # local | free-server
write_roots="${SESSION_WRITE_ROOTS:-src,tests}"
max_age="${SESSION_RECEIPT_MAX_AGE:-900}"

if [[ "$surface" != "local" && "$surface" != "free-server" ]]; then
  echo "refusing: surface must be local or free-server" >&2
  exit 2
fi

export SESSION_ROOT="$root"
export SESSION_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
export SESSION_HEAD="$(git rev-parse HEAD)"
export SESSION_STATUS="$(git status --porcelain)"
export SESSION_SURFACE="$surface"
export SESSION_WRITE_ROOTS="$write_roots"
export SESSION_NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export SESSION_MAX_AGE="$max_age"

python3 - <<'PY'
import json, os
from pathlib import Path
root = Path(os.environ["SESSION_ROOT"])
roots = [p.strip() for p in os.environ["SESSION_WRITE_ROOTS"].split(",") if p.strip()]
if not roots:
    raise SystemExit("refusing: write_roots empty")
receipt = {
    "schema": "session-receipt/v1",
    "written_at": os.environ["SESSION_NOW"],
    "cwd": str(root),
    "branch": os.environ["SESSION_BRANCH"],
    "head": os.environ["SESSION_HEAD"],
    "porcelain": [ln for ln in os.environ["SESSION_STATUS"].splitlines() if ln],
    "surface": os.environ["SESSION_SURFACE"],
    "write_roots": roots,
    "max_age_seconds": int(os.environ["SESSION_MAX_AGE"]),
    "note": "records intent only; this file is not a sandbox",
}
path = root / ".session-receipt.json"
path.write_text(json.dumps(receipt, indent=2) + "\n", encoding="utf-8")
print(f"wrote {path}")
PY

python3 - <<'PY'
import json
from datetime import datetime, timezone
from pathlib import Path
path = Path(".session-receipt.json")
data = json.loads(path.read_text(encoding="utf-8"))
written = datetime.strptime(data["written_at"], "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
age = (datetime.now(timezone.utc) - written).total_seconds()
if age > data["max_age_seconds"]:
    raise SystemExit(f"refusing: receipt is {int(age)}s old")
print(
    "receipt ok surface=%s roots=%s head=%s"
    % (data["surface"], ",".join(data["write_roots"]), data["head"][:12])
)
PY

I run that script, read the porcelain list out loud, and only then do I allow myself to open the chat. If the status shows a file I did not expect, I stop, because I would have blamed that mess on the model. The free-server label does not prove the server is empty; it only forces me to admit I chose a room I cannot see. Is that a weak guarantee, and is a weak named guarantee still better than a strong feeling?

chmod +x ./session-receipt.sh
git checkout -b scratch/receipt-drill
SESSION_SURFACE=free-server SESSION_WRITE_ROOTS=src,tests ./session-receipt.sh
# I open the agent only after the guard prints "receipt ok".
grep -qxF '.session-receipt.json' .gitignore || printf '%s\n' '.session-receipt.json' >> .gitignore

How the fifteen minutes move

Here is how the first fifteen minutes used to go, and how the receipt changes the middle of that stretch. Minute one was connection theater, minute four was a vague prompt, and minute nine was a diff I could not narrate. With the guard, minute one is the script, and minute four is a prompt that quotes those write roots. By minute nine I still have a diff, but I can match it to a stub instead of reconstructing the chat from memory.

I do not pick the surface by vibe, and I do not pick it by whichever button is already highlighted in the UI. If the change is a typo I can see, I label the surface local and keep the write root narrow. If I want a disposable room, I label the surface free-server, and I still name the roots I expect back. If I cannot name a root, I do not have a task yet, so why open a free path on a foggy wish?

The prompt I paste is dull on purpose, because a colorful prompt is how I smuggle scope past my own guard. I write the branch, the head, the surface, and the roots in the first lines, then I describe the bug in one sentence. I ask the agent to refuse any path outside those roots, knowing full well a sentence is not a sandbox. Would you trust a promise inside a chat more than a file you can diff, or have you already been burned that way?

branch: scratch/receipt-drill
head: <paste from receipt>
surface: free-server
write_roots: src, tests
task: explain the null check in src/parse.js and propose a patch only inside those roots.
If a path falls outside write_roots, stop and say so. Do not create files I did not name.

After the agent answers, I do not accept anything until I rerun git status and compare it with the porcelain I stored. A new path outside the write roots means I stop, even if the patch looks clever, because clever and bounded are different compliments. I then append a one-line note to the receipt by hand, recording whether I applied, rejected, or abandoned the suggestion. That note is the whole retrospective, and it takes less time than rewriting the prompt because I felt impatient.

python3 - <<'PY'
import json
from pathlib import Path
data = json.loads(Path(".session-receipt.json").read_text(encoding="utf-8"))
Path(".session-receipt.porcelain").write_text(
    "\n".join(data["porcelain"]) + "\n",
    encoding="utf-8",
)
PY
git status --porcelain > .session-now.porcelain
diff -u .session-receipt.porcelain .session-now.porcelain || true

Where the stub lies to you

This approach fails when you treat the receipt as a cage, because the file cannot stop a remote process you do not control. Clock skew, a dirty submodule, or a file matched by gitignore can make the stub look cleaner than the tree you actually have. If you are in a live incident with a named owner, skip the ceremony and use the runbook you already trust. If the directory is empty and disposable, the receipt may cost more than the experiment, and you should not pretend otherwise.

I would also skip this if your platform already mints a signed workspace contract before the agent can start. Duplicating that contract in a side file creates two truths, and two truths are how the first fifteen minutes get confusing again. The receipt covers the gap where the UI says ready and your disk has not agreed yet. Does your current tool even let you see that gap, or does the ready badge cover it with a friendly color?

If a free model path and a free server are already available, run the guard on a throwaway branch first. I am not asking you to stay, and I am not claiming the receipt makes any vendor correct. I am asking whether your next fifteen minutes can start with a stub you could still read after the tab crashes. That question is the whole practice, and the model you pick is just the coat you handed over the counter.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Name the File Before You Accept

Quinn Wang — Thu, 08 Oct 2026 10:13:36 +0000

I stop trusting an AI coding session the moment I cannot name the file it would change. A fluent answer can still be a rumor until a patch, a path, and a dry run exist on disk. If those three things are missing, I am watching a polished demo rather than reviewing actual work. Would you merge a teammate's change if you could not point to it in git status?

The first fifteen minutes are where that confusion hides, because everything looks busy and almost nothing is inspectable. You open the tool, you paste a task, and a confident block of code arrives before your coffee cools. The spinner feels like progress, yet the working tree may still be exactly the tree you started with. Have you ever accepted a suggestion and then failed to find it with a simple status command?

That gap is the friction I care about, not the color of the onboarding screen and not the speed of the first reply. You can have a glowing editor, a scrolling chat, and a still-clean branch because the suggestion never left the transcript. A transcript is a conversation, while a patch is a claim you can refuse, replay, or hand to someone else. Which of those two artifacts would you rather defend when a reviewer asks for the change tomorrow morning?

So the one fix that mattered was boring, and that is why it survived contact with a real repository. I write the model's proposed change to a patch file before I let anything touch the working tree. Then I run a dry apply, record the repository fingerprint, and only then decide whether the suggestion deserves a human edit. Does that sound slower than clicking accept, or does it sound like the first moment the session becomes reviewable?

Here is a small Node script I would keep beside the repo while testing that habit. I am labeling it as a proposed local check, not as a benchmark and not as a result from a measured lab. It shells out to git, writes a receipt, and exits non-zero when the patch cannot be applied cleanly. You can drop the file in scripts/session-receipt.mjs and run it with Node eighteen or any newer release.

#!/usr/bin/env node
// Proposed local check. It does not call a model and it does not modify tracked files.
// Add .session-receipts to .gitignore so a path receipt never becomes a commit.
import { execFileSync } from "node:child_process";
import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
import { resolve } from "node:path";

const patchPath = resolve(process.argv[2] || "proposal.diff");
const outDir = resolve(".session-receipts");

if (!existsSync(patchPath)) {
  console.error(`missing patch: ${patchPath}`);
  process.exit(2);
}

function git(args) {
  try {
    return execFileSync("git", args, { encoding: "utf8" }).trim();
  } catch (error) {
    const detail = error.stderr ? error.stderr.toString() : error.message;
    console.error(detail);
    process.exit(2);
  }
}

mkdirSync(outDir, { recursive: true });

const head = git(["rev-parse", "HEAD"]);
const branch = git(["branch", "--show-current"]);
const status = git(["status", "--porcelain=v1"]);
const patch = readFileSync(patchPath, "utf8");

let apply = "clean";
try {
  execFileSync("git", ["apply", "--check", "--", patchPath], { stdio: "pipe" });
} catch (error) {
  const detail = error.stderr ? error.stderr.toString() : error.message;
  apply = `failed: ${detail.trim()}`;
}

const receipt = {
  recorded_at: new Date().toISOString(),
  head,
  branch,
  porcelain: status,
  patch_path: patchPath,
  patch_bytes: Buffer.byteLength(patch),
  apply_check: apply,
};

const stamp = receipt.recorded_at.replace(/[:.]/g, "-");
const receiptPath = resolve(outDir, `${stamp}.json`);
writeFileSync(receiptPath, JSON.stringify(receipt, null, 2));
console.log(receiptPath);
console.log(apply);
process.exit(apply === "clean" ? 0 : 1);

I would run it only after saving the suggestion as proposal.diff, because the script will not invent a diff. A typical first pass looks like the three commands below, and none of them require a network call. If the dry run fails, I still have the receipt, and the working tree remains untouched by the suggestion. Is that not a better failure than a half-applied edit you only notice after you come back from lunch?

test -s proposal.diff
node scripts/session-receipt.mjs proposal.diff
git apply --check -- proposal.diff && echo "hunks fit; behavior still unproven"

The commands only prove that a saved diff fits this tree, and they say nothing about whether the behavior is desirable. If the assistant printed a unified diff, I paste that diff into proposal.diff and I do not let the editor apply it for me. If it printed a whole file instead of a diff, I stop and ask for a unified diff against the current file. Why would I accept a rewrite I cannot compare line by line with the file already on disk?

This is where a disposable server becomes useful, and I want the relationship stated before the tool name does any work. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The brief I was given treats free model access and a free server option as available, without a verified quota or hardware spec. I would use MonkeyCode's free server as a scratch workspace, then bring home only a patch that git apply --check already accepted.

I am not treating those availability claims as a performance result, because a free seat does not prove the patch is correct. Read the current docs before you rely on any allowance, since token budgets and server lifetimes move and this article will not chase them. If the docs and the product disagree with a number you saw in a post, believe the docs you can open today. Would you rather cite a changelog you just read, or cite a paragraph that cannot age honestly?

The teardown of those first fifteen minutes usually fails in the same three places, even when the model sounds sharp. First the session cannot prove which commit it saw, so the suggestion argues with a tree you no longer have. Then the accept control sits closer than the diff, so your hand finishes a review your eyes have not started. Have you checked whether your last accepted edit left a path a colleague could open without asking you?

Finally the only surviving record often lives in a chat log that your teammate cannot clone, rerun, or dispute. The receipt script answers the identity failure and the missing-record failure, and it slows the careless click enough to matter. The head and branch fields tell you which snapshot the check ran against, while porcelain shows whether the tree was already dirty. A failed dry run is still a successful diagnosis, because you learned the suggestion does not match this particular tree.

I would not use this approach when the change involves a secret, a migration, or a release commit your policy says must be signed. A local receipt is not an approval system, and it will happily bless a valid patch that deletes the wrong table. Do not paste production credentials into a hosted session just because that server was free to start. If your team needs audit trails, locked runners, or a human gate before model output exists, this scratch workflow is the wrong shape.

There is another limit that shows up quickly, and it is smaller than policy and just as able to waste an afternoon. A clean apply check does not understand intent, tests, or the comment you meant to update three files away. Binary assets, renames, and already-dirty files can make a tidy chat diff fail for purely mechanical reasons. When that happens, can you shrink the task until the patch names one file you could read aloud?

If I were handing this ritual to my future self, I would keep it under five minutes and refuse to add dashboards. Save the diff, run the receipt, read the hunks, and only then decide whether the suggestion earns its own branch. Once the receipt exists, the chat can close, because the claim finally has a filename someone else can open. If you want a disposable desk for that check, read the current free-server docs and ignore any allowance this post refused to freeze.

Accept Nothing You Cannot Replay

Quinn Wang — Thu, 08 Oct 2026 07:43:27 +0000

The first fifteen minutes of an AI coding session fail when you accept a diff you cannot replay the next morning. I keep watching the same quiet collapse, and it is rarely the login wall, the model menu, or the speed of the first token. You paste a goal, three files change, and nobody can name the command that was red before the edit landed. Would you merge a teammate's patch if the only remaining witness was a chat transcript and a hopeful shrug?

That shrug is the friction that actually eats the quarter hour, long before any architecture debate earns the right to speak. A mechanic who swaps parts before reading the fault code sometimes gets lucky, then cannot explain the repair. An assistant that edits before a named check is that mechanic, with your repository as the workshop and the diff as the invoice. If the first fifteen minutes do not end with a frozen failure, what exactly did you purchase with that time?

I do not need those minutes for a settings tour, a green spinner, or praise about how a tool understood the codebase. I want a working directory, one check command, a non-zero exit, and a short tail of the output that made the failure obvious. I do not want a rewritten module or a new dependency until that red exit has a name I can type again. If the check cannot fail on purpose before the patch, what are we asking any model to fix?

The one fix that changed the session for me was a replay card, a small file written before any edit is allowed. It freezes the command, the directory, the git revision, a fingerprint of the dirty tree, and the exit code you just watched. Later, that card is the only context worth pasting, and the same command is the only verdict worth trusting. If the card cannot be rerun in a clean shell, the session was a conversation, not a repair you can defend.

The script below is a local workflow you can copy, not a score I am pretending to have measured on your laptop. It writes .replay/card.env when you pass capture, and it reruns the frozen command when you pass verify. Nothing in the file calls a model, which is deliberate, because the witness should not depend on the assistant that proposed the change. Read it before you trust it, and keep the card out of any commit that might carry secrets from the failing run.

#!/usr/bin/env bash
set -euo pipefail

# Local proposal: bash, optional git, and shasum. Not a measured product benchmark.
card_dir="${REPLAY_DIR:-.replay}"
card="$card_dir/card.env"
mkdir -p "$card_dir"

tree_fingerprint() {
  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
    printf '%s %s\n' \
      "$(git rev-parse HEAD)" \
      "$(git status --porcelain=v1 | shasum -a 256 | awk '{print $1}')"
  else
    find . -type f -not -path './.replay/*' -print0 \
      | sort -z | xargs -0 shasum -a 256 | shasum -a 256 | awk '{print $1}'
  fi
}

capture() {
  local cmd="$1" log exit_code
  log="$(mktemp)"
  set +e
  bash -lc "$cmd" >"$log" 2>&1
  exit_code=$?
  set -e
  {
    printf 'captured_at=%q\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
    printf 'workdir=%q\n' "$PWD"
    printf 'tree_fp=%q\n' "$(tree_fingerprint)"
    printf 'cmd=%q\n' "$cmd"
    printf 'exit_before=%q\n' "$exit_code"
  } >"$card"
  tail -n 40 "$log" >"$card_dir/stderr-before.txt"
  rm -f "$log"
  printf 'captured exit_before=%s into %s\n' "$exit_code" "$card"
  if [[ "$exit_code" -eq 0 ]]; then
    echo "warning: freeze a failing command before you ask for a patch" >&2
    exit 2
  fi
}

verify() {
  # shellcheck disable=SC1090
  source "$card"
  local log exit_code
  [[ -n "${cmd:-}" && -n "${exit_before:-}" ]] || {
    echo "card is incomplete" >&2
    exit 3
  }
  log="$(mktemp)"
  set +e
  bash -lc "$cmd" >"$log" 2>&1
  exit_code=$?
  set -e
  tail -n 40 "$log" >"$card_dir/stderr-after.txt"
  rm -f "$log"
  printf 'exit_before=%s exit_after=%s\n' "$exit_before" "$exit_code"
  if [[ "$exit_before" -eq 0 ]]; then
    echo "card was not a failing check" >&2
    exit 3
  fi
  if [[ "$exit_code" -ne 0 ]]; then
    echo "still red; do not treat the diff as the fix" >&2
    exit 1
  fi
  echo "same command flipped to zero"
}

case "${1:-}" in
  capture) capture "${2:?command required}" ;;
  verify) verify ;;
  *) echo "usage: replay-card.sh capture '<command>' | verify" >&2; exit 64 ;;
esac

A session that respects the card starts with a command you already believe should pass, then captures the moment it does not. I usually point it at one file-scoped check, because a full suite hides the failure inside a crowd of unrelated green lines. After the card exists, and only after exit_before is non-zero, I allow an edit of any kind. The verify step is intentionally dumb: same words, same shell, and a demand that the recorded red exit become zero.

chmod +x replay-card.sh
./replay-card.sh capture 'npm test -- src/parser.test.js'
# card must exist, and exit_before must be non-zero, before any edit
./replay-card.sh verify
git diff --stat

If verify is still red, the patch is only a hypothesis wearing a confident tone, and the chat does not get a vote. I treat that red line as the session still being inside its opening quarter hour, no matter how many files already changed. A green verify is permission to read the diff carefully, not permission to stop asking whether the check was weak.

Notice what the fingerprint is not allowed to do during the verdict, even though the card bothers to store it. A real fix must change the tree, so locking the porcelain hash would freeze the bug and call that stillness purity. I keep tree_fp as a breadcrumb for the morning after, the way a mechanic keeps the old fault code on a clipboard. The lock is the command string plus the exit flip, not the beauty of the diff and not the confidence of the chat.

This is where a free model session earns a narrow job, and where I should be plain about the relationship before going further. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I would paste the command and the stderr tail there, and I would ask only for a patch aimed at that card. I would run verify on the free server option only as a second shell, not as proof the laptop was wrong.

I am not stating a quota, a model name, a hardware shape, a duration, or a promise that either free option stays fixed. The second shell is a witness rather than a trophy, and it counts only if it can build what the check command needs. If that server lacks the toolchain, green is noise and red is a portability finding, not an insult aimed at the model. Would a passing run on an empty image prove anything except that you skipped the hard dependency on purpose?

There is a temptation, once verify prints its one success line, to treat the quarter hour as finished and the review as optional. That temptation is how a flipped exit gets promoted into a feeling of safety that the card never actually earned. The card proves that one command changed its mind under one shell, which is more than a transcript and less than a careful reader. I still read the diff, and I still ask whether the check was too weak to notice a wrong fix.

Some failures should never enter this workflow, and pretending otherwise is how a tidy script becomes a leak. Do not capture a command that prints tokens, customer rows, or production URLs into .replay, and do not commit that directory by accident. Skip the method when the check is non-deterministic, because a flip to zero might be luck wearing a green coat. Skip it when you need signed provenance, an air-gapped policy, or a human gesture that no shell can honestly replay.

Teams with a gated CI job can keep the card local, then let CI be the stranger who reruns the same words. If your check needs a browser, a paid sandbox, or a secret you must not paste, leave the remote server out of the story. A local red-to-green flip is already a better first fifteen minutes than a chat that rewrote three files and wished you luck. Why hand the only copy of the failure to a window you might close before lunch?

If you already have a free model session and a spare server, refuse the first diff that arrives without a card. The useful question is not whether the assistant sounds sure of itself before you have looked at the exit. The useful question is whether tomorrow morning you can rerun the same words and watch that recorded red become zero. I would rather lose a clever patch than keep a repair I cannot replay on a clean shell the next day.