AI-Powered Setup Agent

Relevant source files

The following files were used as context for generating this wiki page:

• internal/agent/agent.go
• internal/agent/phases.go
• internal/agent/prompts/system.md
• internal/agent/executor.go
• internal/agent/types.go
• internal/agent/README.md
• internal/agent/tui.go
• internal/agent/ui_headless.go
• internal/agent/prompts/phase_gather_info_nodejs.md
• internal/agent/prompts/phase_summary.md
• internal/agent/prompts/phase_cloud_summary.md

The AI-Powered Setup Agent is a core component of the tusk-drift-cli that orchestrates an automated, AI-driven setup flow for Tusk Drift. It leverages the Claude AI model to guide users through SDK installation, project configuration, and initial testing. The agent interacts with the user's local environment using a predefined set of tools and can operate in either an interactive Terminal User Interface (TUI) or a non-interactive headless mode.

The primary goal of the agent is to abstract away the complexities of setting up Tusk Drift, providing a conversational and intelligent onboarding experience. It systematically analyzes a project, applies necessary code modifications, creates configuration files, and verifies the setup, all while providing real-time feedback to the user.

Sources: internal/agent/README.md, internal/agent/agent.go:80-88

Architecture

The agent's architecture is composed of several key components that work together to execute the setup flow. The Agent is the central orchestrator, managing the main loop, interacting with the Claude API, and dispatching tool executions. The process is broken down into a series of Phases, each with a specific goal, instructions, and a set of available tools.

Sources: internal/agent/README.md

The following diagram illustrates the high-level architecture of the agent:

Key Components

