Claude Code Commands & Hooks: Performance Boost Guide

This is probably one of the most “underrated” features in Claude Code, basically because people often don’t have any idea how to use them. Let’s take a look at my ideas.

What are Commands?

Commands are a way to quickly send your pre-made prompt templates.

Unlike CLAUDE.md or AGENTS.md which are “System Prompts,” commands are “User Prompts,” giving them much more weight and priority in processing.

For example, if you find yourself writing the same prompts repeatedly, you can now package them into a command and call it quickly with /<command-name>.

How to create Commands

It’s very simple. Create a Markdown file in ~/.claude/commands with the following structure:

---
description: Describe this command
---

Write your prompt here

$ARGUMENTS

You can use this command in all your projects with /<command-name>. If you only want to create a command for the current project you’re working on, simply create it in ./.claude/commands.

(*) $ARGUMENTS is the value following the command, inserted at the specified position (e.g., /fix Default language error).

Pro Tip:

In my first “Subagents” article, I mentioned that “Commands” are the best way to summon Subagents when needed. Therefore, we can create detailed and clear workflows within each command to customize them according to our needs, suitable for different specific tasks.

For example: fix-ci.md

---
description: Read, analyze, debug, and fix failed Github Actions tests
---

Read, analyze, debug, and fix failed Github Actions tests:

$ARGUMENTS

Process:
- Use “debugger” agent to read and analyze Github Actions logs
- Use “planner” agent to plan fixes
- Use “tester” agent to test fixes, ensuring all test suites pass

I’m a bit lazy with this article today 😅, and there’s not much more to say about “Commands,” so I’ll just share a list of the commands I’ve created for use in Claude Code.

I’ve also put all my command files in [this repo](link to repo), along with all the optimized Subagent setups I’m currently using. Feel free to use them if you need! (If you have any feedback or improvement ideas, please contribute directly to the repo!)

Actually, I was “inspired” (a fancy way of saying “borrowed ideas”) from other people’s repos. One of the repos I found quite useful for those using Claude Code is: https://github.com/mrgoonie/claude-code-setup - everyone should check it out!

List of commands I use:

`/ask`

Use this command to ask anything about the codebase.

---
description: Answer technical and architectural questions.
---
## Context
- Technical question or architecture challenge: $ARGUMENTS
- Relevant system documentation and design artifacts will be referenced using @ file syntax.
- Current system constraints, scale requirements, and business context will be considered.

## Your Role
You are a Senior Systems Architect providing expert consultation and architectural guidance. You focus on high-level design, strategic decisions, and architectural patterns rather than implementation details. You orchestrate four specialized architectural advisors:
1. **Systems Designer** – evaluates system boundaries, interfaces, and component interactions.
2. **Technology Strategist** – recommends technology stacks, frameworks, and architectural patterns.
3. **Scalability Consultant** – assesses performance, reliability, and growth considerations.
4. **Risk Analyst** – identifies potential issues, trade-offs, and mitigation strategies.

## Process
1. **Problem Understanding**: Analyze the technical question and gather architectural context.
2. **Expert Consultation**:
   - Systems Designer: Define system boundaries, data flows, and component relationships
   - Technology Strategist: Evaluate technology choices, patterns, and industry best practices
   - Scalability Consultant: Assess non-functional requirements and scalability implications
   - Risk Analyst: Identify architectural risks, dependencies, and decision trade-offs
3. **Architecture Synthesis**: Combine insights to provide comprehensive architectural guidance.
4. **Strategic Validation**: Ensure recommendations align with business goals and technical constraints.

## Output Format
1. **Architecture Analysis** – comprehensive breakdown of the technical challenge and context.
2. **Design Recommendations** – high-level architectural solutions with rationale and alternatives.
3. **Technology Guidance** – strategic technology choices with pros/cons analysis.
4. **Implementation Strategy** – phased approach and architectural decision framework.
5. **Next Actions** – strategic next steps, proof-of-concepts, and architectural validation points.

## Important
This command focuses on architectural consultation and strategic guidance. Do not start implementing anything.

`/cook`

In my system prompt, I already have 3 important parts of the workflow for working with subagents: Core Responsibilities, Subagents Team and Development Rules. Call this command to implement a feature or fix a complex bug that requires the entire team of agents.

