DEV Community: cilly

Disposable isolated dev environments with Claude Code worktree hooks

cilly — Mon, 10 Aug 2026 05:01:38 +0000

Once you start working with coding agents, the unit of work shifts from "one branch a day" to "three or four tasks at once." The agent moves on to the next task without waiting, so the bottleneck on the human side becomes workspaces. If everything fights over a single checkout, all that parallelism dies.

git worktree solves half of this problem. It grows multiple working trees from the same repository, so the code is isolated. But a dev environment doesn't run on code alone. The DB, ports, dev servers, containers — all of these stay shared no matter how many worktrees you create. Apply a migration in worktree A and the app in worktree B breaks. Start dev servers in both and they fight over the port. git worktree by itself does not give you parallel development.

So I built a mechanism that spawns a dedicated environment (DB, ports, processes) per worktree and manages its lifecycle automatically through Claude Code hooks. One command brings up the environment together with the worktree when a task starts; closing the session stops the environment; merging leaves no trace. Disposable, isolated environments.

I've been running this on three projects with different constraints:

Project A: a monorepo — dedicated DB container + frontend dev server per worktree
Project B: a monorepo — runs on a local emulator suite (with the constraint that its ports are fixed)
Project C: multiple repositories (polyrepo) — isolation has to span repos

Despite the differing constraints, the architectures converged to the same shape. This article is that converged design — the division of roles between hooks, skills, and the CLI, plus the design decisions that solidified in operation.

The big picture

Whatever the entrance, the substance is one CLI. Hooks connect lifecycle events to the CLI, and the dedicated environment never touches the main one.

There are only three kinds of actors.

The CLI script … a shell script holding all the real work — create, start, stop, destroy (deterministic, idempotent)
Hooks … connect Claude Code lifecycle events (worktree creation, session start / end) to the CLI
A skill … translates natural-language requests inside a session into CLI commands

The rest of this article walks through five design principles that settled in operation.

Principle 1: put the real work in a deterministic CLI; the skill is only a translator

This is the most important decision. Never let the LLM execute environment orchestration — creation, allocation, startup, teardown — as a "procedure." Everything is materialized in one shell script (a few hundred lines), and the skill's job is narrowed to "translate the request into a command, run it once, report the result."

The skill definition (SKILL.md) is essentially this mapping table:

What the user says	Command
"Set up the environment for TASK-1234"	`up 1234`
"I want to verify with the backend too"	`up 1234 --with-backend --clone-db`
"Pause it for now" (don't delete)	`stop 1234`
"Resume the one from earlier"	`start 1234`
"Tear down this worktree"	`remove 1234` (destructive — confirm first)
"List them" / "What's the status?"	`list` / `status`

If you let an agent improvise git and npm commands, the procedure differs subtly every time, and so does the state after a failure. Pushing everything into a script buys you:

Idempotency and reproducibility … same input, same result; safe to re-run after a mid-way failure
Agent independence … run it straight from a terminal with no LLM and no tokens; usable from CI or other agents
Token savings … even via the skill, the model only reasons about "which command"
Testability … if source-ing the script loads only function definitions, allocation logic can be verified in isolation

The skill explicitly states: "do not re-type individual git commands by hand (the script is the single source of truth)." LLMs are clever; left alone they invent workaround procedures that bypass the script. That one line is the brake.

The three entrances are a corollary of this design. Because the substance is a CLI, calling it (1) from a launcher, (2) from a terminal, or (3) via natural language in a session all produce identical behavior.

Principle 2: session = the environment's lifetime (SessionStart / SessionEnd)

When humans manage environment lifecycles, leftover running environments always pile up. So I tilted it to "the environment lives exactly as long as the Claude Code session."

SessionStart hook … if cwd is a managed worktree, auto-start the environment if stopped
SessionEnd hook … likewise, auto-stop (data persists in volumes; the next start resumes with no diff)

So cd worktree && claude wakes the environment, and /exit cleans up after itself. "Forgot to stop it" and "forgot to start it" disappear structurally.

SessionStart's stdout is injected into context

SessionStart has a crucial property: its stdout (or additionalContext) is injected into the session's context. I use it to push connection info in right at startup.

{
  "systemMessage": "[wt] environment resumed",
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "FE: http://localhost:60398 / DB: localhost:55231 (user/pass...)"
  }
}

Both Claude and the human start the session already knowing the URLs and DB connection info. No more re-discovering "where is the dev server running?" every time. With dynamic port allocation (below), URLs change every run, so this injection matters even more.

Trap: SessionEnd fires on `/clear` too

One trap from operation: /clear (clearing context) also fires SessionEnd, immediately followed by SessionStart. If you naively stop there, the environment goes down mid-work and has to boot again. The hook's input JSON carries a reason, so branch on it:

REASON=$(echo "$INPUT" | jq -r '.reason // empty')
[ "$REASON" = "clear" ] && exit 0   # do not stop on clear; the session continues

Principle 3: take over creation itself with the WorktreeCreate hook

Claude Code can be launched as claude --worktree <name>, and defining a WorktreeCreate hook lets the hook own the creation of the worktree. The contract is simple:

stdout must contain only the worktree's directory path (all other logs go to stderr)
non-zero exit blocks the creation

If the hook does git worktree add plus the full environment build (DB container, env, dependencies, dev server), then claude --worktree fix-login brings up the environment, not just the worktree. Three refinements proved necessary in practice.

Mirror progress to /dev/tty

Hook stderr is only visible in Claude Code's debug mode. Environment builds take minutes, so silence looks like a hang. When a terminal can be opened, mirror progress to /dev/tty:

# test by actually opening it (-w can pass while opening still fails)
if (exec 4> /dev/tty) 2>/dev/null; then
  exec 3>&2 2> >(tee /dev/tty >&3)
fi

Leftover branches: present options and abort

Teardown keeps branches (for history), so re-creating under the same name hits "the branch already exists." Reusing silently is risky; deleting silently is worse. And hooks cannot ask questions. So the policy is passed via an environment variable, and with none set, the hook prints the options and exits non-zero:

reuse … reuse the existing branch (carrying over previous commits)
new … create a suffixed new branch (-2, -3…) from base
delete … delete and recreate from base (aborts if commits not on base exist; delete-force overrides)
unset … show the choices above and abort

"Hooks can't interact, so convert judgment calls into abort + how to re-run" is a pattern that generalizes to other hooks.

Self-replicate the tooling into the worktree

A worktree checks out the base branch's content. Until the hooks and skills are merged into base, sessions opened in the worktree get neither auto start/stop nor the skill. So at the end of creation, the hook copies settings / hooks / skills from the main side into the worktree.

That copy needs mis-commit protection: a worktree-local .claude/.gitignore listing exactly what was copied. Two subtleties:

don't use git's info/exclude … it's a shared file even across linked worktrees, so it would leak to the main side
do not ignore skills … gitignored files can be missed by skill discovery scans; ignoring them breaks the skill itself

Principle 4: an "environment-variable protocol" for entrances that take no flags

claude --worktree <name> accepts no arbitrary flags, and the JSON a hook receives has no argv. Yet real options exist: clone the DB with data or schema-only? which base branch?

The answer is environment variables. Options live in a WORKTREE_* namespace, used by the flagless entrances:

WORKTREE_TITLE="rework login screen" WORKTREE_DB=schema claude --worktree fix-login

Direct CLI calls can use flags, so the rule became "everything is settable via env var or flag, and flags win." Interpretation is centralized in one function, and a __setup-opts subcommand prints how the current env vars will be interpreted. Paths with no flags are also hard to debug — that inspection port quietly earns its keep.

The same trick powers a custom launcher. Project C ships a wrapper that shadows claude as a shell function, intercepts its own flag, converts it to an env var, and launches plain claude. SessionStart hooks inherit env vars set before launch (verified empirically), so the hook detects the variable and routes to environment creation:

claude -we 1234
  └ wrapper: intercepts -we → sets WORKTREE_ENV_REF=1234 → launches plain claude
      └ SessionStart hook: detects WORKTREE_ENV_REF
           on startup → runs the CLI's create
           on resume  → shows status + DB connection info

One operational caution: keep SessionStart's automatic work light (worktree creation + record only), and defer heavy work (dev-server boot, first container build) to after the session opens. Hooks block session startup; a ten-minute build there ruins the experience.

Principle 5: "collision-free" is earned by abandoning fixed values

The nastiest problem with concurrent environments is collisions — ports and resource names. This went through three generations.

Generation 1: fixed ports + mutual exclusion. Project B's emulator suite has fixed ports, so it runs one environment at a time. SessionStart checks port occupancy with lsof; if another environment holds it, it doesn't start and injects that fact into context, returning the decision to the human. A fair second-best under the constraint.

Generation 2: sequential IDs from a shared registry. Allocate an ID per environment and offset ports as port = base + ID * 100. It broke down for two reasons. The registry JSON's read-modify-write has no lock — two simultaneous creates both take ID 1 and everything collides. And fixed ports collide with unrelated existing processes (like the main dev server) no matter how correct the allocation is.

Generation 3: content-derived IDs + dynamic allocation. The current shape.

The environment ID is derived from content: <task key, lowercased>-<short hash of the worktree path>. It namespaces docker compose project names, containers, volumes, networks. Because the ID is determined by content, allocation races are impossible by construction (and no shared registry is needed)
No fixed ports. The dev server gets a free port from the OS (socket.bind(("", 0))); containers let docker assign and are read back afterwards. Infra containers (DB etc.) aren't host-published at all — apps resolve service names inside the docker network; only a GUI-client port is published dynamically
No fixed subnets (docker auto-assigns)

With no fixed values anywhere, any number of environments coexist. The price is predictability: URLs change every run, so completion output always prints them, and Principle 2's SessionStart injection keeps feeding them into the session.

Make runtime.json the single source of truth

The dynamically resolved ports, URLs, PIDs, and state are recorded in a per-worktree runtime.json (gitignored). This file is the environment's single source of truth:

{
  "env_id": "task-1234-cc92ae",
  "title": "rework login screen",
  "state": "running",
  "fe": { "port": 60398, "url": "http://localhost:60398", "pid": 12345 },
  "backend": {
    "compose_project": "task-1234-cc92ae",
    "db": { "port": 55231 }
  }
}

Crucially, teardown is driven by this record. remove reads PIDs, the compose project, and the worktree path from runtime.json and reliably cleans up: kill processes → docker compose down -v → delete artifacts → git worktree remove. "Record what you create; delete from the record" eliminates cleanup leaks.

Invariants — guaranteed by the script, never to be broken

On top of the design decisions sit invariants shared by all projects. They're also written into the skill definition ("the script guarantees these; do not make changes that break them") to guard against agent edits.

Never write to the main environment … don't touch normal checkouts, their ports, containers, DBs, or config. Even backend compose definitions stay unmodified — only an external override file swaps values (repositories unmodified)
Teardown removes everything — except the branch … clean up all dedicated resources including down -v, but keep the branch so pushed PRs are unaffected
Never copy plaintext secrets into worktrees … env files with credentials are excluded from copying
Destructive operations require confirmation … remove and DB restore present the target and impact (e.g. uncommitted changes will be lost) before running

Daily flow, and the quietly useful commands

The daily rhythm looks like this:

create 1234 --desc "rework login screen"   # build the environment (worktree + deps)
up 1234 --with-backend --clone-db          # start (DB cloned from main)
stop 1234                                  # pause before going home (nothing deleted)
start 1234                                 # resume next day (same DB)
pr 1234                                    # push + create PR
remove 1234                                # full teardown after merge

Operation forced a set of "boring but effective" commands into existence:

list … all environments, keeping the creation-time --title / --desc visible. Past four parallel tasks, "what was this one again?" genuinely happens
doctor … diagnostics: required tools, docker state, mismatches between the record (runtime.json) and reality, orphaned compose-project candidates
clean … leftover detection. Report-only by default; --force after review. A marker file protects environments you keep on purpose
snapshot / restore … DB rollback to any point. Invaluable for migration work
logs … aggregates dev-server and container logs. Never tail -f — it blocks the agent

