Workspaces

Workspaces connect chat threads to project directories, enabling AI-assisted coding and file management.

Overview

When you set a workspace for a chat:

• The AI can read files in that directory
• The AI can write and edit files
• File tools become workspace-aware
• The file tree shows in the sidebar

Setting a Workspace

From Chat Header

1. Click the folder icon in the chat header
2. Select a directory from the file picker
3. The workspace is now active

Creating Workspaces

1. Go to Settings → Workspaces
2. Click Add Workspace
3. Choose a directory
4. Give it a name

Default Workspace

Set a default workspace for new chat threads:

1. Go to Settings → General
2. Select a default workspace

File Tree

When a workspace is active:

• The sidebar shows the file tree
• Click files to preview them
• Use search to find files quickly
• Toggle hidden files visibility

File Operations

Reading Files

"Show me the contents of src/index.ts"
"What's in the README?"
"Find all TypeScript files"

Writing Files

"Create a new component called Button"
"Add a function to utils.ts"
"Update the configuration"

Editing Files

"Fix the bug on line 42"
"Refactor this function"
"Add error handling"

Git Integration

Workspaces with git repositories show:

• Current branch
• Modified files
• Commit history

Git Operations

• View status and diffs
• Stage and unstage files
• Create commits
• Switch branches
• Push and pull

Artifact Workspace

For generated artifacts (HTML, React components), Alma uses a separate artifact workspace:

• Located in app data directory
• Stores generated files
• Enables preview functionality

Best Practices

Workspace Organization

• Use one workspace per project
• Set descriptive names
• Configure default for frequent projects

Security

• Only grant workspace access to trusted directories
• Be cautious with file write operations
• Review changes before committing

Performance

• Large directories may take time to load
• Use .gitignore patterns to exclude node_modules
• Close unused workspaces

Troubleshooting

"Workspace Not Found"

• The directory may have been moved or deleted
• Remove and re-add the workspace

"Permission Denied"

• Check file system permissions
• Ensure Alma has access to the directory

"Files Not Showing"

• Check if files are hidden
• Verify the workspace path is correct
• Try refreshing the file tree