Layout and Navigation
Relevant source files
The following files were used as context for generating this wiki page:
Layout and Navigation in the project are centered around a tab-based architecture that facilitates multi-tasking across different modules such as project management, AI agent execution, and system settings. The application utilizes a custom titlebar for global navigation and window control, ensuring a unified aesthetic across desktop environments.
The primary navigation flow allows users to switch between high-level views—such as the Welcome screen, CC Agents, and Project lists—while maintaining active sessions within individual tabs. This structure is supported by global keyboard shortcuts and event-driven tab management.
Sources: src/App.tsx:43-65, src/components/App.cleaned.tsx:37-65, README.md:58-85
Global Layout Structure
The root application layout is a vertical flex container consisting of three main tiers: a custom titlebar, a tab manager for navigation between active contexts, and a dynamic content area.
Visual Hierarchy
| Component | Responsibility | Relevant Files |
|---|---|---|
| CustomTitlebar | Global navigation links (Agents, Usage, MCP, Settings) and window controls (Close, Min, Max). | src/components/CustomTitlebar.tsx, src/App.tsx:327-340 |
| TabManager | Displays active tabs, allows switching between them, and provides a "+" button for new chat tabs. | src/components/TabManager.tsx, src/App.tsx:343 |
| TabContent | Renders the specific component associated with the currently active tab. | src/components/TabContent.tsx, src/App.tsx:345 |
Sources: src/App.tsx:325-350, src/components/App.cleaned.tsx:106-118
Mermaid: Layout Architecture
The diagram below illustrates the hierarchical relationship between the main layout components.
Navigation Mechanisms
Navigation is handled through three primary mechanisms: a centralized view state for top-level navigation, a TabProvider for context-aware multi-tasking, and custom event listeners for global interactions.
Top-Level View Navigation
The AppContent component maintains a view state of type View, which determines the overall layout context. Key views include:
- welcome: The initial entry point with navigation cards.
- projects: Management of Claude Code projects.
- cc-agents: Management and creation of AI agents.
- tabs: The standard operational mode where the
TabManageris visible.
Sources: src/App.tsx:43-57, src/App.tsx:185-323
Tab-Based Navigation
The system supports advanced tab interactions, including persistence and session isolation. Tabs are managed via the useTabState hook, which provides methods for creating specific tab types.
Keyboard Shortcuts
Navigation is enhanced by global keyboard shortcuts handled via window.addEventListener('keydown', ...). These shortcuts facilitate rapid tab manipulation:
- Ctrl/Cmd + T: Create a new chat tab.
- Ctrl/Cmd + W: Close the current tab.
- Ctrl/Cmd + Tab: Cycle through next/previous tabs.
- Ctrl/Cmd + [1-9]: Switch to a specific tab by index.
Sources: src/App.tsx:104-138, src/components/App.cleaned.tsx:37-67
Components Analysis
Custom Titlebar
The titlebar serves as the persistent global navigation hub. It integrates the application logo, navigation links with localized labels (from en.json), and platform-specific window controls.
- Navigation Actions: Triggers functions like
onAgentsClick,onUsageClick, andonSettingsClick. - Styling: Utilizes
tauri-dragfor window movement andtauri-no-dragfor interactive buttons.
Sources: src/components/CustomTitlebar.tsx:10-50, src/i18n/locales/en.json:8-18, src/styles.css:12-20
Tab Manager and Content
The TabManager provides the UI for switching between active tasks, while TabContent acts as the router that renders the correct component based on the active tab's metadata (e.g., project ID, agent type).
- Custom Events: The layout responds to events like
create-chat-tab,close-current-tab, andswitch-to-tab-by-index. - Tab Persistence: Settings can be configured to "Remember Open Tabs," which restores navigation state on restart.
Sources: src/App.tsx:104-138, src/i18n/locales/en.json:104-108
Styling and Theming
The layout uses Tailwind CSS v4 with a custom OKLCH color palette. Themes affect navigation visibility and UI contrast.
UI Utility Classes
| Class | Effect |
|---|---|
.tauri-drag | Enables window dragging on the titlebar area. |
.scrollbar-hide | Hides scrollbars for a cleaner navigation experience in lists. |
.shimmer-hover | Visual feedback for navigation cards on the Welcome screen. |
.trailing-border | Animated border effect for active or hovered project cards. |
Sources: src/styles.css:12-22, src/styles.css:48-60, src/styles.css:355-385
Conclusion
The project's Layout and Navigation are architected to support high-density workflows by combining a traditional view-based router with a modern tabbed interface. This allows developers to seamlessly move between configuring MCP servers, monitoring usage analytics, and executing complex agent workflows without losing context. Consistency is maintained through a custom titlebar and a unified theme system, while accessibility is prioritized through extensive keyboard support.
Sources: src/App.tsx:327-347, README.md:104-125