Command: tusk exp

Relevant source files

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

• cmd/exp_setup.go
• internal/agent/agent.go
• internal/agent/executor.go
• internal/agent/README.md
• internal/agent/prompts/system.md
• internal/agent/prompts/phase_gather_info_nodejs.md
• internal/agent/prompts/phase_check_compatibility.md
• internal/agent/prompts/phase_summary.md
• internal/agent/prompts/phase_cloud_summary.md

The tusk exp command is a namespace for experimental features that are under development. The primary command within this group is tusk exp setup, which provides an AI-powered wizard to automate the configuration of Tusk Drift for a user's service. This agent-based system analyzes the codebase, instruments the Tusk Drift SDK, creates necessary configuration files, and runs initial tests to ensure a correct setup.

The agent is designed to work with a large language model (specifically, Anthropic's Claude) and requires an API key to function. It interacts with the user's system through a controlled set of tools and can operate in either an interactive TUI mode or a headless "print" mode.

Sources: cmd/exp_setup.go:19-33, internal/agent/agent.go

Architecture

The tusk exp setup command is powered by an AI agent that orchestrates the entire setup process. The architecture is composed of several key components that work together to analyze the project, interact with the user, and modify the system.

Sources: internal/agent/README.md

This diagram illustrates the high-level architecture of the AI agent.

Key Components

Component	Description	Source File
Agent	The main orchestrator. It runs the main loop, manages phases, sends messages to the Claude API, and handles tool calls.	internal/agent/agent.go
PhaseManager	Manages the sequence of setup steps (phases). It controls state transitions and determines the current phase's instructions and available tools.	internal/agent/agent.go:42
ClaudeClient	A client for interacting with the Anthropic Claude API. It sends prompts and receives responses, including tool usage requests.	internal/agent/agent.go:38
ToolExecutor	A registry and dispatcher for all available tools. When the AI model requests to use a tool, the executor validates and runs the corresponding function.	internal/agent/executor.go
AgentUI	An abstraction for the user interface, which can be either an interactive Terminal UI (TUI) or a headless mode that prints to stdout.	internal/agent/agent.go:61
Prompts	A collection of markdown files that provide the system prompt and phase-specific instructions to the AI model.	internal/agent/prompts/

Sources: internal/agent/README.md, internal/agent/agent.go, internal/agent/executor.go

Execution Flow

The agent operates in a loop, progressing through a series of predefined phases until the setup is complete or aborted.

This flowchart shows the execution path from command invocation to completion.

1. Initialization: The runExpSetup function is called. It verifies the Anthropic API key and the working directory.
2. Agent Creation: An agent.Agent instance is created with the specified configuration (model, work directory, permissions, etc.).
3. Run: The agent.Run method starts the UI and launches the main agent logic in a background goroutine.
4. Resumption: The agent checks for a .tusk/PROGRESS.md file. If found, it parses completed phases and state, and skips to the next incomplete phase.
5. Phase Loop: The agent iterates through each phase until all are complete.
   • Prompt Generation: For each phase, a system prompt is combined with phase-specific instructions and the current state.
   • API Call: The prompt is sent to the Claude API.
   • Tool Execution: If the model responds with a tool_use request, the agent's executeToolCalls function is invoked. Some tools may require user permission before execution.
   • State Transition: The loop for a phase continues until the transition_phase tool is called, which advances the PhaseManager to the next phase.
6. Cloud Setup: After local setup is complete, the agent prompts the user to optionally continue with Tusk Drift Cloud configuration, which involves another set of phases.
7. Cleanup: Upon completion, failure, or interruption, cleanup functions are run to stop any background processes.

Sources: cmd/exp_setup.go:35-86, internal/agent/agent.go:160-500

Agent Phases

The setup process is broken down into a series of "phases." Each phase has a specific goal, a set of available tools, and instructions for the AI model. The agent must call the transition_phase tool to mark a phase as complete and move to the next one.

Phase	Purpose	Example Instructions Source
Detect Language	Identify the project's programming language (e.g., Node.js, Python).	internal/agent/README.md
Check Compatibility	Verify that the project's dependencies are supported by the Tusk Drift SDK's instrumentation.	internal/agent/prompts/phase_check_compatibility.md
Gather Project Information	Collect key details like service name, entry point, start command, and port.	internal/agent/prompts/phase_gather_info_nodejs.md
Cloud Setup	A series of phases for connecting to Tusk Drift Cloud, including authentication, repository verification, and service creation.	internal/agent/prompts/phase_cloud_summary.md
Summary	Generate a final report of the setup process and save it to .tusk/SETUP_REPORT.md.	internal/agent/prompts/phase_summary.md

Sources: internal/agent/README.md, internal/agent/executor.go:214-228

Agent Tools

The agent's ability to interact with the local environment is strictly limited to a predefined set of tools. This sandboxed approach ensures that the AI can only perform specific, approved actions. Some high-impact tools require user confirmation by default unless disabled with the --skip-permissions flag.

Sources: internal/agent/executor.go, internal/agent/agent.go:618-654

Key Tools

Tool Name	Description	Requires Confirmation	Source
read_file	Read the contents of a file at a given path.	No	executor.go:102-114
write_file	Write content to a file, creating directories if needed.	Yes	executor.go:115-129
patch_file	Apply a targeted edit to a file by replacing a unique string.	Yes	executor.go:145-161
run_command	Run a one-shot shell command and wait for it to complete.	Yes	executor.go:162-175
start_background_process	Start a long-running process (e.g., a server) in the background.	Yes	executor.go:176-189
ask_user	Ask the user a question and wait for a text response.	No	executor.go:260-271
ask_user_select	Present the user with a list of options to choose from.	No	executor.go:272-299
transition_phase	Complete the current phase and move to the next one.	No	executor.go:317-331
abort_setup	Abort the setup process gracefully if it cannot proceed.	No	executor.go:332-348
cloud_*	A suite of tools for Tusk Cloud integration (e.g., cloud_login, cloud_create_service).	Varies	executor.go:351-507

Sources: internal/agent/executor.go

State Management and Resumption

The agent is designed to be resumable. If the setup process is interrupted, it can continue from where it left off on the next run. This is achieved by saving progress to a .tusk/PROGRESS.md file in the user's project directory.

The progress file tracks:

• Discovered Information: Key-value pairs of project details (e.g., Service Name, Port, Start Command).
• Setup Progress: A checklist of milestones (e.g., SDK installed, Config file created).
• Completed Phases: A list of phases that have been successfully completed.
• Current Phase: The phase that was in progress when the agent was interrupted.

When the agent starts, it reads this file, restores its state, and skips directly to the first incomplete phase. The file is automatically deleted upon successful completion of the entire setup.

Sources: internal/agent/agent.go:170-220, 936-1100

Command-Line Flags

The behavior of the tusk exp setup command can be modified with several flags.

Flag	Description	Default Value
--api-key	Anthropic API key. Can also be set via ANTHROPIC_API_KEY env var.	""
--model	The Claude model to use for the agent.	claude-sonnet-4-20250514
--skip-permissions	Skip all permission prompts for actions like file writes and command execution.	false
--disable-sandbox	Disable the sandbox for running shell commands (macOS/Linux only).	false
--disable-progress-state	Do not save progress to PROGRESS.md or attempt to resume from it.	false
--skip-to-cloud	Skip local setup and go directly to cloud setup. Requires an existing .tusk/config.yaml.	false
--print	Run in headless mode, streaming all output to stdout instead of using the TUI.	false
--output-logs	Write detailed logs of agent activity (tool calls, messages) to a file in .tusk/logs/.	false

Sources: cmd/exp_setup.go:40-52

Conclusion

The tusk exp setup command is an experimental but powerful feature that leverages an AI agent to dramatically simplify the process of integrating Tusk Drift into a new project. By combining a phased approach with a restricted set of tools, it provides a guided and automated onboarding experience. Its ability to analyze code, modify files, and run commands within a controlled framework makes it a significant step towards zero-effort setup for developers.