Forem: Recca Tsai

React Compiler 1.0 + Vite 8: The Right Way to Install After @vitejs/plugin-react v6 Drops Babel

Recca Tsai — Tue, 14 Apr 2026 22:10:33 +0000

Originally published at recca0120.github.io

React Compiler reached 1.0 stable in October 2025 — it auto-applies what useMemo / useCallback / React.memo do by hand. Most tutorials online still teach the old react({ babel: { plugins: [...] } }) form, which no longer works on Vite 8 + @vitejs/plugin-react v6.

v6 made one big change: internal Babel was dropped in favor of oxc. JSX transform and Fast Refresh now run in Rust — much faster, but the tradeoff is that Babel plugins can no longer be passed through react({ babel: {...} }). To run Babel-based tools like React Compiler, you now need to add @rolldown/plugin-babel separately.

This post documents the correct 2026 install flow and how to use React Compiler itself.

What React Compiler Actually Does

The most tedious part of writing React is sprinkling memoization everywhere. Children re-render, function references change, shallow comparison fails — solved by useMemo / useCallback / React.memo, but knowing when they help is an eyeball exercise.

React Compiler analyzes your components at build time and inserts memoization where it belongs.

Source:

function TodoList({ items, filter }) {
  const visible = items.filter(i => i.tag === filter);
  const onClick = (id) => toggle(id);
  return <List items={visible} onClick={onClick} />;
}

Compiled (conceptual):

function TodoList({ items, filter }) {
  const $ = _c(4);
  let visible;
  if ($[0] !== items || $[1] !== filter) {
    visible = items.filter(i => i.tag === filter);
    $[0] = items; $[1] = filter; $[2] = visible;
  } else {
    visible = $[2];
  }
  // onClick and the JSX are cached the same way
  // ...
}

_c() is a slot cache from react/compiler-runtime. Granularity is per-expression, not per-component — finer than any hand-written useMemo.

Status in April 2026

1.0 stable: GA on 2025/10/7
Battle-tested: ran at Meta scale (Instagram, Quest Store) for over a year pre-GA
React version: 19 is native; 17 / 18 need react-compiler-runtime
Function components only: class components are skipped

Vite 8 + @vitejs/plugin-react v6 (the new way)

v6 removed Babel, so Babel-based plugins need @rolldown/plugin-babel:

npm i -D @vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler

// vite.config.js
import { defineConfig } from 'vite'
import react, { reactCompilerPreset } from '@vitejs/plugin-react'
import { babel } from '@rolldown/plugin-babel'

export default defineConfig({
  plugins: [
    babel({
      include: /\.[jt]sx?$/,
      babelConfig: reactCompilerPreset(),
    }),
    react(),
  ],
})

Two things to notice:

reactCompilerPreset() is exported from @vitejs/plugin-react — it bundles babel-plugin-react-compiler with sane defaults so you don't hand-roll a preset.
Order: babel() before react(). The compiler must run before other transforms.

To stack other Babel plugins:

babel({
  include: /\.[jt]sx?$/,
  babelConfig: {
    ...reactCompilerPreset(),
    plugins: ['@babel/plugin-proposal-throw-expressions'],
  },
})

Vite 7 and below / @vitejs/plugin-react v5 (legacy)

If you haven't upgraded to Vite 8, the old form still works:

npm i -D @vitejs/plugin-react babel-plugin-react-compiler

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
  ],
})

The two forms are incompatible across one major version. Most people who hit this wall pasted an old tutorial into a fresh Vite 8 project.

Next.js 15.3.1+

Next bakes it in — no Babel wiring:

// next.config.js
module.exports = {
  experimental: {
    reactCompiler: true,
  },
}

Install the plugin: npm i babel-plugin-react-compiler. To customize the mode:

experimental: {
  reactCompiler: {
    compilationMode: 'annotation',
  },
}

Heads up: if Next.js enables the compiler, don't also add the Babel plugin manually — double compilation.

Webpack / Rspack

// webpack.config.js
{
  test: /\.[jt]sx?$/,
  use: {
    loader: 'babel-loader',
    options: {
      plugins: [['babel-plugin-react-compiler', {}]],
    },
  },
}

React Compiler must be the first plugin in the Babel chain.

ESLint Plugin — Enable This Before the Compiler

npm i -D eslint-plugin-react-compiler

// eslint.config.js
import reactCompiler from 'eslint-plugin-react-compiler'

export default [
  {
    plugins: { 'react-compiler': reactCompiler },
    rules: { 'react-compiler/react-compiler': 'error' },
  },
]

