Developer Workstation Setup Recipe

OpenCode + Signet Memory + Oh-My-OpenAgent + Local MCP Tooling

Target: Ubuntu 24.04 LTS (or any Debian-based Linux) / macOS 14+ (Sonoma/Sequoia)
Windows: via WSL recommended — see Windows appendix for native
Audience: Junior developers comfortable with the terminal
Time: ~30 minutes
Tested versions: Node 22, OpenCode 1.4.22, Oh-My-OpenAgent 3.17.5, Signet 0.108.0, uv 0.11.1, Python 3.13

What You're Installing

Tool	What It Does
OpenCode	AI coding assistant CLI (like Cursor, but terminal-based)
Oh-My-OpenAgent	Plugin that adds multi-model orchestration, background agents, LSP/AST tools
Superpowers	Skill framework that adds TDD, planning, debugging, and code review workflows
Signet AI	Persistent memory system — your AI remembers across sessions
signet-first	Plugin + skill that auto-injects Signet as primary memory into every session
Ollama	Local model server — hosts the embedding model (nomic-embed-text) for Signet's vector search. Optionally also runs the extraction/synthesis model locally to save cloud tokens
Fermat MCP	Math computation MCP server — plotting, NumPy, SymPy, equations
UML-MCP	Diagram generation MCP server — UML, sequence, class, flowcharts, 30+ types
DBHub	Database MCP server — direct MySQL schema inspection and query execution (read-only)
API Testing MCP	REST API testing MCP server — HTTP requests, assertions, flows, OpenAPI import, load testing

Architecture:

You ──► OpenCode ──► GitHub Copilot (cloud) ──► Claude / GPT / Gemini
            │
            ├── Oh-My-OpenAgent (orchestration plugin)
            ├── Superpowers (skill framework — auto-installed from git)
            ├── signet-first (memory protocol — auto-installed from git)
            ├── Signet (memory plugin + MCP server)
            │       │
            │       └── Signet Daemon (localhost:3850)
            │               ├── SQLite + sqlite-vec + FTS5
            │               └── Ollama (localhost:11434)
            │                       ├── nomic-embed-text (274 MB embedding model)
            │                       └── llama3.1:8b (optional — local extraction/synthesis, 1.9 GB)
            │
            ├── Fermat MCP (math computation server)
            │       ├── mpl_mcp  (Matplotlib — charts, plots, equations)
            │       ├── numpy_mcp (NumPy — linear algebra, statistics)
            │       └── sympy_mcp (SymPy — symbolic math, calculus, solvers)
            │
            ├── UML-MCP (diagram generation server)
            │       ├── PlantUML (class, sequence, activity, state diagrams)
            │       ├── Mermaid  (flowcharts, ER, Gantt, pie charts)
            │       ├── D2       (declarative diagrams → SVG/PNG)
            │       └── Kroki    (30+ types: C4, BPMN, Graphviz, etc.)
            │
            ├── DBHub (database MCP server)
            │       └── MySQL (schema inspection, SQL queries, read-only)
            │
            └── API Testing MCP (REST API testing server)
                    └── HTTP requests, assertions, flows, OpenAPI import, environments

Prerequisites

You need a GitHub Copilot subscription (for multi-model access to Claude, GPT, Gemini, etc.). Ask your team lead for credentials.

Step 1 — Install Node.js via nvm

nvm lets you manage multiple Node.js versions. We use Node 22.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Load nvm into your current shell
source ~/."${SHELL##*/}rc"

# Install Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

Verify:

node --version    # Expected: v22.x.x
npm --version     # Expected: 10.x.x

Step 2 — Install OpenCode

OpenCode is the AI coding assistant. One npm install.

npm install -g opencode-ai

Verify:

opencode --version   # Expected: 1.x.x
which opencode       # Expected: ~/.nvm/versions/node/v22.x.x/bin/opencode

First-Time Setup

Launch OpenCode once to create the config directory:

opencode

It will create ~/.config/opencode/. Exit with Ctrl+C after it launches.

Configure GitHub Copilot (Multi-Model Access)

If your team uses GitHub Copilot for access to GPT, Gemini, and other models:

# Login to GitHub CLI
gh auth login

OpenCode will auto-detect Copilot credentials.

Step 3 — Install Oh-My-OpenAgent

Oh-My-OpenAgent adds multi-model orchestration — it lets OpenCode use different AI models for different tasks (e.g., cheap models for exploration, expensive models for architecture).

npm install -g oh-my-opencode

Note on naming: npm package is oh-my-opencode, plugin id is oh-my-openagent@latest. The config filename bug is covered in the "Fix the Config Filename Bug" section below.

Verify:

npm list -g --depth=0 | grep oh-my   # Expected: oh-my-opencode@3.x.x

Register Oh-My-OpenAgent as an OpenCode Plugin

