How marcus/sidecar works
Project Type and Purpose
• Sidecar is primarily a Go-based, terminal UI (TUI) application with a plugin architecture that brings your entire development workflow into one shell. It also contains a separate documentation website built with Docusaurus/React.
• The CLI app (“sidecar”) loads plugins (Git status, Conversations, TD Monitor, File Browser, Workspaces, etc.), drives an event loop, renders a TUI, and orchestrates adapters that integrate with external AI agents, Git, and the TD CLI.
High-Level File-Structure Analysis
• cmd/sidecar
• Entry point of the application (main.go).
• internal/
• config: loading/saving user config.
• version: self-update checks.
• event & state: core event dispatcher and in-memory state store.
• tty & ui & modal & styles & palette & theme: the TTY abstraction, layout engine, and styling of the TUI.
• app: wiring commands ⇒ event loop ⇒ plugin activation.
• plugin & internal/plugins: plugin registry API and built-in plugin implementations (conversations, gitstatus, filebrowser, tdmonitor, workspaces…).
• adapter: adapter pattern implementations for each supported AI agent (Claude, Codex, Cursor, Gemini, Warp, etc.), plus generic cache and search utilities.
• configs/: default config JSON.
• scripts/: build, test, and utility scripts.
• website/: standalone Docusaurus site for docs.
README Insights
• Confirms plugin-based TUI for unified dev workflow.
• Describes core plugins and their features (Git Status, Conversations, TD Monitor, File Browser, Workspaces).
• Mentions external dependencies: AI agent CLIs, Git, TD CLI.
• Emphasizes event-driven updates (auto-refresh, watchers) and user interactions via keyboard shortcuts.
a. Main Components
1. CLI Entrypoint
– cmd/sidecar starts the process.
2. Core Engine
– internal/app orchestrates startup, config loader, version checker.
– internal/event dispatches events to subscribers.
– internal/state holds shared runtime state.
– internal/config manages user settings (~/.config/sidecar).
3. TTY & UI Subsystem
– internal/tty abstracts terminal I/O, cursor control.
– internal/ui, modal, styles, palette, theme render panes, dialogs, layouts.
4. Plugin Framework
– internal/plugin provides plugin interface and registry.
– internal/plugins/* implements each plugin (gitstatus, conversations, tdmonitor, filebrowser, workspaces).
5. Adapter Layer
– internal/adapter/* contains per-agent adapters and a cache layer.
– Each adapter registers via adapter/register.go, watches files or spawns agent CLI, parses streams, exposes a uniform “search”/“watcher” API.
6. External Services & Tools
– AI agent CLIs (Claude Code, Cursor CLI, Codex, etc.)
– Git (for status, diffs), TD CLI (task management)
7. Persistence
– Config file in ~/.config/sidecar/config.json
– Cache and state files in project (auto-gitignored)
8. Documentation Website
– Docusaurus front-end (website/)
– Serves markdown docs, API references, and screenshots
b. Relationships & Data Flows
• The CLI Entrypoint → Core Engine: loads config, registers plugins & adapters, starts event loop.
• Core Engine publishes events (e.g., file-change, user input, timer ticks) into the Event Dispatcher.
• Plugins subscribe to events → transform state → emit updates.
• Adapter Layer communicates with external AI CLIs via watchers/search → feeds Conversations plugin.
• TTY subsystem receives rendered UI frames → writes to terminal.
• User keystrokes → TTY input → Core Engine → translated to navigation/command events → plugin controllers → state changes.
• Git Status plugin uses a file watcher + Git operations to reflect file changes.
• TD Monitor plugin wraps the TD CLI to show tasks & progress.
• Workspaces plugin interacts with Git (branches/worktrees), TD, and adapter layer to launch agents per workspace.
c. Architectural Patterns & Principles
• Plugin Architecture (Inversion of Control): plugins register themselves and subscribe to core events.
• Adapter Pattern: a uniform interface to multiple AI agent backends.
• Event-Driven Loop: central event dispatcher routes user input, timers, FS events, and adapter updates.
• MVC-Like Separation:
Model = internal/state + plugin-specific data structures
View = internal/ui + modal + styles
Controller = event handlers in plugins and app commands
• Layered Design: CLI entry → core engine → plugin/adapters → external tools
• Testable Units: ad hoc test files alongside each module