A few things outside what you named that are still worth knowing (not extra tools to install as products): - You will need **system packages** for GTK4 and the C toolchain (libgtk-4-dev, CMake, Ninja). The agent can install them, but you should approve those commands. - Put the project in its **own empty folder** and git init it. /undo helps; git is the real safety net. - **Contributor** means Meta may train on prompts and code you send. Fine for this exercise; do not point it at private work later without switching model IDs. - OpenCode **Plan** vs **Build** (Tab) is the habit that matters more than the toolkit. - Drop the calculator screenshot into the session so the agent can match layout. --- # VS Code + OpenCode + Muse Spark 1.3 Contributor ## GTK4 calculator in C (Ubuntu 26.04 / MATE) Goal: learn the **tools**, not GTK. Treat GTK as “the library the agent uses.” --- ## 0. One-time Ubuntu packages In a normal terminal (not required to be VS Code yet): Bash ``` sudo apt update sudo apt install -y build-essential cmake ninja-build pkg-config git \ libgtk-4-dev ``` Check: Bash ``` gcc --version cmake --version pkg-config --modversion gtk4 code --version ``` If code is missing: in VS Code, Command Palette → **Shell Command: Install 'code' command in PATH**. Optional but useful: Node.js 18+ only if you install OpenCode via npm instead of the curl script. --- ## 1. Create a Meta Model API key 1. Open [https://ai.developer.meta.com](https://ai.developer.meta.com/) (or the Model API dashboard linked from Meta’s Muse Spark docs). 2. Sign in with a Meta account. 3. Create an **API key**. Keys often look like LLM|…|…. 4. Copy it once. Store it in a password manager. **Do not** put it in the project repo. New accounts sometimes have a small credit; Contributor is cheap (muse-spark-1.3-contributor: about $0.10 / $0.20 per million tokens) and Meta may use prompts/completions for training. Rate limit is lower than the paid standard tier (~100 RPM). Plenty for this project. --- ## 2. Install OpenCode CLI Bash ``` curl -fsSL https://opencode.ai/install | bash ``` Close and reopen the terminal (or source ~/.bashrc) so opencode is on PATH. Bash ``` opencode --version ``` Alternative: npm install -g opencode-ai. Docs: https://opencode.ai/docs --- ## 3. Open VS Code the official way Bash ``` mkdir -p ~/src/gtk-calc-lab cd ~/src/gtk-calc-lab git init code . ``` In VS Code’s **integrated terminal** (Ctrl+`): Bash ``` opencode ``` First run should offer to install the official VS Code integration. Accept it. Useful keys (Linux): | Action | Shortcut | | ----------------------------------------- | -------------- | | Open / focus OpenCode in a split terminal | Ctrl+Esc | | New OpenCode session | Ctrl+Shift+Esc | | Insert file reference | Alt+Ctrl+K | You stay in the terminal agent. That is intentional. --- ## 4. Connect Meta and pick Contributor Inside the OpenCode TUI: text ``` /connect ``` - If **Meta** appears in the list, select it and paste the API key. - If not, pick **Other**, provider id meta, paste the key, then add config (next). Create or edit **global** config (not in the git repo): ~/.config/opencode/opencode.json JSON ``` { "$schema": "https://opencode.ai/config.json", "provider": { "meta": { "name": "Meta Model API", "npm": "@ai-sdk/openai", "options": { "baseURL": "https://api.meta.ai/v1" }, "models": { "muse-spark-1.3-contributor": { "name": "Muse Spark 1.3 Contributor", "reasoning": true, "limit": { "context": 1048576, "output": 131072 }, "modalities": { "input": ["text", "image", "pdf", "video"], "output": ["text"] }, "options": { "reasoningEffort": "medium", "reasoningSummary": "auto", "include": ["reasoning.encrypted_content"] } } } } } } ``` Notes: - Use @ai-sdk/openai and https://api.meta.ai/v1 so Muse Spark uses the **Responses** API (what Meta documents for OpenCode). - Restart OpenCode after saving. - /models and select muse-spark-1.3-contributor. - Status line should show something like **Muse Spark 1.3 Contributor · Meta**. For learning, keep reasoning at **medium**. Raise to high only if the agent flails. ### Permissions (ask before writes and shell) In the same opencode.json (or project opencode.json later), prefer the safer default: **do not** turn on auto-approve. When a tool call appears (write file, apt, cmake, run binary), read the diff/command and approve or reject. If the UI has an “Open” / auto-approve switch, leave it off for this project. --- ## 5. Hello-world test (prove the loop) Still in ~/src/gtk-calc-lab, in OpenCode: text ``` /init ``` That writes AGENTS.md (project hints for the agent). Fine to keep. Then paste: text ``` Do not create a GUI yet. Create a tiny CMake + Ninja C project in this folder: - src/hello.c that prints "hello from opencode" and exits 0 - CMakeLists.txt that builds an executable named hello - A one-line README with the exact build commands Use out-of-source build in build/. After writing files, show me the commands. Wait for my approval before running cmake or the binary. ``` You should: 1. See a plan or file diffs. 2. Approve writes. 3. Approve: Bash ``` cmake -S . -B build -G Ninja cmake --build build ./build/hello ``` 4. See hello from opencode. If that works, VS Code + OpenCode + Meta + CMake are wired. If it fails: - Model not selected → /models - 401 → /connect again, check key - Empty reply / truncated reasoning → output limit or wrong adapter; confirm npm is @ai-sdk/openai and model id is exactly muse-spark-1.3-contributor - Extension missing → run opencode from the **VS Code** terminal, not an external one Optional VS Code check: Command Palette → **CMake: Configure** on the same folder. Not required if you build from the terminal. --- ## 6. Other options (know they exist; skip for now) | Option | When to consider | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | OpenCode Zen | Bundled models; there has been a free Contributor-style Muse SKU through Zen. Extra account. | | Standard muse-spark-1.3 | Same model, no training-on-your-data, ~12–21× more expensive | | Ollama local model | Offline; weaker agent than Spark 1.3 | | Third-party VS Code sidebars (OpenCode Panel, Varro, OpenCode GUI) | Chat panel instead of split terminal. Add later if you want diffs in a sidebar. | | Cline / Continue-style extensions | Different agent. Ignore for this exercise. | | Qt6 | Fine later; more packages, not needed to learn OpenCode | | Meson | Native for some GNOME apps; you asked for CMake | Stay on official CLI + Contributor + ask-before-apply. --- ## 7. Calculator project — how to prompt Keep using the **same folder** or start clean: Bash ``` cd ~/src/gtk-calc-lab # optional: git checkout a new branch git checkout -b calculator ``` Attach the screenshot (drag into the OpenCode terminal). Muse Spark accepts images. ### Step A — Plan only Press **Tab** until you are in **Plan** mode. text ``` I am an experienced embedded C developer learning VS Code + OpenCode. I do not want a GTK tutorial. You own the GTK4 details. Build a simple Linux desktop calculator in C + GTK4 + CMake + Ninja that looks like the attached screenshot. Requirements: - Single window titled "Calculator" - Menu bar: Calculator, Mode, View, Help (Calculator can be File-style: Quit is enough; other menus can be stubs or simple About) - Large read-only expression/result entry at the top - Button grid matching the screenshot as closely as practical: 7 8 9 ÷ Undo Clear (Clear is red) 4 5 6 × ( ) 1 2 3 − x² √ 0 . % + = (Equals is wide and blue, spans remaining cells) - Keyboard support for digits and + - * / Enter Backspace Escape - Correct operator precedence, parentheses, percent, square, square root - No crash on divide-by-zero; show an error in the display - No network, no extra frameworks - C11, GTK4 only - CMake + Ninja, target name calculator - Keep C files small and readable (main UI vs evaluation) - README with Ubuntu package list and build/run commands First produce a short plan: files you will create, how you will evaluate expressions, and how you will match the layout. Do not write code until I say so. ``` Read the plan. Push back in plain language (“put eval in its own .c”, “Clear must not be the same color as Undo”). ### Step B — Build Tab back to **Build** mode: text ``` The plan is approved. Implement it in this folder. Replace the hello-world files if they conflict. Show diffs. Do not run cmake until I approve. ``` Approve file writes. Then approve build: Bash ``` cmake -S . -B build -G Ninja cmake --build build ./build/calculator ``` On MATE this should be a normal X11/Wayland window. --- ## 8. How to ask for changes Be specific. Name the widget or behavior. One change per prompt until you trust it. Examples: text ``` Clear must be solid red and Equals solid blue, similar to the screenshot. Use GTK CSS on those two buttons only. Do not restyle the whole app. ``` text ``` Undo should remove the last character from the expression, not clear everything. Clear still wipes the display. ``` text ``` The window is too wide. Match a compact calculator: smaller padding, square-ish number keys, Equals still wider than the others. ``` text ``` % should mean “percent of the current value” as in a four-function calculator, not modulo. ``` text ``` Add a Mode menu item "Degrees" vs "Radians" but do not add sin/cos yet. Just store the flag and print it in a comment or status if easy. ``` text ``` Explain @src/eval.c in five bullet points. Do not change code. ``` Useful OpenCode commands: - /undo — revert last agent turn - /redo - @path/to/file — pin a file in the prompt - Tab — Plan vs Build After each accepted change: Bash ``` git add -A && git commit -m "calculator: describe the change" ``` --- ## 9. Suggested workflow while you learn 1. **You** decide the outcome in one sentence. 2. **Plan mode** for anything more than a one-file tweak. 3. **You** approve diffs and shell. 4. **You** run the binary and click through. 5. **You** write the next prompt from what you saw, not from theory. 6. Commit. If the agent starts teaching GTK, steer it: text ``` Stop explaining GTK. Change the code. I will review the diff. ``` If it installs random libraries: text ``` GTK4 and CMake only. Do not add extra dependencies. ``` --- ## 10. What “done” looks like - OpenCode in VS Code terminal, model = Muse Spark 1.3 Contributor - Hello program built with CMake/Ninja - ./build/calculator looks in the same family as your screenshot - You have used Plan, Build, approve-write, approve-shell, and a follow-up UI prompt When you have walked through it, say what you want tightened and I will turn this into a short markdown file.