Commands

Complete reference for all Sidecar CLI commands. Each command includes what it does, when to use it, and a usage example.

If you're new to Sidecar, read Getting Started first for the "why" and overall workflow. This page is a command-by-command reference.

Looking for setup details on --instructions-template and --instructions-file? See Instructions Templates.

Looking for automatic prompt trimming and token budget behavior? See Prompt Token Budgeting.

Two namespaces: log and work

Sidecar is one CLI with two jobs: capture local project memory (sidecar log <cmd>) and run agents against that memory (sidecar work <cmd>). The underlying verbs still work directly — sidecar worklog record ... and sidecar log worklog record ... are equivalent. Pick whichever reads best in your workflow.

Channel badges: Beta = ships on the beta channel · RC = release candidate · no badge = stable. See Release channels.

Stable JSON contract

All commands that accept --json return a consistent envelope treated as a public integration contract:

 { "ok": true, "version": "1.0", "command": "task add", "data": { ... }, "errors": [] } 

version is the JSON contract version — stable across CLI and DB schema changes.

Project Decisions Work Logs Tasks Runners Prompts Hooks Notes Sessions Artifacts Preferences Summary Events Export UI

Project

sidecar init

 sidecar init [--force] [--name <project-name>] [--instructions-template <name>] [--instructions-file <absolute-path>] [--json] 

Initialize Sidecar in the current directory. Creates .sidecar/ (tasks, runs, prompts, database, config, preferences, AGENTS.md, summary.md), plus AGENTS.md and CLAUDE.md at the repo root. You can optionally generate project instructions.md from either a named template or a direct file path (use one, not both). Sidecar will not overwrite existing instructions.md unless --force is used.

When:

Once per project, at the start.

Example

$ sidecar init --name my-project --instructions-template web-app

sidecar status

sidecar status

Show a quick overview of the project: name, record counts, last activity.

When:

When you want a health check on the project's memory.

Example

$ sidecar status

sidecar context

sidecar context [--limit <n>] [--format text|markdown|json]

Output structured context: recent decisions, open tasks, recent worklogs, notes. The primary way to orient yourself — or an agent — at the start of a session.

When:

Always at the start of a session.

Example

$ sidecar context --format markdown

sidecar recent

sidecar recent [--limit N]

Show the most recent records across all types, ordered by time.

When:

When you want a quick timeline of recent activity.

Example

$ sidecar recent --limit 10

sidecar capabilities

sidecar capabilities [--json]

List available Sidecar commands and features. The --json output is a strong discovery surface for agents and tooling, including cli_version, json_contract_version, features, and full command/subcommand/options metadata with JSON support indicators.

When:

Rarely needed by humans. Essential for agent bootstrapping and external tooling integration.

Example

$ sidecar capabilities --json

sidecar demo Beta

sidecar demo [--cleanup] [--json]

Spin up a throwaway demo project with seeded decisions, worklogs, tasks, and runs so you can try the full Sidecar surface (context, mission, runs) without touching a real codebase. Use --cleanup to tear it down.

When:

First-time exploration, or when reproducing an issue against a known-good dataset.

Example

$ sidecar demo

sidecar doctor

sidecar doctor [--json]

Alias for `sidecar session verify` — runs a quick health check on the current session and project state.

When:

When something feels off with session accounting or when opening a bug report.

Example

$ sidecar doctor

Decisions

sidecar decision record

 sidecar decision record --title "<title>" --summary "<summary>" [--details "<details>"] [--by human|agent] [--json] 

Record an architectural or design decision with a title and a short explanation of why it was made. Use --details for longer context.

When:

Whenever a meaningful design or architecture choice is made.

Example

 $ sidecar decision record \
    --title "Use SQLite for local storage" \
    --summary "Simple, zero-config, works offline — right for v1" 

Work Logs

sidecar worklog record

 sidecar worklog record --done "<summary>" [--goal "<goal>"] [--files a,b] [--risks "<text>"] [--next "<text>"] [--by human|agent] [--json] 

Record a log of completed work: what you set out to do, what got done, and which files changed. Optionally note risks and next steps.

When:

At the end of a meaningful unit of work or a session.

Example

 $ sidecar worklog record \
    --goal "Add task support" \
    --done "Implemented add/list/done commands" \
    --files src/tasks.ts,src/cli.ts \
    --by agent 

Tasks

sidecar task add

 sidecar task add "<title>" [--description "<text>"] [--priority low|medium|high] [--by human|agent] [--json] 