doctor and clean are the safety net for the premise that automated management will eventually drift from reality. Machines die before auto-stop runs; humans touch docker directly. Having "reconcile record vs. reality" as a command spares you manual forensics when it drifts.

Summary

git worktree isolates only code. Environment isolation and lifetime management (DB, ports, processes) are built from hooks and a CLI
Put the real work in a deterministic CLI; keep the skill a translator. However many entrances (launcher / terminal / natural language), the substance is one
Make session = environment lifetime with SessionStart / SessionEnd; share connection info from second zero via stdout injection
Hooks can't interact and get no argv. Convert judgments into "abort + how to re-run," and options into an "environment-variable protocol"
Collision-freedom comes from abandoning fixed values: content-derived IDs + dynamic allocation + runtime.json as the single source of truth

Parallel development with agents is limited less by "how fast the agent is" than by "how many workspaces you can line up." Per-worktree disposable environments are the infrastructure for the lining-up side. The complementary question — "which repos may this session touch, and how far" — is covered in Enforce with config, not attention — scope and permission guardrails for coding agents.

Syncing what comes after provisioning — Cloudflare DNS, Logto, cert-gated proxy, env bundles

cilly — Thu, 23 Jul 2026 12:00:38 +0000

In Provisioning GCP / Firebase environments from a single settings.yml, I covered getting GCP projects and the Firebase platform generated automatically from a settings file. But that's not the end. Add one environment and a chain of chores appears outside the foundation:

Add DNS records in Cloudflare pointing at the Firebase custom domain
Once delivery is stable, turn the proxy on to get CDN / WAF
Set up Logto applications / API resources / roles for the operator console
Collect each app's env values, encrypt them, and make them referenceable at deploy time

These live in a different layer from provisioning, but left alone they regress into "manual work per environment." So I built Platform Sync — a mechanism that keeps them following the same source of truth as the foundation.

The big picture

Config (Git) as SoT, chaining Cloudflare DNS → Logto → proxy → env bundle through a series of dispatches.

There are two SoT files. terraform.yml holds service / environments / hosting (i.e. where domains and DNS come from); platform.yml holds Logto's auth rules and the tenant ⇄ env-group mapping. Platform Sync itself fires manually via workflow_dispatch, defaulting to plan (diff display only). To prevent accidents, the writing mode apply only runs when explicitly selected.

# platform.yml (excerpt, abstracted)
tenants:
  - key: my-service-non-production
    env_groups: [dev, stg]      # the group of envs this tenant is responsible for
    roles:
      - { name: admin, scopes: [secrets:read, secrets:write] }
      - { name: developer, scopes: [secrets:read] }

Processing runs Cloudflare DNS → Logto, in that order. Logto's redirectUri depends on the domain (= DNS / hosting), so apply runs Cloudflare first. And only when apply succeeds are the two follow-up workflows (Cloudflare Proxy / Env Bundle) dispatched. All authentication is keyless: each environment's read-only service account is impersonated through Workload Identity Federation (OIDC). No long-lived credentials anywhere.

The default is "never delete"

plan and apply share the same diff computation, with the mode toggling display-only versus real writes. The decision that pays off here: per-environment sync emits no deletions, ever.

Cloudflare's desired state is derived from the DNS updates Firebase requests. But those requests empty out once the domain goes ACTIVE — they're satisfied. So naively deleting "records that exist but aren't in desired" risks taking out records that are serving traffic. Per-env sync therefore only creates what's missing; deletion is split into a separate reconcile job. Reconcile matches against the env naming convention (<tier>-<number>) and tier constraints, and only records not belonging to defined envs or retained_envs become deletion candidates — the line that avoids false positives on unrelated records like www or api.

Deletion is always dangerous, so it only activates with an explicit allow_delete flag; plan stops at previewing "what would be deleted."

The hard part: don't turn the proxy on until the cert exists

The timing of the proxy switch is what this pipeline sweats over most.

Create DNS-only → let Firebase issue the cert → wait for ACTIVE → proxy only the serving records. The order carries meaning.

DNS records are always created with proxied: false (DNS-only, grey cloud). In that state, Firebase can reach the origin directly for domain-ownership verification and certificate issuance. Turn the proxy on too early and the verification and ACME challenge traffic hides behind Cloudflare's proxy (different cert, different IPs) — the certificate can't be issued and delivery breaks.

So the Cloudflare Proxy workflow polls the Firebase custom domain's host / cert status at 15-second intervals. Once it reaches HOST_ACTIVE && CERT_ACTIVE (treating CERT_PROPAGATING during distribution as "issued = reachable"), it flips only the serving records that point at the hostname itself to proxied: true. Ownership TXT records and ACME-challenge CNAMEs stay DNS-only.

Certificate issuance takes time. That's why this stage isn't embedded in the main workflow but split into an independent workflow that can be re-run later. Timing out while pending isn't a failure; run it again and it resumes waiting for ACTIVE. Already-proxied records are skipped, so it's safe to run any number of times.

Logto: auth config that depends on domains

The Logto side syncs per tenant. It obtains client_credentials for the Management API using an M2M app's credentials and reuses the token. Three kinds of things are synced:

API Resources (+ scopes / permissions)
Roles (+ scope assignments)
Applications (the SPA for the operator console)

Writes have ordering constraints: assigning scopes to a role requires the resource-side scope ids, so it proceeds API Resources → Roles → Applications.

