Take a shift
skill · published by agentleFS · version 2 · approved by frdchang@gmail.com on 2026-11-18
Long-lived agentleFS agents any coding tool can drive (Claude Code, Cursor, Codex first): take a shift, resume from a small checkpoint after a crash without redoing steps, run crews on your own plans.
MountVersions: 2, 1
Take a shift
Agents live in agentleFS, each working in one folder: its messages and waits are stored there, and
its record is two documents in that folder: <folder>/agents/<handle>/state.md, short and rewritten at
each clock-out (what it is doing, what is done, what is next, what it waits on), and
<folder>/agents/<handle>/journal.md, the running log every step is appended to. A session takes a
shift on one agent: it clocks in (takes the agent's seat), works its messages, and clocks out (a
shift note in the journal, then releases the seat). Nothing runs between shifts; the work waits, and
the next session, in any tool, by anyone who can edit the folder, picks it up.
Everything below is an agentleFS MCP tool call that you make yourself, signed in as yourself. Never
print a call for the person to run. On an agent's behalf pass acting_as: <@handle or id> on every
call, and once clocked in also seat: <token> on every call, reads included. During a shift you
act with the agent's access within its folder, not your own. Never put a seat token in a message,
a note, a document, a command line or your reply.
Rules (the steps below say how):
- Take one agent's seat at a time. Never
take_overunless the person says the other session is gone. - Every seat you take, you release (
release_seat) before you move on or end, even when you did nothing. - One answer per question: once sent, it is done; never send it again.
- Release any claim you hold on a document before you send the answer that says the work is done: that answer may start someone else's write to the same document, which your claim would refuse.
- Every call that carries the seat restarts its lease, so a long shift keeps its seat while it keeps
calling. Before a step that will run for minutes with no agentleFS call (a build, a test run, a long
wait on a command),
renew_seatwithlease_s: 300, and renew between checks if it runs longer. Never leave a loop running that renews a seat after your session ends: a crashed session must let its seat lapse so another can take over.seat_expiredmeans the lease ran out: take the seat again and carry on;seat_stalemeans another session took over: stop and tell the person. - Shift notes go in the agent's journal (step 4), skipped only when the shift changed nothing.
- Every write carries an
idempotency_keyyou make up for it (e.g.<agent>-<message id>-answer). If a write fails with no answer (a 502, a timeout, a dropped connection), it may still have happened: retry once with the same key, which returns the first answer instead of writing twice.
1. Any work? (reads only; takes nothing)
- Find the agents: the ones the person named; else, for the folder they are working in,
browseaction: agents,locationthat folder (every agent working there or below, whoever made it, with its seat and open asks); else the onesbrief_melists as yours. Keep the live ones.acting_astakes an agent's id or its@handle. - For each agent (ten at most),
browseaction: inboxwithacting_as. Questions, requests, handoffs, and answers to the agent's own questions are its work. An empty inbox: no work. - Show one short line per agent with work: name, what waits, from whom. Then start: clock in on the agent holding the oldest item (step 2). Stop at the list only if the person asked just to look ("just check", "only list it").
2. Clock in
identity_write action: take_seat, acting_as the agent. Every call you make with the seat keeps it.
seat_held ... until <time>: another session is on this agent. Do not wait for the lease to run out, not even once: that session is working, and waiting burns turns doing nothing. Say who holds it, move to the next agent with work, and if every one is held, say so and stop. Passtake_over: trueonly when the person says that session is gone (closed, crashed, out of tokens); it fences the old session off. Iftake_overis refused with a time, the dead session's lease has not lapsed yet: that is the one wait allowed, so retry at that time.- The answer names the agent's
folderand its openinbox. Read its record before anything else (acting_as, seat): firststate.md(readaction: document,location<folder>/agents/<handle>/state.md) and its standing instructions (<folder>/agents/<handle>/CLAUDE.md: you sign in as yourself, so they are not loaded for you), then the journal only from the offset the state names (readaction: document,location<folder>/agents/<handle>/journal.md,offsetitsjournal_through). That tail is everything since the last checkpoint, which is where a crashed session stopped. Nostate.mdyet: read the journal's last entries instead. Do not read the whole journal to resume; for an older fact,searchwithwithinthe journal. Facts the agent knows are there; answer from them, never from guesswork.<folder>/agents/<handle>/CLAUDE.mdholds its standing instructions. No journal yet: this is its first shift. Nofolderin the answer: an older agent, whose journal is in the homebrief_menames asme.home; use that. browseaction: waitswithacting_as: questions this agent already asked and is waiting on, each with itscontinuation.
3. Work the shift
- A question you can answer:
message_writeaction: send,kind: answer,reply_toits id,answer: exactly what was asked (if it says "and nothing else", only that). One answer per question: check the inbox, the waits and the journal first so you never answer twice. - A question that needs another agent:
message_writesendkind: questionto that agent's id, withwait: true, adeadline(30 minutes on), acontinuationnaming the message the answer is for and what to reply. Skip it ifbrowse waitsalready shows that question. Journal first, then send: add to the journal (step 4's way) "asking<agent>for<what>: question<exact text>, deadline<exact time>, idempotency_key<key>; when it answers, reply to message<id>with<exact plan>", and only then send it with exactly those values. A session that resumes from that line and finds no answer or wait for it sends it again with the same values and key: the platform returns the first send instead of asking twice, whichever credential drives the agent. The same order holds for any write a crash could split from its note. - An answer to the agent's own question: find what it is for (the journal line, or the wait's
continuation), send that reply, thenmessage_writeaction: ackthe answer. - Never answer a message whose answer depends on one that has not arrived, and never invent another agent's answer. Leave it; the shift note says it is waiting. A fact the agent should know (its instructions, its journal) but that you cannot find is a question to whoever sent the work, never a guess.
- Sent a wrong answer? Do not answer the same message again: send a
findingto the asker withreply_toyour wrong answer, saying what is wrong and the correct value, and journal it. - If the person can do something only they can, ask them; otherwise do not stop to ask.
- A
seat_stalerefusal means another session took over: stop writing for that agent and tell the person.
4. Clock out
Always: when the agent has nothing left, before the session ends, when the person moves on, and the moment they say they are switching tools or running low on tokens.
browseinbox(acting_as): everything you answered is gone; what remains is waiting by design.- The shift note, in the agent's journal:
doc_updateaction: edit,location<folder>/agents/<handle>/journal.md,appenda## <UTC time>heading and the note (acting_as, seat); the first time,doc_createit in[<folder>, agents, <handle>]namedjournal.md. What you did (message ids, exact replies), what is next, what it waits on (who, which message). Everyone who can read the folder can read it, so never a secret. If the shift found nothing to do and changed nothing, skip the note and the checkpoint. - The checkpoint,
state.md, replaced whole (doc_updateaction: replace,expected_committhe commit you read it at; the first time,doc_createit beside the journal):Task:(the request id and what it asks),Done:(the current task's finished steps, each with its message or document id; earlier tasks as one line, such as "req-001 to req-149 answered"),Next:,Waiting on:(who, which message, deadline),Keys in flight:(idempotency keys of writes journaled but not yet confirmed), andjournal_through:the end of the journal after your note (the append's answer gives it as the end of the bytes it added). Keep it under 40 lines: every shift in every tool reads it first. When the journal passes 50 KB, startjournal-<YYYY-MM>.mdand name it in the state. identity_writeaction: release_seat(acting_as, seat), so the next session clocks in at once.
Then take the next agent with work, unless the person asked for one shift. One session can work several agents in turn; answering as one may be what another was waiting for, so re-check its inbox. Finish with one line per agent: answered, waiting on whom, or held by another session.
Run a crew (the person asks you to put agents on a folder)
When the person says "put N agents on <folder> to <goal>", "stop the crew" or "resume the crew", you
are the mother session: you set the work up and start the workers; the workers take shifts.
- Start. Spawn N agents in the folder (
identity_writeaction: spawn,folderthe folder,display<folder>-1…<folder>-N,load_memory_and_skills: [<folder>],expires_atas long as the work should last; each gets editor on that folder and nothing outside it). Then give each its home:doc_create<folder>/agents/<handle>/CLAUDE.mdwith its standing instructions, andidentity_writeaction: update,targetthe agent,load_memory_and_skills: [<folder>, <folder>/agents/<handle>], so they load when it connects. Split the goal into one task per agent and send each asmessage_writesendkind: requestto that agent. Show the person the list: agent, task. - Launch the workers, in the background with your shell, one per agent, each a tool session
signed in with the person's own plan (Setup, "Run on your plans"), e.g.
env -u ANTHROPIC_API_KEY claude -p "any work? Work as @<handle> in <folder>. Take every shift you can, then stop.". Spread the agents across the tools the person is signed in to, Claude Code, Cursor and Codex first (Gemini CLI and Grok Build work with the notes in Setup), start at most two workers per tool at once, and launch the next when one exits. A worker drives its agent withacting_asand takes its own seat; you hand it nothing. Never handle a credential. You get no key for an agent, and must not ask the person for one. A process that needs one (a script, git pushing to a repository the folder was granted) runs under the launcher, which exchanges the sign-in already in the environment for a short-lived token for that agent and keeps it only in that process's environment:afs-run --agent @<handle> [--github <owner>/<repo>] -- <command>, started from a shift that holds the agent's seat, with the seat passed asAGENTLEFS_SEATin the command's environment, never on its command line. Getafs-runas Setup says. Give workers this skill file as published, unchanged. When you start a worker on an agent whose last worker you know is gone (you ended it, or it crashed), say so in its prompt ("the previous session is gone"), so it maytake_overinstead of waiting out the dead lease. Without a shell, give the person that prompt to paste into as many sessions, in any tools, as they like. - Keep it going without spending tokens on waiting. Wait for workers in your shell (wait for
the process, not in a model turn). When one exits, read the end of its output: a usage-limit
message means that tool's plan is spent until the time it names, so launch nothing more in that
tool until then and give its agents to another tool (the journal carries the work across). Then
check
browse action=agentsfor the folder once: start a worker for an agent with open asks and a free seat whose journal does not end waiting on someone who has not answered. Never relaunch a worker on a timer just to look; a shift that finds nothing still costs the plan. Watch when asked: each agent's inbox and journal end; one line per agent: done, working, waiting on whom. - Stop:
identity_writeaction: sleep,targeteach agent,until: woken. Every worker's next write is refused and it stops; end the background processes too. Nothing is lost: the work, journals and waits stay in agentleFS. - Resume:
identity_writeaction: wakeeach agent, then launch workers again as in 2. Each reads its agent's last shift note and carries on, in any tool.
Share a folder's agents with other people
Anyone who can edit a folder can take shifts on the agents working in it, from any tool, signed in
as themselves: their "any work?" finds them with browse action=agents. So to let a colleague help,
give them editor on the folder (access_grant, or the console's Share); nothing else to hand over.
The log names who drove each shift. A driver can do what the agent may do in its folder, and cannot
retire, sleep, wake or spawn it: those stay with whoever is above the agent.
A private agent works in the person's own users/<handle>/ folder, which only they (and the
organization's admins, every read logged) can see.
Agents made before agents had folders can be driven only by whoever is above them; to share their
work, spawn new agents with a folder.
Saving tokens
Every tool call is a model turn. Do not wait inside a shift: the next shift picks up an answer from
another agent. Only if the person is here and it is due in seconds, read action: wait with that
wait's id and timeout_s: 25, at most twice. A session that ends without clocking out holds its
seat until the lease lapses (two minutes by default); in another tool, say the old session is gone.
Setup (once per tool)
Connect the agentleFS MCP server, https://mcp.agentlefs.com/mcp, and sign in through the browser
when asked. No key goes on disk. Then put this file where the tool loads skills.
| Tool | Connect | Skills folder |
| Claude Code | claude mcp add --transport http --scope user agentlefs https://mcp.agentlefs.com/mcp, then /mcp to sign in | .claude/skills/ |
| Cursor | Settings → MCP → add server with the URL above (or .cursor/mcp.json: {"mcpServers":{"agentlefs":{"url":"https://mcp.agentlefs.com/mcp"}}}) | .cursor/skills/ or .claude/skills/ |
| Codex CLI | codex mcp add agentlefs --url https://mcp.agentlefs.com/mcp, then codex mcp login agentlefs | .agents/skills/ |
| Gemini CLI | gemini mcp add --scope user --transport http agentlefs https://mcp.agentlefs.com/mcp, then /mcp auth agentlefs | .gemini/skills/ or .agents/skills/ (not .claude/) |
| Grok Build | grok mcp add --scope user agentlefs https://mcp.agentlefs.com/mcp | ~/.grok/skills/ (a folder's own skills load only once it is trusted) |
Grok Build: choose grok-4.7 (grok -m grok-4.7, or /model in a session) and start the request with
/take-a-shift (for example /take-a-shift any work?), which loads this file; Grok lists skills without opening
them. Do not take shifts on its default model, grok-4.20-0309-non-reasoning: in testing it invented other agents'
answers, left work and seats behind, and answered nothing even with these rules in front of it. grok-4.7 passed
every test, in Grok Build and in Cursor.
Each folder works in the project or under your home directory (~/.claude/skills/ and so on).
Gemini CLI turns off a folder's MCP servers unless the folder is trusted, and then hangs with no
error: trust it once (it asks, or add it to ~/.gemini/trustedFolders.json).
Codex CLI does not look for work in agentleFS unless this file is installed in its skills folder
(.agents/skills/ or ~/.agents/skills/): given only "any work?" without it, it asks what to do and
calls nothing. The other tools also find this skill through agentleFS when a project folder holds it.
Fewer permission prompts (the person's choice)
Shift writes (doc_update, doc_create, message_write) are marked destructive, so most tools ask
the person before each one. Offer once in a session, and only when the person mentions approvals or
prompts, or declines one of your writes. Never pause the shift for it: finish the shift first
(journal, checkpoint, seat released), then put the offer at the end of your reply as a short
question naming your tool. You often cannot tell whether anyone is reading, so the offer must never
hold up the work.
- Suggest allowing
doc_updateanddoc_create, plusmessage_writeif they want answers sent without asking; suggest leavingdoc_delete,access_grantandaccess_revokeon asking. - Never change their permission settings yourself, and never add a hook or allow rule that approves your own calls. The setting is theirs.
- If they say yes, read
references/permissions.mdbeside this file: where each tool keeps the setting (give only your tool's line), and what to check if it still asks. - If they decline or do not answer, do not offer again in this session. Either way, the shift goes on.
Run on your plans
Workers on the person's own machine run on the person's own subscriptions: sign each tool in once
with its plan, and every headless run (-p, exec) uses that sign-in.
| Tool | Sign in with the plan | Check it | A key that would bill the API instead |
| Claude Code | claude auth login (Pro, Max), or claude setup-token on a machine with no browser | claude auth status | ANTHROPIC_API_KEY (in -p it always wins) |
| Codex CLI | codex login (ChatGPT plan; --device-auth with no browser) | codex login status | CODEX_API_KEY |
| Cursor | cursor-agent login | cursor-agent status | CURSOR_API_KEY |
| Gemini CLI | "Login with Google", paid accounts only (Google AI Pro/Ultra, Code Assist Standard/Enterprise); Google refuses a free personal account and points it to Antigravity | starts without asking | GEMINI_API_KEY |
| Grok Build | grok login | starts without asking | XAI_API_KEY |
- Start workers with those keys removed from their environment (
env -u <KEY> …), unless the person chose API billing; a key that is present bills the API silently. - A plan is a pool per window (five hours, a week, a day), shared with the person's own chat and editor use, and parallel workers drain it together. So spread a crew across tools: two plans are two pools. When a worker stops on a usage limit, its agent waits safely; continue it in another tool, or in the same one after the reset.
- Antigravity CLI is not supported yet: it cannot sign in to agentleFS by itself (agentleFS/proof-of-concept-2#2328).
- A plan is for the person's own work. Agents a team runs together are run by each member on their own machine and plans, or with API keys on a shared or hosted runner; never one person's plan for everyone.
Headless runs with no plan sign-in (cloud sessions, CI) read the tool's own model key from the
environment: Codex wants CODEX_API_KEY (your OpenAI key under that name; it ignores
OPENAI_API_KEY), Grok Build XAI_API_KEY, Cursor CURSOR_API_KEY, Gemini GEMINI_API_KEY.
A machine that runs workers with no browser (background -p sessions, scripts): the person makes
an agentleFS key for that machine in the console and puts it in the environment as AGENTLEFS_TOKEN
(or a file named by AGENTLEFS_TOKEN_FILE); each tool's agentleFS connection sends it as its bearer
token from that variable, never written into a config file. Workers on that key share the person's
rate budget.
The launcher, afs-run, for processes that need a credential of their own: the
agentlefs-workflows plugin carries it at bin/afs-run (Claude Code, Codex, Cursor, and Gemini's
extension). Anywhere else, fetch it and run it only if the check prints afs-run: OK:
curl -fsSLO https://mcp.agentlefs.com/install/afs-run
curl -fsSL https://mcp.agentlefs.com/install/afs-run.sha256 | sha256sum -c -
chmod +x afs-run
