✅ 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 (cmd:scimax.projectile.remove):

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

The list shows the stalest projects first: never-opened ones, then the longest since last opened, with when each was last opened next to its name. Projects whose folder no longer exists are marked with a warning icon. Tick as many as you like (Space toggles, Enter removes); removing more than one asks for confirmation first.

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

Switching to the Current File's Project

When you open a file that belongs to another project (from the agenda, a link or a search), the window still has the original project, so the Explorer and C-c p f show the wrong files. Scimax: Switch to Current File's Project (C-c p .) switches the window to the file's project:

Command: scimax.projectile.switchToFileProject
Keybinding: C-c p .

The project is the nearest directory above the file that has a .git or .projectile, or is a known project; it is added to the known projects if it is new. The window reloads with that folder, VS Code restores that project's open editors, and the file reopens at the same line, revealed in the Explorer. If the window already has the project, the file is just revealed. VS Code asks about unsaved changes before it switches. To go back, switch with C-c p p.

✅ 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:

  • 🟢 Open folder icon (green) = currently open project

  • Git branch icon = git repository

  • File icon = projectile-marked project

  • Folder icon = manual project

• Name: Project directory name

• Description:

  • "● current" for the active project

  • Relative time (e.g., "2h ago", "3d ago") for recent projects

  • Empty for never-opened projects

✅ 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