{"id":47754236,"url":"https://github.com/jcchikikomori/dotfiles-opencode","last_synced_at":"2026-04-03T04:01:55.473Z","repository":{"id":347524587,"uuid":"1194344255","full_name":"jcchikikomori/dotfiles-opencode","owner":"jcchikikomori","description":"Standalone opencode configuration package for managing AI coding assistant settings, MCP integrations, and agent instructions. Part of jcchikikomori/.dotfiles","archived":false,"fork":false,"pushed_at":"2026-03-28T09:28:54.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T13:18:45.135Z","etag":null,"topics":["agentic-ai","llm","mcp","opencode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcchikikomori.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T08:15:47.000Z","updated_at":"2026-03-28T09:28:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jcchikikomori/dotfiles-opencode","commit_stats":null,"previous_names":["jcchikikomori/dotfiles-opencode"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jcchikikomori/dotfiles-opencode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcchikikomori%2Fdotfiles-opencode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcchikikomori%2Fdotfiles-opencode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcchikikomori%2Fdotfiles-opencode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcchikikomori%2Fdotfiles-opencode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcchikikomori","download_url":"https://codeload.github.com/jcchikikomori/dotfiles-opencode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcchikikomori%2Fdotfiles-opencode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31333229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T03:20:36.090Z","status":"ssl_error","status_checked_at":"2026-04-03T03:20:35.133Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","llm","mcp","opencode"],"created_at":"2026-04-03T04:01:20.947Z","updated_at":"2026-04-03T04:01:55.437Z","avatar_url":"https://github.com/jcchikikomori.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Opencode Configuration\n\n\u003e **Part of [jcchikikomori/.dotfiles](https://github.com/jcchikikomori/.dotfiles)** — A standalone package containing [opencode](https://opencode.ai) configuration files that are stowed to `~/.config/opencode/`.\n\n[![License: AI-Restricted MIT](https://img.shields.io/badge/License-AI--Restricted%20MIT-yellow.svg)](LICENSE)\n[![dotfiles](https://img.shields.io/badge/dotfiles-jcchikikomori-blue.svg)](https://github.com/jcchikikomori/.dotfiles)\n\n---\n\n## About the Agent Framework\n\nThis configuration uses **OpenAgentsControl (OAC)** — a pattern-first AI development framework that provides specialized agents for different development tasks. OAC includes:\n\n- **OpenAgent** — General purpose agent for exploration and quick tasks\n- **OpenCoder** — Production-focused agent with strict approval gates and quality standards\n- **11 specialized subagents** — ContextScout, TaskManager, CoderAgent, TestEngineer, CodeReviewer, and more\n- **198+ context files** — Core patterns, workflows, standards, and external library guides\n- **9 productivity commands** — `/add-context`, `/commit`, `/test`, `/context`, `/optimize`, etc.\n\nThe framework follows an **MVI (Minimal Viable Information)** principle for efficient token usage and implements **approval gates workflow**: Discover → Propose → Approve → Execute → Validate → Ship.\n\n---\n\n## Table of Contents\n\n- [Opencode Configuration](#opencode-configuration)\n  - [About the Agent Framework](#about-the-agent-framework)\n  - [Table of Contents](#table-of-contents)\n  - [Files](#files)\n    - [Directory Structure](#directory-structure)\n  - [Architecture](#architecture)\n  - [Setup](#setup)\n    - [1. Clone and Install Configuration](#1-clone-and-install-configuration)\n    - [2. Install OpenAgentsControl (OAC)](#2-install-openagentscontrol-oac)\n    - [3. Configure Environment](#3-configure-environment)\n    - [4. Enable MCPs](#4-enable-mcps)\n    - [5. Start Using OpenAgentsControl](#5-start-using-openagentscontrol)\n  - [Required Tokens](#required-tokens)\n  - [Plugins](#plugins)\n  - [Model Configuration](#model-configuration)\n    - [Required Environment Variables](#required-environment-variables)\n    - [Why Environment Variables?](#why-environment-variables)\n    - [Configuration Hierarchy](#configuration-hierarchy)\n    - [Supported Providers](#supported-providers)\n  - [Environment Loading](#environment-loading)\n    - [Global vs Project-Level](#global-vs-project-level)\n    - [How the Wrapper Works](#how-the-wrapper-works)\n    - [Debug Toggle](#debug-toggle)\n    - [Recursion Safety](#recursion-safety)\n  - [Per-Project Configuration](#per-project-configuration)\n    - [Minimal Project Config Example](#minimal-project-config-example)\n    - [opencode-mem Plugin](#opencode-mem-plugin)\n    - [oh-my-opencode-slim Plugin](#oh-my-opencode-slim-plugin)\n  - [Security](#security)\n  - [License](#license)\n\n---\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `opencode.jsonc` | Main config: MCPs, providers, permissions |\n| `AGENTS.md` | Global agent instructions |\n| `.env.example` | Template for MCP environment variables |\n| `.env` | **Local-only** (gitignored) — your actual tokens |\n| `oh-my-opencode-slim.template.json` | Template for oh-my-opencode-slim plugin |\n| `opencode-mem.jsonc` | Configuration for opencode-mem plugin |\n\n### Directory Structure\n\n```text\n.config/opencode/\n├── opencode.jsonc          # Main configuration\n├── AGENTS.md               # Global agent instructions\n├── .env.example            # Environment template\n├── skills/                 # 32 specialized skills\n│   ├── android/\n│   ├── backend/\n│   ├── frontend/\n│   ├── git/\n│   ├── nodejs/\n│   ├── python/\n│   └── ... (and 26 more)\n├── agents/                 # (Reserved for future use)\n├── plugins/                # Plugin configurations\n└── scripts/                # Utility scripts\n```\n\n---\n\n## Architecture\n\n```text\n┌─────────────────────────────────────────────────────────────────┐\n│                          USER REQUEST                           │\n└─────────────────────────────────────────────────────────────────┘\n                                  │\n                                  ▼\n┌─────────────────────────────────────────────────────────────────┐\n│              OPENAGENTSCONTROL (OAC) FRAMEWORK                  │\n│  ┌───────────────────────────────────────────────────────────┐  │\n│  │  OpenAgent: General purpose, exploration                  │  │\n│  │  OpenCoder: Production code, approval gates               │  │\n│  └───────────────────────────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────────┘\n                                  │\n        ┌─────────────────────────┼───────────────────────┐\n        │                         │                       │\n        ▼                         ▼                       ▼\n┌───────────────┐         ┌───────────────┐       ┌───────────────┐\n│ SKILLS        │         │ SUBAGENTS     │       │ CONTEXT FILES │\n│ (32 skills)   │         │ (11 agents)   │       │ (198+ files)  │\n│               │         │               │       │               │\n│ • android     │         │ • ContextScout│       │ • Standards   │\n│ • backend     │         │ • TaskManager │       │ • Workflows   │\n│ • frontend    │         │ • CoderAgent  │       │ • Patterns    │\n│ • git         │         │ • TestEngineer│       │ • Library     │\n│ • nodejs      │         │ • CodeReviewer│       │   Guides      │\n│ • python      │         │ • BatchExecutor│      │               │\n│ • ... (26+)   │         │ • ... (5+)    │       │               │\n└───────────────┘         └───────────────┘       └───────────────┘\n```\n\n---\n\n## Setup\n\n### 1. Clone and Install Configuration\n\n```sh\ngit clone https://github.com/jcchikikomori/dotfiles-opencode.git\ncd dotfiles-opencode\n\n# Copy configuration to ~/.config/opencode\nmkdir -p ~/.config\ncp -r .config/opencode ~/.config\n\n# Install helper scripts\nmkdir -p ~/.local/bin\ncp bin/dotfiles-opencode-env ~/.local/bin/\nchmod +x bin/install-oac\n\n# Add to PATH if not already\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 2. Install OpenAgentsControl (OAC)\n\n```sh\n# Install OAC framework (agents, context files, commands)\n./bin/install-oac install\n\n# Verify installation\n./bin/install-oac status\n```\n\nThis installs OAC to `~/.opencode/` with:\n\n- OpenAgent and OpenCoder (main agents)\n- 11 specialized subagents\n- 198+ context files\n- 9 productivity commands\n\n### 3. Configure Environment\n\n```sh\n# Copy the example env file\ncp ~/.config/opencode/.env.example ~/.config/opencode/.env\n\n# Edit and fill in your tokens (see Required Tokens section below)\nnano ~/.config/opencode/.env\n```\n\nRestart your shell (or `source ~/.profile`) to load the env vars.\n\n### 4. Enable MCPs\n\nEnable desired MCPs in `~/.config/opencode/opencode.jsonc` by setting `\"enabled\": true`.\n\n### 5. Start Using OpenAgentsControl\n\n```sh\n# Start with OpenAgent (general purpose)\nopencode --agent OpenAgent\n\n# Or use OpenCoder (production code with approval gates)\nopencode --agent OpenCoder\n\n# Or use default agent (configured in opencode.jsonc)\nopencode\n```\n\n### Install Zenox\n\n```sh\nbunx zenox install\n```\n\nThis automatically adds `zenox` to the plugin list in `opencode.jsonc`.\n\n## Plugins\n\nThis configuration uses the following plugins:\n\n| Plugin | Purpose |\n|--------|---------|\n| `envsitter-guard@latest` | Prevents accidental exposure of secrets in .env files |\n| `oh-my-opencode-slim` | Lightweight skill organization (configured via template) |\n| `@franlol/opencode-md-table-formatter@latest` | Auto-formats markdown tables |\n| `opencode-mem` | Memory/context persistence across sessions |\n| `opencode-redactor@0.1.1` | Redacts sensitive information from outputs |\n| `zenox` | (Optional) Additional plugin support |\n\n---\n\n## Required Tokens\n\n| MCP | Required Env Vars | How to Get |\n|-----|-------------------|------------|\n| `context7` | **None** — public API | Remote MCP at `https://mcp.context7.com/mcp` |\n| `web-forager` | **None** | Local command: `web-forager serve` |\n| `chrome-devtools` | **None** | Local command: `npx -y chrome-devtools-mcp@latest` |\n| `mcp-ocr` | **None** | Local command: `mcp-ocr` |\n| `github-mcp` | `GITHUB_PERSONAL_ACCESS_TOKEN` | [GitHub Settings → Developer settings → PAT](https://github.com/settings/tokens) |\n| `stackoverflow-mcp` | `STACK_EXCHANGE_API_KEY` | [Stack Apps → Register](https://stackapps.com/apps/oauth/register) |\n| `framelink-figma` | `FIGMA_API_KEY` | [Figma Settings → Personal Access Tokens](https://www.figma.com/developers/api#access-tokens) |\n| `atlassian-mcp` | `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`, `CONFLUENCE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN` | [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |\n| `sonarqube-mcp` | `SONARQUBE_TOKEN`, `SONARQUBE_URL` | Your SonarQube instance → My Account → Security |\n| `buildkite-mcp` | **None** — uses OAuth | Remote MCP at `https://mcp.buildkite.com/mcp`; authenticate via OAuth browser flow when first enabled |\n\n\u003e **Note:** MCPs marked as enabled by default: `context7`, `web-forager`, `chrome-devtools`, `mcp-ocr`. Others require configuration and enabling in `opencode.jsonc`.\n\n---\n\n## Model Configuration\n\n**IMPORTANT:** This configuration uses **environment variables** for model selection to support multiple environments (work, personal, different providers).\n\n### Required Environment Variables\n\nAdd these to `~/.config/opencode/.env`:\n\n```bash\n# Model Configuration (REQUIRED)\nOPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0\nOPENCODE_SMALL_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0\n\n# Provider-specific configuration\n# For Amazon Bedrock:\nAWS_REGION=ap-southeast-2\nAWS_PROFILE=your-aws-profile\n\n# For GitHub Copilot (if using instead of Bedrock):\n# OPENCODE_MODEL=github-copilot/claude-sonnet-4\n# OPENCODE_SMALL_MODEL=github-copilot/claude-haiku-4\n```\n\n### Why Environment Variables?\n\n✅ **Multi-environment support** - Switch between work (AWS Bedrock) and personal (GitHub Copilot) projects\n✅ **Subagent compatibility** - Subagents inherit model config correctly\n✅ **Provider flexibility** - Change providers without editing config files\n✅ **No hardcoded models** - Same config works across all machines\n\n### Configuration Hierarchy\n\nModels are resolved in this order:\n\n1. Project `.opencode/opencode.jsonc` (if it defines a model)\n2. Global `~/.config/opencode/opencode.jsonc` (uses `{env:OPENCODE_MODEL}`)\n3. Environment variable `$OPENCODE_MODEL` from `.env` file\n\n### Supported Providers\n\n| Provider | Model Prefix | Example |\n|----------|--------------|---------|\n| Amazon Bedrock | `amazon-bedrock/` | `amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0` |\n| GitHub Copilot | `github-copilot/` | `github-copilot/claude-sonnet-4` |\n| Ollama | `ollama/` | `ollama/qwen2.5-coder:32b` |\n| OpenRouter | `openrouter/` | `openrouter/anthropic/claude-sonnet-4` |\n\nFor detailed troubleshooting and best practices, see the [Model Configuration Guide](https://github.com/jcchikikomori/.dotfiles/blob/main/docs/OPENCODE_MODEL_CONFIG.md) in the main dotfiles repo.\n\n---\n\n## Environment Loading\n\n### Global vs Project-Level\n\nThe `.env` file is sourced automatically by `~/.profile` on shell startup:\n\n```sh\nif [ -f \"$HOME/.config/opencode/.env\" ]; then\n    set -a  # Auto-export all variables\n    . \"$HOME/.config/opencode/.env\"\n    set +a\nfi\n```\n\nWhen you run `opencode`, a shell wrapper loads env files in this order:\n\n1. `~/.config/opencode/.env` — global tokens (loaded first, lower precedence)\n2. Nearest `$PWD` ancestor `.opencode/.env` — project-specific overrides (loaded second, wins)\n\nThis happens **per invocation** via a subshell — no persistent shell pollution.\n\n### How the Wrapper Works\n\nThe `opencode()` function delegates to `~/.local/bin/dotfiles-opencode-env`, which:\n\n1. Loads `~/.config/opencode/.env`\n2. Walks up from `$PWD` to find nearest `.opencode/.env` and loads it\n3. `exec`s the real `opencode` binary\n\n### Debug Toggle\n\n```sh\n_DOTFILES_OPENCODE_ENV_DEBUG=1 opencode\n```\n\n### Recursion Safety\n\nThe wrapper sets `_DOTFILES_OPENCODE_ENV_LOADED=1` before `exec`-ing opencode, preventing infinite loops if the function is re-entered.\n\n---\n\n## Per-Project Configuration\n\nOverride the global config by placing `opencode.jsonc` in your project:\n\n```text\nyour-project/\n├── opencode.jsonc          # option A: project root\n└── .opencode/\n    └── opencode.jsonc      # option B: hidden directory\n```\n\nOpencode merges configs in this order (last wins):\n\n1. `~/.config/opencode/opencode.jsonc` — global\n2. `\u003cproject-root\u003e/opencode.jsonc` or `\u003cproject-root\u003e/.opencode/opencode.jsonc` — project-level\n\n### Minimal Project Config Example\n\n```jsonc\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"instructions\": [\n    \"AGENTS.md\"\n  ],\n  \"mcp\": {\n    \"sonarqube-mcp\": {\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### opencode-mem Plugin\n\nThe `opencode-mem` plugin uses environment variables for user profile information:\n\n| Variable | Purpose |\n|----------|---------|\n| `OPENCODE_MEM_USER_EMAIL` | Your email for memory attribution |\n| `OPENCODE_MEM_USER_NAME` | Your name for memory attribution |\n\n### oh-my-opencode-slim Plugin\n\nThis configuration uses `oh-my-opencode-slim` — a lightweight skill organization plugin. The template is stored in `oh-my-opencode-slim.template.json`. This is distinct from the full `oh-my-opencode` plugin which includes additional features that may not be needed for all use cases.\n\n---\n\n## Security\n\n- `.env` is gitignored via `.config/opencode/.env` pattern\n- **Never commit tokens** to git\n- Use separate tokens per machine if possible (easier to revoke)\n- Plugins like `envsitter-guard` and `opencode-redactor` help prevent accidental secret exposure\n- The `oh-my-opencode-slim` plugin provides lightweight skill organization without unnecessary dependencies\n\n---\n\n## License\n\nCopyright (c) 2026 John Cyrill Corsanes\n\nThis project is licensed under the **AI-Restricted MIT License** — see [LICENSE](LICENSE) for full text.\n\n**Key point:** Permission is granted for human use, but **AI/ML/LLM systems are prohibited** from training on or deriving output from this code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcchikikomori%2Fdotfiles-opencode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcchikikomori%2Fdotfiles-opencode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcchikikomori%2Fdotfiles-opencode/lists"}