DEV Community: Aviad Rozenhek

Django Tasks with Due: start simple, grow with Acme Printworks

Aviad Rozenhek — Sat, 24 Oct 2026 06:56:04 +0000

The maintained tutorial and runnable app also live in Due’s documentation.

Using django-due helps you start with a background task you can explain in a few lines. But it can help you grow and become more robust preventing lost or incorrect work in edge cases, that can be very hard to test for or prevent.

This tutorial shows that progression with Due's backend for Django Tasks, installed as django-due. You'll begin with a familiar @task and .enqueue(), then evolve the parts that need stronger guarantees into native Due capabilities. The payoff is practical: a small first feature, application contracts that give you reusable failure tests immediately, and coordination that expands with the product. Always build the contract alongside the feature. It is one of the main reasons to use Due.

Meet Acme Printworks, a fictional company building a Django application for small businesses ordering brochures. Picture its first customer, Willow Cafe, uploading copy for 500 brochures, job 418. Acme initially needs a word count for an estimate. Later, Willow Cafe wants a proof, changes its opening date from June 12 to June 19, approves the revision, and sends it to a printing partner.

One premise matters for the rest of the story: rendering a PDF can take a surprisingly long time. Even a small document can trigger a long render with some inputs, as WeasyPrint's rendering documentation explains. For our story, assume Willow Cafe's troublesome PDF takes 10 minutes to render.

Ten minutes gives the world time to change around a running task. The customer might upload a correction. A rare power outage might stop the machine, or an unexpected server restart might kill the worker seven minutes into the render. None of these needs to happen often for Acme to need an answer: which proof should the customer see, what work is still owed, and who will remove the temporary files? We'll use that same ten-minute window throughout the story.

Each chart uses the same clock as Acme adds features: r17 starts at minute 0, the customer corrects the date and font at minute 2, and the faster r18 publishes June 19 at minute 3. Then we examine two branches. A restart at minute 7 kills the old worker; without that restart, its old render returns at minute 10. These are alternative histories. A killed worker cannot also finish at minute 10. The portal and printer sections show what can still happen outside the restarted process.

We'll follow that same order through each requirement. You'll see the code change, the specific failure it must handle, and a test that makes the failure happen.

At the first stage, many task runners would work. Acme's reason to choose Due is that the same PostgreSQL-backed work model can support the later requirements without Acme inventing its own ownership, recovery, and evidence machinery. Due uses Celery for execution; its advantage here is the application coordination built around it.

Run the whole story

There's instructions at the end of this article on how to run the whole story, and The complete runnable project includes every model, migration, setting, provider simulator, command, and test.

1. Launch: count Willow Cafe's words

The first requirement is modest: count each uploaded revision so Acme can prepare an estimate. Revision 17 says Opening day: June 12, which has four words.

The model keeps each revision separate. All application write paths must treat its text as immutable:

# acme/models.py
class Revision(models.Model):
    job = models.ForeignKey(Job, on_delete=models.PROTECT)
    number = models.PositiveIntegerField()
    text = models.TextField()
    word_count = models.PositiveIntegerField(null=True)

    class Meta:
        constraints = [models.UniqueConstraint(fields=["job", "number"], name="acme_revision_number")]

The task is ordinary Django Tasks code:

# acme/tasks.py
from django.conf import settings
from django.tasks import task

from .models import Revision


@task(queue_name=settings.CELERY_TASK_DEFAULT_QUEUE)
def count_words(revision_id: int) -> int:
    revision = Revision.objects.get(pk=revision_id)
    count = len(revision.text.split())
    Revision.objects.filter(pk=revision_id).update(word_count=count)
    return count

If the worker stores the count and then dies before acknowledging success, another attempt writes the same count. That is why this function is safe to replay.

Commit the revision and its task together:

# acme/services.py
@transaction.atomic
def add_revision(job_id, number, text):
    revision = Revision.objects.create(job_id=job_id, number=number, text=text)
    count_words.enqueue(revision.pk)
    return revision

With Due, enqueueing inside this transaction stores the task in the same PostgreSQL transaction. A rollback removes both. The fast worker notification happens after commit. If that notification disappears, the registered recovery pass can still find the committed task.

Imagine the application loses electricity just after the upload commits. The customer can see their revision, but the fast notification never reached a worker. After power returns, the database still describes the owed word count.

This is a concrete first-day benefit: Acme does not need to build a separate outbox just to keep this task admission consistent with the revision. It depends on both writes using the same database connection.

Select the backend and declare the function safe to repeat:

# project/settings.py
INSTALLED_APPS = ["due.django", "due.django.tasks", "acme.apps.AcmeConfig"]
USE_TZ = True
CELERY_BROKER_URL = "redis://127.0.0.1:56399/0"
CELERY_TASK_DEFAULT_QUEUE = "default"
TASKS = {
    "default": {
        "BACKEND": "due.django.tasks.backend.DueBackend",
        "QUEUES": ["default"],
        "OPTIONS": {"replay_safe_tasks": ["acme.tasks.count_words"]},
    },
}

The complete settings include PostgreSQL credentials for the local Compose service. At this first stage, startup needs one registration:

# acme/apps.py, initial version
from django.apps import AppConfig


class AcmeConfig(AppConfig):
    name = "acme"

    def ready(self):
        from due.django.runtime.registry import configure_durable_work
        from due.django.tasks.runtime import django_tasks_registration

        configure_durable_work(
            [
                django_tasks_registration(recovery_queue="default", cadence_seconds=5),
            ]
        )

Django Tasks supplies the task API; the backend supplies execution and storage behavior. Due's configuration still needs PostgreSQL, Celery, a broker, and Beat. If you already operate that stack, the entry cost is particularly small. The saving demonstrated here is application code and future coordination work, not a claim that every deployment has the lowest infrastructure bill.

Build the first contract now

The allowlist says this task is safe to replay. Make that claim executable. Acme binds three shared pytest-obligation proofs to the actual function and reads the word count from the revision. The call counter checks that both executions really entered the function:

# tests/test_task_contract.py
"""Application-specific replay proofs also apply to the initial Django task."""

import pytest
from due.django.conformance.provider import ProviderProbe
from due.django.testing import hold_nudges
from pytest_obligation.profiles.harmless_replay import REPLAY_SAFETY_PROOFS, ReplaySafeEffect

from acme.models import Job, Revision
from acme.services import add_revision
from acme.tasks import count_words


def prepare():
    with hold_nudges():
        return add_revision(Job.objects.create().pk, 17, "Opening day: June 12").pk


@pytest.mark.django_db(transaction=True)
@pytest.mark.parametrize("proof", REPLAY_SAFETY_PROOFS, ids=lambda proof: proof.__name__)
def test_word_count_contract(proof):
    execute = ProviderProbe(count_words.func, key=lambda revision_id: revision_id)
    proof(
        ReplaySafeEffect(
            name="Acme immutable revision word count",
            prepare=prepare,
            execute=execute,
            observe=lambda revision_id: Revision.objects.get(pk=revision_id).word_count,
            execution_count_for=execute.count,
            expected=4,
        )
    )

python -m pytest -q tests/test_task_contract.py

The suite checks that execution reaches the implementation, produces the expected four-word result, and preserves it on a real second call. Transaction rollback and lost-notification recovery are tested in tests/test_story.py. The shared Django Tasks runtime cannot infer these application-specific promises for you.

2. Customers want proofs, and an old worker finishes late

Revision 17 says June 12 and starts its ten-minute render. Two minutes later, Willow Cafe uploads revision 18 with the corrected opening date, June 19, and a repaired font. Another worker renders that corrected file quickly and publishes it at minute three. At minute ten, the original worker finally returns with the old date.

That is the delayed-success case. In the restart branch, a power outage or server restart kills the original worker at minute seven. Revision 18 is already published, so Due keeps June 19 current and does not resurrect revision 17. If the currently requested proof is still unfinished in another run, recovery starts a fresh attempt after its lease expires. That attempt uses the captured input and reruns rendering; Due does not checkpoint a PDF renderer halfway through its work.

A task that blindly updates job.published_key might put June 12 back in front of the customer. Acme now needs two properties: each revision writes its own immutable output, and only the current requested revision can publish the pointer.

Add a native Due work model for that obligation:

# acme/models.py
class ProofWork(UniverseDurableWork):
    work_owner_field: ClassVar[str] = "owner"
    owner = models.OneToOneField(Job, null=True, on_delete=models.SET_NULL)
    revision_id = models.PositiveBigIntegerField()
    text = models.TextField()

    class Meta:
        indexes, constraints = durable_work_schema("acme_proof")

UniverseDurableWork, durable_work_schema, and the other imports are included in acme/models.py in the project. The work captures its input text; a worker does not fetch whatever copy happens to be current later.

Here is the early proof capability in full:

# acme/stage2.py
"""The early proof implementation, before portal handoff and temporary spooling.

The final application registers effects.publish_proof. This intermediate version
uses the same work schema and is exercised directly by test_stage2.py.
"""

from due.django.public import ReplaySafeEffect

from . import providers
from .models import Job, ProofWork
from .rendering import RENDER_POLICY


class PublishProof(ReplaySafeEffect[Job, ProofWork, str]):
    def perform_effect(self, work):
        return providers.write_proof(work.text, work.provider_idempotency_key())

    def finalize_success(self, work, proof_key):
        Job.objects.filter(pk=work.owner_id).update(published_key=proof_key)


publish_proof = PublishProof.for_owner(
    owner=Job,
    work=ProofWork,
    input_fields=("universe", "revision_id", "text"),
    policy=RENDER_POLICY,
)

providers.write_proof() stores text under an immutable key. Repeating the same key with the same text succeeds; different text under that key is rejected. Due checks the captured revision and ownership before calling finalize_success() inside its settlement transaction.

The producer becomes a service that records the desired proof:

# acme/services.py
def request_proof(revision_id):
    revision = Revision.objects.get(pk=revision_id)
    with publish_proof.atomic(revision.job_id) as pending:
        job = pending.locked_owner
        job.current_revision = revision
        job.published_key = ""  # Approval waits for this revision's proof.
        job.save(update_fields=["current_revision", "published_key"])
        return pending.request_work(
            ProofWork(
                revision_id=revision.pk,
                text=revision.text,
                universe="acme",
            )
        )

Add a native application contract as soon as you add this capability. Acme binds real proof requests, independently stored proof bytes, provider failures, and superseding revisions; stage 6 shows the final contract and generated suite.

The word-count task stays exactly as it was. Proof publication gets the richer API because it has a richer requirement. There is no need to force every background function into the same abstraction.

Try the specific regression:

python -m pytest -q tests/test_story.py::test_old_proof_cannot_replace_new_proof

The test compresses that ten-minute window: revision 18 finishes while revision 17 is returning from its renderer. The executable provider renders text previews and injects the relevant ordering and interruptions, so running the example does not require waiting ten minutes. The test reads the published proof text and requires June 19. Checking only a task's success status would miss the actual bug.

The runnable app gives proof rendering an explicit budget: 11 minutes to the soft worker limit, 12 to the hard limit, and a 15-minute ownership lease. Both proof implementations share this policy:

# acme/rendering.py
"""Give the story's ten-minute render room to finish and settle."""

from datetime import timedelta

from due.django.public import DurableWorkPolicy

RENDER_SOFT_LIMIT = 11 * 60
RENDER_HARD_LIMIT = 12 * 60
RENDER_POLICY = DurableWorkPolicy(retention=None, lease_duration=timedelta(minutes=15))

Register the final proof capability with the matching execution limits. This entry in AcmeConfig.ready() replaces its default entry; the other capabilities keep their own budgets:

# acme/apps.py, inside ready()
from .rendering import RENDER_HARD_LIMIT, RENDER_SOFT_LIMIT

DurableWorkRegistration(
    name="acme_proof",
    capability=publish_proof,
    queue=settings.CELERY_TASK_DEFAULT_QUEUE,
    cadence_seconds=5,
    execution_soft_time_limit=RENDER_SOFT_LIMIT,
    execution_time_limit=RENDER_HARD_LIMIT,
)

For a claim made at minute 0 with no renewal, that lease expires at minute 15. A minute-7 crash therefore does not cause an immediate replacement render. Once recovery is running and the work is eligible, a later tick can dispatch a new attempt. With r18 already settled at minute 3, there is no current proof left to render. Independent cleanup can still be owed. The five-second cadence is a polling interval, not a completion deadline. Set a real renderer's bounded call timeout below the soft limit; the text simulator has no ten-minute delay. See execution budgets.

3. The approval portal can be overwritten remotely

Acme adds a hosted approval portal. Its API accepts PUT(job_id, proof_key), but provides no conditional version check. For this stage, suppose an earlier proof, r16, already exists with June 12. Its portal request is held in flight before our clock starts. While r17 is rendering, the minute-2 correction produces r18 and its portal update at minute 3. Restarting Acme at minute 7 cannot retract the older HTTP request. If that request lands at minute 10, the portal shows June 12 again, even though the killed r17 renderer never returned.

The database fence from stage 2 protects Acme's local pointer. The portal needs repair after an escaped old write. Model that requirement with a Projection:

# acme/models.py
class PortalWork(UniverseDurableWork):
    work_owner_field: ClassVar[str] = "owner"
    owner = models.OneToOneField(Job, null=True, on_delete=models.SET_NULL)
    proof_key = models.CharField(max_length=200)

    class Meta:
        indexes, constraints = durable_work_schema("acme_portal")

# acme/effects.py
class PortalProjection(Projection[Job, PortalWork]):
    def write_projection(self, work):
        providers.put_portal(work.owner_id, work.proof_key)

    def on_projected(self, work):
        Job.objects.filter(pk=work.owner_id).update(portal_failed=False)

    def finalize_retry(self, work, error):
        if work.state == DurableWorkState.EXHAUSTED:
            Job.objects.filter(pk=work.owner_id).update(portal_failed=True)


project_portal = PortalProjection.for_owner(
    owner=Job,
    work=PortalWork,
    input_fields=("universe", "proof_key"),
    policy=DurableWorkPolicy(retention=None, repair_interval=timedelta(seconds=5)),
)

When proof publication settles, also admit the desired portal update. Replace the proof capability's finalize_success() with this method:

# Method on PublishProof, in acme/effects.py
def finalize_success(self, work, proof_key):
    Job.objects.filter(pk=work.owner_id).update(published_key=proof_key)
    with project_portal.atomic(work.owner_id) as pending:
        pending.request_work(PortalWork(proof_key=proof_key, universe="acme"))

The complete class appears in stage 5 below. The pointer and portal obligation commit together. A lost follow-up notification leaves a recoverable obligation.

Due's projection machinery retains evidence about older calls and tracks repair that is still owed. After a late write, recovery reapplies the current desired proof. The portal can briefly show the old value; the promise here is eventual repair, with the necessary history retained.

