Running Many OpenCode Sessions at Once

Run separate OpenCode sessions for independent tasks, and give simultaneous edits separate working directories. Each session has its own conversation; it does not automatically coordinate file changes with the others. A persistent server can let another client reconnect, while a headless script can handle repeated jobs.

I would start with two tasks that touch different files and a clear review limit. More sessions save time only when their output arrives at a pace you can check.

Before adding parallel sessions, make sure the underlying tool fits your work. Our coding tools guide compares OpenCode with the main alternatives.

For teams sharing a gateway or remote host, the OpenCode enterprise guide explains the deployment and policy questions to settle first.

When Should You Use Separate Sessions or Worktrees?

OpenCode users should use separate sessions for independent conversations and separate worktrees or checkouts for concurrent edits. Use a shared server when clients need to reconnect to ongoing work. These solve different problems. Conversation separation does not protect files, and a worktree does not isolate credentials or network access.

When Do You Need Multiple OpenCode Sessions?

Multiple OpenCode sessions are useful when independent tasks can progress at the same time or when you want separate model attempts on one task. Repeated or scheduled jobs may need automation instead of more interactive sessions.

• Waiting: a long refactor blocks you while a small fix sits untouched.
• Independence: two tasks touch different parts of the repository.
• Comparison: you want the same task attempted by two different models.
• Repetition: the same mechanical change applies across many packages.
• Scheduling: a job should run without a person sitting in front of it.

Only the last two genuinely want automation. The first three want a second window and a clear rule about which files each session may touch. Reaching for orchestration when the real need is a second terminal adds machinery you then have to maintain.

Use the Client and Server Split

OpenCode runs as a client talking to a server rather than as a single terminal program. That split is what makes a fleet possible at all, because the session lives with the server and the client is just a view onto it. A plain opencode run starts both, so persistence depends on a server you keep alive.

Three things follow from that, and each one is a capability you can use or ignore:

• Several sessions can run against one project at the same time.
• A client can attach to a running server from another machine, once you have secured it.
• A session remains available after a client disconnects while the OpenCode server keeps running.

Keep one project per server where you can. Mixing several repositories behind one server makes it harder to reason about which permission rules and which environment a given session inherited.

OpenCode 2 differs: it normally discovers or starts a shared background service for your user. Its --standalone and --server options select a private or explicit server. The serve/attach examples below describe the V1 workflow; see the V2 CLI guide before adapting them.

Give Each Session Its Own Worktree

This is the step most fleets skip, and it is the one that decides whether parallel work is useful or a merge problem. A git worktree is a second checkout of the same repository in its own folder, sharing one history.

Two sessions editing the same working tree can overwrite or conflict with changes because their conversations do not automatically coordinate who owns each file. Separate worktrees turn that silent conflict into an ordinary merge you handle at the end.

Isolation	Cost	Use When
One working tree	None	One session only
Git worktrees	Disk, one branch each	Parallel edits, one repo
Separate clones	Full copy each	Different dependencies
Containers	Setup and images	Untrusted commands

Name the branch after the task, not after the session number. When you come back to four running jobs an hour later, the branch name is the only label that still tells you what the agent was asked to do.

Drive a Session from a Second Device

Because the client attaches to a server, you can start a long job at your desk and check it from a laptop or a phone. That is genuinely useful for jobs measured in tens of minutes.

Get the security order right, because the default is not what people assume. The server binds to 127.0.0.1 and ships with no authentication at all, so anything that can reach it can run commands on that host.

OpenCode's documented protection is OPENCODE_SERVER_PASSWORD, which turns on HTTP basic auth for opencode serve and opencode web. The username defaults to opencode unless OPENCODE_SERVER_USERNAME overrides it. That is the exact invocation its server page shows:

OPENCODE_SERVER_PASSWORD=your-password opencode serve

The variable is the only documented switch for this. There is no password flag on opencode serve, and the server still listens on 127.0.0.1 at port 4096 until --hostname or --port changes it.

Prefer SSH port forwarding for cross-machine access, so the listener stays on localhost and your existing SSH keys do the authenticating. Exposing the server on a network is the riskier path: basic auth sends the password and every prompt unencrypted, so it also needs TLS in front of it, such as a reverse proxy, with the password set before anything else.

Forwarding is two commands on the second device, one per terminal. The first command is standard OpenSSH port forwarding, not an OpenCode feature; the second attaches a client to the forwarded port rather than to a network address:

ssh -N -L 4096:127.0.0.1:4096 you@your-dev-machine
opencode attach http://127.0.0.1:4096 --password your-password

Nothing on the dev machine changed for that to work, which is the point. The server kept its localhost bind, and SSH carried the encryption that basic auth does not. The --password flag is how attach presents the server's basic-auth credential from the second device, since the environment variable you set in the server's terminal does not exist there; it is only needed when the password is set.

A second device is for watching and answering approval prompts. Writing a fresh multi-file task on a phone keyboard is how vague prompts get sent, and a vague prompt costs more to review than it saved to type.

Automate Repeated Tasks with Headless Runs

The repetition case is the one that deserves a script. When the same mechanical change applies across many packages, a loop that runs OpenCode once per package is more reliable than one session asked to remember twelve directories.

The command for that is opencode run, which OpenCode documents as its non-interactive mode: it takes the prompt as an argument and exits when the run finishes.

opencode run "Update this package's lint config to match the repo root."

Four of its flags matter once a script owns the run. --agent picks which agent handles it, --model pins the provider and model, --format json gives output a script can parse, and --auto approves permission prompts so nothing waits for a human who is not there.

