# Output styles

Control how Droid structures and writes responses in interactive CLI sessions.

Output styles add response-writing instructions to interactive Droid CLI sessions. Choose a
built-in style or create a Markdown file for a personal, project, or shared team style.

## Choose an output style

1. Start an interactive session with `droid`.
2. Enter `/settings`.
3. Select **Output style**.
4. Choose a built-in or custom style.

Droid includes two built-in styles:

<PropertyList>
  <Property name='Default'>
    Use Droid's standard response style.
  </Property>
  <Property name='Concise'>
    Return short, direct responses without unnecessary detail.
  </Property>
</PropertyList>

The picker shows where each custom style came from, such as a user, project, or plugin. Your
selection is saved as the `outputStyle` setting in `~/.factory/settings.json`.

## Create a custom style

Create an `output-styles` directory at the scope where you want the style to be available:

| Scope | Location |
| :---- | :------- |
| User | `~/.factory/output-styles/<name>.md` |
| Project | `<repo>/.factory/output-styles/<name>.md` |
| Folder | `<repo>/<project-area>/.factory/output-styles/<name>.md` |
| Plugin | `<plugin>/output-styles/<name>.md` |

Droid loads direct `.md` children of each `output-styles` directory. Nested files and other
file types are ignored.

Each file contains optional YAML frontmatter followed by the instructions Droid should apply:

```markdown title="~/.factory/output-styles/review-notes.md"
---
name: Review Notes
description: Put findings before the summary
---

Start with actionable findings, ordered by severity.

Keep the summary to two sentences.
```

`name` appears in the picker and defaults to the filename without `.md`. `description` appears
below the name in the picker. Keep the Markdown body focused on response presentation.
Repository instructions, tool permissions, and user requests still apply.

<Note>
  Droid uses the style content available when a session sends its first request. Start a new
  session to use edits to that style. Selecting a different style takes effect on the next
  request.
</Note>

## Scope and precedence

Output styles apply only to interactive Droid CLI sessions. They do not change responses from
`droid exec`, Automations, Missions, subagents, the Factory App, or web sessions.

Droid combines styles from the active settings hierarchy and enabled plugins. Higher-priority
sources win when the same style is provided more than once. The built-in `Default` and
`Concise` styles are reserved and cannot be replaced.

When Droid asks you to trust a working folder, review its style files before accepting.
Project and folder styles, including styles from project-scoped plugins, remain unavailable
until the folder is trusted.

## Troubleshooting

<Troubleshooting>
  <TroubleshootingItem title="A custom style is disabled">
    Confirm the style is a direct `.md` child of `output-styles/` with a non-empty body. Run
    `/diagnostics` to see the source path and validation error, including when a style exceeds
    the size limit. Diagnostics do not include the style's instruction body.
  </TroubleshootingItem>

  <TroubleshootingItem title="Droid uses Default instead of the saved style">
    Confirm the style still exists, passes validation, comes from a trusted folder, and belongs
    to an enabled plugin. Droid keeps an unavailable selection but uses **Default** until the
    style becomes available again.
  </TroubleshootingItem>
</Troubleshooting>

<RelatedLinks>
  <RelatedLink href='/droid-cli/settings' title='CLI settings'>
    Configure the saved output style and other Droid preferences.
  </RelatedLink>
  <RelatedLink href='/harness/plugins' title='Plugins'>
    Package output styles with reusable Droid extensions.
  </RelatedLink>
  <RelatedLink href='/droid-cli/cli-reference' title='CLI reference'>
    Review interactive commands and headless output formats.
  </RelatedLink>
  <RelatedLink href='/enterprise/hierarchical-settings-and-org-control' title='Settings hierarchy'>
    See how organization, folder, project, and user sources resolve.
  </RelatedLink>
</RelatedLinks>