Writing a dev CLI
devsess doesn’t wrap effect/cli for you — you write a stock Command.make(...), and devsess gives you services and layers that plug into it: a session directory that survives restarts, a sticky port, managed subprocesses, and cross-package running signals.
Building the command
// scripts/dev.ts
import { CurrentSession, DevSessions, getStickyPort, runManagedSubprocess } from 'devsess'
import { NodeRuntime, NodeServices } from '@effect/platform-node'
import { Effect } from 'effect'
import { Command } from 'effect/cli'
const web = Command.make('web', {}, () =>
Effect.gen(function* () {
// the interesting part goes here
}).pipe(Effect.provide(CurrentSession.layer)),
)
Command.run(web, { version: '0.1.0' }).pipe(
Effect.provide(DevSessions.layer),
Effect.provide(NodeServices.layer),
Effect.scoped,
NodeRuntime.runMain,
)
Command.make(name, config, handler)andCommand.run(command, { version })are plaineffect/cli— nothing devsess-specific.nameshows in--help;configis your flags (see Flags);versionis whatever--versionshould print.DevSessions.layerprovides the session store, rooted at your project — see Dev sessions for how that root gets picked.CurrentSession.layerprovides the resolved session for this run — but only around the handler, not aroundCommand.run. See below for why.NodeServices.layer(or@effect/platform-bun’sBunServices.layer) supplies theFileSystem/Path/ChildProcessSpawner/etc. devsess andeffect/clineed underneath. devsess depends on neither platform package itself — you supply whichever one you run scripts with.Effect.scopedis yours to add — see One scope for the whole run.
Full types are in the API reference.
Why CurrentSession.layer sits on the handler
CurrentSession resolves (or creates) a session via DevSessions#getLatestOrCreate, cached for the run — yield* CurrentSession twice in one handler resolves the identical session both times.
Provide it around each command’s own handler:
const web = Command.make('web', {}, () =>
myHandler.pipe(Effect.provide(CurrentSession.layer)),
)
not around Command.run:
// don't do this — resolves (and creates) a session for --help too
Command.run(web, { version: '0.1.0' }).pipe(
Effect.provide(CurrentSession.layer),
Effect.provide(DevSessions.layer),
// ...
)
A Layer’s build effect runs the moment it’s provided, regardless of what the effect it wraps ends up doing. Wrapping the whole Command.run call means that build effect runs before argv parsing has even decided whether this invocation is --help, --version, or a bad flag — none of which ever reach a handler. Scoping CurrentSession.layer to the handler is what keeps those from creating a session at all. If you have more than one command, provide it around each handler that needs it.
CurrentSession.layerOf(session) pins an explicit session instead of resolving one — useful in tests.
Flags
Command.make’s second argument takes effect/cli’s Flags directly:
import { CurrentSession } from 'devsess'
import { Effect } from 'effect'
import { Command, Flag } from 'effect/cli'
const web = Command.make(
'web',
{
lite: Flag.Boolean('lite').pipe(
Flag.withDescription('Use a per-session PGlite database'),
),
},
(opts) =>
Effect.gen(function* () {
if (opts.lite) {
// ...
}
}).pipe(Effect.provide(CurrentSession.layer)),
)
Each key in the config becomes a property on the handler’s argument — here, opts.lite.
Dev sessions
A session is a directory that outlives your script. CurrentSession resolves to it, and getStickyPort/SessionState (below) read and write inside it.
DevSessions itself also exposes dir (the resolved project root) and path(relative) (joins onto that root, not into any session) — useful for reaching a project file, like a Drizzle migrations folder, without your own node:path import. See A database per session.
Where a session lives
It lives at <root>/.data/sessions/<slug>/ — <slug> a single generated noun, like walrus or piano, not a name you choose.
- my-app/
- .data/
- sessions/
- walrus/ — the current session
- sess.json — sticky port and any SessionState slots
- pglite/ — a per-session PGlite database directory
- piano/ — an older session, now idle
- walrus/ — the current session
- running.json — cross-package signal, not session-scoped
- sessions/
- scripts/
- dev.ts
- .data/
<root> is whatever DevSessions.layer resolved. It walks up from process.cwd() to the nearest ancestor containing a package.json — in a monorepo, running your script from apps/web resolves to apps/web, not the repo root. If no ancestor has one, it fails with ProjectRootNotFoundError (naming the directory it started the search from) instead of silently falling back to process.cwd() — a wrong root means sessions get written somewhere surprising. Pass an explicit root instead with DevSessions.layerAt(rootDir) if you don’t want auto-detection.
How a session gets picked
Every resolution of CurrentSession tries to reuse the last session — the one most recently touched — or creates a new one with a random slug if none exist yet. There’s no flag to choose a specific session: whichever one you touched last is the one you get.
That’s enough for isolation. Every checkout — every git worktree — auto-detects its own root, so its own .data/sessions/ tree. Two agents working in two worktrees never draw from the same pool of sessions, so they never collide: each gets its own port, its own database. Isolation comes from running two different checkouts, not from any session-switching feature inside devsess.
You can create more sessions yourself with DevSessions#createSession, but CurrentSession still always resolves the newest one. An idle session, like piano above, just waits until it happens to become the newest again.
What lives inside a session
SessionState.slot(schema) gives you { read(session), write(session, data) } for a schema you define. Every slot — yours and the library’s own — reads and writes the same file: <session>/sess.json. write shallow-merges your data into whatever’s already there, so distinct slots coexist as long as their keys don’t collide. If two slots use the same key, whichever writes last wins, silently.
import { CurrentSession, SessionState } from 'devsess'
import { Schema } from 'effect'
const LastBranch = SessionState.slot(Schema.Struct({ branch: Schema.String }))
// inside a handler, with CurrentSession.layer provided:
const session = yield* CurrentSession
const state = yield* LastBranch.read(session)
// { branch: string } | null
yield* LastBranch.write(session, { branch: 'main' })
read resolves to T | null, not an Option. null covers two different cases — the file doesn’t exist yet, or it exists but fails to decode against your schema — so treat it as “nothing usable here,” not as “definitely missing.”
Running signals — the mechanism behind publishRunning/awaitRunning — aren’t part of a session at all. They read and write a file scoped to the project root (DevSessions#dir), not any session directory, so a fresh session doesn’t reset them. See Wiring services together.
One scope for the whole run
runManagedSubprocess and publishRunning both register cleanup — “kill this child,” “delete this signal file” — against whatever scope is open when they run. Effect.scoped opens one; wrap it around Command.run(...) itself, not around an individual handler, so every command shares the same scope for as long as the process is alive.
A scope is a lifetime. Effects can register a release action against it — “run this when the scope closes” — and the scope guarantees that release runs exactly once, whether the effect inside finishes normally, fails, or gets interrupted (your Ctrl-C). Put Effect.scoped around the outermost pipeline and it stays open for as long as your script is alive; put it around just a handler instead and cleanup fires the moment that one handler returns, not when the process actually exits.
That’s the mechanism behind two other pages: Running your dev server registers “kill this child” against this scope, and Wiring services together registers “delete this signal file” the same way. Neither depends on your handler doing cleanup itself — the scope closing does it, on a normal exit, a thrown error, or Ctrl-C alike.
Gotchas
session.path(rel) doesn’t create the directory. It resolves a path inside the session and returns it as an Effect<string> — pure path math, no directory or file gets created as a side effect.
import { CurrentSession } from 'devsess'
import { FileSystem } from 'effect/FileSystem'
// inside a handler
const session = yield* CurrentSession
const fs = yield* FileSystem
const dir = yield* session.path('pglite')
// '/my-app/.data/sessions/walrus/pglite'
yield* fs.makeDirectory(dir, { recursive: true })
Skip the makeDirectory call and anything that assumes the path already exists on disk — writing a file under it, pointing a subprocess at it — fails.
“Most recently touched” is filesystem mtime, not a bookkeeping record. There’s no separate “last active” field. A subprocess writing into the directory, a SessionState.write call, anything that touches the session directory refreshes its mtime and keeps it the one CurrentSession resolves next.
SessionState.write isn’t atomic. There’s no temp-file-and-rename step. A sess.json corrupted mid-write makes the next write fail with a SessionStateError (devsess’s tagged error for unparseable session state) — read keeps degrading the same corruption to null instead.