[■]─[▪] sidecar
Get Started
Documentation

Getting Started

This guide walks you through installing Sidecar, initializing it in a project, and understanding the files it creates.

Requirements

  • Node.js 20+
  • npm

Installation

Install the sidecar-cli package globally via npm:

terminal 
$ npm install -g sidecar-cli

Or install with Homebrew:

$ brew tap karlhills/sidecar
$ brew install sidecar

Or run without installing:

$ npx sidecar-cli --help

Verify the installation:

$ sidecar --version
sidecar/1.0.0

Initialize a project

Navigate to any project directory and run sidecar init. This creates the .sidecar/ folder and all required files. 

$ cd my-project
$ sidecar init
✓ Created .sidecar/sidecar.db
✓ Created .sidecar/config.json
✓ Created .sidecar/preferences.json
✓ Created .sidecar/AGENTS.md
✓ Created .sidecar/summary.md
✓ Created AGENTS.md
✓ Created CLAUDE.md

Ready. Run `sidecar context` to get started.

Use --force to overwrite any existing Sidecar-managed files.

What gets created

After sidecar init, your project will have a .sidecar/ directory plus two files at the repo root:

Project structure 
my-project/
├── src/
├── AGENTS.md             # Agent instructions (repo root — visible before .sidecar lookup)
├── CLAUDE.md             # Claude Code project instructions
├── .sidecar/
│   ├── sidecar.db         # SQLite database (all records)
│   ├── config.json       # Project config (name, version)
│   ├── preferences.json  # Project conventions and preferences
│   ├── AGENTS.md         # Detailed agent workflow instructions
│   └── summary.md        # Auto-generated project summary
└── ...

sidecar.db

The SQLite database that stores all records: decisions, work logs, tasks, notes, sessions, and artifacts. This is the source of truth for all Sidecar data.

config.json

Basic project metadata including the project name and Sidecar version. Rarely edited directly.

preferences.json

Project-level preferences and conventions. These can guide agents and inform how the project is worked on. See the Preferences page for details.

AGENTS.md (root + .sidecar/)

Instructions for AI coding agents. The root AGENTS.md is placed at the repo root so the policy is visible before any .sidecar/ lookup. The .sidecar/AGENTS.md contains the detailed workflow. See the Agent Workflow guide.

CLAUDE.md

Project instructions for Claude Code specifically. References the Sidecar workflow so Claude automatically records decisions and worklogs during AI-assisted sessions.

summary.md

A structured summary of the project generated from recent Sidecar records. Refreshed by running sidecar summary refresh.

Your first session

Once initialized, here's a typical flow:

A first session bash 
# See what context exists (will be empty at first)
$ sidecar context

# Record a decision you've already made
$ sidecar decision record \
    --title "Use SQLite for local storage" \
    --summary "Simple, zero-config, works offline — right for v1"

# Log what you worked on
$ sidecar worklog record \
    --goal "Set up project structure" \
    --done "Created folder layout and initial config" \
    --files src/index.ts,src/config.ts

# Add a follow-up task
$ sidecar task add "Write unit tests for config module" --priority medium

# Refresh the project summary
$ sidecar summary refresh

Checking your context

At any time — especially at the start of a new session — run sidecar context to see a structured view of recent project activity: 

$ sidecar context --format markdown

This outputs recent decisions, open tasks, worklogs, and notes — formatted for easy reading or for passing directly to an AI coding agent as context.

What's next