oh-my-openidea 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <img src="img/team.png" alt="Research Council" />
+</div>
+
+Six minds forged from the depths of human knowledge, each an eternal master of their domain,
+await your question to summon ideas that push the boundaries of what is known.
+
+
+Open Research Pipeline · Mix any models · From survey to paper draft
+
+
+## 📦 Installation
+
+### Quick Start
+
+```bash
+bunx oh-my-openidea@latest install
+```
+
+Non-interactive mode with API keys:
+
+```bash
+bunx oh-my-openidea@latest install --no-tui --openai=yes --anthropic=yes --tmux=no --skills=yes \
+  --serpapi-key=YOUR_SERPAPI_KEY \
+  --semantic-scholar-key=YOUR_S2_KEY
+```
+
+Then authenticate:
+
+```bash
+opencode auth login
+```
+
+Run `ping all agents` to verify everything works.
+
+> 💡 Configuration is stored in `~/.config/opencode/oh-my-openidea.json` (or `.jsonc` for comments support).
+
+### For LLM Agents
+
+Paste this into any coding agent:
+
+```
+Install and configure by following the instructions here:
+https://raw.githubusercontent.com/alvinunreal/oh-my-openidea/refs/heads/master/README.md
+```
+
+Detailed installation guide: [docs/installation.md](docs/installation.md)
+
+Additional guides:
+
+- [Antigravity Setup](docs/antigravity.md) - Complete guide for Antigravity provider configuration
+- [Tmux Integration](docs/tmux-integration.md) - Real-time agent monitoring with tmux
+
+---
+
+## 🔬 Meet the Research Council
+
+### 01. Orchestrator: The Architect of Discovery
+
+| The one who sees all paths. | The Orchestrator was born the moment research became too vast for a single mind. It emerged from the intersection of every field ever studied, carrying the weight of all human curiosity. It does not merely coordinate — it envisions. From a single question, it assembles the full arc of discovery: who to ask, what to find, which ideas to forge and which to abandon. It is the mind behind the research mind. |
+| --- | --- |
+| Role: Strategic research coordination and idea synthesis |
+| Prompt: orchestrator.ts |
+| Recommended Models: kimi-for-coding/k2p5 &nbsp; openai/gpt-5.2-codex |
+
+---
+
+### 02. Surveyor: The Cartographer of Knowledge
+
+| The one who maps the unknown. | The Surveyor has read every paper ever published and forgotten none of them. Born in the great libraries of the ancient world, it walked from Alexandria to arXiv without once stopping to sleep. It does not search — it remembers. Point it at any frontier and it returns not just what is known, but where the maps end. Its gift is the horizon: finding the exact edge where known territory becomes uncharted wilderness. |
+| --- | --- |
+| Role: Literature search and paper retrieval |
+| Prompt: surveyor.ts |
+| Recommended Models: openai/gpt-5.1-codex-mini &nbsp; google/gemini-3-flash |
+
+---
+
+### 03. Synthesizer: The Weaver of Understanding
+
+| The one who connects the dots. | The Synthesizer emerged when humanity realized that the sum of all papers was less than the understanding they contained. It is the weaver who threads ten thousand findings into a single tapestry of insight. Where others see isolated results, it sees patterns. Where others see contradictions, it sees tension awaiting resolution. It does not summarize knowledge — it transforms it into the fertile ground from which new ideas grow. |
+| --- | --- |
+| Role: Gap analysis and knowledge synthesis |
+| Prompt: synthesizer.ts |
+| Recommended Models: kimi-for-coding/k2p5 &nbsp; google/gemini-3-flash |
+
+---
+
+### 04. Critic: The Guardian of Truth
+
+| The voice of rigorous doubt. | The Critic was forged in the fires of ten thousand rejected papers. It has sat on every program committee that ever existed, read every rebuttal, and watched brilliant ideas crumble under the weight of prior work. It does not destroy — it purifies. It challenges every claim, demands every citation, and accepts only what can withstand the harshest scrutiny. What survives the Critic is worth building. What doesn't was never real to begin with. |
+| --- | --- |
+| Role: Novelty validation and adversarial review |
+| Prompt: critic.ts |
+| Recommended Models: openai/gpt-5.2-codex &nbsp; kimi-for-coding/k2p5 |
+
+---
+
+### 05. Architect: The Builder of Methods
+
+| The one who turns vision into plan. | The Architect has designed experiments since the first controlled trial. It does not dream — it engineers. Hand it a hypothesis and it returns the full blueprint: the baselines, the datasets, the metrics, the ablations, the failure modes, the compute budget. It has seen every experimental design choice and knows which ones hold and which collapse. Its plans do not merely test ideas — they prove or disprove them decisively. |
+| --- | --- |
+| Role: Methodology and experiment design |
+| Prompt: architect.ts |
+| Recommended Models: kimi-for-coding/k2p5 &nbsp; openai/gpt-5.1-codex-mini |
+
+---
+
+### 06. Writer: The Voice of Science
+
+| The one who makes it legible to the world. | The Writer is immortal because great writing never dies. It has composed every landmark paper in every field, always invisible, always essential. It carries the ancient knowledge of how to arrange words so that a reader understands not just what was done, but why it matters. It does not pad or inflate — it distills. Its abstracts have made reviewers lean forward. Its introductions have converted skeptics. It is the final step between a discovery and the world knowing about it. |
+| --- | --- |
+| Role: Research writing and paper structure |
+| Prompt: writer.ts |
+| Recommended Models: openai/gpt-5.1-codex-mini &nbsp; google/gemini-3-flash |
+
+---
+
+## 📚 Documentation
+
+- [Quick Reference](docs/quick-reference.md) - Presets, Skills, MCPs, Tools, Configuration
+- [Installation Guide](docs/installation.md) - Detailed installation and troubleshooting
+- [Cartography Skill](docs/cartography.md) - Custom skill for repository mapping + codemap generation
+- [Antigravity Setup](docs/antigravity.md) - Complete guide for Antigravity provider configuration
+- [Tmux Integration](docs/tmux-integration.md) - Real-time agent monitoring with tmux
+
+---
+
+## 📄 License
+
+MIT

