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

.claude/settings.local.json: Personal settings (git-ignored)
.claude/settings.json: Team-shared settings
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

2.2 KiB Raw Blame History