[Part 6/6] feat(cli): add activity monitoring hooks and integrate telemetry documentation

[eLyiN]

Summary

Completes the enhanced performance monitoring implementation by adding CLI hooks for activity monitoring and integrating them throughout the CLI application. Includes comprehensive telemetry documentation and full AppContainer integration.

Dependencies

⚠️ This PR depends on:

• [Part 1/6] feat(telemetry): add rate limiter and high-water mark tracker with tests #8110 - Part 1: Telemetry Primitives (RateLimiter, HighWaterMarkTracker)
• [Part 2/6] feat(telemetry): add activity detector with user interaction tracking #8111 - Part 2: Activity Detection (ActivityDetector, isUserActive)
• [Part 3/6] feat(telemetry): enhance metrics with performance monitoring APIs #8113 - Part 3: Metrics Enhancement (performance metrics, recording functions)
• [Part 4/6] feat(telemetry): add memory monitor with activity-aware recording and tests #8122 - Part 4: Memory Monitor (MemoryMonitor, memory tracking APIs)
• [Part 5/6] feat(telemetry): add activity monitor with event-driven snapshots #8124 - Part 5: Activity Monitor (ActivityMonitor, event-driven snapshots)

Review Order: Please review Parts 1-5 first, then this PR.

⚠️ STACKED PR: This PR is based on split/activity-monitor and includes all previous changes. Only review the NEW CLI integration components added in this PR.

Related PRs - Enhanced Performance Monitoring Split

This is Part 6 of 6 in the split implementation of #2127:

• ✅ Part 1/6: [Part 1/6] feat(telemetry): add rate limiter and high-water mark tracker with tests #8110 (telemetry-primitives) - Foundation
• ✅ Part 2/6: [Part 2/6] feat(telemetry): add activity detector with user interaction tracking #8111 (activity-detector) - Activity tracking
• ✅ Part 3/6: [Part 3/6] feat(telemetry): enhance metrics with performance monitoring APIs #8113 (metrics-enhancements) - Performance metrics
• ✅ Part 4/6: [Part 4/6] feat(telemetry): add memory monitor with activity-aware recording and tests #8122 (memory-monitor) - Memory monitoring
• ✅ Part 5/6: [Part 5/6] feat(telemetry): add activity monitor with event-driven snapshots #8124 (activity-monitor) - Event-driven snapshots
• ✅ Part 6/6: [Part 6/6] feat(cli): add activity monitoring hooks and integrate telemetry documentation #8125 (cli-activity-hooks) - YOU ARE HERE 🎯
• 📋 Tracking Issue: [Split PRs] Enhanced Performance Monitoring Implementation - Split into 6 reviewable PRs #8120

Changes in This PR (NEW Components Only)

🆕 CLI Files Added:

• packages/cli/src/ui/hooks/useActivityMonitoring.ts - React hook for activity monitoring (166 lines)
• packages/cli/src/ui/hooks/useActivityMonitoring.test.ts - Comprehensive hook unit tests (235 lines, 14 tests)
• packages/cli/src/ui/hooks/useHistoryManagerWithActivityMonitoring.ts - History management with activity tracking (45 lines)

✏️ CLI Files Modified:

• packages/cli/src/ui/hooks/useHistoryManager.ts - Added callback support (onItemAdded, onItemUpdated, onHistoryCleared, onHistoryLoaded)
• packages/cli/src/ui/hooks/useGeminiStream.ts - Integrated activity recording in stream flows
• packages/cli/src/ui/AppContainer.tsx - Wired up useHistoryWithActivityMonitoring
• packages/cli/src/ui/AppContainer.test.tsx - Updated mocks for new hook

📚 Documentation Added:

• docs/telemetry.md - Complete telemetry system documentation (217 insertions)

CLI Activity Hooks

useActivityMonitoring Hook:

const {
  recordToolCall,
  recordUserInput,
  recordStreamStart,
  recordStreamEnd,
  recordMessageAdded,
  recordHistoryUpdate
} = useActivityRecorder(config);

Features:

• React integration: Seamless integration with CLI React components
• Activity recording: Specific functions for different activity types
• Feature-flagged: Respects isPerformanceMonitoringActive() setting
• Memoized: Optimized to prevent unnecessary re-renders

