# marcus/sidecar architecture

> Architecture diagram of the GitHub repository marcus/sidecar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marcus/sidecar
- Repository: https://github.com/marcus/sidecar

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Entry
    CLI["CLI Entrypoint"]:::core
    click CLI "https://github.com/marcus/sidecar/blob/main/cmd/sidecar/main.go"

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        APP["App Orchestrator"]:::core
        click APP "https://github.com/marcus/sidecar/tree/main/internal/app/"
        EVENT["Event Dispatcher"]:::core
        click EVENT "https://github.com/marcus/sidecar/blob/main/internal/event/dispatcher.go"
        STATE["In-memory State Store"]:::core
        click STATE "https://github.com/marcus/sidecar/blob/main/internal/state/state.go"
        CONFIG["Configuration Manager"]:::core
        click CONFIG "https://github.com/marcus/sidecar/blob/main/internal/config/config.go"
        VERSION["Version Checker"]:::core
        click VERSION "https://github.com/marcus/sidecar/blob/main/internal/version/checker.go"
    end

    %% TTY & UI Subsystem
    subgraph "TTY & UI Subsystem"
        direction TB
        TTY["TTY Abstraction"]:::ui
        click TTY "https://github.com/marcus/sidecar/blob/main/internal/tty/tty.go"
        UI["UI Renderer"]:::ui
        click UI "https://github.com/marcus/sidecar/tree/main/internal/ui/"
        MODAL["Modal Subsystem"]:::ui
        click MODAL "https://github.com/marcus/sidecar/blob/main/internal/modal/modal.go"
        STYLES["Styles"]:::ui
        click STYLES "https://github.com/marcus/sidecar/blob/main/internal/styles/styles.go"
        PALETTE["Palette"]:::ui
        click PALETTE "https://github.com/marcus/sidecar/blob/main/internal/palette/palette.go"
        THEME["Theme Resolver"]:::ui
        click THEME "https://github.com/marcus/sidecar/blob/main/internal/theme/resolve.go"
    end

    %% Plugin Framework
    subgraph "Plugin Framework"
        direction TB
        REGISTRY["Plugin Registry"]:::plugin
        click REGISTRY "https://github.com/marcus/sidecar/blob/main/internal/plugin/registry.go"
        subgraph "Built-in Plugins"
            direction TB
            CONV["Conversations"]:::plugin
            click CONV "https://github.com/marcus/sidecar/tree/main/internal/plugins/conversations/"
            GIT["Git Status"]:::plugin
            click GIT "https://github.com/marcus/sidecar/tree/main/internal/plugins/gitstatus/"
            FILE["File Browser"]:::plugin
            click FILE "https://github.com/marcus/sidecar/tree/main/internal/plugins/filebrowser/"
            TD["TD Monitor"]:::plugin
            click TD "https://github.com/marcus/sidecar/tree/main/internal/plugins/tdmonitor/"
            WS["Workspaces"]:::plugin
            click WS "https://github.com/marcus/sidecar/tree/main/internal/plugins/workspace/"
        end
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        ADAPTER_BASE["Adapter Base & Registry"]:::adapter
        click ADAPTER_BASE "https://github.com/marcus/sidecar/blob/main/internal/adapter/adapter.go"
        SEARCH["Search API"]:::adapter
        click SEARCH "https://github.com/marcus/sidecar/blob/main/internal/adapter/search.go"
        CACHE["Adapter Cache"]:::adapter
        click CACHE "https://github.com/marcus/sidecar/blob/main/internal/adapter/cache/cache.go"
        subgraph "AI Agent Adapters"
            direction TB
            CLAUDE["Claude Code Adapter"]:::adapter
            click CLAUDE "https://github.com/marcus/sidecar/blob/main/internal/adapter/claudecode/register.go"
            CODEX["Codex Adapter"]:::adapter
            click CODEX "https://github.com/marcus/sidecar/blob/main/internal/adapter/codex/register.go"
            CURSOR["Cursor Adapter"]:::adapter
            click CURSOR "https://github.com/marcus/sidecar/blob/main/internal/adapter/cursor/register.go"
            GEMINI["Gemini CLI Adapter"]:::adapter
            click GEMINI "https://github.com/marcus/sidecar/blob/main/internal/adapter/geminicli/register.go"
            WARP["Warp Adapter"]:::adapter
            click WARP "https://github.com/marcus/sidecar/blob/main/internal/adapter/warp/register.go"
        end
    end

    %% External Services & Tools
    subgraph "External Services & Tools"
        direction TB
        AICLI["AI Agent CLIs"]:::external
        GITSVC["Git"]:::external
        TDCLI["TD CLI"]:::external
    end

    %% Documentation Website
    DOCS["Documentation Website"]:::docs
    click DOCS "https://github.com/marcus/sidecar/tree/main/website/"

    %% Relationships
    CLI -->|starts| APP
    APP -->|"load config"| CONFIG
    APP -->|"check update"| VERSION
    APP -->|"start loop"| EVENT
    EVENT -->|dispatch| STATE
    EVENT -->|publish| REGISTRY
    STATE -->|provide| PLUGINS(( ))
    CONFIG -->|settings| APP
    EVENT -->|input| REGISTRY

    REGISTRY -->|load plugins| CONV
    REGISTRY -->|load plugins| GIT
    REGISTRY -->|load plugins| FILE
    REGISTRY -->|load plugins| TD
    REGISTRY -->|load plugins| WS

    CONV -->|listen| EVENT
    GIT -->|listen| EVENT
    FILE -->|listen| EVENT
    TD -->|listen| EVENT
    WS -->|listen| EVENT

    CONV -->|update state| STATE
    GIT -->|git ops| GITSVC
    GIT -->|fs watch| EVENT
    TD -->|td cmds| TDCLI
    WS -->|git/tf| GITSVC
    WS -->|agent| ADAPTER_BASE

    ADAPTER_BASE -->|registers| CLAUDE
    ADAPTER_BASE -->|registers| CODEX
    ADAPTER_BASE -->|registers| CURSOR
    ADAPTER_BASE -->|registers| GEMINI
    ADAPTER_BASE -->|registers| WARP

    CLAUDE -->|calls| AICLI
    CODEX -->|calls| AICLI
    CURSOR -->|calls| AICLI
    GEMINI -->|calls| AICLI
    WARP -->|calls| AICLI

    ADAPTER_BASE -->|search/watch| SEARCH
    SEARCH -->|cache| CACHE
    CACHE -->|feeds| CONV

    STATE -->|model| UI
    UI -->|render frame| TTY
    TTY -->|terminal I/O| Terminal(( ))
    MODAL -->|overlay| UI
    STYLES -->|style| UI
    PALETTE -->|color| UI
    THEME -->|theme| UI

    DOCS -.->|docs build| GitHubActions(( ))
    GitHubActions -->|deploy| DocsHost(( ))
    DocsHost -->|serve| DOCS

    %% Styles
    classDef core fill:#cfe2f3,stroke:#6fa8dc;
    classDef plugin fill:#d9ead3,stroke:#6aa84f;
    classDef adapter fill:#f9cb9c,stroke:#e69138;
    classDef external fill:#d9d9d9,stroke:#999999;
    classDef ui fill:#c9c0ff,stroke:#8e7cc3;
    classDef docs fill:#fff2cc,stroke:#bf9000;
```
