Is it possible to start in plan mode by default?

Question

I'm using Helix editor.
My workflow is highlight a piece of code, and send it to the right pane using opencode -p, along with a prompt to ask some questions. The problem is that if I forget to press Tab to switch to plan mode, it changes my code, which is not what I want.

Is it possible to have opencode always start in plan mode by default?

no but we can add that

I mean you can use the --agent flag actually, but most people want a config option

/oc add a "default_agent" field to config.ts, be sure to update all the places that we default to "build" agent, etc to check hey did the user set a default_agent and if not use build one if build one exists ig

Created PR #4447

opencode session | github run

I think we can add list/ls command into opencode agent to list agents:

opencode agent

manage agents

Commands:
  opencode agent create  create a new agent

and the help page can be improved to something like this:

Options:
      --agent       agent to use                                        
                            [string] [built-in: "build", "plan"]

Yeah that's good

/oc add a new subcommand to the opencode agent command called list, read cmd/agent.ts

It should be pretty straight forward to get all the available agents and list then by name and maybe if they are a subagent or not

Created PR #4446

opencode session | github run

This is a great PR; is it possible to include a parameter which would also output each agent's description field ?
My use case is to help Orchestrator agents delegate to subagents by having a quick way of having the list of subagents

@dehidehidehi

@dehidehidehi any agent that has access to the task tool has every agent and their description in context automatically because they are options for it:


export const TaskTool = Tool.define("task", async () => {
  const agents = await Agent.list().then((x) => x.filter((a) => a.mode !== "primary"))
  const description = DESCRIPTION.replace(
    "{agents}",
    agents
      .map((a) => `- ${a.name}: ${a.description ?? "This subagent should only be called manually by the user."}`)
      .join("\n"),
  )
  return {
    description,
    parameters: z.object({
      description: z.string().describe("A short (3-5 words) description of the task"),
      prompt: z.string().describe("The task for the agent to perform"),
      subagent_type: z.string().describe("The type of specialized agent to use for this task"),
      session_id: z.string().describe("Existing Task session to continue").optional(),
    }),
    async execute(params, ctx)

Yes, why does it always start in Build mode? That's annoying and dangerous. It should by default start in Plan mode unless specifically set by the user to start in Build mode.

Actually, why not at minimum keep the same setting the user had last time instead of resetting it? It doesn't make sense that it doesn't store the preference. It's like setting a preference, then exiting an app, then having to reset it.

So a preference for a specific agent, or the last agent the user had selected ("automatic")?

I saw in my github email feed that someone left this comment earlier today and now it's gone (deleted I guess?), but I think it's worth addressing because it's probably a common question:

Why not simply add an alias to the shell configuration file?
alias opencode="opencode --agent plan"

This is what I originally tried too, but I ran into trouble because always having an --agent=... option messes up opencode subcommands, e.g. it breaks opencode session list:

$ opencode session list -n5
Session ID                      Title                      Updated
──────────────────────────────────────────────────────────────────
ses_4372144b0ffe57Tqg4XQsHOTNC  Greeting                   3:13 PM · 1/16/2026
ses_43721e396ffeCYLkR3Kp1rkc3r  Greeting                   3:12 PM · 1/16/2026
ses_437220afaffeLpqFRU6qCi40NE  Greeting                   3:12 PM · 1/16/2026
ses_437222cdfffe75JvohDScGOEoH  Greeting                   3:12 PM · 1/16/2026
ses_4372267bcffe6j0FOgt24yy2Qy  Greeting                   3:12 PM · 1/16/2026

$ opencode --agent=plan session list -n5
opencode session list

list sessions

Options:
  -h, --help        show help                                                              [boolean]
  -v, --version     show version number                                                    [boolean]
      --print-logs  print logs to stderr                                                   [boolean]
      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]
  -n, --max-count   limit to N most recent sessions                                         [number]
      --format      output format             [string] [choices: "table", "json"] [default: "table"]

So I'd argue that having a proper config setting for the default agent is worthwhile, to avoid weird sharp edges like this.

@jdanbrown

Thanks, @jdanbrown !

I had posted it but thought there should be more to it. So I'm glad you pointed out theses issues.

In the meantime I found out that the "default_agent" option already works in opencode.json - setting it to "plan" solves this issue.

Thanks, @jdanbrown !

I had posted it but thought there should be more to it. So I'm glad you pointed out theses issues.

In the meantime I found out that the "default_agent" option already works in opencode.json - setting it to "plan" solves this issue.

Where is this opencode.json?

I saw Claude recommended the same approach to me, but it's not obvious to me where this lives.

I looked through the help docs of the cli, and looked in the usual places (for non-Windows machines) .local and .config. I couldn't see anywhere that jumps out on where to put this.

You can find it in the schema

https://opencode.ai/config.json

Thanks, @jdanbrown !

I had posted it but thought there should be more to it. So I'm glad you pointed out theses issues.

In the meantime I found out that the "default_agent" option already works in opencode.json - setting it to "plan" solves this issue.

Where is this opencode.json?

I saw Claude recommended the same approach to me, but it's not obvious to me where this lives.

I looked through the help docs of the cli, and looked in the usual places (for non-Windows machines) .local and .config. I couldn't see anywhere that jumps out on where to put this.

I've noticed that when using "default_agent" set to plan, the colors are inverted in the TUI.

What I mean is that by default opencode starts with the Build agent and the TUI highlights the prompt area with purple. When pressing tab the agent becomes Plan and the highlight color is orange.

With the default agent as plan (through the new "default_agent" config opt), the colors are reversed: Build is highlighted with orange and Plan is highlighted with purple. Is this intentional?

I guess the color is attached to the default agent, not build or plan. Any agent you set to default will have a color set on your theme

I've noticed that when using "default_agent" set to plan, the colors are inverted in the TUI.

What I mean is that by default opencode starts with the Build agent and the TUI highlights the prompt area with purple. When pressing tab the agent becomes Plan and the highlight color is orange.

With the default agent as plan (through the new "default_agent" config opt), the colors are reversed: Build is highlighted with orange and Plan is highlighted with purple. Is this intentional?

Yep, color changing is annoying. The color should stick to the agent itself, not to the default/non default - the docs seems clarifying this: https://opencode.ai/docs/en/agents/#color

What's the current state? In the docs, there is a default_agent option but this does not change the default agent when opening up Opencode.

@biolauri

@biolauri

It does work for me, setting "default_agent": "plan", makes the plan mode the default one.

Yeah I can confirm it works for me now, setting up the config like this: https://opencode.ai/docs/config/#default-agent

I've noticed that when using "default_agent" set to plan, the colors are inverted in the TUI.

What I mean is that by default opencode starts with the Build agent and the TUI highlights the prompt area with purple. When pressing tab the agent becomes Plan and the highlight color is orange.

With the default agent as plan (through the new "default_agent" config opt), the colors are reversed: Build is highlighted with orange and Plan is highlighted with purple. Is this intentional?

This works for me, it will show orange in Plan mode and purple (or blue on my pc) in Build mode.

// opencode.json
{
    "default_agent": "plan",
    "agent": {
        "plan": {
            "color": "primary"
        },
        "build": {
            "color": "secondary"
        }
    }
}

@MFWT

Thanks @MFWT ! I tried your solution and confirm that it works!

Navigation Menu

Repository navigation

Is it possible to start in plan mode by default? #4443

Question

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Is it possible to start in plan mode by default? #4443

Description

Question

Activity

rekram1-node commented on Nov 18, 2025

rekram1-node commented on Nov 18, 2025

rekram1-node commented on Nov 18, 2025

opencode-agent commented on Nov 18, 2025

quantonganh commented on Nov 18, 2025

rekram1-node commented on Nov 18, 2025

rekram1-node commented on Nov 18, 2025

opencode-agent commented on Nov 18, 2025

dehidehidehi commented on Nov 20, 2025

rekram1-node commented on Nov 20, 2025

tgrushka commented on Jan 10, 2026

jdanbrown commented on Feb 6, 2026

rapcal commented on Feb 7, 2026

seantiz commented on Feb 7, 2026

rapcal commented on Feb 7, 2026

hernancerm commented on Feb 7, 2026

rapcal commented on Feb 7, 2026

andyceo commented on Mar 13, 2026

biolauri commented on May 5, 2026

0fflineuser commented on May 5, 2026

seantiz commented on May 5, 2026

MFWT commented on Jul 5, 2026

andyceo commented on Jul 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions