Claude Code Superuser

List all available commands. Run in every new environment.

Clear conversation history, start fresh context. Use when switching between unrelated tasks.

Summarize history into a compressed form, freeing context space while preserving key decisions. Essential for sessions over 30 min.

Show token usage and estimated cost for the current session.

Switch models mid-session. Upgrade to Opus for deep architecture work, back to Sonnet for implementation.

Auto-generate a CLAUDE.md for the current directory by analyzing your codebase. Start here on any new project.

List connected MCP servers and their available tools. Use to debug MCP connections.

Plan: Refactor our authentication module to use JWT refresh token rotation. 
Currently in src/auth/session.ts.

## Plan: JWT Refresh Token Rotation Refactor

1. Read src/auth/session.ts — understand current session implementation
2. Read src/middleware.ts — see how sessions are used in request handling  
3. Read src/api/auth/login.ts — understand current login flow
4. Check package.json for existing JWT libraries (jsonwebtoken, jose, etc.)

Then I'll implement:
5. Add refreshToken field to User model in src/types/user.ts
6. Create src/auth/tokens.ts — JWT generation, validation, rotation logic
7. Update src/auth/session.ts — integrate new token utilities, add rotation logic
8. Update src/middleware.ts — check token expiry, auto-refresh if within 5 min
9. Update src/api/auth/login.ts — return both access + refresh tokens
10. Add src/api/auth/refresh.ts — new endpoint for token refresh
11. Write tests in src/auth/__tests__/tokens.test.ts
12. Run npm test — verify no regressions

Estimated files changed: 6. New files: 2.

Shall I proceed? (yes to start, or tell me what to change)

"Skip step 4, I know we use 'jose'. Add a step to update the API docs in docs/auth.md. Proceed."

Claude incorporates your changes and starts executing — only after you approve.

You: Create a new branch for adding CSV export to the reports module.
      Follow our branch naming convention (feature/ticket-description).

Claude: 
$ git checkout -b feature/PROJ-142-csv-export-reports
Switched to a new branch 'feature/PROJ-142-csv-export-reports'

I've created branch feature/PROJ-142-csv-export-reports. Ready to start 
implementing — shall I read the reports module first to understand the 
existing structure?

You: Yes. Then add CSV export. The reports are in src/reports/.
      Use the existing data fetching pattern. Tests required.

Claude reads: src/reports/index.ts, src/reports/types.ts, src/utils/format.ts

Claude implements:
- src/reports/exporters/csv.ts (new)
- src/reports/index.ts (updated — adds export button)
- src/reports/__tests__/csv.test.ts (new)

Runs: npm test -- src/reports/__tests__/csv.test.ts
Result: 12 tests passed

You: Commit these changes. Use conventional commits format.

Claude:
$ git add src/reports/exporters/csv.ts src/reports/index.ts src/reports/__tests__/csv.test.ts
$ git commit -m "feat(reports): add CSV export functionality

- Implements CsvExporter class in src/reports/exporters/csv.ts
- Adds export button to report header component  
- Handles empty datasets, special characters, and large exports (>10k rows)
- Includes 12 unit tests covering happy path and edge cases

Closes PROJ-142"

[feature/PROJ-142-csv-export-reports 3a8f92c] feat(reports): add CSV export...

You: Push and create a GitHub PR. Write a complete description.

Claude:
$ git push -u origin feature/PROJ-142-csv-export-reports

Creating PR via GitHub MCP...
Title: feat(reports): CSV export for all report types

Description:
## What this PR does
Adds CSV export functionality to the reports module. Users can now 
download any report as a CSV file with one click.

## Changes
- New CsvExporter class handles formatting, escaping, and streaming
- Export button added to report header (only visible to users with export permission)
- Handles edge cases: empty reports, special chars in data, reports >10k rows

## Testing
- 12 unit tests added (all passing)
- Manual testing: exported 3 different report types, verified in Excel and Google Sheets
- Performance tested with 50k row dataset — exports in under 2 seconds

## How to test
1. Go to any report → click the new "Export CSV" button in the top right
2. Verify download starts immediately
3. Open CSV in your preferred spreadsheet app

Closes #142

PR created: https://github.com/your-org/your-repo/pull/287

Reviewer comment: "The CSV exporter should handle timezone conversion 
for date fields — currently outputting UTC."

You (to Claude): Fix the timezone issue the reviewer mentioned in PR #287.

Claude reads the review comment via GitHub MCP, finds the date formatting 
code in csv.ts, adds timezone conversion using the user's locale setting,
commits as "fix(reports): convert date fields to user timezone in CSV export",
pushes, and replies to the review comment with a summary of the fix.

{
  "hooks": {
    "notification": [
      {
        "command": "osascript -e 'display notification "Claude needs your attention" with title "Claude Code" sound name "Glass"'"
      }
    ]
  }
}

Now when Claude finishes a multi-step task and is waiting for you, your Mac plays a sound and shows a notification. Great for tasks you kick off and then switch away from.

{
  "hooks": {
    "post_tool_call": [
      {
        "matcher": { "tool_name": "write_file" },
        "command": "echo "$(date '+%Y-%m-%d %H:%M:%S') EDITED: $TOOL_INPUT_PATH" >> ~/claude-audit.log"
      },
      {
        "matcher": { "tool_name": "edit_file" },
        "command": "echo "$(date '+%Y-%m-%d %H:%M:%S') EDITED: $TOOL_INPUT_path" >> ~/claude-audit.log"
      }
    ]
  }
}

Creates ~/claude-audit.log with a timestamped entry every time Claude edits or creates a file. Check cat ~/claude-audit.log to see everything Claude has touched in a session.

{
  "hooks": {
    "post_tool_call": [
      {
        "matcher": {
          "tool_name": "write_file",
          "tool_input_contains": ".test.ts"
        },
        "command": "cd $(dirname $TOOL_INPUT_PATH) && npm test -- $(basename $TOOL_INPUT_PATH) --passWithNoTests 2>&1 | tail -20"
      }
    ]
  }
}

Every time Claude writes a .test.ts file, this hook automatically runs that specific test file and shows you the last 20 lines of output. You see test results immediately without asking Claude to run them.

Claude asks before running shell commands. You see exactly what will run and approve each. Best for client codebases and anything with real-world side effects.

Shell commands execute without confirmation. Much faster. Use for personal projects, prototypes, and scripts in controlled environments. Never use for production credentials or client data.

Add Trust: allow shell execution to your project's CLAUDE.md. Scoped only to that project. Commit this to git so the whole team gets the same trust level.

Include a "Key Files" section in your project CLAUDE.md. Example:

## Key Files
- src/auth/session.ts — session management, JWT handling
- src/middleware.ts — request pipeline, auth checks, rate limiting  
- src/api/index.ts — API router, all routes registered here
- src/db/schema.ts — Drizzle ORM schema, single source of truth for DB
- src/lib/email.ts — all email sending goes through here

Claude reads this first and navigates precisely without reading everything.

"Look at src/auth/session.ts line 45" is 10x faster than "find the session expiry logic." Use exact file paths in every request when you know where the code is.

Working on auth for 30 min, then switching to UI work? Run /compact first. Compresses the auth conversation into a summary, freeing context for the UI work without losing key decisions.

"Read src/auth/session.ts, src/middleware.ts, and src/types/user.ts. Then tell me where the session expiry logic is before touching anything." Gives Claude full context before it acts.