Skip to main content
Tweaks are PowerShell scripts paired with a meta.json configuration file. Sparkle reads the metadata to display the tweak in the UI and runs the scripts when the user applies or reverts it.

​
Directory structure

Each tweak lives in its own subdirectory under tweaks/: 
tweaks/
└── your-tweak-name/
    ├── meta.json
    ├── apply.ps1
    └── unapply.ps1
If a tweak cannot be reversed, omit unapply.ps1. Sparkle will display an Apply button instead of a toggle in the UI.

​
meta.json schema

Every tweak must include a meta.json file. The table below describes all available fields.
FieldTypeRequiredDescription
namestringYesFolder name of the tweak. Must match the directory name.
titlestringYesText displayed in the UI card.
descriptionstringYesShort description shown on the UI card.
categorystring[]YesOne or more categories used to sort tweaks in the UI.
reversiblebooleanNo (default true)Set to false to show an Apply button instead of a toggle.
modalstringNoText shown in a confirmation modal before the tweak is applied.
recommendedbooleanNoDisplays a recommended icon on the UI card.
topbooleanNoPins the tweak to the top of the list.
warningstringNoDisplays a warning icon; users see the text on hover.
restartbooleanNoShows a message indicating a system restart is required.
deepDescriptionstringNoDetailed description supporting Markdown. Used in documentation.
linksobject[]NoRelated resources. Each object must have name and url string properties.
riskstringNoRisk level: safe, caution, or risky. Shows a corresponding icon in the UI.
addedversionstringNo*Version string when the tweak was first added. Appears in the UI.
updatedversionstringNo*Version string when the tweak was last updated. Appears in the UI.
addedversion is required for all new tweaks. updatedversion is required whenever you update an existing tweak.

​
Risk levels

LevelWhen to use
safeNo meaningful risk to system stability or data.
cautionMay affect system behavior; the user should understand what it does before applying.
riskyCould cause instability or be difficult to reverse; should include a warning and ideally a modal.

​
Categories

Assign one or more of the following categories in the category array:
CategoryDescription
GeneralGeneral-purpose tweaks that don’t fit a specific area.
AppearanceChanges to Windows visual elements and themes.
PerformanceImprovements to system or application performance.
PrivacyTweaks that reduce data collection or tracking.
GamingOptimizations for FPS, game services, or GPU configuration.
NetworkAdjustments to network and connectivity settings.
GPUModifications specific to GPU configuration.

​
Toggle vs. apply-only

If your tweak modifies a setting that can be cleanly reversed, include both apply.ps1 and unapply.ps1. The UI will render a toggle. If the change cannot be reversed — for example, because it deletes files or makes a one-way system change — omit unapply.ps1 entirely. The UI will render an Apply button instead of a toggle. You can also set "reversible": false in meta.json explicitly.

​
Working example: disable telemetry

The following is the real Disable Telemetry tweak from the Sparkle repository.

​
meta.json

{
  "title": "Disable Telemetry",
  "name": "disable-telemetry",
  "risk": "safe",
  "recommended": true,
  "addedversion": "2.14.0",
  "top": true,
  "description": "Disables Windows telemetry and data collection for improved privacy and performance.",
  "deepDescription": "Disables Windows telemetry by modifying registry keys to prevent data collection and reporting to Microsoft. This tweak was previously in Sparkle but was removed due to issues with the tweak not applying correctly. It has been re-added.",
  "category": ["Privacy", "Performance"]
}

​
apply.ps1

