feat: support custom /compact commands

[maxeonyx]

What's this?

Makes /compact customizable! You can now override the default compaction prompt or create entirely new compact-style commands (like /handover) using configuration or markdown files.

Why though?

The exact compaction prompt has a massive effect on performance after compaction, and this lets you experiment to find what works best for your workflow.

How it works

Override the default /compact

You can define commands in your configuration (e.g., .opencode/command/compact.md or via opencode.json configuration) with the compact property.

Example using Markdown (.opencode/command/compact.md):

---
description: my custom compact
compact: true
---

Provide a detailed summary focusing on:
- What code changed and why
- What testing was done
- What still needs to be done
- Include exact file paths and commands for next steps

Now when you hit <leader>c or auto-compaction triggers, it'll use your prompt instead of the default.

Create a custom compaction command

Want a "handover" mode? You can configure any command to be a compaction command by setting compact: true.

Example using Markdown (.opencode/command/handover.md):

---
description: handover to new agent
compact: true
---

You're receiving a handover from a previous agent. Summarize what was done
so a new agent can pick up where they left off. Include concrete next steps.

Example using Configuration (General):

You can also configure this directly in your command configuration:

"command": {
  "handover": {
    "description": "handover to new agent",
    "compact": true,
    "template": "..."
  }
}

Then type /handover or configure auto-compaction to use it (see below).

Configure auto-compaction

By default, auto-compaction uses /compact. Want it to use your custom command instead?

Add to your .config/opencode/opencode.json:

"auto_compact_command": "handover"

Now auto-compaction will use /handover instead of /compact when the context window fills up.

What changed under the hood

The minimal approach: Reuse existing command infrastructure, no reinventing the wheel.

1. Command precedence (packages/opencode/src/command/index.ts)

   • Built-in commands (/init, /compact, /review) register first
   • User commands (from config or markdown) override built-ins
   • Clean and simple: same pattern as other commands

2. Config option for auto-compaction (packages/opencode/src/config/config.ts)

   • Added auto_compact_command field (optional, defaults to "compact")
   • Validates the command exists and shows a helpful error if misconfigured
   • Lets you choose which compact command auto-compaction uses

3. Prompt plumbing (various files)

   • Added prompt parameter to the compaction flow
   • Auto-compaction dynamically fetches the command template
   • Manual compaction (via /compact or custom commands) passes the template through
   • One source of truth: packages/opencode/src/command/template/compact.txt

4. SDK updates

   • Command type: added compact?: boolean flag
   • Session API: accepts custom prompts

Total impact: 12 files, 105 additions, 40 deletions. Mostly refactoring to thread the prompt through.

Design decisions

Following maintainer feedback from PR comments:

• ✅ Make compact a built-in slash command (like /init)
• ✅ User commands override built-ins via precedence
• ✅ Reuse existing command infrastructure (no new config complexity)
• ✅ Auto-compaction respects customizations
• ✅ No function execution needed (pure markdown files or config)

The implementation is minimal and composable — it fits naturally into OpenCode's existing patterns.

What's left to test

• Override /compact with a custom prompt and verify it works
• Create a /handover command and use it manually
• Configure auto_compact_command: handover and trigger auto-compaction
• Verify error message when auto_compact_command points to a non-existent command
• Check that default behavior is unchanged when no customization exists

---

Ready for review

[rekram1-node]

@maxeonyx have u seen how we handle /init?

I was thinking a cleaner solution here would be to make compact a built in slash command, a user could override the prompt by defining their own compact and it wouldn't require additional config fields

The main change this would require is allowing slash commands to register functions to execute, which ofc couldn't be done in json but perhaps for now that functionality would remain internal

[maxeonyx]

I haven't seen that, no, but I assumed compact has special handling due to the fact that it replaces the full context window. I am very open to doing this a different way.

[maxeonyx]

@rekram1-node in your suggestion, then, I would define my own /handover slash command, with a different prompt, and configured to remove the rest of the context same as /compact (and we would also make /compact be implemented the same way)

[einarpersson]

@rekram1-node

@maxeonyx have u seen how we handle /init?

I was thinking a cleaner solution here would be to make compact a built in slash command, a user could override the prompt by defining their own compact and it wouldn't require additional config fields

The main change this would require is allowing slash commands to register functions to execute, which ofc couldn't be done in json but perhaps for now that functionality would remain internal

I agree, I think
1.compact should be a default includes slash command
2. Default included slash commands should be able to be overriden by user custom commands
3. User custom commands should be able to run as functions, something like #4411

I would advocate for trying to build the built-in slash commands such as /compact with the sdk, in other words forcing yourself to use the same functionality that a custom plugin developer would use. That would drive a architecture which makes sure that user custom commands can be just as powerful as the ones provided by default.

[rekram1-node]

Yup total agreement, currently jumping between several fixes and then I can come back to these new feature prs

[maxeonyx]

I have the new version mostly implemented but I'm on holiday atm - feel free to take it over or close as I won't able to do the final "runnable as functions" part. But I have done the "custom md file to implement custom compact-type command". I can add precedence for overriding /compact - that's a good idea.

[maxeonyx]

@rekram1-node @einarpersson This PR is ready for your review, hope it's what you are imagining. It has turned out pretty clean I think.

[maxeonyx]

@rekram1-node Keeping this up-to date is becoming a hassle - would you be able to review?