Codebase Overview
Relevant source files
The following files were used as context for generating this wiki page:
The tusk-drift-cli is the command-line interface for Tusk Drift, an API test record-and-replay system. The CLI is responsible for orchestrating local and CI test runs, initializing project configurations, and interacting with the Tusk Drift Cloud service. It is built in Go and utilizes libraries like Cobra for command management and Bubble Tea for its interactive Terminal UI (TUI).
A key feature is an AI-powered setup agent that uses an LLM (Claude) to guide users through installation, configuration, and testing. The CLI also includes traditional TUI-based wizards for local and cloud setup. For more details on specific features, refer to the Configuration and Architecture documentation.
Sources: README.md:4-5, CONTRIBUTING.md:40-47, internal/agent/README.md:3
Project Structure
The repository is organized into several key directories that separate concerns like command definitions, internal logic, and documentation.
| Directory | Description |
|---|---|
cmd/ | Contains the Cobra command definitions. Each file corresponds to a CLI command (e.g., run, init). |
internal/ | Houses the core application logic, including the AI agent, API clients, configuration management, test runner, and TUI components. |
internal/agent/ | Implements the AI-powered setup agent, including phase management, tool execution, and prompts. |
internal/tui/ | Contains the Bubble Tea-based interactive TUI for test runs and onboarding wizards. |
docs/ | Contains markdown documentation for architecture, configuration, and other topics. |
scripts/ | Includes helper scripts, notably the release.sh script for automating releases. |
Sources: CONTRIBUTING.md:40-47, internal/agent/README.md:19-27
Command-Line Interface
The CLI is built using the Cobra library. The entry point is main.go, which executes the root command defined in cmd/root.go.
Key Commands
| Command | Description | Source File |
|---|---|---|
tusk init | Starts an onboarding wizard to create a local .tusk/config.yaml file. | README.md:112-115 |
tusk cloud-init | Starts an onboarding wizard to configure the project for Tusk Drift Cloud. | README.md:139-142 |
tusk exp init | (Experimental) Starts the AI-powered setup agent. | internal/agent/agent.go:199 |
tusk run | Replays recorded traces against the service. Can run in an interactive TUI or headless mode. | README.md:119-127 |
tusk list | Lists available traces, either locally or from Tusk Drift Cloud. | README.md:146-151 |
Sources: README.md:112-159, cmd/root.go
Onboarding Wizards
The CLI provides two distinct TUI-based wizards to guide users through configuration. Both are built using the Bubble Tea framework.
tusk init: Local Setup Wizard
This wizard configures Tusk Drift for local use. It guides the user through a series of steps to generate a .tusk/config.yaml file.
The wizard's architecture is based on a Step interface. Each step in the flow implements this interface, defining its question, validation logic, and how to apply its result to the central state model.
This diagram shows the flow of steps in the local setup wizard.
Wizard Steps:
| Step | Purpose |
|---|---|
ValidateRepoStep | Checks if the current directory is a supported project type (e.g., Node.js). |
IntroStep | Welcomes the user and explains the process. |
SDKCompatibilityStep | Asks the user to confirm compatibility with instrumented SDK packages. |
DockerSetupStep | Asks if the service will run with Docker. |
DockerTypeStep | If using Docker, determines whether it's Docker Compose or a Dockerfile. |
ServiceNameStep | Collects the service name. |
ServicePortStep | Collects the port the service runs on. |
StartCommandStep | Collects the command to start the service. |
StopCommandStep | (Docker only) Collects the command to stop the service. |
ReadinessCommandStep | Collects the command to check if the service is ready. |
ConfirmStep | Shows a preview of the generated YAML and asks for confirmation. |
DoneStep | Confirms the file has been saved and shows next steps. |
Sources: internal/tui/onboard/README.md:5-15, internal/tui/onboard/steps.go:4-13
tusk cloud-init: Cloud Setup Wizard
This wizard connects the local project to Tusk Drift Cloud. It handles repository detection, service registration, API key creation, and recording configuration.
This diagram shows the flow of steps in the cloud setup wizard.
Wizard Steps:
| Step | Purpose |
|---|---|
ValidateConfigStep | Ensures a local .tusk/config.yaml already exists. |
VerifyGitRepoStep | Detects the Git repository from the current directory. |
SelectRemoteStep | If multiple Git remotes exist, asks the user to choose one. |
SelectClientStep | Asks the user to select their Tusk organization if they belong to more than one. |
VerifyRepoAccessStep | Checks if the Tusk GitHub/GitLab app has access to the repository. |
CreateObservableServiceStep | Registers the service in Tusk Cloud. |
CreateApiKeyStep | Creates a new API key for CI/CD authentication. |
RecordingConfigStep | Configures cloud recording parameters like sampling rate. |
ReviewStep | Displays a summary of all configured settings. |
DoneStep | Confirms completion and provides next steps for CI/CD integration. |
Sources: internal/tui/onboard-cloud/steps.go:417-431, internal/tui/onboard-cloud/save_test.go
AI-Powered Setup Agent
The tusk exp init command launches an experimental AI agent that automates the setup process. It uses the Claude API to understand the user's codebase, execute tools, and generate the necessary configuration.
Sources: internal/agent/README.md:3-4
Agent Architecture
The agent is composed of several key components that work together to execute the setup flow.
This diagram illustrates the architecture of the AI agent.
- Agent (
agent.go): The main orchestrator. It runs the phase loop, sends messages to the Claude API, and handles tool calls returned by the model. - PhaseManager (
phases.go): Manages the state and transitions between different stages of the setup process (e.g., "Detect Language", "Gather Project Info"). - ClaudeClient (
api.go): A client for interacting with the Claude API. - ToolExecutor (
executor.go): A registry and dispatcher for all available tools the AI can use, such asread_fileorrun_command. - 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:5-17, internal/agent/agent.go:82-103
Agent Phases
The setup process is broken down into a series of phases. The PhaseManager advances through this list, providing the AI with instructions for the current phase.
| Phase | Description | Required |
|---|---|---|
Detect Language | Identify the project's language/runtime (e.g., Node.js, Python). | Yes |
Check Compatibility | Verify project dependencies are compatible with the Tusk Drift SDK. | Yes |
Gather Project Info | Collect details like entry point, start command, and port. | Yes |
Confirm App Starts | Verify the service can start successfully without the SDK. | Yes |
Instrument SDK | Install the SDK and add initialization code to the entry point. | Yes |
Create Config | Create the .tusk/config.yaml file with the gathered information. | Yes |
Simple Test | Record and replay a simple health check endpoint to verify the setup. | Yes |
Complex Test | (Optional) Test an endpoint that makes external calls. | No |
Summary | Generate a final report of the setup process. | Yes |
After the local setup, the agent can proceed to cloud-specific phases like Cloud Auth, Create Service, and Create API Key.
Sources: internal/agent/phases.go:303-380, internal/agent/phases.go:478-571
Agent Tools
The AI can invoke a predefined set of tools to interact with the user's system. Each tool has a specific function and a JSON schema for its inputs. The executor.go file defines these tools and maps them to their Go implementations.
| Tool Name | Description | Requires Confirmation |
|---|---|---|
read_file | Read the contents of a file. | No |
write_file | Write content to a file, creating it if it doesn't exist. | Yes |
patch_file | Apply a targeted search-and-replace edit to a file. | Yes |
run_command | Run a one-shot shell command and wait for it to complete (e.g., npm install). | Yes |
start_background_process | Start a long-running process like a web server. | Yes |
stop_background_process | Stop a background process. | No |
http_request | Make an HTTP request to test an endpoint. | Yes |
ask_user | Ask the user a question and wait for a free-text response. | No |
ask_user_select | Present the user with a list of options to choose from. | No |
tusk_run | Run tusk run to replay recorded traces. | Yes |
transition_phase | Complete the current phase and move to the next one. | No |
abort_setup | Gracefully abort the setup if the project is unsupported. | No |
Sources: internal/agent/executor.go:13-52, internal/agent/executor.go:113-340
Release Process
Releases are automated using GoReleaser and GitHub Actions. A maintainer can create a new release by running the scripts/release.sh script.
# Create a patch release (e.g., v1.0.0 → v1.0.1)
./scripts/release.sh patch
# Create a minor release (e.g., v1.0.0 → v1.1.0)
./scripts/release.sh minor
The script performs preflight checks (e.g., clean working directory, tests pass), calculates the next version, and pushes a new Git tag. Pushing the tag triggers a GitHub Action that builds binaries for Linux, macOS, and Windows (amd64, arm64), creates a GitHub release, and uploads the artifacts.
Sources: scripts/release.sh, CONTRIBUTING.md:131-147