opencode-dux 1.0.0

package/src/mcp/context7.ts

@@ -0,0 +1,14 @@
+import type { RemoteMcpConfig } from './types';
+
+/**
+ * Context7 - official documentation lookup for libraries
+ * @see https://context7.com
+ */
+export const context7: RemoteMcpConfig = {
+  type: 'remote',
+  url: 'https://mcp.context7.com/mcp',
+  headers: process.env.CONTEXT7_API_KEY
+    ? { CONTEXT7_API_KEY: process.env.CONTEXT7_API_KEY }
+    : undefined,
+  oauth: false,
+};

package/src/mcp/grep-app.ts

@@ -0,0 +1,11 @@
+import type { RemoteMcpConfig } from './types';
+
+/**
+ * grep.app - ultra-fast code search across GitHub repositories
+ * @see https://grep.app
+ */
+export const grep_app: RemoteMcpConfig = {
+  type: 'remote',
+  url: 'https://mcp.grep.app',
+  oauth: false,
+};

package/src/mcp/index.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'bun:test';
+import { createBuiltinMcps } from './index';
+
+describe('createBuiltinMcps', () => {
+  test('returns all MCPs when no disabled list provided', () => {
+    const mcps = createBuiltinMcps();
+    const names = Object.keys(mcps);
+
+    expect(names).toContain('websearch');
+    expect(names).toContain('context7');
+    expect(names).toContain('grep_app');
+  });
+
+  test('returns all MCPs with empty disabled list', () => {
+    const mcps = createBuiltinMcps([]);
+    const names = Object.keys(mcps);
+
+    expect(names.length).toBe(3);
+    expect(names).toContain('websearch');
+    expect(names).toContain('context7');
+    expect(names).toContain('grep_app');
+  });
+
+  test('excludes single disabled MCP', () => {
+    const mcps = createBuiltinMcps(['websearch']);
+    const names = Object.keys(mcps);
+
+    expect(names).not.toContain('websearch');
+    expect(names).toContain('context7');
+    expect(names).toContain('grep_app');
+  });
+
+  test('excludes multiple disabled MCPs', () => {
+    const mcps = createBuiltinMcps(['websearch', 'grep_app']);
+    const names = Object.keys(mcps);
+
+    expect(names).not.toContain('websearch');
+    expect(names).not.toContain('grep_app');
+    expect(names).toContain('context7');
+    expect(names.length).toBe(1);
+  });
+
+  test('excludes all MCPs when all disabled', () => {
+    const mcps = createBuiltinMcps(['websearch', 'context7', 'grep_app']);
+    const names = Object.keys(mcps);
+
+    expect(names.length).toBe(0);
+  });
+
+  test('ignores unknown MCP names in disabled list', () => {
+    const mcps = createBuiltinMcps(['unknown_mcp', 'nonexistent']);
+    const names = Object.keys(mcps);
+
+    // All valid MCPs should still be present
+    expect(names.length).toBe(3);
+    expect(names).toContain('websearch');
+    expect(names).toContain('context7');
+    expect(names).toContain('grep_app');
+  });
+
+  test('MCP configs have required properties', () => {
+    const mcps = createBuiltinMcps();
+
+    for (const [_name, config] of Object.entries(mcps)) {
+      expect(config).toBeDefined();
+      // Each MCP should have either url (remote) or command (local)
+      const hasUrl = 'url' in config;
+      const hasCommand = 'command' in config;
+      expect(hasUrl || hasCommand).toBe(true);
+    }
+  });
+
+  test('websearch MCP has correct structure', () => {
+    const mcps = createBuiltinMcps();
+    const websearch = mcps.websearch;
+
+    expect(websearch).toBeDefined();
+    expect('url' in websearch).toBe(true);
+  });
+
+  test('context7 MCP has correct structure', () => {
+    const mcps = createBuiltinMcps();
+    const context7 = mcps.context7;
+
+    expect(context7).toBeDefined();
+    expect('url' in context7).toBe(true);
+  });
+
+  test('grep_app MCP has correct structure', () => {
+    const mcps = createBuiltinMcps();
+    const grep_app = mcps.grep_app;
+
+    expect(grep_app).toBeDefined();
+    expect('url' in grep_app).toBe(true);
+  });
+});

