From ed1a5ed4668cc0991b4ffc7ef7ef0fed4310b950 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Fri, 5 Dec 2025 01:12:53 +0900 Subject: [PATCH] rewrite READMEs No Vibe Writings. --- README.en.md | 132 +++++++++++++++++++++++++++++++++++++++++++++----- README.ko.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 242 insertions(+), 24 deletions(-) diff --git a/README.en.md b/README.en.md index 707b3e0..db49a85 100644 --- a/README.en.md +++ b/README.en.md @@ -1,31 +1,139 @@ English | [한국어](README.ko.md) +## Contents + +- [Oh My OpenCode](#oh-my-opencode) + - [TL;DR](#tldr) + - [Why OpenCode \& Why Oh My OpenCode](#why-opencode--why-oh-my-opencode) + - [Features](#features) + - [Hooks](#hooks) + - [Agents](#agents) + - [Tools](#tools) + - [Built-in LSP Tools](#built-in-lsp-tools) + - [Built-in AST-Grep Tools](#built-in-ast-grep-tools) + - [Safe Grep](#safe-grep) + - [Other Features](#other-features) + - [Author's Note](#authors-note) + - [Warnings](#warnings) + # Oh My OpenCode Oh My OpenCode oMoMoMoMoMo··· +If you work in tech, you likely appreciated [Claude Code](https://www.claude.com/product/claude-code). +If you are a hacker, you will fucking falling in love with [OpenCode](https://github.com/sst/opencode). -If you work in tech, you would have liked [Claude Code](https://github.com/anthropics/claude-code). -If you are a hacker, you will love [OpenCode](https://github.com/sst/opencode). +You don't write code just for a paycheck? You write because you genuinely love it? -People who write code not just for money, -But those who write code with sincerity. +To you, OpenCode will feel like the paradigm shift from Windows to Linux. Not you? It's still worth the investment. Give it 10 minutes. Your work and life will improve. I promise. -[OpenCode](https://github.com/sst/opencode) is highly extensible and extremely customizable. Also, no stupid screen flickering. -LSPs, linters, and formatters activate automatically and are customizable. You can use your own models, and mix & orchestrate them. -It has many features. Beautiful, and high-performance. +## TL;DR -And the problem that follows: there is too much to know and it is hard for beginners. +- **Model Setup Required** + - This plugin utilizes models from [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, and Anthropic. + - For Anthropic models, use [OpenCode's built-in Claude Code Max Plan login](https://opencode.ai/docs/providers/#anthropic). + - For OpenAI models, I recommend the [OpenCode-OpenAI-Codex-Auth plugin](https://github.com/numman-ali/opencode-openai-codex-auth). + - For Gemini and GPT, use [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) or [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI). +- **Truth be told, the rest is optional. Just install it. Once set up, no further learning is required. It simply evolves.** +- **Paste this document into Claude Code, OpenCode, or Cursor, instruct it to install, and ask for assistance if needed. It works seamlessly.** + - If you are an LLM Agent, install the required plugins and dependencies, then run `opencode auth login` via tmux to assist the user with configuration. -Heavily influenced and inspired by [AmpCode](https://ampcode.com) and [Claude Code](https://github.com/anthropics/claude-code), implementing their features here as-is, or even better. We are standing on the shoulders of the open-source giant, after all. +## Why OpenCode & Why Oh My OpenCode -Better [AmpCode](https://ampcode.com), Better [Claude Code](https://github.com/anthropics/claude-code), or you can think of it as a kind of distribution. +OpenCode is limitlessly extensible and customizable. Zero screen flicker. +[LSP](https://opencode.ai/docs/lsp/), [linters, formatters](https://opencode.ai/docs/formatters/)? Automatic and fully configurable. +You can mix and orchestrate models to your exact specifications. +It is feature-rich. It is elegant. It handles the terminal without hesitation. It is high-performance. -I pursue LLM polytheism, and for the sake of your finances, I recommend CliProxy or VibeProxy. Take only the best advantages of the frontier labs' LLMs. +But here is the catch: the learning curve is steep. There is a lot to master. -**Note**: This setup is Highly Opinionated, and since it includes the general-purpose parts of the setup I use, it is continuously updated. I have spent $20,000 worth of tokens solely for personal development purposes so far, and this plugin is the highlight of those experiences. You just take the best. If you have a better suggestion, contributions are always welcome. +Inspired by [AmpCode](https://ampcode.com) and [Claude Code](https://code.claude.com/docs/en/overview), I have implemented their features here—often with superior execution. +Because this is OpenCode. + +Consider this a superior AmpCode, a superior Claude Code, or simply a specialized distribution. + +I believe in the right tool for the job. For your wallet's sake, use CLIProxyAPI or VibeProxy. Employ the best LLMs from frontier labs. You are in command. + +**Note**: This setup is highly opinionated. It represents the generic component of my personal configuration, so it evolves constantly. I have spent tokens worth $20,000 just for my personal programming usages, and this plugin represents the apex of that experience. You simply inherit the best. If you have superior ideas, PRs are welcome. + +## Features + +### Hooks + +- **Todo Continuation Enforcer**: Forces the agent to complete all tasks before exiting. Eliminates the common LLM issue of "giving up halfway". +- **Context Window Monitor**: Implements [Context Window Anxiety Management](https://agentic-patterns.com/patterns/context-window-anxiety-management/). When context usage exceeds 70%, it reminds the agent that resources are sufficient, preventing rushed or low-quality output. +- **Session Notification**: Sends a native OS notification when the job is done (macOS, Linux, Windows). + +### Agents +- **oracle** (`openai/gpt-5.1`): The architect. Expert in code reviews and strategy. Uses GPT-5.1 for its unmatched logic and reasoning capabilities. Inspired by AmpCode. +- **librarian** (`anthropic/claude-haiku-4-5`): Multi-repo analysis, documentation lookup, and implementation examples. Haiku is chosen for its speed, competence, excellent tool usage, and cost-efficiency. Inspired by AmpCode. +- **explore** (`opencode/grok-code`): Fast exploration and pattern matching. Claude Code uses Haiku; we use Grok. It is currently free, blazing fast, and intelligent enough for file traversal. Inspired by Claude Code. +- **frontend-ui-ux-engineer** (`google/gemini-3-pro-preview`): A designer turned developer. Creates stunning UIs. Uses Gemini because its creativity and UI code generation are superior. +- **document-writer** (`google/gemini-3-pro-preview`): A technical writing expert. Gemini is a wordsmith; it writes prose that flows naturally. + +### Tools + +#### Built-in LSP Tools + +[OpenCode provides LSP](https://opencode.ai/docs/lsp/), but only for analysis. Oh My OpenCode equips you with navigation and refactoring tools matching the same specification. + +- **lsp_hover**: Get type info, docs, signatures at position +- **lsp_goto_definition**: Jump to symbol definition +- **lsp_find_references**: Find all usages across workspace +- **lsp_document_symbols**: Get file's symbol outline +- **lsp_workspace_symbols**: Search symbols by name across project +- **lsp_diagnostics**: Get errors/warnings before build +- **lsp_servers**: List available LSP servers +- **lsp_prepare_rename**: Validate rename operation +- **lsp_rename**: Rename symbol across workspace +- **lsp_code_actions**: Get available quick fixes/refactorings +- **lsp_code_action_resolve**: Apply a code action + +#### Built-in AST-Grep Tools + +- **ast_grep_search**: AST-aware code pattern search (25 languages) +- **ast_grep_replace**: AST-aware code replacement + +#### Safe Grep + +- **safe_grep**: Content search with safety limits (5min timeout, 10MB output). + - The default `grep` lacks safeguards. On a large codebase, a broad pattern can cause CPU overload and indefinite hanging. + - `safe_grep` enforces strict limits. + - **Note**: Default `grep` is disabled to prevent Agent confusion. `safe_grep` delivers full `grep` functionality with safety assurance. + +### Other Features + +- **Terminal Title**: Auto-updates terminal title with session status (idle ○, processing ◐, tool ⚡, error ✖). Supports tmux. + +## Author's Note + +Install Oh My OpenCode. Do not waste time configuring OpenCode from scratch. +I have resolved the friction so you don't have to. The answers are in this plugin. If OpenCode is Arch Linux, Oh My OpenCode is [Omarchy](https://omarchy.org/). + +Enjoy the multi-model stability and rich feature set that other harnesses promise but fail to deliver. +I will continue testing and updating here. I am the primary user of this project. + +- Who possesses the best raw logic? +- Who is the debugging god? +- Who writes the best prose? +- Who dominates frontend? +- Who owns backend? +- Which model is fastest for daily driving? +- What new features are other harnesses shipping? + +Do not overthink it. I have done the thinking. I will integrate the best practices. I will update this. +If this sounds arrogant and you have a superior solution, send a PR. You are welcome. + +As of now, I have no affiliation with any of the projects or models mentioned here. This plugin is purely based on personal experimentation and preference. + +## Warnings + +- If you are on [1.0.132](https://github.com/sst/opencode/releases/tag/v1.0.132) or lower, OpenCode has a bug that might break config. + - [The fix](https://github.com/sst/opencode/pull/5040) was merged after 1.0.132, so use a newer version. + +- I constructed 99% of this project using OpenCode. I focused on functional verification. This documentation has been personally reviewed and comprehensively rewritten, so you can rely on it with confidence. --- diff --git a/README.ko.md b/README.ko.md index 39e18f8..c6df68f 100644 --- a/README.ko.md +++ b/README.ko.md @@ -1,30 +1,140 @@ [English](README.en.md) | 한국어 +## 목차 + +- [Oh My OpenCode](#oh-my-opencode) + - [세 줄 요약](#세-줄-요약) + - [Why OpenCode \& Why Oh My OpenCode](#why-opencode--why-oh-my-opencode) + - [기능](#기능) + - [Hooks](#hooks) + - [Agents](#agents) + - [Tools](#tools) + - [내장 LSP Tools](#내장-lsp-tools) + - [내장 AST-Grep Tools](#내장-ast-grep-tools) + - [Safe Grep](#safe-grep) + - [기타 편의 기능](#기타-편의-기능) + - [작성자의 노트](#작성자의-노트) + - [주의](#주의) + # Oh My OpenCode Oh My OpenCode oMoMoMoMoMo··· -당신이 테크분야 종사자라면, [클로드코드](https://github.com/anthropics/claude-code)를 좋아했을겁니다. -당신이 해커라면, [오픈코드](https://github.com/sst/opencode)를 사랑할겁니다. -그저 돈을 벌기 위해 코드를 작성하는 것이 아닌, -진심으로 코드를 작성하는 그런 사람들. +[Claude Code](https://www.claude.com/product/claude-code) 좋죠? +근데 당신이 해커라면, [OpenCode](https://github.com/sst/opencode) 와는 사랑에 빠지게 될겁니다. -[오픈코드](https://github.com/sst/opencode)는 아주 확장하능하고 아주 커스터마이저블합니다. 또한 멍청한 화면 깜빡임이 없습니다. 자동으로 LSP, 린터, 포매터가 활성화되며 커스텀 할 수 있습니다. 자신만의 모델을 사용 할 수 있으며, 모델을 섞어 오케스트레이션 할 수 있습니다. -기능이 아주 많습니다. 아름답고, 고성능입니다. +Windows 만 사용하다가 처음으로 Linux 를 접하고 신나서 잔뜩 세팅하던 경험이 있진 않나요? +OpenCode 가 낭만이 사라진것같은 오늘날의 시대에, 당신에게 그런 프로젝트가 될겁니다. +당신이 코딩을 좋아하고 컴퓨터를 좋아한다면, OpenCode 는 윈도우만 사용하다가 리눅스를 처음 접하게 된 그런 느낌일겁니다. +그렇지 않은 당신도 약간의 시간을 투자해서 당신의 실력과 생산성을 몇배로 부스트하세요. -그리고 따라오는 문제: 입문자에게 알아야 할 것이 너무 많고 어렵다. +## 세 줄 요약 -[AmpCode](https://ampcode.com), [Claude Code](https://github.com/anthropics/claude-code) 에게 강한 영향과 영감을 받고, 그들의 기능을 그대로, 혹은 더 낫게 이 곳에 구현합니다. 우리는 오픈소스라는 거인 위에 올라타있으니까요. +- **모델 설정이 필요합니다** + - 이 플러그인은 [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, Anthropic 의 모델을 사용합니다. + - Anthropic 모델들을 사용하기 위해 [OpenCode 의 내장 Claude Code Max Plan 로그인 기능](https://opencode.ai/docs/providers/#anthropic)을 사용하세요. (Anthropic 플랜은 유료입니다) + - OpenAI 모델들을 사용하기 위해 이 [OpenCode-OpenAI-Codex-Auth 플러그인](https://github.com/numman-ali/opencode-openai-codex-auth)을 추천합니다. (OpenAI 플랜은 유료입니다) + - Gemini, GPT 를 위해 [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) 또는 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)를 추천합니다. (Gemini 는 구독하지 않아도 사용 할 수 있습니다) +- **사실 밑의 내용은 읽지 않아도 됩니다. 그냥 설치하시면 됩니다. 모델 설정하고나면 추가로 공부하거나 알 필요가 없고, 설치하고 나면 그냥 더 좋아집니다.** +- **이 문서도 그냥 Claude Code, OpenCode, Cursor에 붙여넣고, 설치하고, 사용자의 개입이 필요할 때 알려달라고 프롬프팅하세요. 그럼 그냥 깔립니다.** + - 당신이 LLM Agent 라면, 필요한 플러그인과 의존성을 설치하고, tmux 를 통해 opencode auth login 을 실행하여 사용자의 구성을 도와주세요. -Better [AmpCode](https://ampcode.com), Better [Claude Code](https://github.com/anthropics/claude-code), 혹은 일종의 배포판(distribution) 이라고 생각해도 좋습니다. +## Why OpenCode & Why Oh My OpenCode -저는 LLM polytheism 을 추구하며, 여러분의 재정 상태를 위해 CliProxy 혹은 VibeProxy 를 추천합니다. 프론티어 랩들의 LLM 들의 장점만을 취하세요. +OpenCode 는 아주 확장가능하고 아주 커스터마이저블합니다. 화면이 깜빡이지 않습니다. +수정하는 파일에 맞게 자동으로 [LSP](https://opencode.ai/docs/lsp/), [Linter, Formatter](https://opencode.ai/docs/formatters/) 가 활성화되며 커스텀 할 수 있습니다. +수많은 모델을 사용 할 수 있으며, **용도에 따라 모델을 섞어 오케스트레이션 할 수 있습니다.** +기능이 아주 많습니다. 아름답습니다. 터미널이 화면을 그리려고 힘들어 하지 않습니다. 고성능입니다. -주의: 이 셋업은 Highly Opinionated 이며, 제가 사용하고 있는 셋업 중 범용적인것을 플러그인에 포함하기 때문에 계속 업데이트 됩니다. 저는 여태까지 $20,000 어치의 토큰을 오로지 개인 개발 목적으로 개인적으로 사용했고, 이 플러그인은 그 경험들의 하이라이트여러분은 그저 최고를 취하세요. 만약 더 나은 제안이 있다면 언제든 기여에 열려있습니다. +**그런데 문제는 너무나 알아야 할게 많고, 어렵고, 당신의 시간은 비싸다는겁니다.** + +[AmpCode](https://ampcode.com), [Claude Code](https://code.claude.com/docs/ko/overview) 에게 강한 영향과 영감을 받고, 그들의 기능을 그대로, 혹은 더 낫게 이 곳에 구현했습니다. +**Open**Code 이니까요. + +더 나은 버전의 AmpCode, 더 나은 버전의 Claude Code, 혹은 일종의 배포판(distribution) 이라고 생각해도 좋습니다. + +저는 상황에 맞는 적절한 모델이 있다고 믿습니다. 다양한 모델을 섞어 쓸 때 최고의 팀이 됩니다. +여러분의 재정 상태를 위해 CLIProxyAPI 혹은 VibeProxy 를 추천합니다. 프론티어 랩들의 LLM 들을 채용해서, 그들의 장점만을 활용하세요. 당신이 이제 팀장입니다. + +**Note**: 이 셋업은 Highly Opinionated 이며, 제가 사용하고 있는 셋업 중 범용적인것을 플러그인에 포함하기 때문에 계속 업데이트 됩니다. 저는 여태까지 $20,000 어치의 토큰을 오로지 개인 개발 목적으로 개인적으로 사용했고, 이 플러그인은 그 경험들의 하이라이트입니다. 여러분은 그저 최고를 취하세요. 만약 더 나은 제안이 있다면 언제든 기여에 열려있습니다. + +## 기능 + +### Hooks + +- **Todo Continuation Enforcer**: 에이전트가 멈추기 전 모든 TODO 항목을 완료하도록 강제합니다. LLM의 고질적인 "중도 포기" 문제를 방지합니다. +- **Context Window Monitor**: [컨텍스트 윈도우 불안 관리](https://agentic-patterns.com/patterns/context-window-anxiety-management/) 패턴을 구현합니다. + - 사용량이 70%를 넘으면 에이전트에게 아직 토큰이 충분하다고 상기시켜, 급하게 불완전한 작업을 하는 것을 완화합니다. +- **Session Notification**: 에이전트가 작업을 마치면 OS 네이티브 알림을 보냅니다 (macOS, Linux, Windows). + +### Agents + +- **oracle** (`openai/gpt-5.1`): 아키텍처, 코드 리뷰, 전략 수립을 위한 전문가 조언자. GPT-5.1의 뛰어난 논리적 추론과 깊은 분석 능력을 활용합니다. AmpCode 에서 영감을 받았습니다. +- **librarian** (`anthropic/claude-haiku-4-5`): 멀티 레포 분석, 문서 조회, 구현 예제 담당. Haiku의 빠른 속도, 적절한 지능, 훌륭한 도구 호출 능력, 저렴한 비용을 활용합니다. AmpCode 에서 영감을 받았습니다. +- **explore** (`opencode/grok-code`): 빠른 코드베이스 탐색, 파일 패턴 매칭. Claude Code는 Haiku를 쓰지만, 우리는 Grok을 씁니다. 현재 무료이고, 극도로 빠르며, 파일 탐색 작업에 충분한 지능을 갖췄기 때문입니다. Claude Code 에서 영감을 받았습니다. +- **frontend-ui-ux-engineer** (`google/gemini-3-pro-preview`): 개발자로 전향한 디자이너라는 설정을 갖고 있습니다. 멋진 UI를 만듭니다. 아름답고 창의적인 UI 코드를 생성하는 데 탁월한 Gemini를 사용합니다. +- **document-writer** (`google/gemini-3-pro-preview`): 기술 문서 전문가라는 설정을 갖고 있습니다. Gemini 는 문학가입니다. 글을 기가막히게 씁니다. + +### Tools + +#### 내장 LSP Tools + +[OpenCode 는 LSP 를 제공하지만](https://opencode.ai/docs/lsp/), 오로지 분석용으로만 제공합니다. 탐색과 리팩토링을 위한 도구는 OpenCode 와 동일한 스펙과 설정으로 Oh My OpenCode 가 제공합니다. + +- **lsp_hover**: 위치의 타입 정보, 문서, 시그니처 가져오기 +- **lsp_goto_definition**: 심볼 정의로 이동 +- **lsp_find_references**: 워크스페이스 전체에서 사용처 찾기 +- **lsp_document_symbols**: 파일의 심볼 개요 가져오기 +- **lsp_workspace_symbols**: 프로젝트 전체에서 이름으로 심볼 검색 +- **lsp_diagnostics**: 빌드 전 에러/경고 가져오기 +- **lsp_servers**: 사용 가능한 LSP 서버 목록 +- **lsp_prepare_rename**: 이름 변경 작업 검증 +- **lsp_rename**: 워크스페이스 전체에서 심볼 이름 변경 +- **lsp_code_actions**: 사용 가능한 빠른 수정/리팩토링 가져오기 +- **lsp_code_action_resolve**: 코드 액션 적용 + +#### 내장 AST-Grep Tools +- **ast_grep_search**: AST 인식 코드 패턴 검색 (25개 언어) +- **ast_grep_replace**: AST 인식 코드 교체 + +#### Safe Grep +- **safe_grep**: 안전 제한이 있는 콘텐츠 검색 (5분 타임아웃, 10MB 출력 제한). + - 기본 grep 도구는 시간제한이 걸려있지 않습니다. 대형 코드베이스에서 광범위한 패턴을 검색하면 CPU가 폭발하고 무한히 멈출 수 있습니다. + - safe_grep 은 timeout 과 더 엄격한 출력 제한을 적용합니다. + - **주의**: 기본 grep 도구는 Agent 를 햇갈리게 하지 않기 위해 비활성화됩니다. 그러나 SafeGrep 은 Grep 이 제공하는 모든 기능을 제공합니다. + +### 기타 편의 기능 +- **Terminal Title**: 세션 상태에 따라 터미널 타이틀을 자동 업데이트합니다 (유휴 ○, 처리중 ◐, 도구 ⚡, 에러 ✖). tmux를 지원합니다. + +## 작성자의 노트 + +Oh My OpenCode 를 설치하세요. 복잡하게 OpenCode 구성을 만들지마세요. +제가 밟아보고 경험한 문제들의 해답을 이 플러그인에 담았고, 그저 깔고 사용하면 됩니다. OpenCode 가 ArchLinux 라면, Oh My OpenCode 는 [Omarchy](https://omarchy.org/) 입니다. + +다른 에이전트 하니스 제공자들이 이야기하는 다중 모델, 안정성, 풍부한 기능을 그저 OpenCode 에서 누리세요. +제가 테스트하고, 이 곳에 업데이트 하겠습니다. 저는 이 프로젝트의 가장 열렬한 사용자이기도 하니까요. +- 어떤 모델이 순수 논리력이 제일 좋은지 +- 어떤 모델이 디버깅을 잘하는지, +- 어떤 모델이 글을 잘 쓰고 +- 누가 프론트엔드를 잘 하는지 +- 누가 백엔드를 잘 하는지 +- 주로 겪는 상황에 맞는 빠른 모델은 무엇인지 +- 다른 에이전트 하니스에 제공되는 새로운 기능은 무엇인지. + +고민하지마세요. 제가 고민할거고, 다른 사람들의 경험을 차용해 올것이고, 그래서 이 곳에 업데이트 하겠습니다. +이 글이 오만하다고 느껴지고, 더 나은 해답이 있다면, 편히 기여해주세요. 환영합니다. + +지금 시점에 여기에 언급된 어떤 프로젝트와 모델하고도 관련이 있지 않습니다. 온전히 개인적인 실험과 선호를 바탕으로 이 플러그인을 만들었습니다. +OpenCode 를 사용하여 이 프로젝트의 99% 를 작성했습니다. 기능 위주로 테스트했고, 저는 TS 를 제대로 작성 할 줄 모릅니다. **그치만 이 문서는 제가 직접 검토하고 전반적으로 다시 작성했으니 안심하고 읽으셔도 됩니다.** + +## 주의 + +- [1.0.132](https://github.com/sst/opencode/releases/tag/v1.0.132) 혹은 이것보다 낮은 버전을 사용중이라면, OpenCode 의 버그로 인해 제대로 구성이 되지 않을 수 있습니다. + - [이를 고치는 PR 이 1.0.132 배포 이후에 병합되었으므로](https://github.com/sst/opencode/pull/5040) 이 변경사항이 포함된 최신 버전을 사용해주세요. --- -현재 NPM 계정에 접근할 수 없습니다. 계정이 복구되는 대로 이 내용을 업데이트하겠습니다. \ No newline at end of file +현재 NPM 계정에 접근할 수 없습니다. 계정이 복구되는 대로 이 내용을 업데이트하겠습니다.