How to use output styles with the sdk?

[brickfrog]

As far as I can tell output styles work in --print mode but not in --output-format stream-json mode, which is what the agent-sdk uses. Is there something I'm missing? I wanted to have an application mode switch output styles based on use-case, but seems like it doesn't honor them at all.

  # Create output style
  cat > ~/.claude/output-styles/test.md << 'EOF'
  ---
  name: test
  description: lowercase only
  ---

  use lowercase exclusively. respond with extreme brevity.

  examples:
  - instead of "Hello! How can I help?" → "hey"
  - instead of verbose explanations → concise answers
  EOF

  # Create settings file
  echo '{"outputStyle": "test"}' > /tmp/settings.json

  # Test - output style is ignored
  printf '{"type":"message","role":"user","content":[{"type":"text","text":"hello"}]}\n' | \
    claude --output-format stream-json --verbose \
    --append-system-prompt "You are helpful." \
    --settings /tmp/settings.json \
    --input-format stream-json

  Expected: Lowercase response like "hey" or "yo"
  Actual: Normal case response like "Hello! How can I help you today?"

The init message shows "output_style":"test" confirming it's loaded, but the actual responses don't follow the output style instructions.

[oneryalcin]

@brickfrog I've also tested output styles and it seemed it worked for me, added few guardrails and seems to be holding.

I used npx @mariozechner/claude-trace --include-all-requests to fetch the system prompt and review to make sure my output styles have been added to the system prompt and it was.

[brickfrog]

Ah. Neat. Will check that out.

I was trying to use on the fly + settings.json through the agent-sdk + discord but it didn't seem to take vs. doing the same thing with just claude code straight out, will double check with trace.

Edit: I used strace and apparently the SDK sets --setting_sources "" as default, which breaks custom settings files

  # Manual CLI: WORKS ✓
  echo "What is Python?" | claude -p --output-format stream-json --verbose --settings test.json
  # → "python is a high-level language. used for web dev, data science..." (lowercase, brief)

  # Manual CLI with --setting-sources: BROKEN ✗
  echo "What is Python?" | claude -p --output-format stream-json --verbose --settings test.json --setting-sources local
  # → "Python is a high-level language..." (formal, capitalized)

  # SDK (via strace): ALWAYS passes --setting-sources ""
  claude --output-format stream-json --settings /tmp/tmp.json --setting-sources "" ...
  # → Output style ignored due to the flag

See:

subprocess_cli.py lines 174-179 unconditionally add --setting-sources to the command:
sources_value = (
    ",".join(self._options.setting_sources)
    if self._options.setting_sources is not None
    else ""  # ← Always passes empty string!
 )
 cmd.extend(["--setting-sources", sources_value])  # ← Always added!

That it allows me to do this in the CLI but not the SDK seems that this is unintended behaviour?

[brickfrog]

Okay, so I ended up getting it working, however not the way I wanted:

setting_sources=["user", "project", "local"] ALONG WITH the custom settings file, but this feels extremely kludgey as mentioned above one doesn't need to do this with the CLI itself

I'm assuming claude code hierarchially looks in the location, i.e. user -> project -> local?, but the agent-sdk just kinda requires you to be explicit, so, yeah, wasn't sure if this was intended.

(ideally I would prefer if I could set output styles anywhere I wanted, but that's a claude code feature, not an agent-sdk one, I guess)

[dicksontsai]

Claude Agent SDK used to be implicit about settings, but we updated it to be explicit in >=0.1.0.

[brickfrog]

Ah, I see. Thank you! Closing, I figure anyone searching the issues can find this if they're so inclined.