Regenerate AGENTS.md hierarchy with latest codebase state
This commit is contained in:
YeonGyu-Kim
61
AGENTS.md
61
AGENTS.md
@@ -1,7 +1,7 @@
|
||||
# PROJECT KNOWLEDGE BASE
|
||||
|
||||
**Generated:** 2026-02-03T16:10:30+09:00
|
||||
**Commit:** d7679e14
|
||||
**Generated:** 2026-02-06T18:30:00+09:00
|
||||
**Commit:** c6c149e
|
||||
**Branch:** dev
|
||||
|
||||
---
|
||||
@@ -120,7 +120,7 @@ This is an **international open-source project**. To ensure accessibility and ma
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3 Flash). 41 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 11 specialized agents, full Claude Code compatibility. "oh-my-zsh" for OpenCode.
|
||||
OpenCode plugin: multi-model agent orchestration (Claude Opus 4.6, GPT-5.3 Codex, Gemini 3 Flash). 40+ lifecycle hooks, 25+ tools (LSP, AST-Grep, delegation), 11 specialized agents, full Claude Code compatibility. "oh-my-zsh" for OpenCode.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
@@ -128,15 +128,18 @@ OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemi
|
||||
oh-my-opencode/
|
||||
├── src/
|
||||
│ ├── agents/ # 11 AI agents - see src/agents/AGENTS.md
|
||||
│ ├── hooks/ # 41 lifecycle hooks - see src/hooks/AGENTS.md
|
||||
│ ├── tools/ # 20+ tools - see src/tools/AGENTS.md
|
||||
│ ├── features/ # Background agents, Claude Code compat - see src/features/AGENTS.md
|
||||
│ ├── hooks/ # 40+ lifecycle hooks - see src/hooks/AGENTS.md
|
||||
│ ├── tools/ # 25+ tools - see src/tools/AGENTS.md
|
||||
│ ├── features/ # Background agents, skills, Claude Code compat - see src/features/AGENTS.md
|
||||
│ ├── shared/ # 66 cross-cutting utilities - see src/shared/AGENTS.md
|
||||
│ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
|
||||
│ ├── mcp/ # Built-in MCPs - see src/mcp/AGENTS.md
|
||||
│ ├── config/ # Zod schema, TypeScript types
|
||||
│ └── index.ts # Main plugin entry (788 lines)
|
||||
├── script/ # build-schema.ts, build-binaries.ts
|
||||
│ ├── config/ # Zod schema (schema.ts 455 lines), TypeScript types
|
||||
│ ├── plugin-handlers/ # Plugin config loading (config-handler.ts 501 lines)
|
||||
│ ├── index.ts # Main plugin entry (924 lines)
|
||||
│ ├── plugin-config.ts # Config loading orchestration
|
||||
│ └── plugin-state.ts # Model cache state
|
||||
├── script/ # build-schema.ts, build-binaries.ts, publish.ts
|
||||
├── packages/ # 11 platform-specific binaries
|
||||
└── dist/ # Build output (ESM + .d.ts)
|
||||
```
|
||||
@@ -145,15 +148,17 @@ oh-my-opencode/
|
||||
|
||||
| Task | Location | Notes |
|
||||
|------|----------|-------|
|
||||
| Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` |
|
||||
| Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` in utils.ts |
|
||||
| Add hook | `src/hooks/` | Create dir with `createXXXHook()`, register in index.ts |
|
||||
| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts |
|
||||
| Add MCP | `src/mcp/` | Create config, add to index.ts |
|
||||
| Add MCP | `src/mcp/` | Create config, add to `createBuiltinMcps()` |
|
||||
| Add skill | `src/features/builtin-skills/` | Create dir with SKILL.md |
|
||||
| Add command | `src/features/builtin-commands/` | Add template + register in commands.ts |
|
||||
| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` |
|
||||
| Background agents | `src/features/background-agent/` | manager.ts (1418 lines) |
|
||||
| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (757 lines) |
|
||||
| Plugin config | `src/plugin-handlers/config-handler.ts` | JSONC loading, merging, migration |
|
||||
| Background agents | `src/features/background-agent/` | manager.ts (1556 lines) |
|
||||
| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (770 lines) |
|
||||
| Delegation | `src/tools/delegate-task/` | Category routing (executor.ts 983 lines) |
|
||||
|
||||
## TDD (Test-Driven Development)
|
||||
|
||||
@@ -165,7 +170,7 @@ oh-my-opencode/
|
||||
**Rules:**
|
||||
- NEVER write implementation before test
|
||||
- NEVER delete failing tests - fix the code
|
||||
- Test file: `*.test.ts` alongside source (100 test files)
|
||||
- Test file: `*.test.ts` alongside source (100+ test files)
|
||||
- BDD comments: `//#given`, `//#when`, `//#then`
|
||||
|
||||
## CONVENTIONS
|
||||
@@ -175,7 +180,7 @@ oh-my-opencode/
|
||||
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
|
||||
- **Exports**: Barrel pattern via index.ts
|
||||
- **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories
|
||||
- **Testing**: BDD comments, 100 test files
|
||||
- **Testing**: BDD comments, 100+ test files
|
||||
- **Temperature**: 0.1 for code agents, max 0.3
|
||||
|
||||
## ANTI-PATTERNS
|
||||
@@ -222,7 +227,7 @@ oh-my-opencode/
|
||||
bun run typecheck # Type check
|
||||
bun run build # ESM + declarations + schema
|
||||
bun run rebuild # Clean + Build
|
||||
bun test # 100 test files
|
||||
bun test # 100+ test files
|
||||
```
|
||||
|
||||
## DEPLOYMENT
|
||||
@@ -236,30 +241,38 @@ bun test # 100 test files
|
||||
|
||||
| File | Lines | Description |
|
||||
|------|-------|-------------|
|
||||
| `src/features/builtin-skills/skills.ts` | 29 | Skill definitions |
|
||||
| `src/features/background-agent/manager.ts` | 1418 | Task lifecycle, concurrency |
|
||||
| `src/agents/prometheus/` | 1492 | Planning agent prompt |
|
||||
| `src/tools/delegate-task/tools.ts` | 1135 | Category-based delegation |
|
||||
| `src/hooks/atlas/index.ts` | 757 | Orchestrator hook |
|
||||
| `src/index.ts` | 788 | Main plugin entry |
|
||||
| `src/features/background-agent/manager.ts` | 1556 | Task lifecycle, concurrency |
|
||||
| `src/features/builtin-skills/skills/git-master.ts` | 1107 | Git master skill definition |
|
||||
| `src/tools/delegate-task/executor.ts` | 983 | Category-based delegation executor |
|
||||
| `src/index.ts` | 924 | Main plugin entry |
|
||||
| `src/tools/lsp/client.ts` | 803 | LSP client operations |
|
||||
| `src/hooks/atlas/index.ts` | 770 | Orchestrator hook |
|
||||
| `src/tools/background-task/tools.ts` | 734 | Background task tools |
|
||||
| `src/cli/config-manager.ts` | 667 | JSONC config parsing |
|
||||
| `src/features/skill-mcp-manager/manager.ts` | 640 | MCP client lifecycle |
|
||||
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactor command template |
|
||||
| `src/agents/hephaestus.ts` | 618 | Autonomous deep worker agent |
|
||||
| `src/tools/delegate-task/constants.ts` | 552 | Delegation constants |
|
||||
| `src/cli/install.ts` | 542 | Interactive CLI installer |
|
||||
| `src/agents/sisyphus.ts` | 530 | Main orchestrator agent |
|
||||
|
||||
## MCP ARCHITECTURE
|
||||
|
||||
Three-tier system:
|
||||
1. **Built-in**: websearch (Exa), context7 (docs), grep_app (GitHub)
|
||||
1. **Built-in**: websearch (Exa/Tavily), context7 (docs), grep_app (GitHub)
|
||||
2. **Claude Code compat**: .mcp.json with `${VAR}` expansion
|
||||
3. **Skill-embedded**: YAML frontmatter in skills
|
||||
|
||||
## CONFIG SYSTEM
|
||||
|
||||
- **Zod validation**: `src/config/schema.ts`
|
||||
- **Zod validation**: `src/config/schema.ts` (455 lines)
|
||||
- **JSONC support**: Comments, trailing commas
|
||||
- **Multi-level**: Project (`.opencode/`) → User (`~/.config/opencode/`)
|
||||
- **Loading**: `src/plugin-handlers/config-handler.ts` → merge → validate
|
||||
|
||||
## NOTES
|
||||
|
||||
- **OpenCode**: Requires >= 1.0.150
|
||||
- **Flaky tests**: ralph-loop (CI timeout), session-state (parallel pollution)
|
||||
- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
|
||||
- **No linter/formatter**: No ESLint, Prettier, or Biome configured
|
||||
|
||||
@@ -15,32 +15,32 @@
|
||||
agents/
|
||||
├── atlas/ # Master Orchestrator (holds todo list)
|
||||
│ ├── index.ts
|
||||
│ ├── default.ts
|
||||
│ ├── gpt.ts
|
||||
│ ├── default.ts # Claude-optimized prompt (390 lines)
|
||||
│ ├── gpt.ts # GPT-optimized prompt (330 lines)
|
||||
│ └── utils.ts
|
||||
├── sisyphus.ts # Main prompt (SF Bay Area engineer identity)
|
||||
├── hephaestus.ts # Autonomous Deep Worker (GPT 5.2 Codex, "The Legitimate Craftsman")
|
||||
├── prometheus/ # Planning Agent (Interview/Consultant mode)
|
||||
│ ├── index.ts
|
||||
│ ├── plan-template.ts # Work plan structure (423 lines)
|
||||
│ ├── interview-mode.ts # Interview flow (335 lines)
|
||||
│ ├── plan-generation.ts
|
||||
│ ├── high-accuracy-mode.ts
|
||||
│ ├── identity-constraints.ts # Identity rules (301 lines)
|
||||
│ └── behavioral-summary.ts
|
||||
├── sisyphus-junior/ # Delegated task executor (category-spawned)
|
||||
│ ├── index.ts
|
||||
│ ├── default.ts
|
||||
│ └── gpt.ts
|
||||
├── sisyphus.ts # Main orchestrator prompt (530 lines)
|
||||
├── hephaestus.ts # Autonomous deep worker (618 lines, GPT 5.3 Codex)
|
||||
├── oracle.ts # Strategic advisor (GPT-5.2)
|
||||
├── librarian.ts # Multi-repo research (GitHub CLI, Context7)
|
||||
├── explore.ts # Fast contextual grep (Grok Code Fast)
|
||||
├── librarian.ts # Multi-repo research (328 lines)
|
||||
├── explore.ts # Fast contextual grep
|
||||
├── multimodal-looker.ts # Media analyzer (Gemini 3 Flash)
|
||||
├── prometheus/ # Planning (Interview/Consultant mode)
|
||||
│ ├── index.ts
|
||||
│ ├── plan-template.ts
|
||||
│ ├── interview-mode.ts
|
||||
│ ├── plan-generation.ts
|
||||
│ ├── high-accuracy-mode.ts
|
||||
│ ├── identity-constraints.ts
|
||||
│ └── behavioral-summary.ts
|
||||
├── metis.ts # Pre-planning analysis (Gap detection)
|
||||
├── momus.ts # Plan reviewer (Ruthless fault-finding)
|
||||
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation
|
||||
├── metis.ts # Pre-planning analysis (347 lines)
|
||||
├── momus.ts # Plan reviewer
|
||||
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (431 lines)
|
||||
├── types.ts # AgentModelConfig, AgentPromptMetadata
|
||||
├── utils.ts # createBuiltinAgents(), resolveModelWithFallback()
|
||||
├── utils.ts # createBuiltinAgents(), resolveModelWithFallback() (485 lines)
|
||||
└── index.ts # builtinAgents export
|
||||
```
|
||||
|
||||
@@ -73,15 +73,17 @@ agents/
|
||||
| explore | write, edit, task, delegate_task, call_omo_agent |
|
||||
| multimodal-looker | Allowlist: read only |
|
||||
| Sisyphus-Junior | task, delegate_task |
|
||||
| Atlas | task, call_omo_agent |
|
||||
|
||||
## PATTERNS
|
||||
- **Factory**: `createXXXAgent(model: string): AgentConfig`
|
||||
- **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers.
|
||||
- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`.
|
||||
- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas.
|
||||
- **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers
|
||||
- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`
|
||||
- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas
|
||||
- **Model-specific routing**: Atlas, Sisyphus-Junior have GPT vs Claude prompt variants
|
||||
|
||||
## ANTI-PATTERNS
|
||||
- **Trust reports**: NEVER trust "I'm done" - verify outputs.
|
||||
- **High temp**: Don't use >0.3 for code agents.
|
||||
- **Sequential calls**: Use `delegate_task` with `run_in_background` for exploration.
|
||||
- **Prometheus writing code**: Planner only - never implements.
|
||||
- **Trust reports**: NEVER trust "I'm done" - verify outputs
|
||||
- **High temp**: Don't use >0.3 for code agents
|
||||
- **Sequential calls**: Use `delegate_task` with `run_in_background` for exploration
|
||||
- **Prometheus writing code**: Planner only - never implements
|
||||
|
||||
@@ -2,25 +2,25 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
CLI entry: `bunx oh-my-opencode`. 4 commands with Commander.js + @clack/prompts TUI.
|
||||
CLI entry: `bunx oh-my-opencode`. 5 commands with Commander.js + @clack/prompts TUI.
|
||||
|
||||
**Commands**: install (interactive setup), doctor (14 health checks), run (session launcher), get-local-version
|
||||
**Commands**: install (interactive setup), doctor (14 health checks), run (session launcher), get-local-version, mcp-oauth
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
cli/
|
||||
├── index.ts # Commander.js entry (4 commands)
|
||||
├── index.ts # Commander.js entry (5 commands)
|
||||
├── install.ts # Interactive TUI (542 lines)
|
||||
├── config-manager.ts # JSONC parsing (667 lines)
|
||||
├── types.ts # InstallArgs, InstallConfig
|
||||
├── model-fallback.ts # Model fallback configuration
|
||||
├── types.ts # InstallArgs, InstallConfig
|
||||
├── doctor/
|
||||
│ ├── index.ts # Doctor entry
|
||||
│ ├── runner.ts # Check orchestration
|
||||
│ ├── formatter.ts # Colored output
|
||||
│ ├── constants.ts # Check IDs, symbols
|
||||
│ ├── types.ts # CheckResult, CheckDefinition (114 lines)
|
||||
│ ├── types.ts # CheckResult, CheckDefinition
|
||||
│ └── checks/ # 14 checks, 23 files
|
||||
│ ├── version.ts # OpenCode + plugin version
|
||||
│ ├── config.ts # JSONC validity, Zod
|
||||
@@ -28,10 +28,11 @@ cli/
|
||||
│ ├── dependencies.ts # AST-Grep, Comment Checker
|
||||
│ ├── lsp.ts # LSP connectivity
|
||||
│ ├── mcp.ts # MCP validation
|
||||
│ ├── model-resolution.ts # Model resolution check
|
||||
│ ├── model-resolution.ts # Model resolution check (323 lines)
|
||||
│ └── gh.ts # GitHub CLI
|
||||
├── run/
|
||||
│ └── index.ts # Session launcher
|
||||
│ ├── index.ts # Session launcher
|
||||
│ └── events.ts # CLI run events (325 lines)
|
||||
├── mcp-oauth/
|
||||
│ └── index.ts # MCP OAuth flow
|
||||
└── get-local-version/
|
||||
@@ -46,6 +47,7 @@ cli/
|
||||
| `doctor` | 14 health checks for diagnostics |
|
||||
| `run` | Launch session with todo enforcement |
|
||||
| `get-local-version` | Version detection and update check |
|
||||
| `mcp-oauth` | MCP OAuth authentication flow |
|
||||
|
||||
## DOCTOR CATEGORIES (14 Checks)
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
20 feature modules: background agents, skill MCPs, builtin skills/commands, Claude Code compatibility layer.
|
||||
17 feature modules: background agents, skill MCPs, builtin skills/commands, Claude Code compatibility layer, task management.
|
||||
|
||||
**Feature Types**: Task orchestration, Skill definitions, Command templates, Claude Code loaders, Supporting utilities
|
||||
|
||||
@@ -10,27 +10,25 @@
|
||||
|
||||
```
|
||||
features/
|
||||
├── background-agent/ # Task lifecycle (1418 lines)
|
||||
├── background-agent/ # Task lifecycle (1556 lines)
|
||||
│ ├── manager.ts # Launch → poll → complete
|
||||
│ └── concurrency.ts # Per-provider limits
|
||||
├── builtin-skills/ # Core skills (1729 lines)
|
||||
│ └── skills.ts # playwright, agent-browser, frontend-ui-ux, git-master, dev-browser
|
||||
├── builtin-skills/ # Core skills
|
||||
│ └── skills/ # playwright, agent-browser, frontend-ui-ux, git-master, dev-browser
|
||||
├── builtin-commands/ # ralph-loop, refactor, ulw-loop, init-deep, start-work, cancel-ralph, stop-continuation
|
||||
├── claude-code-agent-loader/ # ~/.claude/agents/*.md
|
||||
├── claude-code-command-loader/ # ~/.claude/commands/*.md
|
||||
├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion
|
||||
├── claude-code-plugin-loader/ # installed_plugins.json
|
||||
├── claude-code-plugin-loader/ # installed_plugins.json (486 lines)
|
||||
├── claude-code-session-state/ # Session persistence
|
||||
├── opencode-skill-loader/ # Skills from 6 directories
|
||||
├── opencode-skill-loader/ # Skills from 6 directories (loader.ts 311 lines)
|
||||
├── context-injector/ # AGENTS.md/README.md injection
|
||||
├── boulder-state/ # Todo state persistence
|
||||
├── hook-message-injector/ # Message injection
|
||||
├── task-toast-manager/ # Background task notifications
|
||||
├── skill-mcp-manager/ # MCP client lifecycle (617 lines)
|
||||
├── tmux-subagent/ # Tmux session management
|
||||
├── skill-mcp-manager/ # MCP client lifecycle (640 lines)
|
||||
├── tmux-subagent/ # Tmux session management (472 lines)
|
||||
├── mcp-oauth/ # MCP OAuth handling
|
||||
├── sisyphus-swarm/ # Swarm coordination
|
||||
├── sisyphus-tasks/ # Task tracking
|
||||
└── claude-tasks/ # Task schema/storage - see AGENTS.md
|
||||
```
|
||||
|
||||
|
||||
@@ -12,6 +12,7 @@ claude-tasks/
|
||||
├── types.test.ts # Schema validation tests (8 tests)
|
||||
├── storage.ts # File operations
|
||||
├── storage.test.ts # Storage tests (14 tests)
|
||||
├── todo-sync.ts # Task → Todo synchronization
|
||||
└── index.ts # Barrel exports
|
||||
```
|
||||
|
||||
@@ -44,86 +45,21 @@ interface Task {
|
||||
|
||||
## TODO SYNC
|
||||
|
||||
The task system includes a sync layer (`todo-sync.ts`) that automatically mirrors task state to the project's Todo system.
|
||||
Task system includes sync layer (`todo-sync.ts`) that automatically mirrors task state to the project's Todo system.
|
||||
|
||||
- **Creation**: Creating a task via `task_create` adds a corresponding item to the Todo list.
|
||||
- **Updates**: Updating a task's `status` or `subject` via `task_update` reflects in the Todo list.
|
||||
- **Completion**: Marking a task as `completed` automatically marks the Todo item as done.
|
||||
- **Creation**: `task_create` adds corresponding Todo item
|
||||
- **Updates**: `task_update` reflects in Todo list
|
||||
- **Completion**: `completed` status marks Todo item done
|
||||
|
||||
## STORAGE UTILITIES
|
||||
|
||||
### getTaskDir(config)
|
||||
|
||||
Returns the task storage directory path.
|
||||
|
||||
**Default behavior (no config override):**
|
||||
Returns `~/.config/opencode/tasks/<task-list-id>/` where:
|
||||
- Task list ID is resolved via `resolveTaskListId()`
|
||||
|
||||
**With `storage_path` config:**
|
||||
- Absolute paths (starting with `/`) are returned as-is
|
||||
- Relative paths are joined with `process.cwd()`
|
||||
|
||||
### resolveTaskListId(config)
|
||||
|
||||
Resolves the task list ID for directory scoping.
|
||||
|
||||
**Priority order:**
|
||||
1. `ULTRAWORK_TASK_LIST_ID` environment variable
|
||||
2. `config.sisyphus?.tasks?.task_list_id` config option
|
||||
3. Sanitized `basename(process.cwd())` as fallback
|
||||
|
||||
**Sanitization:** Replaces non-alphanumeric characters (except `-` and `_`) with `-`
|
||||
|
||||
### readJsonSafe(filePath, schema)
|
||||
|
||||
- Returns parsed & validated data or `null`
|
||||
- Safe for missing files, invalid JSON, schema violations
|
||||
|
||||
### writeJsonAtomic(filePath, data)
|
||||
|
||||
- Atomic write via temp file + rename
|
||||
- Creates parent directories automatically
|
||||
- Cleans up temp file on error
|
||||
|
||||
### acquireLock(dirPath)
|
||||
|
||||
- File-based lock: `.lock` file with timestamp
|
||||
- 30-second stale threshold
|
||||
- Returns `{ acquired: boolean, release: () => void }`
|
||||
|
||||
## TESTING
|
||||
|
||||
**types.test.ts** (8 tests):
|
||||
- Valid status enum values
|
||||
- Required vs optional fields
|
||||
- Array validation (blocks, blockedBy)
|
||||
- Schema rejection for invalid data
|
||||
|
||||
**storage.test.ts** (14 tests):
|
||||
- Path construction
|
||||
- Safe JSON reading (missing files, invalid JSON, schema failures)
|
||||
- Atomic writes (directory creation, overwrites)
|
||||
- Lock acquisition (fresh locks, stale locks, release)
|
||||
|
||||
## USAGE
|
||||
|
||||
```typescript
|
||||
import { TaskSchema, getTaskDir, readJsonSafe, writeJsonAtomic, acquireLock } from "./features/claude-tasks"
|
||||
|
||||
const taskDir = getTaskDir(config)
|
||||
const lock = acquireLock(taskDir)
|
||||
|
||||
try {
|
||||
const task = readJsonSafe(join(taskDir, "1.json"), TaskSchema)
|
||||
if (task) {
|
||||
task.status = "completed"
|
||||
writeJsonAtomic(join(taskDir, "1.json"), task)
|
||||
}
|
||||
} finally {
|
||||
lock.release()
|
||||
}
|
||||
```
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `getTaskDir(config)` | Returns task storage directory path |
|
||||
| `resolveTaskListId(config)` | Resolves task list ID (env → config → cwd basename) |
|
||||
| `readJsonSafe(path, schema)` | Parse + validate, returns null on failure |
|
||||
| `writeJsonAtomic(path, data)` | Atomic write via temp file + rename |
|
||||
| `acquireLock(dirPath)` | File-based lock with 30s stale threshold |
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
41 lifecycle hooks intercepting/modifying agent behavior across 5 events.
|
||||
40+ lifecycle hooks intercepting/modifying agent behavior across 5 events.
|
||||
|
||||
**Event Types**:
|
||||
- `UserPromptSubmit` (`chat.message`) - Can block
|
||||
@@ -14,10 +14,10 @@
|
||||
## STRUCTURE
|
||||
```
|
||||
hooks/
|
||||
├── atlas/ # Main orchestration (757 lines)
|
||||
├── atlas/ # Main orchestration (770 lines)
|
||||
├── anthropic-context-window-limit-recovery/ # Auto-summarize
|
||||
├── todo-continuation-enforcer.ts # Force TODO completion
|
||||
├── ralph-loop/ # Self-referential dev loop
|
||||
├── todo-continuation-enforcer.ts # Force TODO completion (517 lines)
|
||||
├── ralph-loop/ # Self-referential dev loop (428 lines)
|
||||
├── claude-code-hooks/ # settings.json compat layer - see AGENTS.md
|
||||
├── comment-checker/ # Prevents AI slop
|
||||
├── auto-slash-command/ # Detects /command patterns
|
||||
@@ -27,13 +27,14 @@ hooks/
|
||||
├── edit-error-recovery/ # Recovers from failures
|
||||
├── thinking-block-validator/ # Ensures valid <thinking>
|
||||
├── context-window-monitor.ts # Reminds of headroom
|
||||
├── session-recovery/ # Auto-recovers from crashes
|
||||
├── session-recovery/ # Auto-recovers from crashes (436 lines)
|
||||
├── session-notification.ts # Session event notifications (337 lines)
|
||||
├── think-mode/ # Dynamic thinking budget
|
||||
├── keyword-detector/ # ultrawork/search/analyze modes
|
||||
├── background-notification/ # OS notification
|
||||
├── prometheus-md-only/ # Planner read-only mode
|
||||
├── agent-usage-reminder/ # Specialized agent hints
|
||||
├── auto-update-checker/ # Plugin update check
|
||||
├── auto-update-checker/ # Plugin update check (304 lines)
|
||||
├── tool-output-truncator.ts # Prevents context bloat
|
||||
├── compaction-context-injector/ # Injects context on compaction
|
||||
├── delegate-task-retry/ # Retries failed delegations
|
||||
@@ -47,6 +48,11 @@ hooks/
|
||||
├── sisyphus-junior-notepad/ # Sisyphus Junior notepad
|
||||
├── stop-continuation-guard/ # Guards stop continuation
|
||||
├── subagent-question-blocker/ # Blocks subagent questions
|
||||
├── task-reminder/ # Task progress reminders
|
||||
├── tasks-todowrite-disabler/ # Disables TodoWrite when task system active
|
||||
├── unstable-agent-babysitter/ # Monitors unstable agent behavior
|
||||
├── write-existing-file-guard/ # Guards against overwriting existing files
|
||||
├── preemptive-compaction.ts # Preemptive context compaction
|
||||
└── index.ts # Hook aggregation + registration
|
||||
```
|
||||
|
||||
@@ -61,8 +67,8 @@ hooks/
|
||||
|
||||
## EXECUTION ORDER
|
||||
- **UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
|
||||
- **PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → atlasHook
|
||||
- **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo
|
||||
- **PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → atlasHook
|
||||
- **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder
|
||||
|
||||
## HOW TO ADD
|
||||
1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)`
|
||||
|
||||
@@ -4,12 +4,12 @@
|
||||
|
||||
Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands.
|
||||
|
||||
**Config Sources** (priority): `.claude/settings.json` (project) > `~/.claude/settings.json` (global)
|
||||
**Config Sources** (priority): `.claude/settings.local.json` > `.claude/settings.json` (project) > `~/.claude/settings.json` (global)
|
||||
|
||||
## STRUCTURE
|
||||
```
|
||||
claude-code-hooks/
|
||||
├── index.ts # Main factory (401 lines)
|
||||
├── index.ts # Main factory (421 lines)
|
||||
├── config.ts # Loads ~/.claude/settings.json
|
||||
├── config-loader.ts # Extended config (disabledHooks)
|
||||
├── pre-tool-use.ts # PreToolUse executor
|
||||
@@ -19,6 +19,7 @@ claude-code-hooks/
|
||||
├── pre-compact.ts # PreCompact executor
|
||||
├── transcript.ts # Tool use recording
|
||||
├── tool-input-cache.ts # Pre→post input caching
|
||||
├── todo.ts # Todo integration
|
||||
└── types.ts # Hook & IO type definitions
|
||||
```
|
||||
|
||||
@@ -31,22 +32,16 @@ claude-code-hooks/
|
||||
| Stop | Session idle/end | Inject | sessionId, parentSessionId, cwd |
|
||||
| PreCompact | Before summarize | No | sessionId, cwd |
|
||||
|
||||
## CONFIG SOURCES
|
||||
Priority (highest first):
|
||||
1. `.claude/settings.local.json` (Project-local, git-ignored)
|
||||
2. `.claude/settings.json` (Project)
|
||||
3. `~/.claude/settings.json` (Global user)
|
||||
|
||||
## HOOK EXECUTION
|
||||
- **Matchers**: Hooks filter by tool name or event type via regex/glob.
|
||||
- **Commands**: Executed via subprocess with env vars (`$SESSION_ID`, `$TOOL_NAME`).
|
||||
- **Matchers**: Hooks filter by tool name or event type via regex/glob
|
||||
- **Commands**: Executed via subprocess with env vars (`$SESSION_ID`, `$TOOL_NAME`)
|
||||
- **Exit Codes**:
|
||||
- `0`: Pass (Success)
|
||||
- `1`: Warn (Continue with system message)
|
||||
- `2`: Block (Abort operation/prompt)
|
||||
|
||||
## ANTI-PATTERNS
|
||||
- **Heavy PreToolUse**: Runs before EVERY tool; keep logic light to avoid latency.
|
||||
- **Blocking non-critical**: Prefer PostToolUse warnings for non-fatal issues.
|
||||
- **Direct state mutation**: Use `updatedInput` in PreToolUse instead of side effects.
|
||||
- **Ignoring Exit Codes**: Ensure scripts return `2` to properly block sensitive tools.
|
||||
- **Heavy PreToolUse**: Runs before EVERY tool; keep logic light to avoid latency
|
||||
- **Blocking non-critical**: Prefer PostToolUse warnings for non-fatal issues
|
||||
- **Direct state mutation**: Use `updatedInput` in PreToolUse instead of side effects
|
||||
- **Ignoring Exit Codes**: Ensure scripts return `2` to properly block sensitive tools
|
||||
|
||||
@@ -14,7 +14,7 @@ Tier 1 of three-tier MCP system: 3 built-in remote HTTP MCPs.
|
||||
```
|
||||
mcp/
|
||||
├── index.ts # createBuiltinMcps() factory
|
||||
├── websearch.ts # Exa AI web search
|
||||
├── websearch.ts # Exa AI / Tavily web search
|
||||
├── context7.ts # Library documentation
|
||||
├── grep-app.ts # GitHub code search
|
||||
├── types.ts # McpNameSchema
|
||||
@@ -26,26 +26,16 @@ mcp/
|
||||
| Name | URL | Purpose | Auth |
|
||||
|------|-----|---------|------|
|
||||
| websearch | mcp.exa.ai / mcp.tavily.com | Real-time web search | EXA_API_KEY / TAVILY_API_KEY |
|
||||
| context7 | mcp.context7.com/mcp | Library docs | CONTEXT7_API_KEY |
|
||||
| context7 | mcp.context7.com/mcp | Library docs | CONTEXT7_API_KEY (optional) |
|
||||
| grep_app | mcp.grep.app | GitHub code search | None |
|
||||
|
||||
## THREE-TIER MCP SYSTEM
|
||||
|
||||
1. **Built-in** (this directory): websearch, context7, grep_app
|
||||
2. **Claude Code compat**: `.mcp.json` with `${VAR}` expansion
|
||||
3. **Skill-embedded**: YAML frontmatter in skills (handled by skill-mcp-manager)
|
||||
|
||||
## Websearch Provider Configuration
|
||||
|
||||
The `websearch` MCP supports multiple providers. Exa is the default for backward compatibility and works without an API key.
|
||||
|
||||
| Provider | URL | Auth | API Key Required |
|
||||
|----------|-----|------|------------------|
|
||||
| exa (default) | mcp.exa.ai | x-api-key header | No (optional) |
|
||||
| tavily | mcp.tavily.com | Authorization Bearer | Yes |
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"websearch": {
|
||||
@@ -54,17 +44,6 @@ The `websearch` MCP supports multiple providers. Exa is the default for backward
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- `EXA_API_KEY`: Optional. Used when provider is `exa`.
|
||||
- `TAVILY_API_KEY`: Required when provider is `tavily`.
|
||||
|
||||
### Priority and Behavior
|
||||
|
||||
- **Default**: Exa is used if no provider is specified.
|
||||
- **Backward Compatibility**: Existing setups using `EXA_API_KEY` continue to work without changes.
|
||||
- **Validation**: Selecting `tavily` without providing `TAVILY_API_KEY` will result in a configuration error.
|
||||
|
||||
## CONFIG PATTERN
|
||||
|
||||
```typescript
|
||||
@@ -77,15 +56,6 @@ export const mcp_name = {
|
||||
}
|
||||
```
|
||||
|
||||
## USAGE
|
||||
|
||||
```typescript
|
||||
import { createBuiltinMcps } from "./mcp"
|
||||
|
||||
const mcps = createBuiltinMcps() // Enable all
|
||||
const mcps = createBuiltinMcps(["websearch"]) // Disable specific
|
||||
```
|
||||
|
||||
## HOW TO ADD
|
||||
|
||||
1. Create `src/mcp/my-mcp.ts`
|
||||
@@ -96,6 +66,5 @@ const mcps = createBuiltinMcps(["websearch"]) // Disable specific
|
||||
|
||||
- **Remote only**: HTTP/SSE, no stdio
|
||||
- **Disable**: User can set `disabled_mcps: ["name"]` in config
|
||||
- **Context7**: Optional auth using `CONTEXT7_API_KEY` env var
|
||||
- **Exa**: Optional auth using `EXA_API_KEY` env var
|
||||
- **Exa**: Default provider, works without API key
|
||||
- **Tavily**: Requires `TAVILY_API_KEY` env var
|
||||
|
||||
@@ -9,12 +9,14 @@
|
||||
## STRUCTURE
|
||||
```
|
||||
shared/
|
||||
├── tmux/ # Tmux TUI integration (types, utils, constants)
|
||||
├── tmux/ # Tmux TUI integration (types, utils 312 lines, constants)
|
||||
├── logger.ts # File-based logging (/tmp/oh-my-opencode.log) - 53 imports
|
||||
├── dynamic-truncator.ts # Token-aware context window management (194 lines)
|
||||
├── model-resolver.ts # 3-step resolution (Override → Fallback → Default)
|
||||
├── model-requirements.ts # Agent/category model fallback chains (162 lines)
|
||||
├── model-availability.ts # Provider model fetching & fuzzy matching (154 lines)
|
||||
├── model-availability.ts # Provider model fetching & fuzzy matching (357 lines)
|
||||
├── model-sanitizer.ts # Model name sanitization
|
||||
├── model-suggestion-retry.ts # Model suggestion on failure
|
||||
├── jsonc-parser.ts # JSONC parsing with comment support
|
||||
├── frontmatter.ts # YAML frontmatter extraction (JSON_SCHEMA only) - 9 imports
|
||||
├── data-path.ts # XDG-compliant storage resolution
|
||||
@@ -22,16 +24,26 @@ shared/
|
||||
├── claude-config-dir.ts # ~/.claude resolution - 9 imports
|
||||
├── migration.ts # Legacy config migration logic (231 lines)
|
||||
├── opencode-version.ts # Semantic version comparison
|
||||
├── permission-compat.ts # Agent tool restriction enforcement
|
||||
├── system-directive.ts # Unified system message prefix & types
|
||||
├── permission-compat.ts # Agent tool restriction enforcement - 6 imports
|
||||
├── system-directive.ts # Unified system message prefix & types - 8 imports
|
||||
├── session-utils.ts # Session cursor, orchestrator detection
|
||||
├── session-cursor.ts # Session message cursor tracking
|
||||
├── shell-env.ts # Cross-platform shell environment
|
||||
├── agent-variant.ts # Agent variant from config
|
||||
├── zip-extractor.ts # Binary/Resource ZIP extraction
|
||||
├── deep-merge.ts # Recursive object merging (proto-pollution safe, MAX_DEPTH=50)
|
||||
├── case-insensitive.ts # Case-insensitive object lookups
|
||||
├── session-cursor.ts # Session message cursor tracking
|
||||
├── command-executor.ts # Shell command execution (225 lines)
|
||||
├── snake-case.ts # Case conversion utilities
|
||||
├── tool-name.ts # Tool naming conventions
|
||||
├── pattern-matcher.ts # Pattern matching utilities
|
||||
├── port-utils.ts # Port management
|
||||
├── file-utils.ts # File operation utilities
|
||||
├── file-reference-resolver.ts # File reference resolution
|
||||
├── connected-providers-cache.ts # Provider caching
|
||||
├── external-plugin-detector.ts # Plugin detection
|
||||
├── first-message-variant.ts # Message variant types
|
||||
├── opencode-server-auth.ts # Authentication utilities
|
||||
└── index.ts # Barrel export for all utilities
|
||||
```
|
||||
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
20+ tools across 7 categories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent).
|
||||
25+ tools across 8 categories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent).
|
||||
|
||||
**Categories**: LSP (6), AST-Grep (2), Search (2), Session (4), Agent delegation (2), Background (2), Skill (3)
|
||||
**Categories**: LSP (6), AST-Grep (2), Search (2), Session (4), Task (4), Agent delegation (2), Background (2), Skill (3), System (2)
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
@@ -15,20 +15,20 @@ tools/
|
||||
│ ├── tools.ts # ToolDefinition or factory
|
||||
│ ├── types.ts # Zod schemas
|
||||
│ └── constants.ts # Fixed values
|
||||
├── lsp/ # 6 tools: definition, references, symbols, diagnostics, rename (client.ts 540 lines)
|
||||
├── lsp/ # 6 tools: definition, references, symbols, diagnostics, rename (client.ts 803 lines)
|
||||
├── ast-grep/ # 2 tools: search, replace (25 languages)
|
||||
├── delegate-task/ # Category-based routing (1135 lines)
|
||||
├── delegate-task/ # Category-based routing (executor.ts 983 lines, constants.ts 552 lines)
|
||||
├── task/ # 4 tools: create, get, list, update (Claude Code compatible)
|
||||
├── session-manager/ # 4 tools: list, read, search, info
|
||||
├── grep/ # Custom grep with timeout (60s, 10MB)
|
||||
├── glob/ # 60s timeout, 100 file limit
|
||||
├── interactive-bash/ # Tmux session management
|
||||
├── look-at/ # Multimodal PDF/image
|
||||
├── look-at/ # Multimodal PDF/image (307 lines)
|
||||
├── skill/ # Skill execution
|
||||
├── skill-mcp/ # Skill MCP operations
|
||||
├── slashcommand/ # Slash command dispatch
|
||||
├── call-omo-agent/ # Direct agent invocation
|
||||
└── background-task/ # background_output, background_cancel
|
||||
├── call-omo-agent/ # Direct agent invocation (358 lines)
|
||||
└── background-task/ # background_output, background_cancel (734 lines)
|
||||
```
|
||||
|
||||
## TOOL CATEGORIES
|
||||
@@ -49,13 +49,9 @@ tools/
|
||||
Claude Code compatible task management.
|
||||
|
||||
- **task_create**: Creates a new task. Auto-generates ID and syncs to Todo.
|
||||
- Args: `subject`, `description`, `activeForm`, `blocks`, `blockedBy`, `owner`, `metadata`
|
||||
- **task_get**: Retrieves a task by ID.
|
||||
- Args: `id`
|
||||
- **task_list**: Lists active tasks. Filters out completed/deleted by default.
|
||||
- Args: `status`, `parentID`
|
||||
- **task_update**: Updates task fields. Supports additive `addBlocks`/`addBlockedBy`.
|
||||
- Args: `id`, `subject`, `description`, `status`, `activeForm`, `addBlocks`, `addBlockedBy`, `owner`, `metadata`
|
||||
|
||||
## HOW TO ADD
|
||||
|
||||
|
||||
Reference in New Issue
Block a user