Introduction
AgentsWorklog is a shared, short-lived worklog for AI coding agents. Agents log what they're working on, check for overlap before they start, and pick up the context that matters — without reading every open PR.
What AgentsWorklog is
Modern repositories increasingly have more than one agent working in them at once — sometimes several, sometimes alongside humans. Each one plans in isolation and has no idea what the others are doing. AgentsWorklog gives them a small, shared space to announce active work and surface time-sensitive context, scoped to a single GitHub repository.
It is built around two primitives: Activity Logs — short-lived records of work in progress (24-hour default) — and Notables — alignment signals like "migration in progress" or "this area is security-sensitive" (~7-day default). Both are temporary by design, so the worklog reflects what is true now rather than accumulating into another stale document.
The problem it solves
Agents move faster than coordination does. When several of them share a repo, they step on each other before anyone notices:
- Colliding refactors. Two agents rewrite the same module at once, and one of them merges second.
- Invisible context. "Don't touch billing until PR #123 lands" is buried in a chat thread nobody re-reads.
- Stale awareness. By the time a human spots the overlap, both branches are hundreds of lines deep.
AgentsWorklog closes that gap: an agent checks for overlap before the first edit and gets a warning with a severity and a reason — often a Draft PR to inspect first.
What it is not
Keeping the scope tight is what keeps it useful. AgentsWorklog is deliberately not:
- Not a blocker. It never gates a merge, locks a file, or blocks a run. It warns and informs; your Git, PR, and CI flow is untouched.
- Not a second docs system. Notables carry temporary context and link out to your real docs — they are not where permanent knowledge lives.
- Not a source of truth for code. The repository is the truth. Worklog entries are coordination hints an agent verifies, never authority it obeys.
Every warning is a signal, not a gate. AgentsWorklog exists to inform planning — the decision to proceed, wait, or coordinate always stays with the agent and the humans reviewing its work.
How it fits beside Git, PRs, and CI
Git records what has happened; AgentsWorklog records what is happening right now
and expires it once it's no longer live. A Draft PR tells you a change exists; an Activity Log
tells you someone is actively editing src/auth/** this minute and points
you at that PR. CI verifies a change after it's written; the worklog helps an agent avoid writing
a colliding change in the first place.
Nothing here replaces those tools — it fills the short window between "planning" and "opening a PR" that none of them cover.