Best Practices

Best Practices

Patterns and strategies for getting the most out of Oh My OpenAgent.

Usage Patterns

Single Task Mode

Describe your task directly. Sisyphus handles delegation automatically:

refactor the auth module to use JWT instead of sessions

Best for: Focused, well-defined tasks.

ultrawork Mode

One word activates everything:

ultrawork: migrate the entire project from JavaScript to TypeScript

or:

ulw: fix all ESLint warnings and add missing types

Best for: Large tasks, multi-step work, anything that needs parallel execution.

When to use ultrawork:

• Large refactoring tasks
• Full-stack feature development
• Complex problem analysis
• Multi-step implementation

When NOT to use ultrawork:

• Simple queries
• Small-scope single-file changes
• Quick questions

Interview Mode (Prometheus)

For complex tasks that need planning first:

/start-work

Prometheus enters interview mode — asks clarifying questions, identifies scope, builds a verified plan. Then Sisyphus executes it.

Best for: Ambiguous requirements, high-stakes changes, tasks where planning saves more time than it costs.

Multi-Model Strategy

Oh My OpenAgent routes work to the best model automatically. But understanding the strengths helps you write better prompts:

Model	Best At	Category
Claude Opus 4.6	Orchestration, planning, nuanced reasoning	Sisyphus, Prometheus
GPT-5.4	Deep autonomous reasoning, complex debugging	Hephaestus, ultrabrain
Kimi K2.5	Fast orchestration, cost-effective planning	Sisyphus (alternative)
GLM-5	Chinese-language tasks, general orchestration	Sisyphus (alternative)

The framework handles routing. Your job is to describe what you want, not how to do it.

Context Management

AGENTS.md Hierarchy

Create hierarchical context files for better agent understanding:

project/
├── AGENTS.md              ← Project-wide standards
├── src/
│   ├── AGENTS.md          ← Source code conventions
│   └── components/
│       └── AGENTS.md      ← Component-specific rules

Use /init-deep to auto-generate these files.

Conditional Rules

Rules auto-activate based on context:

## when: file.ext == "*.test.ts"
Use Jest and React Testing Library
Follow AAA pattern (Arrange, Act, Assert)

## when: agent == "oracle"
Provide detailed technical decision rationale
Consider long-term maintainability

Troubleshooting

Plugin Not Loading

Symptom: Agent doesn’t use Oh My OpenAgent features.

Fix:

1. Check opencode.json has "oh-my-openagent" (or legacy "oh-my-opencode") in the plugin array
2. Run bunx oh-my-opencode doctor
3. Verify the plugin entry spelling

Model Unavailable

Symptom: Tasks fail with model errors.

Fix:

1. Check your API key is configured for the provider
2. Configure fallback_models so tasks route to alternatives when a provider is down
3. Run bunx oh-my-opencode doctor to verify model access

Context Too Long

Symptom: Agent hits context window limits.

Fix:

1. Enable aggressive truncation: "experimental": { "aggressive_truncation": true }
2. Enable auto-resume: "experimental": { "auto_resume": true }
3. Use /init-deep to create focused AGENTS.md files instead of large monolithic ones

Background Tasks Timing Out

Symptom: Parallel agents fail before completing.

Fix:

1. Reduce concurrency: "background_tasks": { "max_concurrent": 2 }
2. Check API rate limits for your subscription tier
3. Add per-provider limits if needed

Real-World Case Studies

Mass ESLint Fix

“Knocked out 8000 eslint warnings with Oh My Opencode, just in a day” — Jacob Ferrari

Pattern: ulw: fix all ESLint warnings

• Sisyphus decomposes by file group
• Multiple agents fix in parallel
• Ralph Loop ensures nothing is missed

Full-Stack Application Conversion

“I converted a 45k line tauri app into a SaaS web app overnight using Ohmyopencode and ralph loop. Started with interview me prompt… It was amazing to watch it work and to wake up this morning to a mostly working website!” — James Hargis

Pattern: /start-work (Prometheus interview) → ultrawork (execution)

• Prometheus plans the migration strategy
• Sisyphus coordinates frontend and backend agents in parallel
• Hephaestus handles the deep conversion work autonomously
• Ralph Loop keeps everything running overnight

Complex Bug Debugging

Pattern: @explore + @oracle collaboration

1. @explore traces the execution path and identifies suspicious code
2. @oracle analyzes potential root causes and proposes hypotheses
3. Agent implements fix with verification
4. LSP tools ensure the fix doesn’t break references

Best for: Production issues, intermittent bugs, race conditions.

Documentation Generation

Pattern: @librarian + context injection

1. Run /init-deep to give agents project context
2. Use ultrawork: write complete API documentation
3. Librarian researches the codebase
4. Agents generate docs with LSP-verified type information

Quick Reference

Task Type	Recommended Command	Agents Involved
Large refactoring	ulw: [task description]	Sisyphus + Hephaestus + Experts
Architecture decision	/start-work	Prometheus → Sisyphus
Bug fix	@explore [bug description]	Explore → Oracle
Documentation	ulw: write docs for [feature]	Librarian + Experts
Quick change	[simple description]	Sisyphus (quick category)

Next Steps

• Configuration — Fine-tune agent behavior
• Agent System — Understand agent collaboration
• Tools — Explore the tool suite