DEV Community: Recca Tsai

Does a Long Claude Code Session Waste Tokens? A Cost Model Most People Get Wrong

Recca Tsai — Mon, 13 Apr 2026 11:06:30 +0000

Originally published at recca0120.github.io

A common intuition among developers: Claude Code sessions get expensive over time. Context keeps accumulating, every turn resends the entire history, and token costs add up linearly. The obvious conclusion: /clear often, start fresh sessions for each task to save money.

That reasoning is half right and half wrong. The wrong half comes from leaving prompt caching out of the cost model. In practice, frequent /clear can cost more than keeping a long session alive.

Cumulative Context Really Does Cost

Start with what's true. LLM APIs are stateless — every API call must resend the entire conversation history. After 10 turns with Claude, the 11th request contains all 10 previous turns plus your new question.

So yes, the input token count per call grows linearly as the session gets longer. It's reasonable to conclude "longer sessions cost more."

But Prompt Caching Changes the Rules

Anthropic introduced prompt caching in 2024, and Claude Code enables it by default. The rule is simple: identical prefixes only cost 10% of the normal price.

Sonnet 4.6 pricing:

Type	Price (per million tokens)	Relative
Base input (uncached)	$3.00	100%
5-minute cache write	$3.75	125%
1-hour cache write	$6.00	200%
Cache read	$0.30	10%

Opus is even more dramatic: base input $5, cache read only $0.50.

Meaning: the first time you send a large context block, it gets written to the cache and you pay a small write premium (25% above base). For the next 5 minutes, resending the same prefix costs 10% of base. The longer the session and the more cache hits accumulate, the lower your average per-token cost.

The Three Variables That Actually Drive Cost

So the cost model isn't "context size × number of turns." It's these three factors:

1. Cache Hit Rate

In a long, continuous session, every turn's prefix hits the cache written by the previous turn. If a session has accumulated 50K tokens and turn 11 adds 2K new input:

Without cache: 51K × $3 = $0.153
With cache: 50K × $0.30 + 2K × $3 = $0.021

About a 7x difference.

What's worst about aggressive /clear: every new session re-reads CLAUDE.md, re-learns your project files, re-warms the cache. These warm-up costs can easily exceed the "savings" from keeping context small.

2. Cache Invalidation

Cache requires 100% identical prefixes to hit. These actions invalidate the whole cache:

Editing any historical message
Changing tool schemas (adding/removing MCP tools)
Switching models (Sonnet ↔ Opus)
Toggling web search or citations

Claude Code's auto-compact is also a cache-destruction event. The moment it squashes your 200K context into a summary, the accumulated cache is gone, and the next turn has to warm from scratch.

3. TTL (5 Minutes vs 1 Hour)

Default cache TTL is 5 minutes. Pause for more than 5 minutes and the cache expires — the next call pays full base input price.

Anthropic offers a 1-hour TTL option at 2x write cost ($6 vs $3) in exchange for longer persistence. Whether it's worth it depends on rhythm — bursty work with 10–30 minute gaps may benefit; continuous work never hits the timeout anyway.

Counterintuitive: When Long Sessions Are Cheapest

Combine all three and you arrive at the opposite of "longer = more expensive":

Long sessions are cheapest when:

Work is continuous, turns within 5 minutes of each other
No editing of history, no model switches, no MCP churn
Context stays below the compaction threshold (~155K safe zone)

Short sessions / frequent clearing are costliest when:

Every new session re-reads large context (CLAUDE.md, multiple files, skill definitions)
Every new session pays a "cache warm-up tax"
You never reap the 10% cache-read discount

My own experience: two hours of continuous work in one session often costs less than splitting the same work into four independent 30-minute sessions — because the latter pays four cold starts.

When Large Context Is Genuinely a Problem

None of this means context can grow forever with no consequence. Two thresholds turn "large context" from a cost problem into a quality problem:

1. Approaching the context window limit (Sonnet 200K / 1M, Opus 200K)

Model attention degrades past ~100K tokens, especially on content in the middle (the "lost in the middle" phenomenon). At this point the concern isn't cost — it's that the model can't find or misuses what you gave it earlier.

2. Auto-compact triggers

Claude Code auto-compacts as you approach the limit. Compaction is a major operation — cache fully invalidates, cost spikes, and the result is a summary with possible detail loss.

So context shouldn't grow unbounded, but the right reset trigger is "task complete" or "about to hit compaction," not "session has been open for X hours."

Practical Recommendations

Situation	Recommendation
Mid-task	Don't `/clear`, continue the session
Task done, starting a new one	`/clear` so the next session starts clean
Idle for >5 minutes	Use `/resume` instead of opening a new session (TTL expires but history is preserved)
Claude Code open often with idle gaps	Consider 1h TTL — 2x write cost but idle safety
Context exceeds 155K	Proactively end the session; don't wait for auto-compact

To measure your actual cost, try ccusage or claude-view. A high share of cache_read_input_tokens means you're working efficiently; rising cache_creation_input_tokens with low reads means cache keeps invalidating — you're burning money.

"Longer sessions waste more tokens" is a stateless-era intuition, but prompt caching has been rewriting those rules for two years. Check how you actually use Claude Code — the token savings might surprise you.

References

chezmoi: One Dotfiles Repo Across macOS, Linux, and Windows

Recca Tsai — Mon, 13 Apr 2026 10:41:33 +0000

Originally published at recca0120.github.io

My work machine is a MacBook, my home desktop runs Linux, and the company handed me a Windows NUC. All three need synced .gitconfig, .zshrc, .tmux.conf — but each OS has quirks. Windows needs sslCAInfo pointing at scoop's git cert bundle; macOS uses Homebrew; Linux uses apt.

I used to hack it with symlinks and shell scripts. Now I use chezmoi. One dotfiles repo, three machines, one-line setup.

Why Not stow, yadm, or dotbot

Plenty of dotfiles managers exist. chezmoi wins on three fronts:

Go templates: the same file renders differently per OS, no need to maintain three .gitconfig variants
Native encryption: age and gpg are first-class, so secrets can live in a public repo
onchange scripts: the Homebrew bootstrap only re-runs when the package list actually changes

stow is pure symlinks, no templating. yadm wraps git, templating via plugins. dotbot needs a YAML manifest. chezmoi bundles it all into one binary.

Install and Init

# macOS
brew install chezmoi

# Linux
sh -c "$(curl -fsLS get.chezmoi.io)"

# Windows
winget install twpayne.chezmoi

Bootstrap a new machine from an existing repo:

chezmoi init --apply https://github.com/YOUR_USERNAME/dotfiles.git

That single line clones the repo, runs the template engine, and writes everything to $HOME.

Filename Attribute System

chezmoi uses filename prefixes to encode behavior. The repo layout itself is the manifest — no separate config needed.

Prefix	Effect	Example
`dot_`	Target is a hidden file	`dot_zshrc` → `~/.zshrc`
`private_`	User-only permissions (0600)	`private_dot_ssh` → `~/.ssh`
`executable_`	Sets executable bit	`executable_bin_foo`
`encrypted_`	age/gpg encrypted	`encrypted_dot_env`
`symlink_`	Creates a symlink	`symlink_dot_bashrc`
`readonly_`	Strips write permissions	`readonly_dot_config.toml`
`.tmpl` suffix	Run through template engine	`dot_gitconfig.tmpl`

Prefixes stack. My repo has combinations like:

private_executable_dot_php-cs-fixer.dist.php  → ~/.php-cs-fixer.dist.php (0700)
private_dot_ssh/                              → ~/.ssh (whole dir at 0700)

Templates for Machine Differences

This is chezmoi's killer feature. My dot_gitconfig.tmpl:

[user]
    name = {{ .name | quote }}
    email = {{ .email | quote }}

[http]
    sslBackend = openssl
{{ if eq .chezmoi.os "windows" -}}
    sslCAInfo = {{- .chezmoi.homeDir | replace "\\" "/" -}}/scoop/apps/git/current/mingw64/ssl/certs/ca-bundle.crt
{{ end }}

[core]
    autocrlf = false
    symlinks = true

.name and .email come from ~/.config/chezmoi/chezmoi.toml, so each machine can have its own values. The {{ if eq .chezmoi.os "windows" }} block only expands on Windows. On apply, chezmoi strips the .tmpl and writes a clean .gitconfig.

Built-in variables I reach for constantly:

{{ .chezmoi.os }}              # "darwin" / "linux" / "windows"
{{ .chezmoi.arch }}            # "amd64" / "arm64"
{{ .chezmoi.hostname }}        # machine name
{{ .chezmoi.username }}        # login user
{{ .chezmoi.homeDir }}         # home directory

Preview a template without applying:

chezmoi execute-template < dot_gitconfig.tmpl

Age Encryption for Secrets

My repo is public, but it contains an SSH key and database password backups. Those are encrypted with age before they ever hit a commit.

Generate an age key:

age-keygen -o ~/key.txt
# Public key: age1s5xur7evyf9y9un4yt8cwqrqw9vd0k8m67kkl655gy9nmnfrgplsxef583

Configure ~/.config/chezmoi/chezmoi.toml:

encryption = "age"

[age]
    identity = "~/key.txt"
    recipient = "age1s5xur7evyf9y9un4yt8cwqrqw9vd0k8m67kkl655gy9nmnfrgplsxef583"

Add files with --encrypt:

chezmoi add --encrypt ~/.ssh/id_ed25519

The repo only ever stores private_dot_ssh/encrypted_private_id_ed25519.age — opaque ciphertext. On apply, chezmoi decrypts using ~/key.txt and writes the plaintext to the target.

The one catastrophic footgun: key.txt itself must never land in the repo. My workflow: GPG-encrypt it and stash it in a password manager. New machines must restore key.txt manually before running chezmoi init --apply.

run_onchange: Reinstall Only When Lists Change

My .chezmoiscripts/darwin/run_onchange_00_install-packages.sh.tmpl:

{{ if eq .chezmoi.os "darwin" -}}
#!/bin/bash

brew install mas
brew install asdf

asdf plugin add nodejs
asdf install nodejs latest
asdf set nodejs latest

# ... many more asdf installs
{{ end -}}

The run_onchange_ prefix is the key: chezmoi only runs this script when its content hash changes. Unchanged package list means no re-run — no more five-minute brew install cycles through already-installed tools on every chezmoi apply.

Script naming variants:

Prefix	When It Runs
`run_once_`	Once per machine, ever, for given content
`run_onchange_`	Whenever the contents change
`run_onchange_before_`	Before file application (install package manager first)
`run_onchange_after_`	After file application (enable fish plugins last)

The numeric prefix (00_, 01_, 02_) controls execution order.

.chezmoiroot: Source Lives in a Subdirectory

All my files live under home/:

dotfiles/
├── .chezmoiroot        # contains just "home"
├── Readme.md
├── install.sh
├── install.ps1
└── home/
    ├── dot_zshrc.tmpl
    ├── dot_gitconfig.tmpl
    └── .chezmoiscripts/

.chezmoiroot tells chezmoi "source files are under home/". Now the repo root can host a README, install scripts, and other project artifacts without chezmoi trying to apply them as dotfiles.

Great for treating your dotfiles repo like a normal project.

.chezmoiignore: Skip Certain Files

Same syntax as .gitignore, but it supports templates:

README.md
LICENSE
{{ if ne .chezmoi.os "darwin" }}
.aerospace.toml
Library/
{{ end }}

Non-macOS machines skip the aerospace window manager config and the Library folder.

Command Cheat Sheet

chezmoi add ~/.vimrc              # track an existing file
chezmoi add --encrypt ~/.env      # track encrypted
chezmoi edit ~/.zshrc             # edit the source file directly
chezmoi diff                      # show pending changes
chezmoi apply                     # write to $HOME
chezmoi apply --dry-run -v        # preview without writing
chezmoi cd                        # jump to source directory
chezmoi update                    # git pull + apply
chezmoi doctor                    # check environment health

chezmoi doctor reports the status of encryption tools, template engine, git, and friends. First thing to run when a new machine misbehaves.

Combined with zoxide, fish, and More

My fish config, zoxide init, tmux plugins — all managed by chezmoi. New machine ritual:

Restore the age key
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply recca0120
run_onchange scripts install CLI tools via brew / apt / scoop
All configs land in place
Open fish — zoxide, starship, fzf are already wired up

About 20 minutes end to end, most of it waiting on brew install downloads.

Downsides and Gotchas

chezmoi isn't free of friction:

Template learning curve: Go template syntax isn't beginner-friendly. Whitespace handling with {{- }} vs. {{ }} takes practice
Painful debugging: template expansion errors are terse — I lean on chezmoi execute-template to isolate problems
Age key stewardship: lose the key, lose every encrypted file forever. Back it up separately (I GPG-encrypt and park it in a password manager)
First apply is destructive: if $HOME already has hand-edited dotfiles, apply overwrites them. Always chezmoi diff first

References

zoxide: Give cd a Memory — Jump to Any Directory in Two Keystrokes

Recca Tsai — Mon, 13 Apr 2026 07:10:46 +0000

Originally published at recca0120.github.io

My projects are scattered across ~/Sites, ~/WebstormProjects, ~/GolandProjects, ~/PycharmProjects — long paths, no single root. For years I either mashed cd ~/Sites/recca012<TAB> or dragged folders from Finder into the terminal. Then I installed zoxide. Now cd recca gets me there.

The trick is that my cd is no longer a shell builtin. It's zoxide's replacement — same behavior as the original, plus memory.

What frecency Means

zoxide's algorithm is called frecency (frequency + recency). Every directory you visit earns a score that climbs with use and decays over time. Type cd foo and zoxide searches its database for paths containing foo, then jumps to the highest-scoring one.

Here's a slice of my own database:

$ zoxide query --score | head -5
 230.0 /Users/recca0120/WebstormProjects
 215.3 /Users/recca0120/Sites
 198.7 /Users/recca0120/Sites/recca0120.github.io
 142.1 /Users/recca0120/Desktop/vscode-phpunit
  98.5 /Users/recca0120/Downloads

Frequently visited projects float to the top; stale ones sink. Data lives in a local file — fully offline, no network calls.

Install and Init

macOS via Homebrew:

brew install zoxide

Linux one-liner:

curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

Then initialize in your shell config. The key decision is whether to use --cmd cd:

Mode	Command	Effect
Default	`zoxide init <shell>`	Adds `z`, `zi` commands. Builtin `cd` untouched
Replace cd	`zoxide init --cmd cd <shell>`	Replaces `cd` outright

I went with the latter. I use fish shell, so my config reads:

# ~/.config/fish/config.fish
zoxide init --cmd cd fish | source

For zsh / bash, use eval:

# ~/.zshrc
eval "$(zoxide init --cmd cd zsh)"

Why replace cd wholesale? Because zoxide's cd is a superset of the builtin: absolute paths, relative paths, cd -, cd .. all still work. Frecency lookup only kicks in when the argument isn't a valid path. No regression risk.

Three Daily Workflows

1. Keyword jumps. Skip full paths — just type a fragment of the directory name:

cd github          # → ~/Sites/recca0120.github.io
cd webstorm        # → ~/WebstormProjects
cd phpunit         # → ~/Desktop/vscode-phpunit

2. Multi-keyword filtering. When names collide, chain keywords to narrow down:

cd sites blog      # → ~/Sites/scu_blog
cd projects cc     # → ~/WebstormProjects/cc-office

Match rule: every keyword must appear in the path, and the last one must be in the final segment.

3. Interactive selection via zi. When you can't recall the keyword or have multiple candidates:

cdi               # since I used --cmd cd, zi becomes cdi

This opens an fzf UI listing all candidates with live fuzzy filtering. Install fzf first if you haven't: brew install fzf.

Advanced Tricks

Space-triggered completion. In fish, typing cd mydir<SPACE> lists multiple candidates — handy when directories share names. Fish users can also install an enhanced completion pack:

fisher install icezyclon/zoxide.fish

Query without jumping. Preview where zoxide would take you, without actually going:

zoxide query github
# → /Users/recca0120/Sites/recca0120.github.io

zoxide query --list github    # list all matches
zoxide query --score          # view frecency scores

Manually register a directory. For a freshly cloned project you haven't visited yet:

zoxide add ~/projects/new-repo

Exclude noise. /tmp, node_modules, and friends clutter the database:

set -gx _ZO_EXCLUDE_DIRS "/tmp/*" "*/node_modules/*" "$HOME/.cache/*"

Echo destination before jumping. Helps catch wrong jumps:

set -gx _ZO_ECHO 1

