Ephemeral-AI-LabEphemeral-AI-Lab/layerfs/.agents/skills/layerfs-sdk-observe/SKILL.md

layerfs-sdk-observe

Skill2.1k starsChanged 8 days agoMITView on GitHub

Use when observing, measuring or troubleshooting a LayerFS run rather than doing the work itself. Activates on the LayerFS call trace (`LAYERFS_TRACE`, `LAYERFS_TRACE_STEP`), SDK operation timing and phase breakdowns, LayerFS storage deduplication and compression over history, `@layerfs/backend` (`store.project.get_storage`, `store.branch.list_commit_storage`, `store.fs.list_revisions`, `daemon.workspace.status`, `daemon.workspace.get_storage`, `daemon.process.*`, `daemon.sandbox.get_log`), or LayerFS daemon logs and observation records.

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Before the run, set LAYERFS_TRACE=<run>/trace.jsonl for every process.
line 27
Very specific:
After the run, while its Sandboxes still run (each closes itself two minutes after its last Workspace is unmounted): page …
line 32
Distinctive:
Treat every number as diagnostic: one run, tracing on, no cache control.
line 40

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Observing a LayerFS run

Status: Current general guide. For whoever watches or troubleshoots a LayerFS run (an orchestrator, a maintainer), not for an agent doing the work. Using the SDK is the separate layerfs-js-sdk skill.

This skill uses internal surfaces: the @layerfs/backend package, the opt-in call trace and the daemon's diagnostic records. None of them changes the project. Don't hand them to an agent doing production work.

Question	Source	Page
How long did each SDK call take, and which phase was slow?	Call trace (`LAYERFS_TRACE`) with phase timing	tracing
Is storage deduplicating and compressing over a long history, or blowing up?	`backend.store.project.get_storage`, `backend.store.branch.list_commit_storage`, trace `sizes`	storage metrics
What did the Store, SQLite, locks and FUSE do during a call?	Daemon records from `backend.daemon.sandbox.get_log` (or `docker logs`), decoded and joined to the trace	daemon logs
Is a Workspace behind its Branch, what does it hold uncommitted, what is a file's history, which background processes run?	Backend methods	backend

Collecting a run

For an agent run you want to analyse afterwards:

Before the run, set LAYERFS_TRACE=<run>/trace.jsonl for every process. Ask the agent to set LAYERFS_TRACE_STEP on each command it runs.
Record identities: LayerFS commit, daemon binary, runtime image digest, addon build.
Snapshot backend.store.project.get_storage() at the start, every N Commits if you can, and at the end.
After the run, while its Sandboxes still run (each closes itself two minutes after its last Workspace is unmounted): page backend.store.branch.list_commit_storage(branch) for every Branch, and save each Sandbox's daemon log with backend.daemon.sandbox.get_log(sandbox, { lines: 2000 }) (see daemon logs).
Decode and join: see daemon logs. Build the per-step table: see storage metrics.

Treat every number as diagnostic: one run, tracing on, no cache control. It is not a benchmark measurement.

Download now (ZIP)

Oct 30, 2026[探讨] LayerFS 作为非 Git 目录的任务工作副本后端 — holon-run/holon0 reactions
Oct 29, 2026Evaluate agent workspace tools together with LayerFS (item 70) — acg-box/decodex0 reactions
Oct 28, 2026FUSE: umount2 detach does not wake blocked readers while another mount namespace holds the superblock (kernel 7.2.9-orbstack) — orbstack/orbstack0 reactions
Oct 24, 2026Fix Linux-only native build and Conflict unmount sample — earsonlau/layerfs-cursor-agents0 reactions
Oct 21, 2026[Agent Runtime] 评估 LayerFS 作为并行 agent 工作区（暂不接入） — suainam/mac-bootstrap-template0 reactions

1 more on GitHub

Sep 10, 2026feat：LayerFS 作为 workspace-checkpoint（工作区检查点）/ 并行探索候选引擎的评估 — StrayDragon/xylitol0 reactions

On Bluesky · 2

Oct 19, 2026LayerFS: a Git-like environment for agents it’s extremely fast, because it uses Linux’ layered filesystems to avoid any file copies for… — @timkellogg.me86 likes and reposts · 8 replies
Oct 26, 2026LayerFS : un système de fichiers qui donne à chacun de vos agents un Workspace complet et modifiable, posé sur un historique partagé, sans… — @camilleroux.com2 likes and reposts · 2 replies

In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- core/AGENTS.mdAGENTS.md
- layerfs-js-sdkSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free