Feature Epic: Claude Code-Compatible Workspace Sync for Seamless Local + Cloud Workflows

[jms830]

Vision

Transform Eidolon's workspace sync to create a folder structure that works seamlessly with both Claude.ai projects and Claude Code's local expectations. Users should be able to sync projects from Claude.ai, open the local folder in Claude Code CLI/Desktop, work locally with full context, and sync changes back - all without manual file reorganization.

Motivation

Current Situation:

• Eidolon syncs Claude.ai projects to local folders
• Folder structure is arbitrary (just project files dumped into directories)
• Claude Code expects specific folder structure (.claude/ directory, memory bank files, etc.)
• Users must manually reorganize synced files to use with Claude Code
• No alignment between Claude.ai project structure and Claude Code workspace

Desired Outcome:

• Sync creates folders that Claude Code immediately recognizes as valid projects
• Project instructions from Claude.ai → .claude/settings.json or CLAUDE.md
• Project files organized in standard structure
• Memory bank files (if any) properly placed
• User opens synced folder in Claude Code → everything "just works"

Claude Code Folder Structure Reference

Claude Code expects projects to follow this structure:

my-project/
├── .claude/                          # Claude Code configuration directory
│   ├── settings.json                 # Project-specific settings (optional)
│   └── commands/                     # Custom slash commands (optional)
│       └── my-command.md
├── CLAUDE.md                         # Project instructions (checked into git)
├── CLAUDE-patterns.md                # Code patterns (memory bank, optional)
├── CLAUDE-decisions.md               # Architecture decisions (memory bank, optional)
├── CLAUDE-troubleshooting.md         # Known issues (memory bank, optional)
├── CLAUDE-activeContext.md           # Current session state (optional)
├── src/                              # Actual project files
│   └── (your code here)
├── package.json                      # Project metadata
└── README.md                         # Standard documentation

Key Files:

• CLAUDE.md - Primary project instructions (what Claude.ai calls "Custom Instructions")
• .claude/settings.json - Project-specific configuration
• CLAUDE-*.md - Memory bank system for context persistence
• Standard project files - Normal code, docs, configs

Proposed Workspace Structure

Option 1: Flat Workspace with Projects as Subdirectories

~/claude-workspace/                   # User-selected workspace root
├── .eidolon/                         # Eidolon metadata (not synced to Claude.ai)
│   ├── sync-state.json               # Sync status, hashes, timestamps
│   └── workspace-config.json         # Workspace-level settings
│
├── project-alpha/                    # Claude.ai project → local folder
│   ├── .claude/
│   │   └── settings.json
│   ├── CLAUDE.md                     # Synced from project instructions
│   ├── knowledge-file-1.md           # Synced project files
│   ├── knowledge-file-2.py
│   └── README.md
│
├── project-beta/
│   ├── .claude/
│   ├── CLAUDE.md
│   └── src/
│       └── (project files)
│
└── personal-research/
    ├── .claude/
    ├── CLAUDE.md
    └── notes/
        └── (research docs)

Benefits:

• Clean separation of projects
• Each project is a valid Claude Code workspace
• Easy to open individual projects in Claude Code
• Familiar structure for developers

Sync Mapping:

• Claude.ai Project → Local folder with project name
• Project Instructions → CLAUDE.md
• Project Files → Root of project folder (or knowledge/ subfolder)
• .claude/ directory auto-created on first sync

Option 2: Monorepo-Style Workspace

~/claude-workspace/
├── .claude/                          # Shared Claude Code config
│   ├── settings.json
│   └── commands/
├── CLAUDE.md                         # Workspace-level instructions
├── .eidolon/
│   └── sync-state.json
│
├── projects/                         # All Claude.ai projects here
│   ├── alpha/
│   │   ├── CLAUDE.md                 # Project-specific instructions
│   │   └── (project files)
│   ├── beta/
│   │   ├── CLAUDE.md
│   │   └── (project files)
│   └── gamma/
│       └── ...
│
└── standalone-chats/                 # Standalone conversations (issue #7)
    ├── 2025-01-15-api-design.md
    └── 2025-01-16-debugging.md