Edit ~/.config/opencode/opencode.json. If it doesn't exist, create it:

mkdir -p ~/.config/opencode
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-openagent@latest"
  ]
}
EOF
# Signet plugins added after Step 5 + Step 9

Configure Oh-My-OpenAgent Models

⚠️ Model IDs may change. These reflect the current working configuration as of April 2025. GitHub Copilot may rename or retire model IDs — update this file if a model becomes unavailable.

Create the agent configuration file. This maps each agent role to a specific AI model:

cat > ~/.config/opencode/oh-my-opencode.json << 'AGENTEOF'
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": {
      "model": "github-copilot/claude-opus-4.6",
      "variant": "high"
    },
    "hephaestus": {
      "model": "github-copilot/gpt-5.3-codex",
      "variant": "medium"
    },
    "oracle": {
      "model": "github-copilot/gpt-5.4",
      "variant": "high"
    },
    "explore": {
      "model": "github-copilot/claude-haiku-4.5"
    },
    "multimodal-looker": {
      "model": "github-copilot/gpt-5.4",
      "variant": "medium"
    },
    "prometheus": {
      "model": "github-copilot/claude-opus-4.6",
      "variant": "high"
    },
    "metis": {
      "model": "github-copilot/claude-opus-4.6",
      "variant": "high"
    },
    "momus": {
      "model": "github-copilot/gpt-5.4",
      "variant": "xhigh"
    },
    "atlas": {
      "model": "github-copilot/claude-sonnet-4.6"
    },
    "sisyphus-junior": {
      "model": "github-copilot/claude-sonnet-4.6"
    },
    "librarian": {
      "model": "github-copilot/gpt-5.4",
      "variant": "medium"
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "github-copilot/gemini-3.1-pro-preview",
      "variant": "high"
    },
    "ultrabrain": {
      "model": "github-copilot/gpt-5.4",
      "variant": "xhigh"
    },
    "deep": {
      "model": "github-copilot/gpt-5.3-codex",
      "variant": "medium"
    },
    "artistry": {
      "model": "github-copilot/gemini-3.1-pro-preview",
      "variant": "high"
    },
    "quick": {
      "model": "github-copilot/claude-haiku-4.5"
    },
    "unspecified-low": {
      "model": "github-copilot/claude-sonnet-4.6",
      "variant": "low"
    },
    "unspecified-high": {
      "model": "github-copilot/claude-sonnet-4.6",
      "variant": "high"
    },
    "writing": {
      "model": "github-copilot/gemini-3-flash-preview"
    }
  }
}

AGENTEOF

What are these agents? sisyphus is the main agent, oracle is for hard architecture decisions, explore does cheap codebase searches, librarian looks up docs. Each uses the model best suited for its role.

Fix the Config Filename Bug

Oh-My-OpenAgent has a known bug: the code reads from oh-my-opencode.json but writes back to oh-my-openagent.json on startup. Fix this with a symlink:

cd ~/.config/opencode
# After first launch, the plugin writes oh-my-openagent.json as the real file.
# Create a symlink so the read path (oh-my-opencode.json) resolves to it:
ln -sf oh-my-openagent.json oh-my-opencode.json

Note: If Oh-My-OpenAgent has not been launched yet, start OpenCode once first so it creates oh-my-openagent.json, then create the symlink.

This ensures both the read path and write path resolve to the same file, regardless of which name the plugin uses.

What's the github-copilot/ prefix? All models route through your GitHub Copilot subscription. This includes Claude models, GPT-4o, and Gemini Pro.

Step 4 — Install Superpowers

Superpowers adds development workflow skills: TDD, planning, debugging, code review.

