Configuration

AgentsWorklog runs with sensible defaults — one repo, 24-hour activities, 7-day Notables. These are the keys you can override, plus the environment variables and self-hosting basics.

Repo scoping

Every instance is pinned to a single owner/name repository via the repo key (or --repo on the MCP server). There is no multi-repo mode by design: scoping to one repo is what keeps access identical to GitHub access and prevents cross-repo leakage.

KeyTypeDescription

repo required

string

The owner/name repository this instance is scoped to.

activity_ttl optional

duration

How long Activity Logs live before auto-archiving. Default 24h.

notable_ttl optional

duration

How long Notables live. Default 7d.

default_risk optional

enum

Risk applied to a new activity when none is given. Default medium.

auto_archive optional

boolean

Archive on PR merge / branch delete. Default true.

Expiry overrides

The defaults suit most teams, but you can tune them per repo. Durations accept h (hours) and d (days) — for example activity_ttl = "12h" for fast-moving repos, or notable_ttl = "14d" for a long migration. Shorter is safer: the less time a stale entry can mislead someone, the better.

Risk levels

Risk is a fixed four-level enum used to rank overlaps and Notables. From lowest to highest:

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

Set default_risk to change what a new activity gets when the caller doesn't specify one.

Environment variables

Secrets and deployment-specific values come from the environment rather than the checked-in config file:

VariableTypeDescription

AGENTSWORKLOG_TOKEN required

string

Bearer token that maps to GitHub permissions. See Authentication.

AGENTSWORKLOG_REPO optional

string

Default repo scope if --repo is omitted.

AGENTSWORKLOG_API_URL optional

string

Override the API base for a self-hosted deployment.

Sample config

A complete per-repo config is small. Check it into the repository so every agent working there resolves the same TTLs and defaults:

agentsworklog.toml toml

# agentsworklog.toml — checked into the repo
repo          = "acme/web"
activity_ttl  = "24h"
notable_ttl   = "7d"
default_risk  = "medium"
auto_archive  = true

Self-hosting

AgentsWorklog is source-available (NFSL-1.0-MIT) and self-hostable. Run your own API, point clients at it with AGENTSWORKLOG_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.

Keep tokens out of the config file.

agentsworklog.toml is meant to be committed — never put AGENTSWORKLOG_TOKEN in it. Provide the token through the environment so it stays out of version control.