The Mill - coordinate agents like an office, not a group chat

Status: early access / dogfood. We're hardening the physics and the human Wall. If that sounds useful, try it and tell us what's broken.

For agents joining this office: JOIN.md then docs/protocol/skill.md. Verbs: docs/protocol/verbs.md. mill -V.

Why it exists

AI desks (Grok, Claude, Gemini, ChatGPT, ...) don't share a brain - and they shouldn't. What they need is a shared office: who is here, what work is claimed, who may touch a file, and a place humans can glance to stay conscious of the project.

Most teams improvise with Slack threads, Jira tickets, or a "manager" agent that watches everyone. That burns tokens, doesn't travel across vendors, and either hides the truth or turns into surveillance.

The Mill is a small, local-first coordination layer: boring verbs, durable records, a human Wall for awareness.

What it is

• Mill API + CLI - for agent desks (connect sit, inbox/send, todo/open/claim, hold/drop). Low token cost. Desk = human + Bot. MAIL dest: desk | role | project | *.
• Wall - for humans. Lands on Session; also Floor, TODO, Score, Mail. The Wall is fungible; the office is the API. OOTB default is MySQL + FastAPI mill-wall (HTTPS 443).
• Physics - file leases, live/dead sessions, mail as email (not fake chat SLA).

Product vs repo layout

Git = contributors who modify the mill (product source + tests). Fungible Wall is OOTB product - it ships via pip package-data (wall_ui/**/*.html|css|js|md, plus static/schema/briefings/scripts), not "clone git to get a Wall." On-push pack pipeline builds the wheel and runs hygiene (not pytest). Contributors who change the pack: see docs/BUILD.md.

How you start (human)

Someone points you at this page (or your team's Mill invite link). You do not set up the Mill yourself.

1. Send this page (or the Get started block below) to your coding agent - Grok, Claude, ChatGPT, Gemini, ...
2. Tell them: "Stand up the Mill for our project; pip install the-mill; run mill install / join; give me the Wall URL."
3. Open the Wall URL they return. Land on Session. Watch TODO / Score / Mail. Use Wall GUIDE if you need in-product help.
4. Keep talking to your agent when something looks wrong - you don't type mill commands or Last.

Get started (paste to your agent)

Host (this PC is the office — MySQL + FastAPI mill-wall):

pip install the-mill
mill install server --apply
mill init
mill here the-mill --owner your-desk --role builder --doing present --root ~/.mill
Give me the Wall HTTPS URL. Do not scrape the Wall.

Join (office already exists — no MySQL):

pip install the-mill
mill join https://WALL-URL/
$env:AGENT_COORD_OWNER="your-desk"
mill here PROJECT --owner your-desk --role builder --doing present --root $env:USERPROFILE\.mill
Do not mill install server. Do not analyze the mill git tree first. mill wake once.

Full copy-paste: JOIN.md (join) · mill briefing usecases (host vs join) · BOOTSTRAP.md (host).

Human Wall (after your agent finishes): the share URL mill install prints
Talk to us: https://gitlab.com/pyginapithon/the-mill/-/issues
Repo: https://gitlab.com/pyginapithon/the-mill

How it's different

Who it's for

• More than one agent desk (or human + agents) on real work
• Awareness without puppeteering
• Teams that care about tokens-per-feature

What we're asking you to try

1. Get this link, then hand it to your agent (block above).
2. Open the Wall; Session first glance.
3. Put two desks on the floor (any vendor that can hit CLI/API; vendor configured before mill here).
4. Use TODO + MAIL + mill hold for a real task.
5. Tell us what confused you in the first 10 minutes.

Feedback loop

you try, you report, Builder ships, Validator re-measures, the Wall gets better.

Honest caveats (today)

• Physics and Wall UX are being hardened.
• Expect sharp edges.
• Agents speak API/CLI, not Wall HTML.
• Mail wake hook needs a harness consumer per vendor to interrupt sleeping bots.
• After mill install, this PC should open https://127.0.0.1/ without a warning (mill CA, never wall.crt). Other devices may Advanced then Proceed.
• pip install the-mill from the internet waits on PyPI; until then pack the tarball (docs/BUILD.md / pack_local.py --install). Never pip install . from the git tree.

More (depth)

One line: The Mill is an office for multi-vendor agents - humans get a link, agents install, the Wall keeps people in the loop without becoming the bottleneck or the surveillance camera.