package/dist/agents/architect.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createArchitectAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/critic.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createCriticAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/designer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createDesignerAgent(model: string, customPrompt?: string, customAppendPrompt?: string, behaviorPreset?: 'research' | 'code-research' | 'legacy-coding'): AgentDefinition;

package/dist/agents/explorer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createExplorerAgent(model: string, customPrompt?: string, customAppendPrompt?: string, behaviorPreset?: 'research' | 'code-research' | 'legacy-coding'): AgentDefinition;

package/dist/agents/fixer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createFixerAgent(model: string, customPrompt?: string, customAppendPrompt?: string, behaviorPreset?: 'research' | 'code-research' | 'legacy-coding'): AgentDefinition;

package/dist/agents/index.d.ts

@@ -0,0 +1,22 @@
+import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk/v2';
+import { type PluginConfig, SUBAGENT_NAMES } from '../config';
+import { type AgentDefinition } from './orchestrator';
+export type { AgentDefinition } from './orchestrator';
+export type SubagentName = (typeof SUBAGENT_NAMES)[number];
+export declare function isSubagent(name: string): name is SubagentName;
+/**
+ * Create all agent definitions with optional configuration overrides.
+ * Instantiates the orchestrator and all subagents, applying user config and defaults.
+ *
+ * @param config - Optional plugin configuration with agent overrides
+ * @returns Array of agent definitions (orchestrator first, then subagents)
+ */
+export declare function createAgents(config?: PluginConfig): AgentDefinition[];
+/**
+ * Get agent configurations formatted for the OpenCode SDK.
+ * Converts agent definitions to SDK config format and applies classification metadata.
+ *
+ * @param config - Optional plugin configuration with agent overrides
+ * @returns Record mapping agent names to their SDK configurations
+ */
+export declare function getAgentConfigs(config?: PluginConfig): Record<string, SDKAgentConfig>;

package/dist/agents/librarian.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createLibrarianAgent(model: string, customPrompt?: string, customAppendPrompt?: string, behaviorPreset?: 'research' | 'code-research' | 'legacy-coding'): AgentDefinition;

package/dist/agents/oracle.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createOracleAgent(model: string, customPrompt?: string, customAppendPrompt?: string, behaviorPreset?: 'research' | 'code-research' | 'legacy-coding'): AgentDefinition;

package/dist/agents/orchestrator.d.ts

