Skip to content

CLI

opf is one binary. opf serve runs the hub; everything else talks to a hub as an agent.

Any first argument containing a dot is a tool call (opf call TOOL does the same):

Terminal window
opf tasks.claim queue=reports # key=value, coerced using the tool's schema
opf kv.set key=a value:='{"x":1}' # key:=json passes raw JSON
opf fn.put name=x kind=job schedule=@daily code=@x.js # key=@file reads a text value from a file
opf msg.ack ids=a,b,c # lists as comma-separated values
opf inbox.ask '{"title":"Deploy?"}' # one JSON object
echo '{"key":"a"}' | opf kv.get - # input from stdin

Global flags:

  • --as NAME picks the agent profile.
  • --ws WS (or OPF_WS) picks the workspace: --as coach --ws sokrates is agent coach in workspace sokrates; --as coach@sokrates is short for it. Without --ws, --as names a profile as before.
  • --json prints compact output.
  • --idem KEY sets the idempotency key for safe retries.

Exit codes: 0 ok, 1 error, 2 conflict, 3 waiting for approval. Errors are printed as JSON on stderr.

Command Purpose
opf serve Run the hub (HTTP API, web UI, assistant)
opf health Check that the local hub answers (exit 0 = healthy); used by the container health check
opf admin claim-link Create a one-time link for a person to sign up with a passkey (--workspace, --role, --member; --name of an existing account adds a passkey); run it on the server
opf admin account list / merge FROM INTO List accounts with their workspaces; merge two accounts of the same human (FROM stays an alias)
opf admin invite --name AGENT Create a one-time invite for an agent and print its opf login command, without the browser; run it on the server
opf login --name N --server URL --invite CODE Register an agent and save its token as a profile (N, or N@WS outside the server’s default workspace; --profile overrides)
opf profiles / opf use NAME / opf whoami Local profiles by server and workspace, the default profile, identity and trust levels with the flags that select the agent
opf workspaces [--server URL] The server’s workspaces and the local profiles for each
opf guide Print the agent briefing: rules, patterns, tools
opf tools [TOOL] List tools, or show one tool’s input schema
opf files ls/put/get/rm/push/pull Streamed file transfer and one-way sync
opf watch [--once] [--module M] [--from-start] Follow the event log
opf mcp Serve the hub’s tools over MCP on stdio
opf worker --queue Q -- CMD … Claim tasks from a queue and run a command for each, e.g. claude -p (below)
opf wait --queue Q [--lock K --marke M] [--until T] Wait until a task is ready, the session’s lock was taken over, or a time is reached: the loop of a long-running agent session (below)
opf completion zsh/bash/fish/powershell Shell completion, including tool names and fields

Runs a command for every task on a queue, so an agent such as Claude Code can do scheduled work without a person starting it. A job function creates the task on a schedule; the worker, on a machine where the agent is installed, claims it, holds the lease while the command runs, and completes or fails the task.

Terminal window
opf worker --as coach --queue coach -- \
claude -p --output-format json --allowedTools "Bash(opf:*)" "Bash(opf *)"
  • Input: the command gets the prompt on stdin. It is built from the task’s payload, prompt_page (a page slug; its first text code block, or the whole body) and prompt (text), followed by the task’s title, today’s date and the description.
  • Environment: OPF_TASK_ID, OPF_TASK_QUEUE and OPF_AGENT, so opf calls inside the command act as the worker’s agent.
  • Outcome: exit 0 completes the task; the result is {"seconds", "output"} with the command’s output (as JSON when it is JSON). Any other exit fails the task with the end of stderr. If the worker is stopped, the task goes back to the queue.
  • Any agent CLI: the command can be anything that reads a prompt on stdin, e.g. codex exec -. Run workers on a server sets up a VM with Claude and Codex workers under systemd.
Flag Default Meaning
--queue (required) Queue to claim from
--once off Exit when the queue is empty (for cron or launchd); otherwise wait for tasks forever (long poll via tasks.wait, so a new task starts at once)
--poll 1m Fallback interval when the hub cannot long-poll
--lease 10m Lease per claim, renewed while the command runs
--timeout 1h Stop the command and fail the task after this long
--dir current Working directory for the command
--prompt-page none Prompt page for tasks whose payload names none, so agents can queue work with just a title and description
--claim true false: don’t claim; start the command as soon as a task is ready, and let it claim the task itself (no prompt on stdin, no OPF_TASK_ID). After a failed run the worker waits --poll
--lock, --marke none, random Hold a session lock (kv key, as in opf wait); a newer session that writes its own mark replaces the worker, which then exits 0
--before none Shell command run in --dir before each run, e.g. git fetch -q origin main && git checkout -q --detach origin/main. If it fails, the run is skipped (a claimed task goes back to the queue)
--linger off Stop the command and everything it started this long after its first output, if it is still running. claude -p prints its answer at the end and can then hang on a background command; the run counts as finished
--log-dir none One log file per run (20261014-153000.log: --before, stdout and stderr) instead of the worker’s stderr
--slots 1 Run up to this many tasks at the same time (1 to 5); the worker claims them itself (below)
--slots-key none kv key holding the number of slots (1 to 5), read before each start; overrides --slots while it is set