Component	File	Description
Agent	agent.go	The main struct that orchestrates the entire setup process. It manages the phase loop, calls the Claude API, and handles tool execution.
PhaseManager	phases.go	Manages the sequence of setup phases, tracks the current state (State), and handles phase transitions.
ToolExecutor	executor.go	A registry for all available tools. It defines tool schemas and dispatches tool_use requests from the AI to the correct implementation.
State	types.go	A struct that holds all information gathered by the agent during the setup process, such as project type, start command, and port.
ClaudeClient	agent.go	A client for interacting with the Claude API, responsible for sending messages and handling streaming responses.
AgentUI	tui.go, ui_headless.go	An interface for user interaction, with implementations for an interactive TUI (TUIUI) and a non-interactive headless mode (HeadlessUI).
Prompts	prompts/*.md	A collection of Markdown files that provide the system prompt and per-phase instructions to the AI model.

Sources: internal/agent/README.md, internal/agent/agent.go:80-109, internal/agent/phases.go:19-27, internal/agent/executor.go:49-52, internal/agent/types.go:60-113

Execution Flow

The agent operates in a loop for each phase, interacting with the AI model until the phase's objectives are met and the transition_phase tool is called.

Phase Execution Loop

The core logic resides within the runPhase function. The agent repeatedly communicates with the Claude API, executing tools as requested by the model.

This diagram shows the sequence of operations within a single phase:

Timeouts and Retries

To ensure robustness, the agent employs several timeouts and a retry mechanism for API calls.

Timeout	Constant	Default Value	Description
Phase Timeout	PhaseTimeout	15 minutes	Maximum time allowed for a single phase to complete.
API Timeout	APITimeout	5 minutes	Maximum time for a single API call to the Claude model.
Tool Timeout	ToolTimeout	3 minutes	Maximum time for a single tool execution to complete.
Max Iterations	DefaultMaxIterations	50	Default number of loops within a phase before timing out.

API calls are retried up to MaxAPIRetries (3) times with an exponential backoff if a recoverable error occurs.

Sources: internal/agent/agent.go:29-37, internal/agent/agent.go:641-643, internal/agent/agent.go:661-675

State and Configuration

The agent's behavior and memory are managed through two primary structs: Config and State.

Agent Configuration (Config)

The Config struct holds the initial settings for the agent, provided at startup.

Field	Type	Description
APIKey	string	The API key for the Claude service.
Model	string	The specific AI model to use (e.g., Claude Sonnet 4.5).
WorkDir	string	The working directory of the project being configured.
SkipPermissions	bool	If true, skips all user permission prompts for tool execution.
DisableSandbox	bool	If true, disables the fence sandboxing for run_command.
DisableProgress	bool	If true, does not save or read the PROGRESS.md file.
SkipToCloud	bool	If true, skips local setup and proceeds directly to cloud phases.
PrintMode	bool	If true, runs in headless mode without a TUI.
OutputLogs	bool	If true, writes detailed logs to a file in .tusk/logs/.

Sources: internal/agent/types.go:116-128

Agent State (State)

The State struct acts as the agent's memory, accumulating information as it progresses through phases. This state is passed to the AI model as context in each turn.

Field	Type	Description
ProjectType	string	Detected language, e.g., "nodejs", "python".
PackageManager	string	e.g., "npm", "yarn", "pip".
EntryPoint	string	The main entry file for the service, e.g., "src/server.ts".
StartCommand	string	The command to start the service, e.g., "npm run start".
Port	string	The port the service runs on.
HealthEndpoint	string	A health check endpoint, e.g., "/health".
DockerType	string	"none", "dockerfile", or "compose".
CompatibilityWarnings	[]string	List of incompatible dependencies found.
SDKInstalled	bool	Flag indicating if the SDK has been installed.
SDKInstrumented	bool	Flag indicating if the SDK has been initialized in the code.
ConfigCreated	bool	Flag indicating if .tusk/config.yaml has been created.
IsAuthenticated	bool	Flag for Tusk Cloud authentication status.
CloudServiceID	string	The ID of the service created in Tusk Cloud.

Sources: internal/agent/types.go:60-113

Phases

The setup process is divided into a series of sequential phases. The PhaseManager controls the flow from one phase to the next. A phase is only complete when the AI model successfully calls the transition_phase tool.

This diagram shows the standard sequence of local and cloud setup phases.

Each phase is defined by a Phase struct, which includes its instructions, available tools, and other metadata.

Sources: internal/agent/phases.go:9-17

Tools

Tools are functions the AI can request to execute to interact with the file system, run commands, or ask the user for input. The executor.go file defines the schema for each tool and maps tool names to their Go implementations.

Key Tools

Tool Name	Description	Requires Confirmation
read_file	Reads the content of a file.	No
write_file	Writes content to a file, creating it if necessary.	Yes
patch_file	Applies a targeted search-and-replace edit to a file.	Yes
run_command	Runs a one-shot shell command and waits for it to complete.	Yes
start_background_process	Starts a long-running process like a web server.	Yes
ask_user	Asks the user a question and returns their text response.	No
ask_user_select	Presents the user with a list of options to choose from.	No
tusk_run	Executes tusk run to replay recorded traces and test the service.	Yes
transition_phase	Crucial: Completes the current phase and moves to the next.	No
abort_setup	Gracefully aborts the setup process with a clear reason.	No

Sources: internal/agent/executor.go:10-40, internal/agent/executor.go:110-482

Permission Model

To prevent unintended changes, tools that modify the system (e.g., write_file, run_command) require user confirmation by default. The user is prompted to approve, deny, or approve all future actions. This behavior can be disabled with the --skip-permissions flag.

Sources: internal/agent/agent.go:782-823

User Interface

The agent supports two distinct user interface modes, selectable via the printMode configuration flag.

Sources: internal/agent/agent.go:137-141

Interactive TUI

The default mode is a rich Terminal User Interface (TUI) built with bubbletea. It provides:

• A main viewport for logs and AI messages.
• An info panel displaying discovered project details.
• A progress bar showing overall phase completion.
• An interactive command line for user input, selections, and permissions.
• Real-time indicators for when the agent is "thinking" or executing a tool.

Sources: internal/agent/tui.go, internal/agent/ui_tui.go

Headless Mode

When printMode is enabled, the agent runs in a non-interactive headless mode.

• All output is streamed directly to stdout.
• User prompts (ask_user, permissions) are handled via standard input.
• This mode is suitable for CI/CD environments or for users who prefer a simpler, log-style output.

Sources: internal/agent/ui_headless.go

Progress and Recovery

The agent is designed to be resumable. If the setup process is interrupted (e.g., by Ctrl+C or an error), it saves its progress to a .tusk/PROGRESS.md file.

When the agent is run again, it checks for this file and performs the following actions:

1. Reads the file to determine which phases were already completed.
2. Restores the discovered project information (State) from the file.
3. Skips all completed phases and resumes at the first incomplete one.

This ensures that users do not have to restart the entire setup process from scratch if an interruption occurs. The PROGRESS.md file is automatically deleted upon successful completion of the entire setup.

Sources: internal/agent/agent.go:249-301, internal/agent/agent.go:1074-1244