Project Management

Mantra introduces an innovative Logical Project view to help you unify and manage programming sessions from different AI tools.

Core Concepts

Logical Project vs. Physical Path

In Mantra, a project is no longer just a workspace for a single tool, but an aggregated view based on Physical Paths:

• Physical Path: The actual folder on your hard drive (e.g., /Users/decker/projects/mantra).
• Logical Project: Mantra automatically aggregates all sessions pointing to the same physical path (whether from Claude, Gemini, or Cursor) into a unified "Logical Project".

This means that sessions generated using different AI tools within the same code repository can now be viewed and managed centrally in Mantra.

Supported Sources

Mantra currently supports aggregating sessions from the following sources:

• Claude Code: Based on project directories.
• Gemini CLI: Based on project hash or manually associated paths.
• Cursor: Based on workspace paths.
• Codex: Based on session file paths.

Features

1. Automatic Aggregation

When you import logs from different tools, Mantra automatically detects their associated physical paths. If the paths are the same, they are automatically merged under the same Logical Project.

In the project list, you can see the session source icons (such as Claude, Gemini, etc.) contained in each project.

2. Manual Association & Path Correction

Some tools (like Gemini CLI) may not provide accurate physical paths automatically (showing as gemini-project:xxx or "Needs Association").

• Associate Path: On the project details page, you can click the "Associate Real Path" button to manually select the corresponding local folder for that project.
• Auto-Merge: After association, if another project already exists under that path, Mantra will automatically merge them into one Logical Project.

3. Project Renaming

You can customize the display name of a Logical Project for easier identification.

• Right-click the project -> Select Rename.
• This only modifies the display name in Mantra and does not affect the folder name on your hard drive.

4. Unlinking

If you wish to separate a specific source from a Logical Project:

1. Open the project details page.
2. Find the source in the "Aggregated Sources" list.
3. Click the Unlink button.

After unlinking, the source will revert to an independent (usually virtual path) project status.

5. MCP Service Association & Tool Policies (v0.7.0+)

In the project details page, you can deeply customize AI's access permissions for that specific project:

• Associate MCP Services: Toggles specific MCP services for each project. AI can only access services explicitly linked to the current project, ensuring a secure context boundary.
• Tool Policies: Set permissions for specific tools (e.g., read_file, write_file, execute_command):
  • Always Allow: Improves workflow fluidity.
  • Ask for Permission: Recommended for critical operations (e.g., file deletion).
  • Deny: Completely block AI access to high-risk tools.

6. Git Integration

Mantra real-time detects if a Git repository exists under the physical path associated with the Logical Project.

• If it exists, a Git branch icon will be displayed on the right side of the project list.
• You can view the Git status and history of the project directly in Mantra.