btodos

Pulls your assigned Jira tickets for the board columns you care about and lists them as a checklist — either as a Markdown file in your project root (readable in Cursor) or on a localhost webpage.

Minimal runtime dependency: Jinja2 for HTML templates (Python 3.10+).

Board UI stack (vendored in the package):

• HTMX — soft-refresh / swap ticket list HTML from /board
• Alpine.js — modals, filter dropdowns, focus
• Tailwind — utility CSS layered on board.css (preflight off)

Rebuild Tailwind after template class changes:

pnpm install
pnpm run build:css   # → src/btodos/static/app.css

Install

pip install -e /Users/ahmed/Workspace/Work/MyPackages/btodos
# or: uv tool install .
# Commands: btodos  and  btd  (same CLI)

Configure

In your workspace root:

btodos init

That writes .btodos/config.json:

{
  "baseUrl": "https://your-company.atlassian.net",
  "projectKey": "ABC",
  "columns": ["To Do", "In Progress", "In Review"],
  "email": "you@your-company.com",
  "assignee": ["currentUser()"],
  "outputFile": "JIRA-TODOS.md",
  "port": 4321
}

Key	Required	Meaning
baseUrl	yes	Your Jira Cloud site URL
projectKey	yes	Project key, e.g. ABC from ABC-123
columns	yes	Status names to include, in display order
email	yes	Atlassian account email (Basic auth user)
assignee	no	One Jira user ("currentUser()") or a list of teammates. Emails are resolved to account ids via Jira user/assignable search (even when Jira hides emails in the response) and cached in .btodos/assignees.json. Account ids and currentUser() are used as-is. The web assignee filter is built from whoever appears on the loaded tickets.
outputFile	no	Markdown output path, relative to the workspace root
port	no	Port for serve (default 4321)
labels	no	Only include tickets carrying at least one of these labels
models	no	Ollama models: { "recap", "steps", "review" } — each a name or fallback list (default llama3.2:3b; [] disables). steps/review default to recap.
ollama	no	Host Ollama limits: { "numParallel", "maxLoadedModels" } (defaults 1). Apply with btodos ollama apply.
ollamaUrl	no	Ollama host (default http://localhost:11434)
redisUrl	no	Optional Redis URL for the ticket cache (Compose sets BTODOS_REDIS_URL)
git	no	Pull-request lookup — see Pull requests
promptsFile	no	Prompt templates file under .btodos/ (default prompts.json; also .md / .yaml)
promptsDir	no	Directory of per-prompt Markdown files (e.g. prompts/). When set and present, loads instead of promptsFile.
globalsFile	no	Shared {{variables}} for config/prompts (default globals.json)
enrich	no	Bulk --enrich gates: status/label/… filters and/or LLM prompt — see below
notificationsByPriority	no	When true, the 🔔 inbox lists updates by ticket priority (Highest→Lowest), then newest
taskKinds	no	Closed set of task kinds for board filters, e.g. ["backend","web","mobile"]. Empty disables.
estimateField	no	Jira custom field id for story-point / estimate (e.g. customfield_10016) — enables useful order by → estimate
complexityField	no	Optional Jira field for complexity; when filled, wins over the LLM
complexities	no	Levels for LLM complexity (default ["High","Medium","Low"]). Empty disables LLM complexity. Edit criteria in prompts.json → complexity.
orderBy	no	Board sort modes to show (default ["priority","estimate","complexity","created"]). Override or remove entries; [] hides the control. Alias: "time created" → created.

After upgrading btodos, run btodos config sync to migrate legacy keys (e.g. top-level recapPrompt or inline prompts) into .btodos/prompts.json, add any new defaults, and when needed move tickets.json into .btodos/tickets.bundle. Existing values are never overwritten.

The web view

btodos serve is interactive:

• Tick several tickets and a sticky toolbar appears — pick a target column and hit Move. Defaults to In Progress, for starting the day in one action.
• ⧉ next to each key copies that ticket number to the clipboard; Copy keys in the toolbar copies every selected key at once, space-separated.

Moves go straight to Jira through the issue transition API. A ticket that has no valid workflow transition to the chosen column is reported back by name and left untouched; the others still move.

• ⊘ next to each ticket hides it; a N hidden · show hidden control in the header brings them back so you can unhide one at a time.
• Column headings collapse when clicked.
• Filter by epic, label, pull-request state, task kind, or assignee from the header. Epics are listed as ABC-100 — Checkout so you can pick by number or by name. PR states are has a PR, no PR, has active PR, changes requested, approved, in review, not reviewed, draft, merged, declined — only the ones actually present are offered. Task kinds come from taskKinds in config (classified by matching Jira labels, or via btodos sync --enrich / on-demand AI). Assignees come from the loaded tickets — set assignee in config to a list of teammates if you want more than yourself. The filters combine (epic ABC-100 and merged), counts follow the filter, and clear resets them. Filtering is a view over the tickets already loaded — no refetch, and it doesn't touch what's hidden. Order by (priority / estimate / complexity / time created) reorders the board. Estimate needs estimateField. Complexity uses the LLM prompt in prompts.json → complexity (and optional complexityField when present). Modes shown are set by orderBy. (defaults on btodos init / config sync; edit or remove freely).

Hidden tickets and collapsed columns are stored in .btodos/view.json, so the layout comes back the same next time you serve.

Tickets are read from .btodos/tickets.bundle (one JSON file per ticket) rather than refetched on every page load. Use the header buttons:

• fetch pulls fresh Jira issues and linked PR state.
• sync state updates ticket + PR state only (keeps cached descriptions/recaps/steps; no Ollama).

Use the ✨ buttons on each card for on-demand description/comments/PR recaps. Optional bulk enrichment: btodos sync --enrich, gated by enrich filters and/or prompts.enrichCriteria (see Recaps and test steps).

Pull requests

Each ticket shows the pull requests linked to it, with review state and comment count:

IA-142  Fix login redirect   [#312 approved 2/2 💬5]
IA-149  Search is slow       [#318 not reviewed]
IA-151  Audit log            [#301 merged 💬3] [#305 declined 💬1]

Badge	Meaning
merged	the PR is merged
declined	the PR was closed without merging
approved n/m	open, with n of m reviewers approving
in review	open, has comments but no approval yet
not reviewed	open, nobody has commented or approved

Configure where they come from under git:

{
  "git": {
    "enabled": true,
    "provider": "github",
    "repos": ["your-org/api", "your-org/web"],
    "tokenEnv": "GITHUB_TOKEN",
    "apiUrl": "https://api.github.com",
    "maxPages": 3
  }
}

Key	Meaning
provider	github (the GitHub API) or jira (Jira's dev-status panel)
repos	repos to scan, owner/name. Required for github
tokenEnv	env var holding the token (default GITHUB_TOKEN)
apiUrl	override for GitHub Enterprise
maxPages	pages of 100 recent PRs to scan per repo (default 3)
enabled	false skips the lookup entirely

With provider: "github", btodos lists each repo's most recently updated pull requests and matches them to tickets by issue key in the PR title, branch name or body — so feature/ABC-123-login or a title starting ABC-123 both link up. Only matched PRs cost extra requests (two each, for comments and reviews).

The token needs repo scope for private repos (public_repo otherwise):

export GITHUB_TOKEN="ghp_..."    # https://github.com/settings/tokens

provider: "jira" uses Jira's development-status endpoint instead — no GitHub token needed, but that endpoint is undocumented and returns nothing on many Jira sites.

Anything missing is reported and skipped rather than failing the run: no token, no repos, a bad token, or an unreachable repo all print a reason and leave tickets without pull requests.

Unlike recaps, PR state is refreshed by the web fetch / sync state actions, since review counts change far more often than a ticket description.

Labels

Labels are shown under each ticket. Restrict the checklist to certain labels with the labels config key, and edit them from the CLI:

btodos label ABC-123 backend urgent      # add
btodos label ABC-123 --remove urgent     # remove

This is the only command that writes to Jira.

Recaps and test steps

Each ticket gets a one-line recap, plus numbered steps to reproduce or verify it when the description has enough detail (tickets shorter than ~140 characters get no steps, since the model would have to invent them). By default both are generated locally by Ollama — nothing leaves your machine. Ticket recaps/steps are on demand from the board ✨ buttons (and optionally btodos sync --enrich). btodos serve / plain btodos sync never bulk-run the LLM; they reuse .btodos/tickets.bundle.

Bulk --enrich only summarises tickets that pass your criteria (you control both):

1. Filters in config.json → enrich (empty list = no restriction on that field):

{
  "enrich": {
    "statuses": ["In Progress", "In Review"],
    "priorities": ["Highest", "High"],
    "labels": [],
    "kinds": [],
    "assignees": [],
    "prompt": true
  }
}

2. Prompt in prompts.json → enrichCriteria (YES/NO). Set "prompt": true to enable the LLM gate (optionally with filters); leave "prompt": false (default) for filters only, or empty filters with no prompt to summarise every ticket on --enrich.

Shared text for config/prompts can live in .btodos/globals.json and be referenced as {{name}} (single {title} placeholders stay for runtime).

PR review recaps (for changes requested) are generated on demand from a button on the web page, using reviewFeedbackPrompt.

PR code-change briefs (for manual review of AI-written diffs) use Summarise changes. Small diffs run immediately; large ones ask you to proceed or ignore. Customise the brief with codeDiffPrompt. Pull the model once:

ollama pull llama3.2:3b

Host resource limits (how many requests / loaded models Ollama keeps) live under ollama and are applied to the host Ollama process — not the btodos container — by:

btodos ollama apply

That sets OLLAMA_NUM_PARALLEL / OLLAMA_MAX_LOADED_MODELS from config, persists them on macOS via a LaunchAgent, and restarts the Ollama app (use --no-restart to skip the restart):

{
  "ollama": {
    "numParallel": 1,
    "maxLoadedModels": 1
  }
}

models.recap takes a single name or an ordered list of fallbacks. Each model is tried in turn, and one that isn't pulled, errors, or answers with nothing hands off to the next:

{ "models": { "recap": ["qwen2.5:7b", "llama3.2:3b"] } }

models.steps is separate and defaults to models.recap, so you can pair a small fast model for the one-line recap with a stronger one for the steps — same number of calls, better fit per task:

{
  "models": {
    "recap": ["llama3.2:3b"],
    "steps": ["qwen2.5:7b", "llama3.2:3b"]
  }
}

If every model fails — Ollama isn't running, none are pulled — the recap falls back to a truncated excerpt of the ticket description and steps are omitted, so sync never fails because of it. Set "models": { "recap": [] } to always use the excerpt and skip the LLM entirely.

Prompts live in .btodos/prompts.json by default (promptsFile), or as one Markdown file per prompt under .btodos/prompts/ when you set "promptsDir": "prompts".

btd config prompts split            # prompts.json → prompts/*.md + set promptsDir
btd config prompts export           # prompts/*.md → prompts.md

Each file is plain Markdown (the prompt body):

Classify this Jira ticket as exactly one of: {kinds}.
…
Title: {title}

Config stays readable:

{
  "promptsDir": "prompts",
  "promptsFile": "prompts.md"
}

promptsDir wins when present (.md preferred over legacy .yaml). promptsFile can still be JSON, Markdown bundle, or YAML. Each JSON value is a string or an array of lines. Most must contain {description}; {title} is optional. cursorWork is the text copied by the ✨ button on each ticket for pasting into Cursor. It must contain {key} and {branch}; optional placeholders: {title}, {url}, {description}, {brief}, {status}, {priority}, {assignee}, {reporter}. taskKind classifies tickets into taskKinds and must include {kinds} + {description}. btodos init / btodos config sync write the defaults so you can edit them in place. Print the built-in Ollama prompts template (and copy it) with:

btodos config prompts

Then paste into .btodos/prompts.json to replace.

{
  "recap": [
    "Summarise this Jira ticket in one short sentence of at most 25 words.",
    "",
    "Title: {title}",
    "",
    "Description: {description}",
    "",
    "Summary:"
  ],
  "steps": ["…"],
  "reviewFeedback": ["…"],
  "codeDiff": ["…"],
  "reviewDraft": ["…"],
  "cursorWork": ["…"],
  "taskKind": ["…"]
}

Legacy inline prompts / top-level recapPrompt keys still load; btodos config sync moves them into the prompts file.

Recaps and steps are cached and tracked separately, so a re-sync never starts over: it keeps everything it already has and generates only what is new. A ticket is re-summarised when its description changes, when its model or prompt changes (recaps and steps independently), or when the previous attempt fell back to the excerpt because Ollama was unreachable.

The API token is read from the environment, never the config file:

export JIRA_API_TOKEN="..."   # https://id.atlassian.com/manage-profile/security/api-tokens

The config file is looked up in the current directory and every parent, so the commands work from any subdirectory of the workspace.

Use

Run btodos commands (or btd commands) anytime for a full command table. Official short name: btd (same CLI as btodos).

# Daily
btd init                            # create .btodos/config.json
btd sync                            # fetch tickets → JIRA-TODOS.md
btd sync --enrich                   # also bulk-generate recaps/steps/kinds (slow)
btd sync --task-kind                # reclassify kinds only
btd serve                           # http://127.0.0.1:4321
btodos label ABC-123 backend        # add labels
btodos doctor                       # check Jira / GitHub / Ollama
btodos commands                     # show all commands as a table
btodos completion zsh               # shell completion

# Config (noun + verb)
btodos config sync                  # migrate/add keys after an upgrade
btodos config prompts               # built-in prompts.json → clipboard
btodos config sort                  # list orderBy modes
btodos config assignees             # prompt for emails → account ids
btodos config assignees a@x.com     # same, non-interactive

# Ollama host / container
btodos ollama apply                 # apply ollama.* limits + restart app
btodos container write              # write .btodos/docker-compose.yml
btodos container up --build         # start
btodos container logs               # follow
btodos container down               # stop

Output:

# ABC — My Tickets

_4 ticket(s) · generated 2026-09-01 10:12 UTC by btodos._

## To Do (2)

- [ ] [ABC-123](https://your-company.atlassian.net/browse/ABC-123) — Fix login redirect _(High · 2026-08-28)_
- [ ] [ABC-131](https://your-company.atlassian.net/browse/ABC-131) — Add audit log _(Medium · 2026-08-27)_

Notes

• Tickets are selected with project = <key> AND assignee IN (<assignee>) AND status IN (<columns>) (or assignee = … when only one is configured), then listed by priority (Highest first), most recently updated first within a priority.
• Everything btodos writes lives in .btodos/ — config, ticket cache, assignee id cache and view state. Add it to your .gitignore unless you want the cache shared.
• Column names must match your Jira status names exactly (matching is case-insensitive).
• Checkboxes are for your own local tracking — ticking one does not write back to Jira.

Docker

Run the web view as a background container instead of holding a terminal:

btodos container write         # writes .btodos/docker-compose.yml
btodos container up --build    # start
btodos container restart       # down then up (add --build to rebuild)
btodos container logs          # progress output
btodos container down          # stop

Or with compose directly:

btodos container write
docker compose -f .btodos/docker-compose.yml up -d --build
open http://127.0.0.1:4321

docker compose -f .btodos/docker-compose.yml logs -f   # progress output
docker compose -f .btodos/docker-compose.yml down      # stop

The image is python:3.13-alpine with the package installed and nothing else — no build Minimal runtime dependency: Jinja2 for HTML templates. Compose image installs the package as a non-root user (~84 MB). The generated compose file:

• starts a Redis sidecar (redis:7-alpine) for the ticket cache (BTODOS_REDIS_URL); the JSON file under .btodos/ remains a fallback;
• mounts your workspace at /work, so config, cache, view state and the Markdown output are the same files the CLI uses;
• sets BTODOS_HOST=0.0.0.0 so the port mapping can reach the server;
• points BTODOS_OLLAMA_URL at host.docker.internal, since Ollama runs on the host;
• reads JIRA_API_TOKEN and your git token from your shell at up time — never stored in the file;
• restarts unless stopped, so it comes back after a reboot.

If btodos serve is already using the port, give the container a different host port:

BTODOS_PORT=4400 docker compose -f .btodos/docker-compose.yml up -d

host in the config (or BTODOS_HOST) also controls what the plain serve command binds to; it stays 127.0.0.1 by default.

Tests

python3 -m unittest discover -s tests -t tests   # from the package root

148 tests, stdlib unittest, no network — every remote call is stubbed. Runtime needs Jinja2. They cover config parsing and its error messages, JQL and Jira field parsing, priority ordering, the incremental sync/merge rules, the ticket cache and view state, GitHub PR matching and review state, Markdown and HTML rendering, the server endpoints, and the CLI.

Tests prove the logic; they cannot prove your credentials work. For that:

btodos doctor

It checks, against the real services: Jira credentials and that your JQL returns tickets, that every configured column is a real status name, the GitHub token and each repo, whether any PR actually mentions your ticket keys, and that Ollama is up with your models pulled. It exits non-zero if anything failed.