It installs as an OpenCode plugin — just add it to opencode.json (we'll do this in Step 9 when we write the final config). No symlinks or cloning needed.

Verify (after Step 9):

# Start OpenCode and ask:
# "do you have superpowers?"
# Expected: lists brainstorming, test-driven-development, systematic-debugging, etc.

Step 5 — Install Signet AI

Signet gives the AI persistent memory across sessions.

Install Bun (Signet Daemon Requirement)

Signet's daemon process requires Bun as its runtime. Install it first:

curl -fsSL https://bun.sh/install | bash
source ~/."${SHELL##*/}rc"

Verify:

bun --version   # Expected: 1.x.x

Install Signet

npm install -g signetai

Verify:

signet --version   # Expected: 0.108.0 (or newer)
which signet       # Expected: ~/.nvm/versions/node/v22.x.x/bin/signet

Run the Setup Wizard

signet setup

The wizard will ask several questions. Here are the answers for our team's configuration:

Question	Answer
Agent Name	`Smart-Agent` (or your own name)
Harnesses	Select opencode
Description	`Personal AI assistant`
Deployment context	`local`
Advanced Settings	Accept defaults
Import	Skip
Git	Yes (recommended)
Launch Dashboard	Optional

Or run non-interactively:

signet setup --non-interactive \
  --name "Smart-Agent" \
  --description "Personal AI assistant" \
  --harness opencode \
  --deployment-type local

CRITICAL: Sync the OpenCode Plugin

The setup wizard sometimes skips writing the session plugin. Always run this after setup:

signet sync

This writes signet.mjs to ~/.config/opencode/plugins/ and re-registers hooks. You should see:

✓ hooks re-registered for opencode

Verify the plugin file exists:

ls -la ~/.config/opencode/plugins/signet.mjs
# Expected: signet.mjs (400-500KB file)

If signet.mjs is missing, run signet sync again. If it still doesn't appear, check signet doctor.

Configure the Memory Pipeline

The setup wizard creates ~/.agents/agent.yaml. Open it and verify these keys under memory.pipelineV2 — extraction, synthesis, embedding, and autonomous settings:

cat ~/.agents/agent.yaml

Verify the extraction and synthesis providers are set to opencode (the default — routes through GitHub Copilot via OpenCode):

nano ~/.agents/agent.yaml

The key sections to verify:

memory:
  pipelineV2:
    enabled: true
    extraction:
      provider: opencode                              # ← routes through GitHub Copilot
      model: github-copilot/gpt-5-mini                # ← FREE model for extraction (Copilot Business offers it for free)
      structuredOutput: false                         # ← set false, GitHub Copilot do not accept the format parameter
      fallbackProvider: none                          # ← or set `ollama` if you have a good GPU or mac OSX to load a local model (recommended llama3.1:8b)
      # ← degrades to local Ollama if OpenCode is down
    synthesis:
      enabled: true
      provider: opencode
      model: github-copilot/gpt-5-mini
      structuredOutput: false
    embedding:
      provider: ollama                                 # ← local embedding via Ollama and nomic-embed-text
    graph:
      enabled: true
    reranker:
      enabled: true
    autonomous:
      enabled: true
      maintenanceMode: execute

After editing, restart the daemon:

signet daemon restart

Note: signet status may show "Extraction blocked — OpenCode server not available" during initial setup. This is expected — the default extraction pipeline routes through OpenCode (Step 10). Once OpenCode is running, restart the daemon (signet daemon restart) and the status should clear. If you don't want extraction to depend on OpenCode, see the optional local extraction section below.

Optional: Local Extraction with Ollama (saves cloud tokens)

By default, Signet's extraction and synthesis pipeline routes through GitHub Copilot via the OpenCode server (provider: opencode). This is the simplest setup — no extra models needed, and it uses your existing Copilot subscription.

If you want to eliminate cloud token usage for memory extraction (or work fully offline), you can switch to a local model running on Ollama:

Pull the extraction model (~4.9 GB):
```
ollama pull llama3.1:8b
```

Edit ~/.agents/agent.yaml — change the extraction and synthesis providers:

memory:
  pipelineV2:
    enabled: true
    extraction:
      provider: ollama                              # ← local extraction
      model: llama3.1:8b                              # ← llama3.1 8 Billion parameters
    synthesis:
      enabled: true
      provider: ollama
      model: llama3.1:8b

Restart the daemon:
```
signet daemon restart
```

Verify:

signet daemon logs | grep -i "extraction provider"
# Expected: Extraction provider {"configured":"ollama","resolved":"ollama","effective":"ollama",...}

Trade-offs:

	Default (`opencode` → GitHub Copilot)	Local (`ollama/llama3.1:8b`)
Setup	Zero extra work	Pull ~1.9 GB model
Token cost	Uses Copilot tokens (gpt-5-mini — free for Copilot Business)	Zero cloud tokens
Quality	GPT-5-mini (high)	llama3.1:8b (good, slightly lower)
Speed	Network-dependent	Local GPU/CPU (~2-10s per extraction)
Offline	✗ Needs internet	✓ Fully offline
RAM	None	~6-8 GB when model is loaded
Dependency	Requires OpenCode running	Independent — Ollama only

To switch back to the default, change provider: ollama → provider: opencode and model: llama3.1:8b → model: github-copilot/gpt-5-mini in both extraction and synthesis blocks, then signet daemon restart.

Step 6 — Install Ollama (Embedding + Optional Extraction Server)

Ollama runs AI models locally. At minimum, it provides the embedding model (nomic-embed-text) that powers Signet's vector search. If you opted for local extraction with llama3.1:8b (see Optional: Local Extraction with Ollama above), Ollama also serves the extraction/synthesis model. No cloud API key needed — everything runs on your machine.

Install Ollama

Linux:

curl -fsSL https://ollama.com/install.sh | sh

This installs Ollama and registers it as a systemd service that starts automatically on boot.

macOS:

Download the DMG from ollama.com/download and drag Ollama.app to /Applications. Or via Homebrew:

brew install ollama

Verify:

ollama --version   # Expected: ollama version 0.x.x

Pull the Embedding Model

ollama pull nomic-embed-text

This downloads nomic-embed-text (~274 MB). If you are using the default opencode extraction provider, this is the only model Ollama needs. If you opted for local extraction, also pull llama3.1:8b (see Optional: Local Extraction with Ollama).

Verify:

ollama list   # Expected: nomic-embed-text:latest    274 MB

Verify the Server Is Running

On Linux, Ollama runs as a systemd service automatically after install:

sudo systemctl status ollama   # Expected: active (running)

On macOS, launch Ollama.app from Applications (it sits in the menu bar).

You can also test the API directly:

curl -s http://127.0.0.1:11434/api/tags | python3 -m json.tool
# Expected: JSON with nomic-embed-text in the "models" array

Why Ollama? Signet needs an embedding model to convert text into vectors for semantic search. Running it locally via Ollama means: (1) no embedding API costs, (2) no data leaves your machine, (3) embeddings work offline. Ollama serves nomic-embed-text on localhost:11434 — the Signet daemon connects to it automatically when embedding.provider: ollama is set in agent.yaml.

Step 7 — Install signet-first

signet-first forces the AI to use Signet as its primary memory system instead of markdown files. It installs as an OpenCode plugin — added to opencode.json in Step 9.

The plugin auto-injects the memory protocol into every session at the infrastructure level, before the agent's first reasoning step. No manual skill loading needed.

Verify (after Step 9):

# Start OpenCode and ask something from a previous session.
# The agent should search Signet memory first, before reading files or firing agents.

What does signet-first do?

Auto-injection — the plugin injects the memory protocol into every session's first > message, guaranteed at the infrastructure level (not dependent on agent reasoning).

Search-before-act — before reading any file or firing any agent, the agent searches > Signet. Only falls back to markdown if Signet returns no results (with a mandatory warning).

Store protocol — after every investigation, analysis, or decision, conclusions are > stored in Signet immediately with type, scope, and importance metadata.

Session handoff — each session ends with a daily-log summary, and the next session > reads it before doing anything else.

Step 8 — Install MCP Servers (Math + Diagrams + Database + API Testing)

This step installs five components. Complete them in order.

Four local MCP servers give the AI direct capabilities: Fermat MCP for math computation and plotting, UML-MCP for diagram generation (both via Python/uv), DBHub for direct MySQL database access, and API Testing MCP for REST API testing.

8a — Install uv and Python 3.13

uv is a fast Python package manager written in Rust. It replaces pip + venv.

# Install uv (cross-platform)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or on Ubuntu, via snap
sudo snap install uv

# Or on macOS, via Homebrew
brew install uv

Verify:

uv --version   # Expected: uv 0.11.x

Install Python 3.13

Fermat MCP requires Python 3.13+. uv can install it for you:

uv python install 3.13

Verify:

uv python list | grep 3.13   # Should show an installed 3.13.x

8b — Clone Fermat MCP

# Clone the repo
mkdir -p ~/tools
git clone https://github.com/abhiphile/fermat-mcp ~/tools/fermat-mcp

# Enter the directory and sync dependencies
cd ~/tools/fermat-mcp
uv sync

This creates a .venv/ with all dependencies (FastMCP, Matplotlib, NumPy, SymPy).

Verify:

uv run python -c "import fastmcp; print('FastMCP OK')"
uv run python -c "import matplotlib; print('Matplotlib OK')"
uv run python -c "import numpy; print('NumPy OK')"
uv run python -c "import sympy; print('SymPy OK')"

What's Fermat MCP? Three sub-servers in one:

mpl_mcp — Matplotlib: bar charts, scatter plots, line charts, stem plots, stacked charts, equation plots

numpy_mcp — NumPy: add/sub/mul/div, trig, statistics (mean, median, std), linear algebra (dot, inv, det, eig, > svd)

sympy_mcp — SymPy: simplify, expand, factor, differentiate, integrate, limits, series, solve equations, matrix > operations

Important: Remember the absolute path where you cloned it. You'll need it in the next step for opencode.json.

8c — Clone UML-MCP (Diagram Generation Server)

UML-MCP generates UML diagrams, sequence diagrams, class diagrams, flowcharts, and 30+ diagram types via Kroki, PlantUML, Mermaid, and D2.

git clone https://github.com/antoinebou12/uml-mcp ~/tools/uml-mcp

cd ~/tools/uml-mcp
uv sync

Verify:

cd ~/tools/uml-mcp && uv run python server.py --list-tools
# Expected: "MCP server created with 3 tools, 10 prompts, and 9 resources"

What's UML-MCP? One server, multiple renderers:

PlantUML — class, sequence, activity, use case, state, component, deployment, object diagrams

Mermaid — flowcharts, sequence, class, ER, Gantt, pie, state diagrams

D2 — declarative diagrams compiled to SVG/PNG

Graphviz — DOT-based graph layouts

Specialized — C4, BPMN, ERD, BlockDiag, TikZ, Nomnoml, and more via Kroki

8d — Install DBHub (Database MCP Server)

DBHub is a universal database MCP server that gives the AI direct access to MySQL databases — schema inspection, query execution, and object search. It connects to the Matecat dev and test databases in read-only mode.

npm install -g @bytebase/dbhub@latest

Verify:

npm -g list | grep dbhub   # Expected: ├── @bytebase/dbhub@0.21.x
dbhub --demo               # Expected: 0.21.x

Create the DBHub config file:

Prerequisite: These database connections assume Matecat dev/test MySQL instances are already running on 127.0.0.1:3306 with credentials admin:admin. Skip this step if you haven't set up the Matecat Docker stack yet — DBHub is optional until the project database is available.

cat > ~/tools/dbhub.toml << 'DBEOF'
[[sources]]
id       = "matecat"
dsn      = "mysql://admin:admin@127.0.0.1:3306/matecat"
query_timeout      = 30
connection_timeout  = 10

[[sources]]
id       = "matecat_test"
dsn      = "mysql://admin:admin@127.0.0.1:3306/unittest_matecat_local"
query_timeout      = 30
connection_timeout  = 10
lazy     = true

[[tools]]
name     = "execute_sql"
source   = "matecat"
readonly = true
max_rows = 500

[[tools]]
name     = "execute_sql"
source   = "matecat_test"
readonly = true
max_rows = 500

[[tools]]
name     = "search_objects"
source   = "matecat"

[[tools]]
name     = "search_objects"
source   = "matecat_test"
DBEOF

What's DBHub? A minimal, token-efficient database MCP server by Bytebase:

execute_sql — run SELECT, SHOW, DESCRIBE, EXPLAIN queries (read-only by default)

search_objects — search schemas, tables, columns, indexes, procedures

Connects to both matecat (dev) and matecat_test (unit tests) databases

Config via TOML file with hot-reload support

8e — Install API Testing MCP (REST API Testing Server)

API Testing MCP is a comprehensive REST API testing server that gives the AI the ability to make HTTP requests, run assertions, chain multi-step flows, import OpenAPI specs, run load tests, and manage test environments — all from within OpenCode.

npm install -g @cocaxcode/api-testing-mcp@latest

Verify:

npx @cocaxcode/api-testing-mcp --help 2>/dev/null || echo "Installed (stdio server — no --help flag)"

What's API Testing MCP? A full API testing workbench with 42 tools:

HTTP requests — GET, POST, PUT, PATCH, DELETE with headers, auth, JSON bodies

Assertions — 10 operators for validating status codes, response bodies, headers, timing

Multi-step flows — chain requests with variable extraction (e.g., login → use token → verify)

OpenAPI import — load a Swagger/OpenAPI spec and auto-generate request templates

Environments — manage BASE_URL, tokens, and variables per environment (dev/staging/prod)

Load testing — concurrent requests with percentile metrics

Collections — save and reuse request sets

Postman import/export — interop with existing Postman workflows

Step 9 — Update the OpenCode Config (Final)

Now all plugins are installed. Update ~/.config/opencode/opencode.json with the complete configuration:

This command overwrites ~/.config/opencode/opencode.json. If you already use OpenCode with custom config, back it up first: cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak

cat > ~/.config/opencode/opencode.json << OCEOF
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-openagent@latest",
    "./plugins/signet.mjs",
    "./plugins/signet-first-bootstrap.js"
  ],
  "mcp": {
    "fmcp": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "$HOME/tools/fermat-mcp",
        "run",
        "server.py"
      ],
      "enabled": true
    },
    "uml-mcp": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "$HOME/tools/uml-mcp",
        "run",
        "server.py"
      ],
      "enabled": true
    },
    "signet": {
      "type": "local",
      "command": ["signet-mcp"],
      "enabled": true
    },
    "dbhub": {
      "type": "local",
      "command": [
        "dbhub",
        "--transport",
        "stdio",
        "--config",
        "$HOME/tools/dbhub.toml"
      ],
      "enabled": true
    },
    "api-testing": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@cocaxcode/api-testing-mcp@latest"
      ],
      "enabled": true
    }
  }
}
OCEOF

