Skip to content
Back to search

owlex

Get a second opinion without leaving Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentic-mcp-tools--owlex/badge.svg)](/listings/agentic-mcp-tools--owlex)

HTML

<a href="/listings/agentic-mcp-tools--owlex"><img src="/api/listings/agentic-mcp-tools--owlex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv tool install git+https://github.com/agentic-mcp-tools/owlex.git

Add to `.mcp.json`:

{
  "mcpServers": {
    "owlex": {
      "command": "owlex-server"
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 170 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Owlex
  2. [![Version](https://img.shields.io/github/v/release/agentic-mcp-tools/owlex)](https://github.com/agentic-mcp-tools/owlex/releases)
  3. [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  4. [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
  5. [![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
  6. **Get a second opinion without leaving Claude Code.**
  7. Different AI models have different strengths and blind spots. Owlex lets you query Codex, Gemini, OpenCode, ClaudeOR, and AiChat directly from Claude Code - and optionally run a structured deliberation where they review each other's answers before Claude synthesizes a final response.
  8. ![Council demo](media/owlex_demo.gif)
  9. ## How the Council Works
  10. 1. **Round 1** - Your question goes to each agent independently. They answer without seeing each other.
  11. 2. **Round 2** - Each agent sees all Round 1 answers and can revise their position.
  12. 3. **Synthesis** - Claude reviews everything and outputs a structured answer.
  13. Use it for architecture decisions, debugging tricky issues, or when you want more confidence than a single model provides. Not for every question - for the ones that matter.
  14. ### Data Flow
  15. ![Council data flow](media/council_flow.gif)
  16. ## Installation
  17. ```bash
  18. uv tool install git+https://github.com/agentic-mcp-tools/owlex.git
  19. ```
  20. Add to `.mcp.json`:
  21. ```json
  22. {
  23. "mcpServers": {
  24. "owlex": {
  25. "command": "owlex-server"
  26. }
  27. }
  28. }
  29. ```
  30. ## Usage
  31. ### Council Deliberation
  32. ```
  33. council_ask prompt="Should I use a monorepo or multiple repos for 5 microservices?"
  34. ```
  35. Options:
  36. - `claude_opinion` - Share your initial thinking with agents
  37. - `deliberate` - Enable Round 2 revision (default: true)
  38. - `critique` - Agents critique each other instead of revise
  39. - `roles` - Assign specialist roles (dict or list)
  40. - `team` - Use a predefined team preset
  41. - `timeout` - Timeout per agent in seconds (default: 300)
  42. ### Specialist Roles
  43. Agents can operate with specialist perspectives that shape their analysis:
  44. | Role | Description |
  45. |------|-------------|
  46. | `security` | Security analyst - vulnerabilities, auth, data protection |
  47. | `perf` | Performance optimizer - efficiency, caching, scalability |
  48. | `skeptic` | Devil's advocate - challenge assumptions, find edge cases |
  49. | `architect` | System architect - design patterns, modularity, APIs |
  50. | `maintainer` | Code maintainer - readability, testing, tech debt |
  51. | `dx` | Developer experience - ergonomics, documentation, errors |
  52. | `testing` | Testing specialist - coverage, strategies, edge cases |
  53. | `neutral` | No role injection (default) |
  54. **Assign roles explicitly:**
  55. ```
  56. council_ask prompt="Review this auth flow" roles={"codex": "security", "gemini": "perf"}
  57. ```
  58. **Auto-assign from list (in agent order: codex, gemini, opencode, claudeor, aichat):**
  59. ```
  60. council_ask prompt="Review this code" roles=["security", "skeptic", "maintainer"]
  61. ```
  62. ### Team Presets
  63. Predefined role combinations for common scenarios:
  64. | Team | Codex | Gemini | OpenCode | ClaudeOR | AiChat |
  65. |------|-------|--------|----------|----------|--------|
  66. | `security_audit` | security | skeptic | architect | dx | testing |
  67. | `code_review` | maintainer | perf | testing | dx | security |
  68. | `architecture_review` | architect | perf | maintainer | dx | skeptic |
  69. | `devil_advocate` | skeptic | skeptic | skeptic | skeptic | skeptic |
  70. | `balanced` | security | perf | maintainer | dx | testing |
  71. | `optimal` | maintainer | architect | dx | skeptic | perf |
  72. ```
  73. council_ask prompt="Is this design secure?" team="security_audit"
  74. ```
  75. ### Individual Agent Sessions
  76. | Tool | Description |
  77. |------|-------------|
  78. | `start_codex_session` | New Codex session |
  79. | `resume_codex_session` | Resume with session ID or `--last` |
  80. | `start_gemini_session` | New Gemini session |
  81. | `resume_gemini_session` | Resume with index or `latest` |
  82. | `start_opencode_session` | New OpenCode session |
  83. | `resume_opencode_session` | Resume with session ID or `--continue` |
  84. | `start_claudeor_session` | New Claude via OpenRouter session |
  85. | `resume_claudeor_session` | Resume with session ID or `--continue` |
  86. | `start_aichat_session` | New AiChat session |
  87. | `resume_aichat_session` | Resume with session name |
  88. ### Claude Code Skills
  89. Non-blocking slash commands for quick agent invocation:
  90. | Skill | Description |
  91. |-------|-------------|
  92. | `/codex` | Ask Codex a question |
  93. | `/gemini` | Ask Gemini a question |
  94. | `/council` | Run council deliberation |
  95. | `/critique` | Run council in critique mode |
  96. ### Async Task Management
  97. Council runs in the background. Start a query, keep working, check results later.
  98. | Tool | Description |
  99. |------|-------------|
  100. | `wait_for_task` | Block until task completes |
  101. | `get_task_result` | Check result without blocking |
  102. | `list_tasks` | List tasks with status filter |
  103. | `cancel_task` | Kill running task |
  104. ## Configuration
  105. | Variable | Default | Description |
  106. |----------|---------|-------------|
  107. | `COUNCIL_EXCLUDE_AGENTS` | `` | Skip agents (e.g., `opencode,gemini,claudeor`) |
  108. | `COUNCIL_DEFAULT_TEAM` | `` | Default team when none specified (empty = neutral) |
  109. | `COUNCIL_CLAUDE_OPINION` | `false` | Claude shares its opinion with agents by default |
  110. | `OWLEX_DEFAULT_TIMEOUT` | `300` | Timeout in seconds |
  111. | `CODEX_BYPASS_APPROVALS` | `false` | Bypass sandbox (use with caution) |
  112. | `GEMINI_YOLO_MODE` | `false` | Auto-approve Gemini actions |
  113. | `OPENCODE_AGENT` | `plan` | `plan` (read-only) or `build` |
  114. | `OPENROUTER_API_KEY` | `` | OpenRouter API key (enables ClaudeOR agent) |
  115. | `CLAUDEOR_MODEL` | `` | OpenRouter model for ClaudeOR (e.g., `deepseek/deepseek-v3.2`) |
  116. | `AICHAT_MODEL` | `` | Model for AiChat (e.g., `openrouter:minimax/minimax-m2.5`) |
  117. ## Cost Notes
  118. - **Codex** and **Gemini** use your existing subscriptions (Claude Max, Google AI Pro, etc.)
  119. - **OpenCode** and **AiChat** use API tokens (provider-dependent)
  120. - Exclude agents with `COUNCIL_EXCLUDE_AGENTS` to control costs
  121. - Use council for important decisions, not every question
  122. ## When to Use Each Agent
  123. | Agent | Strengths |
  124. |-------|-----------|
  125. | **Codex (gpt5.2-codex)** | Deep reasoning, code review, bug finding |
  126. | **Gemini** | 1M context window, multimodal, large codebases |
  127. | **OpenCode** | Alternative perspective, configurable models |
  128. | **ClaudeOR** | Claude Code + OpenRouter (DeepSeek, GPT-4o, etc.) |
  129. | **AiChat** | Multi-provider (20+ backends), bring-your-own-model flexibility |
  130. | **Claude** | Complex multi-step implementation, synthesis |
owlex/agents/opencode.py · Bundled script · 253 lines · 2 findings marked
  1. """
  2. OpenCode CLI agent runner.
  3. """
  4. import asyncio
  5. import json
  6. import os
  7. import re
  8. from pathlib import Path
  9. from typing import Callable
  10. from ..config import config
  11. from .base import AgentRunner, AgentCommand
  12. def _get_opencode_project_id(working_directory: str) -> str | None:
  13. """
  14. Look up the projectID that OpenCode uses for session storage.
  15. OpenCode stores sessions in ~/.local/share/opencode/storage/session/<projectID>/
  16. The projectID is NOT computed from the path - it's stored in project config files
  17. at ~/.local/share/opencode/storage/project/<projectID>.json
  18. Returns None if no project found for the given working directory.
  19. """
  20. project_dir = Path.home() / ".local" / "share" / "opencode" / "storage" / "project"
  21. if not project_dir.exists():
  22. return None
  23. abs_path = os.path.normpath(os.path.abspath(os.path.expanduser(working_directory)))
  24. # Scan project files to find one matching our working directory
  25. try:
  26. for project_file in project_dir.glob("*.json"):
  27. if project_file.name == "global.json":
  28. continue # Skip global project
  29. try:
  30. with open(project_file) as f:
  31. project_data = json.load(f)
  32. stored_worktree = project_data.get("worktree")
  33. if not isinstance(stored_worktree, str):
  34. continue
  35. normalized_worktree = os.path.normpath(os.path.abspath(os.path.expanduser(stored_worktree)))
  36. if normalized_worktree == abs_path:
  37. project_id = project_data.get("id")
  38. if not isinstance(project_id, str):
  39. continue
  40. return project_id
  41. except (json.JSONDecodeError, OSError, UnicodeDecodeError):
  42. continue
  43. except OSError:
  44. return None
  45. return None
  46. async def get_latest_opencode_session(
  47. working_directory: str | None = None,
  48. since_mtime: float | None = None,
  49. max_retries: int = 3,
  50. retry_delay: float = 0.3,
  51. ) -> str | None:
  52. """
  53. Find the most recent OpenCode session ID from filesystem.
  54. OpenCode stores sessions in ~/.local/share/opencode/storage/session/<project>/ses_*.json
  55. The session ID is extracted from the filename (without .json extension).
  56. Args:
  57. working_directory: Project directory to scope session search.
  58. since_mtime: Only consider sessions created after this timestamp.
  59. max_retries: Number of retries if no session found.
  60. retry_delay: Delay between retries in seconds.
  61. Returns:
  62. Session ID (e.g., ses_49b5d1b81ffeZfa2uTg3NVmKrH) if found, None otherwise
  63. """
  64. opencode_dir = Path.home() / ".local" / "share" / "opencode" / "storage" / "session"
  65. if not opencode_dir.exists():
  66. return None
  67. # Require working_directory for project-scoped session discovery
  68. # Without it, we could accidentally resume a session from a different project
  69. if not working_directory:
  70. return None
  71. # Look up the projectID from OpenCode's config files
  72. project_id = _get_opencode_project_id(working_directory)
  73. if not project_id:
  74. return None # Project not found in OpenCode's registry
  75. for attempt in range(max_retries):
  76. latest_file: Path | None = None
  77. latest_mtime: float = 0
  78. project_dirs = [opencode_dir / project_id]
  79. for project_dir in project_dirs:
  80. if not project_dir.exists():
  81. continue
  82. try:
  83. for session_file in project_dir.glob("ses_*.json"):
  84. try:
  85. mtime = session_file.stat().st_mtime
  86. # Skip files older than since_mtime if specified
  87. if since_mtime is not None and mtime < since_mtime:
  88. continue
  89. if mtime > latest_mtime:
  90. latest_mtime = mtime
  91. latest_file = session_file
  92. except OSError:
  93. continue
  94. except OSError:
  95. continue
  96. if latest_file is not None:
  97. # Session ID is the filename without .json extension
  98. return latest_file.stem
  99. # Retry with delay if no session found
  100. # Uses asyncio.sleep to avoid blocking the event loop
  101. if attempt < max_retries - 1:
  102. await asyncio.sleep(retry_delay)
  103. return None
  104. def clean_opencode_output(raw_output: str, original_prompt: str = "") -> str:
  105. """Clean OpenCode CLI output by removing noise."""
  106. if not config.opencode.clean_output:
  107. return raw_output
  108. cleaned = raw_output
  109. # Remove ANSI escape codes
  110. cleaned = re.sub(r'\x1b\[[0-9;]*m', '', cleaned)
  111. # Collapse multiple newlines
  112. cleaned = re.sub(r'\n{3,}', '\n\n', cleaned)
  113. return cleaned.strip()
  114. class OpenCodeRunner(AgentRunner):
  115. """Runner for OpenCode AI coding agent CLI."""
  116. @property
  117. def name(self) -> str:
  118. return "opencode"
  119. def build_exec_command(
  120. self,
  121. prompt: str,
  122. working_directory: str | None = None,
  123. enable_search: bool = False, # OpenCode doesn't have web search flag
  124. **kwargs,
  125. ) -> AgentCommand:
  126. """Build command for running OpenCode with a prompt."""
  127. full_command = ["opencode", "run"]
  128. # Model configuration (format: provider/model)
  129. if config.opencode.model:
  130. full_command.extend(["--model", config.opencode.model])
  131. # Agent selection (e.g., "build", "plan")
  132. if config.opencode.agent:
  133. full_command.extend(["--agent", config.opencode.agent])
  134. # Output format
  135. if config.opencode.json_output:
  136. full_command.extend(["--format", "json"])
  137. # Use -- to signal end of options, preventing prompt-as-flag injection
  138. # This ensures prompts starting with - aren't parsed as CLI flags
  139. # Note: OpenCode doesn't support stdin input, so we must use positional args
  140. full_command.append("--")
  141. full_command.append(prompt)
  142. return AgentCommand(
  143. command=full_command,
  144. prompt="", # Prompt is in command as positional arg
  145. cwd=working_directory,
  146. output_prefix="OpenCode Output",
  147. not_found_hint="Please ensure OpenCode is installed (curl -fsSL https://opencode.ai/install | bash).",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 180 on GitHub
  148. stream=True,
  149. )
  150. def build_resume_command(
  151. self,
  152. session_ref: str,
  153. prompt: str,
  154. working_directory: str | None = None,
  155. enable_search: bool = False,
  156. **kwargs,
  157. ) -> AgentCommand:
  158. """Build command for resuming an existing OpenCode session."""
  159. full_command = ["opencode", "run"]
  160. # Model configuration
  161. if config.opencode.model:
  162. full_command.extend(["--model", config.opencode.model])
  163. # Agent selection
  164. if config.opencode.agent:
  165. full_command.extend(["--agent", config.opencode.agent])
  166. # Output format
  167. if config.opencode.json_output:
  168. full_command.extend(["--format", "json"])
  169. # Session resume
  170. if session_ref == "--continue" or session_ref == "latest":
  171. full_command.append("--continue")
  172. else:
  173. # Validate session_ref to prevent flag injection
  174. if session_ref.startswith("-"):
  175. raise ValueError(f"Invalid session_ref: '{session_ref}' - cannot start with '-'")
  176. full_command.extend(["--session", session_ref])
  177. # Use -- to signal end of options, preventing prompt-as-flag injection
  178. # Note: OpenCode doesn't support stdin input, so we must use positional args
  179. full_command.append("--")
  180. full_command.append(prompt)
  181. return AgentCommand(
  182. command=full_command,
  183. prompt="", # Prompt is in command as positional arg
  184. cwd=working_directory,
  185. output_prefix="OpenCode Resume Output",
  186. not_found_hint="Please ensure OpenCode is installed (curl -fsSL https://opencode.ai/install | bash).",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 226 on GitHub
  187. stream=False, # Resume uses non-streaming mode
  188. )
  189. def get_output_cleaner(self) -> Callable[[str, str], str]:
  190. return clean_opencode_output
  191. async def parse_session_id(
  192. self,
  193. output: str,
  194. since_mtime: float | None = None,
  195. working_directory: str | None = None,
  196. ) -> str | None:
  197. """
  198. Get session ID for OpenCode.
  199. OpenCode doesn't output session ID in stdout, so we check the filesystem
  200. for the most recently created session file.
  201. Args:
  202. output: Ignored (OpenCode doesn't output session IDs)
  203. since_mtime: Only consider sessions created after this timestamp
  204. working_directory: Project directory to scope session search
  205. """
  206. return await get_latest_opencode_session(
  207. working_directory=working_directory,
  208. since_mtime=since_mtime,
  209. )

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.