logicsrc/packages/openfleet

@logicsrc/openfleet

Reference implementation of OpenFleet, the record an agent session carries about where it sits: which human answers for it, who spawned it, for what task, at what depth, and under what ceiling. A fleet is every agent session one human, its sysop, is answerable for. A swarm is the set of sessions one spawner starts to do one task.

This package holds the record, the ledger, the ceiling rules, claiming and deriving, the folded tree, the five sysop verbs, and the Claude Code hooks. moshcode writes the same files from moshcode swarm and reads them with moshcode fleet; one tree shows both engines.

Install

npm install -g @logicsrc/cli
logicsrc fleet --help

The verbs live in this package and the umbrella CLI wraps them as logicsrc fleet. To use the library directly:

npm install @logicsrc/openfleet

The files

Everything lives under $OPENFLEET_HOME, default ~/.openfleet:

Path	What
fleets/<fleet>/members/<member>.json	One record per member, written before it starts, never changed after member.start.
fleets/<fleet>/ledger.jsonl	The append-only ledger for this host. ledger.<host>.jsonl copies from other hosts are merged by at.
fleets/<fleet>/marks/<event>.<id>	Once-markers for member.start, member.end and swarm.end, so two writers never double a line.
current	The fleet the account's next root member joins. Absent means the implicit <user>@<host>.
sessions/<session_id>.json	The Claude Code hooks' own lookup, not part of the spec.

Files are 0600 and directories 0700.

The five verbs

# Sysop only: mint a fleet, set its whole ceiling, write fleet.open and current.
logicsrc fleet open team --approvals bypass --budget "20 USD" --depth 2 --fan-out 4 --hosts dev,netcup --until 2h

# Sysop only: set a fleet's whole ceiling, or narrow a running swarm's. Members now above it are stopped.
logicsrc fleet cap team-20260913 --approvals native
logicsrc fleet cap create-two-0541 --fan-out 2

# Anyone: the tree, from the ledger, the records and the engine rosters. Run by the sysop it also
# stops what is past its deadline or over its budget (rule 6) and marks lost what its engine no longer lists.
logicsrc fleet tree
logicsrc fleet tree anthony@dev --json

# Anyone, within reach: end a member, a swarm (nested swarms first), or a whole fleet through each member's engine.
logicsrc fleet stop create-two-0541
logicsrc fleet stop team-20260913 --fleet

# Anyone: the ledger, in order, with who did it.
logicsrc fleet log --swarm create-two-0541
logicsrc fleet log --since 2h --json

Every verb takes --json. open and cap refuse with exit 4 when the process carries OPENFLEET_MEMBER: that process is an agent. stop refuses outside the caller's own subtree the same way. An engine that will not end a member leaves it without an end line and the verb exits 3.

stop goes through the member's own engine: claude stop <job id> for claude-code, moshcode herd kill for moshcode/*, tmux kill-pane for tmux, a signal to the pid for claude-p.

Claude Code hooks

logicsrc fleet hooks install    # merges five entries into ~/.claude/settings.json, never clobbers
logicsrc fleet hooks status
logicsrc fleet hooks remove     # takes out only ours

With the hooks installed every Claude Code session becomes a recorded member: SessionStart claims the record OPENFLEET_RECORD names, derives a child under a claimed one, or writes a root record; UserPromptSubmit checks the ceiling with the permission mode the engine reports and writes member.start, or refuses the first prompt with exit 2; PreToolUse denies an Edit or Write outside piece.owns; Stop and SessionEnd write member.end. A hook never fails the engine. logicsrc fleet hook <Event> is the entry point the settings file calls.

Environment

Variable	Meaning
OPENFLEET_HOME	The root directory. Default ~/.openfleet.
OPENFLEET_RECORD	The absolute path of this member's record.
OPENFLEET_FLEET	A copy of the record's fleet; in the sysop's shell, the fleet new roots join.
OPENFLEET_MEMBER	A copy of the record's member. Present means this process is an agent.
OPENFLEET_SWARM	A copy of the record's swarm, when it carries one.

Library

import { context, claimOrDerive, startMember, endMember, fold, renderTree, readLedger } from "@logicsrc/openfleet";
import { registerOpenFleetCommands } from "@logicsrc/openfleet/commands";

context(env) answers which fleet and which member a process is. claimOrDerive is the engine-side rule from the spec's "Claiming and deriving". fold builds the tree tree renders. registerOpenFleetCommands(command, deps) mounts the verbs on a commander command with every world-touching dependency injectable.

License

MIT. The specification text is CC BY 4.0.