@@ -0,0 +1,15 @@
+import type { AgentConfig } from '@opencode-ai/sdk/v2';
+export interface AgentDefinition {
+    name: string;
+    description?: string;
+    config: AgentConfig;
+    /** Priority-ordered model entries for runtime fallback resolution. */
+    _modelArray?: Array<{
+        id: string;
+        variant?: string;
+    }>;
+}
+export declare function createOrchestratorAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/surveyor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createSurveyorAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/synthesizer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createSynthesizerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/writer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createWriterAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/background/background-manager.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Background Task Manager
+ *
+ * Manages long-running AI agent tasks that execute in separate sessions.
+ * Background tasks run independently from the main conversation flow, allowing
+ * the user to continue working while tasks complete asynchronously.
+ *
+ * Key features:
+ * - Fire-and-forget launch (returns task_id immediately)
+ * - Creates isolated sessions for background work
+ * - Event-driven completion detection via session.status
+ * - Start queue with configurable concurrency limit
+ * - Supports task cancellation and result retrieval
+ */
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { BackgroundTaskConfig, PluginConfig } from '../config';
+import type { TmuxConfig } from '../config/schema';
+/**
+ * Represents a background task running in an isolated session.
+ * Tasks are tracked from creation through completion or failure.
+ */
+export interface BackgroundTask {
+    id: string;
+    sessionId?: string;
+    description: string;
+    agent: string;
+    status: 'pending' | 'starting' | 'running' | 'completed' | 'failed' | 'cancelled';
+    result?: string;
+    error?: string;
+    config: BackgroundTaskConfig;
+    parentSessionId: string;
+    startedAt: Date;
+    completedAt?: Date;
+    prompt: string;
+}
+/**
+ * Options for launching a new background task.
+ */
+export interface LaunchOptions {
+    agent: string;
+    prompt: string;
+    description: string;
+    parentSessionId: string;
+}
+export declare class BackgroundTaskManager {
+    private tasks;
+    private tasksBySessionId;
+    private agentBySessionId;
+    private client;
+    private directory;
+    private tmuxEnabled;
+    private config?;
+    private backgroundConfig;
+    private startQueue;
+    private activeStarts;
+    private maxConcurrentStarts;
+    private completionResolvers;
+    constructor(ctx: PluginInput, tmuxConfig?: TmuxConfig, config?: PluginConfig);
+    /**
+     * Look up the delegation rules for an agent type.
+     * Unknown agent types default to surveyor-only access, making it easy
+     * to add new background agent types without updating SUBAGENT_DELEGATION_RULES.
+     */
+    private getSubagentRules;
+    /**
+     * Check if a parent session is allowed to delegate to a specific agent type.
+     * @param parentSessionId - The session ID of the parent
+     * @param requestedAgent - The agent type being requested
+     * @returns true if allowed, false if not
+     */
+    isAgentAllowed(parentSessionId: string, requestedAgent: string): boolean;
+    /**
+     * Get the list of allowed subagents for a parent session.
+     * @param parentSessionId - The session ID of the parent
+     * @returns Array of allowed agent names, empty if none
+     */
+    getAllowedSubagents(parentSessionId: string): readonly string[];
+    /**
+     * Launch a new background task (fire-and-forget).
+     *
+     * Phase A (sync): Creates task record and returns immediately.
+     * Phase B (async): Session creation and prompt sending happen in background.
+     *
+     * @param opts - Task configuration options
+     * @returns The created background task with pending status
+     */
+    launch(opts: LaunchOptions): BackgroundTask;
+    /**
+     * Enqueue task for background start.
+     */
+    private enqueueStart;
+    /**
+     * Process start queue with concurrency limit.
+     */
+    private processQueue;
+    private resolveFallbackChain;
+    private promptWithTimeout;
+    /**
+     * Calculate tool permissions for a spawned agent based on its own delegation rules.
+     * Agents that cannot delegate (leaf nodes) get delegation tools disabled entirely,
+     * preventing models from even seeing tools they can never use.
+     *
+     * @param agentName - The agent type being spawned
+     * @returns Tool permissions object with background_task and task enabled/disabled
+     */
+    private calculateToolPermissions;
+    /**
+     * Start a task in the background (Phase B).
+     */
+    private startTask;
+    /**
+     * Handle session.status events for completion detection.
+     * Uses session.status instead of deprecated session.idle.
+     */
+    handleSessionStatus(event: {
+        type: string;
+        properties?: {
+            sessionID?: string;
+            status?: {
+                type: string;
+            };
+        };
+    }): Promise<void>;
+    /**
+     * Handle session.deleted events for cleanup.
+     * When a session is deleted, cancel associated tasks and clean up.
+     */
+    handleSessionDeleted(event: {
+        type: string;
+        properties?: {
+            info?: {
+                id?: string;
+            };
+            sessionID?: string;
+        };
+    }): Promise<void>;
+    /**
+     * Extract task result and mark complete.
+     */
+    private extractAndCompleteTask;
+    /**
+     * Complete a task and notify waiting callers.
+     */
+    private completeTask;
+    /**
+     * Send completion notification to parent session.
+     */
+    private sendCompletionNotification;
+    /**
+     * Retrieve the current state of a background task.
+     *
+     * @param taskId - The task ID to retrieve
+     * @returns The task object, or null if not found
+     */
+    getResult(taskId: string): BackgroundTask | null;
+    /**
+     * Wait for a task to complete.
+     *
+     * @param taskId - The task ID to wait for
+     * @param timeout - Maximum time to wait in milliseconds (0 = no timeout)
+     * @returns The completed task, or null if not found/timeout
+     */
+    waitForCompletion(taskId: string, timeout?: number): Promise<BackgroundTask | null>;
+    /**
+     * Cancel one or all running background tasks.
+     *
+     * @param taskId - Optional task ID to cancel. If omitted, cancels all pending/running tasks.
+     * @returns Number of tasks cancelled
+     */
+    cancel(taskId?: string): number;
+    /**
+     * Clean up all tasks.
+     */
+    cleanup(): void;
+}