# Registry tweaks
$registrySettings = @(
    @{ Path="HKCU:\Software\Microsoft\Windows\CurrentVersion\AdvertisingInfo"; Name="Enabled"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\Windows\CurrentVersion\Privacy"; Name="TailoredExperiencesWithDiagnosticDataEnabled"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\Speech_OneCore\Settings\OnlineSpeechPrivacy"; Name="HasAccepted"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\Input\TIPC"; Name="Enabled"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\InputPersonalization"; Name="RestrictImplicitInkCollection"; Value=1 },
    @{ Path="HKCU:\Software\Microsoft\InputPersonalization"; Name="RestrictImplicitTextCollection"; Value=1 },
    @{ Path="HKCU:\Software\Microsoft\InputPersonalization\TrainedDataStore"; Name="HarvestContacts"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\Personalization\Settings"; Name="AcceptedPrivacyPolicy"; Value=0 },
    @{ Path="HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\DataCollection"; Name="AllowTelemetry"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced"; Name="Start_TrackProgs"; Value=0 },
    @{ Path="HKLM:\SOFTWARE\Policies\Microsoft\Windows\System"; Name="PublishUserActivities"; Value=0 },
    @{ Path="HKCU:\Software\Microsoft\Siuf\Rules"; Name="NumberOfSIUFInPeriod"; Value=0 }
)

foreach ($reg in $registrySettings) {
    New-Item -Path $reg.Path -Force | Out-Null
    Set-ItemProperty -Path $reg.Path -Name $reg.Name -Value $reg.Value -Type DWord
}

# Disable Defender Auto Sample Submission
Set-MpPreference -SubmitSamplesConsent 2

# Disable Connected User Experiences and Telemetry service
Set-Service -Name diagtrack -StartupType Disabled

# Disable Windows Error Reporting Manager service
Set-Service -Name wermgr -StartupType Disabled

# Set SvcHostSplitThresholdInKB to total RAM in KB
$MemoryKB = (Get-CimInstance Win32_PhysicalMemory | Measure-Object Capacity -Sum).Sum / 1KB
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control" -Name "SvcHostSplitThresholdInKB" -Value [int]$MemoryKB

# Remove PeriodInNanoSeconds key if it exists
Remove-ItemProperty -Path "HKCU:\Software\Microsoft\Siuf\Rules" -Name "PeriodInNanoSeconds" -ErrorAction SilentlyContinue

Write-Output "Telemetry settings have been applied."

​
unapply.ps1

# Registry cleanup (removes entries added by apply.ps1)
$registrySettings = @(
    "HKCU:\Software\Microsoft\Windows\CurrentVersion\AdvertisingInfo\Enabled",
    "HKCU:\Software\Microsoft\Windows\CurrentVersion\Privacy\TailoredExperiencesWithDiagnosticDataEnabled",
    "HKCU:\Software\Microsoft\Speech_OneCore\Settings\OnlineSpeechPrivacy\HasAccepted",
    "HKCU:\Software\Microsoft\Input\TIPC\Enabled",
    "HKCU:\Software\Microsoft\InputPersonalization\RestrictImplicitInkCollection",
    "HKCU:\Software\Microsoft\InputPersonalization\RestrictImplicitTextCollection",
    "HKCU:\Software\Microsoft\InputPersonalization\TrainedDataStore\HarvestContacts",
    "HKCU:\Software\Microsoft\Personalization\Settings\AcceptedPrivacyPolicy",
    "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\DataCollection\AllowTelemetry",
    "HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced\Start_TrackProgs",
    "HKLM:\SOFTWARE\Policies\Microsoft\Windows\System\PublishUserActivities",
    "HKCU:\Software\Microsoft\Siuf\Rules\NumberOfSIUFInPeriod"
)

foreach ($reg in $registrySettings) {
    Remove-ItemProperty -Path ($reg -replace '\\[^\\]+$','') -Name ($reg -split '\\')[-1] -ErrorAction SilentlyContinue
}

# Enable Defender Auto Sample Submission
Set-MpPreference -SubmitSamplesConsent 1

# Enable Connected User Experiences and Telemetry service
Set-Service -Name diagtrack -StartupType Automatic

# Enable Windows Error Reporting Manager service
Set-Service -Name wermgr -StartupType Automatic

Write-Output "Telemetry settings have been reverted to default."

​
Submit your tweak

1

Create the tweak directory

Add a new folder under tweaks/ using a descriptive kebab-case name, for example tweaks/disable-cortana/.
2

Write apply.ps1

Implement the changes your tweak makes. Test it on a real Windows machine and verify it produces the expected result.
3

Write unapply.ps1 (if reversible)

Implement the logic that restores the settings to their original state. If the tweak cannot be reversed, skip this file.
4

Write meta.json

Fill in all required fields and any optional fields that apply. Set addedversion to the current Sparkle version.
5

Open a pull request

Fork the repository, commit your new tweak directory, and open a pull request with a clear description of what the tweak does and why it is useful.

Build docs developers (and LLMs) love

Get started for freeTalk to us