slash commands

[the-vampiire]

how do we use slash commands through the SDK? is it possible or would this be a new feature?

when i try, through this SDK or even directly to the CLI, it will produce no output.

is this because it can't find the commands like in the TUI? maybe a way to auto-detect with .claude/commands presence or a flag to pass in a commands dir would work.

let me know how i can help, happy to contribute.

[sarukas]

slash commands do work:

• clear, compact do the job
• help returns empty
• custom slash commands will execute as tool

You have to handle the initialization and set project parameter properly for it to read the e.g. project claude folder and catch these.

[santhoshkammari]

what about /usage command ?

its not working!

[costiash]

Slash Commands SDK Discovery

I've done comprehensive testing of built-in slash commands via the SDK and documented my findings in this notebook (includes outputs for context):

📓 slash_commands_demo.ipynb

Key Findings

Working Built-in Commands:

Command	Status	Notes
/compact	✅ Works	Returns SystemMessage with subtype="compact_boundary" + summary in UserMessage
/cost	✅ Works	Output in UserMessage with <local-command-stdout> tags
/context	✅ Works	Same output pattern as /cost
/todos	✅ Works	Same output pattern

CLI-Only Commands:

Command	Status	Notes
/help	❌ Not recognized	CLI-only
/clear	⚠️ Misleading	Returns init SystemMessage but does not reset context

Important: /clear Does NOT Actually Work via SDK

Contrary to a previous comment, /clear does not actually reset the session via SDK. While it returns a SystemMessage with subtype="init", measuring context tokens before/after shows messages increase rather than reset to zero. The notebook demonstrates this with /context measurements at each step:

After /compact:  Messages = 1,300 tokens
After /clear:    Messages = 1,800 tokens  ← INCREASED, not reset!

Critical SDK Pattern

You must fully drain receive_response() before calling query() again:

async for message in client.receive_response():
    # Process ALL messages - don't early return!
    pass
# Now safe to query again

Early returns leave the client in a bad state and cause subsequent queries to fail silently.

Custom Slash Commands

This investigation focused on built-in slash commands. For custom slash commands (in .claude/commands/), you need to properly configure ClaudeAgentOptions to load them:

options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Directory containing .claude/commands/
    setting_sources=["project"],  # Required to load project settings
)

See the SDK documentation for more details on custom commands.

---

This is the best I could discover through testing. If anyone has found different methods or has additional insights on slash command behavior via the SDK, it would be great to share! 🙏

[sarukas]

Thanks, super helpful. I can confirm that after clear the client stays in bad state unless drained, but am surprised that it does not clear the context. My tests, which were manual and not rigorous, seemed to show that the response becomes new - e.g. previous context is forgotten:

• " i will ask you about a city later. it is london. now just remember it."->"ok";
  "/clear";
  "what is the city" -> "what do you mean"

[costiash]

Interesting. In the notebook as you can notice I've mostly "followed the tokens" lol but haven't actually performed checks like yours about preservation of the "knowledge" itself before and after /clear. Will definitely check it or feel free to fork the gist and farther play with if you want perhaps you have more Interesting ideas that I did reach to them yet. Anyway your example here very interesting and definitely worth checking.