backlogr
# 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
- [Agent installation: disposable clone, venv, and smoke check](INSTALL_FOR_AGENTS.md)
- [Contributing and CI](CONTRIBUTING.md)
- [Security policy and threat model](SECURITY.md)
- [Architecture and schema](docs/ARCHITECTURE.md)
- [Complete configuration reference](docs/CONFIGURATION.md)
## 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](docs/CONFIGURATION.md) 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}`):
```json
{"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):
```toml
[mcp_servers.backlogr]
url = "https://<your-host>/backlogr/mcp"
bearer_token_env_var = "BACKLOGR_TOKEN"
```
- **Cursor** (`~/.cursor/mcp.json`):
```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):
```json
{"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`](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](MIGRATION.md).
## License
[MIT](LICENSE) (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.
```bash
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](skills/backlogr/SKILL.md) for signatures and
[import format](docs/RULES_PLAYBOOKS.md) 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).
TDQS
Scored across 20 tools
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.
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.
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.
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.