This plugin surfaces violations the compiler would silently skip (mutation, conditional hooks, refs read during render). Run ESLint in CI first, then enable the compiler — otherwise the compiler quietly passes over half your components and you don't know it.

Rules the Compiler Assumes

The compiler assumes you follow the Rules of React:

Pure render: no side effects, no Math.random(), no fetches during render
Immutability: don't mutate props, state, hook return values, or values from previous renders
Rules of Hooks: only at the top level, same order each render
Refs: read / write only in effects and handlers, never during render

Violations cause the compiler to skip that single component, not crash the build. The failure mode is silent regression — you think your component is optimized, it isn't. This is exactly what the ESLint plugin prevents.

Gradual Adoption: compilationMode

Going full-on with a flip is risky. The docs recommend phasing:

Mode	Behavior
`'all'` (default)	Every component is compiled
`'annotation'`	Only components with `"use memo"`
`'infer'`	Heuristic selection

Recommended path:

Upgrade React to 19 (or 17/18 + react-compiler-runtime)
Install the ESLint plugin, fix violations project-wide
compilationMode: 'annotation', add "use memo" to critical paths, test the water
Once stable, switch to 'all' and audit DevTools for the ✨ badge on every compiled component
Don't rush to remove old useMemo / useCallback — the compiler is additive; manual memo still works. Profile first, then delete file by file.

Escape-hatch directive:

function Weirdo() {
  "use no memo"   // compiler skips this component
  // ...
}

Good for temporary workarounds, not a permanent home.

Three Debugging Tools

1. React DevTools badge
Successfully compiled components show a Memo ✨ badge in the Components tab. No badge? Compiler skipped — check ESLint output.

2. React Compiler Playground
https://playground.react.dev — paste a component, see compiled output and bailout reasons immediately. Fastest way to answer "why didn't this one get optimized."

3. Plugin logger option

babelConfig: reactCompilerPreset({
  logger: {
    logEvent(filename, event) {
      console.log(filename, event)
    },
  },
})

Dump every compile event in dev — very direct when hunting down problems.

Real-World Performance Numbers

Numbers from the React team's 1.0 post (Meta production):

Instagram heavy screens: render time down ~12%
Quest Store navigation: 2.5× fewer re-renders

Synthetic summary: biggest wins when an expensive child is re-rendering because its parent re-renders every frame. Leaf components and hand-optimized code won't get much faster. Don't expect the entire app to magically accelerate.

Gotchas

Vite 8 + v6 ordering: babel() must come before react(). Reverse it and the compiler never runs, only oxc's JSX transform does.

Next.js double compilation: if Next has enabled it, don't add the Babel plugin manually.

Test environments: Jest / Vitest don't get the Babel transform by default, so components in tests aren't compiled — usually fine, but fixtures that intentionally mutate will trip ESLint. Add "use no memo" to those.

Storybook / MDX: exclude .stories.* files to avoid stories violating Rules of React.

Source maps: set sourcemap: true in Vite — the compiler's _c() slot code is painful to read in devtools without them.

Closing

React Compiler 1.0 GA, Vite 8, @vitejs/plugin-react v6 all landed within months of each other in late 2025 / early 2026, and stale tutorials are everywhere. The essentials:

Vite 8 + v6: @rolldown/plugin-babel + reactCompilerPreset()
Vite 7 and below: classic react({ babel: {...} })
ESLint first, CI before compiler
'annotation' mode → 'all', not a single flip
Don't bulk-delete useMemo / useCallback; the compiler is additive

The highest-value first step is the ESLint plugin — even before turning the compiler on, fixing Rules of React violations means almost zero surprises the day you flip the switch.

References

git worktree: Multiple Working Directories Per Repo, and the Key to Parallel AI Agents

Recca Tsai — Tue, 14 Apr 2026 21:05:49 +0000

Originally published at recca0120.github.io

You're mid-feature when PM says prod is on fire. The reflex move: git stash, check out master, fix, come back, stash pop. But then the dev server restarts, the IDE re-indexes, and stash silently ate your untracked build artifacts.

git worktree fixes this cleanly: one repo, many checked-out branches in separate directories, each with its own HEAD, index, and untracked files — all sharing the same object database. The feature stays exactly where you left it; the hotfix happens next door.

vs stash, vs multiple clones

Approach	Switch cost	Disk	Object sync
`git stash` + checkout	High (dev server restarts, IDE reindex)	Cheap	Single repo
Multiple clones	Low	Wasteful (GBs on large repos)	Each fetches separately
`git worktree`	Low	Cheap (shared objects)	One fetch updates all

Worktree is the synthesis — filesystem isolation with a unified object store.

Core Commands

