Skip to main content
Glama

Backlogr

A small, self-hosted system of record for a team of AI agents' work (research, purchases, edits, outreach, code). Agents talk to it over MCP or a CLI. Tasks are the objects; the MCP tool verbs are task_*. Rule: no task, no work.

  • Python, SQLite (WAL), append-only update log enforced by triggers.

  • MCP over streamable HTTP (or stdio), plus a JSON API used by the CLI. Bearer-token auth on API/MCP; /healthz is unauthenticated.

  • Nightly JSON export and SQLite backup inside the service.

Documentation

Related MCP server: pith

Rule for every agent (paste verbatim)

No task, no work: before you start anything for the user, create or find its task in Backlogr (task_create / backlogr new), and record every status change, blocker and result on that task (task_update / backlogr update, backlogr done) as it happens, using your bot name as the actor.

Run the server

git clone '<repo-url>' ~/backlogr && cd ~/backlogr
python3 -m venv .venv && .venv/bin/pip install -e '.[test]'
mkdir -p data backups exports && chmod 700 data backups exports
cp deploy/env.example .env && chmod 600 .env    # fill in BACKLOGR_TOKEN etc.
set -a && . ./.env && set +a && .venv/bin/backlogr-server
curl -fsS http://127.0.0.1:8796/healthz         # ok

As a systemd user service: install -D -m 644 deploy/backlogr.service ~/.config/systemd/user/backlogr.service && systemctl --user daemon-reload && systemctl --user enable --now backlogr (and loginctl enable-linger $USER to start at boot).

Expose it only on a private network or behind an authenticating reverse proxy, for example Tailscale serve under a path: tailscale serve --bg --https=443 --set-path /backlogr http://127.0.0.1:8796, then BACKLOGR_URL=https://backlogr.example.invalid/backlogr. Add that host name to BACKLOGR_ALLOWED_HOSTS for MCP transport checks; enforce Host restrictions for all routes at the proxy. Use TLS and authentication before any public exposure. Routes: $BACKLOGR_URL/mcp, $BACKLOGR_URL/healthz, $BACKLOGR_URL/api/<op>.

In a container

Release tags publish ghcr.io/oceanswave/backlogr:<version> (and :latest). The image runs as a non-root user, keeps the DB, exports and backups in the /data volume, and has a health check.

cp deploy/env.example .env && chmod 600 .env    # set BACKLOGR_TOKEN; path settings are overridden
docker compose up -d                             # or: docker build -t backlogr . && docker run ...
curl -fsS http://127.0.0.1:8796/healthz
docker compose exec backlogr backlogr list       # CLI inside the container, local mode

compose.yaml publishes the port on loopback only; put an authenticating proxy such as tailscale serve in front, and add its host name to BACKLOGR_ALLOWED_HOSTS. Inside the container the server binds 0.0.0.0 so the published port reaches it.

Configuration

See the complete reference for all environment variables, including deployment settings.

Variable

Used by

Default

BACKLOGR_TOKEN

server (required for HTTP)

none

BACKLOGR_DB

server, local CLI

~/backlogr/data/backlogr.db

BACKLOGR_PORT

server

8796

BACKLOGR_HOSTS

server bind IPs (comma list)

127.0.0.1

BACKLOGR_ALLOWED_HOSTS

extra MCP Host headers (proxy DNS names)

none

BACKLOGR_BACKUP_DIR / BACKLOGR_BACKUP_KEEP

nightly backup (backlogr-YYYY-MM-DD.db)

off / 14

BACKLOGR_EXPORT

nightly export, CLI export

~/backlogr/exports/backlogr-export.json

BACKLOGR_URL

CLI remote mode (and client configs below)

unset = local DB

BACKLOGR_TOKEN_FILE

CLI remote mode

~/backlogr/.token

BACKLOGR_OWNER

name in messages and default person for act (server and CLI)

owner

BACKLOGR_HUMANS

people whose act done attestation can satisfy completion gates

unset

BACKLOGR_BOTS

bot names that can never be approved_by (DB owners/actors are included, except configured humans)

none

BACKLOGR_APPROVERS

if set, the only names accepted as approved_by

unset

BACKLOGR_TZ, BACKLOGR_DASHBOARD_CATEGORIES, BACKLOGR_TRUST_TAILSCALE_HEADERS

dashboard time zone, card grouping, Tailscale header auth

local zone / none / off

