diff --git a/.claude/commands/weather-karachi.md b/.claude/commands/weather-karachi.md index ebeff1e..5784e84 100644 --- a/.claude/commands/weather-karachi.md +++ b/.claude/commands/weather-karachi.md @@ -9,6 +9,7 @@ Fetch the current temperature for Karachi, Pakistan and apply transformations. ## Workflow + 1. Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit 2. Use the weather-fetcher agent to retrieve the current temperature from wttr.in API in the requested unit 3. Use the weather-transformer agent to read transformation rules from input/input.md and apply them to the temperature diff --git a/.claude/settings.json b/.claude/settings.json index 259aaef..7cffb3c 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,4 +1,23 @@ { + "permissions": { + "allow": [ + "Edit(*)", + "Write(*)", + "NotebookEdit(*)", + "Bash", + "WebFetch(domain:*)", + "WebSearch", + "mcp__*", + "mcp__ide__*", + "mcp__chrome-devtools__*", + "mcp__claude-in-chrome__*", + "mcp__playwright__*" + ], + "deny": [], + "ask": [] + }, + "plansDirectory": "./ralph-wiggum/plans", + "enableAllProjectMcpServers": true, "disableAllHooks": false, "hooks": { "PreToolUse": [ @@ -6,7 +25,19 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 + } + ] + } + ], + "PermissionRequest": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 } ] } @@ -16,7 +47,8 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 } ] } @@ -26,7 +58,8 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 } ] } @@ -36,7 +69,8 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 } ] } @@ -46,7 +80,19 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 + } + ] + } + ], + "SubagentStart": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 } ] } @@ -56,7 +102,8 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000 } ] } @@ -66,7 +113,9 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000, + "once": true } ] } @@ -76,7 +125,9 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000, + "once": true } ] } @@ -86,10 +137,23 @@ "hooks": [ { "type": "command", - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh" + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 5000, + "once": true + } + ] + } + ], + "Setup": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py", + "timeout": 30000 } ] } ] } -} \ No newline at end of file +} diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index 2cc4e68..0000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "permissions": { - "allow": [ - "WebFetch(domain:wttr.in)", - "WebSearch", - "SlashCommand(/weather)", - "Bash(cat:*)" - ], - "deny": [], - "ask": [] - } -} diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..d4cfb41 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"] + }, + "reddit-mcp-server": { + "type": "http", + "url": "http://144.91.76.33:8080/mcp" + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fb2a1ec --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,57 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is a best practices repository for Claude Code configuration, demonstrating patterns for agents, commands, hooks, and skills. It serves as a reference implementation rather than an application codebase. + +## Key Components + +### Weather System (Example Workflow) +A demonstration of agent orchestration: +- `/weather` command delegates to `/weather-karachi` +- `weather-fetcher` agent: fetches temperature from wttr.in API +- `weather-transformer` agent: applies transformation rules from `input/input.md`, writes results to `output/output.md` + +Agents run sequentially, not in parallel, to maintain data dependencies. + +### Hooks System +Cross-platform sound notification system in `.claude/hooks/`: +- `scripts/hooks.py`: Main handler for all 9 Claude Code hooks +- `config/hooks-config.json`: Shared team configuration +- `config/hooks-config.local.json`: Personal overrides (git-ignored) +- `sounds/`: Audio files organized by hook event + +Special handling: git commits trigger `pretooluse-git-committing` sound. + +## Critical Patterns + +### Agent Orchestration +Agents **cannot** invoke other agents via bash commands. Use the Task tool: +``` +Task(subagent_type="agent-name", description="...", prompt="...", model="haiku") +``` + +Be explicit about tool usage in agent definitions. Avoid vague terms like "launch" that could be misinterpreted as bash commands. + +### Agent Definition Structure +Agents in `.claude/agents/*.md` use YAML frontmatter: +- `name`: Agent identifier +- `description`: When to invoke (use "PROACTIVELY" for auto-invocation) +- `tools`: Comma-separated list of allowed tools +- `model`: Typically "haiku" for efficiency +- `color`: CLI output color for visual distinction + +### Configuration Hierarchy +1. `.claude/settings.local.json`: Personal settings (git-ignored) +2. `.claude/settings.json`: Team-shared settings +3. `hooks-config.local.json` overrides `hooks-config.json` + +### Disable Hooks +Set `"disableAllHooks": true` in `.claude/settings.local.json`, or disable individual hooks in `hooks-config.json`. + +## Documentation + +- `docs/AGENTS.md`: Agent orchestration troubleshooting +- `docs/WEATHER.md`: Weather system flow diagram diff --git a/README.md b/README.md index 3f3bfaf..b983071 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,20 @@ your best ai assistant with the best practice ## CONCEPTS -- **[Agents](https://docs.claude.com/en/docs/claude-code/agents)** - Specialized subprocesses that autonomously handle complex, multi-step tasks -- **[Commands](https://docs.claude.com/en/docs/claude-code/slash-commands)** - Custom slash commands to extend Claude Code with reusable prompts -- **[Memory](https://docs.claude.com/en/docs/claude-code/memory)** - Persistent context that Claude remembers across conversations -- **[Hooks](https://docs.claude.com/en/docs/claude-code/hooks)** - Shell commands that execute in response to events like tool calls -- **[Skills](https://docs.claude.com/en/docs/claude-code/skills)** - Installable capabilities that add specialized functionality to Claude Code -- **[Settings](https://docs.claude.com/en/docs/claude-code/settings)** - Hierarchical configuration system for Claude Code behavior -- **[MCP Servers](https://docs.claude.com/en/docs/claude-code/mcp)** - Model Context Protocol for connecting to external tools, databases, and APIs -- **[Plugins](https://docs.claude.com/en/docs/claude-code/plugins)** - Extensible packages that bundle commands, agents, skills, hooks, and MCP servers -- **[Rules](https://docs.claude.com/en/docs/claude-code/memory#project-rules)** - Modular topic-specific instructions in `.claude/rules/*.md` -- **[Output Styles](https://docs.claude.com/en/docs/claude-code/output-styles)** - Custom system prompt modifications for different use cases -- **[Permissions](https://docs.claude.com/en/docs/claude-code/permissions)** - Fine-grained access control for tools and operations +> **Note:** Custom slash commands have been merged into skills. Files in `.claude/commands/` still work, but skills (`.claude/skills/`) are recommended as they support additional features like supporting files, invocation control, and subagent execution. + +- **[Skills](https://code.claude.com/docs/en/skills)** - Reusable knowledge, workflows, and slash commands that Claude can load on-demand or you invoke with `/skill-name` +- **[Subagents](https://code.claude.com/docs/en/sub-agents)** - Isolated execution contexts that run their own loops and return summarized results +- **[Memory](https://code.claude.com/docs/en/memory)** - Persistent context via CLAUDE.md files and `@path` imports that Claude sees every session +- **[Rules](https://code.claude.com/docs/en/memory#modular-rules-with-clauderules)** - Modular topic-specific instructions in `.claude/rules/*.md` with optional path-scoping via frontmatter +- **[Hooks](https://code.claude.com/docs/en/hooks)** - Deterministic scripts that run outside the agentic loop on specific events +- **[MCP Servers](https://code.claude.com/docs/en/mcp)** - Model Context Protocol connections to external tools, databases, and APIs +- **[Plugins](https://code.claude.com/docs/en/plugins)** - Distributable packages that bundle skills, subagents, hooks, and MCP servers +- **[Marketplaces](https://code.claude.com/docs/en/discover-plugins)** - Host and discover plugin collections +- **[Settings](https://code.claude.com/docs/en/settings)** - Hierarchical configuration system for Claude Code behavior +- **[Permissions](https://code.claude.com/docs/en/iam)** - Fine-grained access control for tools and operations + +**Extension Overview:** See [Extend Claude Code](https://code.claude.com/docs/en/features-overview) for when to use each feature and how they layer together. ## LESSON LEARNED diff --git a/output/output.md b/output/output.md index 41f394e..c932910 100644 --- a/output/output.md +++ b/output/output.md @@ -1,26 +1,3 @@ -# Weather Transformation Results - -**Original Temperature:** 309.15 K (Kelvin) - -**Conversion to Celsius:** 309.15 K - 273.15 = 36°C - -**Transformation Applied:** Add +10 to the result - -**Calculation:** 36°C + 10 = 46°C - -**Final Result in Celsius:** 46°C - -**Final Result in Kelvin:** 319.15 K - -## Detailed Summary - -- Input: 309.15 K -- Intermediate (Celsius): 36°C -- After Transformation: 46°C -- Output: 319.15 K - -## Calculation Details - -- Starting value: 309.15 K (equal to 36°C) -- Operation: Add +10 -- Result: 36 + 10 = 46°C (equal to 319.15 K) +Original Temperature: 22°C +Transformation Applied: add +10 in the result +Final Result: 32°C