Three plugins loaded:

oh-my-openagent@latest — multi-model orchestration

./plugins/signet.mjs — session memory + lifecycle hooks

./plugins/signet-first-bootstrap.js — auto-injects Signet memory protocol into every session

Five MCP servers:

signet-mcp — gives the AI direct access to memory tools (search, store, modify, forget)

fmcp — gives the AI math computation and plotting (Matplotlib, NumPy, SymPy)

uml-mcp — gives the AI diagram generation (UML, sequence, class, flowcharts, 30+ types via Kroki/PlantUML/Mermaid/D2)

dbhub — gives the AI direct MySQL database access (schema inspection, queries, read-only)

api-testing — gives the AI REST API testing (HTTP requests, assertions, flows, OpenAPI import, load testing)

Step 10 — Verify Everything

Run these sanity checks. Core tools (checks 1–10) should pass. MCP checks (11–14) may fail if optional components weren't installed. Check 15 validates config file syntax.

echo "=== 1. Node.js ==="
node --version

echo "=== 2. Python + uv ==="
uv --version
uv python list 2>/dev/null | grep 3.13 | head -1

echo "=== 3. Bun ==="
bun --version

echo "=== 4. OpenCode ==="
opencode --version

echo "=== 5. Oh-My-OpenAgent ==="
npm list -g --depth=0 | grep oh-my

