Getting Started

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

Why use Sidecar?

Sidecar helps you keep project context that usually gets lost across days, teammates, and AI sessions. Instead of relying on memory or long chat history, you store decisions, work logs, tasks, and notes directly in the project.

If you use AI coding agents, this is especially useful: each new session can start with sidecar context so the agent sees what already happened and why.

How it works in practice

1. Initialize once with sidecar init.
2. Record important context while building (decisions, worklogs, tasks, notes).
3. Run sidecar summary refresh so future sessions start with up-to-date memory.

Requirements

• Node.js 22+ (Sidecar uses the built-in node:sqlite module)
• npm

Installation

Install the sidecar-cli package globally via npm:

$ npm install -g sidecar-cli

Or install a pre-release channel to try features before they're promoted:

# beta — newest features, may change
$ npm install -g sidecar-cli@beta

# rc — release candidates during a stable cut
$ npm install -g sidecar-cli@rc

Or install with Homebrew (tracks the stable channel only):

$ brew tap karlhills/sidecar
$ brew install sidecar
# to upgrade later:
$ brew update && brew upgrade sidecar

Or run without installing:

$ npx sidecar-cli --help
$ npx sidecar-cli@beta --help

Release channels

Sidecar ships features through beta → rc → stable as version bumps — there are no per-feature channel flags. Install @beta to try new features early; install default (stable) for the latest promoted release.

Features marked with a Beta badge elsewhere in these docs ship on the beta channel. Install sidecar-cli@beta to use them. Per-version release notes live at github.com/karlhills/sidecar-cli/releases.

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
  [■]─[▪]
  ███████╗██╗██████╗ ███████╗ ██████╗ █████╗ ██████╗
  ██╔════╝██║██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗
  ███████╗██║██║  ██║█████╗  ██║     ███████║██████╔╝
  ╚════██║██║██║  ██║██╔══╝  ██║     ██╔══██║██╔══██╗
  ███████║██║██████╔╝███████╗╚██████╗██║  ██║██║  ██║
  ╚══════╝╚═╝╚═════╝ ╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝

Initialized Sidecar for project: my-project
Documentation: https://usesidecar.dev/

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

Initialize with instructions templates

You can also generate a project-level instructions.md during sidecar init by using a reusable template.

$ sidecar init --instructions-template web-app

See Instructions Templates for template setup, direct-file usage, and troubleshooting.

What gets created

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

my-project/
├── src/
├── AGENTS.md             # Agent instructions (repo root — visible before .sidecar lookup)
├── CLAUDE.md             # Claude Code project instructions
├── .sidecar/
│   ├── tasks/            # Task packets and task metadata
│   ├── runs/             # Run artifacts and execution records
│   ├── prompts/          # Saved prompts and prompt packs
│   ├── 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:

# 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

• Commands reference — all available commands with examples
• Instructions Templates — generate project instructions.md during init
• Agent Workflow — how to configure Sidecar for AI agents
• Preferences — store project conventions
• Storage & Data — understand the local data model