Add a lightweight follow-up task to the project. Useful for capturing work that should happen later without losing track of it.

When:

When you notice something that needs doing but you're not doing it right now.

Example

$ sidecar task add "Add import/export support" --priority medium

sidecar task create Beta

 sidecar task create --title "<title>" --summary "<summary>" --goal "<goal>" [--validate-cmds "kind:cmd,..."] [--json] 

Create a full task packet with structured fields that feed a runner: summary, goal, scope, validation commands (tagged with kind), and more. This is the form `sidecar run` consumes.

When:

When you plan to execute the task with an agent runner and want validation routed through typed kinds.

Example

 $ sidecar task create \
    --title "Add import flow" \
    --summary "Support CSV import for users" --goal "Import happy path lands" \
    --validate-cmds "typecheck:tsc --noEmit,lint:eslint .,test:npm test" 

sidecar task list

sidecar task list [--status open|done|all] [--format table|json]

List tasks, optionally filtered by status.

When:

To see what follow-up work is outstanding.

Example

$ sidecar task list --status open

sidecar task done

sidecar task done <id>

Mark a task as completed.

When:

When you've finished a task that was recorded with sidecar task add.

Example

$ sidecar task done 42

Runners

sidecar run

 sidecar run <task-id> [--runner codex|claude|codex,claude] [--agent-role <role>] [--dry-run] [--json] 

Execute a task packet against a coding agent. Records the run with compiled prompt, runner output, validation results, and changed files. Pass a comma-separated `--runner` list to chain runners sequentially as a pipeline.

When:

When you want an agent to execute a task packet end-to-end with a full audit trail.

Example

$ sidecar run T-001 --runner claude --agent-role builder-app

sidecar run replay Beta

 sidecar run replay <run-id> [--runner <r>] [--agent-role <role>] [--reason "<text>"] [--edit-prompt] [--dry-run] [--json] 

Start a fresh run against the same task, linked back to the original via parent_run_id and replay_reason. Useful to retry with a different runner, re-run after fixing a blocker, or fork a green run into an experiment.

When:

When you want another pass against the same task without losing the audit trail.

Example

$ sidecar run replay R-001 --runner claude --reason "retry after codex blocker"

sidecar run list / show / queue / start-ready

 sidecar run list [--task <task-id>] [--json]
sidecar run show <run-id> [--json]
sidecar run queue [--json]
sidecar run start-ready [--dry-run] [--json] 

Inspect runs: list by task, show full detail (prompt path, lifecycle, validation, changed files), view the ready-to-run queue, or start every task with status `ready`.

When:

Day-to-day inspection and batch operations over the runner surface.

Example

$ sidecar run show R-007

Prompts

sidecar prompt compile

 sidecar prompt compile <task-or-file> [--runner <r>] [--agent-role <role>] [--budget <n>] [--budget-max <n>] [--section-policy id=keep|trim-last|drop,...] [--explain] [--format json] [-o <path>] 

Compile a task packet (by id) or a freestanding YAML/JSON spec into a single prompt, with deterministic trimming and a token budget. Returns markdown by default or a JSON envelope with a section-by-section trace. Freestanding spec files (YAML/JSON) are a beta feature — see the Prompt Compile guide.

When:

When iterating on a prompt or composing one programmatically outside of a full run.

Example

$ sidecar prompt compile T-001 --explain

Hooks

sidecar hooks print Beta

sidecar hooks print

Print a ready-to-paste Claude Code settings block that wires ambient capture. Paste into `.claude/settings.json` or `~/.claude/settings.json`.

When:

Once per project (or once in user settings) to enable ambient capture of sessions, file edits, and prompts.

Example

$ sidecar hooks print

sidecar hook Beta

 sidecar hook <session-start|session-end|file-edit|user-prompt> [--actor-name <name>] [--json] 

Claude Code hook bridge. Reads a JSON payload on stdin and records the matching Sidecar event (session open/close, worklog + artifact for file edits, or a note for user prompts). Always exits 0 — never blocks the caller.

When:

Called automatically by Claude Code once hooks are wired. Also usable from any shell hook or wrapper.

Example

 $ echo '{"tool_name":"Edit","tool_input":{"file_path":"README.md"}}' | sidecar hook file-edit 

Notes

sidecar note

sidecar note "<text>" [--by agent]

Record a short note — an observation, warning, or thought that doesn't fit neatly into another record type.

When:

For lightweight, freeform capture. Not everything needs to be a decision or worklog.

Example

$ sidecar note "Auth module is fragile — avoid changing token format"

Sessions

