Files

YeonGyu-Kim d9ab6ab99b docs: update AGENTS.md hierarchy with latest structure and line counts

- Root: Add Prometheus/Metis/Momus agents, MCP architecture, 82 test files
- agents/: Document 7-section delegation and wisdom notepad
- auth/: Multi-account load balancing (10 accounts), endpoint fallback
- features/: Update background-agent 825 lines, builtin-skills 1230 lines
- hooks/: 22+ hooks with event timing details
- tools/: sisyphus-task 583 lines, LSP client 632 lines
- cli/: config-manager 725 lines, 17+ doctor checks
- shared/: Cross-cutting utilities with usage patterns

2026-01-13 21:00:00 +09:00

2.3 KiB

Raw Blame History

SHARED UTILITIES KNOWLEDGE BASE

OVERVIEW

Cross-cutting utilities for path resolution, config management, text processing, and Claude Code compatibility.

STRUCTURE

shared/
├── index.ts              # Barrel export
├── claude-config-dir.ts  # ~/.claude resolution
├── command-executor.ts   # Shell exec with variable expansion
├── config-errors.ts      # Global error tracking
├── config-path.ts        # User/project config paths
├── data-path.ts          # XDG data directory
├── deep-merge.ts         # Type-safe recursive merge
├── dynamic-truncator.ts  # Token-aware truncation
├── file-reference-resolver.ts  # @filename syntax
├── file-utils.ts         # Symlink, markdown detection
├── frontmatter.ts        # YAML frontmatter parsing
├── hook-disabled.ts      # Check if hook disabled
├── jsonc-parser.ts       # JSON with Comments
├── logger.ts             # File-based logging
├── migration.ts          # Legacy name compat (omo → Sisyphus)
├── model-sanitizer.ts    # Normalize model names
├── pattern-matcher.ts    # Tool name matching
├── snake-case.ts         # Case conversion
└── tool-name.ts          # PascalCase normalization

WHEN TO USE

Task	Utility
Find ~/.claude	`getClaudeConfigDir()`
Merge configs	`deepMerge(base, override)`
Parse user files	`parseJsonc()`
Check hook enabled	`isHookDisabled(name, list)`
Truncate output	`dynamicTruncate(text, budget)`
Resolve @file	`resolveFileReferencesInText()`
Execute shell	`resolveCommandsInText()`
Legacy names	`migrateLegacyAgentNames()`

CRITICAL PATTERNS

// Dynamic truncation with context budget
const output = dynamicTruncate(result, remainingTokens, 0.5)

// Config resolution priority
const final = deepMerge(deepMerge(defaults, userConfig), projectConfig)

// Safe JSONC parsing for user-edited files
const { config, error } = parseJsoncSafe(content)

ANTI-PATTERNS

Hardcoding paths (use getClaudeConfigDir, getUserConfigPath)
Using JSON.parse for user configs (always use parseJsonc)
Ignoring output size (large tool outputs MUST use dynamicTruncate)
Manual case conversion (use toSnakeCase, normalizeToolName)

2.3 KiB Raw Blame History

SHARED UTILITIES KNOWLEDGE BASE

OVERVIEW

STRUCTURE

WHEN TO USE

CRITICAL PATTERNS

ANTI-PATTERNS

2.3 KiB

Raw Blame History