Benefits:

• Single Claude Code workspace for all projects
• Shared commands/settings across projects
• Easier to search across all projects
• Natural place for standalone chats

Drawbacks:

• Larger workspace (more files loaded)
• Not ideal if projects are unrelated domains

Option 3: Hybrid - Projects + Standalone Workspace

~/claude-workspace/
├── .eidolon/
│   └── config.json                   # Points to project locations
│
├── projects/                         # Each project is independent
│   ├── work-project-a/               # Can be opened solo in Claude Code
│   │   ├── .claude/
│   │   ├── CLAUDE.md
│   │   └── src/
│   ├── personal-project-b/
│   │   ├── .claude/
│   │   └── CLAUDE.md
│   └── research-project-c/
│       └── ...
│
└── standalone/                       # Workspace for orphaned chats
    ├── .claude/
    ├── CLAUDE.md                     # Generic instructions
    └── chats/
        ├── 2025-01-api-design.md
        └── 2025-01-debugging.md

Benefits:

• Flexibility: open single project or all projects
• Standalone chats have their own workspace
• Projects can be moved/shared independently

Sync Mapping Details

Claude.ai → Local File Mapping

Claude.ai Element	Local Location	Format
Project Name	Folder name (sanitized)	my-project/
Project UUID	Stored in .eidolon/sync-state.json	Metadata only
Project Instructions	CLAUDE.md	Markdown
Project Description	CLAUDE.md frontmatter or README.md	Markdown
Project Files	/ root or /knowledge/	Original format
File UUID	.eidolon/sync-state.json	Metadata only
Standalone Chats (issue #7)	standalone/chats/	Markdown
Conversation Exports	exports/conversations/	Markdown/JSON

CLAUDE.md Format

When syncing project instructions from Claude.ai to local CLAUDE.md:

# Project Name

> Project description from Claude.ai

## Project Instructions

<!-- Synced from Claude.ai project custom instructions -->

Your custom instructions content here...

## Files in This Project

- `knowledge-file-1.md` - Description
- `api-schema.json` - API reference
- `codebase-notes.py` - Implementation notes

---

**Eidolon Metadata:**
- Project UUID: `abc-123-def-456`
- Last Synced: 2025-01-18T10:30:00Z
- Sync Status: ✅ Up to date

.claude/settings.json Format

Optional project-specific settings:

{
  "projectName": "My Project",
  "eidolon": {
    "projectUuid": "abc-123-def-456",
    "lastSync": "2025-01-18T10:30:00Z",
    "syncEnabled": true,
    "conflictResolution": "newer"
  }
}

Implementation Phases

Phase 1: Basic Folder Structure Creation

• On first sync, create project folders with sanitized names
• Auto-create .claude/ directory in each project
• Sync project files to project root
• Store Eidolon metadata in .eidolon/sync-state.json
• Effort: Small | Impact: Medium

Phase 2: Project Instructions → CLAUDE.md

• Fetch project instructions from Claude.ai API
• Create CLAUDE.md with instructions content
• Include metadata footer (UUID, sync timestamp)
• Bidirectional: edit CLAUDE.md locally → syncs back to Claude.ai instructions
• Effort: Medium | Impact: High

Phase 3: .claude/settings.json Integration

• Generate settings.json with Eidolon metadata
• Optionally include project-specific Claude Code settings
• Preserve user-added settings during sync
• Effort: Small | Impact: Low

Phase 4: Memory Bank File Support

• Allow users to create CLAUDE-patterns.md, CLAUDE-decisions.md, etc.
• Optionally sync to Claude.ai as project files
• Or keep local-only (up to user)
• Effort: Small | Impact: Medium

Phase 5: Standalone Chat Workspace

• Related to issue Bug: Project expand dropdown shows 'Error loading files: Not authenticated' despite valid authentication #7 (Standalone Chat Sync)
• Create standalone/ workspace for orphaned conversations
• Each chat becomes a markdown file
• Searchable via Claude Code
• Effort: Medium | Impact: High (combined with Bug: Project expand dropdown shows 'Error loading files: Not authenticated' despite valid authentication #7)

User Workflows Enabled

Workflow 1: Cloud → Local Development

1. User has projects in Claude.ai with knowledge files
2. Opens Eidolon dashboard → "Sync All Projects"
3. Eidolon creates ~/claude-workspace/ with proper structure
4. User opens ~/claude-workspace/my-project/ in Claude Code CLI
5. Claude Code immediately recognizes CLAUDE.md and project structure
6. User can chat with Claude Code using project context
7. Edits files locally, uses git, runs tests
8. Syncs changes back to Claude.ai via Eidolon

Workflow 2: Local → Cloud Bootstrapping

1. User has local project with CLAUDE.md (already using Claude Code)
2. Opens Eidolon dashboard → "Add Workspace"
3. Selects existing project folder
4. Eidolon detects CLAUDE.md, offers to create Claude.ai project
5. Creates project on Claude.ai, syncs CLAUDE.md as instructions
6. Syncs local files as project knowledge
7. User can now use project in both Claude.ai web and Claude Code CLI

Workflow 3: Hybrid Development

1. User works in Claude.ai web interface during research phase
2. Adds code snippets, docs, API schemas to project
3. Syncs to local via Eidolon
4. Opens in Claude Code for implementation phase
5. Makes local changes, commits to git
6. Syncs back to Claude.ai for web-based code review conversations

Technical Implementation Details

Folder Name Sanitization

Claude.ai project names may contain characters invalid for folders:

function sanitizeProjectName(name: string): string {
  return name
    .replace(/[<>:"\/\\|?*]/g, '-')  // Replace invalid chars
    .replace(/\s+/g, '-')            // Spaces to hyphens
    .replace(/-+/g, '-')             // Collapse multiple hyphens
    .substring(0, 255)               // Max filename length
    .toLowerCase();
}

// Example: "My Project: API Design (v2)" → "my-project-api-design-v2"

Bidirectional CLAUDE.md Sync

// Download: Claude.ai instructions → CLAUDE.md
async function syncInstructionsToLocal(project: Project, localPath: string) {
  const instructions = await apiClient.getProjectInstructions(orgId, project.uuid);
  
  const content = `# ${project.name}

> ${project.description || 'No description'}

## Project Instructions

${instructions.content}

---

**Eidolon Metadata:**
- Project UUID: ${project.uuid}
- Last Synced: ${new Date().toISOString()}
`;
  
  await fs.writeFile(path.join(localPath, 'CLAUDE.md'), content);
}

// Upload: CLAUDE.md → Claude.ai instructions
async function syncInstructionsToRemote(localPath: string, projectUuid: string) {
  const content = await fs.readFile(path.join(localPath, 'CLAUDE.md'), 'utf-8');
  
  // Extract instructions section (skip metadata footer)
  const instructionsMatch = content.match(/## Project Instructions\n\n([\s\S]+?)\n---/);
  const instructions = instructionsMatch ? instructionsMatch[1].trim() : content;
  
  await apiClient.updateProjectInstructions(orgId, projectUuid, instructions);
}

Conflict Detection for CLAUDE.md

• Local CLAUDE.md modified: hash changed since last sync
• Remote instructions modified: API returns different content
• Conflict resolution strategies (per workspace config):
  • Local wins: Upload local CLAUDE.md to Claude.ai
  • Remote wins: Download Claude.ai instructions to CLAUDE.md
  • Newer wins: Compare timestamps, use most recent
  • Prompt user: Show diff, let user choose

.eidolon Directory Structure

// .eidolon/sync-state.json (workspace-level metadata)
{
  "workspaceVersion": "1.0",
  "lastSync": "2025-01-18T10:30:00Z",
  "projects": {
    "my-project": {
      "uuid": "abc-123",
      "folderName": "my-project",
      "lastSync": "2025-01-18T10:30:00Z",
      "instructionsHash": "md5-hash-of-CLAUDE.md",
      "files": {
        "knowledge-file-1.md": {
          "uuid": "file-uuid-1",
          "hash": "md5-hash",
          "lastSync": "2025-01-18T10:30:00Z"
        }
      }
    }
  }
}

File System Access API Integration

Reuse existing sync infrastructure:

// In SyncManager.ts
async function syncProjectWithClaudeCodeStructure(
  project: Project,
  workspaceHandle: FileSystemDirectoryHandle
) {
  // Create project folder
  const projectFolder = await workspaceHandle.getDirectoryHandle(
    sanitizeProjectName(project.name),
    { create: true }
  );
  
  // Create .claude directory
  const claudeDir = await projectFolder.getDirectoryHandle('.claude', { create: true });
  
  // Sync instructions to CLAUDE.md
  await syncInstructionsToLocal(project, projectFolder);
  
  // Sync project files to root or knowledge/ subfolder
  await syncProjectFiles(project, projectFolder);
  
  // Create/update .eidolon metadata
  await updateSyncMetadata(project, projectFolder);
}

Configuration Options

Add to workspace config UI in dashboard:

interface WorkspaceConfig {
  // Existing fields...
  
  // New fields for Claude Code compatibility
  claudeCodeCompatible: boolean;           // Enable Claude Code folder structure
  projectFilesLocation: 'root' | 'knowledge'; // Where to put project files
  syncInstructions: boolean;                // Sync CLAUDE.md bidirectionally
  createMemoryBank: boolean;                // Create CLAUDE-*.md files
  standaloneChatsFolder: string;            // Where to put orphaned chats
}

UI in dashboard sync tab:

☑️ Claude Code Compatible Mode
   Create folder structure optimized for Claude Code CLI/Desktop
   
   ◉ Project files in root folder
   ○ Project files in knowledge/ subfolder
   
   ☑️ Sync project instructions to CLAUDE.md
   ☐ Create memory bank files (CLAUDE-patterns.md, etc.)

Benefits

✅ Seamless Workflow: Use Claude.ai web + Claude Code CLI without manual file management

✅ Version Control Ready: Synced folders are git-friendly, standard structure

✅ Context Persistence: Project knowledge available in both environments

✅ Professional Structure: Follows Claude Code best practices out of the box

✅ Bidirectional Editing: Edit CLAUDE.md locally or instructions in web UI

✅ Reduced Friction: No manual .claude/ directory creation or file organization

Challenges & Mitigations

Challenge 1: Name Collisions

• Two projects with same name after sanitization
• Mitigation: Append UUID suffix if collision detected (my-project-abc123/)

Challenge 2: Large Projects

• Hundreds of files in single project
• Mitigation: Optional knowledge/ subfolder to keep root clean

Challenge 3: Instructions Format

• Claude.ai instructions are plain text, CLAUDE.md is markdown
• Mitigation: Wrap in markdown with proper frontmatter, preserve formatting

Challenge 4: Metadata Pollution

• .eidolon/ folder committed to git accidentally
• Mitigation: Auto-add .eidolon/ to .gitignore on workspace creation

Challenge 5: Standalone Chats

• Conversations not tied to projects have no natural folder
• Mitigation: See issue Bug: Project expand dropdown shows 'Error loading files: Not authenticated' despite valid authentication #7, create dedicated standalone/ workspace

Related Issues

• Bug: Project expand dropdown shows 'Error loading files: Not authenticated' despite valid authentication #7 - Standalone Chat Sync (chats without projects)
• Feature Request: Firefox Workspace Sync Support #8 - Firefox Workspace Sync (affects implementation)

Success Metrics

• Zero manual setup: User syncs → opens in Claude Code → works immediately
• Bidirectional edits: Changes to CLAUDE.md sync both directions
• Adoption: % of users enabling "Claude Code Compatible Mode"
• Git integration: Synced folders work with git without extra config

Open Questions

1. Should .claude/settings.json include Eidolon metadata or only Claude Code settings?
2. Where should project files go by default? Root or knowledge/ subfolder?
3. Should we sync memory bank files (CLAUDE-*.md) to Claude.ai as project files?
4. How to handle projects with 100+ files? Subfolder organization?
5. Should we support importing existing Claude Code projects to Claude.ai?
6. What about .gitignore? Auto-create to exclude .eidolon/?

Future Enhancements

• Template Projects: Pre-configured Claude Code project templates
• Smart File Organization: Auto-detect code vs docs and organize accordingly
• Git Integration: Auto-commit synced changes with descriptive messages
• Claude Code Plugin: Official plugin to trigger Eidolon sync from Claude Code CLI

---

Labels: enhancement, integration, claude-code
Milestone: Future
Priority: High (enables local development workflows)
Depends On: Workspace Sync system (already implemented)

[jms830]

Update: AGENTS.md Compatibility Pattern

Based on Anthropic's recommended approach for cross-tool compatibility:

New Structure

Instead of putting instructions directly in CLAUDE.md, use the reference pattern:

project/
├── CLAUDE.md           # Contains only: @AGENTS.md
├── AGENTS.md           # Actual project instructions (synced from Claude.ai)
├── .claude/
│   └── settings.json
└── (project files)

CLAUDE.md Content

@AGENTS.md

That's it - just a single line reference.

AGENTS.md Content

All project instructions synced from Claude.ai go here:

# Project Name

> Project description

## Project Instructions

Your custom instructions content here...

---

**Eidolon Metadata:**
- Project UUID: \`abc-123\`
- Last Synced: 2025-01-18T10:30:00Z

Benefits

✅ Claude Code Compatibility: Follows the @ import syntax to load AGENTS.md

✅ Cross-Tool Compatibility: Works with other LLM CLI tools that use AGENTS.md:

• Gemini CLI
• Codex
• Other emerging tools

✅ Single Source of Truth: One file (AGENTS.md) for all AI tools

✅ Future-Proof: As more tools adopt AGENTS.md convention

Implementation Change

When syncing a project:

1. Create CLAUDE.md with content: @AGENTS.md
2. Sync project instructions to AGENTS.md (not CLAUDE.md)
3. Bidirectional sync operates on AGENTS.md

async function syncProjectInstructions(project: Project, projectFolder: FileSystemDirectoryHandle) {
  // Create CLAUDE.md with reference (if doesn't exist)
  const claudeFile = await projectFolder.getFileHandle('CLAUDE.md', { create: true });
  const claudeWritable = await claudeFile.createWritable();
  await claudeWritable.write('@AGENTS.md');
  await claudeWritable.close();
  
  // Sync actual instructions to AGENTS.md
  const agentsFile = await projectFolder.getFileHandle('AGENTS.md', { create: true });
  const agentsWritable = await agentsFile.createWritable();
  await agentsWritable.write(formatInstructions(project));
  await agentsWritable.close();
}

This approach ensures Eidolon-synced projects work seamlessly with Claude Code AND other LLM CLI tools out of the box.

[toroleapinc]

This is a meaty feature epic! Seamless local + cloud workflow sync is something a lot of people are trying to solve from different angles.

If it helps, claude-brain tackles the config/brain sync layer specifically — keeping CLAUDE.md, settings, skills, and agent definitions portable across machines via git hooks. It might complement the workspace-level sync you're describing here. The brain stays consistent while the workspace files handle the project-specific state.

Happy to discuss how these could fit together if there's interest.