nixpkgs/docs/packages/sidecar.md

# sidecar

A companion tool for CLI coding agents, providing diffs, file trees, conversation history, and task management with td integration.

## Description

sidecar is a terminal UI tool designed to enhance the experience of using AI coding agents in the terminal. It provides a side panel interface for viewing diffs, file trees, conversation history, and integrates with `td` for task management across coding sessions.

## Features

- 🔀 **Diff Viewer**: Visual diff display for code changes
- 📁 **File Tree**: Navigate and understand project structure
- 💬 **Conversation History**: Review and search past AI interactions
- ✅ **Task Management**: Integrated with `td` for tracking tasks
- 🖥️ **Terminal UI**: Clean interface using tmux panes
- 🤖 **AI Agent Integration**: Designed to work with opencode and similar CLI agents

## Installation

### Via Overlay

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    sidecar
  ];
}
```

### Direct Reference

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.sidecar
  ];
}
```

### Run Directly

```bash
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#sidecar
```

## Usage

### Starting sidecar

```bash
# Start sidecar alongside your AI coding agent
sidecar

# Start with a specific agent
sidecar --agent opencode
```

### Basic Commands

```bash
# Show help
sidecar --help

# Check version
sidecar --version
```

## Dependencies

sidecar is packaged with the following runtime dependencies:

- **opencode**: AI coding agent
- **td**: Task tracking CLI
- **tmux**: Terminal multiplexer for UI layout

These are automatically included in the PATH when running sidecar.

## Workflow Integration

### Typical Session

1. Start `sidecar` in your project directory
2. The tool opens a tmux session with panes for:
   - Your AI coding agent (opencode)
   - Task list (via td)
   - Diff viewer
   - File tree navigator
3. Work with your AI agent as usual
4. View diffs and changes in real-time
5. Track tasks using the integrated td panel

### With opencode

```bash
# sidecar automatically integrates with opencode
cd your-project
sidecar
```

## Configuration

### Environment Variables

- `SIDECAR_CONFIG`: Custom configuration file path
- `SIDECAR_AGENT`: Default AI agent to use (default: opencode)

### Customization

Configuration is managed through sidecar's own config system. See the upstream documentation for details.

## Build Information

- **Version**: 0.71.1
- **Language**: Go
- **License**: MIT
- **Source**: [GitHub](https://github.com/marcus/sidecar)

## Platform Support

- Linux
- macOS (Unix systems)

## Notes

- Tests are disabled in the Nix package build
- The package wraps the binary with required dependencies (opencode, td, tmux) in PATH
- Version check is enabled for the Nix package

## Related

- [td](./td.md) - Task tracking CLI used by sidecar
- [opencode](./opencode.md) - AI coding agent integration
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide