Skip to content

START_HERE.md

Latest commit

 

History

History
217 lines (154 loc) · 6.95 KB

START_HERE.md

File metadata and controls

217 lines (154 loc) · 6.95 KB

🚀 START HERE - Open Claude Cowork Research

Welcome! 👋

You asked for deep research on Open Claude Cowork. This directory contains comprehensive analysis answering all 7 of your research questions.

📚 Quick Navigation

"I have 5 minutes"

→ Read: QUICK_REFERENCE_COWORK.md

  • Answers to all 7 questions
  • Key facts and insights
  • Integration recommendations

"I have 20 minutes"

→ Read: OPEN_CLAUDE_COWORK_TECHNICAL_ANALYSIS.md (Sections 1-3)

  • What Cowork is
  • How it differs from Claude Code
  • Full architecture overview

"I have 45 minutes"

→ Read: OPEN_CLAUDE_COWORK_TECHNICAL_ANALYSIS.md (All sections)

  • Complete technical deep dive
  • API specifications
  • Fulcrum integration strategy

"I need to implement it"

→ Read: COWORK_OMEGA_INTEGRATION_GUIDE.md

  • Step-by-step implementation guide
  • Ready-to-use code samples
  • Docker deployment setup

"I'm lost, help me navigate"

→ Read: README_COWORK_RESEARCH.md

  • Navigation guide
  • Learning path (55 minutes)
  • FAQ and references

🎯 Your 7 Research Questions

1. What is it? How does it differ from Claude Code?

  • Answer: Desktop GUI (Electron) vs terminal CLI
  • Where: QUICK_REFERENCE_COWORK.md (Q1) or TECHNICAL_ANALYSIS.md (Section 1)

2. Architecture? Tech stack, entry points, agent collaboration?

  • Answer: Electron + React + Claude Agent SDK + SQLite
  • Where: TECHNICAL_ANALYSIS.md (Section 2) - includes system diagram

3. Multi-agent support? How do agents communicate?

  • Answer: Multiple sessions but no inter-agent communication
  • Where: QUICK_REFERENCE_COWORK.md (Q3) or TECHNICAL_ANALYSIS.md (Section 3)

4. Workspace management? Per-agent workspace support?

  • Answer: Configurable per-session working directory (cwd)
  • Where: TECHNICAL_ANALYSIS.md (Section 4)

5. CLI interface? How do you interact with it?

  • Answer: GUI-only, but supports terminal claude --resume
  • Where: QUICK_REFERENCE_COWORK.md (Q5) or TECHNICAL_ANALYSIS.md (Section 5)

6. Key interfaces/APIs we could use?

  • Answer: Window.electron IPC API + Server/Client events
  • Where: TECHNICAL_ANALYSIS.md (Section 6) - full API specs

7. Integration with Fulcrum Kanban system?

  • Answer: HTTP API wrapper approach (no Cowork modification)
  • Where: TECHNICAL_ANALYSIS.md (Section 7) - complete integration guide

📄 Document Guide

Document Size Purpose Best For
QUICK_REFERENCE_COWORK.md 211 lines Direct answers to 7 Qs Quick understanding, team sharing
OPEN_CLAUDE_COWORK_TECHNICAL_ANALYSIS.md 934 lines Comprehensive technical analysis Complete understanding, architecture
COWORK_OMEGA_INTEGRATION_GUIDE.md 266 lines Implementation guide with code Building the integration
README_COWORK_RESEARCH.md Navigation Guide to all documents Finding what you need
RESEARCH_DELIVERY_SUMMARY.txt Summary Executive overview Stakeholder briefing

