toowl

Documentation

Startup performance

How toowl keeps cold start fast and how we benchmark it.

Launch speed is a first-class metric for toowl. The core terminal loads without spawning plugin subprocesses, without loading every bundled font face, and without blocking on tab restore.

Targets

MetricTarget
Cold start (first frame)<80ms on Apple Silicon
Plugin cost at launch0ms unless Perch opened
Idle RAM<50MB

What stays off the critical path

  • Feathers — Claude, Nest, MCP Hub, Scout hot-start on Perch open or palette invoke
  • Subprocess plugin discovery — background thread after first frame
  • Claude FS watcher — deferred until first Perch open
  • Font loading — only the configured font_family TTF at startup
  • Tab restore — first tab interactive immediately; remaining tabs restore asynchronously

Benchmark locally

bash scripts/bench-startup.sh

Uses hyperfine when installed, otherwise falls back to /usr/bin/time. Compare traces with: 

TOOWL_PERF=1 RUST_LOG=toowl::perf=info cargo run --release

CI gate

The self-hosted runner runs scripts/bench-startup.sh and fails if cold start regresses more than 10% from the pinned baseline in plans/architecture.md.

Profiling

cargo flamegraph --bin toowl

High skipped counts in TOOWL_PERF=1 summaries usually mean a redraw path is not latching; high max_render_us points at GPU work.