Project & Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Project and Session Management in Opcode serves as the core orchestration layer for organizing AI-assisted development workflows. It bridges the gap between the local filesystem—specifically the ~/.claude/projects/ directory—and the interactive Claude Code environment. This system allows users to browse projects, track historical interactions, and resume coding sessions with full context.
Sources: README.md:46-51, src/lib/api.ts:252-263
Architecture and Data Models
The management system relies on two primary entities: Projects and Sessions. Projects represent specific directories where Claude Code has been initialized, while Sessions represent individual JSONL-backed interaction logs within those projects.
Data Structures
| Entity | Field | Type | Description |
|---|---|---|---|
| Project | id | string | Derived from directory name. |
path | string | Absolute path to the project source code. | |
sessions | string[] | List of associated session IDs. | |
| Session | id | string | Unique UUID for the interaction log. |
project_id | string | The parent project identifier. | |
created_at | number | Unix timestamp of session creation. | |
first_message | string | Preview of the initial user prompt. |
Sources: src/lib/api.ts:24-54
System Workflow
The following diagram illustrates the flow from project selection to active session execution.
The application initializes by listing projects from ~/.claude/projects/. Upon selecting a project, the UI retrieves associated session metadata to allow for context-aware resumption.
Sources: src/App.tsx:143-176, src/lib/api.ts:252-276
Session Lifecycle and Execution
Sessions are executed as subprocesses of the main application. In the desktop environment, these are managed via Tauri commands, while the Web Server mode uses an Axum-based Rust backend to spawn the claude binary.
Execution Flow
When a user submits a prompt, the system follows a specific sequence to maintain real-time feedback:
The ClaudeCodeSession component handles both Tauri events and DOM events (in web mode) to process these streams. It maintains a rawJsonlOutput state for full session fidelity and a displayableMessages list for UI rendering.
Sources: src/components/ClaudeCodeSession.tsx:28-56, web_server.design.md:14-25
Critical Session Functions
loadSessionHistory: Retrieves past interactions from JSONL files to populate the UI state.handleSendPrompt: Determines whether to callexecuteClaudeCode(for new sessions) orresumeClaudeCode(for continuing existing context).reconnectToSession: Allows the UI to attach to a process that is already running in the background.
Sources: src/components/ClaudeCodeSession.tsx:191-236, src/components/ClaudeCodeSession.tsx:327-410
Project Settings and Customization
Projects can be customized through specific configuration files stored within the .claude/ subdirectory of the project path.
Configuration Scopes
| Scope | File Location | Version Control |
|---|---|---|
| Project | .claude/settings.json | Committed (Shared with team) |
| Local | .claude/settings.local.json | Ignored (Machine-specific) |
Users can manage Slash Commands and Hooks within these scopes. The ProjectSettings component provides a dedicated interface to toggle between these configurations and ensures that machine-specific settings (local hooks) are properly added to .gitignore.
Sources: src/components/ProjectSettings.tsx:44-77, src/lib/api.ts:1145-1165
Conclusion
Project and Session Management provides the structural framework for Opcode, enabling a persistent and organized development experience. By mapping local directories to isolated session logs and supporting multi-scoped configurations, the system ensures that AI interactions are both reproducible and team-compatible.