First Steps

Add Scan Directories

Astrolabe discovers projects by scanning directories on your system. Start by adding the folders where you keep your projects.

1. Click Settings in the sidebar (⚙️ icon)
2. Navigate to the Scanner tab
3. Click Add Directory
4. Select a folder containing your projects (e.g., ~/projects, ~/code, ~/dev)

Recommended Directories:

• ~/projects - Personal projects
• ~/work - Work-related projects
• ~/code - General code folder
• ~/Desktop - Projects on desktop (if applicable)

Advanced Options:

• Recursive Scanning: Enable to scan subdirectories
• Max Depth: How many levels deep to scan (default: 3)
• Exclude Patterns: Skip directories like node_modules, .git, target

Run Your First Scan

Once you've added directories, it's time to discover your projects!

1. Click the Scan button in Settings → Scanner
2. Wait while Astrolabe discovers your projects (this may take 1-5 minutes depending on the number of directories)
3. Watch the progress indicator as projects are detected

What Astrolabe Detects:

• Languages: JavaScript/TypeScript, Rust, Python, Go, Java, Ruby, PHP, etc.
• Frameworks: Next.js, React, Vue, Svelte, Tauri, Django, Laravel, and more
• Package Managers: npm, pnpm, yarn, bun, cargo, pip, go mod, etc.
• Git Status: Branch, commit info, clean/dirty status

Explore Your Projects

After scanning completes, you'll see all discovered projects in the main view.

View Modes

Switch between different views based on your preference:

• Grid View - Visual cards with project info
• List View - Compact list format
• Table View - Detailed table with sortable columns

Filter Projects

Use the filters to narrow down what you see:

• Search - Fuzzy search by project name (Cmd/Ctrl+F)
• Language - Filter by programming language
• Framework - Filter by framework
• Git Status - Show only dirty/clean repos
• Folder - View projects in specific folders

Quick Actions

Click any project card to see quick actions:

• Open in Editor - Launch in VS Code (configurable)
• Open in Finder/Explorer - View project files
• View Details - See full project information
• Terminal - Open terminal in project directory

Organize with Folders

Keep your projects organized by creating folders and moving projects into them.

Create a Folder

1. Click the + button in the sidebar under "Folders"
2. Enter a name (e.g., "Work Projects", "Personal", "Archived")
3. (Optional) Choose a color for the folder

Move Projects

Drag and drop projects from the main view into folders in the sidebar.

Or use bulk operations:

1. Select multiple projects (hold Cmd/Ctrl and click)
2. Click Move to Folder in the top toolbar
3. Choose the destination folder

Add Tags (Optional)

Tags provide flexible categorization across folders. Create tags for:

• Project types (frontend, backend, fullstack)
• Technologies (react, rust, python)
• Status (active, archived, experimental)
• Clients or teams

Create a Tag

1. Go to Settings → Tags
2. Click New Tag
3. Enter a name and choose a color
4. Save the tag

Assign Tags

1. Open a project detail view
2. Click Add Tag
3. Select from your existing tags

Configure Quick Access

Set up your preferred editor and shell for quick access.

1. Go to Settings → General
2. Default Editor: Choose VS Code, VS Code Insiders, Cursor, or custom
3. Default Shell: Select zsh, bash, fish, or custom
4. Terminal Theme: Choose from available Ghostty themes