Migrate from older tools. autojump, fasd, z.lua all have import paths:

zoxide import --from=autojump ~/.local/share/autojump/autojump.txt
zoxide import --from=z ~/.z

Combining with yazi and tmux

My .zshrc has a function y that syncs yazi's final directory back to the shell on exit:

function y
    set tmp (mktemp -t "yazi-cwd.XXXXXX")
    yazi $argv --cwd-file="$tmp"
    set cwd (cat -- "$tmp")
    if [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]
        cd -- "$cwd"  # this cd is zoxide
    end
    rm -f -- "$tmp"
end

The trailing cd is zoxide's version, so directories I browse through yazi also feed into the frecency database. The two tools cross-pollinate — both get smarter with use.

In tmux, each pane is its own shell, but zoxide's database is shared globally. Visit a directory in pane A and pane B can jump there with cd foo.

When Not to Use --cmd cd

Honestly, --cmd cd isn't uncontroversial. Arguments against overriding the builtin:

Shell scripts might accidentally inherit zoxide behavior
Shared terminals could confuse other users
Certain cd edge cases (like CDPATH) may behave differently

zoxide's implementation only overrides cd in interactive shells, so the first concern is mostly academic. But if you value purity, sticking with the default z / zi gets you 95% of the benefit — you just have to pause each time to pick cd vs. z.

Personally, I prefer --cmd cd. Muscle memory doesn't want to change, so the tool should adapt to the human, not the other way around.

References

MemPalace: 170 Tokens to Recall Everything — A Long-Term Memory System for AI Agents

Recca Tsai — Tue, 07 Apr 2026 17:44:15 +0000

Originally published at recca0120.github.io

Six months of daily AI conversations. 19.5 million tokens of history. Start a new session and it remembers nothing. You can dump important things into CLAUDE.md, but that file quickly balloons to thousands of lines, eating up your context window on every startup.

MemPalace takes a different approach: instead of cramming all memories into the prompt, build a structured memory vault that AI queries on demand. Startup loads just 170 tokens, search accuracy hits 96.6%, completely offline, zero API calls.

The Memory Palace Architecture

MemPalace uses the ancient Greek memory technique as its organizational metaphor:

Wing: Projects, people, or topics. One wing per major category
Room: Sub-topics within a wing — auth, billing, deploy
Hall: Memory type corridors shared across all wings
- hall_facts — locked-in decisions
- hall_events — sessions and milestones
- hall_discoveries — breakthroughs
- hall_preferences — habits and opinions
- hall_advice — recommendations
Closet: Compressed summaries pointing to original content
Drawer: Verbatim original files, preserved losslessly
Tunnel: Cross-wing connections when the same room appears in multiple wings

The structure alone improves search accuracy. Benchmark results:

Search Scope	R@10	Improvement
All closets	60.9%	—
Within wing	73.1%	+12%
Wing + hall	84.8%	+24%
Wing + room	94.8%	+34%

Structure alone delivers a 34% accuracy boost — no fancy algorithms needed.

AAAK Compression Format

This is MemPalace's most interesting design. AAAK is an AI-readable shorthand achieving 30x compression.

Original (~1,000 tokens):

Priya manages Driftwood team: Kai (backend, 3 years), Soren (frontend),
Maya (infrastructure), Leo (junior, started last month). Building SaaS
analytics platform. Current sprint: auth migration to Clerk. Kai
recommended Clerk over Auth0 based on pricing and DX.

AAAK format (~120 tokens):

TEAM: PRI(lead) | KAI(backend,3yr) SOR(frontend) MAY(infra) LEO(junior,new)
PROJ: DRIFTWOOD(saas.analytics) | SPRINT: auth.migration→clerk
DECISION: KAI.rec:clerk>auth0(pricing+dx) | ★★★★

The key point: no decoder required. Any LLM reads it natively — Claude, GPT, Llama, Mistral. It's essentially structured English abbreviations, not binary encoding.

Layered Memory Loading

MemPalace divides memory into four layers, loaded incrementally:

Layer	Content	Size	When Loaded
L0	Identity — who is this AI	~50 tokens	Always
L1	Critical facts — team, projects, preferences	~120 tokens (AAAK)	Always
L2	Room recall — recent sessions	On demand	When topic surfaces
L3	Deep search — semantic across all closets	On demand	When explicitly asked

Startup loads only L0 + L1, about 170 tokens total. Compared to alternatives:

Approach	Tokens Loaded	Annual Cost
Paste everything	19.5M — impossible	Impossible
LLM summaries	~650K	~$507
MemPalace wake-up	~170	~$0.70
MemPalace + 5 searches	~13,500	~$10

Knowledge Graph: Facts Have Expiry Dates

MemPalace includes a temporal knowledge graph stored in local SQLite:

kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")

# Kai leaves the Orion project
kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")

# Query current state
kg.query_entity("Kai")
# → [Kai → works_on → Orion (ended), Kai → recommended → Clerk]

# Historical queries
kg.query_entity("Maya", as_of="2026-01-20")
# → [Maya → assigned_to → auth-migration (active)]

Every fact has a validity window. Invalidation marks end dates without deletion. This solves the most common CLAUDE.md problem: stale information that nobody cleans up, causing the AI to act on outdated data.

The knowledge graph also detects contradictions — tasks assigned to the wrong person, tenure mismatches, outdated sprint end dates.

Claude Code Integration

MCP Server

claude mcp add mempalace -- python -m mempalace.mcp_server

Once installed, Claude Code auto-discovers 19 MCP tools covering search, storage, knowledge graph queries, and agent diaries.

Auto-Save Hooks

Add two hooks to your Claude Code configuration:

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{"type": "command",
        "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"}]
    }],
    "PreCompact": [{
      "matcher": "",
      "hooks": [{"type": "command",
        "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"}]
    }]
  }
}

Save hook: Fires every 15 messages, auto-extracts topics, decisions, and code changes
PreCompact hook: Fires before context compression, emergency-saving current memory

No need to manually tell the AI to remember things — it saves automatically.

I previously covered claude-view, which monitors Claude Code sessions and costs from the outside. MemPalace extends AI's memory from the inside. They're complementary — claude-view shows you what AI did, MemPalace helps AI remember what it did.

Specialist Agents

Create focused agents with independent memory:

~/.mempalace/agents/
 ├── reviewer.json    # code review patterns, bug records
 ├── architect.json   # design decisions, trade-offs
 └── ops.json         # deploys, incidents, infrastructure

Each agent maintains its own wing and AAAK diary, accumulating domain expertise across sessions:

# Agent writes findings
mempalace_diary_write("reviewer",
  "PR#42|auth.bypass.found|missing.middleware.check|pattern:3rd.quarter|★★★★")

# Agent reads history
mempalace_diary_read("reviewer", last_n=10)

No need to stuff agent descriptions into CLAUDE.md. One line suffices: "You have MemPalace agents. Run mempalace_list_agents to see them."

Installation and Usage

pip install mempalace

# Initialize
mempalace init ~/projects/myapp

# Mine different sources
mempalace mine ~/projects/myapp              # project code
mempalace mine ~/chats/ --mode convos        # conversation history
mempalace mine ~/chats/ --mode convos --extract general  # classified import

# Search
mempalace search "why did we switch to GraphQL"

# Generate startup context
mempalace wake-up > context.txt

Supports importing Claude conversations, ChatGPT exports, and Slack exports. Large files can be split first:

mempalace split ~/chats/ --dry-run   # preview
mempalace split ~/chats/             # split into individual sessions

Compared to CLAUDE.md

CLAUDE.md is a flat text file — all information mixed together, no temporal awareness, fully loaded on every startup. MemPalace is a structured memory vault with layered loading, temporal knowledge graphs, and semantic search.

That said, MemPalace isn't perfect. It requires a Python environment, MCP server setup, and hook configuration. If you only need to remember a few coding conventions, CLAUDE.md is sufficient. MemPalace's value shows in long-term, large-scale, cross-project memory management.

References

NodeWarden: Bitwarden on Cloudflare Workers — No Server Required

Recca Tsai — Tue, 07 Apr 2026 09:36:33 +0000

Originally published at recca0120.github.io

Self-hosting Bitwarden gives you two paths. The official version requires Docker and eats memory. Vaultwarden rewrites it in Rust, much lighter, but you still need a VPS, HTTPS configuration, regular updates, and database backups.

