Content
# AgentsWorklog
**Shared situational awareness for coding agents.**
Your team now has more contributors than people. Agents open branches, refactor
shared modules, and rewrite the same helper in three places — each one starting
from a blank context, none of them aware of the others. Git tells you about the
collision at merge time. AgentsWorklog tells you before anyone writes the code.
It is a short-lived, shared view of who is working on what, right now, in a
repository — readable by every agent and human on the team. It sits **before and
beside** Git, GitHub, PRs, and CI, and replaces none of them.
## How it works
Two record types, both deliberately temporary.
| | Activity Log | Notable |
| ----------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| Answers | "Who is working on what right now, and where might we collide?" | "What should I know about this repo before I plan?" |
| Tied to | A branch — one active log per branch, not per session | A pattern, decision, warning, or in-flight migration |
| Default TTL | 24 hours, extended by heartbeat while the work is live | 7 days |
| Ends when | PR merged, branch deleted, marked complete, or expired | Manually archived or expired |
An agent's loop looks like this: **check** for overlap before planning, **log**
the work when it starts touching code, **file a Notable** if it leaves behind
something the next agent must know, and **close out** when the branch lands. The
check returns warnings and reuse suggestions — never a block. Nothing is ever
locked.
With the Claude Code plugin, most of that loop is automatic: hooks register the
log on first edit, heartbeat it as you work, and close it when the branch merges.
## Try it locally
Node ≥ 20 and pnpm. `AUTH_MODE=dev` swaps in a fake GitHub client that logs you
straight in as a local dev user, so this needs no GitHub setup and no
credentials at all:
```bash
pnpm install
pnpm build # builds the workspace packages the apps import
cp .env.example .env # ships with AUTH_MODE=dev
pnpm seed --fresh # demo data + prints a dev API token
pnpm dev # API on :3001, web UI on :5173
```
Open http://localhost:5173, sign in, and you have the live feed seeded with demo
activity. Dev mode lets anyone sign in as anyone, so it is for evaluation and
development only — never expose it.
## Run it for your team
To use AgentsWorklog for real you need a domain, and you need to tell GitHub who
you are. That means **two separate GitHub registrations**, which do different
jobs and are easy to confuse:
- a **GitHub OAuth app** — proves _who a person is_ when they log in
- a **GitHub App** — proves _what the tool may see_ in a repository, and delivers
the webhooks that let Activity Logs close themselves when a PR merges
Both are free, both take a couple of minutes, and you only do this once. Below,
`https://awl.example.com` stands in for your API's public URL (`BASE_URL`).
### 1. GitHub OAuth app — user login
GitHub → **Settings → Developer settings → OAuth Apps → New OAuth App**.
| Field | Value |
| -------------------------- | ----------------------------------------------------- |
| Homepage URL | your web UI URL (`WEB_URL`) |
| Authorization callback URL | `https://awl.example.com/api/v1/auth/github/callback` |
The callback URL must match exactly, or login fails. AgentsWorklog requests the
read-only `read:user user:email` scopes — no write access to anything.
**Take away:** the Client ID and a generated Client Secret →
`GITHUB_OAUTH_CLIENT_ID`, `GITHUB_OAUTH_CLIENT_SECRET`.
### 2. GitHub App — repository access and webhooks
GitHub → **Settings → Developer settings → GitHub Apps → New GitHub App**. A
GitHub App (not plain OAuth) is what gives you repo-scoped installation and
native webhooks, so people can grant access to _specific_ repos rather than their
whole account.
| Field | Value |
| ---------------------- | --------------------------------------------------------------- |
| Webhook URL | `https://awl.example.com/api/v1/webhooks/github` |
| Webhook secret | a strong random string you generate |
| Setup URL | `https://awl.example.com/api/v1/github/setup` |
| Repository permissions | Metadata: **read**, Pull requests: **read**, Contents: **read** |
| Subscribe to events | **Pull request**, **Delete**, **Repositories** |
Read-only throughout — the MVP asks for no write scopes. `Contents: read` is
needed for branch `delete` events; the two event subscriptions are what archive
an Activity Log automatically when its PR merges or its branch disappears.
**Take away:** the App ID, a generated private key (`.pem`), the App slug from
its public page (`github.com/apps/<slug>`), and the webhook secret you chose →
`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_SLUG`,
`GITHUB_WEBHOOK_SECRET`.
### 3. Configure and run
Copy `.env.example` to `.env` and fill it in — the API loads it from the repo
root (or `apps/api`). Real environment variables always win over the file, so if
you'd rather inject config through systemd, a container, or your PaaS, do that
and skip the file entirely. Set `AUTH_MODE=github`, make `BASE_URL` and `WEB_URL`
the real public URLs (OAuth callbacks and redirects are built from them), and
give `SESSION_SECRET` a strong random value.
```bash
pnpm install
pnpm build
pnpm --filter @agentsworklog/api start # API — serve behind TLS on your domain
pnpm --filter @agentsworklog/web build # web UI — static assets, serve from any host
```
Storage is a SQLite file by default (`DATABASE_URL`); the schema is
Postgres-compatible if you outgrow it. Sign in, then install the GitHub App on
the repositories you want to monitor — the UI links you to it.
Prefer containers? The repo ships a generic self-host `Dockerfile` +
`docker-compose.yml` that runs the API and web UI for you — `docker compose up
--build` after copying `.env.example`. Details, including the two-origin/`/api`
proxy note and TLS, are in
[docs/self-hosting.md](docs/self-hosting.md#run-with-docker).
### 4. Connect your agents
Agents authenticate with an **API token**, which you mint from the web UI:
**Settings → Integrations → API tokens → Generate token**. It is shown once, so
copy it then. A token acts _as the user who minted it_ — same repository
visibility, same permissions — and it is hashed at rest and revocable.
Then, in each repo you want coordinated, install the Claude Code plugin. It asks
for your instance URL and that token, and wires up both the MCP server and the
lifecycle hooks:
```text
/plugin marketplace add Walnut-Tree-Studios/AgentsWorklog
/plugin install activity
```
Agents on other tools skip the plugin and point their MCP client straight at
`@agentsworklog/mcp` (13 tools) with `AWL_API_URL` and `AWL_API_TOKEN` set.
Edge cases, troubleshooting, backups, Postgres, and composing your own API live
in **[docs/self-hosting.md](docs/self-hosting.md)**.
## Hosted or self-hosted
Both run the same core. Self-hosting is free and endlessly customisable; the
hosted service trades that for having none of the operational work.
| | Self-host | Hosted |
| ------------- | -------------------------------------------------------------------------------------- | --------------------------------------------- |
| Setup | Register two GitHub apps, run the API, web, and a database | Sign in and authorise — we run the GitHub App |
| Operations | Yours: hosting, TLS, backups, upgrades, uptime | Managed, including backups and monitoring |
| Updates | Pull and redeploy when you choose | New features as they ship |
| Support | Community and the docs in this repo | Supported |
| Integrations | Build your own against the API | Coming soon |
| Customisation | **Full** — compose `api-core` / `web-core` with your own modules, routes, and policies | The core product as shipped |
| Cost | Free | Paid — see the site |
Customisation is the self-hoster's advantage and a real one: the extension seams
are how our own hosted service is built, so anything we can add to the core, you
can add to yours.
→ **[agentsworklog.walnuttreestudios.com](https://agentsworklog.walnuttreestudios.com)**
for the hosted service.
## Teaching your agents to use it
The tooling can supply the mechanics but not the judgment. `/activity:init`
installs a **coordination block** into your repo's `AGENTS.md` / `CLAUDE.md` —
the shared mental model that tells agents when a log is worth writing, what makes
scope honest enough to be useful to the next agent, and why records are _context,
not authority_. This repo runs AgentsWorklog on itself, so the block in our own
[AGENTS.md](AGENTS.md) is the same text you get.
## What's in here
The core is a pair of composable libraries; the apps are thin reference wrappers
around them ([ADR 0002](docs/decisions/0002-rest-api-is-source-of-truth.md)).
```
packages/
api-core/ The Fastify REST API — buildApp + feature-module seam (the core)
web-core/ The React + MUI UI — shell, pages, theme, extension registries
core/ Shared domain types, zod schemas, constants (TTLs, statuses)
api-testing/ Test harness for downstream consumers of api-core
apps/
api/ Reference app: production wiring over api-core (self-host)
web/ Reference app: Vite entrypoint mounting web-core (self-host)
mcp/ MCP server — the agent integration layer over the REST API
plugins/
claude-code/ /activity:* commands, SessionStart hook, lifecycle automation
docs/ Spec, architecture, data model, API, ADRs
```
Published to npm: `@agentsworklog/core`, `api-core`, `web-core`, `api-testing`,
and `mcp`.
## What it deliberately is not
- **Not a locking system.** It warns and guides; it never blocks an edit.
- **Not a PR replacement.** PRs remain the source of truth for code changes.
- **Not permanent documentation.** Records expire on purpose — stale coordination
data is worse than none.
- **Not trusted input.** Records are written by other agents. Agent-facing
surfaces present them as context, never as instructions to follow.
## License
Source-available under the [NonFunctional Source License](LICENSE)
(NFSL-1.0-MIT): use it, self-host it, modify it, learn from it — you just can't
resell it as a competing service. Each version converts to MIT ten years after
release. This is **not** an OSI open-source license; see
[ADR 0007](docs/decisions/0007-relicense-to-nfsl.md) for the reasoning.
## Docs
[docs/spec.md](docs/spec.md) is the source of truth for the feature set;
[docs/README.md](docs/README.md) indexes everything else — architecture, data
model, REST API, MCP tools, auth, and ADRs. Contributors should start with
[CONTRIBUTING.md](CONTRIBUTING.md) and
[docs/engineering-standards.md](docs/engineering-standards.md).
