WorkForce

Pre-release (0.1.x). Part of the ProtocolCity suite with WorkLane and BluePrint. Expect sharp edges; file issues.

Employment infrastructure for agents.

WorkForce turns AI agents into a staffed workforce. Each worker has identity papers (a contract and a prompt), a schedule, a budget, and a tamper-evident shift ledger. One daemon dispatches every shift; the Roster — visual in the BluePrint suite, queryable via CLI and MCP — shows who is employed, who is on the floor, and what every shift cost.

Install the whole suite (recommended)

brew install protocolcity/tap/blueprint
blueprint setup ~/my-city
blueprint serve --root ~/my-city --with-engines
# → http://127.0.0.1:8801/  (Map · Desk · Roster)

WorkForce alone

pip install protocolcity-workforce

workforce roster                     # who is employed
workforce dispatch <worker> --dry-run   # rehearse one shift, spend nothing
workforce ledger <worker>            # the shift record
workforce daemon                     # the scheduler — the only OS service you run
workforce-mcp                        # stdio MCP for chat agents

MCP (chat agents)

# Point at a city roster (BluePrint path):
export WORKFORCE_ROSTER=~/my-city/.protocolcity/workforce/local/roster.json
# or: export WORKFORCE_DATA_DIR=~/my-city/.protocolcity/workforce
python -m workforce.mcp --author you
# tools: wf_status · wf_roster · wf_show · wf_hire · wf_dispatch

Wire next to WorkLane MCP (python -m worklane.mcp / worklane-mcp) so agents can hire and dispatch as well as file work orders. Prefer dry_run=true on hire/dispatch until you trust the seat.

Part of the ProtocolCity suite: pairs naturally with WorkLane (the ticket desk your workers pull work from), and runs standalone against any queue that can answer a ready-count URL. Everything is local-first — the roster is a JSON file on your machine, the ledger is an append-only record, and there is no cloud dependency.

Quickstart (same as alone)

pip install protocolcity-workforce

workforce roster
workforce dispatch <worker> --dry-run
workforce ledger <worker>
workforce daemon

How it works

• The roster is data. Start from roster.example.json and keep your real roster at local/roster.json (gitignored) or point $WORKFORCE_ROSTER at it. One row per worker: identity, contract path, model, cron schedule, budget, queue URL.
• Workers claim tickets, then work them. A worker is bound to one working directory and pulls from its queue — a WorkLane ready-endpoint works out of the box, but any URL that returns a count will do. Empty queue means the shift is skipped, not billed.
• Every shift lands in the ledger. Outcome, passes, tokens in/out, and cost are appended per shift — the record your budgets and reports read.
• Schedules are data, not services. The daemon is the only OS service you run (workforce daemon-plist prints a launchd agent for macOS); hiring, pausing, or rescheduling a worker is a roster edit, not a deploy.

Configuration

All configuration is optional — WorkForce works out of the box from the repo root with no env vars set. For installed-package deployments or multi-directory setups, use these variables:

Installed-package quickstart:

export WORKFORCE_DATA_DIR=~/.workforce
mkdir -p "$WORKFORCE_DATA_DIR/local"
# copy roster.example.json → $WORKFORCE_DATA_DIR/local/roster.json and edit
workforce roster
workforce daemon

launchd (macOS): run workforce daemon-plist while WORKFORCE_DATA_DIR is set and the plist will bake it into EnvironmentVariables automatically.

Hiring a worker

workforce hire --help

Hiring writes the worker's papers (contract + prompt) and adds the roster row. Contracts are the law a worker reads before every shift — a worker whose contract says it is not armed will refuse to work, by design.

Requirements

Python 3.9+. macOS and Linux. Agent CLIs (such as claude) are invoked per shift using the command template in the roster row — bring whichever agent vendor you employ.

License

Apache-2.0. Copyright 2026 ProtocolCity.