claude-report

English | 日本語

claude-report

A Claude Code plugin that gives engineering managers real-time visibility into developer activity through Slack — without interrupting developers.

Overview

claude-report integrates with Claude Code to provide two layers of visibility:

1. Real-time activity log — hooks automatically detect git commits, pushes, PR creation, test failures, and task completions, posting compact log entries to a daily Slack thread
2. End-of-day summary — parses Claude Code transcript files to generate per-project usage stats and AI-written summaries of what was accomplished

The plugin also surfaces manager feedback: replies on Slack threads are automatically injected into the developer's next Claude Code session.

Scope: claude-report covers Claude Code (CLI) only. The Claude desktop app's Cowork / agent mode stores its sessions under ~/Library/Application Support/Claude/local-agent-mode-sessions/ and does not run Claude Code hooks, so Cowork activity and token usage are not included in the activity log or the daily summary.

Team Rollout

claude-report is designed to be rolled out to a whole engineering team so every developer's daily activity and 19:00 usage summary land in one shared channel. The flow splits into a one-time setup by a team lead and a ~2-minute install per teammate.

Team Lead — one-time setup

1. Create the shared Slack app

Go to api.slack.com/apps, create an app from manifest, paste slack-app-manifest.json. Install to your workspace; copy the Bot User OAuth Token (xoxb-…). Invite the bot into the channel where daily reports should land (/invite @Claude Report).

The team shares one bot token + one channel. Per-user threading is handled inside the plugin (thread per git-email-hash), so there's no per-user app setup.

2. Publish the plugin to a marketplace

Push this repo to a public (or org-internal) GitHub repo and keep .claude-plugin/marketplace.json at the root.

3. Share the install instructions

Send teammates the block below with the bot token and channel ID filled in.

Teammate — install (~2 minutes)

# 1. Register the marketplace (one-time)
/plugin marketplace add knorq-ai/claude-report

# 2. Install the plugin
/plugin install claude-report@claude-report-marketplace

Claude Code prompts for three values at install:

Prompt	Value
Slack Bot Token	xoxb-… (from the team lead)
Slack Channel ID	Channel ID, e.g. C0AS7LC0X9B (from the team lead)
Display Name	Your name as shown in Slack posts

Then reload and set up the daily schedule:

/reload-plugins
/install-daily-report
/verify

/install-daily-report writes a launchd plist and loads it (macOS). /verify runs nine checks (Slack auth, channel membership, plist, launchd job loaded, wrapper executable, dist built, claude on PATH). If all green, your daily 19:00 report is live and will survive reboots.

If any check fails, the output includes the exact remediation. Common ones:

• auth.test: invalid_auth → bot token pasted wrong; rerun /plugin config claude-report.
• chat.postMessage: not_in_channel → bot isn't in the channel; /invite @Claude Report in Slack.
• claude on PATH (login shell): not resolvable → ensure claude is in /usr/local/bin or /opt/homebrew/bin (or set CLAUDE_BIN in the plist).

Opting a repo out

echo > .claude-report.ignore in any project root. The file is honored by both the real-time activity log and the 19:00 usage report (tokens, prompts, and estimated cost from opted-out projects are stripped from the Slack header, not just the per-project breakdown).

Updating

When the team lead ships a new version:

/plugin marketplace update claude-report-marketplace
/plugin update claude-report
/reload-plugins
/install-daily-report   # refresh the plist with the new wrapper/paths

Linux teammates

/install-daily-report is macOS-only today. On Linux, create a systemd timer that runs $CLAUDE_PLUGIN_ROOT/bin/daily-usage-wrapper.sh at 18:57 local with CLAUDE_REPORT_PLUGIN_DIR, CLAUDE_REPORT_DATA_DIR=$HOME/.claude-report, and CLAUDE_BIN exported. See bin/daily-usage-wrapper.sh for the expected contract.

What survives /plugin uninstall

The durable config and state live at ~/.claude-report/ (config.json, state/, logs/). Plugin-data ($CLAUDE_PLUGIN_DATA) is wiped by /plugin uninstall. /install-daily-report migrates $CLAUDE_PLUGIN_DATA/config.json → ~/.claude-report/config.json on first run so teammates who configured via /plugin keep their Slack creds across reinstalls.

How It Works

Real-Time Activity Log

Hooks fire on every Bash and TaskUpdate tool call. Detected events are posted as compact log entries to a single daily thread per user: