# Behavior traces — google-gemini/gemini-cli

> Canonical page: https://codevetter.com/unpack/gemini-cli/behavior-traces

# Behavior traces — google-gemini/gemini-cli

Scanned commit d5b3e3accb26000d273abf16e0f1dd83aa5428a9 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Traced three flows end-to-end. (1) Startup: parent spawn → settings → args → session resolution → partial config → auth → optional sandbox relaunch → full config init → interactive Ink UI or headless loop. (2) Headless agentic turn: input normalization → hooks → GeminiClient stream → Turn/GeminiChat → tool requests → Scheduler (policy→confirm→hooks→execute) → responses fed back until Finished. (3) Session persistence/resume: JSONL transcript written per message/tool call and rehydrated via SessionSelector or imported from file.
- Startup trace (parent): `gemini` bin → packages/cli/index.ts run() → getMemoryNodeArgs() reads ~/.gemini/settings.json for advanced.autoConfigureMemory → getSpawnConfig() → spawn child node with same args + IPC channel → forward admin-settings → on child close, exit with code unless code === RELAUNCH_EXIT_CODE, then respawn. — [packages/cli/index.ts#L20-116](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/index.ts#L20-L116) [packages/cli/src/utils/processUtils.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/processUtils.ts) [packages/cli/src/utils/relaunch.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/relaunch.ts)
- Startup trace (child): gemini.tsx main() → setupAdminControlsListener → patchStdio → setupUnhandledRejectionHandler/setupSignalHandlers → SlashCommandConflictHandler.start → loadSettings → optional setupWorktree → parseArguments → resolveSessionId → ConsolePatcher.patch → loadCliConfig (partial, skipExtensions) → validateAuthMethod/validateNonInteractiveAuth → partialConfig.refreshAuth → remote admin settings propagation. — [packages/cli/src/gemini.tsx#L466-682](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L466-L682) [packages/cli/src/config/auth.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/config/auth.ts) [packages/cli/src/validateNonInterActiveAuth.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/validateNonInterActiveAuth.ts)
- Startup trace (sandbox hop): if SANDBOX env is unset and not a subcommand, loadSandboxConfig decides; when configured, piped stdin is read and injected into argv as --prompt, then relaunchOnExitCode(start_sandbox(...)) re-executes the CLI inside Docker/Podman/Seatbelt and the outer process exits SUCCESS. — [packages/cli/src/gemini.tsx#L684-737](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L684-L737) [packages/cli/src/utils/sandbox.ts#L55-120](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/sandbox.ts#L55-L120) [packages/cli/src/config/sandboxConfig.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/config/sandboxConfig.ts)
- Startup trace (post-sandbox): full loadCliConfig → config.storage.initialize → createPolicyUpdater(policyEngine, messageBus, storage) → registerCleanup(SessionEnd hook + ConsolePatcher) → flag handlers (--list-extensions/--list-sessions/--delete-session exit early) → setRawMode → setupTerminalAndTheme → initializeApp(config, settings) which auths, connects IdeClient, validates theme, counts GEMINI.md files → startInteractiveUI dynamically imports interactiveCli.js (React/Ink lazy-loaded). — [packages/cli/src/gemini.tsx#L742-922](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L742-L922) [packages/cli/src/core/initializer.ts#L19-50](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/core/initializer.ts#L19-L50) [packages/cli/src/config/policy.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/config/policy.ts) [packages/cli/src/interactiveCli.tsx](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/interactiveCli.tsx)
- Headless turn trace: runNonInteractive → promptIdContext.run → ConsolePatcher + TextOutput + Ctrl+C readline keypress abort → new Scheduler({context: config, messageBus}) → optional geminiClient.resumeChat → handleSlashCommand/handleAtCommand → loop: geminiClient.sendMessageStream(parts, signal, prompt_id) → for-await events → collect ToolCallRequest → scheduler.schedule → completedToolCalls → append responseParts to history → next iteration until no tool calls / Finished / stopped. — [packages/cli/src/nonInteractiveCli.ts#L72-180](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/nonInteractiveCli.ts#L72-L180) [packages/cli/src/nonInteractiveCli.ts#L234-332](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/nonInteractiveCli.ts#L234-L332) [packages/cli/src/nonInteractiveCli.ts#L482-545](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/nonInteractiveCli.ts#L482-L545)
- Model-stream trace inside core: sendMessageStream → fireBeforeAgentHookSafe (may yield AgentExecutionStopped/Blocked or inject <hook_context>) → processTurn loop → Turn.run → chat.sendMessageStream(modelConfigKey, req, prompt_id, signal, role) → retryWithBackoff around apiCall → per-chunk parse: thought parts → Thought events, text → Content, functionCalls → ToolCallRequest, finishReason → Finished(+citations), citations tracked across chunks. — [packages/core/src/core/client.ts#L930-971](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/client.ts#L930-L971) [packages/core/src/core/turn.ts#L270-399](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/turn.ts#L270-L399) [packages/core/src/core/geminiChat.ts#L480-725](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/geminiChat.ts#L480-L725)
- Tool-execution trace inside Scheduler: schedule() enqueues SchedulerQueueItem → SchedulerStateManager tracks call lifecycle (validating → awaiting approval → executing → success/error) → checkPolicy consults PolicyEngine (deny short-circuits) → resolveConfirmation publishes ToolConfirmationRequest on the MessageBus for UI approval → evaluateBeforeToolHook may block/modify → ToolExecutor runs the ToolInvocation → ToolCallEvent telemetry logged → CompletedToolCall resolved. (inferred) — [packages/core/src/scheduler/scheduler.ts#L57-130](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/scheduler.ts#L57-L130) [packages/core/src/scheduler/state-manager.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/state-manager.ts) [packages/core/src/scheduler/policy.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/policy.ts) [packages/core/src/scheduler/confirmation.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/confirmation.ts) [packages/core/src/scheduler/hook-utils.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/hook-utils.ts) [packages/core/src/scheduler/tool-executor.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/tool-executor.ts)
- Shell tool trace: model calls run_shell_command → ShellToolInvocation → command parsing via initializeShellParsers/getCommandRoots/stripShellWrapper/detectCommandSubstitution → policy check on root commands → confirmation showing command+roots → ShellExecutionService.execute prefers node-pty (getPty) with childProcessFallback → streamed ShellOutputEvents, live output buffer trimmed at 100k chars, background commands wrapped with EXIT-trap PID capture. — [packages/core/src/tools/shell.ts#L102-140](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/tools/shell.ts#L102-L140) [packages/core/src/utils/shell-utils.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/utils/shell-utils.ts) [packages/core/src/services/shellExecutionService.ts#L431-475](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/services/shellExecutionService.ts#L431-L475)
- Session resume trace: --resume → SessionSelector(storage).resolveSession picks or lists JSONL transcripts → ResumedSessionData {conversation, filePath} → in headless mode geminiClient.resumeChat(convertSessionToClientHistory(messages)) rehydrates GeminiChat history; --session-file instead imports an external record, filters to user/gemini messages, mints a new sessionId, and writes a fresh session-*.jsonl. — [packages/cli/src/gemini.tsx#L319-444](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L319-L444) [packages/cli/src/nonInteractiveCli.ts#L242-250](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/nonInteractiveCli.ts#L242-L250) [packages/core/src/core/client.ts#L339-343](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/client.ts#L339-L343) [packages/cli/src/utils/sessionUtils.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/sessionUtils.ts)
- AfterAgent continuation trace: when hooks are enabled and no pending tools, fireAfterAgentHookSafe runs; a blocking decision yields AgentExecutionBlocked, decrements hookState.activeCalls, then recursively calls sendMessageStream with the hook's reason as the new request and stopHookActive=true — an internal agentic continuation invisible to the UI loop. — [packages/core/src/core/client.ts#L973-1058](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/client.ts#L973-L1058)
- Interactive UI trace: startInteractiveUI → interactiveCli.js → Ink renders AppContainer (~2900 lines) → useGeminiStream hook drives geminiClient.sendMessageStream and owns Scheduler wiring plus slashCommandProcessor for / commands inside the TUI. — [packages/cli/src/gemini.tsx#L446-464](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L446-L464) [packages/cli/src/ui/AppContainer.tsx](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/ui/AppContainer.tsx) [packages/cli/src/ui/hooks/useGeminiStream.ts#L1773](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/ui/hooks/useGeminiStream.ts#L1773) [packages/cli/src/ui/hooks/slashCommandProcessor.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/ui/hooks/slashCommandProcessor.ts)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)