# Add — last path segment becomes the new branch name
git worktree add ../hotfix                   # branch "hotfix" from HEAD
git worktree add ../review pr-123            # checkout existing branch
git worktree add -b feat-x ../feat-x main    # new branch from main
git worktree add -d ../throwaway             # detached HEAD, no branch

git worktree list                            # --porcelain for scripts
git worktree remove ../hotfix                # clean only; -f for dirty
git worktree prune                           # clean metadata for manually deleted dirs
git worktree lock ../usb-drive --reason "removable drive"
git worktree unlock ../usb-drive
git worktree move ../old ../new              # won't move worktrees w/ submodules
git worktree repair                          # fix links after moving the main repo

Short aliases make it muscle memory:

git config --global alias.wta 'worktree add'
git config --global alias.wtl 'worktree list'
git config --global alias.wtr 'worktree remove'

Real Workflows

1. Hotfix without disturbing feature work

git worktree add ../hotfix-prod origin/main
cd ../hotfix-prod
# fix, commit, push, open PR
cd ../myrepo
git worktree remove ../hotfix-prod

The feature's dev server never stopped. node_modules untouched. IDE didn't re-index.

2. Long test run + keep coding

pytest / cargo test takes 10 minutes. Open a worktree to run it there while you keep editing the next commit. Zero interference.

git worktree add ../ci-run branch-a
cd ../ci-run && pytest --slow &
cd -   # back to main worktree, keep coding

3. Code review without polluting your state

git worktree add ../review-456 pr-456-branch
cd ../review-456
# run it, read code, leave comments
cd - && git worktree remove ../review-456

4. Multiple AI agents in parallel (the most underrated 2025 use case)

Claude Code / Cursor / Aider only work in one directory at a time — running two in the same folder means they overwrite each other's files. One branch per worktree and you can run three agents on three features simultaneously, each with its own dev server port and node_modules, no collisions:

git worktree add ../agent-a -b feat-a
git worktree add ../agent-b -b feat-b
git worktree add ../agent-c -b feat-c

# three tmux panes / three terminal windows, one claude each

Claude Code's Agent tool even has a built-in isolation: "worktree" option — sub-agents automatically run in a worktree and merge back when done.

Three Directory Layouts

Sibling dirs (simplest)

~/code/myrepo
~/code/myrepo-hotfix
~/code/myrepo-review-123

Plays well with editors' "one folder, one project" mental model.

.worktrees/ subdir

myrepo/
├── src/
└── .worktrees/
    ├── feat-x/
    └── hotfix/

Everything co-located. Add .worktrees/ to global gitignore. Downside: some tools (ESLint, tsc) recurse into it.

Bare repo pattern (best for heavy multi-branch work)

mkdir myproj && cd myproj
git clone --bare git@github.com:org/repo.git .bare
echo "gitdir: ./.bare" > .git
git worktree add main
git worktree add feat-x

Result:

myproj/
├── .bare/           # actual object store
├── .git             # file, pointing to .bare
├── main/            # main branch checkout
└── feat-x/          # feat-x branch checkout

No "primary working copy" — every branch is a worktree, cd is the branch switch. Pairs beautifully with tmux and AI agents.

Gotchas

.git in a linked worktree is a file, not a directory. Contents are gitdir: /path/to/main/.git/worktrees/<name>. Tools that read .git/ as a directory will break.

You can't check out the same branch in two worktrees. By design — prevents index divergence. Override with --force or use detached HEAD.

Submodules are painful. worktree move refuses; remove needs --force. .git/modules/ is shared, so switching submodule commits in one worktree affects the others. Heavy-submodule repos need care.

node_modules, venv, target/ are per-worktree. Disk gets hungry. Mitigations:

pnpm's content-addressable store — reinstalling across worktrees uses almost no extra space
Rust: CARGO_TARGET_DIR=~/.cache/cargo-target shares target dirs
uv, poetry caches are shareable too

.env doesn't get copied. Use direnv — drop a .envrc in each worktree and it auto-loads on cd.

Hooks are shared (.git/hooks/ is in the common dir). If a hook assumes repo root via a hardcoded path, it breaks in linked worktrees. Always use git rev-parse --show-toplevel for the current worktree's root.

IDE indexes run per worktree. VS Code / JetBrains index each one independently — duplicate CPU and disk. Structural limit, no way around it.

Editor Integration

VS Code: use multi-root workspace (File → Add Folder to Workspace) to open multiple worktrees at once, or just open each in its own window. Since 2024, GitHub.vscode-pull-request-github checks out PRs as worktrees.

JetBrains: native worktree UI in the Git tool window since 2023.2 — create, switch, remove from the GUI.

fzf quick-switch:

wtcd() {
  cd "$(git worktree list --porcelain | awk '/^worktree /{print $2}' | fzf)"
}

Type wtcd, fuzzy-search worktree paths, enter to cd.

What's New in 2024–2026

Git 2.44 (2024/2): git worktree add --orphan — creates a worktree with an unborn branch. Handy for gh-pages-style split deploy branches.

Git 2.46 (2024/7): worktree.useRelativePaths config + --relative-paths flag — internal links use relative paths. The main repo (or the whole dir tree) can move without breaking worktrees. Huge for Dropbox/iCloud sync and containerized dev.

Git 2.48 (2025/1): git worktree repair auto-fixes absolute/relative path mismatches.

Git 2.50 (mid-2025): relative paths and porcelain output have stabilized.

Ecosystem: "one worktree per AI agent branch" went mainstream in 2025. git-town, ghq, and the gh CLI all picked up first-class worktree support.

Getting Started

In any repo, try git worktree add ../test-wt -b test-branch and poke around
Back in the main worktree, notice git branch sees it but git status is untouched
git worktree remove ../test-wt — main worktree is completely unchanged
Add wta / wtl / wtr aliases, build muscle memory
Next hotfix, use worktree instead of stash — feel the difference

For anyone using AI coding agents, worktree isn't a bonus — it's required. The "only one agent per repo" limitation is the exact thing worktree removes.

References

Cloudflare Tunnel in 2026: Expose localhost Without Opening Ports or Buying an IP

Recca Tsai — Tue, 14 Apr 2026 17:46:48 +0000

Originally published at recca0120.github.io

A side project at home needs a public demo URL for a client. A NUC in the office runs an internal tool I want to reach from outside. The old playbook — rent a static IP, forward ports on the router, manage Let's Encrypt — is all skippable in 2026.

Cloudflare Tunnel (cloudflared) does the dirty work: your machine opens an outbound-only persistent connection to Cloudflare's edge, and inbound traffic rides that connection back home. No open ports, no public IP, and you get Cloudflare's DDoS protection and WAF for free.

Why Cloudflare Tunnel

Plenty of alternatives exist, and they target different use cases:

Tool	Custom domain	Auth	Self-hosted relay	TCP support	Free tier
Cloudflare Tunnel	✅ free	✅ Access built-in	❌ CF-managed	✅	Generous
ngrok	Paid	Paid add-on	❌	Paid	Connection-capped
Tailscale Funnel	Limited	❌	P2P-ish	HTTPS only	3 ports only
frp	DIY	DIY	✅ self-host	✅	Your machine

Tunnel's real differentiator: it doesn't just forward traffic — it plugs your service into Cloudflare's entire Zero Trust platform. Layer Access (SSO, email OTP) on top, pass traffic through WAF, even get browser-rendered SSH without a client. Those are paid upsells on ngrok and simply don't exist on Funnel.

The 2026 Recommended Flow: Zero Trust Dashboard

Historically cloudflared was configured via local config.yml. In 2026 Cloudflare steers most users to remotely-managed tunnels — config lives in the cloud dashboard, the local cloudflared just needs a token. Bonus: share tunnels across machines, edit ingress without restarts, run multiple replicas for HA.

Go to one.dash.cloudflare.com → Networks → Tunnels → Create a tunnel → Cloudflared. Name it, copy the install command.

Install cloudflared

macOS:

brew install cloudflared

Linux (Debian/Ubuntu):

curl -L https://pkg.cloudflare.com/install.sh | sudo bash
sudo apt install cloudflared

Docker:

docker run -d --name cf-tunnel --restart unless-stopped \
  cloudflare/cloudflared:latest \
  tunnel --no-autoupdate run --token eyJhbGci...

Drop in the token the dashboard gave you:

sudo cloudflared service install eyJhbGci...TOKEN...

This registers a systemd service (Linux) or launchd plist (macOS), auto-starts on boot, auto-restarts on crash. Check the dashboard — green Healthy means you're live.

Pushing localhost:3000 to foo.example.com

Prerequisite: example.com already uses Cloudflare nameservers.

Back on the tunnel page, switch to the Public Hostname tab → Add a public hostname:

Field	Value
Subdomain	`foo`
Domain	`example.com`
Service Type	`HTTP`
URL	`localhost:3000`

Save. Cloudflare auto-creates the DNS CNAME foo.example.com → <tunnel-uuid>.cfargotunnel.com. Hit https://foo.example.com — the cert comes from Cloudflare's edge; your local box needs zero TLS config.

Gate It With Zero Trust Access

Don't want random scanners finding your demo URL? Put a login wall in front:

Zero Trust → Access → Applications → Add an application → Self-hosted

