Commands

workscribe init

Set up Workscribe and install or update shell hooks.

workscribe init

Safe to re-run at any time — installs missing hooks, updates outdated ones, and skips everything already up to date. What it does:

Creates ~/.workscribe/ with owner-only permissions
Initialises the SQLite database
Installs or updates the shell hook in ~/.zshrc or ~/.bashrc
Detects installed AI coding tools (Claude Code, Aider, etc.) and offers to install a session capture hook for each — opt-in, defaults to no
Prompts you to choose an AI provider and enter your API key

Shell hook updates: When a new version of Workscribe ships with an updated hook, re-running workscribe init detects the change and prompts you to update. Your rc file is backed up before any modification.

workscribe summary

Generate an AI work summary for today or a specific date.

workscribe summary
workscribe summary --date 2026-05-20
workscribe summary --week
workscribe summary --fresh
workscribe summary --slack
workscribe summary --webhook <url>

Option	Description
`--date <YYYY-MM-DD>`	Summarise a specific date instead of today
`--week`	Summarise Mon–today for the current week
`--fresh`	Bypass cache and regenerate the summary
`--verbose`	Show all captured events (including those not sent to AI) before generating the summary
`--slack`	Post the summary to your configured Slack webhook
`--webhook <url>`	Post the summary to a custom webhook URL

Slack setup:

Go to api.slack.com/apps → Create New App → From scratch
Name your app, select your workspace, and click Create App
In the left sidebar under Features, click Incoming Webhooks
Toggle Activate Incoming Webhooks to On
Click Add New Webhook to Workspace, choose a channel, and click Allow
Copy the webhook URL and configure workscribe:

workscribe config set integrations.slackWebhook https://hooks.slack.com/services/...

Works on all Slack plans including free. No admin role required — any workspace member can create an app. Then run workscribe summary --slack to post. The summary is automatically formatted for Slack — headings are bolded and bullets are converted to •. Your OS username is prepended to the message so recipients know who sent it in shared channels. Output format:

## project-name (branch) — 2h 15m
- Implemented auth middleware and JWT validation
- Resolved failing test suite
- Committed fixes and pushed to remote

Each session gets its own heading. The heading is always generated from your captured data — project name, branch, and duration — not from the AI. Caching:

Daily summaries are cached per session in the database
Cached summaries are preserved when new events arrive — only new or unsummarised sessions call the AI
Weekly summaries are cached in ~/.workscribe/weekly-cache/<YYYY-WW>.md
Use --fresh to force regeneration of all sessions for the day

workscribe week

Generate an AI weekly digest covering Monday through today.

workscribe week
workscribe week --fresh
workscribe week --slack
workscribe week --webhook <url>

Option	Description
`--fresh`	Bypass cache and regenerate the digest
`--slack`	Post the digest to your configured Slack webhook
`--webhook <url>`	Post the digest to a custom webhook URL

The natural pre-standup ritual for Monday morning or end-of-week reporting. Output is markdown grouped by day, with each session summarised under its project and branch. Caching: Results are cached in ~/.workscribe/weekly-cache/<YYYY-WW>.md. Running workscribe week a second time in the same week returns the cached digest instantly. Use --fresh to force regeneration. Slack: Configure your webhook first:

workscribe config set integrations.slackWebhook https://hooks.slack.com/services/...

Then run workscribe week --slack to post. See workscribe summary for full Slack setup instructions.

workscribe sessions

List detected work sessions for a date.

workscribe sessions
workscribe sessions --date 2026-05-20

Option	Description
`--date <YYYY-MM-DD>`	Show sessions for a specific date

Sessions are computed by grouping events with idle gaps greater than session.idleTimeout (default 30 minutes) and splitting across different repositories.

workscribe events

List raw captured events for a date.

workscribe events
workscribe events --date 2026-05-20
workscribe events --limit 20

Option	Description
`--date <YYYY-MM-DD>`	Show events for a specific date
`--limit <n>`	Limit the number of events shown

Events are colour-coded by category:

