opencode-manager

 ██████╗  ██████╗███╗   ███╗
██╔═══██╗██╔════╝████╗ ████║
██║   ██║██║     ██╔████╔██║
██║   ██║██║     ██║╚██╔╝██║
╚██████╔╝╚██████╗██║ ╚═╝ ██║
 ╚═════╝  ╚═════╝╚═╝     ╚═╝
        opencode-manager

ocm is k9s for OpenCode. One terminal dashboard to create, attach, edit, and tear down coding-agent workspaces, with OpenCode by default plus Claude Code and optional DeepSeek Harness support.

📖 Read the documentation — installation, getting started, concepts, TUI/CLI guides, and modules.

What it does

Coding agents are powerful because they can touch your whole machine — which is also the danger. Run OpenCode directly and one careless prompt can reach your cloud accounts, Kubernetes clusters, SSH keys, and tokens.

ocm gives each project its own isolated container, configured with only the tools and credentials you pick for it. You manage them all from a single screen: one keystroke spins a workspace up, drops you into its session, or shuts it down.

Install

npm install -g @mickaelroger78/opencode-manager

This installs two interchangeable commands, opencode-manager and its short alias ocm. It also creates the config directory, writes a default config.yaml, and copies the built-in modules — without overwriting anything you already have.

Requirements: Docker or Podman installed on the host, and npm's global bin directory on your PATH.

No global install? Use npx @mickaelroger78/opencode-manager.

Quickstart

1. Install (see above).

2. Add your OpenCode config. Every workspace receives a one-way copy of the shared config in ~/.config/opencode-manager/opencode/. Copy your existing opencode.json, skills, commands, agents, and plugins into it:

   cd ~/.config/opencode-manager/opencode
   
   cp /path/to/your/opencode.json .
   cp -r /path/to/your/skills/*   skills/
   cp -r /path/to/your/commands/* commands/
   cp -r /path/to/your/agents/*   agents/
   cp -r /path/to/your/plugins/*  plugins/
   # optional shared instructions:
   cp /path/to/your/AGENTS.md     .

   ocm copies this tree to each workspace on creation, reconciles it at startup, and watches it while active. Host changes win; workspace changes never flow back. Per-workspace generated state such as lockfiles and node_modules is preserved. (ocm creates this directory and an empty opencode.json for you on first run.)

3. Launch the dashboard.

   ocm

4. Create a workspace, then add the modules it needs (AWS, Git, Kubernetes, SSH…) so the agent gets exactly that project's credentials and nothing else. Attach with Enter and you're coding.

Usage

ocm                              # launch the TUI dashboard
ocm improve                      # analyze recent sessions and propose harness improvements
ocm workspaces list              # list workspaces (alias: ocm ws ls)
ocm workspaces attach <ws>       # attach to a workspace session
ocm workspaces create <name> --template backend --start
ocm workspaces create <name> --deepseek --start
ocm workspaces attach <ws> --runtime deepseek
ocm ws exec <ws> -- go test ./... # run a command in the sandbox
ocm ws run <ws> --prompt "..."   # headless OpenCode run (CI/scripts)

From the dashboard you create, attach, edit (e), stop, delete, and update workspaces — all from the keyboard.

DeepSeek Harness is opt-in. OCM enables DSH's web profile per workspace, supervises its web server alongside OpenCode, and attaches through dsh-tui — a terminal client with the session stream, dynamic slash commands, a context-usage meter, an MCP status panel, and an AgentTeams task-DAG view. DSH configuration, credentials, and sessions persist in the workspace home.

Shared non-secret DSH configuration is synchronized one way from ~/.config/opencode-manager/deepseek/ to DeepSeek-enabled workspaces. OAuth credentials and session state remain isolated per workspace.

The CLI mirrors the dashboard with a kubectl-style ocm <resource> <verb> surface (workspaces/ws, templates/tmpl, modules/mod, plus config, doctor, and version), with -o json on read commands for scripting. See the CLI reference for the full command list.

The dashboard table includes a TOKENS I/O/C column showing each workspace's all-time input / output / cache-read token usage (compacted as k/M/B, e.g. 12.3k/4.5k/89k). It is measured with tokscale inside the container — refreshed when a workspace starts and each time it finishes a turn — and the full breakdown is on the describe page (d).

Templates

A template is a reusable, named set of modules-with-configuration — your recipe for "this kind of project needs AWS + Git + Kubernetes, set up like so".

• Type :templates to open the templates page (and :workspaces to go back).
• On it, c creates a template (name it, then pick its modules just like the workspace module editor), e (or Enter) edits one, and ^d deletes one.
• When you create a workspace, after naming it you get an optional Pick Template step: choose one and the new workspace starts with exactly those modules already installed (choose None to start empty). The picker is skipped when you have no templates yet.

Templates are stored as <workspaceRoot>/templates/<name>.yaml.

Harness self improvement

Enable selfImprovement.enabled: true in config.yaml, then run ocm improve or press i on the dashboard. This private OpenCode workspace is excluded from workspace lists and immediately starts a bounded incremental analysis of OpenCode sessions. Subagents examine the entire OCM configuration and optional additional roots, including external knowledge bases. Cumulative observations retain weak signals until recurrence justifies a proposal; decisions and reports persist. Customize ~/.config/opencode-manager/self-improvement/AGENTS.md to extend or replace the built-in protocol. See the self-improvement guide.

Configuration

The global config lives at ~/.config/opencode-manager/config.yaml and sets the workspace root, container runtime (docker or podman), base image, and module directories. The defaults written on install work out of the box; see ARCHITECTURE.md for every option.

Learn more

• User documentation — installation, getting started, concepts, TUI & CLI guides, modules, and troubleshooting.
• ARCHITECTURE.md — design, workspace & module model, full configuration, security principle.
• PROJECT.md — implementation plan and roadmap.