Preferences

Sidecar preferences are project-level conventions stored in .sidecar/preferences.json. They're intended to capture the things that shape how your project is worked on — language choices, code style, architectural guidelines, and anything else that's easy to forget or explain wrong.

What preferences are for

Preferences answer questions like:

• What language and runtime does this project use?
• What's the preferred style guide or formatter?
• Are there things agents should avoid or always do?
• What's the testing convention?
• Are there naming conventions or folder structure rules?

This is different from documentation — it's structured guidance, not prose. When an agent reads project context, it can reference preferences to make better choices without asking you every time.

How preferences are stored

Preferences live in .sidecar/preferences.json as a flat or nested JSON object. The structure is flexible — you define the keys that matter for your project.

{
  "language": "TypeScript",
  "runtime": "Node.js 20+",
  "packageManager": "npm",
  "style": {
    "formatter": "Prettier",
    "linter": "ESLint",
    "quotes": "single",
    "semicolons": false
  },
  "testing": {
    "framework": "Vitest",
    "convention": "co-locate tests next to source files"
  },
  "conventions": [
    "Prefer functional patterns over classes",
    "Keep modules small — one responsibility per file",
    "Write tests before marking a feature done"
  ],
  "agentGuidance": [
    "Always run tests before recording a worklog",
    "Do not modify .sidecar/ files directly except via CLI",
    "Record decisions when choosing between two approaches"
  ]
}

Managing preferences

View current preferences

$ sidecar preferences show

Edit in your default editor

$ sidecar preferences edit

Set a single value

$ sidecar preferences set language TypeScript
$ sidecar preferences set packageManager pnpm

How preferences affect agent behavior

When an agent runs sidecar context, the output includes active preferences. A well-configured agent will use this to:

• Choose the right language and libraries without asking
• Follow the project's code style automatically
• Apply naming and structure conventions
• Respect agent-specific guidance

The more specific your preferences, the more consistently agents will work within your project's norms — without you needing to repeat them in every prompt.

Preferences vs decisions

The difference is scope and permanence:

A preference is "we use Prettier." A decision is "we switched from ESLint to Biome because it's 10x faster and we hit the performance wall."