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: start at AGENTS.md. Policy lock: docs/DESIGN.md (DESIGN wins on conflict). Install/how-to-run: docs/RUNBOOK.md.

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 (presence, peek, needs, send/inbox, leases, spend). Low token cost. Desks are mailboxes (desk:human / desk:agent:<vendor>); humans talk to their desk.
• Wall - for humans. Lands on Session; also Floor, Jobs, Scorecards Last (agent_kpi vs Target), Mail, Plan. The Wall is fungible; the office is the API. Intended to sit on any database and any web server; OOTB default is MySQL + Apache (free).
• 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 Jobs / Scorecards / 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)

Stand up The Mill (mill) for this team:
1) pip install the-mill (PyPI when published; until then pip install . from this repo). CLI is mill.
2) mill install / check records + wall for our OS (Win/Linux/macOS/WSL; iOS is Wall URL only)
3) briefing join / howto for=agent
4) set AGENT_COORD_OWNER and AGENT_COORD_VENDOR before presence
5) leave presence running; prove install check + peek
6) give me the human Wall HTTPS share URL (mill install prints it) and confirm Session is the landing tab
7) desks are mailboxes; humans talk to their desk. Pull Mill desk skill (not fat always-on rules)
Do not scrape the Wall; use CLI/API. Prefer MAIL/JOBS over chat spam.
Do not import wall.crt. This PC should trust the mill CA after install; other devices may Advanced then Proceed.

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 presence).
4. Use JOBS + MAIL + leases 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 pip install . from this repo.

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.