Introduction
Sidecar is a CLI-first project memory tool for developers and AI coding agents. It lives inside your repository and gives you a structured place to record the things that code alone can't capture.
Git tells you what changed. Sidecar tells you why.
Why developers use Sidecar
Most developers lose context between sessions. You can see code changes in git, but not always:
- Why an approach was chosen
- What tradeoffs were discussed
- What was deferred for later
- What an AI agent already discovered while debugging
Sidecar gives your project a shared memory layer so humans and agents can pick up where the last session ended instead of re-learning the same context.
How Sidecar works
In day-to-day use, most developers follow a simple loop:
- Read context at the start with
sidecar context. - Do work and record decisions/worklogs/tasks as you go.
- Refresh summary so the next session starts with current context.
What Sidecar stores
Sidecar organizes project memory into six types of records:
sidecar decision record Architectural choices and their rationale
sidecar worklog record What was done, and what files changed
sidecar task add Follow-up work to track inside the project
sidecar note Observations, warnings, loose thoughts
sidecar summary refresh Structured snapshot of recent project state
sidecar preferences Project conventions and style guidance
Where to start
If you're new to Sidecar, start with the Getting Started guide:
- Install the CLI
- Run
sidecar initin a project - Understand the files that get created
- Record your first decision or work log
Documentation overview
Getting Started
Install, initialize, and understand what Sidecar creates in your project.
Commands
Complete reference for all Sidecar CLI commands with examples.
Agent Workflow
How AI coding agents use Sidecar as shared project memory.
Instructions Templates
Create reusable init templates that generate project instructions.md.
Prompt Token Budgeting
How Sidecar automatically trims prompt size while keeping execution-critical sections.
Workflow Examples
A practical day-to-day command flow for human + agent collaboration.
Runners & Replay
Execute tasks with codex or claude, chain runners into pipelines, and replay runs.
Prompt Compile
Compile prompts from task packets or freestanding YAML/JSON specs.
Claude Code Hooks
Ambient capture of sessions, file edits, and prompts into project memory.
Preferences
Store project-level conventions and guidance for humans and agents.
Storage & Data
How Sidecar stores data locally with SQLite and generated summaries.
Design principles
Sidecar is built around a few decisions that shape how it works:
- Local-first. Everything lives in
.sidecar/inside your project. No cloud, no account, no sync. - CLI-first. The command line is the primary interface. Automation-friendly by design.
- Structured over freeform. Records have defined types so summaries are reliable and queryable.
- Works for both humans and agents. The same commands work whether a person or an AI is running them.