useHistoryWithActivityMonitoring Hook:

const historyManager = useHistoryWithActivityMonitoring(config);

Enhancements:

• Drop-in replacement for useHistory with zero breaking changes
• Automatic activity tracking on all history operations
• Callback architecture: Extends base useHistory with lifecycle callbacks
• Type-safe: Returns same UseHistoryManagerReturn interface

Stream Integration

Activity Recording in useGeminiStream.ts:

• Tool scheduling: recordToolCall() after slash command tool scheduling
• User messages: recordUserInput() when adding normal user messages
• Stream lifecycle: recordStreamStart() and recordStreamEnd() in submitQuery
• Non-intrusive: No behavior changes, only activity signal emission

AppContainer Integration

Complete Top-Level Integration:

• AppContainer.tsx: Replaced useHistory() with useHistoryWithActivityMonitoring(config)
• Automatic propagation: All history operations now emit activity events
• Feature-gated: Only active when performance monitoring is enabled
• Zero breaking changes: Maintains existing behavior and API

History Manager Enhancements

Callback Support in useHistoryManager.ts:

const historyManager = useHistory({
  onItemAdded: (item) => { /* callback */ },
  onItemUpdated: (item) => { /* callback */ },
  onHistoryCleared: () => { /* callback */ },
  onHistoryLoaded: (items) => { /* callback */ }
});

Benefits:

• Extensibility: Allows hooks to observe history changes
• Decoupled: Activity monitoring doesn't modify core history logic
• Optional: Callbacks are optional, maintaining backward compatibility

Telemetry Documentation

Comprehensive Documentation (docs/telemetry.md):

• Complete system overview: All 6 components and their relationships
• Usage examples: How to use each monitoring component
• Configuration guide: Performance monitoring settings and options
• Integration patterns: Best practices for CLI and UI integration
• Troubleshooting: Common issues and debugging approaches

Testing (NEW Tests Only)

✅ CLI Hook tests:

• useActivityMonitoring.test.ts - 14 tests covering hook behavior, lifecycle, activity recording
• Tests use React Testing Library + vitest for proper hook testing
• Mock-based testing for telemetry core dependencies

✅ Integration validation:

• Tests hook integration with core telemetry components
• Validates activity recording in stream flows
• Ensures no regressions in existing CLI behavior

✅ Build verification:

• CLI builds successfully with new hooks
• Linting passes
• Activity monitoring tests pass (14/14)

Technical Implementation

React Integration Architecture:

1. useActivityMonitoring → Provides React interface to ActivityMonitor (Part 5)
2. useHistoryWithActivityMonitoring → Wraps history with activity emission
3. Stream integration → Records activity during key user interactions
4. AppContainer integration → Wires up monitoring at application root
5. Documentation → Explains entire telemetry system for developers

Zero Breaking Changes:

• All new functionality is opt-in
• Activity monitoring feature-flagged via isPerformanceMonitoringActive()
• Existing CLI behavior unchanged when monitoring is disabled
• Stream activity recording is transparent and non-intrusive
• Documentation provides clear migration path

Benefits

1. Complete CLI integration: Activity monitoring fully wired throughout the application
2. Minimal footprint: Only adds activity signals to existing flows, no behavior changes
3. Developer-friendly: Comprehensive documentation for future maintenance
4. Production-ready: Tested, documented, and ready for gradual rollout
5. Extensible: Hook and callback architecture allows easy addition of more monitoring features
6. Feature-gated: Safe to merge, only activates when explicitly enabled

Addresses Original Issues

Issue #1685 (startup/exit problems):

• Memory monitoring during startup provides diagnostic data
• Activity-aware recording reduces noise in startup telemetry

Issue #1687 (rate limiting + memory issues):

• Complete memory monitoring with intelligent rate limiting
• Activity-driven snapshots prevent memory analysis noise

Performance optimization:

• Data-driven memory optimization capabilities
• Event-contextualized performance metrics
• Baseline comparison and regression detection

---

🎉 COMPLETE IMPLEMENTATION: This completes the enhanced performance monitoring implementation from #2127, providing production-ready monitoring with full CLI integration and comprehensive documentation.