Category	Colour	Examples
`code_commit`, `code_push`, `code_merge`	green	`git commit`, `git push`
`code_pull`, `branch_switch`, `code_stash`	blue	`git pull`, `git checkout`
`test_run`	magenta	`npm test`, `npx vitest`, `pytest`
`build`	cyan	`npm run build`, `npx tsc`, `cargo build`
`dependency_install`, `dependency_remove`, `file_ops`	yellow	`npm install`, `rm`, `mkdir`
`lint_run`	yellow	`npx eslint`, `npx prettier`
`server_run`	cyan	`npm run dev`, `yarn start`
`infrastructure`	red	`kubectl`, `docker`, `terraform`
`script_run`	white	`npx husky`, `bash deploy.sh`
`ai_session`	bold magenta	Claude Code, Cursor, Copilot
`code_search`, `code_read`	dim	`grep`, `cat`, `find`
`environment`, `git_other`, `other`	gray	`export`, `git status`

workscribe note

Attach a free-text annotation to the current session.

workscribe note "Fixed race condition in auth middleware"
workscribe note "Blocked by infra outage — picked up again after lunch"

The note is stored as an event in the database, timestamped now, and associated with the current git repo and branch. It groups into whatever session covers its timestamp when sessions are rebuilt. Where notes appear:

workscribe sessions — displayed indented under the matching session
workscribe summary and workscribe week — injected into the AI prompt before the event list so the model reads your context first, and uses it to explain the why behind the work

Removing a note: Notes are events. Use workscribe undo to remove the most recently added note.

workscribe undo

Remove the last N captured events.

workscribe undo
workscribe undo -n 5
workscribe undo --dry-run
workscribe undo -n 3 --dry-run

Option	Description
`-n, --count <number>`	Number of events to remove (default: 1)
`--dry-run`	Preview what would be deleted without deleting

Notes:

Removes events from the database only — does not modify any exported markdown files
Automatically invalidates sessions for affected dates so they rebuild on next access
Running undo twice is safe — the second call removes the next N events

workscribe clear

Delete all captured events for a date.

workscribe clear
workscribe clear --date 2026-05-20
workscribe clear --dry-run
workscribe clear --yes

Option	Description
`--date <YYYY-MM-DD>`	Date to clear (default: today)
`--dry-run`	Preview what would be deleted without deleting
`--yes`	Skip the confirmation prompt

Notes:

Shows a category summary before asking for confirmation
Automatically invalidates cached sessions for the date
Use --dry-run to see what would be removed before committing

workscribe export

Generate a summary and save it as a markdown file.

workscribe export
workscribe export --date 2026-05-20
workscribe export --output ~/Desktop/standup.md

Option	Description
`--date <YYYY-MM-DD>`	Export a specific date
`--output <path>`	Custom output path (default: `~/.workscribe/exports/workscribe-<date>.md`)

workscribe context

Surface the last session for the current repo — at the moment you need it, not at end of day.

workscribe context
workscribe context --file src/auth.ts
workscribe context --file src/auth.ts --json

Option	Description
`--file <path>`	Show the last session that touched this file (requires IDE integration)
`--json`	Output structured JSON instead of formatted text — `null` when no session is found

Without --file: shows the most recent session for the current git repo — date, duration, branch, event count, and the AI-generated summary if one exists. With --file: narrows to the most recent session that included a code_edit event for that path. This is what powers the VS Code extension’s status bar “last worked on” indicator — surfacing “3 days ago” when you switch to a file you haven’t touched recently. Neovim and other editor integrations aren’t built yet. If no summary exists for the session, the default text output includes the command to generate one:

  No summary — run: workscribe summary 2026-08-25

--json output shape, intended for IDE integrations that need to render this themselves rather than parse formatted text:

{
  "date": "2026-08-20",
  "startedAt": "2026-08-20T10:00:00.000Z",
  "endedAt": "2026-08-20T12:14:00.000Z",
  "timeAgo": "3 days ago",
  "durationMinutes": 134,
  "branch": "feature/auth",
  "eventCount": 42,
  "summary": "Implemented authentication middleware." // or null if no summary has been generated yet
}

Prints the bare JSON value null (not an object) when no matching session exists.

workscribe status

Show capture status and event counts.

workscribe status

Output includes:

Whether capture is active or paused
Number of events captured today and total
Last captured event
Configured AI provider and model
Pending security alerts count (if any)

workscribe alerts

Show and manage security alerts raised when Workscribe detects a possible credential in an AI tool prompt.

workscribe alerts          # list all pending alerts
workscribe alerts clear    # dismiss all pending alerts

When credentials are detected in a prompt sent to an AI tool (e.g. Claude Code), Workscribe:

Stores the alert in the local database.
Writes a signal file to ~/.workscribe/alerts.pending.
Displays a one-line warning before your next shell prompt.
Injects a systemMessage into Claude’s context for that turn.

The clear subcommand marks all alerts as dismissed and removes the signal file.

workscribe pause / resume

Pause and resume capture.

workscribe pause
workscribe resume

When paused, the shell hook still fires but events are silently discarded. Useful when sharing your screen or running sensitive commands you don’t want journaled.

workscribe uninstall

Remove shell hooks and optionally delete all Workscribe data.

workscribe uninstall
workscribe uninstall --hooks-only

Option	Description
`--hooks-only`	Remove shell hooks only — skip the data deletion prompt

What it does:

Detects and removes the Workscribe hook block from ~/.zshrc, ~/.bashrc, and ~/.bash_profile
Prompts whether to delete ~/.workscribe/ (database, config, exports) — defaults to no
Prints the command to remove the CLI itself (npm uninstall -g @workscribe/cli)

After running: The hook is removed from your rc file but remains active in your current shell session. Either restart your terminal or run:

source ~/.zshrc   # or ~/.bashrc

If you’ve already removed the binary and still see _workscribe_precmd errors, remove the hook block manually:

Open ~/.zshrc (or ~/.bashrc)
Delete everything between # workscribe:hook:start and # workscribe:hook:end (inclusive)
Run source ~/.zshrc or restart your terminal

workscribe _capture (IDE integration)

Internal command called by shell hooks and IDE plugins. Not intended for direct use. IDE integrations call this to record a file-save or debug event without going through the shell:

workscribe _capture --type code_edit --file src/auth.ts --source vscode --cwd /path/to/repo
workscribe _capture --type debug_start --source neovim --cwd /path/to/repo
workscribe _capture --type task_run --source vscode --cwd /path/to/repo

Option	Description
`--cmd <command>`	Shell command (shell hook only)
`--cwd <path>`	Working directory (required)
`--type <type>`	Event type — skips normalization. One of: `code_edit`, `debug_start`, `debug_end`, `task_run`
`--source <source>`	Event source identifier (e.g. `vscode`, `neovim`, `jupyter`)
`--file <path>`	File path for `code_edit` events
`--exit <code>`	Exit code (shell hook only)
`--duration <ms>`	Duration in milliseconds (shell hook only)

Deduplication: code_edit events for the same file within 30 seconds are dropped. This absorbs rapid auto-saves without creating duplicate records.

workscribe config

View and update configuration.

workscribe config
workscribe config set <key> <value>
workscribe config get <key>

Examples:

workscribe config set ai.provider anthropic
workscribe config set ai.apiKey sk-...
workscribe config set ai.model claude-haiku-4-5-20251001
workscribe config set session.idleTimeout 20
workscribe config set redact.extra "MY_SECRET_PATTERN"
workscribe config set integrations.slackWebhook https://hooks.slack.com/services/...
workscribe config set projects./Users/me/sandbox/myrepo actual-repo-name

Sensitive value masking: workscribe config get and workscribe config mask API keys, tokens, and webhook URLs — showing only the first four characters and the total length:

sk-a******** (51 chars)

This confirms a value is set without exposing it in your terminal history. See Configuration for the full config reference.

Getting Started

Reference

Trust & Safety

Support

Commands

Commands

workscribe init

workscribe summary

workscribe week

workscribe sessions

workscribe events

workscribe note

workscribe undo

workscribe clear

workscribe export

workscribe context

workscribe status

workscribe alerts

workscribe pause / resume

workscribe uninstall

workscribe _capture (IDE integration)

workscribe config

​Commands

​workscribe init

​workscribe summary

​workscribe week

​workscribe sessions

​workscribe events

​workscribe note

​workscribe undo

​workscribe clear

​workscribe export

​workscribe context

​workscribe status

​workscribe alerts

​workscribe pause / resume

​workscribe uninstall

​workscribe _capture (IDE integration)

​workscribe config

Commands

workscribe init

workscribe summary

workscribe week

workscribe sessions

workscribe events

workscribe note

workscribe undo

workscribe clear

workscribe export

workscribe context

workscribe status

workscribe alerts

workscribe pause / resume

workscribe uninstall

workscribe _capture (IDE integration)

workscribe config