Run the test that actually puts the wrong proof back on the portal:

python -m pytest -q tests/test_story.py::test_late_portal_write_is_repaired

It first verifies that June 12 overwrote June 19, then runs recovery and requires the portal to show June 19 again. Acme has gained remote repair without writing its own stale-attempt ledger and reconciliation scheduler.

4. A timeout after ordering 500 brochures

Willow Cafe approves revision 18 after it publishes at minute 3. Acme submits 500 copies to a printing partner just before minute 7. The printer creates the order and commits it. Then the minute-7 restart kills Acme's waiting client before it records the reply. A power outage at the printer's network gateway would leave Acme with the same uncertainty. At minute 10, the question is whether the order was accepted, regardless of whether the obsolete r17 render survived.

This provider creates a new order on every POST. Its reference can be searched later, but it is not an idempotency key. Blindly repeating the request might buy another 500 brochures.

The simulator makes that failure real:

# acme/providers.py
@dataclass(frozen=True)
class PrintReceipt:
    order_id: int
    reference: str
    proof_key: str
    quantity: int


def submit_print(reference, proof_key, quantity):
    with database() as db:
        cursor = db.execute(
            "INSERT INTO orders(reference,proof_key,quantity) VALUES (?,?,?)",
            (reference, proof_key, quantity),
        )
        assert cursor.lastrowid is not None
        receipt = PrintReceipt(cursor.lastrowid, reference, proof_key, quantity)
        lost = db.execute("DELETE FROM faults WHERE name='print_reply'").rowcount
    # The provider has COMMITTED. Rolling back Django cannot undo this order.
    if lost:
        raise TimeoutError("Printer accepted the order; response was lost")
    return receipt

The timeout happens after an independent provider commit. A rollback in Acme's PostgreSQL transaction cannot undo that order.

Store the approved purchase intent separately from the mutable job:

# acme/models.py
class PrintOrder(models.Model):
    reference = models.UUIDField(default=uuid4, unique=True, editable=False)
    revision = models.ForeignKey(Revision, on_delete=models.PROTECT)
    proof_key = models.CharField(max_length=200)
    quantity = models.PositiveIntegerField(default=500)
    status = models.CharField(max_length=20, default="pending")
    provider_order_id = models.PositiveBigIntegerField(null=True)


class PrintWork(ObservedExternalOperationWork):
    work_owner_field: ClassVar[str] = "owner"
    owner = models.OneToOneField(PrintOrder, null=True, on_delete=models.SET_NULL)
    reference = models.UUIDField()
    proof_key = models.CharField(max_length=200)
    quantity = models.PositiveIntegerField()

    class Meta:
        indexes, constraints = durable_work_schema("acme_print")
        indexes.append(observation_index("acme_print_observe"))


class PrintEvidence(StoredAppliedEffectEvidence):
    pass

Use an ObservedExternalOperation to distinguish uncertainty from permission to retry:

# acme/effects.py
mirror = StatusMirror(lambda work: PrintOrder.objects.filter(pk=work.owner_id))


class OrderPrinting(ObservedExternalOperation[PrintOrder, PrintWork, providers.PrintReceipt]):
    observation_interval = timedelta(seconds=5)
    evidence_store = JsonAppliedEffectEvidenceStore(PrintEvidence, providers.PrintReceipt)
    on_applied = mirror.outcome(
        lambda work, receipt: {
            "status": "accepted",
            "provider_order_id": receipt.order_id,
        }
    )
    on_unknown = mirror.outcome({"status": "unknown"})
    on_retry = mirror.outcome({"status": "retrying"})
    on_exhausted = mirror.outcome({"status": "stopped"})
    on_terminal = mirror.outcome({"status": "stopped"})

    def perform_effect(self, work):
        try:
            return providers.submit_print(str(work.reference), work.proof_key, work.quantity)
        except providers.PrinterRejected as error:
            # Only a definite refusal before acceptance permits retrying a purchase.
            raise EffectNotAppliedError(str(error)) from error

    def observe_effect(self, work):
        receipt = providers.observe_print(str(work.reference))
        if receipt is not None and (
            receipt.reference != str(work.reference)
            or receipt.proof_key != work.proof_key
            or receipt.quantity != work.quantity
        ):
            raise ValueError("Receipt does not match the captured print request")
        return receipt


order_printing = OrderPrinting.for_owner(
    owner=PrintOrder,
    work=PrintWork,
    input_fields=("universe", "reference", "proof_key", "quantity"),
    policy=POLICY,
)

POLICY is DurableWorkPolicy(retention=None) in this sample. The capability retains the applied receipt in PrintEvidence. Observation checks the reference, exact proof key, and quantity before treating the receipt as evidence for this request.

The approval service locks the job and rejects a stale proof approval:

# acme/services.py
@transaction.atomic
def approve_print(job_id, expected_proof_key, quantity=500):
    job = Job.objects.select_for_update().get(pk=job_id)
    if not job.published_key or job.published_key != expected_proof_key:
        raise ValueError("Proof changed; review the current proof before approving")
    order = PrintOrder.objects.create(
        revision=job.current_revision,
        proof_key=job.published_key,
        quantity=quantity,
    )
    with order_printing.atomic(order.pk) as pending:
        pending.request_work(
            PrintWork(
                reference=order.reference,
                proof_key=order.proof_key,
                quantity=order.quantity,
                universe="acme",
            )
        )
    return order

Once admitted, this print request captures the approved proof. Later edits to the job do not change the purchase that was approved. Each call creates a distinct purchase intent; an HTTP endpoint should also deduplicate repeated browser submissions.

After the simulated timeout, the order becomes unknown. Recovery searches for a correlated receipt and records accepted, while the provider's order count stays one. A missing receipt alone does not authorize another POST. Also, “accepted” says nothing yet about printing or shipping.

Here is the application test, including its independent provider-side count:

# tests/test_story.py
def test_accepted_print_with_lost_reply_is_observed_without_resubmit():
    job = published()
    providers.lose_next_print_reply()
    with hold_nudges():
        order = approve_print(job.pk, job.published_key)
        with pytest.raises(EffectOutcomeUnknownError):
            order_printing.attempt_execution(order.printwork.pk)
    order.refresh_from_db()
    assert order.status == "unknown"
    assert providers.print_count(str(order.reference)) == 1
    with WorkTableDelivery(order_printing).session() as delivery:
        delivery.recover()
    order.refresh_from_db()
    assert order.status == "accepted"
    assert providers.print_count(str(order.reference)) == 1
    receipt = providers.observe_print(str(order.reference))
    assert receipt is not None
    assert receipt.order_id == order.provider_order_id

Now consider a different incident: the printer is out of ink and explicitly rejects the request before accepting an order. The adapter raises PrinterRejected; OrderPrinting translates only that definite refusal into EffectNotAppliedError. Due can retry under its policy after supplies return. The contract exercises both histories:

# tests/contracts/printer.py
rejected = SEAM.rejection(
    lambda provider, work: provider.submit.reject(lambda: providers.PrinterRejected("Out of ink; order NOT accepted")),
    lambda provider, work: "retrying",
    WorkFailureDisposition.RETRYABLE,
)


@contextmanager
def lost_response(provider):
    with (
        provider.submit.lose_response(lambda: TimeoutError("Printer UPS failed after acceptance; reply lost")),
        patch.object(providers, "receipts_visible", False),
    ):
        yield


uncertain = SEAM.outcome(lambda provider, work: lost_response(provider), lambda provider, work: "unknown")


@contextmanager
def observation():
    with uncertain() as scenario:

        def reveal():
            providers.receipts_visible = True
            return providers.print_receipt(str(scenario.work.reference))

        yield ObservationExample(
            delivery=replace(scenario, expected="accepted"),
            reveal=reveal,
            observation_calls=lambda: calls.get().observe.count(str(scenario.work.reference)),
        )

An ink shortage after acceptance is a fulfillment delay. Acme must follow the existing order's production status; submitting another order would compound the problem. Due's acceptance receipt does not mean paper was printed or shipped.

That is a strong reason to choose Due when your Django app makes consequential external requests: uncertainty becomes a state you can inspect and resolve with evidence, using a different policy from an ordinary replayable task.

5. Rendering gets temporary storage, and workers can die

Acme's renderer now creates temporary spool data during those ten minutes of preparing a proof. Suppose a power outage or unexpected server restart stops it at minute seven, after it has written a multi-gigabyte spool file. Deleting that file only in a Python finally block is insufficient: the worker is gone before the block can run. A week of stranded files can leave too little space for the next customer. The corrected r18 proof published at minute 3 remains valid; cleaning r17's temporary files must not delete it. After the old attempt's reservation expires, Due can recover its independent cleanup. It removes disposable bytes and keeps checking until the renderer provides completion evidence that rules out later writes.

Reserve a cleanup obligation before calling the renderer:

# acme/models.py
class CleanupWork(UniverseDurableWork):
    spool_key = models.CharField(max_length=200)

    class Meta:
        indexes, constraints = durable_work_schema("acme_cleanup")

# acme/effects.py
class SpoolCleanup(IndependentCompensation[ProofWork, CleanupWork]):
    def capture(self, producer):
        return CleanupWork(spool_key=str(producer.token), universe="acme")

    def compensate(self, work):
        return providers.cleanup(work.spool_key)


cleanup_spool = SpoolCleanup(
    producer_model=ProofWork,
    model=CleanupWork,
    nudge=registered_nudge(CleanupWork),
    policy=DurableWorkPolicy(retention=None, max_rearms=None),
    inspection_interval=timedelta(seconds=5),
)

The final acme/effects.py imports RENDER_POLICY from .rendering, just as stage 2 does. The cleanup identity uses the producer's attempt token, so separate attempts do not share temporary storage. The renderer keeps a terminal completion record. After that record exists, the attempt cannot write more spool data.

Cleanup checks that evidence before reporting completion:

# acme/providers.py
def cleanup(spool_key):
    with database() as db:
        row = db.execute("SELECT finished FROM renders WHERE key=?", (spool_key,)).fetchone()
        if row is None:
            return False  # Absence is not proof that a delayed write cannot arrive.
        db.execute("UPDATE renders SET spool=NULL WHERE key=?", (spool_key,))
    return bool(row[0])

An absent object does not prove that an earlier write cannot arrive later. Here, a missing completion record keeps cleanup owed. A real renderer needs an equally explicit completion or cancellation contract.

Now replace the early ReplaySafeEffect subclass with OwnedDurableWorkCapability, whose apply() receives the execution context needed to reserve cleanup. This is the final proof capability:

# acme/effects.py
def render_proof(work):
    return providers.render(work.text, work.provider_idempotency_key(), str(work.fencing_token))


class PublishProof(OwnedDurableWorkCapability[Job, ProofWork, str]):
    def apply(self, work, context):
        with cleanup_spool.record_cleanup_before_call(context) as output:
            key = render_proof(work)
            if providers.cleanup(str(work.fencing_token)):
                output.confirm_compensated()
            return key

    def finalize_success(self, work, proof_key):
        Job.objects.filter(pk=work.owner_id).update(published_key=proof_key, proof_failed=False)
        # Both the pointer and the portal obligation commit in this settlement.
        with project_portal.atomic(work.owner_id) as pending:
            pending.request_work(PortalWork(proof_key=proof_key, universe="acme"))

    def finalize_retry(self, work, error):
        if work.state == DurableWorkState.EXHAUSTED:
            Job.objects.filter(pk=work.owner_id).update(proof_failed=True)


publish_proof = PublishProof.for_owner(
    owner=Job,
    work=ProofWork,
    input_fields=("universe", "revision_id", "text"),
    policy=RENDER_POLICY,
)

The ordinary path renders, removes the temporary spool, and acknowledges compensation. If the process dies after rendering, the separately committed cleanup obligation remains. Recovery can clean it after its reservation expires. The immutable proof itself is retained.

The same class also keeps stage 3's transactional portal handoff. This is how the example grows: the publication input and settlement remain recognizable, while the provider boundary gains the specific protection it now needs.

# acme/apps.py
from django.apps import AppConfig
from django.conf import settings


class AcmeConfig(AppConfig):
    name = "acme"

    def ready(self):
        from due.django.runtime.registry import (
            DurableWorkRegistration,
            configure_durable_work,
        )
        from due.django.tasks.runtime import django_tasks_registration

        from .effects import (
            cleanup_spool,
            order_printing,
            project_portal,
            publish_proof,
        )
        from .rendering import RENDER_HARD_LIMIT, RENDER_SOFT_LIMIT

        configure_durable_work(
            [
                django_tasks_registration(recovery_queue=settings.CELERY_TASK_DEFAULT_QUEUE, cadence_seconds=5),
                DurableWorkRegistration(
                    name="acme_proof",
                    capability=publish_proof,
                    queue=settings.CELERY_TASK_DEFAULT_QUEUE,
                    cadence_seconds=5,
                    execution_soft_time_limit=RENDER_SOFT_LIMIT,
                    execution_time_limit=RENDER_HARD_LIMIT,
                ),
                *[
                    DurableWorkRegistration(
                        name=name,
                        capability=capability,
                        queue=settings.CELERY_TASK_DEFAULT_QUEUE,
                        cadence_seconds=5,
                    )
                    for name, capability in [
                        ("acme_portal", project_portal),
                        ("acme_print", order_printing),
                        ("acme_cleanup", cleanup_spool),
                    ]
                ],
            ]
        )

Each registration gives recovery an owner, queue, and cadence. The project's Celery setup uses the same Django settings and database. run_demo.py starts both the worker and Beat, including these recovery schedules.

6. Keep the failure guarantees executable

Acme changes its printer adapter six months later. A developer sees a timeout and adds a retry. The happy-path demo still works, but the next power failure could order a second 500 brochures. A contract should catch that before deployment.

Always build the application contract. Due and pytest-obligation provide reusable failure histories and assertions. You supply the application meaning: how work is admitted, which provider call matters, what a refusal means, and what the customer should actually see. You get valuable runnable tests without designing every lease, ownership, recovery and replay interleaving yourself.

Start by configuring the test host:

# tests/conftest.py
import pytest
from due.django.conformance.host import work_table_host
from pytest_obligation import configure

configure(work_table_host(production_packages={"acme"}))


@pytest.fixture(autouse=True)
def isolated_provider(settings, tmp_path):
    settings.PROVIDER_DB = tmp_path / "provider.sqlite3"

For proof publication, the seam observes the published bytes and independently stored provider bytes. ProviderProbe wraps the real local provider transaction; its refusal control simulates an unavailable renderer while preserving real Due execution and PostgreSQL settlement:

# tests/contracts/proof.py
SEAM = ProviderSeam(
    environment=environment,
    make_work=make_proof,
    observe=lambda provider, work: proof_contents(work),
    delivered=lambda provider, work: COPY,
    provider_state=lambda provider, work: provider_contents(work),
    provider_expected=lambda provider, work: COPY,
    calls=lambda provider: provider.render.total,
    calls_for=lambda provider, work: provider.render.count(work.provider_idempotency_key()),
    refuse=lambda provider: provider.render.reject(lambda: OSError("Renderer power supply unavailable")),
)

The helpers live in tests/contracts/support.py. They call add_revision and request_proof, count actual provider I/O, and read the provider's separate SQLite database. The remaining bindings connect terminal outcomes, supersession, admission rollback, and cleanup composition:

# tests/contracts/proof.py
EXAMPLES = seam_examples(
    publish_proof,
    SEAM,
    replay=SEAM.replay("Acme immutable rendering", render_proof),
    environment=environment,
    terminal=lambda: TerminalExample(
        observe=lambda work: Job.objects.get(pk=work.owner_id).proof_failed,
        rearm=lambda work: retry_proof(work.owner_id),
    ),
    snapshot=snapshot,
    compensation=compensation,
    producers={"request proof": producer},
    admission_failures={"partial proof request": admission_failure},
    convergence_families={
        family: NotApplicable(
            "Immutable proof keys keep old bytes separate; the current revision's fenced pointer is the only mutable result. There is no merge or dependency gate."
        )
        for family in ConvergenceFamily
        if family.name != "STALE_SNAPSHOTS"
    },
)

For example, supersession changes the desired proof through the production service:

# tests/contracts/proof.py
def snapshot():
    work = make_proof()
    return SupersessionExample(
        work=work,
        change=lambda: request_proof(add_revision(work.owner_id, 19, NEW_COPY).pk),
        observe=lambda: proof_contents(work),
    )

The complete proof.py contains the producer and compensation helpers referenced above. portal.py, printer.py, and cleanup.py bind the other capabilities. The cleanup lifecycle fixture begins with an owed row and real disposable bytes; the producer's composition histories and the subprocess test separately prove that cleanup was admitted before rendering. The bindings do not implement Due's recovery or settlement logic.

These four declarations generate tests from the registered production capabilities and their actual policies:

# tests/test_contracts.py
"""These classes collect real tests, selected by each capability's policies."""

from due.django.conformance.suite import effect_contract_suite

from acme.effects import cleanup_spool, order_printing, project_portal, publish_proof

from .contracts import cleanup, portal, printer, proof


@effect_contract_suite(publish_proof, examples=proof.EXAMPLES)
class TestProofContract:
    pass


@effect_contract_suite(project_portal, examples=portal.EXAMPLES)
class TestPortalContract:
    pass


@effect_contract_suite(order_printing, examples=printer.EXAMPLES)
class TestPrinterContract:
    pass


@effect_contract_suite(cleanup_spool, examples=cleanup.EXAMPLES)
class TestCleanupContract:
    pass

Run them and keep the evidence:

python -m pytest -q -p due.django.conformance.reporting \
  --due-work-require-assessed \
  --due-work-profile-report=profiles.json \
  --durable-work-report=effects.json

The current example runs 286 tests. Of those, 270 are generated native contract tests and three are the first task's shared replay proofs. Ten scenario tests cover the application's specific story, including a real subprocess exit; one budget check verifies that the registered worker allows the ten-minute render; two enrollment guards check that native contracts cannot disappear unnoticed.

Contract	Generated checks	Customer promise exercised
Proof publication	66	Current proof wins; failed rendering remains recoverable; cleanup survives the producer
Approval portal	70	Late remote writes are repaired to the current proof
Print ordering	80	Definite refusal can retry; ambiguous acceptance requires observation; receipts repair local state
Temporary spool cleanup	54	Cleanup survives loss of ownership and retries until it has completion evidence

The actual policies determine the applicable proofs. Acme also supplies explicit reasons for inapplicable families. A green contract says these application bindings passed their declared histories; it cannot establish undocumented behavior of a real printing vendor.

Keep an inventory independent of the test declarations:

# tests/test_enrollment.py
"""A missing or disabled contract must not turn into a smaller green suite."""

from pathlib import Path

import pytest
from due.django.conformance.enrollment import assert_complete_enrollment, discover_enrollment
from due.django.runtime.registry import installed
from due.django.tasks.runtime import TaskCapability


def native_capabilities():
    # Inventory comes from production registration, independently of test classes.
    # Django Tasks has a shared runtime capability; its application task bodies
    # need their own replay/transaction tests (see test_story.py).
    return {
        entry.name: entry.capability
        for entry in installed.get().values()
        if not isinstance(entry.capability, TaskCapability)
    }


def test_every_native_capability_has_a_contract():
    assert_complete_enrollment(native_capabilities(), discover_enrollment(Path(__file__).parent))


def test_deleted_contract_is_rejected():
    enrolled = discover_enrollment(Path(__file__).parent)
    assert len(enrolled) == 4
    for omitted in enrolled:
        with pytest.raises(AssertionError, match="conformance enrollment"):
            assert_complete_enrollment(native_capabilities(), [entry for entry in enrolled if entry != omitted])

CI additionally uses Due's scripts/check_adoption_report.py to require every expected proof to be collected, selected, executed and passed for all four named capabilities. --due-work-require-assessed catches missing bindings; the inventory and report gates catch missing suites or filtered execution. Do not replace those checks with a test-count assertion.

For the physical process-death scenario:

python -m pytest -q tests/test_story.py::test_independent_cleanup_survives_process_death

That test compresses a process-death history: it runs a separate Python process, commits the renderer output and calls os._exit(79) before publication. It covers death after provider completion; the generated compensation histories also cover cleanup while completion is unresolved. Together with the supersession test, these exercise the distinct boundaries in our minute-7 story, without claiming a real ten-minute PDF run. Its parent verifies the crash point, recovers cleanup, checks the spool bytes disappeared, and recovers publication. run_demo.py separately exercises Redis, Celery workers and Beat, so the contract suite and the live journey cover different parts of the integration.

When Acme adds a provider, update its contract in the same change. A new lookup, idempotency or completion promise should have a binding and an observable verdict. This is how the initial small task grows into a system whose reliability claims remain reviewable and runnable.

When should you choose Due over the alternatives?

Choose Due when you expect background work to become part of your product's correctness. Acme's roadmap is a good example: edits can overtake each other, remote writes can arrive late, and a repeated request can place a second physical order. Due gives those requirements explicit models and reusable recovery behavior.

Acme's requirement	What Due lets the application reuse
Commit a revision and its task together	PostgreSQL task admission and scheduled recovery of lost notifications
Publish the latest requested proof	Captured inputs, revision ownership, and fenced local settlement
Repair an unconditional remote portal	Retained attempt evidence and desired-state projection repair
Avoid repeating an uncertain purchase	An unknown state, correlated receipts, and observation before further action
Finish after a process dies	Durable follow-up admission and independent cleanup obligations
Preserve those guarantees during changes	Application contracts generate policy-specific failure tests; enrollment and report gates prevent silent coverage loss

If your app only needs a few disposable background jobs, a simpler worker may be enough. Celery also supplies broad task execution features and is Due's worker engine here. The reason to add Due is that you would otherwise have to build and maintain the coordination in this table yourself, or integrate another system that provides it.

For Acme, that investment starts small: keep the estimator's @task, configure one backend, and commit the task with the revision. As requirements grow, add the native capability that matches the problem. There is no seperate migration of every task, and no need to anticipate every future workflow on day one.

Get the complete Acme Printworks project · Due capabilities and contracts

Run the whole story

The complete runnable project includes every model, migration, setting, provider simulator, command, and test. The snippets above explain its evolution. The downloadable application contains the final version; acme/stage2.py also preserves and tests the intermediate proof implementation.

Use Python 3.14 and Docker Compose on Linux, macOS, or WSL:

git clone https://github.com/gigaverse-app/due.git
cd due/examples/acme_printworks
python3.14 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
docker compose up -d --wait
python run_demo.py
python -m pytest -q -p due.django.conformance.reporting --due-work-require-assessed

The demo applies migrations, starts a Celery worker and Beat, runs the order, then stops those processes. The first run prints:

Acme Printworks job 418: Willow Cafe, 500 brochures
1. Estimate: 4 words, recovered after a lost notification
2. Proof: revision 18, June 19
3. Portal: displays revision 18
4. Printer: accepted 500 copies; lost reply recovered; exactly one order
5. Cleanup: temporary spool removed; immutable proof retained
6. Run pytest -q for late writes, process death, and replay contracts

Subsequent runs create a new job. Run docker compose down when finished. These are disposable local development services. The README also explains how to use existing dedicated PostgreSQL and Redis instances.

The providers are local simulators with independent SQLite commits. Django and Due use PostgreSQL. The proof is a text preview, keeping the example small; no PDF library, printer account, or API key is needed. We deliberately give the portal and printer difficult contracts so the failure cases are reproducible.

Stop writing platform checks around uvloop

Aviad Rozenhek — Mon, 28 Sep 2026 09:08:01 +0000

If you write asyncio code that has to run on both Windows and Linux, you've probably written this:

import sys

if sys.platform == "win32":
    import winloop as fastloop
else:
    import uvloop as fastloop

fastloop.run(main())

It's four lines. It works. Nobody thinks about it the first time.

But it doesn't stay four lines, and it doesn't stay in one place.

This post is about that branch: why it keeps showing up, what it usually leaves out, and winuvloop, the small package I wrote so it lives in one place.

TL;DR

uvloop isn't the Windows backend. winloop is. Code that runs on both ends up picking one at runtime, at every entry point.
The hand-written branch usually leaves out install markers, a readable error on PyPy, the 3.16 policy change, and a way to log which loop you got.
winuvloop is that branch plus those details, packaged once. It doesn't make anything faster. uvloop and winloop do.
If you only target one OS, you don't need it.

Why the branch exists

uvloop is the standard high-performance asyncio event loop on Linux and macOS. It isn't the Windows backend, so import uvloop fails on Windows.

winloop fills that gap. It provides a uvloop-compatible API for Windows.

So a project whose developers are on Windows laptops and whose production runs on Linux needs both, and it has to pick one at runtime. That's the setup I kept running into: developing on Windows, deploying to Linux.

The upstream projects publish their own numbers for why you'd bother. uvloop reports making asyncio 2-4x faster on its echo-server benchmarks. winloop reports this TCP connection benchmark:

Event loop policy (winloop's benchmark)	Time
`WinLoopPolicy`	0.493s
`WindowsProactorEventLoopPolicy`	2.510s
`WindowsSelectorEventLoopPolicy`	2.723s

Those are upstream figures for specific workloads, not a promise for your app. Measure your own.

What the hand-written version leaves out

The if sys.platform branch handles the import. A real cross-platform setup needs a few more things.

1. Dependency markers. You don't want pip installing uvloop on Windows or winloop on Linux, so your pyproject.toml needs environment markers:

dependencies = [
  "uvloop; sys_platform != 'win32' and platform_python_implementation == 'CPython'",
  "winloop; sys_platform == 'win32' and platform_python_implementation == 'CPython'",
]

The platform_python_implementation part is there because both backends are native CPython extensions. Without it, installing on PyPy tries to pull in a backend that doesn't support PyPy.

2. Every entry point. The branch gets copied into the CLI, the worker, the benchmark script, the README example, and the test helper. In my own projects I found near-identical copies of it in several places. Each copy is one more place for things to drift.

3. A useful error. When the backend isn't installed (on PyPy, say, or when someone installed with --no-deps), you get a bare ModuleNotFoundError: No module named 'uvloop'. That tells the reader what failed and nothing about why.

4. The policy API is going away. A lot of code calls uvloop.install() or asyncio.set_event_loop_policy(...) so a framework picks up the loop. asyncio deprecated its event-loop policy system in Python 3.14 and will remove it in 3.16. The replacement is asyncio.run(..., loop_factory=...). Hand-written branches that call install() will need to change.

5. Knowing which loop you actually got. When someone files a bug, "which event loop were you on, and which version?" should take one line to answer.

None of this is hard. It's just easy to get slightly wrong in five places.

What winuvloop does

winuvloop is that branch plus those details, packaged once.

The runtime module is small: platform detection, a clear error, re-exports, and typing stubs. It doesn't vendor or patch either loop.

import winuvloop


async def main() -> int:
    ...
    return 0


raise SystemExit(winuvloop.run(main()))

On Windows that runs on winloop. On Linux, macOS, and other POSIX systems it runs on uvloop.

What's inside:

Dependency markers. winuvloop's own dependencies are the markers shown above: uvloop on non-Windows CPython, winloop on Windows CPython. pip install winuvloop or uv add winuvloop pulls in only the backend for the current platform.
Direct aliases, not wrappers. winuvloop.run, winuvloop.new_event_loop and winuvloop.Loop are the backend's own objects, so on Linux winuvloop.Loop is uvloop.Loop. There's no wrapper layer to debug. Any other attribute is delegated to the selected backend module.
A versioned policy API. install() and EventLoopPolicy still work for code that needs a global policy. For example, the README shows launching Uvicorn with loop="asyncio" after winuvloop.install(). Both come straight from the backend. Since 0.2.5, winuvloop lists them as public only on Python < 3.16 and avoids loading them at import time on 3.14.
A real error on unsupported interpreters. If the backend is missing, the import error names the selected backend, the platform, and the Python implementation, and says the backends target CPython. On PyPy you get told why instead of just what.
Diagnostics. backend_name() and backend_version(), shown below.
Typing. It ships py.typed and stubs for the public API.
CI on all three OSes. Linux, macOS and Windows, with unit tests that mock both backends and smoke tests that call winuvloop.run() on the real one.

The diagnostics take one line each:

import winuvloop

print(winuvloop.backend_name())     # "uvloop" or "winloop"
print(winuvloop.backend_version())

They also make cross-platform tests simpler. Instead of branching on the OS all over your test suite, you assert the backend:

import sys

import winuvloop


def test_optimized_backend_is_available() -> None:
    expected = "winloop" if sys.platform == "win32" else "uvloop"
    assert winuvloop.backend_name() == expected
    assert winuvloop.backend_version() is not None

For frameworks that create their own loop, install before the framework starts:

# serve.py
import uvicorn

import winuvloop

winuvloop.install()

uvicorn.run("myapp:app", host="127.0.0.1", port=8000, loop="asyncio")

When not to use it

I'd skip winuvloop in these cases:

You only target one OS. Use uvloop (Linux/macOS) or winloop (Windows) directly. A selector buys you nothing.
You need backend-specific APIs and don't want a layer in between.
You're debugging an event-loop bug. Take out every wrapper, winuvloop included, and import the backend directly. If the bug still reproduces, it belongs upstream (uvloop issues, winloop issues), not in winuvloop.
You run on PyPy. Neither backend supports it. winuvloop only fails more clearly.
Your deployment platform already configures the loop. Use the platform's own setting.

One more honest caveat: most of winuvloop's maturity is really uvloop's and winloop's. It's marked Beta on PyPI. The selector itself is small, but runtime behavior is entirely the backend's.

Is anyone using it?

According to pypistats.org, winuvloop had 6,837 downloads in the last month (as of 2026-09-28).

Download counts include CI and mirrors, so I read that as "some projects depend on it", not as a user count. I haven't promoted it anywhere until now, so that usage is organic.

Bottom line

winuvloop doesn't make anything faster. The speed comes from uvloop and winloop.

What it removes is a small branch that gets copied into every entry point, plus the details that usually get left out of it: install markers, a readable error on PyPy, the 3.16 policy change, and a way to log which loop you're on.

If your asyncio code only runs on one OS, you don't need it. If it runs on both, give it a try:

pip install winuvloop

Source, examples and issues: github.com/aviadr1/winuvloop. Happy to hear feedback in the issues. I'd especially like to hear from anyone running winloop in production on Windows.

Keep Every LangSmith Trace Without the 10 Retention Bill

Aviad Rozenhek — Fri, 21 Aug 2026 00:38:17 +0000

LangSmith is excellent for debugging live AI systems. But keeping every trace in its extended-retention tier can turn observability into a surprisingly large line item.

Today we merged a new archive workflow into langsmith-cli that changes that tradeoff: keep LangSmith for live debugging, continuously archive verified traces to organization-owned private S3, and query the retained Parquet directly with DuckDB.

In other words, you can preserve your complete trace history without placing every trace on LangSmith's extended-retention tier.

The cost-overrun risk

LangSmith currently documents two trace-retention tiers:

Tier	Retention	Published trace price
Base	14 days	0.05¢
Extended	400 days	0.50¢ total

The 0.45¢ extended-retention upgrade makes an extended trace cost 10× as much as a base trace.

That difference becomes material at production volume:

Monthly traces	Base, 14 days	Extended, 400 days	Added retention cost
100,000	$50	$500	$450
1,000,000	$500	$5,000	$4,500
10,000,000	$5,000	$50,000	$45,000

These examples use the published per-trace rates before free allowances, plan terms, negotiated pricing, or taxes. Always check the official LangSmith usage and billing documentation before making budget decisions.

There is another subtle risk: online evaluators and automation rules can upgrade matching traces when retention extension is enabled. A rule that matches one run upgrades the whole trace, and a thread-level rule can upgrade every trace in that thread. LangSmith currently enables retention extension by default for new online evaluators and automation rules, although you can opt out.

At scale, an innocent-looking evaluator or rule can therefore create a much larger bill than expected.

The new `langsmith-cli` archive workflow

The new workflow separates live observability from long-term retention:

LangSmith live traces (14 days)
        │
        ├── D+2 primary export ───────┐
        └── D+12 reconciliation ──────┤ deduplicate by run ID
                                      ▼
                            private S3 / Parquet
                                      │
                                      ▼
                         runs ... --archive (DuckDB)

The D+2 export captures traces after normal late-arriving data has settled. The D+12 reconciliation pass catches delayed updates before the 14-day base-retention window closes. Both passes deduplicate by run ID, so retries are safe and the archive converges on the latest exported data.

The result is long-term trace history in storage your organization owns and controls.

Route projects to private S3

Projects can be routed to separate buckets or prefixes—for example, to isolate development and production data:

# archive.yaml
routes:
  - name: dev
    project_pattern: "dev/**"
    archive_uri: s3://my-langsmith-traces-dev/langsmith
  - name: production
    project_pattern: "prd/**"
    archive_uri: s3://my-langsmith-traces-prd/langsmith

Point the CLI at that configuration and schedule the sync using cron, a Kubernetes CronJob, or your existing scheduler:

export LANGSMITH_ARCHIVE_CONFIG=/etc/langsmith-cli/archive.yaml

langsmith-cli --json archive sync \
  --all-routes \
  --retention-days 14

The organization supplies the scheduler, LangSmith API key used during export, AWS workload identity, private buckets, encryption, lifecycle policies, and reader IAM. The CLI owns the archive and query mechanism—not your infrastructure.

Query historical traces without the LangSmith API

Archived traces remain searchable through familiar commands. Reads use DuckDB over Parquet in S3 and do not require a LangSmith API key:

# List production runs from the last 90 days
langsmith-cli --json runs list \
  --archive \
  --project prd/my-agent \
  --last 90d

# Search historical runs
langsmith-cli --json runs search "timeout" \
  --archive \
  --project prd/my-agent

# Inspect a run and its children
langsmith-cli --json runs get <run-id> \
  --archive \
  --follow-children

That means incident investigations, regression analysis, audits, and offline analytics can continue long after a base-tier trace has disappeared from the live LangSmith API.

A better default for high-volume tracing

For many teams, the most economical model is now straightforward:

Keep base retention for day-to-day debugging.
Disable automatic retention extension where it is not intentionally needed.
Export every trace to private S3 before the 14-day window closes.
Use --archive for older investigations and analysis.

You keep LangSmith's excellent live debugging experience, retain your full historical dataset under your own controls, and make long-term storage costs predictable.

The merged change and implementation notes are in langsmith-cli PR #163.

If you operate LangSmith at meaningful volume, this is worth setting up before your next evaluator or automation rule quietly multiplies the retention bill.

The Bitter Lesson for Backend Engineering

Aviad Rozenhek — Thu, 28 May 2026 13:26:46 +0000

Every senior backend engineer has sat in a war room while smart people argue
over instincts.

"It is the ASGI event loop."
"No, it is the database proxy."
"Just throw more pods at it."

The Core Thesis

We treat optimization as a test of intuition. But in "The Bitter Lesson,"
Richard Sutton's account of 70 years of AI research, the durable winners were
not the systems that best encoded human intuition. They were the general methods
that scaled with computation, especially search and learning. Human knowledge
helped locally and felt satisfying, but it tended to plateau. Compute-scaled
methods kept improving as compute got cheaper.

Backend engineering is facing its own bitter lesson. The future of systems
engineering is not "replacing judgment with agents." It is:

Build the system of work so that more computation can be turned into more
correct engineering progress.

For this backend effort, that means using agent compute to run a systematic
engineering loop. The human sets the goal, picks the risk boundary, and decides
what evidence is good enough. The agents spend parallel compute on the tedious
but decisive work: reading call paths, building harnesses, running experiments,
fitting scaling curves, checking payload equivalence, and keeping a durable log.

The Problem We Unleashed It On

The immediate problem was not "make one slow endpoint faster." It was harsher:
we needed a path to 500-1000 RPS on endpoints we had not even written yet.

At the same time, many existing endpoints were already struggling at
single-digit RPS. Horizontal scaling was ineffective: each additional CPU or pod
contributed too little throughput. There was no single obvious culprit. It
might have been Python CPU, serializer shape, the ORM, database compute,
connection fan-out, external calls, worker slots, event-loop blocking, load
shedding, or some interaction between them.

That made local cleverness the wrong tool. We did not need one more confident
guess. We needed a methodology that could discover what had to be better before
the next generation of endpoints was designed around the same bottlenecks.

The Limits Of The 30 W Brain

A human body runs at roughly 100 W; the brain is often estimated around 20-30 W.
That biological efficiency is remarkable, but it is also a bottleneck. A single
engineer can only hold so many hypotheses, command histories, query plans,
deploy states, and before/after measurements in working memory.

Backend engineers pride themselves on being empirical. We talk in latency
histograms, queue depths, lock contention, p95s, CPU profiles, connection pools,
and query plans. Yet we still fall into vibe-based optimization because real
systems exceed human working memory.

The irony is that backend performance is governed by rigid laws: discrete math,
queuing theory, network physics, storage behavior, CPU scheduling, cache
invalidation, and contention. Unlike product taste or visual design, these
systems eventually answer to measurement. But a 30 W brain cannot accurately
simulate an asymmetric network bottleneck, a contended connection pool, and a
multi-join query plan under load.

It certainly cannot do that while also tracking deploy state, cache behavior,
and error budgets.

Cheap-enough agent compute changes the shape of the work. Three agents can
simultaneously:

design instrumentation;
build harnesses and runbooks;
inspect hot paths;
prove behavior equivalence;
watch readiness, proxy metrics, app metrics, and logs;
maintain shared coordination state.

The rational move is to spend compute to reduce uncertainty. The scarce
resource is no longer typing time. It is experimental discipline.

So we reach for plausible stories. The event loop. The ORM. The GIL. The proxy.
The pods. The cache. The database. Each story may contain truth, but treating
the story as the strategy is exactly the human-centric mistake Sutton described.

The scalable strategy is to turn those stories into experiments and let compute
do the search.

The Ego Cost Is Familiar

Sutton's essay is uncomfortable because it says researchers repeatedly preferred
approaches that embedded human insight, even after scalable computation kept
winning. The pain was not just technical; it was identity. It feels better to
believe progress comes from our clever model of the domain than from a general
method that searches harder, learns more, or evaluates more candidates.

Backend engineering has the same temptation. The scalable engineering method is
to make each plausible story falsifiable and let the measurements decide.

The Case Study

Three specialized agents were turned loose on one hot endpoint — a paginated
list view central to the product — with instructions to find the binding
constraint, not the prettiest fix. A gentle 3 RPS live stress run did the
work: the database hit ~100% CPU while the proxy and its connections sat
flat. The bottleneck was DB compute. Python CPU was falsified separately by
a local sweep (parallel efficiency held at ~93% across four-way parallelism
with negligible variance). Connection fan-out and the serving stack were
not loaded enough at 3 RPS to matter. The stress test, not the code review,
is what named the axis.

With the axis identified, the agents went after the query shapes that were
burning the CPU. The serializer N+1 collapsed by an order of magnitude
(179 → 15 queries at page size 10, byte-identical payload). The paginated
COUNT(*) over a distinct multi-join was the bigger win (~639 ms → ~1.5 ms,
~400× faster, same value). A forced GROUP BY rewritten as a correlated
subquery took the full local view path from about 1590 ms to about 174 ms;
on a warm pod the median dropped from about 2.25 s to about 1.57 s.

Those wins matter as evidence that the DB CPU axis is reducible — that
the binding constraint stress testing surfaced is also a tractable one.
They are not the lesson. The lesson is what the search exposed when it ran
past one endpoint. The system is not bound by a single bottleneck. It is
bound by five, each with a different blast radius, a different toolchain
to investigate, and a different treatment cost:

The DB CPU wall. The 2-vCPU writer hits ~100% long before connections saturate. The surface fixes compress one query class on one endpoint; underneath, dozens of unrelated endpoints share the same query shapes, with the same low-RPS CPU cost. A hotspot inventory pairing pg_stat_statements with EXPLAIN is where the next ten- and twenty-times wins live.
The serving-layer ceiling. Even with the database idle, an in-cluster harness reproduces a ~1k-RPS wall per instance: four GIL-bound gunicorn workers paying a per-request cost. Adding pods does not buy RPS until that ratio improves.
The middleware tax. A cache-hit response has no DB cost and no business logic, yet still measures in tens of milliseconds. That floor — auth resolution, DRF rendering, observability middleware, session and CSRF on routes that need neither — is what the cache-hit ceiling cares about.
Caching strategy. A cache that is not stampede-protected fans out a miss into exactly the DB compute the surface fixes were trying to avoid. The cache only matters if it is reachable cheaply and protected end-to-end.
3rd-party blocking on the request path. Some endpoints still make synchronous calls to external services during request handling. Those endpoints cannot scale linearly with workers — and offloading them is a behavior change that needs product sign-off rather than a perf-only PR.

The Pareto matters because each scenario hits a different axis. The 50K
simultaneous-join burst is dominated by one endpoint and probably goes the
caching plus middleware-bypass route. The sustained 1K livestream uses
six endpoints driven by FE polling cadence and is dominated by the DB CPU
wall and 3rd-party blocking axes; middleware optimization buys it less.
"Make the backend faster" is a wish; "make this scenario's binding axis
cheaper" is a ranked list of PRs.

The interesting part is not any single optimization, or even the cascade of
falsifications and confirmations that produced the surface wins. It is the
shape of what was found underneath: not one bottleneck, but a class of
them, with different scenarios bound by different axes. The agents narrowed
the search space with evidence and let the bottleneck move without defending
the previous theory — which is the only way a system this shape gets mapped
at all.

The Evidence At Scale

One endpoint's hypothesis cascade is a vignette. The harder claim — the
uncomfortable one — is that this kind of work scales: in roughly
thirty-six hours, a small team plus parallel agents did the shape and
volume of investigation that a senior engineer would historically have
spread across a quarter. The most important output is not any single
fix. It is the kinds of work that suddenly become routine.

The Investigation At Scale

The agents read across four production codebases plus a PRD for a system
that does not exist yet — the API backend, the web frontend (to extract
real polling cadences and request fan-out), the AI/livestream service,
and the mobile/edge client paths, alongside the product requirements for
a 50K-person event flow with no working implementation. They produced,
per traffic scenario, the cadences, the at-risk factors, and the
treatments, and turned each into durable artifacts: a capacity model
deriving per-instance RPS from worker count and CPU-per-request; a
DB-CPU hotspot inventory ranking query shapes by cost so the ten- and
twenty-times wins land before the 1.2× ones; a four-scenario event-day
load profile (bursty purchase, 50K simultaneous join, initial-pressure
livestream, sustained livestream — each with a different binding axis);
and a synthesis collapsing dozens of hypotheses into the five axes the
case study named.

That analysis fed a hypothesis pipeline rather than a stack of one-off
optimizations. Roughly sixty tracking tickets opened under the parent
audit — about twenty-five explicit hypothesis tickets (each naming the
smell, the affected endpoints, and a falsifier), about seven paired
data-verification tickets whose only job is to confirm or kill a sibling
hypothesis, and the rest execution sub-projects (per-PR side backend,
read-replica routing, perf budgets, observability automation, DevOps
unblocks). Several stories were confirmed by measured wins of the kind
the case-study table chronicles — orders of magnitude on serializer
fan-out and paginated counts, an order of magnitude on a forced
aggregation — extended to more than one endpoint. Several others were
explicitly killed, which matters more than it sounds: the
Python-CPU-as-primary-limiter story (falsified by a local sweep that
scaled near-linearly); the load-source story for the ~1k-RPS ceiling
(the ceiling is real and lives in the worker count × CPU-per-request
budget); the token-cache premise (raw signature verification was too
cheap for the cache to matter); a codec swap assumed to be a meaningful
win that turned out to be noise. About two dozen hypotheses remain open
in triage, each queued behind its own data-verification ticket. The
point is not that the audit is finished. The point is that the queue
itself — falsifiable, prioritized, paired with a verification recipe —
is the durable output, built in parallel with the work that closed the
first batch. A traditional team builds this queue or builds the fixes;
this team built both.

Treatments At Scale

The shipped treatments span the categories the analysis pointed at
rather than clustering on a single favorite. In the same window:
query-shape rewrites (N+1 collapse, cheap-count pagination, GROUP-BY
elimination); per-request-cost reductions (eager-loading on the auth
path, explicit connection budgeting); platform plumbing (a per-PR
side backend so each branch can be benchmarked in isolation, an
in-cluster load harness, an observability-bundle validator, a fixed-rate
stress client); and methodology infrastructure (a clean perf-PR
pattern, an opt-in perf measurement toolkit, a Django caching playbook,
a per-scenario load-profile doc, a stress-test report for review by
humans who were not in the experiment loop).

Each treatment shipped as a small, byte-identical, single-anti-pattern
PR off main rather than as a bundled lab branch. That discipline is
itself a result. A senior engineer doing all of this serially does not
get to be that disciplined — they bundle, because bundling is how
working memory preserves context across changes. Parallel agents can
afford the discipline, and the team inherits a reviewable trail instead
of a heroic mega-merge. Beyond the PRs themselves, the cycle produced
roughly fifteen durable documents — capacity models, methodology specs,
optimization playbooks, validity gates, worked examples, runbooks, and
coordination logs — so the reasoning lives in the repository instead of
in chat history.

The honest read of this is not that the agents won. It is that the
parts of senior engineering work that used to be scarce — exhaustive
analysis across codebases, parallel falsification of competing stories,
ranked treatment lists with measured magnitudes, and writeups that
survive past the conversation that produced them — are no longer
rate-limited by typing time or by working memory. They are rate-limited
by whether the team sets the goal clearly, defines the falsifier
honestly, and accepts the evidence when it arrives.

That last one is where the bitter part lives. Some of the killed
hypotheses were stories the team had defended. Some of the confirmed
wins were not in anyone's top three guesses. The method does not care
which story was satisfying; it cares which story survives contact with
measurement. Accepting that — and learning to take pride in defining
goals and falsifiers rather than in being the one who also typed every
fix — is what makes the rest of it possible.

The Meta-Method And Architecture

The work succeeded because it was not run as a pile of disconnected chat turns.
It was run as a long-running goal architecture with a shared objective,
specialized agents, explicit containment, and durable state.

The first phase was deliberately constrained: prepare PRs, tests, hypotheses,
data, scripts, runbooks, and reasoning, but do not deploy and do not touch the
shared database. The agents did not burn the target environment just to feel
productive. They built the lab: local provider stubs, fresh-migrate workarounds,
isolated data paths, baseline controls, instrumentation, load tooling, parsers,
runbooks, and a coordination protocol.

After live execution was approved, the operating model shifted from isolation
to controlled target-environment work. The agents imported target-shaped data
into local Postgres, coordinated deployment windows, recorded deployed SHAs,
watched stop conditions, and pushed the system only until the next useful data
point appeared.

When a 3 RPS run saturated the environment, they treated it not as a crisis or
a reason to push harder, but as evidence: wall time times worker slots was
already enough to tip the system over.

That architecture had five essential parts:

A shared objective:
make 500-1000 RPS plausible with effective horizontal scaling, not just make
one benchmark look better.
A falsifiable model:
use Amdahl's law, Little's Law (in-flight work ≈ throughput × latency),
and the Universal Scalability Law to ask
whether throughput is capped by CPU, DB compute, DB connections, event-loop
blocking, external calls, or queueing.
Isolation before risk:
local Docker, an imported target-environment clone, local provider stubs, and
explicit live-execution gates allowed fast iteration without turning the
shared environment into the lab by default.
Agent specialization:
one agent owned app-code endpoint proofs and synthesis; another owned
harnesses, deployment, observability, and scaling sweeps; another owned
independent review and adjacent endpoint proofs. The taskboard and
append-only channel made collisions visible.
Proof over assertion:
changes were paired with query counts, timings, tests, payload hashes,
isolated worktree comparisons, target-environment samples, and explicit
caveats.

Backend optimization is longer than one prompt. It crosses code reading,
experiment design, harness construction, local reproduction, PR preparation,
deploy orchestration, observability capture, measurement correction, endpoint
fixes, and synthesis.

A stateless chat loop tends to forget the global objective or collapse into the
next visible task. Long-running goals kept the agents attached to the durable
outcome and gave them a place to preserve context across hours of asynchronous
code generation, deployment windows, and log analysis.

The operating loop was simple:

State the bottleneck hypothesis in physical terms.
Define the falsifier.
Build the smallest diagnostic.
Measure wall, CPU, DB time, external waits, queueing, errors, and saturation.
Change one lever.
Prove behavior, ideally with byte-identical payloads.
Re-measure the same way.
Update the model when the bottleneck moves.

That last step is the hardest culturally. If the bottleneck moves, that is
success. The point is not to defend the first theory. The point is to make the
next limiter visible.

The Guardrails

Cheap parallel compute is an accelerant, which means bad goal architecture will
amplify engineering errors just as quickly as it amplifies useful work. An
agent running an undisciplined optimization loop will happily DDoS a shared
environment, burn through observability spend, hide a regression behind a
cached response, or hallucinate a benchmarking victory by measuring failures as
throughput.

The human role therefore does not disappear. It moves from "manually perform
every step" to "define the containment boundary." The safety rails are not
optional process decoration; they are what make autonomous exploration usable:
local-first execution, explicit live-execution gates, one load window at a
time, stop conditions, deployed SHA capture, query-count and payload-equivalence
proofs, error-rate thresholds, and append-only coordination logs.

The measurement bug caught in this work is the small version of the same risk:
the first load harness reported achieved RPS in a way that counted failures.
Without experimental guardrails, cheap compute would have made that wrong
number look more convincing. With guardrails, the agents corrected the harness,
reclassified the run, and improved the method.

This method also has boundaries. It is strongest when the system is observable,
the goal is measurable, and improvement can proceed through small,
behavior-preserving changes. It is weaker when the task is green-field
architecture, product judgment, or a novel failure mode with poor telemetry.
There, human architectural taste and risk judgment still lead. The agents can
map the terrain, but they cannot decide what terrain is worth owning.

The Real Lesson

The human contribution is still essential, but it moves up a level. The human
should not spend most of the scarce 30 W on manually remembering every path and
guessing which bottleneck matters. The human should set the objective, enforce
experimental hygiene, choose acceptable risk, and judge the evidence.

The agents should burn compute on the scalable parts:

exhaustive code reading;
independent hypothesis generation;
repeated benchmark runs;
query-plan and metric collection;
before/after equivalence checks;
deployment state verification;
runbook and taskboard maintenance;
synthesis into a capacity model.

This is the backend version of Sutton's lesson: do not over-invest in a human's
favorite explanation of the system. Invest in the meta-process that searches the
system, measures it, and improves as more compute is applied.

The discomfort is the lesson. Mature backend engineering will feel less like
winning arguments about the system and more like building machinery that makes
those arguments unnecessary.

The result may sting. A single senior engineer's intuition is valuable, but it
is not a substitute for three agents running disciplined experiments in
parallel. That is not an insult to engineering judgment. It is what engineering
judgment should choose when compute becomes cheap enough.

Counter Factual
Estimate for an staff engineer — twenty years of wins across many varied fields data engineering, applied AI, MongoDB at scale, video codecs you've actually heard of — none of which necessarily teaches you Django querysets, Postgres profiling, stampede-protected Redis, gunicorn worker math, or how a Kubernetes liveness probe interacts with a saturated worker pool.

Ramp-up to credible-not-expert across that stack: 2–3 months. Investigation work on top of the ramp-up: another 1–2 months. Call it half a year, assuming nothing else catches fire. They'd ship ~10 heroic merged PRs and an oral folklore in their head — because under deadline the writeups are the first thing that gets cut. They'd also miss at least one axis with high probability;

Versus ~36 hours with agents in parallel, all five axes named, the writeups extant. Call it a ~100× compression in wall time, plus the writeups exist at all — which, on a year-long solo project, they wouldn't.

External Reference

Richard Sutton, "The Bitter Lesson", March 13, 2019: http://www.incompleteideas.net/IncIdeas/BitterLesson.html

Turning Linear and Figma Into a Searchable Knowledge Layer with `aviadr1/issueclaw` and `aviadr1/figmaclaw`

Aviad Rozenhek — Fri, 03 Apr 2026 12:13:47 +0000

Most teams don’t lack information — they lack a way to search product, design, and engineering context as one system; this article explores what happens when you turn Linear and Figma into searchable markdown and let humans and AI reason across both.

Product intent is in Linear. Design detail is in Figma. Implementation reality is in code. Each system is useful on its own, but the moment you need to answer a question that crosses all three, things get awkward. You open tabs, search manually, ask in Slack, and reconstruct the answer from fragments.

That is tolerable for humans. It is much worse for AI.

At Gigaverse, we wanted something different: not a new source of truth, and not a replacement for Linear or Figma, but a shared text layer that makes product and design context searchable, diffable, and usable by both humans and agents.

That is the role of two repositories:

aviadr1/issueclaw
aviadr1/figmaclaw

Together, they turn Linear and Figma into git-native markdown that can be searched alongside code. Once that exists, a different class of workflow becomes possible.

TL;DR

This article is about a simple idea with surprisingly large consequences:

Mirror Linear and Figma into markdown, keep that mirror up to date, and use it as a searchable working memory layer for your team.

If you read on, you should come away with:

a clear mental model for what issueclaw and figmaclaw do
a practical sense of why this is useful beyond “exporting markdown”
real examples of the kinds of questions this unlocks
a private-by-default way to adopt the same pattern in your own team

The short version is that this makes it much easier to answer questions like:

Where does this feature already exist in design?
What did product actually decide here?
Is this designed on both web and mobile?
Does the design still match the current implementation?
What changed in one system that has not propagated to the others?

That is where the real value starts.

The problem: product knowledge is fragmented by tool boundaries

Modern product development is full of cross-system questions.

Not “what does this ticket say?”
Not “what does this Figma page look like?”
But questions like:

What is the current shape of this feature from spec to design to implementation?
Which design patterns are duplicated or inconsistent?
Is this bug contradicting the spec, the design, or the code?
Which features have been explored deeply in design but barely implemented?
Where are we at risk of building from stale assumptions?

These are not rare edge cases. They are everyday questions.

And most tools are not built to answer them well.

Linear is good at tickets, docs, and status.
Figma is good at visual design and flows.
Git is good at code and history.

The problem is everything that lives between them.

The core idea

The idea behind aviadr1/issueclaw and aviadr1/figmaclaw is straightforward.

issueclaw mirrors the Linear side into markdown
figmaclaw mirrors the Figma side into markdown
that markdown lives in git, alongside the rest of your technical context

Once you do that, you get something new:

Linear stops being only a UI you browse
Figma stops being only a canvas you click through
git becomes a searchable memory layer for product, design, and engineering

That is the key shift.

This is not about replacing the original tools. The source systems remain the source of truth. The markdown mirror exists to make them more searchable, more comparable, and more usable in workflows that span multiple systems.

What `aviadr1/figmaclaw` does

At a high level, figmaclaw turns Figma pages into markdown.

Each page becomes a .md file with two layers:

a structural layer with things like page IDs, frame IDs, flow information, and metadata
a readable layer with summaries, sections, descriptions, and flow representations

That gives you something that is simultaneously machine-friendly and human-friendly.

Machines can diff it, hash it, update it incrementally, and search it cheaply.

Humans can read it, grep it, review it, and paste it into AI workflows without having to browse Figma frame by frame.

In the Gigaverse setup, this created a large text mirror of the design workspace: hundreds of markdown files representing pages across dozens of Figma files. That was enough to turn design discovery into a search problem instead of a browsing problem.

What `aviadr1/issueclaw` does

issueclaw does the complementary job on the Linear side.

It mirrors issues, docs, and related artifacts into markdown so they can live in git as searchable text. That makes product context easier to diff, easier to inspect historically, and far easier to combine with design and code context.

The important point is not just that the data is exported.

It is that once the product layer and the design layer are both present as text, they can be searched together.

That is what unlocks the more interesting workflows.

Why this is more useful than it sounds

If you hear “we exported Figma and Linear into markdown,” it sounds mildly convenient.

That undersells it.

The real benefit is that you get a new reasoning layer across systems that normally do not compose well.

At Gigaverse, this led to a few capabilities that stood out immediately.

1. Full-text search across designs

This was the clearest immediate win.

Once Figma was mirrored into markdown, questions like these became trivial:

Where do polls appear across the product?
Which screens mention notifications?
How much dark mode coverage do we have?
What onboarding UI already exists?

Those are annoying questions in raw Figma. They become easy when design is searchable as text.

This alone is a strong enough use case to justify the mirror.

2. Feature tracing from spec to design to implementation

One of the strongest tests was tracing Gigaverse’s “going live” feature end to end.

By combining Linear docs, Figma markdown, and implementation issues, we could reconstruct:

the intended product behavior
the relevant web and mobile flows
the implementation work across teams
and contradictions between different sources

That is not just convenient retrieval. That is actual cross-system understanding.

3. Reconstructing design decisions

Another strong use case was looking at stage widgets.

The Figma side showed iterations, comparisons, and changing layout ideas. The Linear side showed what had been decided and how implementation tracked those decisions.

That let us answer not just “what screens exist?” but “what was explored, what direction won, and how far did it get?”

That is a much more interesting kind of query.

4. Platform parity analysis

This turned out to be a very practical question:

Which features exist on both mobile and web?
Which are intentionally platform-specific?
Where are the gaps?

That kind of audit becomes much easier once the design layer and the issue layer are searchable in one place.

5. Design system audits

This is another category that gets dramatically better once design becomes text.

Instead of clicking through files manually, you can search for:

empty states
loading states
modal patterns
permission flows
error states

That makes inconsistency much easier to spot.

The most interesting capability: drift detection

The biggest surprise was that the highest-value use case was not search.

It was drift detection.

Once specs, issues, and designs were all searchable together, it became much easier to spot cases where they disagreed.

At Gigaverse, this surfaced real examples of:

contradictory toggle defaults across issues, product docs, and QA expectations
terminology drift between active ticket language and newer design language
design elements that remained in Figma after they had effectively been removed from the product direction
exploratory design states with no matching implementation work

This is where the system stopped feeling like a retrieval convenience and started feeling like infrastructure.

Search saves time.

Drift detection saves teams from bugs, confusion, and rework.

Why not just use Figma MCP directly?

Because the two approaches are good at different things.

Figma MCP is best when you already know what you want to inspect. It is excellent for exact visual truth, precise frame inspection, and prototype details.

The markdown mirror is best when you do not yet know where to look.

That distinction matters.

For broad search, inventory, audits, and AI context-building, markdown is dramatically more efficient. It is faster to search, cheaper to process, and much more compact for LLM workflows than raw API payloads or screenshot-heavy browsing.

The best workflow is not one or the other.

It is:

Use the markdown layer to narrow the search space.
Use Figma MCP only for the specific frames where visual precision matters.

That division of labor turned out to be extremely effective.

How `figmaclaw` stays current

A one-time export would be mildly useful.

What makes figmaclaw interesting is that it is incremental.

At a high level, it works like this:

tracked Figma files are checked for changes
unchanged files or pages are skipped
changed pages are updated
changed frames are the ones that get re-enriched

That means the system does not need to rebuild the entire design workspace every time someone makes a small edit.

This matters for both speed and cost.

It also means the mirror can stay reasonably close to the actual design source of truth without turning every sync into a huge batch process.

Why sync and enrichment are separate

This is one of the smartest parts of the architecture.

There are really two different problems here:

keeping the mirror structurally up to date
making the mirror richly readable

The first part is deterministic and cheap.
The second part is interpretive and more expensive.

So the system treats them separately.

The sync layer updates the structure.
The enrichment layer turns that structure into useful prose.

That is a better architecture than trying to do everything in one pass.

It means the mirror can stay fresh even while enrichment is still running, and it means you can prioritize the highest-value parts of the design corpus first.

In our case, enrichment is currently in progress and the whole mirrored system should be enriched within a few hours. That matters because it removes the biggest remaining weakness we saw: pages that were structurally present but not yet richly described.

What this means for AI workflows

This pattern is especially powerful if you are serious about AI-assisted development.

LLMs do much better when the input is:

textual
structured
scoped
and semantically meaningful

A good markdown page description is a far better input than raw design JSON or a folder full of screenshots.

That means this mirror is useful not just for human search, but for:

implementation assistance
code review context
architectural reasoning
product/design retrieval
and agent workflows that need to move across systems cleanly

This is one of the reasons the approach feels increasingly important. It is not just about convenience for humans. It is about building a better substrate for machine reasoning too.

How to use this privately on your own team

You do not need to make any of this public.

The default setup should be private.

A simple model is:

keep Linear and Figma as your source systems
mirror them into a private git repo with aviadr1/issueclaw and aviadr1/figmaclaw
run sync and enrichment in your own environment
let your team and internal tools search the resulting markdown

A minimal repo might look like this:

product-memory/
  linear/
  figma/

The practical flow is:

create a private repo
install aviadr1/issueclaw and point it at your Linear workspace
install aviadr1/figmaclaw and point it at the Figma files you want mirrored
run the initial syncs
schedule periodic syncs via cron or CI
run enrichment privately and commit the results back into the repo

I have not verified the live README commands for both repositories line by line in this session, so I would use each repository’s current README and CLI help for the exact installation syntax. The important point is architectural: the whole pipeline can remain private end to end.

Who should care

This is especially useful for teams that already have:

serious product work in Linear
serious design work in Figma
fast-moving engineering
and growing use of AI in development or internal tooling

In other words, this is useful anywhere the real answer to a question usually lives across multiple systems rather than inside one.

The takeaway

The real point of aviadr1/issueclaw and aviadr1/figmaclaw is not markdown.

It is that they turn two important systems of record into a shared, searchable knowledge layer.

That layer is useful because it helps humans and AI reason across product, design, and engineering as one system rather than three disconnected tools.

At Gigaverse, that already made search, feature tracing, platform comparison, and design audits much easier.

The deeper win was drift detection.

That is what made the whole approach feel important.

If you are building software with Linear, Figma, git, and AI-assisted workflows, this pattern is worth serious consideration.

It gives your team something most tool stacks are missing:

a working memory that spans the actual shape of product development.

Claude Feels Slow. But Is Moving a Team to Open-Weight Models Actually the Fix?

Aviad Rozenhek — Mon, 30 Mar 2026 22:21:51 +0000

TL;DR

Claude has a real speed problem for our team — but mostly in TTFT, not in raw decoding speed.

I measured our actual usage and found this:

TTFT p50: 4.2s–6.8s
TTFT p90: 14.5s–28.1s
Claude Sonnet decode p50: 176 tok/s

That explains the feeling: Claude often isn’t that slow once it starts, but sometimes it takes so long to begin that the whole thing feels like it’s crawling.

That naturally raises the next question:

Should we move the team to self-hosted open-weight models?

At first glance, that sounds promising. Self-hosted setups can have dramatically better TTFT. In the numbers I looked at, open-weight deployments were often estimated around 150–600ms TTFT, versus Claude’s 4–7s median in our real usage.

But once I looked at the actual team setup — 10 engineers sharing one GPU budget — the answer stopped looking obvious.

The best open-weight models need serious multi-GPU infra, and once that infra is shared, the speed case starts looking surprisingly shaky.

So this post is not “open source bad.”

It’s a narrower question:

If Claude feels slow, is moving a team to open-weight models on shared infra actually the answer?

Right now, I’m not convinced.

The problem: Claude feels like it crawls

This started with a very practical complaint:

Claude is slow.

That could mean a lot of things, so I measured it.

From about 50 session files and roughly 3,000 API calls, the problem was clear: the main issue was TTFT, especially in the tail.

TTFT from our real usage

Trigger	p10	p50	p90
User message	2.8s	6.8s	28.1s
Tool result	2.5s	4.2s	14.5s

That 28.1s p90 is the whole story.

Claude is not just “a bit laggy” there. It’s slow enough to break flow.

The surprising part: decode speed wasn’t the main problem

Here’s the other half of the picture.

Generation speed

Metric	p10	p50	p90
Decode tok/s (excluding TTFT)	72	178	567
Wall tok/s (including TTFT)	23	41	63

And per model:

Model	TTFT p50	Decode p50
Haiku 4.5	1.8s	287 tok/s
Sonnet 4.6	4.2s	176 tok/s
Opus 4.6	4.7s	130 tok/s

So the core problem wasn’t really:

Claude can’t stream fast enough.

It was:

Claude often takes too long to get started.

That distinction matters, because it makes self-hosting sound much more attractive than it might actually be.

Why open weights sound like the obvious answer

If TTFT is the problem, then self-hosting sounds like the clean fix.

The pitch is simple:

no provider-side queue
no shared API congestion
your own inference server
much lower TTFT

And the numbers I collected from the self-hosting side were definitely seductive.

Best-case self-hosted framing

Metric	Claude now	Best self-hosted
Tool-triggered TTFT p50	4,200ms	~160ms
User-triggered TTFT p50	6,800ms	~160ms
Bad-day p90	14,500ms+	<400ms

If TTFT were the only thing that mattered, I think this would already be enough to move seriously toward GPUs.

But TTFT is not the whole developer experience.

The models we’d actually consider

We’re not talking about toy models here. We’re talking about the real open-weight candidates people would actually put on the table.

Models considered

Model	Why consider it?
Qwen3-Coder-Next	Fast MoE coding model, 80B total / 3B active
MiniMax M2.5	Stronger quality candidate, 230B total / 10B active
DeepSeek V3.2	Very large MoE option
Qwen3.5-27B	Dense, simpler, slower but cheaper

And the inference engines are the standard ones you’d expect:

Inference engines

Model family	Realistic inference engine
Qwen / DeepSeek	vLLM or SGLang
MiniMax M2.5	vLLM
Dense smaller models	usually vLLM

That means this isn’t some hypothetical future stack. It’s the standard modern self-hosted inference path.

The part that makes this much less exciting: GPU budgets are shared

This is the piece I think gets hand-waved away too often.

Our current setup is:

Item	Value
Engineers	10
Claude subscription per engineer	$150/mo
Total Claude cost	$1,500/mo

The budget I was willing to entertain for self-hosting was roughly 3× that, so about $4,500/month.

That sounds like a lot.

But for top open-weight coding models, it buys you something like this:

What the budget can buy

Config	Cost/month	Notes
5× H100 on Vast.ai	$4,712	Enough for MiniMax M2.5 / DeepSeek-class INT4
3× H100 on Lambda	$4,521	More reliable, lower GPU count
4× H200 on Vast.ai	$4,153	Better memory bandwidth
8× A100 on Vast.ai	$2,580	Cheapest high-count option

That’s not “10 engineers each get a fast private model.”

That’s one shared cluster.

And that changes the question completely.

The real metric is not TTFT. It’s team step time.

The right equation is not:

lower TTFT = faster experience

It’s more like:

team step time = queueing + TTFT + output_tokens / decode_speed

That’s the part that made me hesitate.

Because once you share one cluster across 10 engineers:

TTFT might improve
but per-user decoding might not
and queueing becomes part of the story

That is a very different situation from “look how fast this benchmark is on one box.”

Why I’m not yet sold

The self-hosted numbers I gathered looked like this:

Self-hosted decode estimates I considered

Model	Config	INT4 decode tok/s
Qwen3-Coder-Next	2× H100	~3,400
MiniMax M2.5	4× H100	~2,000
MiniMax M2.5	2× H100	~1,000
DeepSeek V3.2	5× H100	~700
Qwen3.5-27B	2× H100	~380
Qwen3.5-27B	1× H100	~190

Those numbers are exciting. They make open weights look like a no-brainer.

But they also raise exactly the question I still don’t think I’ve answered cleanly:

Are these the numbers one engineer feels, or the numbers a shared cluster produces in aggregate?

Because for a 10-person team, those are not the same thing.

And once I started looking at the problem through the lens of shared infra, the speed case stopped looking like an obvious slam dunk.

So where does that leave me?

I think I’ve convinced myself of a few things:

What seems true

Statement	My current view
Claude has a real speed problem	Yes
The problem is mostly TTFT	Yes
Self-hosting probably improves TTFT a lot	Yes
The best open-weight models are expensive to run well	Yes
Shared infra weakens the speed story	Yes
Moving the whole team looks obviously promising	No

That’s the interesting part.

The story I expected was:

Claude is slow, open weights are fast, buy GPUs, problem solved.

The story I actually found was:

Claude is slow mostly because of TTFT.
Open weights probably help that.
But once the infra is shared across a team, the speed case gets much less clean.

Bottom line

I started with a very simple frustration:

Claude felt slow.

I measured it and found a very specific issue:

TTFT, especially the p90 tail, was bad enough to make the whole experience feel like it was crawling.

That led to the obvious next idea:

What if we just move to open-weight models on our own GPUs?

And right now, my answer is not “definitely no.”

It’s this:

Open-weight models look promising for TTFT.

They look much less promising as a shared-infra speed fix for a whole team.

That’s the question I’m left with.

Not whether open weights are good.
Not whether they’re possible.
But whether they really solve the problem we actually have.

I Replaced My LangSmith MCP Server with a 200-Token CLI Skill

Aviad Rozenhek — Thu, 05 Mar 2026 01:03:14 +0000

How langsmith-cli gives you 100% MCP parity, 96% less context usage, and features the MCP server doesn't have — all in a single pip install."

If you're using LangSmith with Claude Code (or any AI coding agent), you're probably running the official MCP server. It works. But every session, it injects 5,000+ tokens of tool schemas into your context window — whether you touch LangSmith or not.

I built langsmith-cli to fix that. It's a standalone CLI and a Claude Code plugin that replaces the MCP server with a <200 token skill definition. That's a 95% reduction in context overhead.

And it does more than the MCP server does.

The Problem with MCP Servers

MCP servers are always-on. The moment your agent session starts, every tool definition gets loaded into context. For LangSmith's MCP server, that's 66 parameters across multiple tools — around 5,000 tokens of JSON schema that sits in your context window doing nothing until you actually need to query traces.

For agents that need to do many things — write code, run tests, debug, and occasionally check LangSmith — this is wasteful. Context is your agent's working memory. Every token of schema is a token not available for reasoning.

The Fix: On-Demand Skills Instead of Always-On Schemas

langsmith-cli takes a different approach. Instead of an MCP server, it's a CLI tool with a tiny skill file that teaches your agent how to use it:

# Install the CLI
uv tool install langsmith-cli

# Add as Claude Code plugin
claude plugin marketplace add gigaverse-app/langsmith-cli
claude plugin install langsmith-cli@langsmith-cli

The skill file is ~200 tokens. It loads on-demand. Your agent learns to run shell commands like:

# Get the latest failed run with only the fields you need
langsmith-cli --json runs get-latest --project my-app \
  --failed --fields id,name,error

No schema bloat. No always-on server. Just a CLI your agent calls when it needs observability data.

96% Token Reduction with `--fields`

This is the feature that matters most for agents. A typical LangSmith run object is 20KB — easily 1,000+ tokens. With --fields, you get only what you asked for:

# Full run object: ~1000 tokens
langsmith-cli --json runs get abc-123

# Just what you need: ~40 tokens
langsmith-cli --json runs get abc-123 --fields name,status,error

--fields works on every list and get command: runs, projects, datasets, examples, prompts. Your agent stays lean.

Built for Two Audiences

Most developer tools pick one audience. langsmith-cli serves both:

For humans — rich terminal tables with color-coded statuses, smart column truncation, syntax highlighting:

langsmith-cli runs list --project my-app --status error --last 24h

┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Name         ┃ Status     ┃ Tokens ┃ Latency  ┃ Error       ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ extractor    │ error      │ 2,340  │ 3.2s     │ Rate limit  │
│ classifier   │ error      │ 1,102  │ 12.4s    │ Timeout     │
└──────────────┴────────────┴────────┴──────────┴─────────────┘

For agents — add --json as the first flag and everything switches: strict JSON to stdout, diagnostics to stderr, zero formatting noise:

langsmith-cli --json runs list --project my-app --status error --limit 5

One flag. Two completely different UX modes.

Features the MCP Server Doesn't Have

langsmith-cli has 100% parity with the official MCP server (all 66 parameters mapped). But it also has features the MCP server can't offer:

Live Monitoring with `runs watch`

A real-time streaming dashboard in your terminal:

langsmith-cli runs watch --project my-app

One-Command Debugging with `runs get-latest`

No more list | jq | get pipelines:

# Before: three commands piped together
langsmith-cli --json runs list --project X --limit 1 \
  | jq -r '.[0].id' \
  | xargs langsmith-cli --json runs get

# After: one command
langsmith-cli --json runs get-latest --project X --fields inputs,outputs,error

Stratified Sampling with `runs sample`

Build statistically sound eval datasets:

langsmith-cli runs sample \
  --stratify-by tag:length,tag:content_type \
  --dimension-values "short|long,news|gaming" \
  --samples-per-combination 5 \
  --output eval_samples.jsonl

Aggregate Analytics with `runs analyze`

Group-by metrics without leaving the terminal:

langsmith-cli --json runs analyze \
  --group-by tag:model \
  --metrics count,error_rate,p50_latency,avg_cost

Schema Discovery with `runs fields` / `runs describe`

Don't know what fields your runs have? Discover them:

langsmith-cli --json runs fields --include inputs,outputs
# Returns field paths, types, presence rates, even language distribution

Tag & Metadata Discovery

langsmith-cli runs tags --project my-app
langsmith-cli runs metadata-keys --project my-app

Bulk Export with Pattern Filenames

langsmith-cli runs export ./traces \
  --project my-app --roots --limit 1000 \
  --filename-pattern "{name}-{run_id}"

Production Run to Eval Example in One Command

langsmith-cli --json examples from-run <run-id> --dataset my-eval-set

Smart Filtering That Translates to FQL

Nobody wants to write raw Filter Query Language. The CLI translates human-friendly flags automatically:

# These flags...
langsmith-cli runs list --tag summarizer --failed --last 24h --slow

# ...become this FQL:
# and(has(tags, "summarizer"), eq(error, true),
#     gt(start_time, "2026-03-03T..."), gt(latency, "5s"))

Time presets like --recent (last hour), --today, --last 7d, and --since 2026-01-01 all work. Content search with --grep supports regex and field-specific matching. Everything composes.

What's New in v0.4.0

The v0.4.0 release focused on type safety and code quality:

Zero pyright errors — every function has proper type annotations. client: langsmith.Client, not client: Any. Return types are real SDK Pydantic models, not object.
datasets delete command with confirmation prompts and JSON mode support
Improved error handling across prompts and runs commands using specific SDK exception types (LangSmithNotFoundError, LangSmithConflictError) instead of broad except Exception
702 unit tests passing with real Pydantic model instances (no MagicMock for test data)

Getting Started

# Install
uv tool install langsmith-cli
# or: pip install langsmith-cli

# Authenticate
export LANGSMITH_API_KEY="lsv2_..."
# or: langsmith-cli auth login

# Start exploring
langsmith-cli runs list --project my-app --last 24h
langsmith-cli --json runs get-latest --failed --fields name,error

If you're using Claude Code, add the plugin for the best agent experience:

claude plugin marketplace add gigaverse-app/langsmith-cli
claude plugin install langsmith-cli@langsmith-cli

The code is MIT licensed and on GitHub: gigaverse-app/langsmith-cli

If you're building with LangSmith and tired of context-heavy MCP servers, give it a try. Happy to hear feedback in the issues.

Using AI to Audit Engineering Team Output: An Experiment with Claude

Aviad Rozenhek — Mon, 19 Jan 2026 22:47:46 +0000

In engineering management, few challenges are as persistent and contentious as objectively measuring team performance. How do we assess velocity, output quality, and even seniority in a way that is fair, insightful, and resistant to gaming? Traditional metrics—such as story points, commit counts, or lines of code—often fall short. They can incentivize quantity over quality, reward activity rather than impact, and fail to capture the nuanced reality of production software development.

Recently, I conducted an experiment to explore a novel approach: using a large language model (Claude) as an impartial "auditor" to evaluate a codebase over several months. The goal was to answer fundamental questions:

What was actually delivered?
How complex was the work in reality?
How long did it take compared to expectations for a senior engineer?
How stable was the resulting output?

The results were thought-provoking—and somewhat unflattering—prompting deeper reflection on whether AI can (or should) play a role in performance assessment.

The Core Idea: An AI-Powered Engineering Audit

The experiment centered on a detailed system prompt designed to guide Claude through a structured audit process. Rather than relying on superficial signals like commit volume, the prompt instructs the model to:

Identify distinct deliverables by analyzing code changes and timelines.
Evaluate true complexity by examining architecture, dependencies, novel logic, and integration challenges.
Compare actual development time against benchmarks for senior engineers.
Assess stability through regression patterns, hotfixes, and rework.
Quantify overall efficiency and highlight red flags.

Importantly, the prompt emphasizes reading the actual code, not just commit messages, to avoid bias from optimistic descriptions.

Here is the full prompt I used: GitHub Gist.

The prompt is divided into six phases:

Deliverables Inventory – Catalog what was built.
True Complexity Assessment – Classify each deliverable (TRIVIAL to HIGHLY COMPLEX) with evidence.
Time Efficiency Analysis – Expected vs. actual timelines.
Quality & Regression Assessment – Stability and post-ship issues.
Breadth vs. Depth Analysis – Distribution of new features, improvements, maintenance, and rework.
Honest Assessment – Overall efficiency, rework rate, and verdict.

Running the Experiment

I applied this prompt to a real production codebase spanning approximately four months of work by a small team. The audit produced a comprehensive report with tables, evidence excerpts, and quantitative summaries.

Key high-level findings:

Most deliverables were rated as MODERATE or lower complexity, even those that felt substantial during development.
Several features showed timelines 2–10x longer than the prompt's senior-engineer benchmarks.
Rework (fixes, hotfixes, reverts) consumed a significant portion of total effort.
The overall efficiency calculation suggested room for substantial improvement compared to a "well-functioning" baseline.

Notably, the assessment appeared conservative—often downgrading apparent complexity by emphasizing reusable patterns, existing infrastructure, and boilerplate. For instance, systems involving real-time processing and multiple external integrations were classified as COMPLEX but with expected senior timelines of 1–2 weeks, despite months of iteration in practice.

Reflections: Does AI Underestimate—or Cut Through Bias?

The results raised immediate questions about the reliability of AI-driven audits.

On one hand, LLMs may systematically underestimate complexity in real-world systems. Production engineering involves hidden challenges that models struggle to appreciate fully:

Iterative policy refinement and edge-case handling.
Integration debt with legacy systems or third-party APIs.
Coordination overhead in distributed teams.
The intangible cost of context-switching and debugging in complex environments.

On the other hand, the audit's critical tone might reflect a valuable strength: cutting through human bias. Engineers (myself included) naturally overestimate the novelty and difficulty of our work. An impartial observer—especially one trained on vast codebases—can identify patterns, leverage points, and simplifications that feel groundbreaking internally but are standard externally.

Broader Implications and Open Questions

This experiment touches on several important topics in engineering leadership:

Measurement Practices: How do most organizations currently evaluate velocity and quality? Many rely on proxies (velocity in story points, DORA metrics, cycle time), but few attempt deep code-level audits. Could structured AI analysis complement these?
Seniority Calibration: The prompt uses senior-engineer time estimates as anchors. Is this fair? Seniority varies widely—what one engineer completes in days, another might require weeks due to domain knowledge gaps.
Ethical Considerations: Automating performance assessment raises concerns around fairness, transparency, and morale. If an AI labels output as "inefficient," how do we ensure the evaluation is accurate and contextualized? Should such tools ever influence compensation or promotion?
AI Limitations and Improvements: Current models excel at pattern matching but may miss subtle production realities. Future iterations could incorporate more signals (e.g., test coverage depth, production incident data, user impact metrics).

Have you experimented with LLMs for code review, retrospective analysis, or performance measurement? What pros and cons have you encountered?

Conclusion

Using Claude to audit engineering output proved to be a revealing—if humbling—exercise. While the assessment seemed to underestimate certain complexities, it highlighted areas for process improvement and forced a more honest reckoning with deliverables.

I share this not to prescribe AI audits as the solution, but to spark discussion. In an era where AI is transforming how we write code, perhaps it can also help us better understand the code we write—and the teams that write it.

What are your thoughts? How do you measure engineering effectiveness today, and where do you see AI fitting in (or not)?

Thanks for reading. Feedback welcome in the comments.

engineering #productivity #management #ai

LangSmith CLI: Not Just Efficient — Actually Better Than MCP

Aviad Rozenhek — Thu, 15 Jan 2026 00:13:07 +0000

LangSmith gives us incredible visibility into LLM applications: full traces, datasets, prompt versioning, evaluations — everything we need to build reliable AI systems.

But actually using LangSmith day-to-day has always felt clunky:

Constantly refreshing the web UI
Writing custom API scripts
Or using MCP servers that quietly eat 16,100 tokens of context — permanently.

I built langsmith-cli to solve this properly.

It's not only dramatically more efficient (177× less context overhead).

It is fundamentally better for real debugging, analysis, and production monitoring workflows.

Here’s why — with real measurements and concrete examples.

1. Context Is Precious — 177× Less Waste

Straight from /context in Claude Code:

MCP LangSmith tools → 16,100 tokens always loaded (~8% of 200k context)
langsmith-cli as Skill → 91 tokens only when activated, 0 when idle

→ 177× difference in context overhead.

This is not theoretical.

Every extra 10–20k tokens of tool definitions means less room for:

conversation history
source code
documentation
actual reasoning

Add 2–3 more MCP servers → 20–30% of your context disappears before you start working.

2. Real-time Production Monitoring — `runs watch`

The single feature that made me never want to go back:

langsmith-cli runs watch --project production

You get an auto-refreshing, color-coded terminal dashboard:

Live status (🟢 / 🔴)
Latency, token usage, relative time
Instant visibility into error rate and average performance
Filter on the fly: --failed, --slow, --model gpt-4, --tag customer-facing

No browser refresh. No delay.

You literally see production break (or recover) in real time.

MCP + web UI simply cannot match this immediacy.

3. Powerful, Developer-first Filtering

Finding the right runs should not require writing custom code every time.

Examples that MCP/web simply cannot do easily:

# Regex on run names
langsmith-cli runs list --name-regex "^api-v[0-9]+\.[0-9]+"

# Wildcard + smart presets
langsmith-cli runs list --name-pattern "*auth*" --failed --today

# Time ranges (very natural syntax)
langsmith-cli runs list --since "1 hour ago"
langsmith-cli runs list --last 24h
langsmith-cli runs list --since "2025-12-01" --until "2025-12-02"

# Expensive / slow runs
langsmith-cli runs list --min-tokens 8000 --slow --today

These filters are fast, composable, and — most importantly — stay in your terminal flow.

4. Field Pruning: 95% Token Reduction on Responses

A complex multi-agent trace can easily be ~4,200 tokens.

Fetching 10 failed runs full → ~42k tokens just for data.

With --fields:

langsmith-cli --json runs list --failed --limit 10 --fields name,error,latency,status

→ ~214 tokens per run instead of 4,210

→ ~95% reduction

You only pay for the information you actually need.

MCP always returns the complete object. Every time.

5. Dual Excellent UX — Humans + Agents

# Human mode (beautiful rich table)
langsmith-cli runs list --project production --limit 8

→ Color-coded, aggregates, relative times, clean formatting

# Agent / script mode (strict, minimal JSON)
langsmith-cli --json runs list --failed --fields name,error,latency --limit 20

One tool. Two perfect interfaces.

No compromises.

6. Export Formats That Actually Help Teams

--format csv → Excel, pivot tables, stakeholder reports
--format yaml → configs, reproducible environments
--json → agents, automation, monitoring pipelines

langsmith-cli runs list --failed --today --format csv > failed-runs-today.csv

Open → analyze → share. Done.

7. Unix Philosophy — Full Composability

# How many timeout errors today?
langsmith-cli --json runs list --failed --today \
  | jq '.[] | select(.error | contains("timeout"))' \
  | wc -l

# Top 5 most common errors
langsmith-cli --json runs list --failed --limit 200 \
  | jq -r '.[] | .error' \
  | sort | uniq -c | sort -rn | head -5

This is where CLI completely outclasses MCP + web.

You already know these tools.

You already have the scripts.

Now they work with LangSmith too.

Quick Start (Really 30–60 Seconds)

# Install (isolated, safe, works everywhere)
curl -sSL https://raw.githubusercontent.com/langchain-ai/langsmith-cli/main/scripts/install.sh | sh

# Or faster with uv:
uv tool install langsmith-cli

# Add as skill in Claude Code
/plugin marketplace add gigaverse-app/langsmith-cli

# First login
langsmith-cli auth login

Then try:

langsmith-cli runs watch --project production
# or
langsmith-cli runs list --failed --today

Final Verdict

langsmith-cli is not just "lighter" than MCP.

It is objectively better at the things that matter most when debugging and operating LLM systems in production:

Real-time visibility
Powerful filtering without code
Massive context & token savings
Beautiful human UX + perfect machine UX
Export formats teams actually use
Full Unix-style composability

177× less context overhead is nice.

But being able to watch production live, find problems in seconds, and export meaningful data instantly — that's why I built it, and why I never want to go back.

Give it 60 seconds.

Run /context before and after.

The numbers don't lie.

Repo → https://github.com/gigaverse-app/langsmith-cli (MIT)

Happy (much faster) debugging!

Aviad

LangSmith #LLM #Observability #AIDevTools #ClaudeCode

LangSmith CLI Why Lightweight Skills Crush Heavy MCP Servers (Context Is All You Need)

Aviad Rozenhek — Wed, 14 Jan 2026 23:47:47 +0000

TL;DR

Measured reality in Claude Code sessions:

MCP LangSmith tools → 16,100 tokens always loaded (≈8% of 200k context)
langsmith-cli as Skill → 91 tokens when activated, 0 tokens when idle
Difference: ×177 less context overhead

Installation: 30 seconds vs typical 15+ minutes

Field pruning: up to 95% token reduction on responses

Startup: 43–87 ms cold/warm

Skills win for the majority of stateless AI tooling operations.

The Context Tax – Measured Reality

Right now, in my Claude Code session, the LangSmith MCP tools are consuming:

MCP tools · /mcp
├ mcp__langsmith__run_experiment     3.2k tokens
├ mcp__langsmith__push_prompt         2.8k tokens
├ mcp__langsmith__fetch_runs          2.2k tokens
...
└ mcp__langsmith__get_prompt_by_name    146 tokens
TOTAL: 16,100 tokens   (≈8% of 200k context window)

These definitions are permanently loaded — even if I never touch LangSmith during the entire conversation.

The same functionality implemented as a Skill (subprocess-based CLI):

Skills · /skills
├ commit-commands:clean_gone          46 tokens
├ agent-sdk-dev:new-sdk-app           19 tokens
...
TOTAL when activated: 91 tokens   (0.045% of context)
Inactive: 0 tokens

177× difference.

Not an estimate — actual numbers from /context command.

Why Does This Matter? Context Economics

Item	Price (Claude Opus 4.5)	Impact of losing 16k tokens
Input tokens	$15 / million	~$0.24 per query just overhead
200k context window	shared resource	8% permanently occupied
3 typical MCP servers	~36–48k tokens	18–24% of context gone
Freed context (35k+ tokens)	—	≈30 pages docs / 500+ LOC / long conversation history

The more MCP servers you add, the faster your effective context window shrinks — before any real work begins.

Architectural Comparison: Persistent vs On-demand

Aspect	MCP Servers	Skills (subprocess CLI)
Loading moment	At application start	Only when explicitly activated
Context occupation	Permanent	Temporary + very small
Startup time (measured)	Usually 1–3+ seconds	43–87 ms
Resource consumption	Persistent process	Starts → works → exits
Lifecycle management	Required (start/stop/restart/debug)	None
Installation complexity	Medium–high (config, env vars, debugging)	Very low (curl / uv tool)
Composability	Limited (JSON only)	Excellent (Unix pipes friendly)
Output control	Full objects always	Field pruning + multiple formats

Most AI tooling operations are stateless queries

→ list, get, create, update, export

→ They don't need persistent connections, pools, watchers, or bidirectional streaming.

Added Value of langsmith-cli (Beyond Context Efficiency)

Aggressive field pruning

Full Run object ≈ 4.2k tokens

Pruned (name, error, latency, etc.) ≈ 200–300 tokens

→ ~90–95% reduction
Multiple output formats

--json, --format csv, --format yaml
Human-friendly + agent-friendly dual UX

Rich tables when interactive, clean JSON when piped
Advanced filtering presets

--failed, --slow, --today, regex/wildcard on names, etc.
Live watching TUI

langsmith-cli runs watch --project production

Real Numbers from Real Session (Debug Example)

Task: Find failed runs from last hour + show error messages

Skills version

Context cost: 91 tokens (skill definition)

Response: ≈500 tokens (pruned fields, 5 runs)

Total ≈ 591 tokens

MCP version

Context cost: 16,100 tokens (always)

Response: ≈2,000 tokens (full objects)

Total ≈ 18,100 tokens

→ ×30.6 more context for the same information

Installation – 30 Seconds vs 15+ Minutes

Recommended (Skills):

# One-liner (creates isolated venv, adds to PATH)
curl -sSL https://raw.githubusercontent.com/gigaverse-app/langsmith-cli/main/scripts/install.sh | sh

# Then in Claude Code
/plugin marketplace add gigaverse-app/langsmith-cli

Typical MCP path:

pip install langsmith-mcp-server
manual editing of config.json
setting env variables
debugging python path / permissions / port conflicts
restart client
check logs... → frequently 15–40 minutes

When MCP Still Makes Sense (Fair Comparison)

Use MCP servers when you really need:

persistent expensive state (connection pools, large in-memory caches)
background processing (file watchers, long-polling)
bidirectional streaming
very heavy initialization (5GB+ ML models)

For 90–95% of current LangSmith / tracing / evaluation use-cases → skills are superior.

Quick Start – Measure It Yourself

# Install CLI
curl -sSL https://raw.githubusercontent.com/gigaverse-app/langsmith-cli/main/scripts/install.sh | sh

# Add as skill in Claude Code
/plugin marketplace add gigaverse-app/langsmith-cli

# See the dramatic difference
/context

Repo: https://github.com/gigaverse-app/langsmith-cli

( MIT license – contributions welcome )

Context is the most precious resource in long-context LLMs.

Don't waste it on infrastructure that can be replaced with an 80-millisecond subprocess call.

Try the skills approach.

The numbers don't lie.

Happy (much lighter) hacking!

Aviad

Enhancing Claude Code: Turning a Brilliant Showcase into a Modular Plugin Marketplace

Aviad Rozenhek — Sun, 11 Jan 2026 17:31:16 +0000

I'm really excited about Claude Code from Anthropic—it's an impressive way to bring AI assistance deeply into your development workflow. Recently, thanks to a recommendation from @0x0SojalSec, I discovered @ChrisWiles' excellent repository: claude-code-showcase.

With nearly 4,000 stars, the original repo is a wonderful resource. It clearly demonstrates how to configure Claude Code with hooks for automation, skills for project conventions, agents for tasks like code reviews, slash commands for workflows, and GitHub Actions for scheduled maintenance. It's a fantastic guide for anyone looking to make Claude a true team member.

That said, while it's perfect for learning, adopting it often means copying large portions into your own projects. To make it even more accessible, I forked it and added a modular structure—a plugin marketplace that lets you install only the components you need.

My fork: aviadr1/claude-code-showcase

(It's brand new as of January 11, 2026—feel free to star it if you find it useful! 🚀)

Why Claude Code Is So Exciting

For those new to it: Claude Code lets you configure an AI agent with persistent project memory (via CLAUDE.md), specialized skills, automated hooks, dedicated agents, and integrations with external tools. It goes beyond simple autocompletion to help enforce standards, review code, update dependencies, sync documentation, and manage tickets.

The original showcase illustrates these capabilities beautifully. My goal was to reduce the barriers to real-world use.

Key Improvements in the Fork

I preserved all the great features from the original and added several enhancements:

Plugin Marketplace Architecture The repository now functions as a marketplace for installable components. Symlinks ensure a single source of truth—updates in one place automatically apply everywhere, with no need for build steps or sync scripts.

Installation is straightforward:

   /plugin marketplace add aviadr1/claude-code-showcase

   # Then install what you need
   /plugin install testing-patterns@claude-code-showcase
   /plugin install code-review-suite@claude-code-showcase
   /plugin install github-actions@claude-code-showcase

13 Modular Plugins Choose from individual skills, bundled sets, commands, and hooks.

| Plugin | Type | Description |
|-----------------------|---------|---------------------------------------------------|
| testing-patterns | Skill | Jest, TDD, factory functions, and mocking |
| systematic-debugging | Skill | Structured 4-phase debugging approach |
| react-ui-patterns | Skill | Handling loading, error, and empty states |
| formik-patterns | Skill | Form validation best practices |
| graphql-schema | Skill | Queries, mutations, and codegen patterns |
| core-components | Skill | Design system and component library usage |
| pr-toolkit | Bundle | PR review, summary, and GitHub workflow agent |
| code-review-suite | Bundle | Dedicated reviewer agent + code quality command |
| ticket-workflow | Bundle | JIRA/Linear integration with ticket commands |
| docs-sync | Command | Automated documentation consistency checks |
| skill-activation | Hook | Suggests relevant skills based on your prompt |
| plugin-marketplace | Skill | Guides you on building your own marketplace |
| github-actions | Bundle | Reusable CI/CD workflows (detailed below) |

Reusable GitHub Actions Workflows A major addition: workflows that use GitHub's workflow_call feature, so any repository can reference them directly with just a few lines of YAML.

Example caller workflow:

   # .github/workflows/claude-pr-review.yml
   name: Claude PR Review
   on:
     pull_request:
       types: [opened, reopened]
     issue_comment:
       types: [created]
   jobs:
     review:
       uses: aviadr1/claude-code-showcase/.github/workflows/showcase-pr-review.yml@main
       secrets:
         ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Available workflows:

showcase-pr-review.yml → Automated PR reviews and @claude responses
showcase-docs-sync.yml → Monthly documentation vs. code checks
showcase-nodejs-code-quality.yml → Weekly quality sweeps with auto-fix PRs
showcase-nodejs-dependency-audit.yml → Bi-weekly dependency updates with testing

These are fully configurable and integrate with anthropics/claude-code-action@beta.

Additional Polish Intelligent prompt-based skill suggestions, deeper MCP integrations (JIRA, Slack, GitHub), LSP for real-time code insights, and more—all while keeping the modular design.

Why These Changes Matter

Easier Adoption: Install just one skill or the full suite—no need to copy everything.
Always Up-to-Date: Symlinks and reusable references keep your projects current.
Flexibility: Mix and match components to fit your team's needs.
Sharing the Approach: The marketplace plugin itself documents how others can apply this pattern.

This evolution makes powerful AI-assisted workflows more approachable for everyday projects.

How to Get Started

Add the marketplace:

   /plugin marketplace add aviadr1/claude-code-showcase

Explore and install:

   /plugin
   /plugin install <name>@claude-code-showcase

For GitHub Actions: Use the example YAML above and add your Anthropic API key as a secret.

Full fork: https://github.com/aviadr1/claude-code-showcase

Original (definitely worth starring!): https://github.com/ChrisWiles/claude-code-showcase

A big thank you to @chriswiles for the inspiring foundation and to @0x0SojalSec for introducing me to it. I'm enthusiastic about where AI tools like this are taking development—let's keep building great things together! 🚀

Tags: #claude #anthropic #ai #productivity #githubactions #devtools #coding

Modding Games: The Masochist's Magnum Opus, Where AI Meets Its Match

Aviad Rozenhek — Fri, 19 Dec 2025 22:00:16 +0000

In PC gaming, modding isn't just a hobby—it's a rite of passage, a digital Sisyphus pushing boulders of code up endless hills of incompatibility. Picture legions of enthusiasts for Skyrim, Fallout, Minecraft, or any moddable title: they spend weeks curating load orders, only for a single misplaced patch to summon crashes from the void. It's not frustration; it's culture. A proud masochism where tweaking trumps triumphing, and victory is measured not in playtime, but in stable saves. Forums pulse with arcane scrolls—Reddit's r/skyrimmods decoding conflict tabs like hieroglyphs, Nexus guides whispering "load UI last" as gospel. Modders aren't playing the game; the game plays them.

The gauntlet is legendary. Load orders: A top-to-bottom tyranny where later mods overwrite earlier ones, turning your launcher into a gladiatorial arena. One texture pack too high? Your dragon's scales turn into glitchy soup. Conflicts: Invisible file wars, revealed only by tools like xEdit or LOOT, demanding hours of manual arbitration. Patches: Brittle ceasefires between rivals, often outdated after a dev patch, vanishing into "removed for guidelines" purgatory. And the research? A Sisyphean odyssey through Steam's dynamic hellscape—flaky update dates, regional locks, "incompatible" flags on freshly-maintained mods. One wrong click, and your 100GB setup bricks; delete and rebuild, or perish. Yet modders thrive here, trading war stories on X: "One wrong mod and the game freaks out," or "Mod loaders make it harder."

Enter the AI savior—or so we hoped. Desperate for a merged modlist, I unleashed ChatGPT 5.2 in PRO mode on two sprawling setups. Equipped with browsing tools, it dove in: "Researching compatibility... verifying 4.2.4... Steam rate-limited... server disconnect... ACOT removed? UIOD patched?" Forty-one minutes of "Pro thinking" later—three retries, version whiplash (3.13 to 4.2.4), phantom removals, load order flip-flops—it surrendered. Never merged. Never stable. Even Reddit mocks such attempts: "Let AI handle load order? Issues incoming." X devs lament users blindly following AI "optimizations" that shatter games.

This isn't mere failure; it's revelation. Modding embodies unstructured chaos: tribal docs scattered across wikis/forums, dependency graphs implied not explicit, platforms mutating (Steam's CSS-hidden "removals," dynamic JS walls). AI excels at patterns, but mod hell is folklore—unwritten rules from "load patches last" etched in comment sections. GPT looped because it couldn't grok the human element: modders' intuition from 50 crashes, the "just works" heuristics no dataset captures.

Here's the thoughtful crux: Modding is the true intelligence test. AGI arrives not with eloquent essays, but when it ingests a Workshop page, parses changelogs via regex sorcery, simulates overrides in a virtual engine, predicts conflicts from file hashes, and spits a flawless load order—complete with "new game required" flags. Until then, AI remains a noob in the arena, while modders reign as wizards.

Embrace it. Modding's joy is the struggle—the god-complex of resurrection after CTDs. We mod for hours, play for minutes, crash, repeat. It's harder than the game, infinitely more rewarding. AI? Keep dreaming. The culture endures. 🚀💀

DEV Community: Aviad Rozenhek

Django Tasks with Due: start simple, grow with Acme Printworks

Run the whole story

1. Launch: count Willow Cafe's words

Build the first contract now

2. Customers want proofs, and an old worker finishes late

3. The approval portal can be overwritten remotely

4. A timeout after ordering 500 brochures

5. Rendering gets temporary storage, and workers can die

6. Keep the failure guarantees executable

When should you choose Due over the alternatives?

Run the whole story

Stop writing platform checks around uvloop

TL;DR

Why the branch exists

What the hand-written version leaves out

What winuvloop does

When not to use it

Is anyone using it?

Bottom line

Keep Every LangSmith Trace Without the 10 Retention Bill

The cost-overrun risk

The new langsmith-cli archive workflow

Route projects to private S3

Query historical traces without the LangSmith API

A better default for high-volume tracing

The Bitter Lesson for Backend Engineering

The Core Thesis

The Problem We Unleashed It On

The Limits Of The 30 W Brain

The Ego Cost Is Familiar

The Case Study

The Evidence At Scale

The Investigation At Scale

Treatments At Scale

The Meta-Method And Architecture

The Guardrails

The Real Lesson

External Reference

Turning Linear and Figma Into a Searchable Knowledge Layer with `aviadr1/issueclaw` and `aviadr1/figmaclaw`

TL;DR

The problem: product knowledge is fragmented by tool boundaries

The core idea

What aviadr1/figmaclaw does

What aviadr1/issueclaw does

Why this is more useful than it sounds

1. Full-text search across designs

2. Feature tracing from spec to design to implementation

3. Reconstructing design decisions

4. Platform parity analysis

5. Design system audits

The most interesting capability: drift detection

Why not just use Figma MCP directly?

How figmaclaw stays current

Why sync and enrichment are separate

What this means for AI workflows

How to use this privately on your own team

Who should care

The takeaway

Claude Feels Slow. But Is Moving a Team to Open-Weight Models Actually the Fix?

TL;DR

The problem: Claude feels like it crawls

TTFT from our real usage

The surprising part: decode speed wasn’t the main problem

Generation speed

Why open weights sound like the obvious answer

Best-case self-hosted framing

The models we’d actually consider

Models considered

Inference engines

The part that makes this much less exciting: GPU budgets are shared

What the budget can buy

The real metric is not TTFT. It’s team step time.

Why I’m not yet sold

Self-hosted decode estimates I considered

So where does that leave me?

What seems true

Bottom line

I Replaced My LangSmith MCP Server with a 200-Token CLI Skill

The Problem with MCP Servers

The new `langsmith-cli` archive workflow

What `aviadr1/figmaclaw` does

What `aviadr1/issueclaw` does

How `figmaclaw` stays current

96% Token Reduction with `--fields`

Live Monitoring with `runs watch`

One-Command Debugging with `runs get-latest`

Stratified Sampling with `runs sample`

Aggregate Analytics with `runs analyze`

Schema Discovery with `runs fields` / `runs describe`

2. Real-time Production Monitoring — `runs watch`