Daniel Borek

Listening to Local Music with MPD on Mac in 2026

dtborek@gmail.com (Daniel Borek) — Sun, 22 Mar 2026 00:00:00 +0000

In the era of streaming, I am returning to my local library of ripped CDs and Bandcamp albums. Going back to local is not (only) about rejecting streaming (check Mood Machine by Liz Pelly, which describes some of the wrongdoing of the industry), but more about better regulating your environment in the attention economy.

I was once a very avid listener and follower of blogs, recommendations from peers (kudos to niekomercyjni muzyczni laicy), and in general my own exploration. But at some point, maybe due to lack of time and energy, I started relying almost completely on Spotify to tell me what to listen to from my own library or its recomendation. While it was handy, the recommendations became really similar, and the UI mostly surfaced only the latest listened playlists and albums. It became hard to make a distinction between my library and their recommendations. I ended up listening to much less of much more homogeneous music.

The renaissance came when I rediscovered album views. First I read on an app proposing rethinking Apple Music (I weren’t subscriber), but then I found a similar interface for a local library via MPD, first Persephone, then Rigelian. Interfaces matter more than I expected here. With a local or remote library, a good client is not just a remote control but part of how the collection appears to you. Cover views, album browsing, and even small bits of friction change what I end up listening to.

Spotify may still be nice in terms of convenience and availability of albums, setting apart the controversies, but resurfacing older music or albums is much harder there. Also, more and more Spotify and other streaming services move away from the concept of the album toward playlists. That makes sense sometimes, but I still miss the artistic completeness of albums. As a person renting a house abroad and moving often, I am still not prepared to start amassing a collection of vinyl or cassettes, so I need to focus on digital. And digital still offers a lot.

I like that this setup can bring back albums I have not played in years. A local library can easily become too large and too familiar at the same time, where I mostly return to the same small corner of it. Randomizing album playback is a simple way to make the collection feel wider again, and it can still bring surprise and wonder :)

I was a long-time ago a Foobar2000 user, but a while back I switched to MPD and various interfaces. On Mac and iOS, I used to enjoy Persephone for its nice cover view, though it is no longer supported since development ceased. Right now I really like Rigelian. It is written in Swift, offers a lovely album view, and has the potential to resurface random albums. It also recently received a major update with a new interface.

MPD is a solution for that, and its biggest advantage is its extendability via players and the fact that it does not get in your way when you need something minimal. Rigelian is really nice, but I often prefer just to listen to music in my terminal. Sometimes I still use ncmpcpp as a command-line client, but recently I switched to rmpc. It is like ncmpcpp, but it offers a nice cover view out of the box, at least in the ghostty terminal. The latest release from February 2026 has a bug preventing it from displaying covers in iTerm, though this was fixed on main and has not yet been released. I tried to make covers available in ncmpcpp, but on Mac it seems to be a bit harder than on Linux, so I gave up :)

To keep my metadata clean and download covers I am using Mp3tag.

P.S. I still scrobble music on Last.fm, and many of my friends do too. I have been doing this since 2008, although I created a new account in 2011 and had a few years off from more active music listening practices in between. I remember the time when Last.fm felt more like a social network; now it is only a shadow of its former glory. Call me old-school, but I really enjoy documenting my listening practices, not only on Last.fm but also on Rate Your Music. It is also still a great way to peek at what your friends are listening to and what albums to try next, especially lists on Rate Your Music(the lists were hot there long before Letterboxd). Scrobbling still gives a kind of continuity to my listening, even when the software around it changes.

A bit of technical setup #

I installed mpdscribble to enable scrobbling via MPD. There is also a handy command to restart services, since I installed mpd and mpdscribble via Homebrew:

brew services restart mpd mpdscribble
brew services stop mpd mpdscribble

When I add new albums or move them between folders, for refreshing the local mpd database I use:

mpc update --wait

As I wrote before, one thing I have been thinking about is how much choice I have in my library, and how often that makes my attention switch too quickly. There are too many albums to choose from, so I decided to randomize the process a bit and make it easier to return to records I might otherwise overlook.

Rigelian offers random albums out of the box, but when I am listening in the terminal, I am using a small script added to my .zshrc to cache albums, pick one at random, and keep a short history so I can replay earlier picks.

My MPD settings in ~/.mpd/mpd.conf look like this:

bind_to_address "127.0.0.1"
bind_to_address "::1"
#bind_to_address "/Users/daniel/.config/mpd/socket"
port "6600"
audio_buffer_size "8192"
buffer_before_play "25%"
music_directory "/Users/daniel/Music/Moja muzyka"
audio_output {
type "osx"
name "Mac Output"
mixer_type "software"
audio_output_format "44100:16:2"
}

# part of .zshrc
album_cache_file="$HOME/.cache/mpd-albums.tsv"
album_history_file="$HOME/.cache/mpd-last-album.tsv"


rebuild_album_cache() {
 mkdir -p "${album_cache_file:h}"

 mpc -f '[[%albumartist%]|[%artist%]]\t[%album%]' search '(album != "")' |
 awk -F '\t' 'NF >= 2 && $1 != "" && $2 != "" && !seen[$1 FS $2]++ { print $1 FS $2 }' \
 > "$album_cache_file"

 printf 'Cached %s albums\n' "$(wc -l < "$album_cache_file" | tr -d ' ')"
}

random_album_cached() {
 [ -s "$album_cache_file" ] || rebuild_album_cache

 local choice artist album
 choice="$(
 python3 - "$album_cache_file" <<'PY'
import random, sys, pathlib
p = pathlib.Path(sys.argv[1])
rows = [line.rstrip("\n") for line in p.read_text(encoding="utf-8").splitlines() if line.strip()]
print(random.choice(rows) if rows else "", end="")
PY
 )"

 [ -z "$choice" ] && { echo "No albums found."; return 1; }

 artist=${choice%%$'\t'*}
 album=${choice#*$'\t'}

 printf 'Playing: %s — %s\n' "$artist" "$album"
 mpc clear
 mpc findadd albumartist "$artist" album "$album" || \
 mpc findadd artist "$artist" album "$album"
 printf '%s\t%s\n' "$artist" "$album" >> "$album_history_file"
 mpc play
}