⚡ TL;DR (Too Long; Didn't Read)

Open Claude Cowork is:

  • ✅ Desktop app (Electron) that wraps Claude Agent SDK
  • ✅ Persistent session management with SQLite
  • ✅ Multi-session support (concurrent agents)
  • ✅ Real-time streaming UI for agent outputs
  • ✅ Per-session workspace isolation
  • ❌ NOT designed for multi-agent coordination

For Omega integration:

  • Wrap Cowork with HTTP API (no code changes needed)
  • Map Kanban tasks → Cowork sessions (1:1)
  • Stream progress via Server-Sent Events
  • Extract artifacts from session history
  • Let Omega orchestrate the tasks

Recommended approach: HTTP wrapper + Omega adapter (see COWORK_OMEGA_INTEGRATION_GUIDE.md)

🎓 Suggested Reading Path

If you're completely new to this project:

  1. 5 min: Read this file (START_HERE.md)
  2. 5 min: Read QUICK_REFERENCE_COWORK.md
  3. 15 min: Read TECHNICAL_ANALYSIS.md Sections 1-3
  4. 10 min: Skim TECHNICAL_ANALYSIS.md Sections 4-7
  5. 15 min: Read COWORK_OMEGA_INTEGRATION_GUIDE.md

Total: ~50 minutes for complete understanding

🔗 Key Files in the Codebase

Based on our analysis, these are the important files:

  • src/electron/main.ts - Electron app lifecycle
  • src/electron/ipc-handlers.ts - Session management + event routing
  • src/electron/libs/runner.ts - Agent execution (Claude SDK wrapper)
  • src/electron/libs/session-store.ts - SQLite persistence
  • src/electron/preload.cts - IPC bridge (window.electron API)
  • src/ui/App.tsx - Main React component
  • src/ui/store/useAppStore.ts - Zustand state management

💡 Key Insights

  1. Sessions are the unit of work - Each Kanban task = one Cowork session
  2. Workspaces are per-session - Each task gets isolated filesystem access
  3. Real-time streaming available - Full message iterator for live updates
  4. Resumable conversations - Session IDs enable context preservation
  5. Local-first architecture - SQLite is the source of truth
  6. No orchestration needed in Cowork - Omega provides this layer
  7. Minimal wrapper approach - HTTP API just bridges to existing code

⚠️ Important Limitations

  • ❌ No multi-agent coordination built-in
  • ❌ Desktop-only (Electron)
  • ❌ Single-user per instance
  • ❌ Tool set is hardcoded (Read, Edit, Bash)
  • ⚠️ SQLite grows unbounded (no auto-cleanup)

🚀 Next Steps

  1. Pick a reading level (5 min / 20 min / 45 min / 55 min)
  2. Read the appropriate documents
  3. Review COWORK_OMEGA_INTEGRATION_GUIDE.md
  4. Start implementation (fork Cowork, add HTTP wrapper)

❓ FAQ

Q: Can Cowork handle multiple agents on the same task? A: No. Each task = one session = one agent. Use Omega for orchestration.

Q: Is Cowork suitable for production? A: Yes, for single-user scenarios. For Omega, wrap with HTTP API.

Q: Do we need to modify Cowork? A: No! The HTTP wrapper approach leaves Cowork unchanged.

Q: How do we get real-time updates to Fulcrum? A: Server-Sent Events from the HTTP API wrapper.

📊 Research Statistics

  • Total Documentation: 2,030+ lines
  • Code Examples: 20+
  • Architecture Diagrams: 3
  • Implementation Phases: 4
  • Questions Answered: 7/7 ✅

🎯 Your Success Metrics

After implementing this integration, you should have:

✅ HTTP API wrapper for Cowork
✅ Kanban tasks executing as Cowork sessions
✅ Real-time progress updates on cards
✅ Artifacts extracted and displayed
✅ E2E workflow: Card → Execution → Results
✅ Graceful error handling
✅ <100ms latency for SSE updates

📞 Questions?

  • "What is Cowork?" → QUICK_REFERENCE_COWORK.md
  • "How does it work?" → TECHNICAL_ANALYSIS.md
  • "How do I build it?" → INTEGRATION_GUIDE.md
  • "Where do I start?" → README_COWORK_RESEARCH.md

Ready? Pick a document above and start reading! 🚀