package/src/mcp/index.ts

@@ -0,0 +1,66 @@
+import type { McpName, WebsearchConfig } from '../config';
+import { context7 } from './context7';
+import { grep_app } from './grep-app';
+import type { McpConfig } from './types';
+import { createWebsearchConfig, websearch } from './websearch';
+
+export type { LocalMcpConfig, McpConfig, RemoteMcpConfig } from './types';
+
+const allBuiltinMcps: Record<McpName, McpConfig> = {
+  websearch,
+  context7,
+  grep_app,
+};
+
+/**
+ * Creates MCP configurations, excluding disabled ones.
+ * Accepts an optional websearchConfig to override the default Exa provider.
+ */
+export function createBuiltinMcps(
+  disabledMcps: readonly string[] = [],
+  websearchConfig?: WebsearchConfig,
+): Record<string, McpConfig> {
+  const mcps = Object.fromEntries(
+    Object.entries(allBuiltinMcps).filter(
+      ([name]) => !disabledMcps.includes(name),
+    ),
+  );
+
+  // Override websearch with user-configured provider (default: Exa)
+  if (!disabledMcps.includes('websearch')) {
+    mcps.websearch = createWebsearchConfig(websearchConfig);
+  }
+
+  return mcps;
+}
+
+/**
+ * Filter MCP configs for a specific agent based on its MCP permissions.
+ * When no permission rules exist, all MCPs are available.
+ */
+export function filterMcpsForAgent(
+  allMcps: Record<string, McpConfig>,
+  _agentName: string,
+  mcpPermissionRules?: Record<string, 'allow' | 'ask' | 'deny'>,
+): Record<string, McpConfig> {
+  if (!mcpPermissionRules) {
+    return allMcps; // all allowed
+  }
+
+  const hasWildcard = mcpPermissionRules['*'] === 'allow';
+  const filtered: Record<string, McpConfig> = {};
+
+  for (const [name, config] of Object.entries(allMcps)) {
+    const specific = mcpPermissionRules[name];
+    if (specific === 'allow') {
+      filtered[name] = config;
+    } else if (specific === 'deny') {
+    } else if (hasWildcard) {
+      // No specific rule and wildcard is active → include
+      filtered[name] = config;
+    }
+    // else: no wildcard and no specific rule → exclude
+  }
+
+  return filtered;
+}

package/src/mcp/types.ts

@@ -0,0 +1,16 @@
+// MCP types - McpName is defined in config/schema.ts to avoid duplication
+
+export type RemoteMcpConfig = {
+  type: 'remote';
+  url: string;
+  headers?: Record<string, string>;
+  oauth?: false;
+};
+
+export type LocalMcpConfig = {
+  type: 'local';
+  command: string[];
+  environment?: Record<string, string>;
+};
+
+export type McpConfig = RemoteMcpConfig | LocalMcpConfig;

package/src/mcp/websearch.ts