# Updated replay function
replay_album() {
 [ -s "$album_history_file" ] || { echo "No album history."; return 1; }
 local n=${1:-1} total line artist album
 total=$(wc -l < "$album_history_file" | tr -d ' ')
 (( n > total )) && n=$total
 line=$(tail -n "$n" "$album_history_file" | head -n 1)
 artist=${line%%$'\t'*}
 album=${line#*$'\t'}
 printf 'Replaying (%d ago): %s — %s\n' "$n" "$artist" "$album"
 mpc clear
 mpc findadd albumartist "$artist" album "$album" || \
 mpc findadd artist "$artist" album "$album"
 mpc play
}
alias rra='replay_album'
alias ra='random_album_cached'

Tracking commits across multiple repositories with Beeminder

dtborek@gmail.com (Daniel Borek) — Sat, 07 Mar 2026 00:00:00 +0000

Beeminder is a habit-tracking tool built around committing to measurable progress over time. You can even put real money on the line, so missing your target comes with a financial sting — and for some people, that extra bit of accountability is surprisingly effective. It also integrates with various services, which makes it easy to track progress automatically instead of logging everything by hand. For programming, tracking habits like commits can help maintain momentum and make it easier to notice when you are quietly drifting away from a project.

Beeminder used to have an option to track commits across your whole GitHub account, but for new goals that is not really available anymore. The simple workaround is to create one Do More goal and let each repository send commit counts to it.

It sounds more complicated than it is. In practice, you create one Beeminder goal, add three secrets to each repository, and drop the same GitHub Actions workflow into all of them.

Create a Do More goal #

Create a normal Do More goal in Beeminder.

I used:

goal slug: github-commits
units: commits

Then go to Beeminder account settings and copy your API token from Apps & API.

Add secrets to each repository #

In every repository, go to:

Settings -> Secrets and variables -> Actions -> New repository secret

Add these three secrets:

BEEMINDER_USERNAME
BEEMINDER_TOKEN
BEEMINDER_GOAL

For BEEMINDER_GOAL, use your goal slug, for example github-commits

Add the workflow #

Create .github/workflows/beeminder-commits.yml in each repository:

name: Send commits to Beeminder

on:
 push:

jobs:
 beemind:
 runs-on: ubuntu-latest
 steps:
 - name: Send commit count to Beeminder
 env:
 BEEMINDER_USERNAME: ${{ secrets.BEEMINDER_USERNAME }}
 BEEMINDER_TOKEN: ${{ secrets.BEEMINDER_TOKEN }}
 BEEMINDER_GOAL: ${{ secrets.BEEMINDER_GOAL }}
 COMMITS_JSON: ${{ toJson(github.event.commits) }}
 REPO: ${{ github.repository }}
 SHA: ${{ github.sha }}
 REF: ${{ github.ref }}
 run: |
 count=$(python - <<'PY'
 import json, os
 data = os.environ.get("COMMITS_JSON", "[]")
 try:
 commits = json.loads(data)
 print(len(commits))
 except Exception:
 print(0)
 PY
 )

 if [ "$count" -eq 0 ]; then
 echo "No commits to send"
 exit 0
 fi

 curl -sS -X POST "https://www.beeminder.com/api/v1/users/${BEEMINDER_USERNAME}/goals/${BEEMINDER_GOAL}/datapoints.json" \
 -d "auth_token=${BEEMINDER_TOKEN}" \
 -d "value=${count}" \
 -d "comment=${REPO} ${REF} ${SHA}" \
 -d "requestid=${REPO}-${SHA}"

That is all the plumbing. Every time you push, GitHub Actions runs the workflow, counts the commits in that push, and sends that number to the same Beeminder goal.

A small note #

This counts commits in the push payload. For normal use that is fine. If you work across several repositories, this gives you one combined Beeminder graph without depending on the old GitHub integration.

If you only want to count pushes on main, change this:

on:
 push:
 branches:
 - main

Option 2: Count only your own commits #

If you work in shared repositories, you may want to count only commits authored by you. In that case, you can filter commits by the email stored in your Git metadata. I have not battle-tested this setup yet in a repository with more active contributors, so treat it as a proposition of a workaround rather than something fully verified under shared-repo conditions.

name: Send my commits to Beeminder

on:
 push:

jobs:
 beemind:
 runs-on: ubuntu-latest
 steps:
 - name: Check out repository
 uses: actions/checkout@v4
 with:
 fetch-depth: 0

 - name: Send only my commit count to Beeminder
 env:
 AUTHOR_EMAIL: your.email@example.com
 BEFORE: ${{ github.event.before }}
 AFTER: ${{ github.event.after }}
 BEEMINDER_USERNAME: ${{ secrets.BEEMINDER_USERNAME }}
 BEEMINDER_TOKEN: ${{ secrets.BEEMINDER_TOKEN }}
 BEEMINDER_GOAL: ${{ secrets.BEEMINDER_GOAL }}
 REPO: ${{ github.repository }}
 SHA: ${{ github.sha }}
 REF: ${{ github.ref }}
 run: |
 count=$(git log --format='%ae' "${BEFORE}..${AFTER}" \
 | awk -v author="$AUTHOR_EMAIL" '$0 == author {c++} END {print c+0}')

 if [ "$count" -eq 0 ]; then
 echo "No matching authored commits to send"
 exit 0
 fi

 curl -sS -X POST "https://www.beeminder.com/api/v1/users/${BEEMINDER_USERNAME}/goals/${BEEMINDER_GOAL}/datapoints.json" \
 -d "auth_token=${BEEMINDER_TOKEN}" \
 -d "value=${count}" \
 -d "comment=${REPO} ${REF} ${SHA}" \
 -d "requestid=${REPO}-${SHA}"

To find the email you should put in AUTHOR_EMAIL, check the one Git actually uses in your commits rather than only the one stored in your general config. In a repository, you can run git log -1 --format='%ae' to print the author email from your most recent commit, which is usually the safest value to use here. You can also inspect your configured email with git config user.email for the current repository or git config --global user.email for your global Git setup.

Connecting Zotero to AI Assistants via MCP

dtborek@gmail.com (Daniel Borek) — Sun, 08 Feb 2026 00:00:00 +0000

If you use Zotero for managing your research library, you might want to talk to your papers using an AI assistant. The Model Context Protocol (MCP) makes this possible — your AI can search, summarize, and analyze your local Zotero library, and if you use a local model, you can do it without uploading anything to third-party servers. Or you can use semantic search with ZotSeek directly within the Zotero desktop app to resurface relevant papers hidden in your library and get better semantic search when the keyword isn’t in the title or abstract.

Disclaimer: to get some of the setup running, I used a debugging session with a chatbot, and a big part of this post was first dictated by me, then converted from speech to text with an open model (Parakeet on MacWhisper), cleaned via chatbot, and finally checked and edited by me (with some additional edits after I received feedback and tried to help some friends with install).

Why use your own library? #

There is a risk of chatbots hallucinating when you work in research — and one of the worst kinds is hallucinated bibliography. The AI just makes up references that don’t exist. The best way to limit this is to not rely on internet sources you can’t verify, but to ground the conversation in your own bibliography instead. Especially when you’ve accumulated several thousand papers over your whole research career — sometimes you forget you have something relevant sitting in your library. This tutorial is about chatting with your own curated database of publications. You still need to be careful and verify what the AI says, but you can really limit the risk of total hallucination by grounding it in your own selection of relevant papers. It’s useful when the topic you’re working on connects to things you already collected — you ask for context and it pulls from what you know is real.

Even with your own library as the source, the AI can still get creative with what it attributes to your papers — it connects things very well, sometimes too well, adding claims that are only loosely present in the original text. Please read carefully and verify any ‘discoveries’ made by your AI companion :)