sidecar session start

sidecar session start [--actor human|agent] [--name "<actor-name>"] [--json]

Start a work session. Groups subsequent records under a shared session. Use --actor to tag who is running the session.

When:

When starting a focused work block, especially for agent sessions.

Example

$ sidecar session start --actor agent --name codex

sidecar session end

sidecar session end [--summary "<summary>"]

End the current session and optionally record a summary of what happened.

When:

At the end of a session started with sidecar session start.

Example

$ sidecar session end --summary "Refactored token validation, tests passing"

sidecar session current

sidecar session current

Show the currently active session, if any.

When:

To check whether a session is active.

Example

$ sidecar session current

sidecar session verify

sidecar session verify

Verify the integrity of the current session's records.

When:

Rarely needed. Useful for diagnostics.

Example

$ sidecar session verify

Artifacts

sidecar artifact add

 sidecar artifact add <path> [--kind file|doc|screenshot|other] [--note "<text>"] [--json] 

Attach a file or path to the project as a tracked artifact. Useful for referencing outputs, screenshots, or generated files alongside your records.

When:

When a file produced during work should be noted in project memory.

Example

 $ sidecar artifact add dist/report.pdf --kind doc --note "Generated audit report" 

sidecar artifact list

sidecar artifact list [--json]

List all tracked artifacts for the project.

When:

To review what files have been linked to project memory.

Example

$ sidecar artifact list

Preferences

sidecar preferences show

sidecar preferences show [--json]

Display the current project preferences. Use --json to get a stable machine-readable response for scripts and agents.

When:

To review what conventions and preferences are stored, or to read them programmatically.

Example

$ sidecar preferences show --json

sidecar preferences edit

sidecar preferences edit

Open the preferences file in your default editor.

When:

To update multiple preferences at once.

Example

$ sidecar preferences edit

sidecar preferences set

sidecar preferences set <key> <value>

Set a single preference by key.

When:

To update a specific preference without opening the editor.

Example

$ sidecar preferences set language TypeScript

Summary

sidecar summary refresh

sidecar summary refresh

Regenerate the project summary from all recent records and write it to .sidecar/summary.md.

When:

After completing meaningful work, especially at the end of a session.

Example

$ sidecar summary refresh

Events

sidecar event add

 sidecar event add --type <type> [--title <title>] [--summary <text>] [--created-by <who>] [--source <source>] [--json-input <json>] [--stdin] [--json] 

A generic validated ingest path for external tools, scripts, and agents to write Sidecar events without direct database access. Supports three mutually exclusive input modes: structured flags, raw JSON (--json-input), or piped STDIN JSON (--stdin). Supported types: note, decision, worklog, task_created, task_completed, summary_generated. Validation rules: note/worklog/task_created/task_completed require summary; decision requires title + summary; summary_generated has no required fields. Defaults: created_by = system, source = cli.

When:

When external tools, automations, or agents need to write Sidecar events through a validated interface rather than direct CLI commands.

Example

 $ sidecar event add \
    --type decision \
    --title "Use SQLite" \
    --summary "Simple local storage for v1" \
    --created-by agent \
    --json

# Raw JSON input
sidecar event add --json-input '{"type":"note","summary":"Captured context"}' --json

# STDIN
cat event.json | sidecar event add --stdin --json 

Export

sidecar export

 sidecar export [--format json|jsonl] [--limit <n>] [--type <type>] [--since <iso-date>] [--until <iso-date>] [--output <path>] 

Export Sidecar project memory for external systems, backups, or pipelines. --format json: Full object export with project, preferences, sessions, tasks, artifacts, and events. Shape: { "version": "1.0", "project": {...}, "preferences": {...}, "events": [...] } --format jsonl: Events-only stream, one JSON object per line. Shape: { "version": "1.0", "record_type": "event", "project_id": 1, "data": {...} } Output directories are created automatically when using --output.

When:

To back up project memory, pipe Sidecar data into external systems, or generate event streams for analysis.

Example

 $ sidecar export --format json --output ./exports/sidecar.json

sidecar export --format jsonl --since 2026-01-01 > events.jsonl

sidecar export --format json --type decision --limit 50 

UI

sidecar ui

sidecar ui [--port <number>]

Start a local web dashboard for the current project. Opens a browser UI where you can browse decisions, work logs, tasks, notes, and sessions without using the CLI. Runs entirely on localhost — no data leaves your machine.

When:

When you want a visual overview of your project memory, or to share context with teammates who prefer a UI over the terminal.

Example

$ sidecar ui