Application domain: foo.example.com
Add policy: Action = Allow, Include = Emails ending in @yourco.com (or a specific email list)
Identity provider: the default One-time PIN (email OTP) works out of the box, or hook up Google SSO / GitHub via Settings → Authentication

Next visit to foo.example.com lands on a Cloudflare login screen first. Free up to 50 users.

TryCloudflare: Disposable Demo Tunnels

Need to show a webhook or demo in 30 seconds, not even wanting to open an account:

cloudflared tunnel --url http://localhost:8080

Prints https://<random-words>.trycloudflare.com — random subdomain, traffic routed back to your localhost. Dies with the process. Great for temporary use, not production, rate-limited.

Local config.yml (for the GitOps crowd)

To keep tunnel config in Git or drive it from Terraform, the old workflow still works:

cloudflared tunnel login
cloudflared tunnel create dev-laptop
cloudflared tunnel route dns dev-laptop foo.example.com

~/.cloudflared/config.yml:

tunnel: dev-laptop
credentials-file: /Users/me/.cloudflared/<UUID>.json
ingress:
  - hostname: foo.example.com
    service: http://localhost:3000
  - hostname: api.example.com
    service: http://localhost:4000
    originRequest:
      connectTimeout: 30s
      noTLSVerify: true
  - service: http_status:404

Run: cloudflared tunnel run dev-laptop

Footguns I've Stepped On

Always include the catch-all ingress. Without - service: http_status:404, cloudflared refuses to start:

ingress:
  - hostname: foo.example.com
    service: http://localhost:3000
  - service: http_status:404   # mandatory final entry

WebSockets just work. Default-on since 2022, no flag needed. Next.js HMR, Socket.IO, fine.

SSH / RDP also work. Ingress entry service: ssh://localhost:22, then enable Browser rendering in the Access app — users get an in-browser terminal with no client install.

Run the same tunnel on multiple hosts. Re-use the same token on a second machine and Cloudflare handles HA / load balancing automatically. Reboot one host, service stays up.

Per-hostname originRequest. Each ingress can independently set httpHostHeader, connectTimeout, noTLSVerify — no need to change global settings for one service.

Pricing

Tunnel itself: 100% free, unmetered bandwidth, unlimited tunnels
Zero Trust Access: free up to 50 users, then Cloudflare One pay-as-you-go ~$7/user/month
No egress fees, no connection limits

For individuals and small teams, it's effectively free.

Notable 2025–2026 Updates

Dashboard consolidation: dash.teams.cloudflare.com is fully retired; everything lives at one.dash.cloudflare.com. If you land on an old tutorial, update the URL.

WARP Connector GA: where Tunnel exposes individual services, WARP Connector brings entire subnets onto Cloudflare's network. Site-to-site VPN replacement; complements Tunnel for full-network reach.

Cloudflare One rebrand: Access, Gateway, Tunnel, WARP, CASB, DLP, Email Security merged into a single SSE platform. One Zero Trust menu now covers all enterprise network security.

Terraform provider v5 is stable: full IaC for tunnel resources, trivial multi-environment deployments.

QUIC as default: cloudflared now uses QUIC (HTTP/3) by default, faster connection establishment and more resilient on flaky networks.

When Not to Use Tunnel

Great tool, not universal:

Want strict peer-to-peer with no third party: use Tailscale / WireGuard
Regulatory rules require non-US / non-CF transit: self-host frp or enterprise VPN
Huge static file traffic: Cloudflare Pages / R2 is a better fit than tunneling
Five-minute demo with no domain: TryCloudflare or ngrok is faster

Closing

Demo environments, webhook receivers, showing your coworker a work-in-progress — in 2026 Cloudflare Tunnel is almost always the lowest-friction answer. Generous free tier, security handled by Cloudflare, and the same setup carries from dev to production.

Three steps to live: brew install cloudflared → dashboard creates tunnel → paste token. Everything complicated lives in a cloud UI.

References

I Scanned 95 Days of My Claude Code Logs and Found Anthropic''s Second Silent Cache TTL Regression

Recca Tsai — Mon, 13 Apr 2026 18:47:02 +0000

Originally published at recca0120.github.io

The previous post covered prompt caching cost mechanics. While researching it I bumped into a dramatic controversy — in March 2026 Anthropic silently changed Claude Code's cache TTL from 1 hour back to 5 minutes, with community-measured monthly costs inflating 15–53%. Reddit and HN exploded.

But every public claim is somebody else's billing statement or issue #46829. I wanted to know whether my own machine was affected. After scanning 95 days of native logs, the answer turned out richer than expected: I not only reproduced the March 6 regression precisely, but also discovered a second wave starting April 9 — five consecutive days, 4,840 API calls, sub-agents 100% downgraded to 5m, and no public report I can find.

The Evidence Is in ~/.claude/projects JSONL

Claude Code writes complete API interaction logs at:

~/.claude/projects/{project-path}/{session-uuid}.jsonl

Each assistant response carries a usage.cache_creation object that directly tells you which TTL bucket this write went to:

{
  "cache_creation": {
    "ephemeral_5m_input_tokens": 0,
    "ephemeral_1h_input_tokens": 6561
  }
}

These fields come straight from Anthropic's API, bypassing any client-side display logic. If the client wanted to lie, the server wouldn't go along — this data is the truth from the server itself.

A Python script that scans every project, splits by date, and separates main agent from sub-agent:

#!/usr/bin/env python3
import json
from pathlib import Path
from collections import defaultdict

ROOT = Path.home() / ".claude/projects"
main = defaultdict(lambda: {"5m":0,"1h":0,"calls":0})
sub  = defaultdict(lambda: {"5m":0,"1h":0,"calls":0})

for jsonl in ROOT.rglob("*.jsonl"):
    bucket = sub if "subagent" in jsonl.parent.name.lower() else main
    try:
        with jsonl.open() as fp:
            for line in fp:
                try: d=json.loads(line)
                except: continue
                ts=d.get("timestamp"); msg=d.get("message")
                if not isinstance(msg,dict) or not ts: continue
                u=msg.get("usage") or {}; cc=u.get("cache_creation") or {}
                w5=cc.get("ephemeral_5m_input_tokens",0)
                w1=cc.get("ephemeral_1h_input_tokens",0)
                if not (w5 or w1): continue
                day=ts[:10]
                bucket[day]["5m"]+=w5
                bucket[day]["1h"]+=w1
                bucket[day]["calls"]+=1
    except: pass

def pct(s):
    tot=s["5m"]+s["1h"]
    return s["1h"]/tot*100 if tot else 0

print(f"{'Date':<11} | {'M5m':>10} {'M1h':>11} {'M%':>4} | {'S5m':>11} {'S1h':>12} {'S%':>4} {'calls':>5}")
for d in sorted(set(main.keys())|set(sub.keys())):
    if d < '2026-01-01': continue
    m=main[d]; s=sub[d]
    print(f"{d} | {m['5m']:>10,} {m['1h']:>11,} {pct(m):>3.0f}% | "
          f"{s['5m']:>11,} {s['1h']:>12,} {pct(s):>3.0f}% {s['calls']:>5}")

95-Day Timeline

Scanning my machine from January 9 through April 13, four phases with three transitions emerge:

Phase	Window	Sub-agent	Main agent	Event
1	1/9 ~ 2/5	100% 5m (28 days)	no data	1h not yet rolled out
2	2/6	79% 1h (transition starts)	—	The 2/1-announced 1h upgrade actually goes live
3	2/7 ~ 3/5	100% 1h stable (28 days)	100% 1h	1h golden era
4	3/6 ~ 4/8	1h ↔ 5m mixed, swinging 6%–97%	100% 1h	First regression (the one cnighswonger reported)
5	4/9 ~ now	100% 5m stable (5 days)	100% 1h	Second regression (no public report)

Key days around each transition:

Date        | MAIN 1h  calls | SUB 5m         SUB 1h         S1h%   calls
------------|----------------|-----------------------------------------
2026-02-05  | (no data)      |          0    7,974,898       100%   1392    ← still 1h
2026-02-06  | (no data)      |  2,886,030   10,753,834        79%   1684    ← 1h rollout begins
2026-02-07  | (no data)      |          0    4,280,317       100%    639

2026-03-05  | 100%   1503    |          0    6,004,235       100%   2446    ← still 1h
2026-03-06  | 100%   3355    |    461,509    1,281,686        74%    608    ← FIRST regression!
2026-03-07  | 100%   2753    |  9,810,771   10,465,251        52%   7548
2026-03-08  | 100%   4724    | 34,340,003   24,301,557        41%  17514

2026-04-08  | 100%   3041    |  2,650,760    5,533,277        68%   1301    ← still mixed
2026-04-09  | 100%   4155    |  8,451,674            0         0%   1268    ← SECOND regression!
2026-04-10  | 100%   5523    |  5,437,455            0         0%   1170
2026-04-11  | 100%   2579    |  3,325,195            0         0%    778
2026-04-12  | 100%   3738    |  2,981,213            0         0%    993
2026-04-13  | 100%   4443    |  2,648,132            0         0%    631

Decoding the Three Transitions

Transition 1: 2026-02-06 — 1h Rollout Goes Live