NodeWarden takes a third path: run directly on Cloudflare Workers. No VPS, no SSL management, no uptime monitoring. Cloudflare's free tier is enough.

How It Differs from Vaultwarden

Vaultwarden is the most popular third-party Bitwarden server, written in Rust, running in Docker. NodeWarden is written in TypeScript, running on Cloudflare Workers.

	Vaultwarden	NodeWarden
Language	Rust	TypeScript
Deployment	Docker / VPS	Cloudflare Workers
Database	SQLite / MySQL / PostgreSQL	Cloudflare D1
Attachment storage	Local filesystem	R2 or KV
SSL	Self-configured	Cloudflare handles it
Maintenance	Manual updates and backups	Fork + auto-sync upstream
Cost	VPS monthly fee	Cloudflare free tier
Organizations/Collections	Supported	Not supported

The biggest difference is operational burden. Vaultwarden needs you to maintain a VPS. NodeWarden is fully serverless. The downside is no organization or collection features, making it unsuitable for teams.

Technical Architecture

NodeWarden is built entirely on Cloudflare's infrastructure:

Compute: Cloudflare Workers (serverless)
Database: D1 (Cloudflare's SQLite)
Attachment storage: R2 (object storage) or KV (key-value)
Frontend: Preact (original Web Vault interface)

Two storage options:

Option	Credit card required	Max attachment size	Free quota
R2	Yes	100 MB (adjustable)	10 GB
KV	No	25 MiB (hard limit)	1 GB

If you don't want to add a credit card, use KV mode. 1 GB free quota is more than enough for personal password management. Only consider R2 if you need large attachments.

Feature Comparison

Compared to official Bitwarden, everything needed for personal use is covered:

Web Vault password manager interface
Full sync (/api/sync), compatible with official clients
Attachment upload and download
Send feature (text and files)
Import/export (Bitwarden JSON/CSV, ZIP with attachments)
TOTP and Steam TOTP
Multi-user (invitation code registration)
Password hints (viewable directly in web, no email required)

NodeWarden adds one feature the official version lacks: a cloud backup center. Supports WebDAV and E3 protocol for scheduled backups, including db.json, manifest.json, and attachments/ directory. During restoration, missing attachments are safely skipped without leaving broken records.

Not supported: organizations, collections, permission management, SSO, SCIM, enterprise directories. These are team features unnecessary for personal use.

Client Compatibility

Tested and working:

Windows desktop
Mobile apps (iOS / Android)
Browser extensions
Linux desktop
macOS desktop (not fully verified)

Deployment

Web Deployment (Recommended)

The simplest approach, no local tools needed:

Fork the NodeWarden repo
Go to the Cloudflare Workers console and create a new project
Choose Continue with GitHub, point to your forked repo
Keep default settings and deploy
For KV mode, change the deploy command to npm run deploy:kv
Set the JWT_SECRET environment variable (at least 32 random characters)

The whole process takes under five minutes.

CLI Deployment

git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden
npm install
npx wrangler login

# R2 mode
npm run deploy

# KV mode
npm run deploy:kv

Local development:

npm run dev      # R2 mode
npm run dev:kv   # KV mode

Automatic Updates

After forking, enable the Sync upstream workflow in GitHub Actions. It auto-syncs with upstream daily at 3am. For manual updates, click Sync fork → Update branch on your fork page.

NodeWarden or Vaultwarden

If you already have a stable VPS, Vaultwarden is more feature-complete with a larger community. Organizations, collections, and login 2FA are all supported.

NodeWarden fits these scenarios:

No VPS management. No server means no maintenance — no uptime worries, no expired SSL certs, no full disks
Zero budget. Cloudflare's free tier is plenty for personal use
Solo user. No need for organizations and permission management
Offsite backups. Built-in WebDAV backup is more convenient than Vaultwarden's approach

The main risk is that your password vault runs on Cloudflare's infrastructure. D1 and Workers are relatively new services. While Cloudflare probably won't shut them down suddenly, free tier limits and terms can change anytime. Regular WebDAV backups are essential.

Also note that NodeWarden hasn't undergone the same level of community security review as Vaultwarden. Password managers are high-sensitivity applications — assess the risk yourself before using it.

References

claude-view: Mission Control for Claude Code — Live Session Monitoring, Cost Tracking, and Analytics

Recca Tsai — Tue, 07 Apr 2026 09:32:23 +0000

Originally published at recca0120.github.io

After using Claude Code for a while, the most common question I get is "how much are you spending per month?" Honestly, I can't answer that. Claude Code's terminal interface doesn't show cumulative token costs, how many sub-agents ran, or which session burned the most money.

claude-view fills that gap. One command opens a dashboard that monitors every Claude Code session on your machine in real-time.

npx claude-view

What It Shows You

Live Session Monitoring

Open the dashboard and you see all running Claude Code sessions, each card showing:

Last message
Model in use (Opus, Sonnet, Haiku)
Current cost and token count
Context window utilization (live percentage)
Prompt cache countdown timer

Cards can be arranged in multiple layouts: Grid, List, Kanban, Monitor. Kanban mode groups sessions by project/branch in swimlanes — great when running multiple projects simultaneously.

Conversation Browser

Click into any session for the full conversation history. Unlike the terminal view, claude-view visualizes tool calls — file reads, edits, bash commands, and MCP calls each get their own cards.

A Developer Mode toggle reveals hook metadata, event cards, and raw JSON. Invaluable for debugging.

Conversations can be exported as Markdown for documentation or feeding back to Claude for continuation.

Sub-agent Tree View

Claude Code spawns sub-agents for subtasks. In the terminal you only see one level. claude-view renders the full tree structure with per-agent cost and token breakdowns at a glance.

Full-Text Search

The search engine is Tantivy, a Rust-native Lucene-class full-text indexer. Search response times across 1,500 sessions stay under 50ms.

Cmd+K opens a command palette for quick session jumping and view switching.

Analytics: Where Did the Money Go

This is where I see the most value.

Dashboard Metrics

Week-over-week session count, token usage, and cost comparison
90-day GitHub-style activity heatmap
Most-used skills, commands, and MCP tools leaderboards
Most active projects bar chart
Cross-session totals for edits, reads, and bash commands

AI Contributions Tracking

This feature quantifies Claude Code's output:

Lines added/removed, files touched, commit counts
Cost per commit, cost per session, cost per line ROI
Opus vs Sonnet vs Haiku side-by-side comparison
Re-edit rate: tracking whether your prompt quality is improving

There's also an experimental AI Fluency Score (0-100), calculated from your session history to measure how effectively you use AI.

85 MCP Tools

claude-view ships a plugin (@claude-view/plugin) that auto-loads with every Claude Code session.

claude plugin add @claude-view/plugin

The plugin provides 85 MCP tools: 8 hand-crafted core tools plus 77 auto-generated from the OpenAPI spec.

The core 8:

list_sessions, get_session, search_sessions
get_stats, get_fluency_score, get_token_stats
list_live_sessions, get_live_summary

Once installed, you can ask Claude Code "how much did I spend today" or "which session took the longest last week" — it queries claude-view via MCP.

9 Built-in Skills

Beyond MCP tools, there are 9 built-in skills:

Skill	Purpose
`/session-recap`	Summarize commits, metrics, duration
`/daily-cost`	Today's spending and tokens
`/standup`	Multi-session work log
`/coaching`	AI usage tips
`/insights`	Behavioral pattern analysis
`/project-overview`	Cross-session project summary
`/search`	Natural language search
`/export-data`	CSV/JSON exports
`/team-status`	Team activity overview

Technical Architecture

claude-view uses Rust for the backend and React for the frontend.

Layer	Technology
Web framework	Axum
Database	SQLite
Search engine	Tantivy
File I/O	Memory-mapped I/O
Real-time	SSE + WebSocket
Frontend	React + Vite + Dockview
Monorepo	Turbo + Bun

Performance benchmarks (M-series Mac, 1,493 sessions):

Metric	claude-view	Typical Electron Dashboard
Download	~10 MB	150-300 MB
On disk	~27 MB	300-500 MB
Startup	<500 ms	3-8 s
RAM	~50 MB	300-800 MB
Index 1,500 sessions	<1 s	N/A

Rust's mmap + SIMD-accelerated JSONL parsing enables zero-copy from parse to response. Compared to Electron dashboards, it's 10x smaller and uses 6x less memory.

Installation

Three options:

# Recommended
curl -fsSL https://get.claudeview.ai/install.sh | sh

# Or via npx
npx claude-view

# Install plugin (auto-starts with Claude Code)
claude plugin add @claude-view/plugin

Only prerequisite: Claude Code installed. Dashboard runs at http://localhost:47892.

All data stays local, zero telemetry, no account required.

Compared to Other Tools

There are similar tools, but with different positioning:

ccusage: CLI tool, token stats only, no GUI, no live monitoring
opcode: Tauri-based GUI with session management but no multi-session chat browsing or search
CodePilot: Electron chat UI for interacting with Claude Code, not monitoring it

claude-view is positioned as monitoring and analytics. If you already work in the terminal with Claude Code, it doesn't change your workflow — it just shows you more information.

I previously covered AionUi, which unifies multiple agents into one GUI. claude-view takes a different approach: keep working in the terminal, but add a dashboard for tracking. The two can work together.

Who Needs This

If you use Claude Code occasionally, you probably don't need this tool.

But if you use it daily, run multiple sessions simultaneously, and want to know where the money goes, which model gives the best ROI, and whether your prompt quality is improving — claude-view provides information density that the terminal simply can't match.

References

bb-browser: No Scraping, No API Keys — Your Browser Is the API

Recca Tsai — Tue, 07 Apr 2026 03:37:23 +0000

Originally published at recca0120.github.io

Want Twitter search results? Traditional approaches give you three paths: apply for an API key (rate-limited), write a scraper (get IP-banned), or use Playwright with a headless browser (detected as non-human).

bb-browser takes a fourth path: use the Chrome you already have open. You're logged into Twitter, the cookies are right there, and bb-browser runs fetch() inside that tab. From the website's perspective, it's just you browsing.

How It Differs from Scrapers and Playwright

Let's get the differences clear.

	bb-browser	Playwright / Selenium	Scrapers (requests, Scrapy)
Browser	Your real Chrome	Isolated headless browser	No browser
Login state	Already logged in	Must re-login or inject cookies	Manual cookie handling
Anti-bot detection	Invisible (it IS the real user)	Easily detected	Easily blocked
Fingerprint	Your real fingerprint	Headless browser fingerprint	No fingerprint

The key insight: bb-browser doesn't launch a new browser instance. It connects to your running Chrome via CDP (Chrome DevTools Protocol) and injects code into tabs. The User-Agent, cookies, and TLS fingerprint the website sees are all real — because it is your actual browser.

Architecture

AI Agent (Claude Code, Codex, Cursor)
         │ CLI or MCP (stdio)
         ▼
bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Real Browser
                            │
                     ┌──────┴──────┐
                     │ Per-tab event│
                     │ cache (net,  │
                     │ console)     │
                     └─────────────┘

bb-browser runs a daemon (default 127.0.0.1:19824) that communicates with Chrome via CDP WebSocket. CLI commands go to the daemon, which executes them in the corresponding tab.

Installation and Basic Usage

npm install -g bb-browser

Pull community adapters:

bb-browser site update

Try a command:

bb-browser site zhihu/hot

This opens a Zhihu tab (if you're already logged in), uses your cookies to fetch the trending questions list.

Structured Output

All commands support --json and --jq:

bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'
# {"name":"云天化","changePercent":"2.08%"}
# {"name":"东芯股份","changePercent":"-7.60%"}

Browser Operations

Beyond running adapters, you can directly control the browser:

bb-browser open https://example.com     # Open URL
bb-browser snapshot -i                  # Accessibility tree snapshot
bb-browser click @3                     # Click element
bb-browser fill @5 "hello"             # Fill input
bb-browser eval "document.title"       # Execute JavaScript
bb-browser fetch URL --json            # Authenticated fetch
bb-browser screenshot                  # Take screenshot

36 Platforms, 103 Commands

bb-browser's adapters cover a wide range:

Search: Google, Baidu, Bing, DuckDuckGo
Social: Twitter/X, Reddit, Weibo, Xiaohongshu, LinkedIn
Dev: GitHub, StackOverflow, Hacker News, npm, PyPI, arXiv, V2EX, Dev.to
News: BBC, Reuters, 36kr, Toutiao
Video: YouTube, Bilibili
Finance: Xueqiu, Yahoo Finance, Eastmoney
Knowledge: Wikipedia, Zhihu

Each adapter is a single JavaScript file, community-driven. To add a new platform, write a JS file and submit it to the bb-sites repo.

Three Levels of Adapter Complexity

Not every website is equally straightforward. bb-browser categorizes adapters into three levels:

Level	Approach	Examples	Dev Time
Level 1	Direct fetch with cookies	Reddit, GitHub	~1 min
Level 2	Bearer token + CSRF extraction	Twitter, Zhihu	~3 min
Level 3	Webpack injection or Pinia store	Twitter search	~10 min

Level 1 is simplest — some sites' APIs work with just cookies. Level 3 is most complex, requiring reverse engineering of frontend bundles, extracting data from Webpack's __webpack_require__ or Vue's Pinia store.

MCP Server for AI Agents

This is bb-browser's most compelling use case. Configure it as an MCP server, and Claude Code or Cursor can directly access any website your browser can see.

{
  "mcpServers": {
    "bb-browser": {
      "command": "npx",
      "args": ["-y", "bb-browser", "--mcp"]
    }
  }
}

Once configured, you can tell Claude Code "search arXiv for recent RAG papers" and it will search through bb-browser using your real browser.

Without bb-browser, an AI agent can only work with files and the terminal. With bb-browser, it can access the entire internet — as you.

I previously wrote about CLI-Anything, which wraps desktop software as CLIs for agents to call, and AionUi, which provides a unified interface for managing multiple agents. bb-browser extends agent capability from yet another angle: letting it browse the web using your real browser.

Things to Consider

A few things to think through before using it:

It uses your real account. bb-browser acts on your behalf. If the operation frequency is too high, your account might get flagged. It's not an invisible scraper — it IS you
Security. The daemon binds to localhost by default, but if you open it to 0.0.0.0, anyone who can reach your machine can control your browser. Use Tailscale or ZeroTier for safer remote access
Adapter quality varies. Community-driven means broad coverage, but some adapters may lag behind website redesigns
macOS users: watch for IPv6 issues — add --host 127.0.0.1 to the daemon command

When to Use It

bb-browser isn't for scraping millions of records. Use Scrapy for that.

It's ideal for:

Giving AI agents web access without applying for API keys one by one
Quickly pulling structured data from platforms you're already logged into
Cross-platform research — query arXiv, Twitter, GitHub, Zhihu, and StackOverflow in under a minute

One command does what used to require writing a scraper, and it won't get blocked.

References

AionUi: One Interface for 12+ AI Agents — A Free, Open-Source Cowork Desktop App

Recca Tsai — Tue, 07 Apr 2026 03:05:44 +0000

Originally published at recca0120.github.io

You've got Claude Code installed. Also Codex. Maybe Qwen Code for Chinese-language tasks. Each tool gets its own terminal window, MCP configs are duplicated across tools, and conversation history is scattered everywhere.

AionUi tackles exactly this: one desktop app that brings all your AI agents under a single interface. Free, open-source, Apache 2.0 licensed.

What It Does

AionUi is a cross-platform desktop app built with Electron + React, supporting macOS, Windows, and Linux. Its core purpose is unified management of multiple AI coding agents.

Supported Agents

AionUi auto-detects CLI tools installed on your machine. Currently supported:

Claude Code, Codex, Qwen Code, Goose AI, OpenClaw, Augment Code
iFlow CLI, CodeBuddy, Kimi CLI, OpenCode, Factory Droid, GitHub Copilot

Over 12 agents total. No extra configuration needed — install the CLI and it shows up in AionUi. If you don't have any CLI tools installed, AionUi has its own built-in agent that works with Google login or API key authentication.

20+ Model Platforms

Wide model selection:

Major platforms: Gemini, Claude, OpenAI
Cloud: AWS Bedrock
Chinese platforms: Dashscope (Qwen), Zhipu, Moonshot (Kimi), Baidu Qianfan, Tencent Hunyuan, ModelScope
Local models: Ollama, LM Studio

If you're in mainland China and can't easily access OpenAI or Claude APIs, just switch to Dashscope or Zhipu. For fully offline work, run Ollama with local models.

Configure MCP Once, Sync Everywhere

This is the most practical design choice. Configure MCP (Model Context Protocol) tools once in AionUi, and all agents sync automatically. No more maintaining separate mcp.json files for each agent — change it in one place, it applies everywhere.

12 Built-in Professional Assistants

AionUi isn't just an agent launcher. It comes with 12 pre-built assistants:

Assistant	Purpose
Cowork	Automated task execution
PPTX Generator	Presentation creation
PDF to PPT	Format conversion
3D Game	Single-file game prototyping
UI/UX Pro Max	57 styles, 95 color palettes
Beautiful Mermaid	Flowcharts, sequence diagrams
Planning with Files	File-based project planning

The Office features (PPT, Word, Excel) are powered by OfficeCLI, producing editable .pptx, .docx, and .xlsx files — not PDF screenshots. PPT output even supports Morph transition animations.

Scheduled Tasks: 24/7 Automation

This feature is uncommon in agent tools. You can set up scheduled tasks using natural language, like "every morning at 9am, summarize yesterday's Git commit log." AionUi converts it to a cron expression and runs it automatically.

Each scheduled task is bound to a conversation, maintaining context. Results are sent back to the conversation window, and can also be pushed to Telegram, Lark (Feishu), or DingTalk.

Preview Panel

AionUi has a built-in file preview supporting many formats:

Documents: PDF, Word, Excel, PowerPoint
Code: 30+ languages with syntax highlighting
Images: PNG, JPG, SVG, WebP, and more
Markup: Markdown and HTML with live editing

It also tracks file changes, shows Git version history, and supports one-click rollback.

WebUI Remote Access

You don't have to sit in front of your computer to use a desktop app. AionUi can serve a WebUI, accessible via QR code or password login from your phone or another computer. Supports both LAN and cross-network access.

Combined with Telegram, Lark, and DingTalk bot integration, you can send commands to AI agents from your phone and receive results in your chat groups.

Tech Stack

Layer	Technology
Framework	Electron
UI	React
CSS	UnoCSS
Build	Vite
Testing	Vitest + Playwright
Database	SQLite (local)
Language	TypeScript

All data is stored locally in SQLite — nothing gets uploaded to any server. With local models (Ollama), the entire workflow can run completely offline.

Installation

Download the installer for your platform from GitHub Releases. Homebrew is also supported on macOS.

Once installed, just open the app. If Claude Code or Codex is already on your machine, AionUi detects them automatically. Otherwise, use the built-in agent with an API key or Google login to get started.

Compared to Using Claude Code Alone

Claude Code is powerful, but it's a terminal tool. AionUi doesn't aim to replace it — it puts Claude Code alongside other agents in one managed workspace.

Key differences:

Multi-agent: Claude Code only runs Claude; AionUi runs multiple agents simultaneously
GUI: Full desktop interface with file preview, Office generation, and image processing built in
Scheduling: Claude Code has no built-in scheduling; AionUi runs tasks 24/7 automatically
Price: Claude Code requires API costs or a $100/month subscription; AionUi itself is free
Model choice: Not locked to one provider — 20+ platforms available

If you're interested in the AI agent tool ecosystem, I previously wrote about CLI-Anything: A Universal Bridge for AI Agents to Operate Any Software, which approaches the problem from the opposite angle — wrapping existing software as CLIs for agents to call. AionUi takes the agent management perspective instead.

Current State

AionUi is iterating rapidly, with 4,400+ commits on GitHub. The community is active on Discord (English) and WeChat groups (Chinese).

One caveat: while the star count is impressive, Electron apps typically have significant memory overhead. If you only use one agent, running the CLI in a terminal is lighter weight. AionUi's value shows when you genuinely need multiple agents, want GUI management, or require scheduling and Office generation features.

References

League Period: A Swiss Army Knife for Time Intervals in PHP

Recca Tsai — Mon, 06 Apr 2026 21:53:30 +0000

Originally published at recca0120.github.io

Have you ever written this kind of code — checking whether two time intervals overlap?

if ($startA < $endB && $startB < $endA) {
    // overlap
}

Looks simple, but add boundary conditions (include endpoints or not?), more intervals (what about three?), and gap detection (which time slots aren't covered?), and the code explodes.

League Period wraps time intervals into immutable value objects with built-in overlap, containment, gap, and intersection operations. No hand-written logic.

Install

composer require league/period

Requires PHP 8.1+.

Creating Intervals

From Dates

use League\Period\Period;

// Basic: specify start and end
$meeting = Period::fromDate('2026-04-06 09:00', '2026-04-06 10:30');

// Default is [start, end) — includes start, excludes end

From Calendar Units

// All of April 2026
$april = Period::fromMonth(2026, 4);

// Q1 2026
$q1 = Period::fromQuarter(2026, 1);

// Full year 2026
$year = Period::fromYear(2026);

// ISO week 15 of 2026
$week = Period::fromIsoWeek(2026, 15);

// A single day
$day = Period::fromDay(2026, 4, 6);

No need to figure out how many days April has or when the quarter starts — Period handles it.

From a Point + Duration

// 2 hours forward from a point
$slot = Period::after('2026-04-06 14:00', '2 HOURS');

// 30 minutes backward from a point
$before = Period::before('2026-04-06 14:00', '30 MINUTES');

// Centered on a point, 1 hour total
$around = Period::around('2026-04-06 14:00', '1 HOUR');

Boundary Control

Default is [start, end) (include start, exclude end). You can change it:

use League\Period\Bounds;

// Include both ends
$closed = Period::fromDate('2026-04-01', '2026-04-30', Bounds::IncludeAll);

// Exclude both ends
$open = Period::fromDate('2026-04-01', '2026-04-30', Bounds::ExcludeAll);

// Exclude start, include end
$leftOpen = Period::fromDate('2026-04-01', '2026-04-30', Bounds::ExcludeStartIncludeEnd);

Hotel booking systems often use [checkin, checkout) — check-in day is included, check-out day is not. Meeting room reservations work the same way.

Containment Checks

$workday = Period::fromDate('2026-04-06 09:00', '2026-04-06 18:00');

// Is a point inside the interval?
$workday->contains('2026-04-06 12:00');  // true
$workday->contains('2026-04-06 20:00');  // false

// Is one interval entirely inside another?
$lunch = Period::fromDate('2026-04-06 12:00', '2026-04-06 13:00');
$workday->contains($lunch);  // true

Overlap Detection

$meetingA = Period::fromDate('2026-04-06 09:00', '2026-04-06 10:30');
$meetingB = Period::fromDate('2026-04-06 10:00', '2026-04-06 11:30');
$meetingC = Period::fromDate('2026-04-06 11:00', '2026-04-06 12:00');

$meetingA->overlaps($meetingB);  // true (10:00-10:30 overlap)
$meetingA->overlaps($meetingC);  // false

No more writing if ($startA < $endB && $startB < $endA) yourself.

Comparison Operations

Period implements Allen's Interval Algebra — 13 possible relations between two intervals:

$a->meets($b);        // a ends exactly where b starts
$a->overlaps($b);     // partial overlap
$a->contains($b);     // a fully contains b
$a->isDuring($b);     // a is inside b (reverse of contains)
$a->equals($b);       // same start, end, and bounds
$a->abuts($b);        // adjacent (meets or metBy)
$a->bordersOnStart($b);
$a->bordersOnEnd($b);

Modification (Immutable)

Period is immutable — all modifications return new objects:

$original = Period::fromDate('2026-04-06 09:00', '2026-04-06 10:00');

// Extend the end
$extended = $original->endingOn('2026-04-06 11:00');

// Move the start
$moved = $original->startingOn('2026-04-06 08:30');

// Expand (add 30 min before and after)
$expanded = $original->expand('30 MINUTES');

// Shift the whole interval (keep duration)
$shifted = $original->move('1 HOUR');

$original is untouched. Safe to pass around.

Splitting and Iteration

$april = Period::fromMonth(2026, 4);

// Iterate by day
foreach ($april->dateRange('1 DAY') as $day) {
    echo $day->format('Y-m-d') . "\n";
}

// Split a month into weeks
foreach ($april->splitForward('1 WEEK') as $week) {
    echo $week->toIso80000('Y-m-d') . "\n";
}

Sequence: Collection Operations on Multiple Intervals

This is Period's most powerful feature. When you have a set of intervals and need to find gaps, intersections, or unions:

use League\Period\Sequence;

$sequence = new Sequence(
    Period::fromDate('2026-04-06 09:00', '2026-04-06 10:30'),  // Meeting A
    Period::fromDate('2026-04-06 11:00', '2026-04-06 12:00'),  // Meeting B
    Period::fromDate('2026-04-06 14:00', '2026-04-06 15:30'),  // Meeting C
);

Finding Gaps

"What time slots are free today?"

$gaps = $sequence->gaps();
// 10:30-11:00, 12:00-14:00

Shift scheduling, meeting room availability, doctor appointment slots — gaps() handles it in one line.

Finding Intersections

"Which time slots have two or more meetings overlapping?"

$overlaps = $sequence->intersections();

Sorting

$sorted = $sequence->sorted(fn (Period $a, Period $b) => $a->startDate <=> $b->startDate);

Practical Use Cases

Meeting Room Conflict Detection

function hasConflict(Period $newBooking, Sequence $existing): bool
{
    foreach ($existing as $booking) {
        if ($newBooking->overlaps($booking)) {
            return true;
        }
    }
    return false;
}

Available Slot Query

function getAvailableSlots(Period $workday, Sequence $meetings): Sequence
{
    return $meetings->gaps();
}

$workday = Period::fromDate('2026-04-06 09:00', '2026-04-06 18:00');
$meetings = new Sequence(
    Period::fromDate('2026-04-06 09:00', '2026-04-06 10:30'),
    Period::fromDate('2026-04-06 14:00', '2026-04-06 15:00'),
);

$available = getAvailableSlots($workday, $meetings);
// 10:30-14:00, 15:00-18:00

Reports: Monthly Breakdown

$year = Period::fromYear(2026);

foreach ($year->splitForward('1 MONTH') as $month) {
    $orders = getOrdersInPeriod($month);
    echo $month->startDate->format('Y-m') . ': ' . count($orders) . " orders\n";
}

Formatting

$period = Period::fromDate('2026-04-06 09:00', '2026-04-06 10:30');

// ISO 8601
echo $period;
// 2026-04-06T09:00:00+08:00/2026-04-06T10:30:00+08:00

// ISO 80000 (mathematical notation)
echo $period->toIso80000('Y-m-d H:i');
// [2026-04-06 09:00, 2026-04-06 10:30)

// JSON
echo json_encode($period);

Summary

Handling time intervals with raw DateTime is easy to write, hard to debug, and even harder to maintain. League Period wraps it all into a clean API:

Create intervals without calculating day counts
Overlap checks without hand-written conditions
Sequence's gaps() / intersections() solve common scheduling, booking, and reporting needs
Immutable design — safe to pass around without worrying about mutation

Good fit for anything involving "a span of time": booking systems, shift scheduling, reports, event dates, contract validity periods.

References

EmDash: A Full-Stack TypeScript CMS Built on Astro + Cloudflare — Can It Replace WordPress?

Recca Tsai — Mon, 06 Apr 2026 21:53:14 +0000

Originally published at recca0120.github.io

WordPress powers 43% of the web, but it was born in 2003. PHP + MySQL, plugins with full database access, content stored as HTML coupled to the DOM. After twenty years, it's fair to rethink the whole thing.

EmDash is that attempt. Full-stack TypeScript, running on Astro, backed by Cloudflare infrastructure. Still in beta, but the architecture is worth examining.

How It Differs from WordPress

Let's start with the biggest differences.

Sandboxed Plugin Isolation

96% of WordPress security vulnerabilities come from plugins. The reason is straightforward: plugins run in the same PHP process as the core, with full access to the database and filesystem. One bad plugin exposes the entire site.

EmDash uses Cloudflare Workers' Dynamic Worker Loaders for isolation. Each plugin must declare a capability manifest listing exactly what permissions it needs:

export default () =>
  definePlugin({
    id: "my-plugin",
    capabilities: ["read:content", "email:send"],
    hooks: {
      "content:afterSave": async (event, ctx) => {
        // Can only operate within declared permissions
      }
    }
  });

No write:content declaration, no write access. This fundamentally limits a plugin's attack surface.

Content Format: Portable Text Instead of HTML

WordPress stores content as HTML. Seems intuitive, but the problem is that HTML is tightly coupled to presentation. If you want the same content for an app, email, or API, you have to re-parse the DOM.

EmDash uses Portable Text, storing content as structured JSON. One piece of content can be processed by different renderers without reverse-engineering semantics from HTML.

Full-Stack TypeScript

WordPress is PHP with JavaScript layered on top for the frontend. EmDash is TypeScript from schema definition to frontend rendering, and schema changes generate types automatically:

npx emdash types

This command generates TypeScript type definitions from the database schema. Change the schema, and your IDE immediately shows type errors.

Architecture

No Database Lock-in

EmDash uses Kysely as its database abstraction layer, supporting multiple SQL dialects:

Environment	Database	Storage	Session	Plugin Isolation
Cloudflare	D1	R2	KV	Worker isolates
Self-hosted	SQLite / PostgreSQL	S3-compatible / local	Redis / file	In-process mode

Want to run on Cloudflare? Use D1 + R2. Want to self-host? Use SQLite + local filesystem. No vendor lock-in.

Astro Integration

EmDash is an Astro integration, configured like any other Astro plugin:

// astro.config.mjs
import emdash from "emdash/astro";
import { d1 } from "emdash/db";

export default defineConfig({
  integrations: [emdash({ database: d1() })]
});

Querying content uses getEmDashCollection, with syntax similar to Astro's Content Collections:

---
import { getEmDashCollection } from "emdash";
const { entries: posts } = await getEmDashCollection("posts");
---

{posts.map((post) => (
  <article>{post.data.title}</article>
))}

The key point: this data is fetched live from the database — no need to rebuild the entire site.

Feature Overview

Content Management

Customizable content types (collections) built through the admin UI
TipTap rich text editor
Version control, drafts, scheduled publishing
FTS5 full-text search

Authentication

Passkey-first (WebAuthn) by default, with OAuth and Magic link as alternatives. Four permission levels: Administrator, Editor, Author, Contributor.

Plugin Capabilities

Plugins go beyond simple hooks:

KV storage
Settings management
Admin pages
Dashboard widgets
Custom block types
API routes

AI Integration

EmDash natively supports MCP (Model Context Protocol), allowing direct content and schema manipulation through Claude or ChatGPT. Agent skills help with plugin and theme development.

WordPress Migration

Supports WXR export import, REST API integration, and WordPress.com import. A gutenberg-to-portable-text package converts Gutenberg blocks to Portable Text.

Quick Start

npm create emdash@latest

This runs a scaffold where you pick a template. Three options:

blog: categories, tags, full-text search, RSS, dark mode
marketing: hero section, pricing cards, FAQ, contact form
portfolio: project grid, tag filtering, case study pages

Local development:

git clone https://github.com/emdash-cms/emdash.git
cd emdash
pnpm install
pnpm build
pnpm --filter emdash-demo seed
pnpm --filter emdash-demo dev

Admin panel at http://localhost:4321/_emdash/admin.

Current Limitations

EmDash is still in beta. A few things to keep in mind:

Worker isolate sandboxing requires a paid Cloudflare account; free accounts run in-process mode (no sandbox)
The ecosystem is just starting — third-party plugins and themes can't compete with WordPress's library
Documentation is still being built; some features require reading source code
Portable Text has a steeper learning curve than HTML, especially for custom blocks

Who Is This For

If you're a heavy WordPress user who needs thousands of plugins and clients installing their own themes, EmDash can't replace that yet.

But if you're already using Astro and want a backend that lets non-technical people edit content — without wiring up a headless CMS API — EmDash's integration is seamless. Full-stack TypeScript, types that update with schema changes, and near-zero-config Cloudflare deployment.

It's not trying to kill WordPress, but it demonstrates what a CMS designed in 2026 can look like.

References

Typer: Build CLIs With Type Hints, No argparse API to Memorize

Recca Tsai — Thu, 02 Apr 2026 20:39:15 +0000

Originally published at recca0120.github.io

After accumulating scripts in a project, at some point you want to consolidate them into one CLI tool.

The standard approach is argparse, but argparse is verbose: add_argument, set type, set help, parse, then retrieve values — a simple CLI takes many lines.

Typer's approach: type hints are the specification, the function signature is the CLI interface, help comes from docstrings. Nothing to declare separately.

Same author as FastAPI. Same design logic.

Install

pip install typer

The Simplest Case

# main.py
import typer

def main(name: str, count: int = 1):
    for _ in range(count):
        print(f"Hello {name}")

if __name__ == "__main__":
    typer.run(main)

python main.py Alice
# Hello Alice

python main.py Alice --count 3
# Hello Alice
# Hello Alice
# Hello Alice

python main.py --help
# Usage: main.py [OPTIONS] NAME
# Arguments: NAME  [required]
# Options: --count INTEGER  [default: 1]

name: str has no default — becomes a required positional argument. count: int = 1 has a default — becomes an optional --count option. No argument parser declarations needed.

Multiple Subcommands

import typer

app = typer.Typer()

@app.command()
def deploy(env: str, force: bool = False):
    """Deploy to an environment."""
    if force:
        typer.echo(f"Force deploying to {env}")
    else:
        typer.echo(f"Deploying to {env}")

@app.command()
def rollback(env: str, version: str):
    """Rollback to a specific version."""
    typer.echo(f"Rolling back {env} to {version}")

if __name__ == "__main__":
    app()

python main.py deploy production
python main.py deploy staging --force
python main.py rollback production v1.2.3

python main.py --help
# Available commands: deploy, rollback

python main.py deploy --help
# Deploy to an environment.

The docstring becomes the --help description automatically.

bool types auto-generate both --force and --no-force options.

Arguments vs Options

@app.command()
def process(
    filename: str,                      # positional argument (required)
    output: str = "output.txt",         # --output (has default)
    verbose: bool = False,              # --verbose / --no-verbose
    workers: int = typer.Option(4, help="Number of workers"),  # with description
):
    ...

No default → positional argument, passed directly without --
Has default → option, passed as --name value
bool → flag, auto-generates --flag / --no-flag

Prompts and Confirmation

@app.command()
def delete(name: str, confirm: bool = typer.Option(False, prompt="Are you sure?")):
    if confirm:
        typer.echo(f"Deleted {name}")

python main.py delete mydb
# Are you sure? [y/N]: y
# Deleted mydb

Add prompt=True or prompt="..." to dangerous operations for automatic confirmation.

Colored Output

def check(service: str):
    if is_running(service):
        typer.echo(typer.style("✓ Running", fg=typer.colors.GREEN))
    else:
        typer.echo(typer.style("✗ Stopped", fg=typer.colors.RED, bold=True))

Progress Bar

import time

@app.command()
def process(items: int = 100):
    with typer.progressbar(range(items), label="Processing") as progress:
        for _ in progress:
            time.sleep(0.01)

Built in, no extra packages.

Nested Subcommands

For larger tools, group commands:

app = typer.Typer()
users_app = typer.Typer()
orders_app = typer.Typer()

app.add_typer(users_app, name="users")
app.add_typer(orders_app, name="orders")

@users_app.command("list")
def list_users():
    ...

@orders_app.command("list")
def list_orders():
    ...

python main.py users list
python main.py orders list

Shell Completion

# install into current shell
python main.py --install-completion

# show the completion script without installing
python main.py --show-completion

Bash, Zsh, Fish, and PowerShell supported. One command, done.

Compared to argparse / Click

	argparse	Click	Typer
Declaration	add_argument()	@click.option()	type hints
Help text	manual	manual	from docstring
Type conversion	set type=	set type=	inferred
Subcommands	subparsers	multiple commands	@app.command()
Learning curve	medium	medium	low

Typer is built on Click, so Click's ecosystem (plugins, testing utilities) still works.

How I Use It

I consolidate scattered scripts into a single CLI:

project/
├── cli.py          # app = typer.Typer(), entry point
├── commands/
│   ├── db.py       # database commands
│   ├── deploy.py   # deployment
│   └── seed.py     # test data

# cli.py
import typer
from commands import db, deploy, seed

app = typer.Typer()
app.add_typer(db.app, name="db")
app.add_typer(deploy.app, name="deploy")
app.add_typer(seed.app, name="seed")

What used to be python scripts/seed_db.py --env staging --users 100 becomes python cli.py seed users --env staging --count 100. Single entry point, --help discovers everything.

Summary

Typer maps Python type hints directly to CLI interfaces. No new API to learn — it reads like normal functions.

Good for:

Consolidating scattered admin scripts
Giving internal tools a proper CLI
Anything where shell completion would be useful

References

pytest: assert Is Enough, Forget self.assertEqual

Recca Tsai — Thu, 02 Apr 2026 20:38:59 +0000

Originally published at recca0120.github.io

After switching from unittest to pytest, the thing I noticed most wasn't some killer feature — it was not having to remember all the assertXxx methods.

Just write assert result == expected. pytest knows how to expand the failure message on its own.

Why pytest Instead of unittest

unittest ships with the standard library, no install needed, but it has some rough edges:

Tests must inherit from TestCase — you can't just write plain functions
You need self.assertEqual, self.assertIn, self.assertRaises… hard to keep track of
setUp / tearDown scope is fixed at the class level, not flexible

Three things in pytest that made me not go back:

Plain assert — failures show the actual values automatically
Fixtures injected on demand — scope can be function / class / module / session
parametrize — test multiple inputs with one decorator

Install

pip install pytest

The Simplest Test

# test_calc.py
def add(a, b):
    return a + b

def test_add():
    assert add(1, 2) == 3

pytest test_calc.py

On failure:

FAILED test_calc.py::test_add
AssertionError: assert 4 == 3
 +  where 4 = add(2, 2)

No guessing which value is which — pytest expands it.

Fixtures: Better Than setUp

unittest's setUp runs before every test with fixed class scope.

pytest fixtures let you control scope and share across modules:

import pytest

@pytest.fixture
def db():
    conn = create_db_connection()
    yield conn
    conn.close()  # teardown goes after yield

def test_query(db):
    result = db.query("SELECT 1")
    assert result == 1

Setup before yield, teardown after. Much cleaner.

Scope

@pytest.fixture(scope="module")   # one instance per module
def expensive_resource():
    return load_something_slow()

scope	lifetime
`function`	default — rebuilt for every test
`class`	shared within a class
`module`	shared within a file
`session`	shared for the entire test run

I typically set database connections to session scope, with each test function running inside its own transaction that rolls back. The full test suite runs without being painfully slow.

conftest.py

Fixtures in conftest.py are available to all test files in the same directory — no imports needed:

tests/
├── conftest.py       # shared fixtures here
├── test_users.py
└── test_orders.py

# conftest.py
import pytest

@pytest.fixture
def admin_user():
    return {"id": 1, "role": "admin"}

Both test_users.py and test_orders.py can use admin_user without importing anything.

parametrize: Multiple Inputs at Once

@pytest.mark.parametrize("a, b, expected", [
    (1, 2, 3),
    (0, 0, 0),
    (-1, 1, 0),
    (100, -50, 50),
])
def test_add(a, b, expected):
    assert add(a, b) == expected

Each set of inputs runs as a separate test. On failure, it tells you exactly which input set broke:

FAILED test_calc.py::test_add[0-0-1]

I use this for boundary conditions — normal values, zero, negatives, extremes all in one go.

Testing Exceptions

import pytest

def test_divide_by_zero():
    with pytest.raises(ZeroDivisionError):
        1 / 0

To also check the exception message:

def test_value_error():
    with pytest.raises(ValueError, match="invalid input"):
        parse_value("abc")

Running Only Some Tests

# specific file
pytest test_users.py

# specific function
pytest test_users.py::test_login

# by keyword
pytest -k "login or register"

# only last failed
pytest --lf

--lf (last failed) is what I reach for most. Fix a bug, immediately re-run just the tests that were failing — no need to wait through the whole suite.

Useful Options

pytest -v          # show each test name
pytest -s          # don't capture stdout (print shows up)
pytest -x          # stop on first failure
pytest --tb=short  # shorter tracebacks

During development I almost always add -x — one failure at a time, output doesn't get buried.

Summary

The gap between pytest and unittest isn't about features — it's about how comfortable the writing experience is. Plain assert, on-demand fixture composition, parametrize for multiple inputs. Once those habits are in place, testing stops feeling like something that requires opening documentation every time.

If your tests need a lot of fake data, polyfactory generates it from type hints automatically — no hand-crafting fixture data.