Install the MCP

Server name backlogr, streamable HTTP at $BACKLOGR_URL/mcp, header Authorization: Bearer <token>. Keep the token in an env var or a mode-600 file; never commit it or paste it into chat.

  • Claude Code (project .mcp.json or ~/.claude.json; Claude Code expands ${VAR}):

    {"mcpServers": {"backlogr": {"type": "http", "url": "${BACKLOGR_URL}/mcp",
      "headers": {"Authorization": "Bearer ${BACKLOGR_TOKEN}"}}}}
  • Codex (~/.codex/config.toml, with BACKLOGR_TOKEN exported in the launching shell):

    [mcp_servers.backlogr]
    url = "https://<your-host>/backlogr/mcp"
    bearer_token_env_var = "BACKLOGR_TOKEN"
  • Cursor (~/.cursor/mcp.json):

    {"mcpServers": {"backlogr": {"url": "https://<your-host>/backlogr/mcp",
      "headers": {"Authorization": "Bearer ${env:BACKLOGR_TOKEN}"}}}}
  • Stdio-only clients (runs on the server host, reads .env there):

    {"mcpServers": {"backlogr": {"command": "ssh", "args": ["<user>@<server-host>",
      "cd backlogr && set -a && . ./.env && .venv/bin/backlogr-server --stdio"]}}}
  • Any other client: streamable HTTP, the URL above, the bearer header.

Install the skill

The agent skill is skills/backlogr/SKILL.md (CLI, MCP tools, status flow, rules). Copy or symlink the folder into your agent's skills directory:

git clone '<repo-url>' ~/src/backlogr
ln -s ~/src/backlogr/skills/backlogr ~/.claude/skills/backlogr     # Claude Code
ln -s ~/src/backlogr/skills/backlogr ~/.codex/skills/backlogr      # Codex

Other agents: point them at AGENTS.md, or paste the rule above into their instructions.

MCP tools

task_create, task_update (status/due/owner/approval_needed/note), task_add_link, task_get, task_list (owner, status or comma list, overdue, stale_hours, due_before, q, source, include_closed, limit, offset), task_flags (overdue, stale, blocked, waiting_on_owner, created_recently), task_stale (hours), task_waiting (waiting_on_owner queue with asks), task_import, task_act. Fields: id, title, done_means, owner_bot, due (ISO), status (todo|in_progress|waiting_on_owner|blocked|done|declined), source (direct_to_bot|via_coordinator|bot_initiated), approval_needed, ask (required when moving to waiting_on_owner), waiting_since, created_at, updated_at, updates[], links[].

CLI (backlogr)

Remote when BACKLOGR_URL is set (token from BACKLOGR_TOKEN_FILE), else the local DB (BACKLOGR_DB).

backlogr new "Order sample tee" --owner Mint --source via_coordinator --by Coordinator --done-means "tee arrives" --due 2026-10-30 --approval --key mint:sample-tee   # --key: retries return the same task
backlogr update T-abc123 --by Mint --status blocked --note "needs card"
backlogr update T-abc123 --by Mint --due none    # clear the due date (MCP/API: due="")
backlogr update T-abc123 --by Mint --link https://example.com/order --kind order
backlogr done T-abc123 --by Mint --evidence "https://example.com/pr/12" --test unit=pass --test e2e=pass   # --evidence required; --test when done_means mentions tests
backlogr list [--owner Mint] [--status todo,in_progress] [--q PR] [--source via_coordinator] [--due-before 2026-11-01] [--overdue] [--stale-hours 24] [--all] [--limit 50] [--offset 0]
backlogr flags [--stale 24] [--recent 24]
backlogr waiting                    # waiting_on_owner queue: exact ask + age, oldest first
backlogr approve T-id --by Forge --approver Operator --source "Operator in chat 11:17"   # human approval record
backlogr stale [--hours 2]          # in_progress with no note in N hours, by owner
backlogr get T-abc123 [--short]      backlogr import file.json --by Coordinator      backlogr export [--path P]

new, update and done print one line (T-abc123 in_progress); add --json (before or after the subcommand) for the full row. Other commands print a readable summary or JSON with --json.

Deploying to a host with deploy.sh

scripts/deploy.sh updates an existing install (a git clone with a .venv and a systemd user unit, as in Run the server) on a host that has no GitHub access. Ship the release as a git bundle:

git bundle create /tmp/backlogr.bundle --all --tags
scp /tmp/backlogr.bundle "$DEPLOY_HOST:/tmp/backlogr.bundle"
# on the host, from the install dir:
scripts/deploy.sh --bundle /tmp/backlogr.bundle --ref vX.Y.Z --dry-run   # preview: fetches refs, changes no files, DB or service
scripts/deploy.sh --bundle /tmp/backlogr.bundle --ref vX.Y.Z

It refuses to run (exit 4) if tracked files in the install are modified. Otherwise it backs up the DB to backups/pre-deploy-<ts>.db, checks out the ref, runs pip install -e ., restarts the service and waits for /healthz (5 s per try, 40 tries). If pip install, the restart or healthz fails, it rolls the code back to the previous commit and exits 1; schema changes are not reverted, so the DB backup is kept. Without --ref it deploys the highest v* tag; without --bundle it fetches from origin.

Env

Default

BACKLOGR_HOME

~/backlogr (install dir)

BACKLOGR_SERVICE

backlogr (systemd --user unit)

BACKLOGR_DB, BACKLOGR_PORT

environment, else $BACKLOGR_HOME/.env, else data/backlogr.db and 8796

Tests

.venv/bin/python -m pytest -q tests (unit, CLI local + remote, auth 401s, live MCP HTTP end-to-end). ensure.sh health-checks $BACKLOGR_URL. Migrating from the earlier "task manager" deployment: MIGRATION.md.

License

MIT (see license for copyright attribution)

Diagnostics and restore

backlogr --version prints the installed code version. backlogr doctor prints configuration without the token value, including token presence and token-file permissions. Locally it checks DB writability and schema version/columns; remotely it checks /healthz and an authenticated list with limit=1. Exit status is 0 when all checks pass, 1 otherwise. Remote token files should have mode 600. Other CLI failures, including unreadable files, invalid import JSON, and network errors, print error: ... on stderr and exit 2.

List pagination is optional: --limit N --offset N (MCP/API: limit, offset), with no limit by default. Both must be non-negative integers; pagination applies after filtering.

backlogr export writes tasks plus rules and playbooks. backlogr import export.json --by Bot accepts either the exported {"tasks": [...], "rules": [...], "playbooks": [...]} object or a task list; rules and playbooks are upserted as in rules import. Normal imports, including API/MCP snapshots, enforce approval, evidence, and test gates; snapshot history and derived metadata are not restored. For trusted local recovery, backlogr import export.json --by Bot --restore preserves IDs, timestamps, task fields, update history, and links verbatim, bypassing creation gates. Remote --restore is rejected; unset BACKLOGR_URL for local use. Existing IDs are left as they are and reported in skipped; the result also lists created IDs and per-item errors. SQLite backups remain the primary restore method.

One-call human actions (act)

backlogr act T-id done|na|question|later|undo [--reason TEXT] [--by NAME] (MCP: task_act, API op act). --by defaults to BACKLOGR_OWNER (owner when unset). Set BACKLOGR_OWNER=Operator on the server and CLI clients to retain that name.

action

effect

done

status done, with evidence confirmed done by <by>[: reason]. If <by> is listed in BACKLOGR_HUMANS (and in BACKLOGR_APPROVERS, when that is set), their word counts: the tests gate is skipped, and a missing approval is recorded as <by> via act done. Anyone else goes through the normal gates.

na

status declined, with the reason in the note

question

status unchanged. --reason is the question; it is stored in open_question and listed under flags.questions_for_owner, and it clears on the owner bot's next update

later

adds a note without changing status; --reason is required

undo

restores status, evidence, approval, tests and question to what they were before the last act. This works only if nothing else changed the task since.

Every act is logged in the history as act <action> by <by>.... Each act is checked inside the write lock. If the task changed after it was read, the act is refused with "retry". Names in BACKLOGR_HUMANS (comma-separated) never count as bots, even after they act on tasks. The HTTP API accepts only the parameters exposed by the corresponding MCP tool; unknown fields return HTTP 400 (unknown field: x). Request bodies over 1 MiB return HTTP 413.

Dashboard mapping: DASH T-x DONE → act T-x done; DASH T-x N/A[: r] → act T-x na --reason r; DASH T-x QUESTION: q → act T-x question --reason q.

Rules and Playbooks (1.5.0)

Store reusable rules alongside tasks, and group them into playbooks with optional skill names and test commands. IDs are supplied by you. A rule needs nonempty rule text; its title and other descriptive fields are optional.

