// Guide for debugging OhMyCode issues. Use when user reports errors, unexpected behavior, or connection problems.
Run OhMyCode benchmarks — score any provider/model with token tracking. Use when user wants to benchmark, evaluate, test performance, or compare models.
Generate high-quality tests for OhMyCode modules. Use when user wants to create, add, or generate tests for a module or file.
Run tests and analyze results for OhMyCode. Use when user wants to run, check, or verify tests — or after any code change.
Guide for adding a new feature to OhMyCode. Use when user wants to add functionality that goes beyond existing extension points (tools/providers). Always start by reading docs/DEVELOPMENT_GUIDE.md.
Guide for adding a new LLM provider to OhMyCode. Use when user wants to connect a new AI model backend.
Guide for adding a new tool to OhMyCode. Use when user wants to create a custom tool.
| name | debug-ohmycode |
| description | Guide for debugging OhMyCode issues. Use when user reports errors, unexpected behavior, or connection problems. |
Systematic approach to diagnosing and fixing OhMyCode issues.
Error? → Which category?
├── "command not found" → Installation Issue
├── API/connection error → Provider Issue
├── Tool execution error → Tool Issue
├── "context compression failed" → Context Issue
├── Memory/resume not working → Storage Issue
└── Unexpected AI behavior → Prompt Issue
Symptoms: ohmycode: command not found, ModuleNotFoundError
Steps:
pip3 show ohmycodewhich ohmycode && ohmycode --helpcd <project_dir> && ./scripts/setup-cli.shpython3 --version (needs 3.9+)Symptoms: APIError, AuthenticationError, timeout, empty responses
Steps:
from openai import OpenAI
client = OpenAI(api_key="...", base_url="...")
r = client.chat.completions.create(
model="...", messages=[{"role": "user", "content": "hi"}], max_tokens=10
)
print(r.choices[0].message.content)
Check config: cat ~/.ohmycode/config.json
api_key set?base_url correct (trailing /v1)?model name correct for this provider?Check provider registration:
from ohmycode.providers.base import PROVIDER_REGISTRY, auto_import_providers
auto_import_providers()
print(list(PROVIDER_REGISTRY.keys()))
Check for rate limiting: look for 429 errors in output. OpenAI provider retries 3 times with [1, 2, 5]s delays.
Azure-specific: verify azure_endpoint and azure_api_version in config.
Symptoms: Tool returns error, wrong output, tool not found
Steps:
from ohmycode.tools.base import TOOL_REGISTRY, auto_import_tools
auto_import_tools()
print(list(TOOL_REGISTRY.keys()))
import asyncio
from ohmycode.tools.base import ToolContext
from ohmycode.tools.<name> import <ToolClass>
ctx = ToolContext(mode="auto", agent_depth=0, cwd=".", is_sub_agent=False)
tool = <ToolClass>()
result = asyncio.run(tool.execute({"param": "value"}, ctx))
print(result.output, result.is_error)
Check permissions: if mode=default, dangerous tools need confirmation. Try --mode auto.
Check concurrent_safe flag: if a tool has side effects but is marked concurrent_safe=True, it may have race conditions when called in parallel.
Symptoms: "Circuit breaker open", conversations getting cut off, AI forgetting context
Steps:
token_budget and output_tokens_reservedohmycode/core/context.py → maybe_compress()
Quick fix: Increase token_budget in config, or start a new conversation.
Symptoms: --resume not working, memories not saving, conversations lost
Steps:
ls -la ~/.ohmycode/conversations/
ls -la ~/.ohmycode/memory/
Check conversation files: cat ~/.ohmycode/conversations/<latest>.json | python3 -m json.tool | head
Memory index: cat ~/.ohmycode/memory/MEMORY.md
Resume matching: --resume with no argument loads the most recent file by modification time. With an argument, it matches filename substring.
Symptoms: AI ignores instructions, wrong persona, missing tools in responses
Steps:
from ohmycode.core.system_prompt import build_system_prompt, find_project_instructions
from ohmycode.tools.base import auto_import_tools
auto_import_tools()
prompt = build_system_prompt(mode="auto", cwd=".")
print(prompt)
OHMYCODE.md / CLAUDE.md is being found:from ohmycode.core.system_prompt import find_project_instructions
print(find_project_instructions("."))
Check memory content: cat ~/.ohmycode/memory/MEMORY.md
Check system_prompt_append in config
--mode auto to skip permission prompts during debuggingohmycode onlypython3 -m pytest tests/ -v to verify nothing is broken