echo "=== 6. Superpowers ==="
ls ~/.config/opencode/plugins/superpowers.js &>/dev/null && echo "Plugin installed" || echo "MISSING — restart OpenCode to auto-install"

echo "=== 7. Signet ==="
signet --version
signet status

echo "=== 8. Signet Plugin ==="
ls ~/.config/opencode/plugins/signet.mjs && echo "OK" || echo "MISSING — run: signet sync"

echo "=== 9. signet-first ==="
grep -q "signet-first" ~/.config/opencode/opencode.json && echo "Plugin registered in opencode.json" || echo "MISSING from opencode.json"

echo "=== 10. Ollama ==="
ollama --version && echo "Ollama OK" || echo "MISSING — see Step 6"
ollama list 2>/dev/null | grep -q "nomic-embed-text" && echo "nomic-embed-text model OK" || echo "MISSING — run: ollama pull nomic-embed-text"
ollama list 2>/dev/null | grep -q "llama3.1:8b" && echo "llama3.1:8b model OK (local extraction)" || echo "llama3.1:8b not installed (optional — only needed for local extraction)"

echo "=== 11. Fermat MCP ==="
cd ~/tools/fermat-mcp && uv run python -c "from fmcp.mpl_mcp.server import mpl_mcp; print('mpl_mcp OK')" && echo "Fermat MCP OK" || echo "MISSING"
cd -