backlogr rules add M1 --title "Check examples" --rule "Examples must run." --test "python -m pytest" --category quality --by Agent
backlogr playbooks add P-check --name "Example checks" --rules M1 --skill example-check --test "python -m pytest"
backlogr rules list --playbook P-check --testable yes --json
backlogr rules get M1
backlogr rules untested
backlogr rules remove M1            # also: backlogr playbooks remove P-check (keeps its rules)
backlogr playbooks list
backlogr playbooks get P-check --json
backlogr rules import tests/fixtures/rules-playbooks.json --by Agent --json

rules add accepts --evidence, --source, --applies-to, --playbook, --testable yes|no, and --replace. Duplicate rule IDs fail unless --replace is given; replacement supplies the full editable record, preserving creation metadata. --by defaults to BACKLOGR_OWNER for rule creation. Playbook add upserts by ID; --description is optional. An omitted --rules preserves links; an explicit list replaces additional links. Unknown rule/playbook references fail.

A rule's testable defaults to true when it has a test. Empty or whitespace-only tests and tests starting with UNTESTED (case-insensitive, ignoring leading whitespace) always derive false. Explicit true with an empty test is rejected. rules untested and rules list --untested return every rule with testable=false, just like rules list --testable no. This includes empty tests, UNTESTED placeholders, and rules explicitly added or imported with testable=false despite descriptive test text. Rules with testable=true are excluded. MCP/API rule_untested uses the same flag-based filter. rules list also accepts --category. --json works at every command level.

The same authenticated HTTP API and MCP expose rule_list, rule_get, rule_add, rule_untested, rule_remove, playbook_list, playbook_get, playbook_add, playbook_remove, and rules_import. API operations use those exact names: POST to $BACKLOGR_URL/api/rule_get with {"id":"M1"}, for example. See the agent skill for signatures and import format for relationships and bulk import.

Live dashboard

Open /dashboard on your Backlogr server (or /backlogr/dashboard under a /backlogr reverse-proxy prefix) for the live dashboard. The page reads SQLite on every request and refreshes every 60 seconds. It shows task counts, assignees, decisions waiting on the owner (BACKLOGR_OWNER), task cards (grouped by optional BACKLOGR_DASHBOARD_CATEGORIES), the latest 40 finished tasks, up to 80 timeline events from the last 48 hours, and rules/playbooks. /dashboard.json serves the same computed model for other read-only clients.