Ready for Production: All components tested, documented, and integrated. Activity monitoring is feature-flagged and safe to activate in CLI workflows.

[jacob314]

Please let me know when this is ready to review. Would be great to start tracking these metrics.

[eLyiN]

Please let me know when this is ready to review. Would be great to start tracking these metrics.

Hi @jacob314 still waiting the pr #8124 , ci failed due some test introduced a few days ago, it should be me ready for review again.

[eLyiN]

/gemini review

[gemini-code-assist]

Code Review

This pull request completes the performance monitoring implementation by adding React hooks for activity monitoring and integrating them into the CLI. The changes include new hooks useActivityMonitoring, useActivityRecorder, and useHistoryWithActivity, updates to useGeminiStream to record user activities, and comprehensive documentation.

My review identifies a few critical issues. The useActivityRecorder hook incorrectly logs all activities as the same type. In useGeminiStream, a generic activity recording function is used instead of the new specific recorders, which prevents detailed activity tracking. Additionally, useHistoryWithActivity doesn't correctly propagate the enableActivityMonitoring flag. These issues should be addressed to ensure the new monitoring system functions as intended.

[eLyiN]

/gemini review

[gemini-code-assist]

Code Review

This pull request completes the performance monitoring implementation by adding React hooks for activity monitoring and integrating them into the CLI. It also includes comprehensive documentation for the new telemetry system.

My review focuses on improving maintainability and type safety in the new hooks.

• I've pointed out that useHistoryWithActivity duplicates logic from useHistory instead of wrapping it, which could lead to maintenance issues.
• I've also suggested strengthening the type safety of the useActivityMonitoring hook to prevent potential bugs with invalid activity types.

The changes in useGeminiStream.ts to record activities at various points seem correct and well-placed. The new tests and documentation are also valuable additions.

[eLyiN]

/gemini review

[gemini-code-assist]

Code Review

This pull request completes the performance monitoring implementation by adding React hooks for activity monitoring and integrating them into the CLI. The changes are well-structured, introducing useActivityMonitoring and useHistoryWithActivity hooks, and correctly instrumenting key user interactions in useGeminiStream. However, there is a critical bug in useHistoryManager where the new callbacks for history changes will never be triggered due to an incorrect pattern for handling side effects with asynchronous state updates. Additionally, a test for useActivityMonitoring is flawed and misleading. My review includes comments to address these critical and high-severity issues.

[eLyiN]

@jacob314, finally, the last PR is ready for review (let me know if you have any requests or thoughts).

[eLyiN]

Heads up. Looks like there are some legitimate test failures. Once the failures are addressed let me know and I will review.

Tests passing, ready for re-review.

[eLyiN]

Hey @jacob314 ! I rebased the branch onto origin/main and resolved the conflicts in useGeminiStream.ts.

The conflicts occurred because main added a runInDevTraceSpan wrapper around submitQuery. I preserved your evolved approach with typed recording functions (recordStreamStart/End) and integrated them with the new tracing wrapper.

FYI: Your branch has evolved significantly from the original PR-6 plan:

• Original: Simple recordUserActivity() calls (~546 LOC)
• Current: Typed functions with useActivityRecorder hook (17 commits)

The evolution is great for code quality (type safety, semantic names), but it's a larger scope than originally planned. Let me know if you want to:

1. Keep this evolved version as-is
2. Simplify back to match original PR-6 scope
3. Split into 2 smaller PRs

The rebase is done and tests should pass. Please review the conflict resolution in useGeminiStream.ts (lines 821-984) to ensure I preserved your intent correctly.

[bdmorgan]

Hi @eLyiN, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[bdmorgan]

Thank you for submission to the Gemini CLI project. At this time, we are closing this pull request in order to allow us to better triage and support more recent pull requests against the latest code changes. If you feel like this pull request is a critical contribution to the Gemini CLI project, please associate the pull request with an existing GitHub issue (instructions here: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) before reopening. After Monday January 26 2026, any pull requests submitted by contributors without an associated issue will be automatically closed (more information here: #16706). If you do choose to reopen and submit this pull request, please ensure you rebase your changes onto the current main branch before resubmitting. This will help avoid merge conflicts and ensure your contribution is compatible with the latest codebase.