tt() Function
- Entity ID:
ent-20260409-16f897566296 - Type:
file - Scope:
shared - Status:
active - Aliases: tt function, god function
Description
The tt() function in src/cli/print.ts is the single most complex function in the Claude Code codebase and one of the most complex single functions found in any widely-used open-source TypeScript project. At 3,167 lines with a cyclomatic complexity of 486, it serves as the central orchestrator for the agent's run loop, handling everything from SIGINT signal processing to rate-limit recovery, MCP server lifecycle management, plugin refresh cycles, worktree bridging, and team-lead polling.
Complexity Metrics
| Metric | Value |
|---|---|
| Lines of code | 3,167 |
| Cyclomatic complexity | 486 |
| Maximum nesting depth | 12 levels |
| Inner functions | 21 |
| Parameters | Multiple overloaded signatures |
The 486 cyclomatic complexity means there are 486 independent paths through the function. For context, most static analysis tools flag functions with cyclomatic complexity above 10 as needing refactoring. The 12 nesting levels indicate deeply nested conditional logic -- if inside switch inside try inside while inside if, and so on.
Responsibilities
The tt() function is a "god function" that has accumulated responsibilities over the evolution of the product:
- Agent run loop orchestration -- Drives the core loop that sends messages to the API, processes streaming responses, executes tools, and loops back. This is the heartbeat of queryengine-ts.
- SIGINT handling -- Traps Ctrl+C signals and implements graceful shutdown with a multi-stage escalation (first press cancels current operation, second press forces exit).
- Rate-limit recovery -- Detects HTTP 429 responses and implements exponential backoff with jitter, displaying countdown timers through the terminal-renderer.
- MCP lifecycle -- Manages startup, health checking, and teardown of Model Context Protocol servers connected to the session.
- Plugin refresh -- Periodically checks for plugin updates and hot-reloads changed plugin-system configurations without restarting the session.
- Worktree bridging -- Coordinates with git worktrees when the bridge-system is operating in multi-workspace mode.
- Team-lead polling -- In multi-agent configurations using the teammate-tool, polls for instructions from the lead agent.
The 21 Inner Functions
The function contains 21 inner (nested) function definitions, each handling a specific sub-responsibility. These inner functions close over the outer function's scope, sharing mutable state through closure variables rather than explicit parameter passing. This makes the function difficult to test in isolation and contributes to its high complexity score.
Technical Debt Implications
The tt() function is a canonical example of organic technical debt in a fast-moving startup codebase. Its complexity is a direct consequence of Claude Code's rapid feature development, where new capabilities were added to the existing run loop rather than factored into separate modules. The function works correctly but represents a significant maintenance burden -- any change to the run loop requires understanding the full 3,167-line context and all 486 code paths.
Integration
The tt() function sits at the intersection of nearly every major subsystem: it calls into queryengine-ts for API communication, drives output through the terminal-renderer, respects the permission-pipeline for tool approvals, triggers hooks-system events, and coordinates forked-agent-pattern subagent lifecycles.
Key claims
clm-20260409-a26167429d0d: tt() is the most complex single function with 486 cyclomatic complexity
Relations
- none yet
Sources
src-20260409-4837ecedf1ce