Oh My Imagicma

A minimal OpenCode plugin with Ralph Loop - self-referential development loop until task completion.

Features

- ibuild primary agent - 自动注入一个开箱即用的工程执行 Agent（不覆盖你已有的同名 agent）
- Built-in docs-first subagents - 自动注入 idesigner、igen-prd、igen-persona、igen-feature-modules、igen-style-guide、igen-db-schema
- /ralph-loop - Start a self-referential development loop that continues until task completion
- /ulw-loop - Start an ultrawork loop that continues until task completion
- /cancel-ralph - Cancel the currently active Ralph Loop
- search_codebase(query, search_glob_patterns) - Use a sub-session to analyze repo snapshots with long context
- packager_tool(action, scope, language, packages) - Install/uninstall Node.js packages (pnpm preferred, npm fallback with lockfile rule)
- create_postgresql_database_tool() - Detect DB env readiness and return setup guidance
- check_database_status() - Verify DB connectivity via psql (or TCP fallback)
- execute_sql_tool(sql_query, environment) - Execute SQL with production read-only guard
- view_env_vars(type, environment, keys) - View env values or secret existence from .env*
- set_env_vars(input) - Set/delete env keys in .env*
- restart_workflow(name, workflow_timeout) - Restart a process defined in process-compose.yaml
- refresh_all_logs() - Snapshot plugin/process-compose logs to /tmp/logs//
- get_latest_lsp_diagnostics(file_path) - Get latest LSP diagnostics (single file or cached latest)
- architect(task, relevant_files, include_git_diff, responsibility, relevant_git_commits, relevant_integrations) - Architecture/debug/plan analysis in isolated sub-session
- run_test(test_plan, relevant_technical_documentation, default_screen_width, default_screen_height) - Structured test execution orchestration in isolated sub-session
- search_docs(query) - Local project docs search (README, docs//, /*.md|mdx)

Installation

``bash


Install the plugin

bun add oh-my-imagicma

or

npm install oh-my-imagicma
`

Add to your OpenCode config (~/.config/opencode/opencode.json):

`json
{
"plugin": ["oh-my-imagicma"]
}
`

> 提示：本插件会在启动时通过 OpenCode 的 config.command 自动注册
> /ralph-loop、/ulw-loop、/cancel-ralph 三个命令（如果你在 opencode.json 里已定义同名命令，将不会被覆盖）。
>
> 同时会自动注入 agent.ibuild 以及 docs-first 相关内置 agents（idesigner + igen-*）。
> 若 default_agent 当前未设置，会自动设为 ibuild。
> ibuild 系统提示词维护入口：src/agents/ibuild.md（front matter + prompt，构建时内联到插件产物）。

Usage

$3

Start a loop that continues until the task is complete:

`
/ralph-loop "Build a REST API with authentication"
/ralph-loop "Refactor the payment module" --max-iterations=50
/ralph-loop "Fix all TypeScript errors" --completion-promise=ALL_FIXED
`

How it works:
1. The agent works on the provided task
2. When the session goes idle, the system checks if the completion promise was output
3. If not complete, the agent is prompted to continue
4. This repeats until:
- The completion promise is detected: DONE
- Maximum iterations reached (default: 100)
- User cancels with /cancel-ralph

$3

Start an ultrawork loop that runs at maximum intensity until completion:

`
/ulw-loop "Build a REST API with authentication"
/ulw-loop "Refactor the payment module" --max-iterations=50
/ulw-loop "Fix all TypeScript errors" --completion-promise=ALL_FIXED
`

$3

`
/cancel-ralph
`

$3

`txt
search_codebase(
query="Where is session idle handling implemented?",
search_glob_patterns=["src/*/.ts", "README.md"]
)
`

$3

`txt
packager_tool(
action="install",
scope="language",
language="nodejs",
packages=["express", "lodash"]
)
`

包管理器决策顺序：
1. 目标目录存在 package-lock.json 时优先 npm
2. 否则优先 pnpm
3. pnpm 不可用时回退 npm

成功后会执行“硬中断重启工作流”：先返回结果，再异步中断当前会话并注入强约束继续提示。

$3

`txt
create_postgresql_database_tool()
check_database_status()
execute_sql_tool(sql_query="select now();", environment="development")
`

说明：
1. create_postgresql_database_tool 仅做检测与引导，不会自动创建云数据库。
2. execute_sql_tool 在 production 环境只允许只读 SQL（SELECT/WITH/EXPLAIN）。

$3

`txt
view_env_vars(type="all", environment="shared")
set_env_vars(input={operation:"set", environment:"development", values:{API_BASE_URL:"https://example.com"}})
`

$3

`txt
restart_workflow(name="web", workflow_timeout=30)
refresh_all_logs()
`

工作流配置文件默认读取（按顺序查找）：
1. process-compose.yaml
2. process-compose.yml
3. .opencode/process-compose.yaml
4. .opencode/process-compose.yml

示例配置：

`yaml
version: "0.5"
log_location: ".opencode/logs/process-compose.log"
processes:
web:
command: "pnpm dev"
working_dir: "."
environment:
PORT: "5001"
`

依赖说明：
1. restart_workflow / refresh_all_logs 需要系统安装 process-compose
2. 缺失时工具会返回 missing_dependency，不会自动安装

$3

`txt
get_latest_lsp_diagnostics(file_path="src/index.ts")
get_latest_lsp_diagnostics()
`

$3

`txt
architect(task="Review this refactor", relevant_files=["src/index.ts"], include_git_diff=true, responsibility="evaluate_task")
run_test(test_plan="[Browser] ...", relevant_technical_documentation="...", default_screen_width=1280, default_screen_height=720)
search_docs(query="workflow logs")
`

Notes

- 以下能力已直接复用 OpenCode 内置工具，不在插件中重复实现：task（start_subagent）、question（user_query/request_env_var）、websearch（do_web_search）、webfetch（web_fetch）。

Configuration

Create a config file at .opencode/oh-my-imagicma.json (project) or ~/.config/opencode/oh-my-imagicma.json (user):

`json
{
"agents": {
"ibuild": {
"enabled": true,
"set_as_default": true
}
},
"ralph_loop": {
"enabled": true,
"default_max_iterations": 100,
"state_dir": ".imagicma/ralph-loop.local.md"
},
"disabled_hooks": []
}
`

$3

1. Create src/agents/.md (front matter + system prompt).
2. Import and register it in src/agents.ts by adding it to BUILTIN_AGENT_MARKDOWN_SOURCES.
3. Configure it in .opencode/oh-my-imagicma.json under agents..

Troubleshooting

$3

1. 确认已把 "oh-my-imagicma" 加到 ~/.config/opencode/opencode.json 的 plugin 数组里，并重启 OpenCode
2. 检查 .opencode/oh-my-imagicma.json 或 ~/.config/opencode/oh-my-imagicma.json：
- ralph_loop.enabled 不能是 false
- disabled_hooks 里不要包含 "ralph-loop"

$3

- SEARCH_CODEBASE_MAX_FILES（默认 120）
- SEARCH_CODEBASE_MAX_FILE_BYTES（默认 50000）
- SEARCH_CODEBASE_MAX_TOTAL_BYTES（默认 600000）
- PACKAGER_NPM_TIMEOUT_MS（默认 300000）
- DATABASE_CHECK_TIMEOUT_MS（默认 10000）
- DATABASE_SQL_TIMEOUT_MS（默认 30000）
- PROCESS_COMPOSE_BOOT_TIMEOUT_MS（默认 20000）
- PROCESS_COMPOSE_COMMAND_TIMEOUT_MS（默认 30000）
- PROCESS_COMPOSE_LOG_TAIL_LINES（默认 200）
- ARCHITECT_TIMEOUT_MS（默认 120000）
- RUN_TEST_TIMEOUT_MS（默认 180000）
- SEARCH_DOCS_MAX_RESULTS（默认 20）

Development

`bash


Install dependencies

bun install

Type check

bun run typecheck

Build

bun run build

Run tests

bun test
`

Publishing

1. 登录 npm（若未登录）：
`bash
npm login
`
按提示输入 npm 用户名、密码和邮箱（或使用 2FA）。

2. 确认版本：在 package.json 里改好 version，或使用：
`bash
npm version patch # 0.1.0 -> 0.1.1
npm version minor # 0.1.0 -> 0.2.0
npm version major # 0.1.0 -> 1.0.0
`

3. 发布：
`bash
npm publish
`
发布前会自动执行 prepublishOnly（clean + build），因此会先构建再上传。

首次发布前请确认 npmjs.com 上还没有同名包 oh-my-imagicma，否则需要换包名或使用 scope（如 @your-username/oh-my-imagicma`）。

License

MIT