Sanitized showcase of a role-based OpenCode profile installer for safer agentic development environments. It demonstrates how agent instructions, skills, themes, and runtime configuration can be packaged as verifiable profiles instead of copied as personal dotfiles.
- A TypeScript/Node CLI built with Ink for terminal-first setup flows.
- Installable OpenCode profiles for different collaboration and workflow styles.
- Transactional configuration updates with staging, rollback, backup, and verification.
- Managed-tree hashing to detect unexpected file differences.
- Symlink rejection to avoid copying files outside the managed profile boundary.
- Generic MCP examples for documentation lookup and browser automation.
- Tests for backup, restore, rollback, runtime checks, and safety constraints.
Agentic developer tooling is most useful when teams can standardize it safely. This showcase treats OpenCode configuration as a managed profile catalog so a team can choose a workflow model, install it consistently, and recover if anything goes wrong.
The repository is intentionally public-safe: it preserves the engineering patterns while removing private history, local state, credentials, sessions, and organization-specific integrations.
| Profile | Purpose |
|---|---|
vanilla |
Minimal OpenCode baseline with lightweight guidance. |
blueprint |
Team starter profile with plan, build, and explorer agents. |
streamlined |
Direct implementation workflow with optional explicit specialist agents. |
orchestrated |
Plan-first workflow with dedicated exploration, implementation, testing, debugging, and review agents. |
learning |
Learning and onboarding workflow for concept breakdown, tutorials, research, and diagrams. |
See docs/profile-catalog.md for details.
The CLI only manages these entries inside the OpenCode config directory:
AGENTS.mdagents/skills/themes/opencode.jsontui.json
Before replacing managed entries, it can create a backup, stage the selected profile, compare manifests, apply changes transactionally, roll back on blocking failures, and verify the final installed tree.
See docs/safety-model.md for the detailed boundaries.
The interactive setup flow can:
- Check local prerequisites.
- Detect the OpenCode runtime.
- Offer runtime install/update guidance.
- List available profiles.
- Detect differences against the current managed config.
- Create a safety backup.
- Install the selected profile transactionally.
- Verify the final managed state.
- Restore a recent backup when needed.
See docs/cli-flow.md for the end-to-end flow.
npm install
npm run check
npm run setup -- --dry-run --skip-opencode-checkUseful scripts:
npm run build # compile the CLI and copy profile assets
npm test # run the CLI safety tests
npm run check # build and test
npm run setup # launch the interactive installerThe installer writes only to the current user's OpenCode config directory when run without --dry-run. Review the profile docs and backup behavior before installing a profile on a real machine.
npm run setup -- --dry-run --skip-opencode-checkCommon flags:
--dry-run: preview the flow without applying changes.--force: skip confirmation prompts where supported.--skip-opencode-check: skip runtime detection and go straight to profile selection.--verbose: enable more detailed runtime feedback.
cli/ TypeScript/Ink installer
frameworks/ Sanitized OpenCode profile catalog
docs/ Public explanation of profiles, safety model, and CLI flow- Private repository history.
- Personal shell/session state.
- Credentials, tokens, auth files, or generated logs.
- Organization-specific remote integrations.
- Real project/client examples.
- Generated
dist/and dependency directories.
- Add non-interactive install commands for CI-friendly validation.
- Add profile metadata files for richer catalog descriptions.
- Add screenshot or terminal recording examples after sanitization.
- Add optional docs for adapting profiles to team-specific MCP servers safely.
MIT. See LICENSE.