Sidecar

Overview

Sidecar is a unified terminal-based development workflow management tool that integrates planning, AI agent monitoring, git operations, and workspace management in a single shell environment. Designed to be used alongside AI coding agents (Claude Code, Cursor, Codex, etc.), it provides visibility and control over the entire development process without leaving the terminal.

Status: Ready for daily use

Installation

Quick Install

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

Alternative Methods

• Homebrew: brew install marcus/tap/sidecar
• Binary downloads: GitHub Releases
• Manual install available

Requirements

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

Quick Start

From any project directory:

sidecar  

Suggested Setup

Split terminal horizontally with your coding agent on the left and Sidecar on the right:

• Watch tasks move through the workflow in real-time
• See files change in the Git plugin
• Browse and edit code in the File Browser
• View and resume conversations across all agent adapters
• Monitor everything without interrupting agent workflow

Core Plugins

Git Status

View and manage git operations with a split-pane interface:

• Features:
  • View staged, modified, and untracked files
  • 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
  • Syntax-highlighted diff view

Conversations

Browse session history from multiple AI coding agents:

• Supported Agents: Claude Code, Codex, Cursor CLI, Gemini CLI, OpenCode, Warp
• Features:
  • Unified view across all supported agents
  • View sessions grouped by date
  • Search sessions with /
  • Expand messages to see full content
  • Track token usage per session

TD Monitor

Integration with TD task management system for AI-assisted development:

• Features:
  • Current focused task display
  • Scrollable task list with status indicators
  • Activity log with session context
  • Quick review submission with r
  • Tracks work across context window resets

File Browser

Navigate project files with syntax highlighting:

• Features:
  • Collapsible directory tree
  • Code preview with syntax highlighting
  • Auto-refresh on file changes

Workspaces

Manage parallel development with isolated branches:

• Features:
  • Create and delete workspaces with n/D
  • Link TD tasks to workspaces for context tracking
  • Launch Claude Code, Cursor, or OpenRouter agents with a
  • Merge workflow: commit, push, create PR, cleanup with m
  • Auto-adds sidecar state files to .gitignore
  • Preview diffs and task details in split-pane

Project Management

Project Switcher

Press @ to switch between configured projects without restarting.

Configure in ~/.config/sidecar/config.json:

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

All plugins reinitialize with new project context. State is remembered per project.

Worktree Switcher

Press W to switch between git worktrees within the current repository. Sidecar remembers which worktree you were working in and restores it automatically.

Themes

Press # to open the theme switcher:

• Built-in themes: default, dracula
• 453+ community color schemes from iTerm2-Color-Schemes
• Search filtering and live preview
• Color swatches for each scheme

Command Options

sidecar                      # Run from current project  
sidecar --project /path     # Specify project root  
sidecar --debug             # Enable debug logging  
sidecar --version           # Check version  

Configuration

Config file: ~/.config/sidecar/config.json

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

Keyboard Shortcuts

Global

Key	Action
q, ctrl+c	Quit
@	Open project switcher
W	Open worktree switcher
#	Open theme switcher
tab / shift+tab	Navigate plugins
1-9	Focus plugin by number
j/k, ↓/↑	Navigate items
g/G	Jump to top/bottom
enter	Select
esc	Back/close
r	Refresh
?	Toggle help

Git Status

Key	Action
s	Stage file
u	Unstage file
d	View diff (full-screen)
v	Toggle side-by-side diff
h/l	Switch sidebar/diff focus
c	Commit staged changes

Workspaces

Key	Action
n	Create new workspace
D	Delete workspace
a	Launch/attach agent
t	Link/unlink TD task
m	Start merge workflow
p	Push branch
o	Open in finder/terminal

Updates

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

Use Cases

AI-Assisted Development

• Run Sidecar alongside Claude Code or Cursor to monitor agent progress
• View real-time git changes and task movement
• Browse conversation history across all agents
• Switch workspaces for parallel development

Task-Driven Development

• Integration with TD for context-aware task management
• Track work across context window resets
• Link tasks to workspaces for organized development

Collaborative Workflows

• Manage multiple worktrees for parallel features
• Create isolated workspace branches
• Track workspace merge workflows

Related

• TD - Task management system for AI agents
• Claude Code - AI coding agent
• Cursor - AI-powered code editor