How to Manage Project Folders in ChocolateLMLite: A Complete Developer Guide

ChocolateLMLite stores persona-specific project files in isolated data/persona_<id>/project/ directories and provides the FileManager class with built-in path traversal protection to safely create, read, and enumerate workspace files.

Managing project folders in ChocolateLMLite is essential for organizing persona-specific assets and source code. The repository implements a secure, sandboxed file system through the FileManager class in src/FileManager.cs, ensuring that each persona's project files remain isolated and protected from directory traversal attacks. This guide covers the architecture, security mechanisms, and API methods for programmatically managing project folders.

Understanding the Project Folder Architecture

Directory Structure and Storage Location

Every persona in ChocolateLMLite receives a dedicated workspace under the data directory. When you create a new persona using CreateNewPersona, the system automatically generates a project subfolder:

• Root path: data/persona_<id>/
• Project workspace: data/persona_<id>/project/

This structure ensures that files belonging to different personas never intersect, maintaining strict data isolation between workspaces.

Security Boundaries and Path Traversal Protection

The FileManager class implements multiple security layers to prevent unauthorized file access. According to the source code in src/FileManager.cs (lines 1236-1242), the system validates that any target file's absolute path must start with the persona's project directory absolute path.

Key security features include:

• Path sanitization: The SanitizeFilename method strips illegal characters from filenames to prevent injection attacks.
• Directory traversal blocking: Attempts to access paths like ../secret.txt raise an InvalidOperationException.
• Automatic folder creation: If the project directory is missing, the system creates it on demand during write operations.

Creating and Accessing Project Folders Programmatically

Initializing a New Persona Workspace

To create a project folder, you first create a persona. The CreateNewPersona method in FileManager.cs handles both the persona record and the directory structure.

using ChocolateLMLite;

// Initialize the file manager
var fm = new FileManager();

// Create a new persona - this automatically creates the project folder
string? newId = fm.CreateNewPersona("DemoPersona");
// Returns: persona_1234567890 (timestamp-based ID)
// Creates: data/persona_1234567890/project/

Writing and Reading Project Files

Once the workspace exists, use SaveProjectFileContentToActivePersona to write files and GetProjectFileContentFromActivePersona to retrieve them. These methods automatically handle path sanitization and security checks.

// Save a JavaScript file to the project
string filename = "app.js";
string code = @"console.log('Hello, Chocolate LMLite!');";

// This writes to: data/persona_<id>/project/app.js
fm.SaveProjectFileContentToActivePersona(filename, code);

// Retrieve the file content later
string retrieved = fm.GetProjectFileContentFromActivePersona(filename);
Console.WriteLine(retrieved); 
// Output: console.log('Hello, Chocolate LMLite!');

Listing and Managing Project Files

To enumerate all files in the project directory, use GetProjectFileListFromActivePersona. This returns a list of filenames currently stored in the workspace.

// Get all files in the project folder
List<string> files = fm.GetProjectFileListFromActivePersona();

// Example output: ["app.js", "README.md", "styles.css"]
Console.WriteLine(string.Join(", ", files));

Integrating Project Files with LLM System Prompts

ChocolateLMLite extends the LLM context by injecting project file metadata into system prompts. When generalSettings.EnableProject is set to true, the SystemPrompt.BuildSystemPrompt method in src/SystemPrompt.cs automatically reads the project file list and includes it as <project_files> XML tags.

This integration allows the language model to reference the current workspace structure without manual configuration. The file list is generated using the same GetProjectFileListFromActivePersona method, ensuring consistency between the file system and the AI context.

Summary

Managing project folders in ChocolateLMLite involves understanding the sandboxed directory structure and utilizing the FileManager API for secure file operations:

• Storage location: Project files reside in data/persona_<id>/project/, created automatically when a persona is initialized via CreateNewPersona.
• Security model: The system enforces path traversal protection and filename sanitization through src/FileManager.cs, rejecting attempts to access files outside the designated workspace.
• Core operations: Use SaveProjectFileContentToActivePersona and GetProjectFileContentFromActivePersona for file I/O, and GetProjectFileListFromActivePersona for directory enumeration.
• LLM integration: Enable generalSettings.EnableProject to automatically inject file lists into system prompts via SystemPrompt.BuildSystemPrompt.

Frequently Asked Questions

Where are project folders stored in ChocolateLMLite?

Project folders are stored within persona-specific directories under the data folder. Each persona receives a workspace at data/persona_<id>/project/, where <id> is the timestamp-based identifier generated during persona creation. This structure ensures complete isolation between different personas.

How do I prevent path traversal attacks when saving files?

ChocolateLMLite automatically prevents path traversal attacks through the FileManager class in src/FileManager.cs. The system validates that any target file's absolute path must begin with the persona's project directory absolute path. Attempts to use directory traversal sequences like ../ in filenames will raise an InvalidOperationException.

Can I use project files with the LLM system prompt?

Yes. When you set generalSettings.EnableProject to true in the settings, the SystemPrompt.BuildSystemPrompt method automatically scans the project folder and injects a list of available files into the LLM context using <project_files> XML tags. This allows the language model to reference your codebase without manual copy-pasting.

What happens if the project folder doesn't exist?

If the project folder is missing, ChocolateLMLite creates it automatically on demand. When you call methods like SaveProjectFileContentToActivePersona or GetProjectFileListFromActivePersona, the FileManager checks for the directory existence and initializes it if necessary. This ensures that file operations never fail due to missing directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}