---
description: Implement a feature
---
Strictly follow your Core Responsibilities, Subagents Team and Development Rules.
Start implementing this task: 
 $ARGUMENTS

`/fix`

For small bugs that need quick fixes, just use this command for convenience.

---
description: Analyze and fix the issue [FAST]
---
Analyze and fix this issue:
<issue>
$ARGUMENTS
</issue>

`/fix-test`

Run the test suite on my machine (local) to check the results. If there are failed tests, do everything to make them pass, repeat until death :)) pass, repeat until death :))

---
description: Run test flows and fix issues
---
## Reported Issues
 $ARGUMENTS

First use the `debugger` subagent and `tester` subagent to find the root cause of the issues, then analyze the reports and implement the fix. Repeat this process until all issues are addressed.

After finish, delegate to `code-reviewer` agent to review code.

`/test`

Run the test suite on my machine (local) to check the results, then report back the execution direction.

---
description: Debugging technical issues and providing solutions.
---
Use the `tester` subagent to run tests locally and analyze the summary report.

`/refactor`

Typically, “refactoring” is a rather complex and... dangerous process. Therefore, I need more strict guidance (I only describe the main ideas, the rest is generated using Meta Prompt with Claude Desktop).

---
description: Refactoring technical debt and improving code quality.
---
Refactoring scope/target: $ARGUMENTS

## Context
- Existing test coverage and dependencies will be preserved.

## Your Role
You are the Refactoring Coordinator orchestrating four refactoring specialists:
1. **Structure Analyst** – evaluates current architecture and identifies improvement opportunities.
2. **Code Surgeon** – performs precise code transformations while preserving functionality.
3. **Design Pattern Expert** – applies appropriate patterns for better maintainability.
4. **Quality Validator** – ensures refactoring improves code quality without breaking changes.

## Process
1. **Current State Analysis**: Use `planner-researcher` agent to map existing code structure, dependencies, and technical debt, and provide the comprehensive implementation plan.
2. **Refactoring Strategy**:
   - Structure Analyst: Identify coupling issues, complexity hotspots, and architectural smells
   - Code Surgeon: Plan safe transformation steps with rollback strategies
   - Design Pattern Expert: Recommend patterns that improve extensibility and testability
   - Quality Validator: Establish quality gates and regression prevention measures
   - Risk Management: Identify and mitigate risks associated with refactoring
3. **Incremental Transformation**: Design step-by-step refactoring with validation points.
4. **Quality Assurance**: Use `code-reviewer` agent and `tester` agent to Verify improvements in maintainability, readability, and testability.

## Output Format
1. **Refactoring Assessment** – current issues and improvement opportunities.
2. **Transformation Plan** – step-by-step refactoring strategy with risk mitigation.
3. **Implementation Guide** – concrete code changes with before/after examples.
4. **Validation Strategy** – testing approach to ensure functionality preservation.
5. **Next Actions** – monitoring plan and future refactoring opportunities.

**IMPORTANT:** Ask the user for confirmation on the refactoring plan before start implementation.

`/debug`

Activate the “debugger” agent to find the root cause of a problem, then report back (do not execute, I need to review it first!).

---
description: Debugging technical issues and providing solutions.
---
**Reported Issues**:
 $ARGUMENTS

Use the `debugger` subagent to find the root cause of the issues, then analyze and explain the reports to the user.
**Do not implement the fix automatically.**

`/watzup`

During vibe coding, I found this command quite useful for myself, because AI writes the code, not me. So when I come back the next day or in 2-3 days, I almost can’t remember what I did recently, and what I should do next. This command helps review the latest commits, documents in ./docs, and summarizes it for me.

---
description: Review recent changes and wrap up the work
---
Review my current branch and the most recent commits. 
Provide a detailed summary of all changes, including what was modified, added, or removed. 
Analyze the overall impact and quality of the changes.

I think using Commands like this can also be shared among team members, which is quite useful.

Hooks - what are they & what are they for?

Simply put, hooks are like the “automatic settings” you set in a game. Instead of hoping AI remembers to do something, you program it: “Every time you do X, you must do Y.” No negotiation, no “forgetting,” no “maybe” - it just runs.

In other words, if you understand how Webhooks work, then Hooks work similarly.

There are 8 main types of hooks:

UserPromptSubmit - Runs immediately when you send a query (before Claude processes it)
PreToolUse - Runs before Claude uses a tool (can block the tool)
PostToolUse - Runs after Claude finishes using a tool
Notification - Runs when Claude sends a notification
Stop - Runs when Claude completes a response
SubagentStop - Runs when a subagent completes a task
PreCompact - Runs before compaction
SessionStart - Runs when a session starts

Cases where I use hooks:

Send notifications upon completion of work Specifically, I will use a hook here for Claude Code to send notifications via Telegram when it finishes implementing something:

1/ Create a Telegram Bot:

Message /start to @BotFather

Use /newbot to create a new bot

Choose a username (must end with “bot”)

2/ Get Chat ID:

Message “hello” to the newly created bot

Go to https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

Copy chat_id from the JSON response

3/ Set environment variables:

export TELEGRAM_BOT_TOKEN=”123456789:ABCdefGHIjklMNOpqrsTUVwxyz”
export TELEGRAM_CHAT_ID=”987654321”

4/ Install hook: Once installed, the Hook will automatically activate! No additional commands are needed.

Now, every time Claude Code finishes a task, it will send a summary message to my Telegram to notify me. I just need to go back and review it.

TTS + Hook = Voice Assistant!

This is another interesting case study, turning Claude Code into a talking assistant 😁

The method is also simple.

First, your machine needs Python support (install it if you haven’t already).

1/ Setup hook:

Open ~/.claude/settings.json (or ./.claude/settings.json if you only want to configure for a single project)
Add this snippet:

{
  “$schema”: “https://json.schemastore.org/claude-code-settings.json”,
  “hooks”: {
    “Notification”: [
      {
        “matcher”: “”,
        “hooks”: [
          {
            “type”: “command”,
            “command”: “uv run ~/.claude/hooks/notification.py”
          }
        ]
      }
    ],
    “Stop”: [
      {
        “matcher”: “”,
        “hooks”: [
          {
            “type”: “command”,
            “command”: “uv run ~/.claude/hooks/stop.py”
          }
        ]
      }
    ]
  }
}

2/ Create the file ~/.claude/hooks/notification.py to play audio

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = “>=3.11”
# dependencies = [
#     “pyttsx3”,
# ]
# ///

import sys
import json
import pyttsx3
from typing import Dict, Any


def main() -> None:
    “”“Main function to handle Claude hook notifications.”“”
    try:
        input_data = sys.stdin.read().strip()
        if not input_data:
            print(”No data received from stdin”, file=sys.stderr)
            sys.exit(1)
        
        hook_data = json.loads(input_data)
        handle_notification(hook_data)
    except json.JSONDecodeError as e:
        print(f”Error parsing hook data: {e}”, file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f”Error handling notification: {e}”, file=sys.stderr)
        sys.exit(1)


def handle_notification(data: Dict[str, Any]) -> None:
    “”“Handle the notification with text-to-speech.”“”
    message = data.get(”message”, “Claude Code notification”)
    
    # Initialize TTS engine
    engine = pyttsx3.init()
    
    # Make it speak a bit slower so I can understand
    rate = engine.getProperty(’rate’)
    engine.setProperty(’rate’, rate - 50)
    
    # Actually speak the message
    engine.say(message)
    engine.runAndWait()
    
    print(f”Notification: {message}”)


if __name__ == “__main__”:
    main()

If you want Claude Code’s voice to sound better, you can use the ElevenLabs or OpenAI TTS API, but that costs money!

The Trick: “Hoisted by my own petard”

This is my “secret trick” for this article. Send Claude Code’s documentation (copy URL or Markdown) → prompt Claude Code to configure hooks.

Here are some ideas for you:

Read this doc: https://docs.anthropic.com/en/docs/claude-code/hooks-guide 
Then write me 3 hooks: 
1/ Auto-format Python code 
2/ Auto-commit with Git branches 
3/ Security Validation: Dangerous prompts are blocked before Claude can act on them

A few other tricks

There are many great resources on Claude Code for you to check out here: https://github.com/hesreallyhim/awesome-claude-code

If you don’t feel like it’s enough, or rather, you SHOULD check out this website/repo, because it has a lot of cool stuff!

[VC-05] Leverage “Commands & Hooks” to boost performance!