docs(agents): regenerate all AGENTS.md files with comprehensive codebase analysis
- Regenerated root AGENTS.md with overview, structure, and complexity hotspots
- Regenerated all 7 subdirectory AGENTS.md files: hooks, tools, features, agents, cli, auth, shared
- Used 11 background explore agents for comprehensive feature and architecture analysis
- All files within size limits (root: 112 lines, subdirs: 57-68 lines)
- Includes where-to-look guide, conventions, anti-patterns, and agent model information
🤖 Generated with assistance of oh-my-opencode
This commit is contained in:
YeonGyu-Kim
@@ -2,85 +2,65 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Lifecycle hooks that intercept/modify agent behavior. Inject context, enforce rules, recover from errors, notify on events.
|
||||
22 lifecycle hooks intercepting/modifying agent behavior. Context injection, error recovery, output control, notifications.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
hooks/
|
||||
├── agent-usage-reminder/ # Remind to use specialized agents
|
||||
├── anthropic-context-window-limit-recovery/ # Auto-compact Claude at token limit
|
||||
├── auto-slash-command/ # Auto-detect and execute /command patterns
|
||||
├── auto-update-checker/ # Version update notifications
|
||||
├── background-notification/ # OS notify on background task complete
|
||||
├── claude-code-hooks/ # Claude Code settings.json integration
|
||||
├── anthropic-context-window-limit-recovery/ # Auto-compact at token limit (554 lines)
|
||||
├── auto-slash-command/ # Detect and execute /command patterns
|
||||
├── auto-update-checker/ # Version notifications, startup toast
|
||||
├── background-notification/ # OS notify on task complete
|
||||
├── claude-code-hooks/ # settings.json PreToolUse/PostToolUse/etc
|
||||
├── comment-checker/ # Prevent excessive AI comments
|
||||
│ ├── filters/ # Filtering rules (docstring, directive, bdd, etc.)
|
||||
│ └── output/ # Output formatting
|
||||
├── compaction-context-injector/ # Inject context during compaction
|
||||
├── directory-agents-injector/ # Auto-inject AGENTS.md files
|
||||
├── directory-readme-injector/ # Auto-inject README.md files
|
||||
│ └── filters/ # docstring, directive, bdd, etc
|
||||
├── compaction-context-injector/ # Preserve context during compaction
|
||||
├── directory-agents-injector/ # Auto-inject AGENTS.md
|
||||
├── directory-readme-injector/ # Auto-inject README.md
|
||||
├── empty-message-sanitizer/ # Sanitize empty messages
|
||||
├── interactive-bash-session/ # Tmux session management
|
||||
├── keyword-detector/ # Detect ultrawork/search keywords
|
||||
├── non-interactive-env/ # CI/headless environment handling
|
||||
├── preemptive-compaction/ # Pre-emptive session compaction
|
||||
├── ralph-loop/ # Self-referential dev loop until completion
|
||||
├── keyword-detector/ # ultrawork/search keyword activation
|
||||
├── non-interactive-env/ # CI/headless handling
|
||||
├── preemptive-compaction/ # Pre-emptive at 85% usage
|
||||
├── ralph-loop/ # Self-referential dev loop
|
||||
├── rules-injector/ # Conditional rules from .claude/rules/
|
||||
├── session-recovery/ # Recover from session errors
|
||||
├── session-recovery/ # Recover from errors (430 lines)
|
||||
├── think-mode/ # Auto-detect thinking triggers
|
||||
├── thinking-block-validator/ # Validate thinking blocks in messages
|
||||
├── context-window-monitor.ts # Monitor context usage (standalone)
|
||||
├── empty-task-response-detector.ts
|
||||
├── session-notification.ts # OS notify on idle (standalone)
|
||||
├── todo-continuation-enforcer.ts # Force TODO completion (standalone)
|
||||
└── tool-output-truncator.ts # Truncate verbose outputs (standalone)
|
||||
├── agent-usage-reminder/ # Remind to use specialists
|
||||
├── context-window-monitor.ts # Monitor usage (standalone)
|
||||
├── session-notification.ts # OS notify on idle
|
||||
├── todo-continuation-enforcer.ts # Force TODO completion
|
||||
└── tool-output-truncator.ts # Truncate verbose outputs
|
||||
```
|
||||
|
||||
## HOOK CATEGORIES
|
||||
|
||||
| Category | Hooks | Purpose |
|
||||
|----------|-------|---------|
|
||||
| Context Injection | directory-agents-injector, directory-readme-injector, rules-injector, compaction-context-injector | Auto-inject relevant context |
|
||||
| Session Management | session-recovery, anthropic-context-window-limit-recovery, preemptive-compaction, empty-message-sanitizer | Handle session lifecycle |
|
||||
| Output Control | comment-checker, tool-output-truncator | Control agent output quality |
|
||||
| Notifications | session-notification, background-notification, auto-update-checker | OS/user notifications |
|
||||
| Behavior Enforcement | todo-continuation-enforcer, keyword-detector, think-mode, agent-usage-reminder | Enforce agent behavior |
|
||||
| Environment | non-interactive-env, interactive-bash-session, context-window-monitor | Adapt to runtime environment |
|
||||
| Compatibility | claude-code-hooks | Claude Code settings.json support |
|
||||
|
||||
## HOW TO ADD A HOOK
|
||||
|
||||
1. Create directory: `src/hooks/my-hook/`
|
||||
2. Create files:
|
||||
- `index.ts`: Export `createMyHook(input: PluginInput)`
|
||||
- `constants.ts`: Hook name constant
|
||||
- `types.ts`: TypeScript interfaces (optional)
|
||||
- `storage.ts`: Persistent state (optional)
|
||||
3. Return event handlers: `{ PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }`
|
||||
4. Export from `src/hooks/index.ts`
|
||||
5. Register in main plugin
|
||||
|
||||
## HOOK EVENTS
|
||||
|
||||
| Event | Timing | Can Block | Use Case |
|
||||
|-------|--------|-----------|----------|
|
||||
| PreToolUse | Before tool exec | Yes | Validate, modify input |
|
||||
| PostToolUse | After tool exec | No | Add context, warnings |
|
||||
| UserPromptSubmit | On user prompt | Yes | Inject messages, block |
|
||||
| PreToolUse | Before tool | Yes | Validate, modify input |
|
||||
| PostToolUse | After tool | No | Add context, warnings |
|
||||
| UserPromptSubmit | On prompt | Yes | Inject messages, block |
|
||||
| Stop | Session idle | No | Inject follow-ups |
|
||||
| onSummarize | During compaction | No | Preserve critical context |
|
||||
| onSummarize | Compaction | No | Preserve context |
|
||||
|
||||
## COMMON PATTERNS
|
||||
## HOW TO ADD
|
||||
|
||||
- **Storage**: Use `storage.ts` with JSON file for persistent state across sessions
|
||||
- **Once-per-session**: Track injected paths in Set to avoid duplicate injection
|
||||
- **Message injection**: Return `{ messages: [...] }` from event handlers
|
||||
- **Blocking**: Return `{ blocked: true, message: "reason" }` from PreToolUse
|
||||
1. Create `src/hooks/my-hook/`
|
||||
2. Files: `index.ts` (createMyHook), `constants.ts`, `types.ts` (optional)
|
||||
3. Return: `{ PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }`
|
||||
4. Export from `src/hooks/index.ts`
|
||||
|
||||
## ANTI-PATTERNS (HOOKS)
|
||||
## PATTERNS
|
||||
|
||||
- **Heavy computation** in PreToolUse: Slows every tool call
|
||||
- **Blocking without clear reason**: Always provide actionable message
|
||||
- **Duplicate injection**: Track what's already injected per session
|
||||
- **Ignoring errors**: Always try/catch, log failures, don't crash session
|
||||
- **Storage**: JSON file for persistent state across sessions
|
||||
- **Once-per-session**: Track injected paths in Set
|
||||
- **Message injection**: Return `{ messages: [...] }`
|
||||
- **Blocking**: Return `{ blocked: true, message: "..." }` from PreToolUse
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
- Heavy computation in PreToolUse (slows every tool call)
|
||||
- Blocking without actionable message
|
||||
- Duplicate injection (track what's injected)
|
||||
- Missing try/catch (don't crash session)
|
||||
|
||||
Reference in New Issue
Block a user