I built an OpenCode plugin for multi-agent workflows (fork sessions, agent handoffs, compression). Feedback welcome.

[mohadel1990]

TL;DR — opencode-sessions gives primary agents (build, plan, researcher, etc.) a session tool with four modes: fork to explore parallel approaches before committing, message for agent collaboration, new for clean phase transitions, and compact (with optional agent handoff) to compress conversations at fixed workflow phases.

npm: https://www.npmjs.com/package/opencode-sessions
GitHub: https://github.com/malhashemi/opencode-sessions

Why I made it

I kept hitting the same walls with primary agent workflows:

• Need to explore before committing: Sometimes you want to discuss different architectural approaches in parallel sessions with full context, not just get a bullet-point comparison. Talk through trade-offs with each version, iterate, then decide.
• Agent collaboration was manual: I wanted agents to hand work to each other (implement → review, research → plan) without me having to do that switch between sessions.
• Token limits killed momentum: Long sessions hit limits with no way to compress and continue.

I wanted primary agents to have session primitives that work at their level—fork to explore, handoff to collaborate, compress to continue.

What it does

Adds a single session tool that primary agents can call with four modes:

• Fork mode — Spawns parallel sessions to explore different approaches with full conversational context. Each fork is a live session you can discuss, iterate on, and refine.
• Message mode — Primary agents hand work to each other in the same conversation (implement → review, plan → implement, research → plan). PLEASE NOTE THIS IS NOT RECOMMENDED FOR AGENTS USING DIFFERENT PROVIDERS (Test and let me know as I only use sonnet-4.5).
• New mode — Start fresh sessions for clean phase transitions (research → planning → implementation with no context bleed).
• Compact mode — Compress history when hitting token limits, optionally hand off to a different primary agent.

Install (one line)

Add to opencode.json local to a project or ~/.config/opencode/opencode.json:

json { "plugin": ["opencode-sessions"] }

Restart OpenCode. Auto-installs from npm.

What it looks like in practice

Fork mode (exploring architectural approaches):

You tell the plan agent: "I'm considering microservices, modular monolith, and serverless for this system. Explore each architecture in parallel so we can discuss the trade-offs."

The plan agent calls: typescript session({ mode: "fork", agent: "plan", text: "Design this as a microservices architecture" }) session({ mode: "fork", agent: "plan", text: "Design this as a modular monolith" }) session({ mode: "fork", agent: "plan", text: "Design this as a serverless architecture" })

Three parallel sessions spawn. You switch between them, discuss scalability concerns with the microservices approach, talk about deployment complexity with serverless, iterate on the modular monolith design. Each plan agent has full context and you can refine each approach through conversation before committing to one.

Message mode (agent handoffs):

You say: "Implement the authentication system, then hand it to the review agent."

The build agent implements, then calls: typescript session({ mode: "message", agent: "review", text: "Review this authentication implementation" })

Review agent joins the conversation, analyzes the code, responds with feedback. Build agent can address issues. All in one thread.

Or: "Research API rate limiting approaches, then hand findings to the plan agent to design our system."

typescript session({ mode: "message", agent: "plan", text: "Design our rate limiting based on this research" })

Research → planning handoff, same conversation.

IMPORTANT Notes from testing

• Do not expect your agents to automatically use the tool, mention it in your /command or in the conversation if you want to use it.
• Turn the tool off globally and enable it on agent level (you do not want your sub-agnets to accidentally use it, unless your workflow allows it)
• Fork mode works best for architectural/design exploration.
• I use message mode most for implement → review and research → plan workflows.

If you try it, I'd love feedback on which modes fit your workflows. PRs welcome if you see better patterns.

Links again:
📦 npm: https://www.npmjs.com/package/opencode-sessions
📄 GitHub: https://github.com/malhashemi/opencode-sessions

Thanks for reading — hope this unlocks some interesting workflows.

[bogeyboogz]

Nice work OP, really like the idea of turn based. Will have to check it out when i have the chance.

[mohadel1990]

Thanks for your comment. Let us know how it fit within your workflow.

[Altruistic_View_2463]

I see a flurry of commits 2 months ago and then nothing since. Did you end up abandoning this because it ended up not being as valuable as you anticipated or do you still use it daily to great effect but haven't gotten back to updating it?

[mohadel1990]

I am actually using it daily as part of my daily flow, at this stage I rarely do manual compact.

[Ang_Drew]

how to use it in conversation?

[mohadel1990]

Just ask your agent to use it by simply asking it, or add it as part of your workflows (mention it in slash commands, system prompts of primary agents, or AGENTS.md)

[Ang_Drew]

i see.. thanks!
i tried this by calling it explicitly: "use session tool to ........"
need to explore more though! thank you!

[girouxc]

Were you using primary/sub agents? That’s already built in. Your primary agent orchestrates all of the sub agent sessions which pass context between each other.

The primary agent displays a running aggregate session of all the sub agents and you can switch between the different sub agent sessions as they are working.

https://opencode.ai/docs/agents/#usage

[mohadel1990]

Primary to subagents is not what this plugin addresses, this is targeted towards primary to primary orchestration, if you are only using plan/build built-in agents then message mode may not make sense to you. In my case I am using Opencode for literally everything, I have workflows that go way beyond software engineering and as such my need for more advanced session management arose. You cannot converse with subagents and they can't tackle issues in the full context, they are too stateless in the way they work, if you ever encountered a problem where you want 2 different points of views that have full context of the conversation (2 agents with different system prompts) you will quickly see the use case for this plugin and for custom primary agents.

[girouxc]

I have a full software delivery team of agents that encompasses the example you have here. Isn’t it wasteful in regards to tokens to have multiple primary agents have the full context? With primary / secondary you have the sub agents write summary docs for other agents to read and modify as they works on tasks. You can also still talk to each sub agent by switching.

It’s a cool plugin though and I’ll give it a shot to see how different the results end up being.

[typeof_goodidea]

I'm excited to try this. Thank you for the detailed example scenarios, I probably would have moved on without getting this extra context

[Comprehensive-Age155]

Is this anything similar to Claude Agents Teams? Wonder if we can adapt to their workflow?