An application's redirectUri is assembled from the environment's domain (https://<domain>/callback, etc.). The point is that target domains are derived from terraform.yml's hosting definitions, not listed in platform.yml. This is also why apply runs Cloudflare first — without the domain settled, you can't build the correct redirectUri. Deletion is conservative here too: only applications it manages — names starting with <service>- and ending with -web-system-console — can ever be treated as orphans.

Env bundles and GPG: keep it off argv

Last is how env values are bundled. Per environment, a value source (JSON including the Firebase web app config and Logto app id) is generated, tarred, and encrypted with GPG symmetric encryption into a .tar.gpg. The encrypted bundle is committed; the decrypted plaintext JSON is gitignored. Only "the key itself" lives in CI secrets.

# The passphrase arrives via env var and flows only into fd 3 via process substitution
set -o pipefail
tar cf - "$src" | gpg -c --batch --yes --pinentry-mode loopback \
  --passphrase-fd 3 -o "$out" 3< <(printf %s "$PASSPHRASE")

Unglamorous but important: how the passphrase is passed. Put it on the command line and it's visible in ps, so instead it's fed through process substitution into fd 3 and read with --passphrase-fd 3. printf is a bash builtin, so it doesn't even become a separate process. A path where the passphrase appears neither in argv nor in any other process.

The other trick is the diff. GPG encryption produces different bytes every run, so diffing bundles directly yields changes even when the content is identical — mass-producing meaningless PRs. So the existing bundle is decrypted once and the plaintexts compared; re-encryption happens only when values actually changed (or no bundle exists). PRs force-push to a fixed branch: update the open PR if one exists, create one if not — never duplicating.

Developers hold no secrets

The heart of this setup: a developer can reach deployment without ever holding a dev environment's env values or the decryption key. Generating the value sources, encrypting with GPG, decrypting at deploy — all of it completes inside CI. The passphrase is held only by CI as a CI secret; the only thing in Git is the encrypted .tar.gpg. The plaintext value source appears only on CI runners during generation and is gitignored, so it's never committed.

In other words, what developers touch day-to-day is the config (terraform.yml / platform.yml) and the finished encrypted bundles. "No dev secrets on anyone's laptop" is guaranteed by the mechanism, not by operating rules or review diligence. Since no distribution channel for secrets exists, the accidents themselves — leaks during distribution, stale .env files quietly diverging across machines — can't happen. It's the same idea as going keyless (WIF) for cloud credentials, extended to application env values.

Decisions that pay off

Keyless doubles as an existence check. When cleaning up bundles for retired environments, "does that GCP project still exist?" is answered by attempting to impersonate the read-only SA with access_token and checking success. If the project / SA is gone, impersonation fails — that failure is the "doesn't exist" signal. (One caveat: without token_format, the auth step merely writes config and always succeeds, so it decides nothing.)

Heavy stages are split into independent workflows. The certificate wait is separated from the main body, and only environments with DNS changes are handed to the follow-ups. Zero changes means the proxy workflow isn't even started.

What I gave up

The cost is the growing chain of workflow dispatches. The apply → proxy / env-bundle branching trades clarity for the chore of tracking "where did it stop." With Cloudflare, Logto, Firebase, and GitHub Actions all involved, failure triage is harder than in a single system.

Even so, collapsing the cost of one more environment into "add a few lines of config and run apply" is worth a lot. Last time, the foundation was generated from config. This time, everything outside it — DNS, auth, delivery, env — follows the same config. Push infrastructure all the way into "something you write and generate," and the operational concern shifts from individual environments to the machinery that generates and syncs them.

Originally published at cilly-yllic.github.io.

Runtime and delivery of a multi-service Firebase environment

cilly — Thu, 23 Jul 2026 12:00:32 +0000

I designed a Firebase / GCP environment where multiple services live together in a single GCP project. Leaving out anything product-specific, this note presents the architecture itself through two cross-sections: "how it runs" (runtime) and "how it ships" (delivery).

Runtime: separate writes from reads

Writes go to SQL (the SoT); reads come from Firestore (a rebuildable cache). The backend updates both at once, and reconciliation guarantees consistency.

At the center of this environment is a design that separates writes and reads into different datastores. Writes are received by the backend (Next.js / Cloud Run), which updates both the SoT (Cloud SQL via Firebase Data Connect) and Firestore in the same operation. Cloud SQL is the source of truth; Firestore is a read-only cache that can be rebuilt from the SoT. Clients stream Firestore via onSnapshot, so their own writes reflect immediately. Divergence from the double write is repaired by a reconciliation job — enqueued before the DB updates — that treats the SoT as authoritative.

The benefits and costs of this "Firestore as cache, not SoT" decision are explored in a separate note, so I won't go deeper here:

Treating Firestore as a public cache

What this note is really about is the two remaining structures that make this read/write separation work on a single GCP project shared by multiple services.

Two-layer DB: Core and Service

The database is two-layered: a Core DB holding cross-cutting foundation entities — identity, organizations, membership — and a Service DB holding each service's own domain entities. This repeats in the same shape in both Cloud SQL and Firestore.

The Service DB only references Core's identifiers; it never duplicates shared data. Cramming multiple services into one project tends to scatter identity everywhere, but this boundary preserves the state where "from any service's viewpoint, users and organizations come from Core, and only Core." Adding a service means adding only a Service DB.

Two authentication tracks

Authentication isn't singular either. End-user apps authenticate with Firebase Authentication; the operator console authenticates with an external OIDC IdP.

The latter can't use onCall, which assumes Firebase Auth — so Cloud Functions are exposed as onRequest, and the function itself does JWT verification against JWKS plus scope-based authorization. Two authentication domains coexist on physically separate paths. When you want end users and operators to have different roots of trust, splitting the path entirely turned out to be a much clearer boundary than straining Firebase Auth with custom claims.

Delivery: fan out from a monorepo to each environment

From one Nx monorepo, a keyless CI fans out to per-environment GCP projects.

Behind how it runs is a CI that fans out from a single Nx monorepo to multiple deploy targets.

The monorepo holds, per service, the API (Cloud Functions) / Web (SSR or SPA) / security rules / Data Connect schema. Nx builds only the affected apps.
CI (GitHub Actions) holds no keys. It operates GCP through Workload Identity Federation (OIDC), impersonating the deploy service account. No SA key files sit in the pipeline.
firebase deploy fans out to each target in the per-environment GCP project (Cloud Functions / App Hosting / Hosting / Firestore rules & indexes / Storage rules / Data Connect schema). Environments switch through templated config.
Projects, IAM, WIF, API enablement, and Firebase Auth are provisioned by Terraform before any deploy. The "create the environment" layer and the "ship the code" layer are kept separate.

The "create the environment" side (provisioning GCP / Firebase with Terraform + GitHub Actions) is covered in a separate note:

Provisioning GCP / Firebase environments from a single settings.yml

Decisions that pay off

Read/write separation. Consistent related updates and relational constraints go to SQL; realtime push goes to Firestore. Once you shrug Firestore off as "a cache that can break and be rebuilt," you gain full freedom in modeling the read side.

One project, shared + two-layer DB. Putting multiple services in one GCP project lets shared identity and runtime (Functions codebases) coexist naturally. The Core / Service two-layer structure is the boundary that keeps that cohabitation from collapsing.

Keyless. Issuing no SA key files removes long-lived secrets from the pipeline. CI and TFC alike borrow permissions through OIDC only for the moment they need them.

Closing

I said "presents," but what these two cross-sections really show is a map of where responsibilities live. Writes in SQL, reads in Firestore, auth split between users and operators, provisioning in Terraform, deployment in the firebase CLI. Decide the boundaries first, and as services multiply, you keep adding onto the same map.

Originally published at cilly-yllic.github.io.

Treating Firestore as a public cache

cilly — Thu, 23 Jul 2026 00:03:01 +0000

Using Firestore as "the app's primary database" is easy at first. Writes and reads complete in one place, and onSnapshot gives you realtime push for free. But as a service grows, keeping Firestore as the SoT (source of truth) exposes some fatal constraints.

Where SoT-Firestore hurts

Weak transaction boundaries, missing complex queries, the cost structure, the difficulty of migrating away. The harshest one: you cannot narrow related updates with a WHERE. For the use case "update a set of documents matching a condition, consistently, in one go," Firestore is structurally weak.

Redefining it as a public cache

In one project, I made Cloud SQL the SoT and treated Firestore as a "read-optimized projection." Writes go through the backend (Next.js / Cloud Run), and the SoT (Cloud SQL via Data Connect) and Firestore are both updated within the same write path. Separately, a Cloud Run reconciliation job runs and checks and repairs consistency against the SoT as authoritative. This reconciliation job is enqueued at the start of the request, before the DB updates. Because it's queued first, even if the write dies halfway, the consistency check always runs afterward and repairs the state. From the client's perspective, Firestore is a rebuildable cache — in the worst case it can be rebuilt from the SoT.

// Writes go through the backend. The backend updates both the SoT
// (Data Connect → Cloud SQL) and Firestore. Clients never write Firestore directly.
await backend.updateEntity({ id, title });

// Changes are pushed back in realtime via Firestore's onSnapshot
unsubscribe = onSnapshot(entityRef, (snap) => render(snap.data()));

Benefits and costs

The benefits are clear. The SoT side (SQL) brings transactional consistency and complex queries; the read side (Firestore) brings freedom in data modeling and realtime push; and consistent syncing with external systems (OpenSearch / BigQuery, etc.) coexists naturally. Since the backend updates Firestore at write time, the frontend gets immediate reflection through its onSnapshot stream. No optimistic-update tricks like "hold the value I just wrote in the UI for a while."

The cost is not latency — it moves to double writes and consistency. The backend writes two places, SoT and Firestore, so if one fails they can diverge (this is not a single distributed transaction). What closes that gap is the Cloud Run reconciliation, verifying and repairing Firestore with the SoT as truth. You can only shrug Firestore off as "a cache that can break and be rebuilt" because that consistency check stands behind it. The operational cost concentrates in this double-write path and the reconciliation route.

Which to choose

The choice between "Firestore as SoT" and "Firestore as cache" comes down to the expected lifespan of the service. A short-lived prototype: the former. Something you intend to grow for years: the latter. And if you're in between — the cost of switching over later is far higher than the cost of treating it as a cache from day one.

Originally published at cilly-yllic.github.io.

Provisioning GCP / Firebase environments from a single settings.yml

cilly — Thu, 23 Jul 2026 00:02:58 +0000

Every time you add a service on GCP and Firebase, the same manual work repeats. Create the project, attach billing, enable APIs, set up the Terraform service account and Workload Identity, configure Firestore / Auth / Storage / App Hosting. Multiply all of that by the number of environments (dev / stg / prd). No matter how carefully you write the runbook, as long as human hands are involved, environments drift.

So I built a platform where dropping a single settings.yml per service provisions everything automatically. The configuration is the source of truth; the infrastructure is nothing more than its projection.

What gets built

Let's start with the "generated" side — the overall picture.

A shared bootstrap project lends permissions, keyless, to per-environment service projects.

The structure has three layers.

Identity & Trust — Terraform Cloud and GitHub Actions operate GCP through Workload Identity Federation (OIDC). No service account key files are ever issued.
Shared bootstrap project — the "platform for the platform": the WIF pool / provider, the Terraform service account, the Cloud Run router described below, and Secret Manager. Created once per organization.
Per-environment service projects — independent GCP projects per environment, like my-service-dev-001. Inside each, Firebase resources (Auth / Firestore / Storage / App Hosting / Data Connect / Functions …) line up according to feature flags.

Holding no keys is what makes this work. Each environment's Terraform SA is impersonated from the bootstrap SA, and that permission only fires through an OIDC token exchange. There is no long-lived credential anywhere that could leak.

How it gets generated

Now the "generating" side. From merging settings.yml to applying against GCP, everything is chained without polling.

One settings file flows in a straight line: GitHub Actions → Terraform Cloud → GCP.

The flow has two stages.

# terraform/settings.yml in the service repo (excerpt)
service: my-service
environments:
  dev-001:
    labels: [tier:dev]
    firebase_platform:
      firebase: true
      firestore: true
      app_hosting:
        - { backend_id: web, location: asia-northeast1 }
      notifications:
        - url: https://hooks.slack.com/services/...  # notify apply results

Action A (project-bootstrap) reads settings.yml, filters target environments by status / labels, and creates GCP projects / SAs / WIF in one batched run.
The run's completion notification (HMAC-signed) is received by a Cloud Run router, which verifies it and fires GitHub's repository_dispatch.
That triggers Action B (firebase-platform), which stands up a workspace per environment and applies the Firebase resources.

Instead of keeping a polling orchestrator running, I chained webhooks: Terraform Cloud notification → Cloud Run → GitHub. Only TFC knows the state, so the result notification to Slack is also sent by TFC — the one party that knows whether the apply succeeded.

Design decisions that pay off

Feature flags decide everything down to APIs and IAM. Write firestore: true in settings.yml and the corresponding API enablement, resource creation, and role grants to the CI SA all cascade from it. Leave it unset and nothing is created (zero side effects). Users never need to memorize which GCP APIs a feature requires.

Configuration ownership stays with the service team. Which features to use is the application's concern, so settings.yml lives in the service repo and the platform side only reads it. The platform never becomes a central registry hoarding every service's configuration.

Deletion has a separate safety net. Removing an environment from the settings normally destroys it, but if its name is listed in retained_envs, it is only removed from state and the GCP resources stay. A config mistake cannot take production down with it.

What I gave up

There are costs. The webhook chain adds one more operational component — the Cloud Run router. You have to think about HMAC secret rotation and a retry path for dropped notifications. Since it spans Terraform Cloud, GitHub Actions, and GCP, failure triage is harder than in a single repository.

Even so, the value of collapsing the cost of adding an environment to "add a few lines to settings.yml and run the Action" is significant. Manual drift disappears structurally, and anyone gets the same environment. When you push infrastructure all the way into "something you write and generate," the operational concern shifts from individual environments to the generating machinery itself.

Where it's published

The platform is open source — a monorepo of Terraform modules and GitHub Actions, free for anyone to use.

Repository — github.com/cilly-yllic/terraform-google-platform
Terraform Registry — registry.terraform.io/modules/cilly-yllic/platform/google

Originally published at cilly-yllic.github.io.

Enforce with config, not attention — scope and permission guardrails for coding agents

cilly — Wed, 22 Jul 2026 12:17:24 +0000

When you put a coding agent (like Claude Code) to work, where it really pays off is work that spans multiple repositories. Writing into one repository while referencing another's implementation. Fixing a shared library while verifying behavior in the repository that consumes it. Updating a generated-artifacts repository while reading the config repository. The agent's speed shines in this kind of "straddling" work far more than in single-feature fixes.

But cross-repository work widens the blast radius just as much. Accidentally editing a repository you only meant to reference. Pushing straight to another repository's main. Touching files unrelated to the goal. The more repositories are involved, the blurrier the boundary of "which ones may I touch right now, and how far am I allowed to go" becomes — and the agent re-reads that boundary from scratch every time, so there is structurally nothing equivalent to human attentiveness. That's why "asking nicely in the prompt to be careful" can't fundamentally prevent accidents.

So I built a mechanism that enforces guardrails through config files instead of attention. The idea is simple: before starting work, declare "the repositories that may be straddled" and "the permission for each," and make everything else technically impossible. The span of the cross-repository work itself gets frozen as configuration up front.

A session = a declaration of scope + permissions

The parent declares scope and permissions and spawns the session. Each straddled repository is handled per its permission — a "read-only repository" structurally cannot be modified.

I call the smallest unit a "session". One session = one unit of work, and at launch two things are fixed:

Scope … which repositories / directories may be touched
Permissions … per target, how far is allowed

Permissions have three levels:

read … reference only
write-local … edit + local commits. No push
write-push … push allowed (including PR creation)

The point is that permissions are held per target. In cross-repository work, repositories of differing trust naturally mix within one session. "Reference the config repo read-only, write-push to the artifacts repo." "Fix the shared library write-local but don't push; use the consumer repo read-only for verification." A session handles combinations like these as one unit of work — so it carries a single declaration (manifest) listing target-level pairs, and scope, permissions, and identity checks all concentrate there.

In fact, this very article was written in such a cross-repository session: referencing the repository the mechanism comes from as read, while writing the text into the article repository as write-push. The guarantee that the read side can never be modified is enforced by config, so there's no fear of breaking the source being referenced.

Build scope as "what isn't opened doesn't exist"

Scope is an allowlist. The list of directories the agent can access enumerates only the allowed targets. Repositories not listed cannot even be referenced. I deliberately avoided symlink tricks so that scope is complete in the config file alone.

The direction matters: you add what can be touched, never subtract from everything. Because the default is closed, any target you forget to configure fails safe (= invisible).

Hard part 1: keep the agent away from its own permission definitions

This is the single most effective design decision. From inside a session, the files defining scope and permissions themselves cannot be modified.

The logic goes like this. When you give an agent read permission, the config file describing "what counts as read" is also just a file. If the agent could edit it, it could notice "removing this deny lets me write" — room to loosen its own guardrails. An entity holding permissions must not be able to rewrite its own permission definition. So permission changes can only happen one level up (the parent that spawns sessions).

There's an implementation trap here, though. What you want to protect is "the permission and scope definition files themselves." If you conclude "just ban Edit / Write entirely," you fail: the agent can no longer write even its own work log. What's needed is not a per-tool ban but a per-path ban. Deny exactly the definition files by name, and keep the session's working area writable.

// What we protect is the session's own permission/scope definitions. Deny exactly those by name.
"deny": [
  "Write(.claude/**)",   // permission definitions (settings)
  "Write(/CLAUDE.md)"    // scope declaration
  // Working areas like session logs stay writable
]

Conversely, read-permission repositories get banned wholesale — since they're read-only, excluding the entire tree from Write / Edit is the straightforward, safe move. The problem appeared where "ban wholesale" collided with "keep my own logs writable."

I actually messed this up once. The session's own working directory was nested under a read-target repository. Banning the read target's whole tree took the session's logs down with it — the agent could no longer write its own log.

What fixed it was not narrowing the deny but physically separating the working area from the scoped targets. Move the session's working directory (logs, scratch notes) outside the protected tree entirely. Then read targets can be banned wholesale with confidence, and the session writes its logs freely. Not shaving down the protected area to make things fit — splitting the ground so that what you protect and where you write never overlap.

Hard part 2: double-lock push

Push is the scariest. Pushing to a read repository; pushing straight to main. Both are hard to undo.

Naively, narrowing the allowlist of push commands stops it. That works well against the agent's careless accidents. But as hardness goes, it's insufficient: an allowlist only checks "is this command shaped like git push", so it can't judge variants that switch the working directory like git -C <other-repo> push, nor which repository or branch the push is aimed at. Matching on command shape cannot protect the destination's permission.

So I made it two layers:

Narrow "what can push" with the allowlist … only sessions holding write-push get a push command at all. Sessions with only read or write-local are never given one.
A pre-execution hook … inspects the command string, derives the push destination's repository path, looks up its permission, and decides.

The hard layer is the second. It looks at the command string about to run, works out the push destination from git -C <path> or the working directory, and checks it against the manifest (path → permission). Pushes to read / write-local paths are all blocked; even on write-push paths, direct pushes to main / master are blocked. If the destination can't be determined, it fails safe and rejects, prompting "specify the target explicitly with git -C <absolute path>". The hook physically enforces the per-destination permission that command-shape allowlists can't reach.

Make sessions resumable

Agent sessions die. If the context vanishes with them, you're back to square one every time, so work logs are kept in two layers:

Snapshot (always current, overwritten) … the one page that says "read this and you can resume": current task, target repositories and working branches, touched files, next move, unresolved decisions
Task log (chronological, append-only) … the history of events and decision rationale

On resume, a launch hook automatically injects the snapshot into context. The agent picks up "from where it left off" without being told anything. If guardrails are the mechanism that prevents accidents, this is the mechanism that prevents losing work.

Where this stands, and what's next

Honestly: this is still personal tooling. It's something I built to put guardrails on my own agent, on my own machine — not a production system.

But the shape itself — "a session = a declaration of scope + permissions" — has no reason to stay personal. I'm considering publishing it as a repository, installable globally, so anyone's machine can cut sessions the same way. As more people use coding agents daily, the need to fix "what the agent may and may not touch" as an external declaration will only grow, and I'd like this to become a shared foundation for it.

When you try to control an agent cleverly, you're tempted to write clever prompts. But what actually stops accidents is usually not cleverness — it's the config that makes them impossible in the first place.

Originally published at cilly-yllic.github.io.

Generating every Firebase layer’s types from a single contract.yml

cilly — Wed, 22 Jul 2026 12:17:21 +0000

Sharing types between frontend and backend is an old problem. A while back it was common to keep the two in separate repositories, so you had no choice but to hand-write the same type definitions in each — that is, duplicate them.

The next stage was private packages. Extracting shared types into a package removes the duplication, but now you have one more repository, and during development you bounce between the frontend, backend, and package repos and editors. Worse, every time you fix a type, nothing reaches the frontend or backend until the package goes through commit → push → version bump → publish. That cycle sits in the middle of every verification loop. Private packages also need separate authentication for CI and deploy pipelines to install them — registry tokens and permissions turn into a surprisingly annoying mechanism. Embedding a shared repo as a git submodule instead just changes the flavor of the chore: every consumer has to advance the referenced commit, and checkout skew happens easily.

What solved this was the monorepo. Shared libraries can be referenced directly within one repository, and frontend and backend can be developed in parallel. If the problem were just "frontend and backend use the same types," the story would end here.

But once you adopt an architecture where Cloud SQL (Data Connect) is the source of truth and Firestore is a read projection (cache) — see Treating Firestore as a public cache (Japanese) — the axis of type sharing changes. It's no longer "one type referenced from both sides"; the same model gets written over and over in different representations, one per layer. A monorepo lets you reference the same type from anywhere, but it does nothing to keep definitions that have split into different representations consistent with each other.

The same model, written six times

Add a single Product model and these are the files you hand-write:

The Data Connect GraphQL schema (type Product @table(...))
The shared TypeScript type (interface Product)
The Zod schema (ProductSchema)
The Firestore projection schema (relations resolved to ids, timestamp becomes Date)
The API request / response types and their validation Zod
The NestJS class-validator DTOs

Each is a different representation of "the same thing," but nothing verifies them against each other. Every added field means walking through all of these files, and if you forget one, the breakage shows up much later — at runtime. This is not a problem you prevent by being careful; the multi-maintenance structure itself is the cause.

Write the contract, generate everything else

So I built a tool that unifies model definitions into a YAML contract file and generates every representation from it: firebase-contract.

One direction: contract → compiler (IR) → generated artifacts. Drift between artifacts and contract is caught by --check in CI.

# contract.yml (excerpt)
models:
  Product:
    key: [catalog, productNo]
    fields:
      catalog: { type: Catalog, relation: true }
      productNo: int
      title: { type: string, nonempty: true, maxLength: 200 }
      status: ProductStatus
      metadata: { type: ProductMetadata, optional: true }
      createdAt: timestamp

generators:
  - { generator: typescript, out: '#contracts', split: true }
  - { generator: zod, out: '#contracts', split: true }
  - { generator: data-connect-graphql, out: src, split: true }
  - { generator: firestore, out: '#contracts', split: true }

A single fbc generate emits the TS types, Zod schemas, GraphQL schema, and Firestore projection all at once. Constraints like title's nonempty: true, maxLength: 200 flow identically into Zod — and, if you declare the API generators (api-validation / api-dto), into request validation and class-validator DTOs as well. "Only the validation is stale" stops happening.

Contracts can be split with imports, so in a multi-app monorepo the yml files can follow the repository layout. In the project where I introduced this, the root contract splits into 9 yml files across 2 apps, generating over 30 files.

Firestore is a projection, not "another schema"

This is where the tool earns its keep. When Firestore is a read projection, its schema stands in an odd position relative to Data Connect: not the same, but not unrelated either. Relations become resolved string ids, timestamp becomes Date, denormalized fields get added. Hand-written, you end up transcribing this "regular transformation plus a few additions" wholesale.

In the contract, a projection is declared as a derivation from a Data Connect model.

firestore:
  Product:
    from: Product
    collection: shops/{ws}/.../products/{productNo}
    omit: [catalog, log]
    fields:
      linkedCatalogTitle: { type: string, optional: true }

The projection rules — relation → id, timestamp → z.date() — are applied uniformly by the generator; humans only write pick / omit and the extra fields. Project-wide fields shared across projections can be declared once as fragments: and inserted into each projection with extends:. The generated Zod schema reuses fields whose chains are identical to the Data Connect side via .pick(), so only the parts where the representation actually changes appear in the file. The diff reads as design intent.

Data Connect's Any boundary

Data Connect stores embedded objects and JSON as an Any scalar, erasing the logical type. With hand-written schemas, what metadata "really is" lives in comments and memory. Generating from the contract, the GraphQL side keeps the logical type as a comment (metadata: Any # logical: ProductMetadata), and typed adapters that convert between the Any row and the logical type are generated alongside. This is possible because the contract knows where the type-erasing boundaries are.

Design decisions that pay off

Generators never see YAML. Their only input is an IR (intermediate representation), normalized after parsing and import resolution. Validation is an independent set of rule functions over the IR. Adding a generator requires no changes to existing code, and extensions like OpenAPI output are just a registry entry.

I invested in byte-for-byte reproduction of the hand-written files. The adoption target was a product already in production; if generated output differed from the existing hand-written files by even one byte, the verification would drown in diffs. The style options that absorb formatting variance and the raw escape hatch exist for this incremental migration — "reproduce the existing file exactly, then switch it over." Migration became a per-file loop of "lean on generation, confirm the diff is zero" instead of a big-bang rewrite.

Regeneration is idempotent. As long as the content doesn't change, files stay byte-for-byte identical, generation timestamp included (generatedAt carries over from the first generation; only updatedAt moves when content changes). CI's --check can mechanically detect contract-code drift precisely because of this idempotency.

The costs

The DSL is itself added complexity. Field options and operations have a ceiling of expressiveness, and every time you hit it you choose between growing the generator and escaping through raw. Debugging generated code is one level more indirect.

Normally "the team has to learn a new YAML DSL" would count as a cost too, but AI has offset it. Load a coding agent with the DSL rules and the product spec, and an instruction like "add an inventory-count field to Product" gets turned into the contract yml edit by the AI. A declarative contract concentrates model definitions in one place with small diffs, which makes it a friendly target for AI as well. If the output is wrong, it shows up in the fbc generate diff, so verification is mechanical. What humans need to master is no longer the DSL grammar but "reading the contract and confirming the intent."

What remains is the expressiveness ceiling and the indirection in debugging — but even minus that, collapsing "add one field" into "add one line to the contract and run fbc generate" is worth a lot. Multi-maintenance drift moved from "something to be careful about" to "something CI detects." When type consistency shifts from human attention to machinery, review attention also shifts — from transcription-checking individual type definitions to the design of the contract itself.

Why not let AI write the type definitions directly?

If AI can write the contract, a further thought suggests itself: hand the LLM the rules and the product spec, let it edit each layer's type definitions directly, and you need neither contract nor generator. If humans never touch the type definitions, doesn't the multi-maintenance chore disappear entirely?

I think this gets the division of labor backwards. LLM output is probabilistic, so direct edits to six representations carry the risk that something is misaligned every single time. More fundamentally, without a contract the mechanical definition of "aligned" ceases to exist. To verify that six representations express the same model, you need their common origin — something equivalent to the contract. --check can detect drift because a deterministic generator can state uniquely what the correct output is; AI's direct edits have no such verifiability.

Review cost changes too. If AI edits six files directly, humans read six files of diffs with suspicion, every time. With the contract approach, humans read only the yml diff, and the rest is derived deterministically. Turning fuzzy specs into a contract is the AI's job; expanding the contract into each representation is the generator's job. It's precisely because the probabilistic layer and the deterministic layer are separated that you can let AI write with confidence.

Where it's published

Published as an npm package. Through the RC series I tightened "the contract is authoritative" (unknown keys and out-of-vocabulary values become errors), verified every feature drift-free in a real project, and released v0.1.0 as the first stable version. The DSL's expressiveness and generator details keep improving with feedback from operation.

npm — npmjs.com/package/firebase-contract
README — github.com/cilly-yllic/my-packages

Originally published at cilly-yllic.github.io.

DEV Community: cilly

Disposable isolated dev environments with Claude Code worktree hooks

The big picture

Principle 1: put the real work in a deterministic CLI; the skill is only a translator

Principle 2: session = the environment's lifetime (SessionStart / SessionEnd)

SessionStart's stdout is injected into context

Trap: SessionEnd fires on /clear too

Principle 3: take over creation itself with the WorktreeCreate hook

Mirror progress to /dev/tty

Leftover branches: present options and abort

Self-replicate the tooling into the worktree

Principle 4: an "environment-variable protocol" for entrances that take no flags

Principle 5: "collision-free" is earned by abandoning fixed values

Make runtime.json the single source of truth

Invariants — guaranteed by the script, never to be broken

Daily flow, and the quietly useful commands

Summary

Syncing what comes after provisioning — Cloudflare DNS, Logto, cert-gated proxy, env bundles

The big picture

The default is "never delete"

The hard part: don't turn the proxy on until the cert exists

Logto: auth config that depends on domains

Env bundles and GPG: keep it off argv

Developers hold no secrets

Decisions that pay off

What I gave up

Runtime and delivery of a multi-service Firebase environment

Runtime: separate writes from reads

Two-layer DB: Core and Service

Two authentication tracks

Delivery: fan out from a monorepo to each environment

Decisions that pay off

Closing

Treating Firestore as a public cache

Where SoT-Firestore hurts

Redefining it as a public cache

Benefits and costs

Which to choose

Provisioning GCP / Firebase environments from a single settings.yml

What gets built

How it gets generated

Design decisions that pay off

What I gave up

Where it's published

Enforce with config, not attention — scope and permission guardrails for coding agents

A session = a declaration of scope + permissions

Build scope as "what isn't opened doesn't exist"

Hard part 1: keep the agent away from its own permission definitions

Hard part 2: double-lock push

Make sessions resumable

Where this stands, and what's next

Generating every Firebase layer’s types from a single contract.yml

The same model, written six times

Write the contract, generate everything else

Firestore is a projection, not "another schema"

Data Connect's Any boundary

Design decisions that pay off

The costs

Why not let AI write the type definitions directly?

Where it's published

Trap: SessionEnd fires on `/clear` too