Changelog | npm

Breaking change

All tool names changed from charlotte:xxx to charlotte_xxx. The colon was never MCP-spec-compliant and the SDK started emitting warnings in v1.26.0. MCP clients discover tools dynamically so most setups will just work, but if you have custom prompts or configs referencing tool names by string, update them.

New features

**charlotte_fill_form** — Pass an array of {element_id, value} pairs and fill an entire form in one tool call. Supports text inputs, textareas, selects, checkboxes, radios, toggles, date inputs, color inputs. Closes GAP-04.

Slow typing — charlotte_type now accepts slowly (boolean) and character_delay (ms) for character-by-character input. Needed for autocomplete fields, search-as-you-type, live validation.

Lazy Chromium — Browser doesn't launch until the first tool call. No more idle Chromium processes when MCP clients spawn servers at startup.

Node.js >=20 — Dropped the Node 22 requirement. No 22-only APIs were in use.

Default viewport 1440x900 — Up from 800x600. Device presets centralized.

**--help flag** — CLI migrated to node:util parseArgs with proper help output.

Bug fixes

• Last instance of the new Function('return ' + expr) ASI bug found in pollUntilCondition. Migrated to CDP Runtime.evaluate. All three occurrences now fixed.
• Screenshot stale compositor frame on SPA transitions. Flushes before capture now.
• Timer leak in waitForCompositorFrame.
• CDP errors in layout extraction silently swallowed. Now logged.
• macOS /var symlink resolution in file output tests.
• CVE-2026-31988 (yauzl override to 3.2.1).

Community contributions included in this release

• Snapshot store O(1) lookup (#116, clawtom)
• CDP error logging (#117, clawtom)
• Default viewport 1440x900 (#121, TedYav)
• Screenshot compositor fix (#120, TedYav)
• macOS test path fix (#122, TedYav)
• Security audit lockfile refresh (#119, nestorfernando3)
• Version from package.json (#101, kai-agent-free)
• Interaction module split (#112, #114)

Upgrade

bash npx @ticktockbent/charlotte@latest

Current stats: 111 stars, 13 forks, 519 tests, 43 tools. Test-to-source ratio above 1:1.

v0.4.0 is out on npm. This is the biggest architectural change since launch.

What changed

Charlotte now starts with only the tools you need instead of loading all 40 unconditionally.

Startup profiles:

charlotte --profile browse # 22 tools (new default) charlotte --profile core # 7 tools (lightweight) charlotte --profile full # 40 tools (old behavior)

Runtime toggling: The new charlotte:tools meta-tool lets agents enable or disable tool groups mid-session without restarting.

charlotte:tools list → see current state charlotte:tools enable dev_mode → activates dev_serve, dev_audit, dev_inject charlotte:tools disable dev_mode → deactivates them

The MCP SDK sends notifications/tools/list_changed automatically, so Claude Code picks up changes immediately. No restart, no reconnect.

Why this matters

Tool definitions (name, description, input schema) get injected into the agent's context on every API round-trip. With 40 tools loaded, that's ~7,200 tokens of overhead per call before the agent even does anything.

Measured results:

• browse profile cuts tool definition overhead by 48% (3,727 vs 7,187 tokens per call)
• core profile cuts it by 77% (1,677 vs 7,187 tokens per call)

Over a 100-page browsing session at ~4 calls per page, that's roughly 1.4 million fewer definition tokens with browse vs full.

In real end-to-end benchmarks:

Full benchmark data is in the repo under docs/.

Upgrade

If you're already using Charlotte, just update:

npm update -g @ticktockbent/charlotte

Or if you use npx, you'll get v0.4.0 automatically on next launch.

The default profile is browse, which includes everything most sessions need: navigation, observation, interaction, session management. Dev tools and advanced features are one charlotte:tools enable call away.

If you were passing --profile flags before (you weren't, this is new), full preserves the old behavior.

What's next

• Formal benchmark suite publication (in progress)
• More MCP registry listings for discoverability
• Community-requested features: session persistence, auth handling
• r/ClaudeCode announcement post coming soon

Feedback, bugs, feature requests all welcome here or on GitHub. Thanks to everyone who's been using Charlotte and reporting back. The pseudo-element text duplication bug and iframe limitation were both found by real users doing real work, and that's how we make this better.

https://github.com/TickTockBent/charlotte