bootstrap

Documentation

Overview

Package bootstrap initializes and wires up all application components, then hands control to the cobra root command.

Initialization order (mirrors TS src/entrypoints/init.ts):

Phase 0  Fast-path detection (--version, etc.)
Phase 1  Config system init (settings.json merge, env-var overrides)
Phase 2  Runtime safety / network (graceful-shutdown, proxy)
Phase 3  Auth pre-warm (OAuth token check/refresh)
Phase 4  Feature/policy loading
Phase 5  Data migrations
Phase 6  Service layer init (deferred until first REPL render)

Index

• func Execute() error
• func HandleFastPath(args []string) bool
• func RegisterBuiltinTools(reg *tools.Registry)
• func Run(args []string) error
• func RunHeadless(container *AppContainer, prompt string, outputFormat string, maxTurns int) error
• type AppContainer
  • func BuildContainer(opts ContainerOptions) (*AppContainer, error)
  • func BuildContainerWithClient(opts ContainerOptions, client api.Client) (*AppContainer, error)
  • func BuildHeadlessContainer(opts ContainerOptions) (*AppContainer, error)
• type ContainerOptions

Functions

func Execute

func Execute() error

Execute is kept for backward-compatibility (called by older stubs).

func HandleFastPath

func HandleFastPath(args []string) bool

HandleFastPath inspects raw os.Args and handles zero-dependency flags (--version, -v) before cobra is initialised. Returns true if the process should exit immediately (clean exit).

func RegisterBuiltinTools

func RegisterBuiltinTools(reg *tools.Registry)

RegisterBuiltinTools registers all built-in tool singletons into reg. Order follows the canonical tool ordering in the TS implementation.

func Run

func Run(args []string) error

Run is the main entry point called from cmd/claude/main.go. It builds the cobra command tree and executes it.

func RunHeadless

func RunHeadless(container *AppContainer, prompt string, outputFormat string, maxTurns int) error

RunHeadless executes a single headless query using a pre-built container. outputFormat must be one of: "text", "json", "stream-json". maxTurns controls the maximum number of agentic turns; 0 means unlimited. This is the testable entry point for the CLI headless path.

Types

type AppContainer

type AppContainer struct {
	// QueryEngine drives all LLM interactions.
	QueryEngine engine.QueryEngine
	// AppStateStore holds the global reactive application state.
	AppStateStore *state.AppStateStore
	// ToolRegistry holds all registered tools.
	ToolRegistry *tools.Registry
	// MCPPool manages MCP server connections.
	MCPPool *mcp.Pool
	// Settings is the merged layered config.
	Settings *config.LayeredSettings
	// PermAskCh receives permission requests from the engine (for TUI to consume).
	PermAskCh <-chan permissions.AskRequest
	// PermRespCh is used by TUI to send permission responses back to the engine.
	PermRespCh chan<- permissions.AskResponse
	// Coordinator manages multi-agent lifecycle and message routing.
	Coordinator coordinator.Coordinator
	// AgentCoordinator is the tools-facing adapter for the coordinator.
	AgentCoordinator tools.AgentCoordinator
	// AgentEventCh receives sub-agent progress and status events for TUI display.
	AgentEventCh <-chan coordinator.Event
	// MsgQueue is the unified command queue for mid-session message processing.
	MsgQueue *msgqueue.MessageQueue
	// QueryGuard is the query dispatch guard (three-state machine).
	QueryGuard *msgqueue.QueryGuard
	// AgentProfiles holds all registered agent type profiles (built-in + custom).
	AgentProfiles *agenttype.Registry
}

AppContainer holds all wired application dependencies. It is the single object threaded through the run functions.

func BuildContainer

func BuildContainer(opts ContainerOptions) (*AppContainer, error)

BuildContainer wires up the full application container used in interactive mode.

Initialization order:

1. Config loading (layered settings merge)
2. OAuth token pre-warm
3. API client construction
4. Tool registry setup
5. Permission checker setup (HIL support)
6. Engine construction
7. App state store construction

func BuildContainerWithClient

func BuildContainerWithClient(opts ContainerOptions, client api.Client) (*AppContainer, error)

BuildContainerWithClient wires up an AppContainer using the provided api.Client. This bypasses OAuth and API key resolution, making it suitable for tests that inject a mock client.

func BuildHeadlessContainer

func BuildHeadlessContainer(opts ContainerOptions) (*AppContainer, error)

BuildHeadlessContainer wires up a minimal container for non-interactive (-p) mode. No MCP connections are pre-established; OAuth pre-warm is still performed.

type ContainerOptions

type ContainerOptions struct {
	HomeDir       string
	WorkingDir    string
	ModelOverride string
	Verbose       bool
	Debug         bool
	DebugFile     string // File path for debug log output (empty = stderr when Debug is true)
}

ContainerOptions is the minimal set of startup parameters fed into BuildContainer. It is populated by runInteractiveOrHeadless before dispatching.