@@ -0,0 +1,47 @@
+import type { WebsearchConfig } from '../config';
+import type { RemoteMcpConfig } from './types';
+
+/**
+ * Creates a websearch MCP config based on the provided configuration.
+ * Supports Exa (default) and Tavily providers.
+ * @see https://exa.ai  @see https://tavily.com
+ */
+export function createWebsearchConfig(
+  config?: WebsearchConfig,
+): RemoteMcpConfig {
+  const provider = config?.provider || 'exa';
+
+  if (provider === 'tavily') {
+    const tavilyKey = process.env.TAVILY_API_KEY;
+    if (!tavilyKey) {
+      throw new Error(
+        'TAVILY_API_KEY environment variable is required for Tavily provider',
+      );
+    }
+    return {
+      type: 'remote',
+      url: 'https://mcp.tavily.com/mcp/',
+      headers: {
+        Authorization: `Bearer ${tavilyKey}`,
+      },
+      oauth: false,
+    };
+  }
+
+  // Default: Exa provider
+  // Prefer exaApiKey in URL (reliably validated by Exa MCP endpoint)
+  // Fall back to anonymous access when no key is available
+  const exaKey = process.env.EXA_API_KEY;
+  const exaUrl = exaKey
+    ? `https://mcp.exa.ai/mcp?tools=web_search_exa&exaApiKey=${encodeURIComponent(exaKey)}`
+    : 'https://mcp.exa.ai/mcp?tools=web_search_exa';
+
+  return {
+    type: 'remote',
+    url: exaUrl,
+    oauth: false,
+  };
+}
+
+// Backward compatibility: default export using default (Exa) config
+export const websearch: RemoteMcpConfig = createWebsearchConfig();

package/src/skills/codemap/README.md

@@ -0,0 +1,60 @@
+# Codemap Skill
+
+Repository understanding and hierarchical codemap generation.
+
+## Overview
+
+Codemap helps orchestrators map and understand codebases by:
+
+1. Selecting relevant code/config files using LLM judgment
+2. Creating `.slim/codemap.json` for change tracking
+3. Generating empty `codemap.md` templates for fixers to fill in
+
+Legacy `.slim/cartography.json` state is migrated to `.slim/codemap.json` automatically.
+
+## Commands
+
+```bash
+# Initialize mapping
+node codemap.mjs init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
+
+# Check what changed
+node codemap.mjs changes --root /repo
+
+# Update hashes
+node codemap.mjs update --root /repo
+```
+
+## Outputs
+
+### .slim/codemap.json
+
+```json
+{
+  "metadata": {
+    "version": "1.0.0",
+    "last_run": "2026-01-25T19:00:00Z",
+    "include_patterns": ["src/**/*.ts"],
+    "exclude_patterns": ["node_modules/**"]
+  },
+  "file_hashes": {
+    "src/index.ts": "abc123..."
+  },
+  "folder_hashes": {
+    "src": "def456..."
+  }
+}
+```
+
+### codemap.md (per folder)
+
+Empty templates created in each folder for fixers to fill with:
+- Responsibility
+- Design patterns
+- Data/control flow
+- Integration points
+
+## Installation
+
+Bundled with `opencode-dux` and auto-scanned on plugin init. The plugin
+registers it automatically; no manual installation needed.