echo "=== 12. UML-MCP ==="
cd ~/tools/uml-mcp && uv run python server.py --list-tools &>/dev/null && echo "UML-MCP OK" || echo "MISSING"
cd -

echo "=== 13. DBHub ==="
npm -g list @bytebase/dbhub && echo "DBHub OK" || echo "MISSING — run: npm install -g @bytebase/dbhub@latest"

echo "=== 14. API Testing MCP ==="
npm list -g --depth=0 | grep cocaxcode && echo "API Testing MCP OK" || echo "MISSING — run: npm install -g @cocaxcode/api-testing-mcp@latest"

echo "=== 15. Config files ==="
cat ~/.config/opencode/opencode.json | python3 -m json.tool > /dev/null && echo "opencode.json: valid JSON" || echo "opencode.json: INVALID"
cat ~/.config/opencode/oh-my-opencode.json | python3 -m json.tool > /dev/null && echo "oh-my-opencode.json: valid JSON" || echo "oh-my-opencode.json: INVALID"

Example output (versions may differ):

=== 1. Node.js ===
v22.22.1
=== 2. Python + uv ===
uv 0.11.1
cpython-3.13.x-linux-x86_64-gnu    ...
=== 3. Bun ===
1.3.11
=== 4. OpenCode ===
1.14.22
=== 5. Oh-My-OpenAgent ===
├── oh-my-opencode@3.17.5
=== 6. Superpowers ===
Plugin installed
=== 7. Signet ===
0.108.0
● Daemon running ...
=== 8. Signet Plugin ===
OK
=== 9. signet-first ===
Plugin registered in opencode.json
=== 10. Ollama ===
ollama version is 0.x.x
Ollama OK
nomic-embed-text model OK
llama3.1:8b not installed (optional — only needed for local extraction)
=== 11. Fermat MCP ===
mpl_mcp OK
Fermat MCP OK
=== 12. UML-MCP ===
UML-MCP OK
=== 13. DBHub ===
0.21.2
DBHub OK
=== 14. API Testing MCP ===
├── @cocaxcode/api-testing-mcp@0.12.11
API Testing MCP OK
=== 15. Config files ===
opencode.json: valid JSON
oh-my-opencode.json: valid JSON

Step 11 — Smoke Test

Start OpenCode in any project directory:

cd ~/your-project
opencode

Test each component:

