Configuration

Customize Astrolabe to fit your development workflow.

General Settings

Access settings by clicking the ⚙️ icon in the sidebar, or press Cmd+, (Ctrl+, on Windows/Linux).

Default Editor

Choose which code editor opens when you click "Open in Editor":

Supported Editors:

• VS Code
• VS Code Insiders
• Cursor
• Custom (provide path to executable)

Example custom editor paths:

/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl
/Applications/WebStorm.app/Contents/MacOS/webstorm

C:\Program Files\Sublime Text\sublime_text.exe
C:\Program Files\JetBrains\WebStorm\bin\webstorm64.exe

/usr/bin/subl
/opt/sublime_text/sublime_text
/usr/local/bin/code

Default Shell

Select the shell used in the embedded terminal:

• zsh (macOS/Linux default)
• bash
• fish
• PowerShell (Windows)
• cmd (Windows)
• Custom (provide path)

Scanner Settings

Configure how Astrolabe discovers projects.

Scan Directories

Add, edit, or remove directories to scan:

1. Click Add Directory
2. Select a folder
3. Configure options:
   • Recursive: Scan subdirectories
   • Max Depth: How many levels deep (1-10)
   • Exclude Patterns: Comma-separated patterns

Recommended Exclusions:

node_modules, .git, target, dist, build, .next, venv, __pycache__

Scan Frequency

Manual Scanning (default):

• Click "Scan" button to discover projects
• Useful for large directories or infrequent changes

Auto-Scan on Startup (optional):

• Enable in Settings → Scanner
• Automatically scans when Astrolabe launches
• Can slow startup for large scan lists

Terminal Settings

Customize the embedded terminal experience.

Theme

Choose from Ghostty themes or create your own:

Built-in themes:

• Dracula
• Monokai
• Solarized Dark/Light
• Nord
• One Dark
• GitHub Dark/Light

Font

Configure terminal font:

# macOS
~/.config/ghostty/config

# Windows
%APPDATA%\ghostty\config

# Linux
~/.config/ghostty/config

Example configuration:

font-family = "JetBrains Mono"
font-size = 14

theme = "dracula"

cursor-style = "block"
cursor-style-blink = true

window-padding-x = 10
window-padding-y = 10

Hotkey

Toggle terminal visibility with a keyboard shortcut:

• Default: Cmd+` (macOS) or Ctrl+` (Windows/Linux)
• Customizable in Settings → Keyboard Shortcuts

Appearance

View Mode

Choose default project view:

• Grid - Visual cards with project previews
• List - Compact list format
• Table - Detailed table view

Sidebar Width

Adjust sidebar width by dragging the resize handle.

Theme

System (default): Follows OS dark/light mode Dark: Always use dark theme Light: Always use light theme

Organization

Auto-Organization Rules

Enable or disable automatic organization:

When enabled:

• New projects automatically sorted into folders based on rules
• Rules evaluated on every scan
• Manual organization still possible

When disabled:

• All organization is manual
• Rules remain saved but inactive

Tag Colors

Customize tag color palette in Settings → Tags. Choose from 20+ colors.

Integrations

API Tokens

Configure platform integrations securely:

1. Go to Settings → Integrations
2. Select a platform (Vercel, GitHub, etc.)
3. Click "Add Token"
4. Enter your API token
5. Click "Verify" to test connection

Token Security:

• Stored in OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Encrypted at rest
• Never logged or transmitted except to platform APIs

Connection Status

See connection status for each platform:

• 🟢 Connected - Token valid, API accessible
• 🟡 Warning - Token valid but API issues
• 🔴 Disconnected - Token invalid or missing

Keyboard Shortcuts

View and customize keyboard shortcuts in Settings → Keyboard.

Default shortcuts:

Advanced Settings

Database Location

View or change database location (requires restart):

Default locations:

• macOS: ~/Library/Application Support/com.astrolabe.app/
• Windows: %APPDATA%\com.astrolabe.app\
• Linux: ~/.local/share/com.astrolabe.app/

Reset Settings

Reset all settings to defaults:

1. Settings → Advanced
2. Click "Reset All Settings"
3. Confirm the action

Export/Import Configuration

Export:

1. Settings → Advanced → Export Configuration
2. Save JSON file

Import:

1. Settings → Advanced → Import Configuration
2. Select JSON file
3. Restart Astrolabe

Troubleshooting Configuration

Settings not saving:

• Check file permissions for config directory
• Ensure sufficient disk space
• Restart Astrolabe

Terminal not working:

• Verify shell path is correct
• Check shell is installed: which zsh or which bash
• Try default shell first

Editor not opening:

• Verify editor path in settings
• Test path in terminal: /path/to/editor --version
• Use absolute paths, not relative

Need more help? See the Troubleshooting Guide.