Anthropic announced "TTL upgraded from 5m to 1h" on 2/1. The actual rollout landed on 2/6. My logs show sub-agent flipping from 100% 5m to 79% 1h overnight, matching the announcement.

Transition 2: 2026-03-06 — First Silent Regression

This is the event cnighswonger reported in issue #46829, using the same methodology to scan 119,866 API calls — on March 6, sub-agent went from 100% 1h to 74%. I reproduced it precisely: 3/5 still 100% 1h, 3/6 dropped to 74%, 3/7 spiked to 9.8M tokens of 5m writes.

The following month (3/6–4/8), sub-agent oscillated wildly between 6% and 97% 1h share. The server's TTL decision logic was unstable.

Anthropic employee Jarred Sumner defended in The Register's coverage that "sub-agent 5m is cheaper for one-shot calls" — barely plausible for the mixed phase 4 behavior. But the next event breaks that defense.

Transition 3: 2026-04-09 — Second Silent Regression (Original Finding)

Starting 4/9, sub-agent 1h share dropped to zero. Five consecutive days, 100% 5m, across 4,840 API calls. No public report I can find.

Why this matters:

Not noise. 4,840 calls with zero 1h, while 4/8 was still 68% 1h. This is a sharp binary cutover, not gradual drift.

Not a quota-triggered downgrade. Anthropic's docs say exceeding 5h quota triggers a server-enforced downgrade. But main agent is 100% 1h on the same days — quota mechanism would have downgraded both.

Not a client version issue. Same client, same day, two different TTL behaviors for main vs sub.

Not a workflow change. API call volume sits in the normal range (631–1268 per day), comparable to early April.

The only plausible explanation: starting 4/9, the server changed sub-agent default TTL from "mixed" to "hard-coded 5m". And no changelog, no announcement, no issue mentions it — the same silent-rollout pattern as 3/6.

Why Main Agent Was Never Affected

Across all 95 days, main agent has zero 5m writes. Every TTL action Anthropic took only touched sub-agents:

Claim	Did my data verify it
Reddit "Anthropic silently changed TTL on 3/6"	✅ Strongly verified (precise 3/6 transition)
Sumner "main agent unaffected"	✅ Verified (main 100% 1h across 95 days)
"Regression only hits sub-agent"	✅ Verified
Sumner "sub-agent 5m is a one-shot optimization"	⚠️ Partially refuted (4/9 100% 5m isn't optimization, it's forced downgrade)
New finding: 4/9 sub-agent 100% 5m	🆕 Original

Anyone Can Reproduce This

Save the script above as ~/bin/cc-ttl-timeline.py and run:

python3 ~/bin/cc-ttl-timeline.py

If you see corresponding 3/6 and 4/9 transitions in your sub-agent — you're a silent regression victim, please add a data point to issue #46829. If you don't see them — the regression isn't a 100% rollout and you're in the control group.

Both outcomes have value. The point is this evidence chain doesn't depend on anyone's claims — the source is local JSONL written by Claude Code to your disk, and the cache_creation object structure is part of Anthropic's public API spec. To fake this the server would have to lie in its own API responses.

Why Not Just Use cnighswonger's npm Package

cnighswonger/claude-code-cache-fix is excellent, but it only sees data captured after install — its monitoring tools (status line, cost-report, quota-analysis) read ~/.claude/usage.jsonl, which only exists while the interceptor is loaded.

For historical audit, only Claude Code's own ~/.claude/projects/*.jsonl works. That's what this post uses.

The two are complementary:

Scenario	Tool
Look back, find regression transition dates	The Python script in this post
Live TTL state visibility + fix client cache bugs	cnighswonger's package
General token usage analysis	ccusage

Closing

"Did Anthropic silently change cache TTL?" — everyone should scan their own data. Community rumors and Anthropic's official statements aren't enough. Only the JSONL on your disk doesn't lie.

The result is valuable either way: see the regression → you're a victim, contribute evidence; don't see it → you're in the control group, which is also evidence that the rollout isn't 100%.

I'll keep scanning every few days to see how long the 4/9 wave persists and whether it spreads to main agents. If your data shows similar 100% 5m sub-agent behavior post-4/9, please comment on issue #46829 or reach out.

References

Cache TTL silently regressed from 1h to 5m — GitHub Issue #46829 — cnighswonger's original evidence
Followup: Anthropic quietly switched the default — r/ClaudeAI
Anthropic: Claude quota drain not caused by cache tweaks — The Register
Anthropic downgraded cache TTL on March 6th — Hacker News
cnighswonger/claude-code-cache-fix — fixes client cache-busting bugs + live monitor
Prompt Caching — Claude API Docs
ccusage — Claude Code Usage CLI

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.