With --auto, requests that would ask for permission are approved automatically; explicit deny rules remain enforced. Review those rules and the process's operating-system access before an unattended run.

Three rules keep a scripted fleet from becoming a liability:

1. Run each unit against its own branch, so a bad run is one branch to delete.
2. Set permissions explicitly for the script's user, never inheriting your interactive setup.
3. Fail loudly on the first unit before letting the loop touch the rest.

The following loop runs OpenCode sequentially, one package after another, and stops on the first nonzero exit. It demonstrates batch automation, not simultaneous sessions:

for pkg in packages/*/; do
  opencode run --agent build "Update the lint config in $pkg to match the repo root." || exit 1
done

That stops at the first nonzero process exit. A successful exit does not prove the requested edit is correct or that tests passed; add the package's actual validation command before advancing. It does not give you the first rule, and it is worth being clear about why: every run lands in the same working tree, so uncommitted changes from one package are still sitting there when the next one starts.

Branch-per-unit therefore needs a commit, a stash, or a separate checkout between runs. Add that isolation before using the loop for independent tasks.

Permission rules and bounded loops are their own subject, and the advanced OpenCode guide covers the allow, ask, and deny patterns a scripted run should carry before it runs unattended.

Add Orchestration Only When You Need It

Oh My OpenCode is a community extension, not an OpenCode product, and it adds a layer that routes work across a team of specialised agents. It is mid-rename to Oh My OpenAgent, so expect both names in the wild.

Adopt it when you have already outgrown a shell loop, not before. The honest test is whether you can name the routing decision the orchestrator makes that your script cannot. If you cannot, the script is still the smaller thing that works.

OpenCode's own subagents cover a lot of ground first: General for parallel multi-step work, Explore for read-only codebase search, and Scout for external docs and dependency research. All three are invoked from inside one session.

Two mechanisms do that, and the OpenCode agents page documents both. A primary agent delegates to a subagent on its own, based on that subagent's description, and you can call one directly by mentioning it in the prompt, as in @general help me search for this function.

Primary agents are the separate case. Tab cycles between Build and Plan inside a session, and --agent names the agent for a scripted opencode run.

Keep Review from Becoming the Bottleneck

A fleet moves the constraint. Generation stops being the slow part, and reading diffs becomes it. Three sessions producing changes faster than anyone reads them just builds a backlog with extra token spend attached.

• Cap the fleet at the number of diffs you will actually read today.
• Give each session an acceptance test it must pass before you look.
• Watch the cost meter per session, not just the monthly total.
• Stop a session that has retried the same failure twice.

When a session repeats a failure, inspect the error and narrow the task before restarting it.

How Does OpenCode Compare with a Managed Agent Interface?

Cursor's Agents Window presents parallel tasks in one interface and supports several execution locations. OpenCode 1 gives you client/server and headless tools to assemble a workflow around your own environment. Compare the specific execution mode, isolation, and scripting support you need instead of assuming every commercial product uses only a vendor cloud.

I favor a small terminal setup when it is already easy to supervise. A task board becomes useful when status and review, rather than model access, are what slow the work. The broader comparison is in Cursor vs OpenCode.

Run the Smallest Fleet That Works

Two sessions on separate worktrees, each with a task you could describe in a sentence, covers most of what a fleet is actually for. Add a third only if you have another independent task and spare review capacity. Use a script when the work is repetitive rather than merely parallel.

Start from the OpenCode overview if the basics are not in place yet, and read the advanced guide before any session runs without someone watching it.

FAQ

Every OpenCode command, flag, and environment variable shown on this page was checked against OpenCode's own CLI, server, and agents documentation on August 10, 2026. The one command here that is not OpenCode's, the SSH tunnel, follows the OpenSSH manual page instead. The client and server split, the subagent trio, and the fleet guidance were checked on August 9, 2026.

How many OpenCode sessions can I run at once?

OpenCode does not publish a fixed session cap; the practical limit is your machine, your provider's rate limits, and how many diffs you can review. Start with two sessions. Add a third only when you have another independent task and enough capacity to review the extra output.

Do parallel sessions share context?

Parallel OpenCode sessions keep separate conversation and compaction histories and do not automatically coordinate edits. Sessions using the same working directory may still read files changed by one another, so give concurrent edits separate worktrees or checkouts.

Does OpenCode isolate agents from each other?

Separate OpenCode sessions do not provide a security boundary between agents. Git worktrees and separate checkouts keep edits in different folders, but do not restrict access to credentials, other files, or the network. Those restrictions depend on operating-system permissions or appropriately configured containers.

Can I check on a run from my phone?

Developers can check an OpenCode run from a phone by connecting a client to the server hosting the session. The server binds to localhost and has no authentication by default, so prefer SSH port forwarding rather than changing the bind address. Exposing it on a network needs OPENCODE_SERVER_PASSWORD and TLS in front of it, because basic auth alone sends everything unencrypted.

Is a fleet cheaper than one session?

Running multiple OpenCode sessions does not automatically make the same workload cheaper or more expensive. Total model cost depends on usage and provider pricing; duplicated context and extra retries can increase it. Parallel sessions can finish independent tasks sooner while consuming your usage allowance faster.

When should I not run a fleet?

Developers should avoid running multiple OpenCode sessions in parallel when tasks touch the same files, output exceeds their review capacity, or permissions are still being configured. A single well-scoped session beats three sessions producing changes nobody has read.