DSH plugin startup cost: five things in apply that slow boot
Almost all of a plugin's startup cost sits in the small synchronous stretch called apply. The framework pushes a plugin from PENDING to LOADING to ACTIVE, and apply is the only part of that path you write. Slow code there makes the whole boot slow, whether the plugin calls itself DSH plugin or something else.
DSH plugin boot chain: where apply sits
Order comes from the dependency graph, not from the order of lines in cordis.yml. (source)
Three states matter for startup cost:
- PENDING — the plugin is declared, but services listed in
injectare not ready, so apply has not run. - LOADING — dependencies are satisfied and the framework is executing apply.
- ACTIVE — the plugin is running and can serve other plugins.
Two consequences follow. First, slow boot may be waiting rather than computing: an upstream plugin that never provides its service keeps everything downstream in PENDING. Second, every synchronous line in apply is on the boot path, including file reads, connection setup, and directory scans.
One detail is easy to miss: ctx.plugin() gives a child plugin its own Fiber, but the child's apply still runs inside the parent's startup window. Adding "just a small plugin" can therefore lengthen the parent's boot too.
That also explains why reordering cordis.yml often changes nothing. Line order decides when a declaration appears; service dependencies decide who runs first. Moving your plugin to the top of the file still leaves it waiting for upstream services.
A related trap is assuming a service exists because it is listed in the same file. Declaration order is not a readiness guarantee, and the plugin will sit in PENDING until the provider's own apply finishes.
Five patterns that slow DSH plugin boot
The same code is harmless at runtime and expensive in apply. (source)
- Synchronous file work — reading templates, loading word lists, scanning skill directories. Expect boot time to grow with the number of files, especially on a cold disk.
- Heavy module-level initialization — constructing large objects or SDK clients at import time. Expect to pay before the plugin is even enabled, because the module loads first.
- Full scans in apply — walking every session, plugin, or history entry to build an index. Expect boot time to track data size, even though none of that data is needed yet.
- Synchronous waiting — spin loops, sleep, or a blocking HTTP call. Expect a pegged CPU with no log output, and even diagnostic commands stalling.
- Module-level side effects — starting timers or mutating globals at import. Expect residue after unload and duplicates after each hot reload.
What these share is not a particular API but a category error: work that must happen at startup mixed with work that can happen later. The test is simple. If this step fails, can the plugin still register its capabilities? If yes, move it out.
Three ways to move work out of DSH plugin apply
Moving work out is not skipping initialization; it is choosing when it happens. (source)
- Run it asynchronously inside
ctx.effect— the effect registers the resource and returns a disposer, so async setup has an owner and a teardown path. - Load lazily on first use — register capabilities in apply, but defer reading files or building caches until the first call. The first request is slower; boot is unaffected by data size.
- Drive it from an event or a background job — index building or directory scanning starts after some event, leaving only a registration behind during boot.
All three preserve cleanup semantics. They differ in first-frame experience: an effect runs shortly after boot, lazy loading spreads the cost to usage points, and a background job leaves the startup window entirely.
How to measure DSH plugin startup time
Separate waiting from computing before optimizing anything. (source)
- Instrument — log a timestamp at the start and end of apply to get your own number instead of guessing.
- Compare — measure an empty plugin that only logs, then swap in yours; the difference is your startup tax.
- Read the state — a plugin that stays in PENDING is waiting on dependencies; one that enters LOADING and lingers is slow inside apply.
- Measure cold — with HMR on, every save re-runs apply, so take numbers from a cold start or you will double-count.
Step 3 is where most debugging goes wrong. PENDING is a dependency problem, and optimizing apply will not help; conversely, treating a dependency problem as slow code leads to pointless refactoring.
Hot reload charges the DSH plugin boot cost again
HMR unloads the old instance and runs a new apply, so heavy work is paid on every save. (source)
The documented sequence is unload with full cleanup, reload the code, then execute the new apply. Registrations do not survive, which is good for state hygiene and bad for anyone who put synchronous setup in apply: it runs again each time.
So the same code is charged once on a cold boot and hundreds of times during development. Moving the work out shortens the gap between save and effect, which is far more noticeable than any abstract "startup optimization".
One inverse symptom is worth knowing: if a feature sometimes fails to appear right after a reload, suspect async setup that has not finished rather than a broken HMR. Nothing between unload and reload waits for your initialization.
A five-point DSH plugin startup self-check
Run this before shipping; it is cheaper than diagnosing after rollout. (source)
- For each line in apply, ask whether the plugin could still register its capabilities without it. Keep only what must stay.
- Look for module-level side effects, especially constructors, connections, and timers.
- Look for full scans over data that the first request does not need.
- Look for synchronous I/O or blocking waits, and consider async effects or lazy loading instead.
- Check that every resource you create has a disposer, so leaks do not ride along with slow startup.
Verification: a three-step comparison
Change one thing at a time on one machine, or you cannot attribute the cost. (source)
- Boot with an empty plugin and record the time from process start to a usable UI as the baseline.
- Add a synchronous read of a large file or a blocking wait in apply, restart, and assert the time clearly exceeds the baseline while the plugin enters LOADING.
- Move that logic into an async
ctx.effectcallback, restart, and assert boot returns near baseline while the feature still works shortly after. - Stop the provider of a required service, restart, and assert the plugin sits in PENDING rather than LOADING, which proves you can tell the two kinds of slow apart.
If the feature is missing after step 3, check whether anything actually consumes the async result; moving code without awaiting or reacting to it is not a fix.
For the unload side, read cleanup order and reverse disposers; if the plugin never loads at all, start with common plugin errors.
One line to close: startup is decided by the dependency graph plus the synchronous part of apply, so move heavy work into effects, lazy loading, or background jobs, then measure with PENDING and LOADING separated.
FAQ
DSH plugin apply is synchronous, and the framework will not wait for you. Schedule async setup inside ctx.effect and return a disposer, so the loading phase only registers capabilities. Anything slow then runs after activation instead of blocking boot.
For DSH plugin boot time, look at the Fiber state first. A plugin stuck in PENDING is waiting for a required service, not running your apply; staying in LOADING for a long time points at synchronous work inside apply. Treating those two as one problem sends you optimizing the wrong file.
DSH plugin disposers run in reverse registration order, and async ones run concurrently. Put cleanup steps that depend on each other inside a single effect disposer that awaits them in sequence, because the framework does not guarantee one-by-one completion.
DSH plugin HMR unloads the old instance, clears its registrations, then loads new code and runs apply again. Anything synchronous in apply is paid on every save, which is why moving heavy work out makes the reload loop feel instant.
Related Terms
- Fiber
- Fiber is the lifecycle scope Cordis creates for each loaded plugin, moving through PENDING, LOADING, and ACTIVE, with FAILED when apply throws.— DeepSeek Harness reference - Plugins and lifecycle
- apply
- apply is the synchronous entry of a DSH plugin; the framework calls it during LOADING, after injected services are ready, and you register capabilities there.— DeepSeek Harness reference - Your first plugin
- PENDING
- PENDING is the state of a declared plugin whose required services are not ready yet, so apply has not run and the plugin is only waiting on inject.— DeepSeek Harness reference - Plugins and lifecycle
- ctx.effect
- ctx.effect is the registration API for a custom resource; the disposer it takes, which the framework calls on unload to close connections or clear timers.— DeepSeek Harness reference - Plugins and lifecycle
Sources
- DeepSeek Harness reference - Plugins and lifecycle· deepseek-ai
- DeepSeek Harness reference - Your first plugin· deepseek-ai