package/dist/background/index.d.ts

@@ -0,0 +1,2 @@
+export { type BackgroundTask, BackgroundTaskManager, type LaunchOptions, } from './background-manager';
+export { TmuxSessionManager } from './tmux-session-manager';

package/dist/background/tmux-session-manager.d.ts

@@ -0,0 +1,63 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { TmuxConfig } from '../config/schema';
+/**
+ * Event shape for session events
+ */
+interface SessionEvent {
+    type: string;
+    properties?: {
+        info?: {
+            id?: string;
+            parentID?: string;
+            title?: string;
+        };
+        sessionID?: string;
+        status?: {
+            type: string;
+        };
+    };
+}
+/**
+ * TmuxSessionManager tracks child sessions and spawns/closes tmux panes for them.
+ *
+ * Uses session.status events for completion detection instead of polling.
+ */
+export declare class TmuxSessionManager {
+    private client;
+    private tmuxConfig;
+    private serverUrl;
+    private sessions;
+    private pollInterval?;
+    private enabled;
+    constructor(ctx: PluginInput, tmuxConfig: TmuxConfig);
+    /**
+     * Handle session.created events.
+     * Spawns a tmux pane for child sessions (those with parentID).
+     */
+    onSessionCreated(event: SessionEvent): Promise<void>;
+    /**
+     * Handle session.status events for completion detection.
+     * Uses session.status instead of deprecated session.idle.
+     *
+     * When a session becomes idle (completed), close its pane.
+     */
+    onSessionStatus(event: SessionEvent): Promise<void>;
+    /**
+     * Handle session.deleted events.
+     * When a session is deleted, close its tmux pane immediately.
+     */
+    onSessionDeleted(event: SessionEvent): Promise<void>;
+    private startPolling;
+    private stopPolling;
+    /**
+     * Poll sessions for status updates (fallback for reliability).
+     * Also handles timeout and missing session detection.
+     */
+    private pollSessions;
+    private closeSession;
+    /**
+     * Clean up all tracked sessions.
+     */
+    cleanup(): Promise<void>;
+}
+export {};

package/dist/cli/chutes-selection.d.ts

@@ -0,0 +1,3 @@
+import type { OpenCodeFreeModel } from './types';
+export declare function pickBestCodingChutesModel(models: OpenCodeFreeModel[]): OpenCodeFreeModel | null;
+export declare function pickSupportChutesModel(models: OpenCodeFreeModel[], primaryModel?: string): OpenCodeFreeModel | null;