What is free, what costs money #

With Zotero MCP, the local part — indexing and searching your library (if you use open-source embeddings) — is completely free. What costs money is AI inference, meaning the chatbot subscription you use to actually have a conversation (Claude, ChatGPT, Mistral, etc.). Similarly, ZotSeek does the retrieval and semantic search part entirely for free and locally — after the initial indexing, it works without any additional computation; you only need to re-index when you add new PDFs to your library (I wrote more details about the setup of it in the last sections of this blogposs)

So in practice: the search/RAG layer is free, the chat layer requires a subscription or your local compute resources. But many of you probably already have one — you’d just use tokens from your existing plan a bit faster.

Personally, I use Claude — the setup is the easiest. But I also wanted to test a European alternative, so I set it up with Mistral Le Chat as well. If you’re a student, Mistral has a cheap subscription around €7. The quality is a bit below the latest biggest models from Anthropic or OpenAI, but you can still get a lot of value from it. The Mistral setup is more convoluted though — I figured it out together with Gemini, so I put more details in that section below.

A word on token budgets: if you’re on Claude Pro, the bigger models (like Opus with extended thinking) eat through your tokens much faster than Sonnet. In my experience, a Pro subscription gives me roughly 1.5 hours of intensive work with Opus before hitting the limit. The allowance resets every 5 hours, so I plan my work in cycles — a focused session in the morning, then another after the reset, and so on. On a free plan, expect a smaller token budget; also take into account the weekly token budget, otherwise you will quickly hit the wall.

(Edit 2026-02-26) There is always the possibility to work with any tool or model that adheres to and supports MCP standards. I connected to my Zotero via the same MCP while using LM Studio on my Mac and local models (this time Qwen3.5-35B in MLX format, but it should also work with smaller models and other tools). I now do less complex searches or tasks with my local LLM to spare budget for more complex queries in Claude when I need them. There are obviously some limitations, but for clearly defined tasks local inference is pretty useful.

A word on security: when using the Mistral/ngrok setup, be careful not to expose your computer to the outside. Always use a password and do not share your ngrok links with anyone.

One more thing — there’s also ARIA, a plugin that lets you chat with your PDFs directly inside the Zotero application using your own API keys. It costs additional tokens and I haven’t used it much myself, but if you want to stay entirely within Zotero, check it out.

I’m also maintaining a curated list of useful Zotero plugins on GitHub — I’ll be adding new ones as I discover them.

I also assume you have minimal experience with the command line and Python installation; instead of uv, you can install the MCP server via pipx or another way to make it available in your environment. This setup is tested on macOS, but in principle it should work on other OSes (I didn’t test it; the main difference I can think of might be path handling between OSes).

It will also serve as a reminder for me — every time there is a new ngrok instance, you need to repeat the Mistral setup.

Zotero MCP is available only locally via the Claude desktop app. I am not related to the development of any of these tools — you can always ask me questions, but if you find a bug or something is unclear in the documentation, let the developers know via a GitHub issue (and thank them ;)).

Install Zotero-MCP #

The tool we need is zotero-mcp (documentation). It works with Claude Desktop, ChatGPT, Mistral Le Chat, and other MCP-compatible clients.

Prerequisites #

Zotero 7+ running on your computer
Python installed (with uv package manager recommended)
In Zotero: go to Settings > Advanced and ensure “Allow other applications on this computer to communicate with Zotero” is checked

Install MCP #

Note: You can either install uv directly or with the help of brew. brew is a community package manager for macOS: https://brew.sh/. For both methods, you need to use Terminal. If you haven’t used Terminal before, you can open it on Mac with Option + Space and search for “Terminal”. The easiest install command is:

uv tool install zotero-mcp-server
zotero-mcp setup # Auto-configure (Claude Desktop supported)

During the setup you will have occasion to configure the semantic search. After setup, initialize your search database:

# Build with full-text extraction (slower, more comprehensive)
zotero-mcp update-db --fulltext