Both routes accept GET and HEAD only and require the Authorization: Bearer … API credential. Behind tailscale serve you can set BACKLOGR_TRUST_TAILSCALE_HEADERS=1 to also accept the Tailscale-User-Login identity header it adds; enable that only when the listener is reachable solely through tailscale serve, because a direct client could forge the header. The existing BACKLOGR_ALLOWED_HOSTS configuration also applies. The dashboard sends a strict Content-Security-Policy and has no scripts, task action controls, or external assets. Times use BACKLOGR_TZ (default: the server's local zone).

Available Tools

20 tools
playbook_addC

Upsert a playbook and its rule links; unknown rule IDs are errors.

Inputs: id (required), name (required), test, skill, +2 more.

playbook_getA

Get a playbook with linked rules embedded.

Inputs: id (required).

playbook_listB

List playbooks with linked rules.

Inputs: no named parameters.

playbook_removeA

Delete a playbook; its rules are kept, and rules whose primary playbook it was are detached.

Inputs: id (required).

rule_addB

Add a rule; replace=true explicitly updates an existing ID. UNTESTED tests derive testable=false. actor defaults to BACKLOGR_OWNER.

Inputs: id (required), rule (required), test, actor, +8 more.

rule_getC

Get one rule.

Inputs: id (required).

rule_listB

List rules with optional playbook, testability and category filters.

Inputs: category, playbook, testable.

rule_removeA

Delete a rule and its playbook links.

Inputs: id (required).

rules_importC

Atomically import a rules/playbooks object; return created/updated/unchanged counts.

Inputs: actor (required), items (required).

rule_untestedA

List every rule whose testable flag is false, including rules with test text.

Inputs: no named parameters.

task_actA

One-call action by a person (default BACKLOGR_OWNER), e.g. from dashboard buttons. action: later (note only; reason required) | done (status done; the person's word is the evidence) | na (status declined, reason in the note) | question (status unchanged; reason is the question, marked as open_question for the owner bot until the owner updates) | undo (reverts the last act if nothing changed since). Logged in the task history as "act by ".

Inputs: id (required), action (required), by, reason.

task_createA

Create a task. key: a stable idempotency key (e.g. "forge:pr-12-review"); if a task already has it, that task is returned unchanged with existing=true, so retries never duplicate. The result has warnings when an open task has a very similar title: check it before carrying on. source: direct_to_bot | via_coordinator | bot_initiated. status: todo|in_progress|waiting_on_owner|blocked|done|declined. due: ISO 8601. done_means: one line saying what done looks like. ask: required with status waiting_on_owner, one line saying exactly what the owner must decide or do. approved_by/approval_source: the human approval (never a bot name); required before an approval_needed task can be in_progress or done. evidence/test_results: see task_update. actor: your bot name.

Inputs: actor (required), title (required), source (required), owner_bot (required), +11 more.

task_flagsB

Check-in view: overdue, stale, blocked, waiting_on_owner, open questions for owners, and tasks created in the last N hours.

Inputs: stale_hours, created_within_hours.

task_getC

Get one task with its full updates log and links.

Inputs: id (required).

task_importA

Bulk create tasks. items: a list, or an export object {tasks, rules, playbooks}. Each task takes task_create fields except actor (title, owner_bot, source, done_means, due, status, approval_needed, note, created_at) plus optional links [{ref, kind}]. Rules and playbooks are upserted as in rules_import.

Inputs: actor (required), items (required).

task_listA

List tasks (open only unless status or include_closed given). Filters (AND): owner, status (one or comma list e.g. "todo,in_progress"), overdue, stale_hours (no update in N hours), due_before (ISO date), q (text in title/done_means/notes/links), source.

Inputs: q, limit, owner, offset, +6 more.

task_staleA

in_progress tasks with no note or change in the last N hours, grouped by owner (oldest first).

Inputs: hours.

task_updateA

Update a task's status/due/owner/approval_needed and/or append a note to its log. due="" clears the due date. Moving to waiting_on_owner requires ask (one line: exactly what the owner must decide or do). Record a human approval with approved_by (the human, never a bot) and approval_source (e.g. "owner in chat"); an approval_needed task cannot move to in_progress or done without one. Moving to done requires evidence (link, commit sha, path or command output summary), and test_results {test name: "pass"|"fail"} when done_means mentions tests. actor: your bot name.

Inputs: id (required), actor (required), ask, due, +8 more.

task_waitingA

Owner queue: every waiting_on_owner task, oldest first, with its exact ask and age in hours.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 20 tools

    Disambiguation3/5

    Core operations are distinguishable, but several specialized views overlap: task_list can reproduce much of task_stale and task_waiting, task_flags aggregates those same concerns, and rule_untested overlaps filtered rule_list. The two import tools also overlap because task_import can upsert rules and playbooks, though their descriptions help clarify the intended entry points.

    Naming Consistency4/5

    Names consistently use snake_case and mostly follow a predictable resource_action pattern. Minor deviations include plural rules_import, mixed create/add verbs, and view names such as task_flags and rule_untested that do not use action verbs.

    Tool Count3/5

    Twenty tools is somewhat heavy for this backlog and rules domain. Several tools are specialized convenience views or overlapping import paths rather than clearly essential capabilities, so the surface could be consolidated.

    Completeness4/5

    Task creation, querying, status transitions, evidence, approvals, links, and bulk import are covered, while rules and playbooks have list/get/add-or-update/remove workflows. Remaining gaps include limited editing of general task fields, no task or link deletion, and no export counterpart to the import tools, though closure states and upserts provide partial workarounds.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Server-enforced workflow discipline for AI agents. An MCP server providing persistent work items, dependency graphs, quality gates, and actor attribution. Schemas define what agents must produce — the server blocks the call if they don't. Works with any MCP-compatible client.
      214
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for task management that enables AI agents to read, create, update tasks, and track work sessions, allowing agents and humans to collaborate on the same task board.
      14
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server enabling AI coding agents to interact with a task tracker that enforces rules server-side, replacing markdown files and hooks with a database, CLI, and web UI.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for agentic task orchestration and management, enabling AI agents to create goals, plan tasks with acceptance criteria, track dependencies, request human input, and provide proof of completion.
      27 npm
      3
      MIT