Skip to main content
This guide covers everything you need to build and run Default Tamer locally.

​
Prerequisites

Before you begin, ensure you have the following installed:

macOS

macOS 13.0 or later

Xcode

Xcode 14.0 or later

just

Command runner tool

​
Installing just

The project uses just as a command runner. Install it via Homebrew: 
brew install just

​
Getting Started

1

Clone the repository

Clone the repository with submodules:
git clone --recurse-submodules https://github.com/0xdps/default-tamer.git
cd default-tamer
2

Build and run

Use just to build and deploy the app:
just deploy
This performs a fast rebuild and launches the app.
3

Set as default browser

Once the app launches:
  1. Click “Open System Settings” in the first-run window
  2. Go to System Settings → Desktop & Dock → Default web browser
  3. Select Default Tamer

​
Common Commands

The project includes several just commands for development: 
# Fast rebuild + deploy (ideal for UI iteration)
just deploy

# Full clean rebuild from scratch
just fresh

# Stream live app logs
just logs

# Dump current UserDefaults settings
just settings
Run just --list or simply just to see all available commands.

​
Development Workflow

​
Quick Iteration

For rapid UI development: 
just deploy
This command:
  1. Performs an incremental build
  2. Kills any running instance
  3. Launches the new build

​
Clean Rebuild

If you encounter build issues or want a fresh start: 
just fresh
This performs a full clean build and launches the app.

​
Viewing Logs

To monitor app behavior in real-time: 
just logs
This streams live logs from the app, showing:
  • URL routing decisions
  • Source app detection
  • Rule evaluation
  • Browser selection

​
Debugging Settings

To inspect current app settings: 
just settings
This dumps all UserDefaults values for debugging.

​
Testing

​
Manual Testing

Before submitting changes:
  1. Build verification
    • Ensure app builds without warnings
    • Check for Swift compiler errors
  2. Functionality testing
    • Test your specific changes
    • Verify existing features still work
    • Test edge cases
  3. Performance testing
    • Check for memory leaks
    • Verify no crashes
    • Test on supported macOS versions

​
Testing First-Run Experience

To reset the first-run flag: 
just reset
This allows you to test the onboarding experience again.

​
Complete Reset

To wipe all app data and start fresh: 
just reset-all
This deletes all rules, settings, and logs. Use with caution.

​
Troubleshooting

​
Build Fails

If you encounter build errors:
  1. Try a clean rebuild: 
    just fresh
  2. Verify Xcode version: 
    xcodebuild -version
    Should be 14.0 or later.
  3. Check submodules: 
    git submodule update --init --recursive

​
App Won’t Launch

If the app fails to launch:
  1. Check the logs: 
    just logs
  2. Try a complete reset: 
    just reset-all
just deploy

​
Permission Issues

If you encounter permission errors:
  1. Check System Settings → Privacy & Security
  2. Grant necessary permissions to Default Tamer
  3. Restart the app

​
Next Steps

Architecture

Understand the project structure and key components

Contributing

Learn about the contribution process