package/dist/cli/config-io.d.ts

@@ -0,0 +1,26 @@
+import type { ConfigMergeResult, DetectedConfig, InstallConfig, OpenCodeConfig } from './types';
+/**
+ * Strip JSON comments (single-line // and multi-line) and trailing commas for JSONC support.
+ */
+export declare function stripJsonComments(json: string): string;
+export declare function parseConfigFile(path: string): {
+    config: OpenCodeConfig | null;
+    error?: string;
+};
+export declare function parseConfig(path: string): {
+    config: OpenCodeConfig | null;
+    error?: string;
+};
+/**
+ * Write config to file atomically.
+ */
+export declare function writeConfig(configPath: string, config: OpenCodeConfig): void;
+export declare function addPluginToOpenCodeConfig(): Promise<ConfigMergeResult>;
+export declare function writeLiteConfig(installConfig: InstallConfig): ConfigMergeResult;
+export declare function disableDefaultAgents(): ConfigMergeResult;
+export declare function canModifyOpenCodeConfig(): boolean;
+export declare function addAntigravityPlugin(): ConfigMergeResult;
+export declare function addGoogleProvider(): ConfigMergeResult;
+export declare function addChutesProvider(): ConfigMergeResult;
+export declare function detectAntigravityConfig(): boolean;
+export declare function detectCurrentConfig(): DetectedConfig;

package/dist/cli/config-manager.d.ts

@@ -0,0 +1,12 @@
+export * from './chutes-selection';
+export * from './config-io';
+export * from './dynamic-model-selection';
+export * from './external-rankings';
+export * from './model-selection';
+export * from './opencode-models';
+export * from './opencode-selection';
+export * from './paths';
+export * from './precedence-resolver';
+export * from './providers';
+export * from './scoring-v2';
+export * from './system';

package/dist/cli/custom-skills.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A custom skill bundled in this repository.
+ * Unlike npx-installed skills, these are copied from src/skills/ to ~/.config/opencode/skills/
+ */
+export interface CustomSkill {
+    /** Skill name (folder name) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** List of agents that should auto-allow this skill */
+    allowedAgents: string[];
+    /** Source path in this repo (relative to project root) */
+    sourcePath: string;
+}
+/**
+ * Registry of custom skills bundled in this repository.
+ */
+export declare const CUSTOM_SKILLS: CustomSkill[];
+/**
+ * Get the target directory for custom skills installation.
+ */
+export declare function getCustomSkillsDir(): string;
+/**
+ * Install a custom skill by copying from src/skills/ to ~/.config/opencode/skills/
+ * @param skill - The custom skill to install
+ * @param projectRoot - Root directory of oh-my-openidea project
+ * @returns True if installation succeeded, false otherwise
+ */
+export declare function installCustomSkill(skill: CustomSkill): boolean;

package/dist/cli/dynamic-model-selection.d.ts

@@ -0,0 +1,14 @@
+import type { DiscoveredModel, DynamicModelPlan, ExternalSignalMap, InstallConfig, ScoringEngineVersion } from './types';
+declare const AGENTS: readonly ["orchestrator", "oracle", "designer", "explorer", "librarian", "fixer"];
+type AgentName = (typeof AGENTS)[number];
+export type V1RankedScore = {
+    model: string;
+    totalScore: number;
+    baseScore: number;
+    externalSignalBoost: number;
+};
+export declare function rankModelsV1WithBreakdown(models: DiscoveredModel[], agent: AgentName, externalSignals?: ExternalSignalMap): V1RankedScore[];
+export declare function buildDynamicModelPlan(catalog: DiscoveredModel[], config: InstallConfig, externalSignals?: ExternalSignalMap, options?: {
+    scoringEngineVersion?: ScoringEngineVersion;
+}): DynamicModelPlan | null;
+export {};

package/dist/cli/external-rankings.d.ts

@@ -0,0 +1,8 @@
+import type { ExternalSignalMap } from './types';
+export declare function fetchExternalModelSignals(options?: {
+    artificialAnalysisApiKey?: string;
+    openRouterApiKey?: string;
+}): Promise<{
+    signals: ExternalSignalMap;
+    warnings: string[];
+}>;

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};