DEV Community: Arthur

I got tired of reading Claude Code's .md files in VS Code, so I built a native Mac viewer

Arthur — Wed, 08 Jul 2026 08:44:34 +0000

Disclosure: I'm the developer of MacMD Viewer. Honest maker story — not a sponsored post.

Something changed when I started using Claude Code daily.

It drops markdown files everywhere. CLAUDE.md, plan.md, architecture notes after every session, progress summaries I didn't ask for. By the end of a sprint I'd have five .md files I hadn't actually read properly.

My workflow was Cmd+Shift+V into a VS Code preview pane. Which works. But I was always reading inside a code editor. The preview pane is half the screen. The file tree is still there. The terminal's still there. There's this constant friction between "reading mode" and "dev mode" that I couldn't shake.

I looked for a native Mac app that was specifically a viewer — read-only, one click to open, renders Mermaid, handles QuickLook properly. Couldn't find one I was happy with.

So I built one.

What I tried first (and why it didn't stick)

VS Code preview — already using it, already frustrated with it for long documents. Also: you can't just drag a .md onto it. You open VS Code, open the file, Cmd+Shift+V. Five steps to read one file. Feels wrong.

Typora — popular, but it's an editor. It opens in edit mode. I don't want to accidentally overwrite the plan Claude Code just wrote for me.

Obsidian — genuinely great app if you want a second brain. For opening a single file it's like using Photoshop to crop a photo. It also creates an .obsidian folder wherever you point it, which is fine in your notes directory and annoying everywhere else.

Quick Look (stock) — renders .md as plain text. Useless.

None of these were wrong tools. They were tools built for different jobs.

Building it — the two things that actually surprised me

I'm a Mac dev, I know Swift, I had two months of evenings. The architecture is straightforward: SwiftUI + WKWebView, markdown renders to HTML via highlight.js and mermaid.min.js, DocumentGroup for the native open-file model.

Two things caught me off-guard.

Swift 6 strict concurrency. I thought I was mostly there on actor isolation. I was not. Every function that touches WKWebView needs @MainActor. Not "most of them." All of them. I spent an embarrassing amount of time chasing "Sending 'coordinator' risks causing data races" warnings before I stopped fighting it and just marked the entire Coordinator class @MainActor. Then it worked. Swift 6 is right about this, it's just not gentle about teaching it.

The scroll spy. I wanted the sidebar to highlight the active heading as you scroll — one of those features that sounds simple until you actually try it. My solution: an IntersectionObserver injected into the WKWebView watches all headings; when one enters the viewport it fires window.webkit.messageHandlers.headingObserver.postMessage(id) back to Swift, and a WKScriptMessageHandler picks it up to update the UI. Works great.

The gotcha: I was calling MarkdownRenderer.render() in the SwiftUI view body to regenerate the HTML on each update. That function generates a fresh UUID nonce for the CSP on every call, which makes WKWebView treat it as a new document and reload from scroll position zero. Every. Time. The fix was caching the rendered HTML in @State and only regenerating it when the content actually changes. A weekend well spent, I guess.

The QuickLook part — this is the actual feature

MacMD ships a QuickLook extension alongside the main app.

Hit Space on any .md file in Finder. Rendered markdown. Syntax highlighting. Themes. Mermaid diagrams if they're in there. Not raw text. Not a wall of hashtags.

For my workflow this is the thing. Claude Code drops plan.md in my project. I'm in Finder. I hit Space. I read the plan. I close the preview. No app switch, no editor opening, no Cmd+Shift+V.

Honest specs (because I've seen some wild claims in this space)

highlight.js covers around 34 languages out of the box — I verified this in the source. Not 180+. Some tools claim ridiculous numbers.
No LaTeX / KaTeX support yet. It's on the list.
~10 MB install size. Not 2 MB either.
File watching works: when Claude Code updates the file you're reading, MacMD auto-reloads.

Where it is now

macmdviewer.com — $19.99, one-time, no subscription. Also on Homebrew (brew install --cask macmd-viewer) and Setapp.

I built it for my own workflow. Turns out the Claude Code / Codex / Cursor crowd has the same problem — AI agents write .md to disk, and macOS has no good native way to read them. That's the use case I'm focused on.

If you're on Mac and this sounds familiar, give it a try. If something doesn't work the way you'd expect, I respond to everything — I'm the only developer.

ChatGPT writes you a clean doc. Your Mac shows raw text with ## everywhere. Here's the fix

Arthur — Fri, 05 Jun 2026 10:11:09 +0000

Short version: if ChatGPT, Claude, or Cursor handed you a file that opens as a wall of #, *, and backticks on your Mac, that file is Markdown and nothing on your Mac is rendering it. Install a small app that adds a Finder preview for it, then hit Space on the file and it shows up formatted. Free options exist and they are covered below. If reading AI output is part of your daily work and you want the formatted view to refresh on its own each time an agent rewrites the file, that is the specific frustration I built MacMD Viewer to solve.

Why does my Mac show the file as raw text instead of a clean document?

Because the file is Markdown, and macOS has no built-in renderer for it. Markdown is a plain-text format where # Heading, **bold**, and - item are shorthand instructions for formatting. The model emits those symbols, your editor or chat window interprets them and shows you the pretty result, but the symbols themselves are all that gets saved to the .md file. There is no formatting baked in, only instructions waiting to be read.

The reason it looks fine in the chat and broken on disk comes down to who is doing the rendering. Inside ChatGPT or Claude, the web interface reads the Markdown and paints it for you in real time. The moment you download the file, you leave that renderer behind. Now it is just text. Double-click the .md and TextEdit shows the raw symbols, because it treats the file as plain text with nothing to interpret. Press Space in Finder and Quick Look shows the same raw text, because Apple ships Quick Look generators for PDFs, images, and .txt, but not for .md.

This was a niche annoyance for years, mostly hitting developers. Now that millions of people receive plans, specs, meeting notes, and drafts back from AI as .md files, it has become a daily papercut, and most people do not even know the file format has a name they can search for.

How do I fix it on macOS?

Pick the lightest tool that matches how often you actually hit this. There is no single right answer: a one-off problem and a daily workflow deserve different solutions, and overspending on a paper cut is its own mistake.

If it happens rarely. Do not install anything. Send the file's contents back into the chat that produced it and ask for it formatted, then read it right there in the browser. Or open one of the many free browser-based Markdown viewers and paste it in. VS Code also has a built-in preview if you already have it: open the file, then press Shift+Cmd+V. All free, slightly fiddly, perfectly fine for something you do twice a month.

If you want it to just work in Finder. Install a small Mac app that registers a Quick Look extension for .md. Once it is installed, pressing Space on any Markdown file shows it formatted in place: headings, bold, lists, links, code blocks, tables, and Mermaid diagrams too. You never open a separate app, you just preview like you would a photo. Readdown is a free app that does exactly this and does it well, and it even refreshes on its own when the file changes. QuickMD is another free option that renders Markdown and Mermaid, though it does not add a Finder Quick Look preview or refresh when the file is overwritten. If your needs stop at "I want Space to show me a clean doc," start with Readdown before paying for anything.

If you live in AI output all day. When you run Claude Code, Cursor, or any agent that writes files on your behalf, the same .md gets overwritten again and again as the model works. You want a window that stays open and repaints itself the instant the file changes. Readdown, the free option above, actually does this well, and if you just want the lightest free reader it is a genuinely great pick. I built MacMD Viewer for people who want a fuller, actively maintained and supported tool around that same live-reload idea. It is on Setapp and Homebrew (Readdown is a direct-download, no-account hobby project), it adds a Library window and 7 themes, and its live-reload is debounced at around 50ms so it keeps up cleanly with an agent overwriting the file in rapid bursts. Like the free tools it handles Mermaid and syntax-highlighted code, installs the Finder Quick Look extension, and is read-only by design (it never touches your files). It costs a one-time 19.99 dollars, no subscription. If you only need the occasional clean render, the free options above genuinely cover it.

Quick comparison

Tool	Price	Quick Look in Finder	Live reload	Mermaid
Paste back into the chat	free	no	no	no
Readdown	free	yes	yes	yes
QuickMD	free	no	no	yes
MacMD Viewer	19.99 once	yes	yes	yes
Typora (this is an editor)	14.99	no	n/a	yes
Marked 2 (this is an editor companion)	13.99	no	yes	no

What if I want to edit the file, not just read it?

Then you want an editor, which is a different category of tool. Everything above is tuned for reading AI output cleanly. If you plan to write Markdown yourself, Typora formats your text live as you type, and Obsidian is the better pick if you are assembling a connected notes system. But you do not need either one just to look at what the model handed you, and paying for an editor to solve a viewing problem is the long way around.

Full disclosure: MacMD Viewer is my own product, so weigh my praise for it accordingly. I have made a point of calling out exactly where the free tools are the smarter choice, since for plenty of readers that is the honest answer.

How Accountants Collect Client Documents Without Endless Email Threads

Arthur — Mon, 04 May 2026 08:57:16 +0000

Every accountant I've talked to has the same January nightmare: 80 clients, 12 missing W-2s, 30 unsigned engagement letters, and an inbox full of "I'll send it tomorrow" replies. Client document collection is the unglamorous bottleneck that turns a 6-hour return into a 3-week back-and-forth.

This guide walks through how modern accounting firms — from solo practitioners to 50-person practices — are killing the email thread and standardizing how they collect client documents in 2026.

Why email is the worst tool for collecting client documents

Email feels free. It's not. Every email-based document request costs an accountant roughly:

15 minutes per client to draft a personalized request
4–6 follow-ups to get all documents in
20+ minutes sorting attachments into the right folders
2–3 hours chasing missing items per active engagement

Multiply that by 80 clients during tax season and you've burned 200+ hours on coordination — before you've done a single calculation.

The real problems with email:

No status tracking. You can't tell at a glance who has sent what.
Attachment chaos. PDFs scattered across threads, named Scan_001.pdf.
Security risk. Sensitive financial data sitting in inboxes forever.
No reminders. You become the reminder system.
No client experience. Clients hate it as much as you do.

What good client document collection looks like

The firms that have solved this all share the same workflow shape:

A single request, sent once, listing every document the client owes
A magic-link portal the client opens without creating an account
Real-time status for both sides ("3 of 7 documents received")
Automated reminders for missing items
Auto-organized storage with consistent naming
One-click validation so the accountant accepts or rejects each upload

The shift is from "I'm chasing you" to "the system is chasing you, I'm reviewing what arrives."

Building a standardized document checklist

Before tools, you need a checklist. The biggest unlock isn't software — it's documenting what you actually need from each client type.

Individual tax return checklist (US example)

W-2 forms from every employer
1099s (NEC, MISC, INT, DIV, B)
Mortgage interest statement (1098)
Property tax records
Charitable donation receipts
Prior year return
Government-issued ID

Small business return checklist

P&L statement (current and prior year)
Balance sheet
Bank statements (12 months)
Payroll summary
Business mileage log
Equipment purchases over $2,500
Engagement letter, signed

Keeping these as templates inside your tool of choice means a new client request takes 30 seconds, not 30 minutes.

Tools for client document collection in 2026

Quick comparison of the main options:

Tool	Best for	Watch out for
Email + Dropbox	Solo, under 10 clients	Doesn't scale, security risk
Google Drive shared folders	Bookkeepers with recurring clients	No request workflow, no reminders
TaxDome / Karbon	Full practice management	Expensive, steep learning curve
DokuTrak	Firms that just need document collection	Newer entrant, less ecosystem
Custom client portal	Firms with dev resources	Maintenance burden

If you only need client document collection — without the full practice management stack — a focused tool like DokuTrak gets you to a working portal in under an hour. If you also need time-tracking, billing and project management bundled, look at the heavyweight platforms.

A workflow you can implement this week

Here's the lightest possible setup that still kills the email thread:

Day 1: Build your templates

Write 3 checklists (individual return, business return, bookkeeping onboarding)
Each line item gets a clear name and a one-sentence description

Day 2: Pick a tool

If you have under 5 clients, even a Notion page with file uploads works
Above 5, use a real document request tool with magic-link access

Day 3: Send your first request

Pick one new client and send a single, structured request
Resist the urge to also email them "just in case"

Day 4: Set up automated reminders

Day 3, day 7, day 14 cadence works for most clients
Make reminders friendly — clients are busy, not hostile

Day 5: Document the process for your team

Write a 1-page SOP
Decide which templates to use for which engagement

After two months, the email-thread habit is dead.

Mistakes that kill adoption

Three things sabotage rollouts I've seen:

Tool sprawl. If clients have to learn a new portal for every accountant, they revert to email. Pick one tool and stick with it for at least a year.
Over-customizing the checklist. Start with the 80% case. Edge cases ("client owns a yacht in Monaco") can stay as ad-hoc requests.
Skipping the engagement letter step. If your portal also handles signatures, your conversion-to-paying-client improves dramatically. Don't split signing and document collection across two tools.

FAQ

Is it secure to collect client tax documents through a portal?
Yes — provided the portal uses end-to-end encryption, magic-link or strong auth, and stores documents in a SOC 2 compliant region. Always more secure than email attachments.

Will older clients use a document portal?
Most will, if the entry point is a single email link with no account creation. Magic-link flows have ~85% completion rates even for clients over 60.

Do I still need DocuSign for engagement letters?
Not necessarily. Many client document collection tools now include e-signature, which removes one tool from the stack.

How does this compare to TaxDome or Karbon?
TaxDome and Karbon are full practice management platforms (CRM + billing + projects + portal). If you only need the portal piece, focused tools like DokuTrak cost a fraction and are faster to roll out.

How long until I see the ROI?
Most firms recover the time investment in the first tax season, often within 4–6 weeks of rollout.

Wrapping up

Client document collection is the highest-leverage process you can fix in an accounting practice. You don't need to rip out your existing stack — you just need to stop using email for the part it was never designed to do.

Pick a tool, write three checklists, and send your first request this week. Future-you, in the middle of tax season, will thank present-you.

How to Track Laptop Battery Health Across a Remote Team in 2026

Arthur — Mon, 04 May 2026 08:55:45 +0000

If you manage a remote team of 10+ people, laptop battery monitoring is one of those quiet problems you only notice when it's too late: a dev's MacBook dies on a client call, a sales rep's Dell shuts down mid-demo, or you suddenly need to replace 8 laptops in the same quarter because nobody saw it coming.

This guide walks through how to track laptop battery health across a remote team — the metrics that matter, the tools available in 2026, and a workflow you can roll out this week.

Why laptop battery health matters for remote teams

When everyone worked in the same office, IT could physically inspect machines. Remote work killed that. Today, a battery that's silently degrading on a remote worker's laptop becomes:

A productivity tax (machines die mid-meeting)
A budget surprise (emergency replacements cost 30–40% more)
A security risk (employees buy random chargers from Amazon)
An ESG liability (early replacements increase e-waste)

The fix isn't complicated. You need three things: the right metrics, a way to collect them automatically, and a threshold-based alerting system.

The 4 battery metrics you should track

Not every battery stat is useful. These four cover 95% of real-world decisions.

1. Cycle count

Every full charge-discharge counts as one cycle. Most modern laptops are rated for 1,000 cycles before significant capacity loss.

Healthy: under 500 cycles
Watch: 500–800 cycles
Replace soon: 800+ cycles

2. Design vs. full charge capacity

The ratio of current max capacity to original (factory) capacity. This is the single best predictor of remaining battery life.

Healthy: above 85%
Degraded: 70–85%
Failing: below 70%

3. Temperature

Sustained high temperatures kill batteries faster than cycle counts. If a battery regularly hits 40°C+, it's being stressed by a thermal issue (often dust, often a failing fan).

4. Charging behavior

Devices left plugged in at 100% for weeks degrade twice as fast. Track average state-of-charge over time and flag machines that never drop below 95%.

How to collect battery data without invading privacy

This is where most teams stall. Employees (rightly) push back on tools that look like spyware.

The minimum-viable, GDPR-compliant approach:

Collect only hardware telemetry (battery, CPU, RAM, disk)
Never collect screenshots, keystrokes, or browsing history
Document what's collected in your employee handbook
Give employees a way to view their own data

Native OS tools give you a starting point:

macOS: system_profiler SPPowerDataType
Windows: powercfg /batteryreport
Linux: upower -i $(upower -e | grep BAT)

Running these manually every month doesn't scale past 5 people. For real fleets, you need centralized collection.

Tools for fleet battery monitoring

A quick rundown of what's available in 2026:

Tool	Best for	Pricing model
Microsoft Intune	Windows-heavy enterprises	Per device/month
Jamf Pro	Mac-only fleets	Per device/year
Sobrii	Cross-platform SMBs and MSPs	Per device/month
Kandji	Apple-focused, design-led	Per device/month
Custom scripts + Grafana	Engineering teams who love yak-shaving	Free + ops time

Native MDM tools (Intune, Jamf) are heavyweight — they're built for compliance and config push, not for lightweight monitoring. If all you need is laptop battery monitoring plus basic hardware visibility, an agent-based tool like Sobrii will be cheaper to deploy and easier to explain to your team.

A simple weekly workflow

Here's the workflow we landed on after iterating with three different teams:

Monday: Auto-generated report drops in Slack

Devices with capacity below 80%
Devices with cycle count above 800
Anything reporting battery temperature alerts

Wednesday: IT reviews the list, opens replacement tickets for anything in the red zone

Friday: Replacements scheduled or shipped — no surprises at end of quarter

This took us from "emergency battery replacements every other week" to "two scheduled replacements per quarter, both budgeted."

Common mistakes to avoid

After helping a few teams roll this out, three patterns burn people:

Tracking too much. If you collect everything, you'll review nothing. Start with the 4 metrics above.
Setting thresholds too late. "Replace at 60%" means the laptop is already unusable. 80% is the right line.
Not telling employees. Surprise monitoring is the fastest way to lose trust. Always announce, document, and share the data.

FAQ

How often should I check battery health?
Weekly is enough for most teams. Daily is overkill unless you have 1,000+ devices.

Can I track battery health without installing an agent?
Partially. You can ask employees to run native commands and submit reports, but adoption tanks fast. An agent-based tool is the only sustainable approach above 20 devices.

Is laptop battery monitoring legal under GDPR?
Yes, if you collect only hardware telemetry, document it, and have a legitimate business interest. Get a sign-off from legal before rolling out.

What's the ROI of fleet battery monitoring?
At ~€150/year per device in monitoring cost, you break even if you avoid one premature replacement (€1,200+) per 8 devices, which is well below typical failure rates.

Wrapping up

Laptop battery monitoring isn't glamorous, but it's one of the highest-ROI moves a remote-first IT team can make in 2026. Pick your metrics, automate collection, set thresholds, and move on.

If you want a tool that handles cross-platform fleets out of the box, Sobrii gives you battery, hardware, software and energy telemetry from a single agent — without the MDM overhead.

What metrics does your team track today? Drop a comment.

How to Preview Markdown Files Directly in macOS Finder

Arthur — Tue, 17 Mar 2026 20:39:44 +0000

You know that thing where you press Space on a file in Finder and get an instant preview?

It works for images. PDFs. Videos. Even 3D models.

But try it on a .md file. Nothing useful. Just raw text in a monospace font.

Here's how to fix that — and turn your Finder into a proper Markdown previewer.

What QuickLook actually is

For those unfamiliar: QuickLook is a macOS feature that renders a file preview when you press the spacebar in Finder. No app launches. No window management. Just instant preview.

Developers use it constantly without thinking about it. You select a .png and press Space to check the right asset. You select a .pdf to skim a doc without opening Preview. It's muscle memory.

The problem is that macOS ships with no QuickLook support for Markdown. Press Space on README.md and you get the same experience as opening it in TextEdit — raw syntax, no rendering.

Which is wild, because Markdown is arguably the most common documentation format in software development.

The setup (takes 2 minutes)

You need a QuickLook extension that understands Markdown. There are a few options:

QLMarkdown — Free, open-source, available on GitHub. Solid for basic Markdown rendering. No Mermaid support.

MacMD Viewer — $19.99 on https://macmdviewer.com/from/devto. Full viewer app that includes a QuickLook extension. Handles Mermaid diagrams, syntax highlighting, and dark mode in the preview. This is what we built and what I'll demo below.

Install either one. No config needed. macOS picks up the extension automatically.

The workflow that changes everything

Once installed, here's what your daily workflow looks like:

Triaging repos

You clone a repo. Before opening anything in your editor:

~/projects/new-repo/
├── README.md          ← select, press Space
├── CONTRIBUTING.md    ← arrow down, preview updates
├── docs/
│   ├── setup.md       ← arrow down again
│   └── api.md         ← you've scanned 4 docs in 10 seconds
├── src/
└── package.json

You just read four documentation files without launching a single app. Arrow keys move between files. The preview updates in real-time.

Compare that to: open VS Code → wait 3 seconds → navigate to file → Cmd+Shift+V for preview → repeat for each file. For reading documentation, QuickLook is 10x faster.

Reviewing PRs locally

Someone sends you a branch with updated docs. You check it out, navigate to the changed .md files in Finder, press Space. Instantly see how the rendered output looks. No need to push to GitHub just to preview the formatting.

Checking Mermaid diagrams

This is where it gets interesting. If your QuickLook extension supports Mermaid, you can preview architecture diagrams without leaving Finder.

Imagine your doc contains a flowchart: Client → API Gateway → Auth Service → Database. In raw Markdown, that's just text. With the right QuickLook extension, press Space and you see the actual rendered diagram — boxes, arrows, layout.

No browser, no Mermaid Live Editor, no copy-pasting syntax into a web tool.

For teams that document architecture in Markdown (and in 2026, most teams do), this is a massive time saver.

Live editing preview

If your QuickLook extension supports live reload (MacMD Viewer does), you can keep the preview open while editing the file in your favorite editor. Every save updates the preview instantly.

Split your screen: editor on the left, Finder QuickLook preview on the right. Poor man's live preview that works with any text editor — Vim, Neovim, Sublime, whatever.

Pro tips

Set your default app. Right-click any .md file → Get Info → Open With → choose your Markdown viewer → "Change All." Now double-clicking opens the rendered view, not TextEdit.

Spotlight works too. Open Spotlight (Cmd+Space), type a filename, arrow down to the .md file. The preview panel on the right renders it. You just searched and previewed a Markdown file without touching Finder.

Open/Save dialogs. Any time macOS shows a file picker (Cmd+O in any app), you can press Space to QuickLook preview files. Works with the Markdown extension installed. Handy when you're looking for the right doc in a cluttered project.

The before and after

Before:

See .md file in Finder
Double-click → TextEdit opens → raw text
Close TextEdit
Open VS Code
Wait for it to load
Open file, switch to preview
Read the doc
Close VS Code

After:

See .md file in Finder
Press Space
Read the doc

Eight steps down to two. That's not an optimization. That's a different workflow entirely.

The bigger picture

Markdown isn't going away. If anything, AI tools are generating more of it than ever. Every Cursor session, every Copilot suggestion, every v0 scaffold comes with .md files.

Your operating system should be able to read them natively. macOS can't — yet. But with the right QuickLook extension, it takes two minutes to fix what Apple hasn't fixed in 25 years of macOS development.

Try it. Select a .md file. Press Space. You'll wonder how you ever lived without it.

I've been using MacMD Viewer for this — it's a native macOS app with a QuickLook extension that handles Mermaid and syntax highlighting. $19.99 once. QLMarkdown is a solid free alternative if you just need basic rendering. Either way, get QuickLook working for Markdown. Your future self will thank you.