When to open: You want to see how newtype uses OpenCode together with a self-built npm CLI tool. Oh My OpenCode customization guide (1729 lines, the most complete documentation-level guide) + newtype CLI (a production-grade 8-Agent multi-agent content production CLI).
Compared with Claude Code Best Practices (Cal Rueb · Anthropic Internal Talk) the difference: That guide is from the perspective of Anthropic Claude Code. This wiki covers newtype's OpenCode + self-built CLI dual tool stack.
I. Part 1: Oh My OpenCode Customization Guide
1.1 Project Background
- Oh My OpenCode: The powerful plugin for OpenCode
- Official repository:https://github.com/code-yeongyu/oh-my-opencode
- License: SUL-1.0 (Sustainable Use License) — modification and redistribution are permitted (non-commercial)
- Features: multi-model orchestration, parallel background agents, LSP/AST tools
1.2 10 Built-in Agents
| English name | Suggested Chinese localization | Role |
|---|---|---|
| Sisyphus | Xixifusi | Main Agent / default orchestrator |
| oracle | Shenyuzhe | Architecture advisor |
| librarian | Tushu Guanliyuan | Documentation / knowledge retrieval |
| explore | Tansuozhe | Code exploration |
| frontend-ui-ux-engineer | Qianduan Gongchengshi | UI / UX implementation |
| document-writer | Wenzhu Zhuanxieyuan | Documentation generation |
| multimodal-looker | Duomotai Guanchazhe | Image / multimodal |
| Metis (Plan Consultant) | Motisi (Planning Advisor) | Planning advisor |
| Momus (Plan Reviewer) | Momosi (Plan Reviewer) | Plan review |
| orchestrator-sisyphus | Bianpai Xixifusi | Multi-agent orchestration |
1.3 Comparison of 2 Customization Methods
| Method | Applicable scenarios | Programming required | Can rename | Installation method |
|---|---|---|---|---|
| Configuration file | Modify parameters / add Agents | ❌ | ❌ | Edit JSON |
| Fork + GitHub | Full customization, Chinese localization | ✅ | ✅ | 用户名/仓库#标签 |
| Fork + npm | Public sharing | ✅ | ✅ | npm publish |
1.4 Method 1: Configuration file (recommended for beginners)
Locations (priority from low to high):
~/.config/opencode/oh-my-opencode.json(user-level).opencode/oh-my-opencode.json(project-level)
Core fields:
model/temperature/top_pprompt/prompt_append(replace vs append)tools/disable/descriptionmode:subagent/primary/allpermission:edit/bash/webfetch/doom_loop/external_directory
Example — permission control:
{
"agents": {
"explore": {
"permission": {
"edit": "deny",
"bash": "ask",
"webfetch": "allow",
"doom_loop": "deny"
}
},
"oracle": {
"permission": {
"bash": {
"git": "allow",
"rm": "deny",
"npm": "ask"
}
}
}
}
}
1.5 Method 2: Fork repository + full Chinese localization (advanced)
Key — modify 3 files
| File | Modification target | Location |
|---|---|---|
src/agents/types.ts |
BuiltinAgentName type |
Lines 59–70 |
src/config/schema.ts |
BuiltinAgentNameSchema + OverridableAgentNameSchema + AgentOverridesSchema |
Lines 19–30, 38–53, 118–133 |
src/agents/utils.ts |
Agent name references in utility functions | (per file) |
Automated Chinese localization script (perl replacement)
#!/bin/bash
set -e
mkdir -p .backups
cp src/agents/types.ts .backups/
cp src/config/schema.ts .backups/
cp src/agents/utils.ts .backups/
perl -i -pe 's/"Sisyphus"/"西西弗斯"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"oracle"/"神谕者"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"librarian"/"图书管理员"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"explore"/"探索者"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"frontend-ui-ux-engineer"/"前端工程师"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"document-writer"/"文档撰写员"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"multimodal-looker"/"多模态观察者"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"Metis \(Plan Consultant\)"/"墨提斯 (计划顾问)"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"Momus \(Plan Reviewer\)"/"摩摩斯 (计划审查员)"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
perl -i -pe 's/"Prometheus \(Planner\)"/"普罗米修斯 (规划者)"/g' src/config/schema.ts
perl -i -pe 's/"orchestrator-sisyphus"/"编排西西弗斯"/g' src/agents/types.ts src/config/schema.ts src/agents/utils.ts
echo "✅ 中文化完成"
8-step hands-on workflow
- Fork + Clone +
bun install - Run the automation script Chinese localization
- Build + verify:
bun run build+bun run typecheck+bun test - MODIFICATIONS.md Modification notice (required by SUL-1.0)
- Git commit + push to fork
- GitHub Release Create tag:
v3.0.0-zh.1(gh release create v3.0.0-zh.1 --title "...") - Configure OpenCode Use GitHub version:
"plugin": ["你的用户名/oh-my-opencode#v3.0.0-zh.1"] - Test:
Ask @神谕者 to explain this function
1.6 GitHub version vs local build vs npm
| Method | Configuration | Applicable to |
|---|---|---|
| GitHub version(recommended) | 用户名/仓库名#标签 |
Personal use / sharing with friends |
| Local build | file:///path/to/dist/index.js |
Development / frequent modifications |
| npm | @scope/包名 |
Public sharing / widespread use |
1.7 Key Q&A
| Q | A |
|---|---|
| How to force update the GitHub version | rm -rf ~/.cache/opencode/node_modules/ then restart |
| How to use a private repository | (1) HTTPS + credential helper (2) Local clone + file:/// path |
| SUL-1.0 restrictions | Personal use / internal business,commercial use is not allowed,Modifications must be declared |
1.8 Recommended workflow
开发时:
Fork → Clone → 修改 → 本地构建测试
配置: "file:///path/to/dist/index.js"
个人使用:
推送 GitHub → 创建 Release → 使用 GitHub 引用
配置: "用户名/仓库名#v3.0.0-zh.1"
公开分享:
发布 npm → 让其他人 npm 安装
配置: "@scope/包名"
II. Part 2: newtype CLI Multi-Agent Content Team
2.1 Project Positioning
Binary:
nt| Package:npm i -g @newtype-os/cli8 professional AI agents (researcher / writer / editor / fact-checker / extractor / analyst / archivist / chief) as non-interactive CLI commands. Designed specifically for programmatic invocation by other AI agents.
Core positioning:A CLI for AIs(invoked by other AI agents, not for human interaction)
2.2 8 Core Agents
| Agent | Purpose |
|---|---|
| researcher | Deep research (default + fact-checker) |
| writer | Content generation |
| editor | 4-layer refinement (structure → paragraph → sentence → word) |
| fact-checker | Fact-checking / claim verification |
| extractor | Extract structured content from documents/images/web pages |
| analyst | Framework analysis (12 frameworks) |
| archivist | Knowledge base CRUD (semantic search) |
| chief | Orchestrator (coordinates all agents) |
2.3 8 Core Commands
nt research [topic..] # 主题研究(+ fact-check 默认)
nt write [topic..] # 内容生成
nt edit [file] # 4 层精修
nt fact-check [topic..] # 事实核验
nt analyze [topic..] # 框架分析(12 framework)
nt extract [topic..] # 内容提取
nt archive <action> # 知识库(store/search/list/delete)
nt pipeline [topic..] # 全流程编排
2.4 Output modes (4 Flags)
| Flag | Behavior | Used for |
|---|---|---|
| (none) | Plain text stdout | Human reading, simple piping |
--json |
JSON envelope stdout | Programmatic parsing by Agents |
--stream |
NDJSON event stream | Real-time progress monitoring |
-o <file> |
Write to file | Saving output, pipelines |
2.5 JSON Envelope Schema (key — for AI use)
Success response:
{
"success": true,
"result": "... text output ...",
"metadata": {
"agent": "researcher",
"sessionID": "...",
"duration_ms": 45000,
"tools": [{ "name": "web_search", "title": "..." }]
}
}
Error response:
{
"success": false,
"error": { "code": 2, "message": "..." },
"metadata": { "agent": "researcher", "sessionID": "...", "duration_ms": 12000, "tools": [] }
}
2.6 Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Input / argument error |
| 2 | Model call failed |
| 3 | Timeout |
| 4 | Config / auth error |
2.7 Input methods (priority from high to low)
1. 位置参数: nt research AI Agent architectures
2. --input <file>: nt write --input notes.md
3. --topic <text>: nt analyze --topic "Tesla EV"
4. stdin 管道: cat notes.md | nt write
2.8 Global flags (key)
| Flag | Short | Purpose |
|---|---|---|
--output <path> |
-o |
Output file |
--json |
JSON envelope | |
--stream |
NDJSON event stream | |
--verbose |
Show tool execution | |
--quiet |
-q |
Silent (show results only) |
--model <p/m> |
-m |
Override model(provider/model) |
--lang <code> |
Output language:zh / en / ja |
|
--timeout <sec> |
-t |
Timeout (default 300s, pipeline 600s) |
2.9 Key commands explained
nt research — topic research
# 基础
nt research "AI Agent architectures 2026" -o research.md
# 深度研究 + focus
nt research "MCP vs CLI" --depth deep --focus "developer experience,adoption" -o deep.md
# JSON 输出
nt research "Kubernetes security" --json
# 跳过 fact-check 加速
nt research "quick overview of RAG" --no-fact-check -o quick.md
| Flag | Default | Description |
|---|---|---|
--depth <level> |
normal |
shallow / normal / deep |
--sources <n> |
5 |
Expected number of sources |
--focus <keywords> |
Keywords, comma-separated | |
--no-fact-check |
Skip fact-check |
nt write — content generation
# 从研究材料生成 newsletter
nt write --input research.md --style newsletter -o draft.md
# 从主题写 essay
nt write "Why CLI is the native language of AI Agents" --style essay --words 2000 -o article.md
| Flag | Option |
|---|---|
--style <s> |
newsletter / essay / report / tweet-thread / technical / story |
--method <m> |
WRITE / AIDA / PAS / STORYTELLING / ANALYTICAL / CONVERSATIONAL |
--words <n> |
Default 1500 |
--tone <t> |
professional / casual / academic / provocative |
--audience <desc> |
Target audience description |
nt edit — 4-layer refinement
# 全 4 层
nt edit --input draft.md -o final.md
# 只调结构
nt edit --input draft.md --layer structure -o restructured.md
# 保留 voice,只改语法
nt edit --input draft.md --preserve-voice -o polished.md
# 带 diff
nt edit --input draft.md --diff -o final.md
| Flag | Default | Description |
|---|---|---|
--layer <l> |
all |
structure / paragraph / sentence / word / all |
--preserve-voice |
Preserve original voice, only fix grammar / logic | |
--diff |
Output diff |
nt analyze — 12-framework analysis
nt analyze --input research.md --framework swot -o analysis.md
nt analyze "Why are all tools moving to CLI" --framework first-principles
nt analyze --input data.md --framework "swot,pestel" -o combo.md
12 frameworks:swot, pestel, porter, first-principles, 5why, jobs-to-be-done, blue-ocean, value-chain, bcg-matrix, ansoff, okr, systems-thinking
nt pipeline — full-process orchestration
# 默认流程 (research → analyze → write → fact-check → edit)
nt pipeline "AI Agent trends 2026" --style newsletter --output-dir ./output/
# 自定义步骤
nt pipeline "MCP future" --steps "research,write,edit" -o result.md
# 从已有材料(跳过 research)
nt pipeline --input notes.md --steps "analyze,write,edit" -o final.md
2.10 Pipeline Composition (chained)
# Research → Write → Edit
nt research "AI Agents" -o /tmp/r.md \
&& nt write --input /tmp/r.md --style newsletter -o /tmp/d.md \
&& nt edit --input /tmp/d.md -o final.md
# Extract → Fact-check → Archive
nt extract --input paper.pdf -o /tmp/e.md \
&& nt fact-check --input /tmp/e.md -o /tmp/fc.md \
&& nt archive store --input /tmp/fc.md --tags "paper,verified"
2.11 Example for AI Agent invocation
# 获取结构化输出
result=$(nt research "Kubernetes best practices" --json)
echo "$result" | jq -r '.result' # 取文本
echo "$result" | jq '.success' # 检查成功
echo "$result" | jq '.metadata' # 取元数据
# 检查 exit code
nt research "topic" --json -o out.json
if [ $? -eq 0 ]; then
echo "Success"
elif [ $? -eq 2 ]; then
echo "Model call failed, retry"
elif [ $? -eq 3 ]; then
echo "Timeout, increase with --timeout"
fi
III. Part 3: The Overall Philosophy of the Two Tools
3.1 Why build a self-built CLI instead of a Skill
| Dimension | Claude Code Skill | newtype CLI |
|---|---|---|
| Caller | Inside LLM | Any external AI / script |
| Installation | drop .skill file |
npm i -g |
| Cross-tool reuse | Locked to Claude Code | Any CLI environment(VSCode / Cursor / shell / other AIs) |
| Output | LLM text | JSON envelope / NDJSON / file(programmably consumable) |
| Value | Single-task methodology | Orchestrate other AIs as building blocks |
Key insight:newtype wraps the 8 Agents as a CLI because he needs to call them within the AI Coding workflow(Claude Code calls nt research → gets JSON → processes further). A Skill is for Claude to use; a CLI is for Claude to call Claude (nesting itself).
3.2 Synergy between the two tools
Oh My OpenCode (10 agents) ──→ 主要做编程任务
↓
Claude Code / OpenCode 调用 nt
↓
newtype CLI (8 agents) ──→ 主要做内容任务
↓
JSON / Markdown 文件
↓
回写到代码 / 文档
3.3 Full map of the Newtype tool ecosystem
| Layer | Tool | Role |
|---|---|---|
| CLI / IDE | OpenCode + Oh My OpenCode plugin | Main programming battlefield |
| CLI / IDE | Claude Code | Main programming battlefield |
| CLI tool | nt(newtype CLI) |
Content production tool |
| Skill | Super Analyst Pro / Super Writer | Anthropic Skill format |
| MCP | Prompt House local / Sequential Thinking / Tavily | Tool layer |
| Client | ChatWise / Cherry Studio | Fallback conversation |
IV. Implications for independent developers
4.1 Should you fork Oh My OpenCode?
| Your situation | Recommended method |
|---|---|
| Only want to adjust parameters / add prompts | Method 1 (configuration file), do not fork |
| Want full Chinese localization / personalization | Method 2 (Fork + GitHub), SUL-1.0 allows this |
| Want to share publicly | Method 2 + npm publish, remember to comply with SUL-1.0 |
Key constraint:SUL-1.0 prohibits commercial use.
4.2 Should you build a newtype-style CLI?
5 reasons to do it:
- Called by other AIs — JSON output is programmably consumable
- Cross-IDE reuse — runs on VSCode + Cursor + Claude Code
- Chained orchestration —
nt research && nt write && nt edit - timeout / error / retry handled by the shell(mature toolchain)
- Can publish to npm for distribution
3 reasons not to do it:
- Users only use it in Claude Code — Skill is more convenient
- No habit of npm publish / willingness to maintain
- 8 Agents is too many — start with 1–2 to validate
4.3 newtype's design philosophy (extracted from the two tools)
- Clear stages: commands correspond to stages (research → write → edit → fact-check)
- JSON-first: output is programmably consumable (for AI invocation, not for human reading)
- Standardized exit codes: 0/1/2/3 each represent different failures, retryable
- Chain-composable: each command is a building block, can be piped / chained
- Multiple input methods(positional argument / --input / --topic / stdin) — adapts to multiple invocation scenarios
- timeout defaults to 300s, pipeline defaults to 600s — empirically reasonable values
V. Links to other wikis
- Claude Code Best Practices (Cal Rueb · Anthropic Internal Talk) — Anthropic Claude Code perspective (this wiki is from the OpenCode + self-built CLI perspective)
- newtype · AI Coding Practice and Tool Stack Evolution — the evolution history of newtype's AI Coding tool stack
- newtype Skill System in Practice (Super Analyst v1/v2 + Super Writer) — Anthropic Skill format (the CLI in this wiki is a different paradigm)
- newtype · Vibe Coding Independent Product Practice — newtype's history of building self-owned products (newtype CLI is one of them)
- newtype Knowledge System and Full Evolution of Life OS — Oh My OpenCode is a core component of its AI Coding system
History
- 2026-05-17:Phase 5.1 ingest: Merge content from file_037 (1729 lines, complete Oh My OpenCode guide) and file_032 (358 lines, newtype CLI product documentation) to write one wiki page. Fully cover the 2 methods for customizing OpenCode, the 8-step hands-on Chinese localization process, and newtype CLI's 8 agents / 8 commands / JSON envelope / pipeline composition.