AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-03-02 -->
3 
4# src
5 
6TypeScript source code for oh-my-claudecode - the core library that powers multi-agent orchestration.
7 
8## Purpose
9 
10This directory contains all TypeScript source code organized into modules:
11 
12- **agents/** - 32 specialized AI agent definitions with tiered variants
13- **tools/** - 15 LSP/AST/REPL tools for IDE-like capabilities
14- **hooks/** - 31 event-driven behaviors for execution modes
15- **features/** - Core features (model routing, state management, verification)
16- **config/** - Configuration loading and validation
17- **commands/** - Command expansion utilities
18- **mcp/** - MCP server integration
19 
20## Key Files
21 
22| File | Description |
23|------|-------------|
24| `index.ts` | Main entry point - exports `createOmcSession()` |
25| `shared/types.ts` | Shared TypeScript types used across modules |
26 
27## Subdirectories
28 
29| Directory | Purpose |
30|-----------|---------|
31| `agents/` | 32 agent definitions with prompts and tools (see `agents/AGENTS.md`) |
32| `tools/` | 15 LSP, AST, and Python REPL tools (see `tools/AGENTS.md`) |
33| `hooks/` | 31 hooks for execution modes (see `hooks/AGENTS.md`) |
34| `features/` | Core features like model routing, state (see `features/AGENTS.md`) |
35| `config/` | Configuration loading (`loader.ts`) |
36| `commands/` | Command expansion utilities |
37| `mcp/` | MCP server configuration and team runtime convergence helpers |
38| `cli/` | CLI entry points and command surfaces |
39| `hud/` | Heads-up display components |
40| `installer/` | Installation system |
41| `__tests__/` | Test files |
42 
43## For AI Agents
44 
45### Working In This Directory
46 
471. **Module Organization**: Each major feature has its own directory with:
48   - `index.ts` - Main exports
49   - `types.ts` - TypeScript interfaces
50   - Supporting files as needed
51 
522. **Entry Point Pattern**:
53```typescript
54   // Main export in index.ts
55   export { createOmcSession } from './session';
56   export { lspTools, astTools, allCustomTools } from './tools';
57   export { getAgentDefinitions, omcSystemPrompt } from './agents/definitions';
58```
59 
603. **Tool Registration**: Custom tools are registered in `tools/index.ts`:
61 
62```typescript
63   export const allCustomTools = [
64     ...lspTools,      // 12 LSP tools
65     ...astTools,      // 2 AST tools
66     pythonReplTool    // 1 REPL tool (15 total)
67   ];
68```
69 
704. **Agent Registration**: Agents defined in `agents/definitions.ts`:
71```typescript
72   export function getAgentDefinitions(): Record<string, AgentConfig> {
73     return {
74       architect: architectAgent,
75       executor: executorAgent,
76       // ... all 32 agents
77     };
78   }
79```
80 
81### Testing Requirements
82 
83- Test files are in `__tests__/` with pattern `*.test.ts`
84- Run `npm test -- --grep "module-name"` for specific modules
85- Verify type safety with `npm run build` after changes
86- Use `lsp_diagnostics_directory` tool for project-wide type checking
87 
88### Common Patterns
89 
90#### Creating a New Agent
91 
921. Add agent file in `agents/` (e.g., `new-agent.ts`)
932. Export from `agents/index.ts`
943. Add to `getAgentDefinitions()` in `agents/definitions.ts`
954. Create prompt template in `/agents/new-agent.md`
965. Update `docs/REFERENCE.md` (Agents section) with new agent
97 
98#### Adding a New Hook
99 
1001. Create directory in `hooks/` (e.g., `new-hook/`)
1012. Add `index.ts`, `types.ts`, `constants.ts`
1023. Export from `hooks/index.ts`
1034. Update `docs/REFERENCE.md` (Hooks System section) with new hook
104 
105#### Adding a New Tool
106 
1071. Create tool definition with Zod schema
1082. Add to appropriate tools file (`lsp-tools.ts`, `ast-tools.ts`)
1093. Export from `tools/index.ts`
1104. Update `docs/REFERENCE.md` if user-facing tool
111 
112#### Adding a New Feature
113 
1141. Create feature directory in `features/`
1152. Export from `features/index.ts`
1163. Update `docs/FEATURES.md` with API documentation
117 
118#### TypeScript Conventions
119 
120- Use strict mode (`noImplicitAny`, `strictNullChecks`)
121- Prefer interfaces over type aliases for public APIs
122- Use barrel exports (`index.ts`) for each module
123- File size: 200-400 lines typical, 800 max
124- Use Zod for runtime input validation (see `templates/rules/coding-style.md`)
125 
126## Dependencies
127 
128### Internal
129- Uses types from `shared/types.ts`
130- Imports agent prompts from `/agents/*.md`
131- Loads skills from `/skills/*.md`
132 
133### External
134 
135Key packages by module: `zod` (tools, features), `@ast-grep/napi` (tools/ast), `vscode-languageserver-protocol` (tools/lsp), `better-sqlite3` (hooks/swarm), `chalk` (cli, hud). See root AGENTS.md for full dependency list.
136 
137### MCP Runtime Notes
138 
139- Team MCP runtime status/wait behavior is implemented in `mcp/team-server.ts`.
140- Shared team-job convergence helpers (artifact-first status convergence, scoped team-state cleanup) live in `mcp/team-job-convergence.ts`.
141 
142## Module Dependency Graph
143 
144```
145index.ts
146├── agents/definitions.ts → agents/*.ts → /agents/*.md (prompts)
147├── tools/index.ts
148│   ├── lsp-tools.ts → lsp/*.ts
149│   ├── ast-tools.ts
150│   └── python-repl/
151├── hooks/index.ts → hooks/*/*.ts
152├── features/index.ts
153│   ├── model-routing/
154│   ├── boulder-state/
155│   ├── verification/
156│   └── ...
157├── config/loader.ts
158└── mcp/servers.ts
159```
160 
161<!-- MANUAL: -->
162