Configuration

Per-repo settings

Configuration is stored server-side, per repository — not in a checked-in file. One MCP server works across every repo you can access; you pass owner and repo on each call, and access stays identical to your GitHub permissions. Repo admins tune the settings below from the web UI or by PATCHing /api/v1/repos/{owner}/{repo}/settings. Any field you omit keeps its default.

Repositories join your workspace manually: installing the GitHub App only makes repos available — nothing is added until someone explicitly picks a repo via Add repository on the Repositories page.

Public-repo opt-out

One setting deliberately lives in the repository rather than server-side. Public GitHub repos are otherwise usable by anyone whose GitHub permissions can see them. To restrict AgentsWorklog usage to the owning org or user, commit a .agentsworklog.yml at the repo root on the default branch:

# .agentsworklog.yml — repo root, default branch
allow_public: false

No file (or allow_public: true) keeps the default behaviour. With allow_public: false, anyone outside the owning org/user — including users with plain public read access — gets a clear 403; the owner, org members, and explicit collaborators keep access. Changes take effect within a few minutes (the file is cached briefly server-side), and private repositories never consult the file.

Expiry overrides

The defaults suit most teams, but you can tune them per repo. TTLs are milliseconds — for example activity_ttl_ms = 43200000 (12h) for fast-moving repos, or notable_ttl_ms = 1209600000 (14d) for a long migration (bounded below by min_notable_ttl_ms). Shorter is safer: the less time a stale entry can mislead someone, the better.

Risk levels

Activity risk is a fixed four-level enum. From lowest to highest:

• low — the default; routine, isolated work.
• medium — normal feature work.
• high — touches shared or sensitive areas; worth a look before you overlap.
• critical — a collision here is expensive; coordinate first.

An activity created without a risk defaults to low. Note that overlap severity is a separate, three-level scale (low, medium, high) computed by the ranker, and Notables carry an importance (low–critical) — three distinct fields, not one.

Environment variables

The MCP server (and any direct API client) reads two environment variables — the token is a secret, so it comes from the environment, never a committed file:

With the Claude Code plugin there are no environment variables to manage — the install prompts store the URL in ~/.claude/settings.json under pluginConfigs (hand-editable) and the token in your OS secure storage (change it via /plugin only; a hand-edited token in settings is ignored). Run /reload-plugins after any change.

Sample settings request

Settings are a partial update: send only the keys you want to change. The API applies field-level validation and cross-field bounds (TTL ordering, non-empty categories) and leaves everything else at its default.

// PATCH /api/v1/repos/acme/web/settings — a partial update
{
  "activity_ttl_ms": 86400000,   // 24h
  "notable_ttl_ms": 604800000,  // 7d
  "webhook_archive": true
}

Self-hosting

AgentsWorklog is source-available (NFSL-1.0-MIT) and self-hostable. Run your own API, point clients at it with AWL_API_URL, and back it with a GitHub App for auth. Free for internal use under the NFSL; a commercial license is required to offer it as a service.