Test	What to Type	Expected
Basic response	`hello, what model are you?`	Should identify itself and model
Superpowers	`do you have superpowers?`	Should say yes and list skills
Memory store	`remember that my preferred editor theme is dark`	Should confirm memory stored
Memory recall	(new session) `what theme do I prefer?`	Should recall "dark mode"
signet-first	`remember that my favorite color is blue`	Should store in Signet, not .md
Background agents	`[search-mode] what files are in this project?`	Should launch explore agents
Diagram generation	`generate a simple class diagram with User and Order classes`	Should produce UML via uml-mcp
Database query	`run SELECT COUNT(*) FROM jobs on the matecat database`	Should return a number via dbhub (requires local MySQL)
API testing	`make a GET request to http://localhost/api/v2/ping`	Should return HTTP response (requires local API running)

Note: If plugins like Superpowers are not loading, restart OpenCode.

File Map (What Goes Where)

~/.nvm/                                          # Node.js version manager
    versions/node/v22.x.x/bin/
        node, npm                                # Node.js runtime
        opencode                                 # → opencode-ai
        oh-my-opencode                           # → oh-my-opencode
        signet, signet-mcp, signet-daemon        # → signetai

~/.config/opencode/                              # OpenCode config root
    opencode.json                                # Main config (plugins + MCP)
    oh-my-openagent.json                        # Agent-model mappings (real file)
    oh-my-opencode.json → oh-my-openagent.json  # Symlink (see Step 3 — filename bug fix)
    AGENTS.md                                    # Auto-generated by Signet
    plugins/
        signet.mjs                               # Written by `signet sync`
        superpowers.js                           # Auto-installed from plugin entry on restart
        signet-first-bootstrap.js                # Auto-installed from plugin entry on restart

~/.agents/                                       # Signet workspace
    agent.yaml                                   # Signet configuration
    AGENTS.md, SOUL.md, IDENTITY.md, USER.md     # Agent identity files
    MEMORY.md                                    # Generated memory summary
    memory/
        memories.db                              # SQLite database
    skills/                                      # Signet-managed skills
    .daemon/
        pid                                      # Daemon process ID
        logs/                                    # Daily log files

~/tools/fermat-mcp/                              # Fermat MCP (Matplotlib + NumPy + SymPy)
    server.py                                    # Entry point
    .venv/                                       # Created by `uv sync`

~/tools/uml-mcp/                                 # UML-MCP (PlantUML + Mermaid + D2 + Kroki)
    server.py                                    # Entry point
    .venv/                                       # Created by `uv sync`

~/tools/dbhub.toml                               # DBHub config (MySQL connections + tool settings)
                                                 # (api-testing-mcp is npm global — no local config file)

~/.bun/bin/bun                                   # Bun runtime (Signet daemon)

~/.ollama/                                       # Ollama model storage
    models/
        manifests/                               # Model metadata
        blobs/                                   # Model weights (nomic-embed-text ~274 MB)

Updating

# OpenCode
npm update -g opencode-ai

# Oh-My-OpenAgent
npm update -g oh-my-opencode

# Superpowers — auto-installed from opencode.json plugin entry on restart

# Signet
npm update -g signetai && signet daemon restart

# signet-first — auto-installed from opencode.json plugin entry on restart

# Ollama
curl -fsSL https://ollama.com/install.sh | sh   # Linux: re-run the installer
# macOS: download latest DMG from ollama.com/download, or: brew upgrade ollama
ollama pull nomic-embed-text                      # Re-pull to get latest model revision
# ollama pull llama3.1:8b                         # Optional: only if using local extraction

# DBHub
npm update -g @bytebase/dbhub@latest

# API Testing MCP
npm update -g @cocaxcode/api-testing-mcp@latest

Troubleshooting

Problem	Solution
`opencode: command not found`	Run `source ~/."${SHELL##*/}rc"` or open a new terminal
Signet daemon not running	`signet daemon start`
`signet.mjs` missing in plugins	`signet sync` then restart OpenCode
Memory not injected in new session	Verify `signet.mjs` exists, restart OpenCode
Ollama not running	Linux: `sudo systemctl start ollama` / macOS: launch Ollama.app
`nomic-embed-text` not found	`ollama pull nomic-embed-text`
Signet extraction blocked (opencode)	Check `signet status` — kill stale `opencode serve` on port 4096, restart daemon
Signet extraction blocked (ollama)	Verify Ollama is running and `llama3.1:8b` is pulled; check `signet status`
JSON parse error in config	Validate with `python3 -m json.tool < file.json`
Plugin not auto-installing	Check `opencode.json` contains the expected plugin entries and restart OpenCode
Oh-My-OpenAgent not activating	Check `opencode.json` has `"oh-my-openagent@latest"` in plugin array
Wrong Node.js version	`nvm use 22`

Quick Reference Card

# Start coding
opencode

# Signet
signet status                    # Check daemon health
signet dashboard                 # Web UI at localhost:3850
signet remember "important fact" # Store memory
signet recall "search query"     # Search memories
signet sync                      # Re-register plugins + hooks
signet daemon restart            # Restart after config changes
signet doctor                    # Full diagnostics

