# Troubleshooting ## "Command not found: logicoal" The binary isn't in your PATH. **macOS:** Check if it's installed at `/usr/local/bin/logicoal`. If macOS Gatekeeper blocked it: ```bash xattr -d com.apple.quarantine /usr/local/bin/logicoal ``` **Linux:** Ensure the binary is in a PATH directory: ```bash sudo mv logicoal /usr/local/bin/ chmod +x /usr/local/bin/logicoal ``` **Windows:** Re-run the installer, which adds `logicoal` to PATH. Restart your terminal after installation. ## Login Fails or Browser Doesn't Open - Ensure port **9876** is not in use by another application (LogiCoal's OAuth callback runs on this port) - Check that the API is reachable: `logicoal health` - A firewall or VPN may be blocking the local callback server. Try disabling temporarily. - If the browser doesn't open automatically, check the terminal for the URL and open it manually. ## "Credit limit exceeded" You've used your token allocation. Check your plan: ```bash logicoal status ``` Options: - Wait for your quota to reset (check your plan details on coals.ai) - Upgrade your plan at coals.ai ## The AI Keeps Asking for Approval In **Normal** mode, write operations require your approval. If this is slowing you down: - Switch to **Auto** mode: press **Shift+Tab** twice or type `/mode auto` - The AI will execute all operations without prompting You can switch back to Normal mode at any time. ## Agents Not Running or Timing Out - Default time limit is **5 minutes** per agent (odyssey gets 10 minutes) - Check agent status: `/agents` - If an agent is stuck, cancel it: `/agents kill ` or `/agents kill all` - For complex multi-step tasks, use the **odyssey** role — it can delegate to child agents and has a longer time limit - In **Plan** mode, agents with write tools will fail. Switch to Normal or Auto mode. ## Agent Keeps Delegating After I Deny It Denying a delegation checkpoint now immediately stops the parent agent. If an agent still retries after denial, update to the latest version (`logicoal update` or reinstall). Additionally, denying 3+ checkpoints of any type will stop the agent. ## Agent Reads Wrong Files or Ignores My Request - The **planner** role is context-aware: it uses web search for new project questions and reads local files for existing codebase tasks. If it's reading unrelated files, rephrase your request to clarify whether you're asking about a new project or an existing one. - The **odyssey** role plans first before executing. If you want immediate code changes without a planning phase, use `@coder` directly. ## Update Shows Wrong Version If `logicoal update` installs a new version but the header still shows the old version number, the binary may not have been rebuilt correctly. Run `logicoal update` again to re-download. If the issue persists, reinstall from [logicoal.ai](/content/site-root.html). ## MCP Server Won't Connect 1. Check the error: `/mcp servers` 2. Verify `npx` is installed and working (most MCP servers use it) 3. Check required environment variables are set correctly in the config 4. Try reconnecting: `/mcp connect ` 5. Reload all config: `/mcp reload` 6. Test the server directly in your terminal: ```bash npx -y @modelcontextprotocol/server-github ``` ## Custom Command Not Showing Up - Commands are loaded at startup. Restart LogiCoal to pick up new files. - Verify the file is in `~/.coalcode/commands/` with a `.md` extension - Check the file is readable: open it in a text editor ## Custom Role Not Recognized - Verify the file is in `~/.coalcode/agents/roles/` (global) or `.coals/agents/` (project) with a `.md` extension - The `## System Prompt` section is required — roles without it are skipped - Restart LogiCoal to reload roles - Check with `/roles` to see if your role appears ## `/init` or `.COAL.md` Generation Fails - Ensure you're authenticated and have credits: `logicoal status` - Large projects may take longer. The command makes multiple AI calls — one for each section. - If it fails partway through, run `/init --force` to regenerate - For very large monorepos, try running from a specific subdirectory ## Terminal Colors Look Wrong LogiCoal uses 256-color ANSI sequences. - **Windows:** Use **Windows Terminal** (not `cmd.exe`). The classic command prompt has limited color support. - **Linux:** Ensure your terminal emulator supports 256 colors. Most modern terminals (GNOME Terminal, Kitty, Alacritty) do. - **SSH sessions:** Set `TERM=xterm-256color` before running LogiCoal. ## Nothing Happens When I Type - Check if a **checkpoint approval** prompt is active (look for Y/N prompt at the bottom). An agent may be waiting for your approval. - Press **Escape** to cancel any in-progress operation - Try **Ctrl+C** to exit and relaunch ## Tool Call Errors or "Too Many Iterations" The AI is limited to **50 tool iterations** per response. If it hits this limit: - Rephrase your request to be more specific - Break the task into smaller steps - Ask the AI to work on one file or component at a time ## Getting Help If you're stuck, type `/help` in the chat for a summary of all commands and features. For bugs or feature requests, visit the project repository or contact support through coals.ai.