Profile

Personal OpenCode environment setup. One command, clean defaults, managed MCPs, and project files on demand.

Installs OpenCode, writes global rules, enables PTY/LSP/MCPs, configures RTK, and can generate a compact project map for OpenCode.

Commands

npx @erminhhho/profile help

Init — full environment setup

npx @erminhhho/profile init

Detects environment, checks prerequisites, installs/validates tools, removes old managed files, generates the complete project setup, and finishes with doctor. It does not start loop.cjs.

| Tool | What it does | How it hooks in | | ---------------- | -------------------------------------------- | ------------------------ | | opencode-pty | Background and interactive terminal sessions | OpenCode plugin | | Serena | Semantic code navigation and refactoring | OpenCode MCP | | RTK | Compresses command output (git/test/lint) | OpenCode PreToolUse hook | | LSP | Code diagnostics and semantic navigation | OpenCode config |

init is strict. If OpenCode, opencode-pty, Serena, RTK, cleanup, any generator, or doctor checks fail, the command fails.

Individual generators

npx @erminhhho/profile agents
npx @erminhhho/profile spec
npx @erminhhho/profile loop
npx @erminhhho/profile map
npx @erminhhho/profile config

agents generates AGENTS.md, spec creates SPEC.md when it does not exist, loop generates LOOP.md and loop.cjs, map generates .opencode/map.md, and config generates the global and project OpenCode configuration.

Map — generate project context

npx @erminhhho/profile map

Writes .opencode/map.md. The map is deterministic and small: package scripts, runtime hints, config files, entry points, routes, data files, and tests.

Doctor — diagnose setup

npx @erminhhho/profile doctor

Checks whether OpenCode, opencode-pty, Serena, project AGENTS.md and opencode.json, allowed project permissions, LSP, managed MCPs, and the current project map are active.

Generated files

Managed files:

• LOOP.md — project workflow generated by profile init or profile loop
• SPEC.md — project specification template created by profile init or profile spec only when missing
• loop.cjs — project loop runner generated by profile init or profile loop
• AGENTS.md — local project instructions generated by profile init or profile agents
• .opencode/map.md — project map generated by profile init or profile map
• opencode.json — portable project OpenCode config with opencode-pty, allowed permissions, LSP, managed MCPs, compact tool output defaults, and project instructions

The OpenCode config is project-local and can be versioned with the repository, so it applies consistently on Windows, Linux, and macOS.

OpenCode model selection is not hardcoded by this profile. config and init preserve existing model/provider settings.

The generated AGENTS.md tells OpenCode to use Serena for semantic code work, Context7/Nuxt UI for current docs, Playwright for UI verification, and PTY sessions for dev servers, watch modes, REPLs, prompts, and commands that may hang. One-shot commands still use normal shell execution.

Managed MCPs:

• Enabled by config: serena, nuxt-ui, context7, sequential, playwright, filesystem, and firecrawl
• Serena is disabled by default on Windows because each OpenCode instance starts a separate local MCP process.

Restart OpenCode after init, config, or MCP changes; OpenCode loads config only on startup.

Legacy files from earlier versions are removed during init:

• .github/copilot-instructions.md
• .github/instructions/
• .github/skills/
• .github/profile.manifest.json

Profile files

Edit these in the repo to change agent behavior:

| File | Purpose | | ----------------- | ----------------------------------------------------- | | stack.md | Technology stack (Nuxt, Biome, PostgreSQL, Docker) | | architecture.md | App structure: autonomous, flat, no coupling | | design.md | Design philosophy: functional, minimal, Nuxt UI-first | | naming.md | Naming conventions: single-word, lowercase, English | | workstyle.md | Execution gates: minimal changes, real-flow validation |

Publishing

npm test
npm version patch  # or minor / major
npm publish

After publish, workspaces update with:

npx @erminhhho/profile init
npx @erminhhho/profile map