package/src/skills/codemap/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: codemap
+description: Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping
+---
+
+# Codemap Skill
+
+You help users understand and map repositories by creating hierarchical codemaps.
+
+## When to Use
+
+- User asks to understand/map a repository
+- User wants codebase documentation
+- Starting work on an unfamiliar codebase
+
+## Workflow
+
+### Step 1: Check for Existing State
+
+**First, check if `.slim/codemap.json` exists in the repo root.**
+
+If it does not exist, check for legacy state at `.slim/cartography.json`.
+
+If legacy state exists: move `.slim/cartography.json` to `.slim/codemap.json`, then continue with change detection.
+
+If `.slim/codemap.json` exists: Skip to Step 3 (Detect Changes) - no need to re-initialize.
+
+If neither file exists: Continue to Step 2 (Initialize).
+
+### Step 2: Initialize (Only if no state exists)
+
+1. **Analyze the repository structure** - List files, understand directories
+2. **Infer patterns** for **core code/config files ONLY** to include:
+   - **Include**: `src/**/*.ts`, `package.json`, etc.
+   - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
+     - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
+     - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
+     - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
+   - Respect `.gitignore` automatically
+3. **Run codemap.mjs init**:
+
+```bash
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs init \
+  --root ./ \
+  --include "src/**/*.ts" \
+  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
+```
+
+This creates:
+
+- `.slim/codemap.json` - File and folder hashes for change detection
+- Empty `codemap.md` files in all relevant subdirectories
+
+4. **Delegate codemap writing to Fixer agents** - Spawn one fixer per folder to read code and create or update its specific `codemap.md` file.
+
+### Step 3: Detect Changes (If state already exists)
+
+1. **Run codemap.mjs changes** to see what changed:
+
+```bash
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs changes \
+  --root ./
+```
+
+2. **Review the output** - It shows:
+
+   - Added files
+   - Removed files
+   - Modified files
+   - Affected folders
+
+3. **Only update affected codemaps** - Spawn one fixer per affected folder to update its `codemap.md`.
+4. **Run update** to save new state:
+
+```bash
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs update \
+  --root ./
+```
+
+### Step 4: Finalize Repository Atlas (Root Codemap)
+
+Once all specific directories are mapped, the Orchestrator must create or update the root `codemap.md`. This file serves as the **Master Entry Point** for any agent or human entering the repository.
+
+1.  **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose.
+2.  **Aggregate Sub-Maps**: Create a "Repository Directory Map" section. For every folder that has a `codemap.md`, extract its **Responsibility** summary and include it in a table or list in the root map.
+3.  **Cross-Reference**: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.
+
+### Step 5: Register Codemap in AGENTS.md
+
+**OpenCode auto-loads `AGENTS.md` into agent context on every session.** To ensure agents automatically discover and use the codemap, update (or create) `AGENTS.md` at the repo root:
+
+1. If `AGENTS.md` already exists and already contains a `## Repository Map` section, **skip this step** - the reference is already set up.
+2. If `AGENTS.md` exists but has no `## Repository Map` section, **append** the section below.
+3. If `AGENTS.md` doesn't exist, **create** it with the section below.
+
+```markdown
+## Repository Map
+
+A full codemap is available at `codemap.md` in the project root.
+
+Before working on any task, read `codemap.md` to understand:
+
+- Project architecture and entry points
+- Directory responsibilities and design patterns
+- Data flow and integration points between modules
+
+For deep work on a specific folder, also read that folder's `codemap.md`.
+```
+
+This is idempotent - repeated codemap runs will detect the existing section and skip. No duplication.
+
+## Codemap Content
+
+Fixers are responsible for writing `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
+
+- **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
+- **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
+- **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
+- **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.
+
+Example codemap:
+
+```markdown
+# src/agents/
+
+## Responsibility
+
+Defines agent personalities and manages their configuration lifecycle.
+
+## Design
+
+Each agent is a prompt + permission set. Config system uses:
+
+- Default prompts (orchestrator.ts, explorer.ts, etc.)
+- User overrides from ~/.config/opencode/opencode-dux.json
+- Permission wildcards for skill/MCP access control
+
+## Flow
+
+1. Plugin loads → calls getAgentConfigs()
+2. Reads user config preset
+3. Merges defaults with overrides
+4. Applies permission rules (wildcard expansion)
+5. Returns agent configs to OpenCode
+
+## Integration
+
+- Consumed by: Main plugin (src/index.ts)
+- Depends on: Config loader, skills registry
+```
+
+Example **Root Codemap (Atlas)**:
+
+```markdown
+# Repository Atlas: opencode-dux
+
+## Project Responsibility
+
+A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and multiplexer-assisted child sessions.
+
+## System Entry Points
+
+- `src/index.ts`: Plugin initialization and OpenCode integration.
+- `package.json`: Dependency manifest and build scripts.
+- `opencode-dux.json`: User configuration schema.
+
+## Directory Map (Aggregated)
+
+| Directory       | Responsibility Summary                                                            | Detailed Map                        |
+| --------------- | --------------------------------------------------------------------------------- | ----------------------------------- |
+| `src/agents/`   | Defines agent personalities (Orchestrator, Explorer) and manages model routing.   | [View Map](src/agents/codemap.md)   |
+| `src/features/` | Core logic for tmux integration and session state.                                | [View Map](src/features/codemap.md) |
+| `src/config/`   | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md)   |
+```