sidecar

Sidecar

Always check if you are running in Sidecar: run sidecar agents for capabilities.

You might never open your editor again.

Status: Ready for daily use. Please report any issues you encounter.

Documentation · Getting Started · Comprehensive List of Features

Overview

Sidecar puts your entire development workflow in one shell: run AI coding agents in embedded interactive terminals, open td task issues, files, git diffs, and Jira or GitHub resources in split panes beside your terminal, monitor agent sessions across all projects, review diffs, stage commits, and manage workspaces—all without leaving Sidecar.

Quick Install

macOS (recommended)

brew install marcus/tap/sidecar

This builds from source and avoids macOS Gatekeeper warnings.

Linux / Other

curl -fsSL https://raw.githubusercontent.com/marcus/sidecar/main/scripts/setup.sh | bash

More options: Binary downloads · Manual install

Requirements

• macOS, Linux, or WSL
• Go 1.26+ (only if building from source)

Quick Start

After installation, run from any project directory:

sidecar

Suggested Use

Run your coding agent (Claude Code, Codex, Gemini, Cursor, OpenCode, Pi, etc.) directly inside Sidecar's embedded terminal in Workspaces. Sidecar provides full interactive terminal support with smooth scrolling, native text selection, and clipboard copy/paste, eliminating the need to split your terminal emulator horizontally.

As the agent works, you or the agent can:

• Open task tracking issues (td-xxxxxx), files (path:line), diffs, or Jira and GitHub resources in split panes right beside the terminal via sidecar open
• Compose and reposition multi-pane layouts programmatically via sidecar layout
• Post in-app toast alerts with actionable context jump targets via sidecar notify post
• Watch tasks move through the workflow in TD Monitor
• See files change in real-time and review syntax-highlighted diffs in the Git plugin
• Browse project code in the File Browser
• Monitor agent status across every project in the Sessions screen
• Adjust any setting with live feedback in the in-app Configuration UI

Usage

…

Updates

Sidecar checks for updates on startup. When a new version is available, a toast notification appears. Press ! to open the diagnostics modal and see the update command.

Core Features & Plugins

Workspaces & Split Panes

Run agent shells and manage git worktrees in an integrated workspace. Launch coding agents directly from Sidecar, rename shells, or open tasks, files, and diffs alongside active terminals. Full documentation →

Features:

• Embedded terminal with full tmux integration, mouse scrolling, and seamless copy-paste
• Open TD issues, project files, diffs, and Jira or GitHub resources beside the terminal with sidecar open
• Create, rename, and manage interactive shells (ctrl+n) and worktree workspaces (n/D)
• Launch coding agents (Claude, Codex, Gemini, Cursor, OpenCode, Pi) with a
• Integrated merge workflow: commit, push, create PR, and cleanup with m
• Drag-and-drop and keyboard-resizable pane splits

Sessions Screen

Press 8 or navigate to Sessions in the navbar to monitor and manage all active agent sessions, shells, and git worktrees across every configured project in one centralized screen.

Features:

• Cross-project session overview categorized by status (Needs Attention, Working, Live, Idle)
• Live preview pane showing real-time agent output, activity, and diffs
• Fast filtering (/), sorting, and instant project/session switching (Enter)
• Seamless transition between global session overview and project workspaces

Git Status

View staged, modified, and untracked files with a split-pane interface. The sidebar shows files and recent commits; the main pane shows syntax-highlighted diffs. Full documentation →

Features:

• Stage/unstage files with s/u
• View diffs inline or full-screen with d
• Toggle side-by-side diff view with v
• Browse commit history and view commit diffs
• Auto-refresh on file system changes

TD Monitor

Integration with TD, a task management system designed for AI agents working across context windows. TD helps agents track work, log progress, and maintain context across sessions. Full documentation →

Features:

• Current focused task display
• Scrollable task list with status indicators and priority badges
• Activity log with session context
• Quick review submission with r and approval with a

See the TD repository for installation and CLI usage.

File Browser

Navigate project files with a tree view and syntax-highlighted preview. Full documentation →

Features:

• Collapsible directory tree
• Code preview with syntax highlighting
• Auto-refresh on file changes
• Quick file opening into workspace splits

In-App Configuration

Press , (comma) or run sidecar setup to open the full in-app Configuration interface. Adjust project settings, appearance, terminal behavior, agent integrations, and view system diagnostic checks with live feedback.

Configuration Pages:

• Sidecar Setup: System readiness checks (tmux version, truecolor support, project roots, AGENTS.md instructions) with one-key guided repairs
• Appearance: Live theme selection, swatches, and custom color overrides
• Projects: Add, remove, and manage configured projects and paths
• Workspaces & Terminal: Customize default agents, shell creation, terminal scrollback, and tmux settings
• Panels & Integrations: Configure external terminal resource providers (e.g., Jira and GitHub link matchers)
• Diagnostics & About: System info, update checks, and troubleshooting tools

Project Switcher

Press @ to switch between configured projects without restarting sidecar.

1. Add projects to ~/.config/sidecar/config.json or using the in-app Configuration UI:

{
  "projects": {
    "list": [
      { "name": "sidecar", "path": "~/code/sidecar" },
      { "name": "td", "path": "~/code/td" },
      { "name": "my-app", "path": "~/projects/my-app" }
    ]
  }
}

1. Press @ to open the project switcher modal
2. Select with j/k or click, press Enter to switch

All plugins reinitialize with the new project context. State (active plugin, cursor positions) is remembered per project.

Worktree Switcher

Press W to switch between git worktrees within the current repository. When you switch away from a project and return later, sidecar remembers which worktree you were working in and restores it automatically.

Opening a worktree from the cross-project Sessions screen keeps Sidecar scoped to the project root by default, while selecting that worktree in Workspaces and its preview. To instead enter the selected worktree's scope, set:

{
  "plugins": {
    "workspace": {
      "overviewWorktreeScope": "worktree"
    }
  }
}

Themes

Press # to open the theme switcher or navigate to Appearance in Configuration. Choose from 21 curated built-in themes (including Sidecar Modern, Dracula, Catppuccin Mocha, Tokyo Night Storm, Gruvbox Dark, Nord, Kanagawa Wave, Rose Pine, Everforest Dark, Solarized Dark, Monokai Pro, and more) with instant live preview.

Custom color overrides and theme preferences can be set in ~/.config/sidecar/config.json or directly in the in-app Configuration UI.

See Theme Creation Skill for custom theme creation and color palette reference.

Sidecar additions

Standalone executables that extend Sidecar over a frozen protocol. Sidecar does not import them, and they do not import Sidecar. The only coupling is one JSON object in and one JSON object out.

Write your own against the terminal resource provider protocol: a provider is any executable that reads one JSON request on stdin, writes one JSON response on stdout, and declares the resource patterns it recognizes.

Keyboard Shortcuts

Workspace Shortcuts

Git Status Shortcuts

Configuration

Config file: ~/.config/sidecar/config.json (or configure interactively via , / sidecar setup)

{
  "plugins": {
    "git-status": { "enabled": true, "refreshInterval": "1s" },
    "td-monitor": { "enabled": true, "refreshInterval": "2s" },
    "file-browser": { "enabled": true },
    "workspace": { "enabled": true }
  },
  "ui": {
    "showClock": true,
    "terminalTitle": "{project}{worktree}",
    "theme": {
      "name": "default",
      "overrides": {}
    }
  }
}

terminalTitle names the terminal window/tab after the active project — handy when several sidecars are open at once. Variables: {project}, {worktree}, {plugin}, {dir}; set it to "" to leave the title alone.

Contributing

• Bug reports: Open an issue
• Feature requests: Check the Sidecar Roadmap for planned features and backlog