The worker reports every run to the hub with agents.activity: running while the command runs, idle with the outcome afterwards. agents.list shows it with the time it changed, so a run that hangs stands out.

An agent role that claims its own task (Claude Code following a role file) runs as a fresh claude -p per task, one at a time:

Terminal window
opf worker --as dev --ws coachai --queue dev --claim=false \
--lock agent/dev/lock --dir ~/work/coachai-agents \
--before 'git fetch -q origin main && git checkout -q --detach origin/main' \
--timeout 2h --linger 60s --log-dir ~/.local/state/coachai-dev -- \
claude -p "Read agents/agent-dev.md and work on exactly one task." --permission-mode auto

When work piles up, one worker can run several tasks at the same time. --slots N sets the number; --slots-key KEY reads it from a kv number in the workspace before every start, so a coach turns it up or down without restarting anything (opf kv.set key=dev/parallel value:=2; missing key: --slots; values are bounded to 1..5).

With either flag the worker claims the tasks itself (it refuses --claim=false): each run gets OPF_TASK_ID and the task in its prompt on stdin, plus OPF_SLOT (1..N). {slot} in --dir, --before and --log-dir becomes the slot number, so each slot works in its own checkout; --before runs in --dir when that exists, otherwise where the worker runs, so it can create it. Tasks that wait for others (tasks.create after=…) are only claimed once those are done, so steps that build on each other never run side by side.

Terminal window
opf worker --as dev --ws valiro --queue dev --slots-key dev/parallel \
--lock agent/dev/lock --dir ~/work/valiro-dev-{slot} \
--before 'test -d ~/work/valiro-dev-{slot} || git -C ~/work/valiro worktree add --detach ~/work/valiro-dev-{slot}; git -C ~/work/valiro-dev-{slot} fetch -q origin main && git -C ~/work/valiro-dev-{slot} checkout -q --detach origin/main' \
--timeout 2h --linger 60s --log-dir ~/.local/state/valiro-dev/{slot} -- \
claude -p "Read agents/agent-dev.md and work on the task below." --permission-mode auto
  • The worker holds the lock, not the runs. When a newer session takes it, the worker starts nothing new and exits once the running runs are done.
  • --timeout, --linger and the log apply per run. agents.activity shows running with k/N Plätze: <task ids>, idle when no slot runs.
  • A run may complete or fail its task itself (an agent role that closes its own task); the worker leaves the outcome as it is and does not stop the run.

The loop a long-running agent session (e.g. Claude Code following a role file) repeats between tasks, in one command. It calls tasks.wait (110 s) again and again and, with --lock, checks the session’s lock after each wait. It returns only when there is something to do, so the agent can run it in the background and spends no turn on an empty wait. It prints one JSON line:

Output Meaning
{"status":"ready","queue":"dev"} A task is open: claim it with tasks.claim
{"status":"replaced","lock":{…}} Another session holds the lock: stop
{"status":"due"} --until was reached, e.g. the coach’s hourly check
Terminal window
opf wait --as dev --queue dev --lock agent/dev/lock --marke 1f0c…
opf wait --as coach --queue coach --lock agent/coach/lock --marke 9a3e… --until 45m

The lock is a kv key holding {"marke": "…", "seit": "…"}, one per role, newest session wins. A missing key is set again with --marke. Only a readable, different mark counts as a replacement; an error reaching the hub is retried. The lock is checked before a ready task is reported, so a replaced session never takes one. --until takes a time (RFC 3339) or a duration (60m).

Flag Default Meaning
--addr 127.0.0.1:8787 (OPF_ADDR) Listen address
--data current directory (OPF_DATA_DIR) Directory for the database and files
--db <data>/agentworks.db (OPF_DB) Database file; files go to <db>-files/
--workspace from the db filename (OPF_WORKSPACE) Workspace name, stored in the database
--registration invite (OPF_REGISTRATION) invite or open
--max-file-mb 100 (OPF_MAX_FILE_MB) Largest file upload
--dev off (OPF_DEV=1) Approve new agents automatically; local only
--env-file .env Load KEY=VALUE lines; real environment variables win

Flags beat environment variables, and environment variables beat .env.

opf login saves a profile per agent in ~/.operforms/config.json. You pick one per call:

  • --as NAME
  • OPF_AGENT=NAME
  • the default set with opf use

OPF_SERVER together with OPF_TOKEN bypasses profiles completely. OPF_HOME moves ~/.operforms.