# Ollama
ollama list                      # Show installed models
ollama pull nomic-embed-text     # Pull/update embedding model
# ollama pull llama3.1:8b        # Optional: local extraction model
sudo systemctl status ollama     # Check server status (Linux)

# Superpowers + signet-first — update automatically on OpenCode restart

Recipe based on a running Ubuntu 24.04 workstation. macOS steps cross-checked against official docs. Windows appendix is untested — use WSL for the recommended experience.

Appendix: Windows (Untested)

⚠️ This section is UNTESTED. Windows commands below are derived from official documentation but have not been validated on a real Windows machine. Signet does not officially support native Windows yet — their docs say "Windows support planned." The recommended approach for Windows is to install WSL (Windows Subsystem for Linux) and follow the main Linux instructions above.

WSL (Recommended)

Install WSL with Ubuntu, then follow the main recipe as-is:

wsl --install -d Ubuntu-24.04

After WSL is running, open the Ubuntu terminal and follow Steps 1–11 above unchanged.

Native Windows (Experimental)

If you prefer native Windows without WSL, each tool has a Windows-specific installer. Steps not listed here (OpenCode, Oh-My-OpenAgent, API Testing MCP) use npm and work identically on Windows. Signet does not officially support native Windows — use WSL for the full stack.

W-1 — Node.js (nvm-windows)

Native Windows uses nvm-windows, which is a separate project from nvm-sh/nvm. Download the latest installer from nvm-windows releases.

# After installing nvm-windows:
nvm install 22
nvm use 22

Gotcha: Uninstall any existing Node.js installation first to avoid PATH conflicts. nvm-windows often requires an Administrator shell for symlink operations.

W-5a — Bun (PowerShell)

powershell -c "irm bun.sh/install.ps1|iex"

You may need to add %USERPROFILE%\.bun\bin to your PATH manually.

W-5b — Signet

⚠️ Signet does not officially support native Windows. The daemon uses Unix-specific tooling (systemd/launchd for service management, Unix paths, lsof for diagnostics). npm install -g signetai may install the CLI, but the daemon is unlikely to work correctly. Use WSL instead.

W-6 — Ollama (Windows)

Download the installer from ollama.com/download/windows. After install:

ollama pull nomic-embed-text
ollama list   # Should show nomic-embed-text:latest

Ollama on Windows runs as a background service automatically after installation.

W-8 — uv (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or via package managers:

winget install --id=astral-sh.uv -e
# or: scoop install main/uv

File Paths on Windows

Linux/macOS Path	Windows Equivalent
`~/.config/opencode/`	`%USERPROFILE%\.config\opencode\`
`~/.agents/`	`%USERPROFILE%\.agents\`
`~/.bun/bin/bun`	`%USERPROFILE%\.bun\bin\bun.exe`
`~/.ollama/`	`%USERPROFILE%\.ollama\`
`~/tools/fermat-mcp/`	`%USERPROFILE%\tools\fermat-mcp\`
`~/tools/dbhub.toml`	`%USERPROFILE%\tools\dbhub.toml`

Ostico/developer-workstation-setup.md

Developer Workstation Setup Recipe

What You're Installing

Prerequisites

Step 1 — Install Node.js via nvm

Step 2 — Install OpenCode

First-Time Setup

Configure GitHub Copilot (Multi-Model Access)

Step 3 — Install Oh-My-OpenAgent

Register Oh-My-OpenAgent as an OpenCode Plugin

Configure Oh-My-OpenAgent Models

Fix the Config Filename Bug

Step 4 — Install Superpowers

Step 5 — Install Signet AI

Install Bun (Signet Daemon Requirement)

Install Signet

Run the Setup Wizard

CRITICAL: Sync the OpenCode Plugin

Configure the Memory Pipeline

Optional: Local Extraction with Ollama (saves cloud tokens)

Step 6 — Install Ollama (Embedding + Optional Extraction Server)

Install Ollama

Pull the Embedding Model

Verify the Server Is Running

Step 7 — Install signet-first

Step 8 — Install MCP Servers (Math + Diagrams + Database + API Testing)

8a — Install uv and Python 3.13

Install Python 3.13

8b — Clone Fermat MCP

8c — Clone UML-MCP (Diagram Generation Server)

8d — Install DBHub (Database MCP Server)

8e — Install API Testing MCP (REST API Testing Server)

Step 9 — Update the OpenCode Config (Final)

Step 10 — Verify Everything

Step 11 — Smoke Test

File Map (What Goes Where)

Updating

Troubleshooting

Quick Reference Card

Appendix: Windows (Untested)

WSL (Recommended)

Native Windows (Experimental)

W-1 — Node.js (nvm-windows)

W-5a — Bun (PowerShell)

W-5b — Signet

W-6 — Ollama (Windows)

W-8 — uv (PowerShell)

File Paths on Windows