Sidecar

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

Sidecar puts your entire development workflow in one shell: plan tasks with td, chat with AI agents, review diffs, stage commits, and manage workspaces—all without leaving Sidecar. (Optional: multi-agent session history via the Conversations plugin.)

brew install marcus/tap/sidecar

This builds from source and avoids macOS Gatekeeper warnings.

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

More options: Binary downloads · Manual install

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

After installation, run from any project directory:

sidecar

Split your terminal horizontally: run your coding agent (Claude Code, Cursor, etc.) on the left and sidecar on the right.

┌─────────────────────────────┬─────────────────────┐
│                             │                     │
│   Claude Code / Cursor      │      Sidecar        │
│                             │                     │
│   $ claude                  │   [Git] [Files]     │
│   > fix the auth bug...     │   [Tasks] [Workspaces]│
│                             │                     │
└─────────────────────────────┴─────────────────────┘

Tip: You can run two sidecar instances side-by-side to create a dashboard view. For example, keep one on the [Tasks] plugin and the other on [Git] or [Workspaces] to monitor everything at once.

As the agent works, you can:

• Watch tasks move through the workflow in TD Monitor
• See files change in real-time in the Git plugin
• Browse and edit code yourself in the File Browser
• Optionally browse multi-agent session history (Conversations plugin; opt-in feature flag)
• Switch between built-in and community themes with live previews

This setup gives you visibility into what the agent is doing without interrupting your workflow. The entire dev loop—planning, monitoring, reviewing, committing—happens in the terminal while agents write the code.

# Run from any project directory
sidecar

# Specify project root
sidecar --project /path/to/project

# Enable debug logging
sidecar --debug

# Check version
sidecar --version

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.

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

Browse session history from multiple AI coding agents with message content, token usage, and search. Supports Amp Code, Claude Code, Codex, Cursor CLI, Gemini CLI, GitHub Copilot CLI, Kiro, OpenCode, Pi Agent, and Warp. Full documentation →

Off by default. Enable the conversations_plugin feature flag:

{
  "features": {
    "flags": {
      "conversations_plugin": true
    }
  }
}

Or: sidecar --enable-feature=conversations_plugin. When disabled, Sidecar does not load history adapters or read agent session stores.

Features:

• Unified view across all supported agents
• View all sessions grouped by date
• Search sessions with /
• Expand messages to see full content
• Track token usage per session

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—essential for AI-assisted development where context windows reset between conversations. Full documentation →

Features:

• Current focused task display
• Scrollable task list with status indicators
• Activity log with session context
• Quick review submission with r

See the TD repository for installation and CLI usage.

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

Manage workspaces for parallel development with integrated agent support. Create isolated branches as sibling directories, link tasks from TD, and launch coding agents directly from sidecar. Full documentation →

Features:

• Create and delete workspaces with n/D
• Link TD tasks to workspaces for context tracking
• Launch coding agents (Claude, Codex, Gemini, Cursor, OpenCode, Pi) with a
• Merge workflow: commit, push, create PR, and cleanup with m
• Auto-adds sidecar state files to .gitignore
• Preview diffs and task details in split-pane view

Press @ to switch between configured projects without restarting sidecar.

1. Add projects to ~/.config/sidecar/config.json:

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

2. Press @ to open the project switcher modal
3. 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.

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 Overview 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"
    }
  }
}

Press # to open the theme switcher. Choose from built-in themes (default, dracula) or press Tab to browse 453 community color schemes derived from iTerm2-Color-Schemes.

The community browser supports search filtering, live preview as you navigate, and color swatches for each scheme. Press Enter to save a scheme as your active theme.

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

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 }
  },
  "features": {
    "flags": {
      "conversations_plugin": false
    }
  },
  "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.

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

make build            # Build to ./bin/sidecar
make test             # Run Go tests
make test-dev-install # Test managed install switching in an isolated fake prefix
make test-v           # Verbose Go test output
make install-local    # Activate the canonical main checkout
make install-worktree # Deliberately activate the current branch/worktree
make install-status   # Show managed link plus current/login shell resolution
make use-homebrew     # Restore the installed Homebrew release
make install          # Unmanaged go install to GOBIN (does not change Homebrew)
make fmt              # Format code
make fmt-check        # Verify formatting for changed Go files
make fmt-check-all    # Verify formatting across full codebase
make lint             # Lint new issues only (merge-base with main)
make lint-all         # Lint entire codebase (includes legacy debt)
make install-hooks    # Install pre-commit hooks (gofmt, go vet, go build)

make install-local refuses branches and linked worktrees so an incidental checkout cannot silently replace the normal development binary. Use make install-worktree when that replacement is intentional. Both managed commands require Homebrew; use make install for a separate, unmanaged Go installation.

• Formatting: changed Go files must be gofmt-clean (make fmt-check)
• Correctness lint: errcheck, govet, ineffassign, staticcheck, unused
• Enforcement: CI runs tests and blocks new lint issues on PRs (.github/workflows/go-ci.yml)
• Debt tracking: run make lint-all to measure and burn down legacy lint debt

Sidecar runs locally and makes no telemetry, analytics, or tracking requests. The only network calls are GitHub API version checks on startup (cached for 3 hours) and user-initiated changelog fetches. See PRIVACY.md for full details on data access, file reads/writes, and network behavior.

MIT