Performance and Responsiveness

Forge should feel like a local tool even when several agents are active.

Core rules

• Bound all concurrency.
• Bound queues and replay windows.
• Propagate context.Context cancellation.
• Avoid polling when provider protocol or filesystem/process events give a reliable signal.
• Do not keep full raw histories in memory.
• Stream to disk incrementally.
• Prefer bulk database queries over N+1 request loops.

UI rules

• Show cached/current query state immediately, then refresh.
• Virtualize large lists.
• Page activity and log history.
• Coalesce token/tool deltas before React publication.
• Keep expensive diff/markdown work off high-frequency update paths where possible.
• Do not put authoritative domain state in one global Zustand store.
• Measure before introducing complex memoization.

Useful performance scenarios

Eventually benchmark:

• 1 project / 1 active run;
• 20 Tasks / 4 active runs;
• 5,000 activity items with latest 100 rendered;
• reconnect after small gap;
• reconnect after very large gap → snapshot fallback;
• large diff opening/scrolling;
• long-running app with many completed Runs.

Performance bugs in comparable tools show that replay and UI publication strategy can matter more than raw data volume. Build explicit regression fixtures once those paths exist.