Dereference Documentation

System Requirements

• macOS 10.15 (Catalina) or later
• Apple Silicon (M1/M2/M3) or Intel processor
• 4GB RAM minimum (8GB recommended)
• 500MB available disk space

Download and Install

1. Visit the download page
2. Download the Universal DMG file (works on both Intel and Apple Silicon Macs)
3. Open the downloaded DMG file
4. Drag the Dereference app to your Applications folder
5. Eject the DMG

First Launch on macOS

On first launch, macOS may show a security warning. This is normal for apps downloaded outside the App Store.

1. Right-click (or Control-click) on the Dereference app
2. Select "Open" from the context menu
3. Click "Open" in the dialog that appears
4. The app will now launch and be trusted for future use

When you first launch Dereference, you'll be greeted with a welcome screen that guides you through the initial setup.

Initial Setup Steps

1. Choose your default Claude model (Claude 3 Opus, Sonnet, or Haiku)
2. Select your preferred theme (Light or Dark)
3. Configure Claude Code CLI path (auto-detected if installed)
4. Sign in with your Claude account

All settings can be changed later in the Settings page (Cmd+,).

Dereference uses OAuth authentication to securely connect to your Claude account.

Sign In Process

1. Click "Sign in with Claude" on the welcome screen or in Settings
2. Your default browser will open to the Claude authentication page
3. Enter your Claude credentials and authorize Dereference
4. You'll be redirected back to Dereference automatically

Your authentication tokens are stored securely in your system keychain and never transmitted to our servers.

Dereference provides a graphical interface for Claude Code, making it easier to work with AI-assisted development.

Key Features

• Real-time streaming of Claude responses
• Syntax highlighting for code blocks
• File reference with @ mentions
• Image paste and drag-drop support
• Session history and context preservation

Using Claude Code

1. Open a project or create a new session
2. Type your question or request in the input field
3. Use @ to reference specific files
4. Press Enter to send (Shift+Enter for new line)
5. Claude will respond with code suggestions and explanations

Organize your development work with Dereference's project management features.

Opening Projects

• Click "Open Project" or use Cmd+O
• Select a folder containing your code
• The project will open with file explorer on the left
• Recent projects appear in the command palette (Cmd+K)

Project Features

• File tree with real-time updates
• Quick file search with fuzzy matching
• Git integration showing file status
• Multiple projects can be opened in different sessions

Sessions allow you to maintain separate conversations with Claude for different tasks or projects.

Session Features

• Create new sessions with Cmd+N
• Switch between sessions using the session manager (Cmd+Shift+E)
• Rename sessions with Ctrl+L
• Search through session history
• Sessions auto-save and persist between app launches

Session Organization

Sessions are automatically organized by project and include timestamps. You can rename sessions to better describe their purpose.

The built-in file explorer provides quick access to your project files.

Features

• Toggle with Cmd+B
• Real-time file watching for external changes
• File icons based on file type
• Collapsible folders
• Right-click context menu for file operations

File References

Reference files in your messages by typing @ followed by the file path. Autocomplete helps you find files quickly.

Essential Shortcuts

The command palette (Cmd+K) provides quick access to all app features and recent items.

Available Commands

• Search and open recent projects
• Switch between sessions
• Access settings and preferences
• Create new sessions or projects
• Run app commands

Type to filter commands, use arrow keys to navigate, and Enter to select.

Dereference automatically checks for updates and notifies you when a new version is available.

Update Process

1. When an update is available, a notification appears
2. Click "Download Update" to begin
3. The update downloads in the background
4. Click "Restart and Update" when ready
5. Dereference will restart with the new version

You can also manually check for updates in Settings > Application Updates.

Common Issues

Claude Code not found

If Dereference can't find Claude Code CLI:

1. Install Claude Code CLI from claude.ai/code
2. Ensure it's in your PATH
3. Manually set the path in Settings > Claude Configuration

Authentication issues

If authentication fails:

1. Check your internet connection
2. Clear app data in Settings > Advanced
3. Try signing in again

Performance issues

For slow performance:

1. Close unused sessions
2. Clear session history in Settings
3. Restart the application

Getting Help

If you continue to experience issues:

• Check the GitHub issues
• Join our Discord community
• Email support at support@dereference.dev