Optional: Enable Semantic Search #

For AI-powered similarity search across your library (beyond basic keyword matching):

zotero-mcp setup --semantic-config-only
zotero-mcp update-db --fulltext

The --fulltext flag indexes the full text of your PDFs, which is slower but gives much better results. Without it, only metadata is indexed.

For more details and more options check the github repository of the MCP and semantic search section.

Setup for Claude Desktop (recommended) #

When you installed and have run the command

zotero-mcp setup # Auto-configure (Claude Desktop supported)

you’ve alreade done that. This auto-configures your claude_desktop_config.json. Restart Claude Desktop and you’re done — Zotero tools will appear in your conversation.

If you prefer manual config, add this to your claude_desktop_config.json:

{
 "mcpServers": {
 "zotero": {
 "command": "zotero-mcp",
 "env": {
 "ZOTERO_LOCAL": "true"
 }
 }
 }
}

Setup for Claude code (assuming mcp server is instlled already):

claude mcp add --scope user zotero ~/.local/bin/zotero-mcp \
 -e ZOTERO_LOCAL=true \
 -e ZOTERO_EMBEDDING_MODEL=default

then verify it via

claude mcp list

In a fresh session (or after /mcp reconnect), the Zotero tools become available. In case of issues use absolute path to your user instead of ~.

Qwen Desktop/Studio #

Assuming you have uv installed and configure zotero-mcp in other steps, add this directly to the qwen app (tested on MacOS only)

{
 "mcpServers": {
 "zotero": {
 "command": "uvx",
 "args": ["zotero-mcp"],
 "env": {
 "ZOTERO_LOCAL": "true"
 }
 }
 }
}

Setup for ChatGPT #

According to the MCP documentation, ChatGPT also supports MCP now, but the MCP requires a slightly different configuration:

uv tool install zotero-mcp-server
zotero-mcp setup --no-claude

The --no-claude flag creates a standalone configuration optimized for ChatGPT’s specific tool naming requirements.

Other option is to use OpenAI codex directly with you installed MCP

codex mcp add zotero \
 --env ZOTERO_LOCAL=true \
 --env ZOTERO_EMBEDDING_MODEL=default \
 -- /Users/daniel/.local/bin/zotero-mcp

And the just have conversation in termin in mode /plan

Setup for Mistral Le Chat #

Mistral Le Chat supports MCP via remote connectors, which means you need to expose your local MCP server through a secure tunnel. This section covers both the one-time setup and the daily workflow.

The mental model: Your Zotero library is a locked room. The MCP Server is the librarian inside. ngrok punches a temporary (or permanent) tunnel through your firewall so Mistral can talk to the librarian.

You will need ngrok installed and authenticated — we cover that first.

Step 0: Install ngrok and Claim Your Permanent Address #

By default, ngrok gives you a random address that changes every time you restart it, which means re-configuring Mistral every day. To avoid this, claim one free permanent domain — you only do this once.

Install ngrok (using the same brew tool as before):

brew install --cask ngrok

Connect your account: Go to ngrok.com, sign up for a free account, and paste the auth command it gives you:

ngrok config add-authtoken YOUR_PERSONAL_TOKEN_HERE

Optional — Claim a permanent domain: By default, ngrok gives you a random URL that changes every time you restart it, which means updating Mistral’s connector every day. To avoid this, log into your ngrok Dashboard, click “Create Domain”, and copy the free address it gives you (e.g. fancy-shrimp-1.ngrok-free.app). This becomes your permanent “phone number.”

Step 1: Start the MCP Server #

TThis section assumes you have already installed and configured zotero-mcp on your computer using previous step. Open your terminal and run the server in SSE mode:

uv tool run zotero-mcp serve --transport sse --port 8000

Keep this terminal open.

Step 2: Open a Secure Tunnel #

Open a new terminal tab and run:

ngrok http 8000 --basic-auth='admin:your-password'

