@viberlabs/opencode-plugin

Session continuity for OpenCode. Pick up exactly where you left off. No more re-explaining your project every time you start a new chat.

What it is

An orchestration layer that validates tasks before agents run them, maintains state in local SQLite, and writes handoffs so your next session starts with context.

Why this isn't Jira

Most task managers store todos. VIBER validates them.

Before any agent executes, the Formal Logic Layer checks if the task is actually ready:

• Does it have clear requirements?
• Does it respect your architecture constraints?
• Is it aligned with your vision?

Tasks get scored:

• PEAK: Ready to execute
• SLOPE: Needs planning first, then re-validate
• VALLEY: Not ready, clarify first

This prevents agents from running on vague requirements and breaking your codebase.

Quickstart

Requires OpenCode.

npm install -g @viberlabs/opencode-plugin
viber start

Open your project in OpenCode and say: "Run the viberHealth tool"

Dashboard: http://localhost:5173

How it works

Control plane: Your OpenCode chat controls everything. Dashboard is read-only.

State: SQLite at .viber/state.db is canonical.

Validation: FLL checks tasks against VISION.md and ARCHITECTURE.md before execution.

Execution: Agents run in separate OpenCode sessions. ORCA (the orchestration engine) executes queued work from SQLite.

Continuity: VIBER writes handoffs to .viber/handoff/ so new sessions start with context.

Session handoffs

The context window problem: You build for 2 hours, hit the limit, start a new chat, and have to re-explain everything.

VIBER fixes this by writing handoffs.

End a session: Say: "End this session and write a handoff."

VIBER writes to .viber/HANDOFF.md: what you built, decisions made, what's blocked, what to do next.

Start a new session: Say: "Start a new session. Load the latest handoff."

OpenCode reads the handoff. You skip the re-explaining. The new session starts with full context.

Vision and Architecture

These two docs are your planning baseline. They connect your idea to execution.

VISION.md - What you're building and why. The problem you're solving.

ARCHITECTURE.md - How it works. Constraints that must not be broken.

Most VIBER tools require these. Tasks get validated against them. Agents read them before executing.

Create them: viberPlanProject

This also writes compact versions (VISION-COMPACT.md, ARCHITECTURE-COMPACT.md) for faster loading.

Tools

These are OpenCode tools. Talk to OpenCode naturally, or ask it to run a specific tool by name.

Setup and planning:

• viberHealth - Confirm VIBER is running, check root and DB path
• viberDocsStatus - Check if VISION.md and ARCHITECTURE.md exist
• viberPlanProject - Create or update Vision and Architecture docs

Tasks:

• viberCreateTask - Create a task
• viberValidateTask - Run FLL validation, writes artifact to .viber/artifacts/
• viberListTasks - Show all tasks with status
• viberUpdateTask - Update task status

Agents:

• viberSpawnAgent - Create agent + OpenCode session and prompt it
• viberEnqueueAgent - Queue agent for ORCA to execute
• viberContinue - Pick next task, validate, spawn next agent
• viberListAgentRuns - Show agent records and session IDs
• viberFocus - Show the most relevant runs

Continuity:

• viberHandoffWrite - Write handoff and update .viber/HANDOFF.md
• viberHandoffList - List recent handoffs

Configuration

Environment variables:

• VIBER_ORCA_SCHEDULER=1 - Enable automatic task scheduling (off by default)
• VIBER_ORCA_SCHEDULER_ALLOW_SLOPE=1 - Allow scheduling SLOPE tasks (PEAK only by default)

Files:

• opencode.json - Project-level OpenCode config (auto-updated by viber start)
• .viber/opencode-auth.json - Local connection file for your OpenCode server (do not commit)

Technical details

• SQLite canonical at .viber/state.db
• Agents run in separate OpenCode sessions (traceable, repeatable)
• ORCA executes queued work from SQLite
• FLL writes validation artifacts to .viber/artifacts/fll-<taskId>.json
• Local-only, no cloud dependencies