What "Prefix" Actually Means

Before going further, it's worth unpacking the word "prefix." A prompt is an ordered sequence of tokens. Cache matching runs from the very beginning, token by token — and a single differing token breaks everything after it.

In multi-turn conversations, every new turn only appends to the tail; the prior history stays untouched:

Turn 1: [system] [CLAUDE.md] [Q1]
Turn 2: [system] [CLAUDE.md] [Q1] [A1] [Q2]
         ↑ identical prefix → cache hit at 10% price
                                    ↑ new tail → written to cache
Turn 3: [system] [CLAUDE.md] [Q1] [A1] [Q2] [A2] [Q3]
         ↑ an even longer prefix hits cache

So long conversations aren't a cost disadvantage — they're an advantage. The longer the accumulated history, the more tokens per turn get the 90% discount.

But this only holds while you're strictly appending. If you could go back and edit Turn 5, every token after Turn 5 — even ones that look identical — invalidates because the prefix hash diverges from that point onward. That's the cruelty of "prefix": change one character in the middle and everything downstream is lost.

Analogy: git commit hashes. Tweak any historical commit and every hash after it changes.

Topic Switching: How Cache Bills Across A → B → C

The most-overlooked scenario: you discuss topic A with Claude, finish, move to topic B, then topic C — without /clear in between. A's and B's histories stay glued to the prompt prefix, getting billed at 10% on every single turn while they ride along.

Concretely:

Topic A (30K tokens accumulated over 10 turns)
  → A's 30K written to cache

Switch to B (no /clear)
  Turn 11 = [A's 30K] + [B's new question]
            ↑ 30K × $0.30/M = $0.009 from cache

B accumulates 20K more

Switch to C (still no /clear)
  Every turn = [A's 30K] + [B's 20K] + [C's new question]
               ↑ 50K from cache ≈ $0.015 / turn

20 turns on C means an extra 20 × $0.015 = $0.30 spent "carrying corpses." A and B may contribute nothing to C, but you're paying for them to ride along.

Rule of thumb for when to /clear:

A, B, C are independent (frontend in the morning / SQL in the afternoon / CI at night) → /clear between topics
A, B, C reference each other (A defines spec / B implements / C debugs B) → don't clear; the 10% price on history is cheap and useful
History is heavy but its conclusion is condensable (A was a 50K doc you read) → clear, then paste a short summary of A's conclusions as new context

A common misconception: "Claude Code automatically detects topic changes and drops stale content." It doesn't. Cache is mechanical prefix matching — it has no semantic understanding. Deciding what to forget is entirely a human responsibility: either /clear manually, or let auto-compact fire based on context usage (not topic).

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 it — some loudly, some quietly:

Event	Impact
Editing message N	Everything from N onward invalidates (earlier still cached)
Adding/removing an MCP tool	Full invalidation (tool schemas sit at the front)
Switching Sonnet ↔ Opus	Different model, different cache — starts over
Toggling web search / citations	system + message cache invalidates
Idle > 5 minutes (TTL expires)	Cache evaporates; next call pays 100% to rewrite
Auto-compact fires	Prefix is replaced by a summary; subsequent turns warm a fresh cache
`/clear`	Everything resets

Idle-over-5-minutes is the sneakiest — grab lunch, come back, type a question, and you've quietly paid full write price without any UI warning.

A nuance about auto-compact worth clarifying: per Anthropic's implementation, the compaction API call itself sends the same prefix as the turn before it, so that call is a cache hit. The real cost lands after compaction — the new session uses the summary in place of the original history as its prefix, so every subsequent turn is warming a brand-new cache from that point on. The net cost is similar to "cache blown away," but the mechanism is prefix replacement, not cache invalidation.

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: age1examplepublickeyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

encryption = "age"

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

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 a handful of directories with long, inconsistent paths. For years I either mashed cd ~/some/long/path<TAB> or dragged folders from Finder into the terminal. Then I installed zoxide. Now two or three characters is all it takes.

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 what the database looks like:

$ zoxide query --score | head -5
 230.0 /Users/demo/projects/frontend
 215.3 /Users/demo/work/api-server
 198.7 /Users/demo/blog
 142.1 /Users/demo/oss/some-tool
  98.5 /Users/demo/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 blog            # → ~/work/personal-blog
cd api             # → ~/work/api-server
cd dotfiles        # → ~/config/dotfiles

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

cd work blog       # → ~/work/personal-blog
cd client api      # → ~/work/client-project/api

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 blog
# → /Users/demo/work/personal-blog

zoxide query --list blog      # 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.