(Use single quotes ' around the credentials to prevent Zsh errors)

You will see a deprecation warning — this is expected, the flag still works. Copy the Forwarding URL from the output (e.g. https://xyz-123.ngrok-free.app).

If you claimed a permanent domain in Step 0, use instead:

ngrok http 8000 --url=YOUR-DOMAIN.ngrok-free.app --basic-auth='admin:your-password'

Step 3: Get Your Auth Token #

Mistral needs your credentials encoded in Base64. Run this in a third terminal tab:

echo -n 'admin:your-password' | base64

Copy the output string (e.g. YWRtaW46eW91ci1wYXNzd29yZA==).

Step 4: Configure Mistral Le Chat #

Go to Mistral Le Chat > Connectors (plug icon) > + Add Connector > Custom MCP Connector.

Field	Setting	Note
Connector Server	`https://YOUR-NGROK-URL/sse`	Must end in `/sse`
Authentication	`API Token Authentication`
Header Name	`Authorization`
Header Type	`Basic`	Select from the dropdown
Header Value	`YWRtaW46c2VjcmV0`	Paste only the Base64 code

Click Create.

Daily Workflow #

Every time you want to chat with your papers:

Open Terminal → run the MCP Server command (Step 1).
Open a second tab → run the ngrok command (Step 2).
Open Mistral and start chatting.

If you set up a permanent domain, you never have to touch the Mistral connector again. If not, you will need to repeat Steps 3 and 4 each time your ngrok URL changes.

Troubleshooting (Mistral) #

“404 Not Found” — You forgot to add /sse to the end of the URL.
“401 Unauthorized” — The Base64 string doesn’t match the credentials you passed to --basic-auth. Re-run the echo command and paste the fresh output. Or you typed “Basic” twice (once in the dropdown, once in the text box).
“MCP connection requires additional information…” — Usually a malformed URL or header. Try the nuclear option below.

The “Nuclear Option”: If the dropdown menus are fighting you, bypass them by putting the credentials directly in the URL. Set Authentication to None and URL to: https://admin:secret@your-ngrok-url.ngrok-free.app/sse

Bonus: How to use ZotSeek directly in Zotero? #

ZotSeek uses semantic search, which means you can find similar papers by meaning, not just keywords. It is 100% local, and no data leaves your machine.

There is a pretty neat explanation in the project GitHub README, but if you are new to more advanced use of Zotero, you need to:

Download the plugin.

Go to the project releases page and download the latest file with the .xpi extension.

Install that extension as a plugin in Zotero via Tools (you can find it in the Zotero menu, on the same level as File, Edit, etc.), then pick Plugins. In the upper-right corner, click the small cog button, select Install plugin from file, and then enable the plugin via the toggle by its name.

After enabling it, you can play with its settings (you need to go to Zotero settings; the plugin section will be just below the Zotero sections together with other plugins).

I advise first picking the Abstract only option for indexing, and automatically indexing new items. You can also run the “Update index” action (located at the bottom of the settings pane; you will probably need to scroll to it) to index unindexed items in your library.

I did indexing in abstract-only mode — 1 chunk per paper — and 6k papers used 20 MB of disk space and took a bit less than 1 hour to index.

Other tools worth checking #

MCP for Various scientific engines search #

If you already installed uv for Zotero MCP, another useful companion tool is paper-find-mcp. Instead of searching your own Zotero library, it lets your AI assistant search across external academic sources such as arXiv, PubMed, bioRxiv, medRxiv, IACR, Google Scholar et cetera.

It is available on PyPI as paper-find-mcp, and the project documents both uv/pip installation and Claude Desktop configuration via an MCP server entry in claude_desktop_config.json.

If you already installed uv to use with Zotero mcp in previous step, you can easily install this package via:

uv pip install paper-find-mcp

After installing, you only need to add new mcp defnition to claude config file (the example below), pleasebe careful with correctly closing json brackets.

open ~/Library/Application Support/Claude/claude_desktop_config.json

{
 "mcpServers": {
 "paper_find_server": {
 "command": "uvx",
 "args": ["paper-find-mcp"],
 "env": {
 "SEMANTIC_SCHOLAR_API_KEY": "",
 "CROSSREF_MAILTO": "your_email@example.com",
 "NCBI_API_KEY": "",
 "PAPER_DOWNLOAD_PATH": "~/paper_downloads"
 }
 }
 },
 "preferences": {
 "chromeExtensionEnabled": false,
 "coworkScheduledTasksEnabled": true,
 "sidebarMode": "chat",
 "coworkWebSearchEnabled": true
 }
 }

Tracking Word Count Progress in Git

dtborek@gmail.com (Daniel Borek) — Thu, 05 Sep 2024 01:00:00 -0700

I created a simple script to count word changes in my git repository. I’m trying Typst now for writing an article in VSCode, and there’s no good extension to quantify daily progress. This script looks at your commits, counts words added, deleted, and duplicated in the files of the extension by your choice (by default .typ and .md files). It shows a daily breakdown of writing progress.

Got the idea from a Gijs van Dam’s blog post (who described logic behind the word change calculation). I adapted it by adding Typst and extending the way it display the output. I add some additions like handling the first commit: The script checks if it’s dealing with the first commit in the repo, which doesn’t have a parent to compare against and it stops.

It’s been helpful for tracking my word count (and writing it was a nice excuse to not writing the text I supposed to write). Below you can find the gist with the latest version.

Github Education Pack and other tips

dtborek@gmail.com (Daniel Borek) — Fri, 14 Jun 2024 01:00:00 -0700

GitHub is a powerful platform (if you stayed on it after it was bought by Microsoft) that you can use for version control with Git and collaborative software/project development.

Apart of its main purpose for managing and maintaining your projects, and many people are familiar with the basic functionalities of GitHub, there are several valuable features that even experienced users might overlook

This is a bit trivial information but I know that are some people (mostly academic colleagues) who were using Github and for whom this information was new when I shared with them. The post will be updated if I will learn about features.

If You Are a Student, Ask for the GitHub Education Pack #

If you are a student, you can apply for the GitHub Student Developer Pack, which offers free access to various developer tools, resources, and services. Some of the best perks include access to Microsoft Copilot inside VSCode, a license for PyCharm Professional Edition (which supports some great features), and a year of a Namecheap domain.

You also get a year of a free domain with a .me ending on Namecheap, a free 3-month individual subscription to DataCamp, and access to other perks. Some of these perks might not be as useful, but you may find something valuable, like computing credits on Azure and other services for machine learning. More details can be found here: GitHub Education Pack

When applying, if you encounter verification issues, you might find useful this comment from related discussion :

You are unlikely to be verified until you have completed your GitHub user profile with your full name as it appears in your academic affiliation document, plus a short bio.

Overall, having a good presence and short introduction on your profile is a good idea.

Even after successful verification, you might need to wait up to 72hours, and in peak times like the start of the semester even longer.

Use Favorites for Easy Access to Repositories #

The staring a favorites repo is a pretty standard feature, but a new shiny beta feature is “lists,” which you can create and add repositories to when starring them. This is useful for creating low-effort, different collections.

Be Notified About Releases of Specific Packages #

To stay updated on the latest releases of specific packages or repositories, you can “Watch” the repository. This is one of the badges on the top of the repository view. By default, the “Participation and mentions” option is active. When you choose “Custom,” you can select “Releases Only” to stay informed about the latest updates.

Utilize GitHub Pages for Hosting #

GitHub Pages allows you to host static websites directly from your repositories. This is an excellent way to showcase your projects, create documentation, or even host a personal blog. It’s free and integrates seamlessly with your GitHub workflow.

For creating webpages you can use static site generators that use markdown.
Hugo and Jekyll are great for that (Hugo is really fast, i switched from Jekyll ), but if you work with code and often want to showcase you project notebooks as blogpost you might think about using Quarto for blogging .

Open Github repository on the web in vscode #

You can open your repository in the vscode in your browser replacing github.com by vscode.dev. It may be useful when you travel and have only access to your tablet et cetera.

Streamline Your Research: Zotero's File Management Tricks

dtborek@gmail.com (Daniel Borek) — Thu, 13 Jun 2024 00:00:00 +0000

After listening an episode of PhD Life Coach podcast (recommend to everyone related to academia) on How to be your own best personal assistant Iearned that some academic people still spent their time on renaming pdfs downloaded from internet. I want to share an important message to those people :) :

If you deal if structured articles (web, pdf) please use Reference Mangers, even if you don’t cite those articles that often; It will remove many of your headaches and you can have nice organization of your research materials
Even if you want to store PDFs inside specific projects a Reference Mangers can be really useful by automatic file renaming for you (you can move this files to another folder later). If you need to standardize the naming convention for all your PDF files or want to include specific metadata in the file names, Zotero or other reference mangers offers built-in functionalities and add-ons to achieve this efficiently.

Here a quick tips how to rename files using Zotero.

I am using Zotero 7 Beta (which offer nicer interface that Zotero 6 and some additional features like epub or webpages annotation, and is really stable and I hope will soon released as stable version) so my description might be slightly different from what people using previous version may sees .

In Zotero go to Edit > Preferences (or Zotero > Preferences on a Mac).
In the General tab, check the box •Automatically rename locally added files

The ‘Rename linked files’ will matter only the files added to Zotero items aren’t story with Zotero folder (where every bibliographic item has its own folder with the not so meaningful alphanumeric name ) but out outside of Zotero (when you move the file, you will broke the link )

if you click Customize Filename Format… you can customize the format,.

For example using filename template
{{ firstCreator suffix=" - " }}{{ year suffix=" - " }}{{ title truncate="100" }} the resulting name will result in the filename similar to the one below: Aljalal et al. - 2024 - Selecting EEG channels and features using multi-objective optimization for accurate MCI detection v.pdf

On the official documentation page you can find the options you can use explained in more depth file_renaming [Zotero Documentation]

You easily rename in bulk the files that you already downloaded and store in Zotero if for some reason you prefer to change the pattern in the future.

Zotero is adding a great QoL value with its Browser Plugin Zotero Connector (which automatically download and add pdf (if you have access to it on publishers page) or snapshot of webpage to your local library ), and apparently this is not a comment knowledge, as prof. Inga Mewburn from [The Thesis Whisperer][thttps://thesiswhisperer.com/] blog and On the reg podcast recently admitted in one of the episodes that she learned about the connector after few years of using Zotero.

If you prefer to have linked files in one big folder, the Zotfile or other plugin that offer the same capabilities are something for you.

Even if you prefer have PDFs in the folders of your projects, you can always easily open folder containing the renamed files and move it to the project folder.

I didn’t create here a full tutorial or covered many helpful features of Zotero, but you can find many great tutorials on the internet. I am also a big fan of integrating Zotero with Obsidian, you could find some example vault how it could be used here:rlaker/Obsidian-for-Academia: Demo vault to explain how to use Obsidian, git and Zotero with another writeup here: Integrating Obsidian with Zotero – RadOncNotes.

Zotero 7 is coming …

dtborek@gmail.com (Daniel Borek) — Tue, 15 Aug 2023 00:00:00 +0000

Edit 1: Zotero 7 was realeased officialy in August 2024.

Zotero is a free, open-source reference management software. It make the process of collecting and storing references pretty easy (sometimes too easy !).

The latest stable, big release version, Zotero 6, was introduced in March 2022. It brought a new built-in PDF viewer and annotation system, as well as iOS and iPadOS apps.

Zotero 7 is Coming #

Recently, the devs shared a public beta of Zotero 7. Most of the updates are related to transitioning from the legacy Firefox 60 ESR, which Zotero was originally built on top of (Zotero started as a browser extension), to the newer Firefox 102 ESR now and Firefox 115 ESR before the release this year.

What’s exciting is the native support for Apple Silicon desktop devices and an even better reader, with EPUB support and web annotation. An Android app is also in development.

Plugins I’m Using in Zotero 7 #

As an avid Zotero user, I’ve tested my fair share of plugins to optimize my workflow. While Zotero is great on its own, plugin take it to the next level for managing citations and references. Unfortunately with the changes to Zotero app, many plugins doesnt support beta yet. Below those I am using and are ported (or will be ported soon):

GitHub - retorquere/zotero-open-pdf
Since introduction of Zotero 6 users can opt to use new build-in PDF reader. I like the new new reader, but sometimes need to open the PDF in external PDF reader (PDF Expert in my case). This simple plugin lets you open PDF in external PDF reader via right click menu, instead of tedious opening in folder.
Better BibTeX for Zotero :: Better BibTeX for Zotero.A must-have for LaTeX/Obsidian/Pandoc users like myself. Provide citekeys. Ported with much of work due to many changes in Zotero 7.
GitHub - windingwind/zotero-pdf-preview: PDF Preview for Zotero. Enables live PDF miniature previews right in my Zotero item info pane so I can quickly confirm I have looking into right paper without open the item. Current changes to PDF Reader (Zotero 7 beta 29) broke it, it still doesn’t work as for the middle of August;
GitHub - wshanks/Zutilo: Zotero plugin providing some additional editing features A nice collection of tools, still in the process of porting.

While Zotero 7 has some additional compatible plugins I don’t use or haven’t tested, many of the best plugins remain available only for Zotero 6."

Edit 2: Some additional extensions not mentioned earlier, that I am currently using (in 2024):

Markdown translators #

Useful pair of Zotero translators when you want to link to Zotero item as Markdown link
https://github.com/erazlogo/zotero-markdown-translators

PDF tweaks and tips with Quarto

dtborek@gmail.com (Daniel Borek) — Fri, 04 Aug 2023 00:00:00 +0000

Disclaimer: This is work in progress, I will be updating this post as I standardize and create a separate template/extension repository.

I wrote my master thesis in LaTeX, but given that markdown is a bit nicer to write, so I decided to switch with my PhD thesis to Markdown.
I was trying with Pandoc but last year I switched to Quarto, as it is more flexible, and it is easier to customize.

Nicer Fonts and Better Handling of Figures #

I am sharing with you a fragment of my _quarto.yml file, with some tweaks I am using to make my PDF output nicer.

 format:
 pdf:
 link-citations: true # <1>
 number-sections: false
 reference-section-title: "References"
 pdf-engine: xelatex
 include-in-header:
 text: |
 \usepackage{epigraph}
 %%
 %% Code related to fonts and how the output looks
 %%
 \usepackage{mathpazo} % <2>
 \usepackage[T1]{fontenc}
 \usepackage[sups,osf]{fbb} % osf (or tosf) for text, not math # <2>
 \usepackage[scaled=.95]{cabin} % sans serif # <2>
 \usepackage[varqu,varl]{inconsolata} % sans serif typewriter # <2>
 %%
 %% Code related to figures in document
 %%
 \usepackage{float} % <3>
 \graphicspath{{figures}{chapters/figures}{../figures}{chapters}} # <4>
 \let\origfigure\figure
 \let\endorigfigure\endfigure
 \renewenvironment{figure}[1][2] {
 \expandafter\origfigure\expandafter[H]
 } {
 \endorigfigure
 }

I put number as comments, so you can better understand specific lines.

Some options for PDF output (more or less self-explanatory)>
The font use by default template are ugly format, this look similar but are nicer.
Forcing figures to be placed where they are in the text
Allowing to use figures from different folders, and allowing to use relative paths to figures.

Use Profiles to Compile either Whole Book or Thesis or Single Chapter #

Since quarto 1.2 profiles are introduced ¹ In my use case I have on profile _quarto-thesis.yml which include all chapters and preambles, and another _quarto.yml which I can use just to compile the current markdown file; If I want to render whole thesis I just use quarto render --profile thesis; you could have as many as you want of those profiles (I was procrastinating that way with different look and templates for my thesis :slight_smile: )

Roman Numbering for front Matter and Arabic for Main Matter #

I am inserting roman numbering for front matter and arabic for main matter.

 format:
 pdf:
 include-before-body:
 text: |
 \pagestyle{plain}
 \pagenumbering{roman}

In main tex I switch back to arabic numbering:

\pagenumbering{arabic}

Problem with index.md and Inserted Blank Page #

As you write complex project, you want might want to have separate files for each chapter.
When you are using quarto to render your project, you could put them inside index.md in your root folder:

{{include "chapters/chapter1.qmd"}}
{{include "chapters/chapter2.qmd"}}

Using include filter will add the content of the files to the index.md file when compiling.
This is nice solution, but I have a problem when I want to use quarto preview to update and monitor resulting pdf when I change something in source files.
Unfortunately, quarto preview does not update output .pdf file when files added with include change, so I needed to choose another solution.

Alternative solution is to add chapters into you _quarto.yml file:

project:
 output-dir: _output
 execute-dir: file

book:
 title: Title of my thesis or book
 author:
 name: Author Name
 chapters:
 - index.qmd
 - chapters/chapter1.md
 - chapters/chapter1.md

I want to all of my content of to live in the ‘chapters’ folder.
Unfortunately currently in quatro users always need to include index.md (it makes sense when generating html as output, but not always when generating pdf).

I can leave the index.md file empty, but then I will have an empty page between my table of content and first chapter.
I can include the first chapter into index.md but then we were hitting the same problem on smaller scale again.

My Solution #

By default, latex is adding a page break after each chapter, and the index.md file is treated as a chapter, even if empty.
As a hack, I am hiding the problem by relaxing \clearpage behaviour in latex.

I am leaving my index.md file almost empty, I’m just adding this latex code ²:

\let\standardclearpage\clearpage
\let\clearpage\relax

Then within my first chapter when my content start, I am returning to standard behaviour of \clearpage:

\let\clearpage\standardclearpage

This way I am not adding any extra page between my table of content and first chapter, and I can use quarto preview to monitor my changes.
In future the quatro behaviour might change regarding inclusion of `index.md``, you can follow discussion here:

Useful Materials #

I just saw this post published on the blog of Cameron Patrick, it contains more useful information about writing thesis with quarto: https://cameronpatrick.com/post/2023/07/quarto-thesis-formatting/.

I am personally using modified quarto-thesis template for my thesis, you can find it here: https://github.com/nmfs-opensci/quarto-thesis
If you don’t use quarto, but you want to play with it, you can modify it online on the Posit virtual Rstudio instance https://rstudio.cloud/content/4383755 (free account required)

References #

From Quarto with love (but back to Hugo)

dtborek@gmail.com (Daniel Borek) — Thu, 03 Aug 2023 00:00:00 +0000

I’ve been using different static site generators over the years - Jekyll, Hugo, and most recently Quarto. In this post I’ll share my experiences and how I’m now using Hugo and Quarto together for my blog.

Why I Switched back to Hugo #

I used Jekyll years ago (you can see one of the pages I created here), then switched to Hugo, and about a year ago I started using Quarto.

Quarto is great for scientific publishing, but I found it too limiting for a personal blog:

Every post must be in its own folder with an index.qmd file. This works well for showcasing content, but isn’t convenient for writing.
As a scientific publishing tool, the blog features remain an afterthought. The Quarto team is great about adding features, but blog improvements happen slowly.

So I decided to switch back to Hugo as my static site generator for the flexibility.

Fortunately, there’s no need to fully abandon Quarto. Quarto has built-in support for outputting to Hugo. I can use Quarto to render my posts written in qmd format into Markdown that Hugo can use.

Quarto Loves Hugo #

Here is a quick overview of how I have Hugo and Quarto working together:

I added some config settings to my Hugo config.toml file:

ignoreFiles = [ "\\.qmd$", "\\.ipynb$", "\\.py$" ]

[markup]
 defaultMarkdownHandler = "goldmark"
 [markup.goldmark.renderer]
 unsafe = true

I have a content/posts folder containing subfolders for each post, with a index.qmd file inside.
I put this _quarto.yml in the Hugo root directory:

project:
 type: hugo
format:
 hugo-md:
 code-fold: true
 html-math-method: webtex
execute:
 warning: false

To create post written in qmd files, I run quarto render which outputs Markdown from my qmd posts into the Hugo content folder.

I also found two nice blog posts from people using Quarto with Hugo:

🪄 Quarto, Hugo, Apero | Cédric Batailler. Cédric is using lovely Apero theme. I am finding this theme great, but I choose to stick with minimalism of lines theme.
Setting up a Hugo Website with Quarto | Paul Johnson. Paul is using a PaperMod theme, which is also very nice. He is a bit more technical in his post
Paul Johnson describe how he render mermaid diagrams (supported in Quarto) in this blogpost.

Customizing the Theme #

I started from the lines theme, you can find it here.
Later I mixed it with another theme, simplist by the same author and I added my custom CSS parts.

More Customisation #

I started with the Lines theme, customised it with styles from the Simplist theme, and added some of my own CSS.

Hugo and GitHub Pages #

I followed Hugo’s GitHub Pages guide but ran into some issues:

The theme submodule wasn’t syncing properly. I had to manually add the .gitmodules file.
The theme’s example content was cluttering my published site. I forked the theme and removed the examples.

Here is my final .gitmodules file:

[submodule "themes/lines"]
 path = "themes/lines"
 url = "https://github.com/danieltomasz/lines.git"

Hugo and Code Highlighting #

To get code highlighting in backticks markdown fences I enabled:

pygmentsStyle = "pygments"
pygmentsCodefences = true

Adding Comments with `giscus` #

I followed various blogpost with the configuration advices.
By default, giscus is adding comments to every page, but I wanted to have comments only on my posts.
I followed advice¹ and I wrapped my addition of giscus partial into footer.html with if statement:

{{ if not .Params.noComment }}
{{ partial "giscus" . }}
{{ end }}

When I don’t want to include a comments block, I am adding this in the frontmatter of the post (yaml):

noComment: true

Some other useful links: https://www.brycewray.com/posts/2022/05/tips-using-giscus/

Date of Last Edit Directly from Github #

Some advice how to set up it: Add a Last Edited Date to Posts · Make with Hugo.

One caveat: setting enableGitInfo to true in your site’s configuration file sometimes is not enough². You have to add --enableGitInfo to get .GitInfo:

hugo serve --enableGitInfo

Using Wikilinks and Git/Obsidian Callouts in Quarto Markdown

dtborek@gmail.com (Daniel Borek) — Wed, 31 May 2023 00:00:00 +0000

About Callouts #

Disclaimer: Previous version of this post was originally published as a public gist

Callouts are a great way to highlight important details in your text by adding boxes with icons. Many flavours of markdown support them (but might use different syntax).

Quarto supports 5 callout types:

note
warning
important
tip
caution.

Each type has a different color and icon. You can see examples in the Quarto documentation.

The Problem #

To use callouts in Quarto markdown (qmd) files, you need to use Pandoc’s div syntax:

::: {.callout-note}
This is a note callout
:::

But Obsidian doesn’t recognise this syntax. Instead, it uses:

> [!note] My note
>
> Note content

So there’s no easy way to preview nice callouts in Obsidian before compiling to PDF.

Github also introduced callouts into its markdown flavour with the same syntax under name of Alerts

Lua Filters to the Rescue #

Pandoc supports Lua filters that can modify the markdown before compilation.

I found a filter on the Obsidian forum and modified it to support Quarto callouts. You need to save the filter as obsidian-callouts.lua in your project’s filters folder.

Then point to it in _quarto.yml:

filters:
- filters/obsidian-callouts.lua

Content of the file obsidian-callouts.lua is in the following gist :

This makes Obsidian’s callout syntax compile properly in Quarto.

Tweaking Obsidian CSS #

By default Obsidian only styles note and warning callouts. To match Quarto, add this CSS:

/* See https://lucide.dev for icon codes */

/* annotation */
.callout[data-callout="important"] {
 --callout-color: 251, 70, 76;
 --callout-icon: lucide-alert-circle
}

.callout[data-callout="tip"] {
 --callout-color: 28, 207, 110;
 --callout-icon: lucide-lightbulb
}

.callout[data-callout="caution"] {
 --callout-color: 255,153,102;
 --callout-icon: lucide-flame
}

Now the callouts look (almost) the same in Obsidian and compiled PDFs!

Below is the Obsidian markdown that can be used to generate the basic 5 types of callouts that map nicely to Quarto types:

> [!note] My note
>
> Note content

> [!warning] My note
>
> Note content

> [!important] My note
>
> Note content

> [!tip] My note
>
> Note content

> [!caution] My note
>
> Note content

Obsidian support for callouts is much more extensive.

Caveat #

This approach makes callouts render nicely in Obsidian, but may break other Quarto-supporting editors. Test thoroughly before relying on it.

Remember that in order for callouts to work you need to leave an empty line starting with > between title and content. If you want a line break in the rendered callout, you might need the same trick.

Since Quarto 1.3 callouts are represented as a custom AST node. An earlier version of Lua filter that generated native Pandoc Divs will not work with latest Quarto.

Bonus: Wikilinks #

Obsidian also supports wikilinks, which are a great way to link between notes. They are not supported in Quarto, but you can use a Lua filter to convert them to regular text in the rendered file. Unfortunately, this version doesn’t fully support aliases in wikilinks. Also be careful, as this gist is not thouroughly tested, but works in all simple cases I tested it.

Add it to _quarto.yml or the yaml header of your document:

filters:
- filters/wikilinks-filter.lua

More Obsidian + Quarto Tips #

I use plugins to preview Quarto files in Obsidian:

obsidian-shellcommands to run quarto render
Custom button with commander to rerun compilation
qmd-as-md-obsidian for basic qmd support

See the plugin README for more workflow advice.

Let me know if you have any other questions!