✅ What is Projectile?

Projectile is a project management system that:

• Automatically detects projects based on version control markers (`.git'), special files (`.projectile'), or manual registration

• Maintains a list of known projects with quick-switch capabilities

• Provides project-scoped file search and text search

• Remembers recently accessed projects

• Integrates with the notebook system for research project organization

• Tracks project metadata including type and last access time

Projects can be:

• Git repositories: Directories containing a .git folder

• Projectile-marked: Directories with a .projectile marker file

• Manual projects: Any directory you explicitly add to the project list

✅ Key Features

• Automatic Detection: Discovers git repos and projectile-marked directories

• Quick Switching: Fast navigation between known projects with C-c p p

• Project History: Shows when each project was last opened

• Batch Scanning: Scan directories to discover multiple projects at once

• File Finding: Project-scoped file search with C-c p f

• Cross-Project File Finding: Find files across all known projects with C-c p F

• Text Search: Search within project files with C-c p s

• Tree View: Sidebar showing all known projects with visual indicators

• Cleanup Tools: Remove non-existent projects from the list

• Notebook Integration: Works seamlessly with scimax-notebook for research projects

• Database Integration: Projects are persisted in the scimax database for reliability

Detection Methods

Scimax uses three methods to detect projects, in this priority order:

1. Git Repositories: Any directory containing a .git/ subdirectory

2. Projectile Markers: Directories with a .projectile file

3. Manual Registration: Projects you explicitly add via commands

Automatic Detection

When you open a workspace folder, Scimax automatically registers it as a project:

# Opening a folder registers it automatically
$ code /home/user/my-project/

# The folder is now in your project list
# Type: git (if it has .git) or manual (otherwise)

✅ Creating a Projectile Marker

To mark a directory as a projectile project, create an empty .projectile file in the root:

# Create marker file
touch .projectile

# Now Scimax recognizes this as a project

The `.projectile' file can be empty or contain patterns for ignoring files (reserved for future use).

✅ Project Types

Projects are classified into three types:

The type is automatically detected when adding a project.

✅ Switching Between Projects

The primary projectile command is Switch Project (C-c p p):

Command: Scimax: Switch Project
Keybinding: C-c p p
Hydra: Projects → p (Switch Project)

This opens a quick pick menu showing:

• Project name

• Full path

• Project type (git, projectile, or manual)

• Last opened time (e.g., "2h ago", "3d ago")

Select a project to choose how to open it:

Example workflow:

1. Press C-c p p
2. Type to filter: "scimax"
3. Select "scimax_vscode"
4. Choose "New Window"
→ Project opens in new VS Code window
→ Last opened time is updated

✅ Adding Projects

Command: Scimax: Add Project
Keybinding: C-c p a
Hydra: Projects → a (Add Project)

1. Press C-c p a
2. Navigate to /home/user/projects/my-app/
3. Select folder
→ "Added project: my-app"
→ Project appears in the list

Command: Scimax: Scan Directory for Projects
Keybinding: (none)
Hydra: Projects → s (Scan for Projects)

Scan directory: /home/user/projects/
Max depth: 2

# Finds and adds:
/home/user/projects/project-a/         (git)
/home/user/projects/project-b/         (git)
/home/user/projects/work/client-site/  (git)
/home/user/projects/notes/journal/     (projectile)

Result: "Found 4 projects"

✅ Removing Projects

Remove projects from the list with Scimax: Remove Project:

Command: Scimax: Remove Project
Keybinding: (none)
Hydra: Projects → r (Remove Project)

Notes:

• This removes the project from the known projects list only

• It does not delete any files from disk

• The project can be re-added at any time

✅ Cleaning Up Projects

Over time, projects may be moved or deleted. Use Scimax: Cleanup Non-existent Projects:

Command: Scimax: Cleanup Non-existent Projects
Keybinding: (none)

This scans all known projects and removes entries for directories that no longer exist on disk.

Known projects: 15
Checking each path...
Removed: /home/user/old-project (not found)
Removed: /tmp/temp-project (not found)
Result: "Cleaned up 2 non-existent projects"

Run this periodically to keep your project list clean.

✅ Finding Files in Projects

Find files within the current project using Scimax: Find File in Project (C-c p f):

Command: Scimax: Find File in Project
Keybinding: C-c p f
Hydra: Projects → f (Find File)

This delegates to VS Code's built-in quick open (`C-p'), which automatically scopes to workspace folders.

Features:

• Fuzzy matching (e.g., "orgpar" matches "orgParser.ts")

• Recent files appear first

• Respects .gitignore and VS Code ignore patterns

• Fast indexing with intelligent caching

Example:

C-c p f
Type: "babelProv"
→ Matches: src/org/babelProvider.ts
→ Press Enter to open

✅ Searching in Projects

Search for text within project files using Scimax: Search in Project (C-c p s):

Command: Scimax: Search in Project
Keybinding: C-c p s
Hydra: Projects → g (Search in Project)

This opens VS Code's search panel pre-scoped to the current workspace.

Search features:

• Regular expression support

• Case sensitivity toggle

• Whole word matching

• Include/exclude file patterns

• Replace across all matches

Example workflow:

1. Press C-c p s
2. Search panel opens
3. Enter search: "executeSourceBlock"
4. Results show all matches in project
5. Click to navigate to each match

✅ Opening Project Root

Navigate to the project root in the file explorer with Scimax: Open Project Root (C-c p d):

Command: Scimax: Open Project Root
Keybinding: C-c p d
Hydra: (none)

For multi-root workspaces, you'll be asked to select which project root to reveal.

✅ Project Information

View details about the current project with Scimax: Project Info:

Command: Scimax: Project Info
Keybinding: (none)

Displays:

• Project name

• Full path

• Project type (git, projectile, manual)

• Last opened timestamp

• Whether it's tracked by projectile

Example output:

Name: scimax_vscode
Path: /home/user/scimax_vscode
Type: git
Last opened: 2026-01-13 14:32:15

✅ Sidebar Panel

The Projects tree view appears in the Scimax sidebar, showing all known projects.

To open the sidebar:

View → Open View... → Scimax Projects

✅ Tree View Elements

Each project in the tree shows:

• Icon:

• Name: Project directory name

• Description:

✅ Tree Interactions

Click a project to open it:

• Same behavior as `C-c p p' (Switch Project)

• Choose New Window, Current Window, or Add to Workspace

Right-click (context menu) actions:

• Refresh tree view

• Remove project

• Show project info

✅ Refreshing the Tree

The tree auto-refreshes when:

• Projects are added or removed

• Workspace folders change

• Projects are accessed (last opened time updates)

Manual refresh:

Command: Scimax: Refresh Projects
Icon: Refresh button in tree view toolbar

✅ Sorting by Last Access

Projects are sorted by last opened time, with the most recently accessed appearing first:

Project List:
1. scimax_vscode        (just now)     # ← Currently open
2. my-research          (2h ago)       # ← Recently used
3. client-website       (3d ago)
4. old-notes            (2024-11-15)   # ← Long time ago

This ordering makes it quick to switch back to recently used projects.

✅ Automatic Time Tracking

Last opened time is updated automatically when:

• Opening a project via `C-c p p' (Switch Project)

• Clicking a project in the tree view

• Opening a workspace folder that's a known project

The timestamp is stored in VS Code's global state, persisting across sessions.

✅ Time Format

Relative times are shown for recent access:

✅ All Projectile Commands

✅ Keybindings

All projectile keybindings use the C-c p prefix, matching Emacs Projectile conventions:

C-c p p    Switch project
C-c p f    Find file in current project
C-c p F    Find file in all known projects
C-c p s    Search in project
C-c p d    Open project root (directory)
C-c p a    Add project

These bindings work in all editors, regardless of file type.

✅ Hydra Menu Access

Open the Projects hydra menu:

1. Open main hydra: C-c m (or Command Palette → Scimax: Hydra Menu)
2. Press 'p' for Projects

The hydra shows all projectile commands with single-key access:

┌─────────────────────────────────────┐
│ Projects (Projectile)               │
├─────────────────────────────────────┤
│ Switch                              │
│  p  Switch Project                  │
│                                     │
│ Manage                              │
│  a  Add Project                     │
│  r  Remove Project                  │
│  s  Scan for Projects               │
│                                     │
│ Files                               │
│  f  Find File                       │
│  g  Search in Project               │
└─────────────────────────────────────┘

✅ Notebook-Projectile Relationship

The notebook and projectile systems work together:

• Notebooks are projects: Creating a notebook automatically creates a .projectile marker

• Projects can be notebooks: Any project can have a .scimax/ directory to become a notebook

• Shared markers: Both systems recognize .projectile files

• Unified workflow: Switch projects with projectile, manage research structure with notebooks

✅ Creating Projectile-Enabled Notebooks

When you create a notebook with Scimax: New Notebook:

my-notebook/
├── .scimax/
│   └── config.json        # Notebook metadata
├── .projectile            # ← Projectile marker (auto-created)
├── .git/                  # Optional: if "Initialize Git" was checked
└── README.org

The notebook is automatically:

1. Added to the projectile projects list

2. Detected as type "projectile" (or "git" if git was initialized)

3. Available via `C-c p p' for quick switching

✅ Converting Projects to Notebooks

Convert any existing project into a notebook:

1. Open the project
2. Run: Scimax: New Notebook
3. Choose the project directory as the location
→ Adds .scimax/ configuration
→ Project becomes a full notebook with metadata

The project remains in your projectile list and gains notebook features:

• Master file tracking

• Collaborator management

• Notebook-scoped agenda

• Archive capabilities

✅ Notebook Metadata in Projects

Notebooks store additional metadata in .scimax/config.json:

{
  "name": "Research Project",
  "description": "My research on topic X",
  "masterFile": "README.org",
  "collaborators": [
    {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "role": "lead"
    }
  ],
  "keywords": ["research", "machine-learning"],
  "custom": {
    "grant": "NSF-12345"
  }
}

This metadata is available to both systems:

• Projectile shows the project in its list

• Notebook commands provide research-specific features

✅ Workflow Example: Research Projects

Typical workflow for managing multiple research projects:

# Create notebooks for each research topic
Scimax: New Notebook → "ml-experiments"
Scimax: New Notebook → "paper-writing"
Scimax: New Notebook → "data-analysis"

# Each is now in projectile list
C-c p p → Shows all three projects

# Quick switching between research
C-c p p → ml-experiments → open README.org
  (run experiments, update notes)
C-c p p → paper-writing → edit paper.org
  (write, cite references)
C-c p p → data-analysis → explore data/
  (analyze results)

# Search across specific project
C-c p s → "neural network" → find all mentions

The integration provides:

• Fast project switching (projectile)

• Organized research structure (notebook)

• Project-scoped search and navigation

• Consistent marker files

✅ Project Organization

Good:
  my-research-project/
  client-website-2024/
  ml-experiments/

Less good:
  proj1/
  tmp/
  stuff/

~/projects/
  ├── research/
  │   ├── ml-experiments/
  │   ├── data-analysis/
  │   └── paper-writing/
  ├── work/
  │   ├── client-a/
  │   └── client-b/
  └── personal/
      ├── blog/
      └── dotfiles/

✅ Efficient Workflows

C-c p p → type few chars → Enter → choose window option
# Takes ~2 seconds to switch projects

Morning: Open project A (becomes #1)
Afternoon: Switch to project B (becomes #1, A becomes #2)
Evening: Back to A (already #2, quick to select)

1. C-c p p → select project
2. C-c p f → find file
3. Start working

# Faster than navigating manually

Maintenance

Scimax: Cleanup Non-existent Projects

# Find VS Code's storage location
# Linux: ~/.config/Code/User/globalStorage/
# macOS: ~/Library/Application Support/Code/User/globalStorage/
# Windows: %APPDATA%\Code\User\globalStorage\

# Project list is in state.vscdb
# Backup this file to preserve project list

Multi-Root Workspaces

Workspace: "Full Stack App"
  Folders:
    - frontend/  (React app)
    - backend/   (Node API)
    - shared/    (TypeScript types)

Benefits:
  - Search across all three
  - Shared settings
  - Unified git operations

Window 1: Research project (Jupyter, org files)
Window 2: Client website (HTML, CSS, JS)
Window 3: Personal blog (Markdown, static site)

Benefits:
  - Mental separation
  - Independent configurations
  - Clearer taskbar

Custom Project Markers

While .projectile is the standard marker, you can manually add any directory:

Scimax: Add Project → select any folder

Use this for:

• Projects without version control

• Shared network directories

• Temporary project workspaces

Scanning Large Directories

When scanning directories with many subdirectories:

Directory: ~/dev/ (contains 100+ repos)
Max depth: 1

# Only scans immediate children
# Fast, finds top-level projects

Directory: ~/dev/
Max depth: 3

# Scans deeper
# Slower, finds nested projects
# Useful for monorepos or organized hierarchies

Balance depth vs. speed based on your directory structure.

Project Type Prioritization

If a directory has multiple markers:

my-project/
  ├── .git/          # Git marker
  └── .projectile    # Projectile marker

Type: git (git takes priority)

Priority order:

1. .git/ → type "git"

2. `.projectile' → type "projectile"

3. Manual add → type "manual"

This ensures git projects are recognized as such, even if they also have `.projectile' markers.

Programmatic Access

Other extensions can access the projectile manager:

// Get the projectile manager from extension context
const scimaxExt = vscode.extensions.getExtension('scimax.scimax-vscode');
if (scimaxExt?.isActive) {
    const api = scimaxExt.exports;
    const projects = api.projectileManager.getProjects();
    // Use project list...
}

This enables:

• Custom project selection UIs

• Integration with external tools

• Automated project management

Projects Not Appearing

Project List Too Long

Tree View Not Updating

Scanning Not Finding Projects

Slow Project Operations

Similarities

Differences

Migration Tips

If migrating from Emacs Projectile:

1. Muscle memory: Core keybindings (C-c p p, C-c p f, C-c p s) are the same

2. Markers: Your .projectile files work without changes

3. Workflows: File finding and search feel similar but use VS Code UI

4. Project list: Use Scimax: Scan Directory for Projects to import existing projects

5. Customization: VS Code settings replace most projectile variables

No Configuration Required

Projectile works out-of-the-box with no configuration. The extension:

• Automatically detects current workspace folders

• Persists project list in global state

• Uses sensible defaults for all operations

Future Configuration Options

Potential future settings (not currently implemented):

{
  // Default depth for scanning directories
  "scimax.projectile.scanDepth": 2,

  // Auto-scan directories on startup
  "scimax.projectile.autoScan": false,

  // Paths to scan for projects
  "scimax.projectile.scanPaths": [
    "~/projects/",
    "~/dev/"
  ],

  // Max number of recent projects to show
  "scimax.projectile.maxRecentProjects": 50
}

Note: These settings are planned but not yet available. Check extension documentation for current configuration options.

Next Steps

• Create a `.projectile' marker in your important projects

• Use `C-c p p' to build muscle memory for project switching

• Scan your development directory to populate the project list

• Explore integration with notebooks for research projects

• Set up keybindings for your most-used projectile commands

Related Documentation

• Notebook (Project Organization) - Research project structure with notebooks

• Keybindings - Complete keybinding reference

• Configuration - Extension settings and customization

Feedback

If you encounter issues or have feature requests for projectile:

• GitHub Issues: [[https://github.com/your-repo/scimax-vscode/issues]]

• Discussion: [[https://github.com/your-repo/scimax-vscode/discussions]]