Documentation

Getting Started

Requirements

$ node --version

Install

$ npm install -g @workscribe/cli

Initialise

$ workscribe init

init will:

1. Create ~/.workscribe/ and initialise the local database
2. Detect your shell (zsh or bash) and install the capture hook
3. Walk you through choosing an AI provider

After init, activate the hook without restarting your terminal:

$ source ~/.zshrc   # or ~/.bashrc

Verify it's working

$ workscribe status

You should see Capture active and your configured AI provider. Run a few commands, then check:

$ workscribe events

Events should appear within seconds of running commands.

Generate your first summary

$ workscribe summary

workscribe groups your captured events into sessions and sends them to your AI provider, which returns a standup-ready narrative.

What gets captured

Every command you run in the terminal is intercepted by the shell hook, filtered, redacted, and stored locally. workscribe never stores:

• Raw file contents
• File paths
• Passwords, tokens, or API keys (stripped before writing to disk)
• Commands you've added to the ignore list

See Privacy & Security for full details.

Commands

$ workscribe init

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

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

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

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

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

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

$ workscribe status

$ workscribe pause
$ workscribe resume

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

$ 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

Configuration

Config is stored at ~/.workscribe/config.json with owner-only permissions (0600). Use workscribe config set <key> <value> to update any value. Nested keys use dot notation.

AI

Provider defaults:

$ workscribe config set ai.provider anthropic
$ workscribe config set ai.apiKey sk-ant-...
$ workscribe config set ai.model claude-sonnet-4-6

Session

$ workscribe config set session.idleTimeout 20

Capture

The default ignore list: cd, ls, ll, la, ls -la, ls -l, ls -a, pwd, clear, exit, history, man.

$ workscribe config set capture.ignore '["cd","ls","htop","top"]'

Redact

workscribe automatically redacts common secret patterns (tokens, API keys, passwords, JWTs). Use redact.extra to add custom patterns.

$ workscribe config set redact.extra '["MY_INTERNAL_TOKEN"]'

Summary

Projects

Override the display name for a repository whose local folder name differs from the actual project name.

$ workscribe config set projects./Users/me/sandbox/chronicle workscribe

Priority order for project name resolution:

1. Config override (this setting)
2. git remote get-url origin — extracts repo name from the remote URL
3. package.json name field (strips @scope/ prefix)
4. Folder name (fallback)

Integrations

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

Both keys are masked in workscribe config output for security.

Full example config

{
  "ai": {
    "provider": "anthropic",
    "apiKey": "sk-ant-...",
    "model": "claude-haiku-4-5-20251001",
    "baseUrl": ""
  },
  "session": {
    "idleTimeout": 30
  },
  "capture": {
    "ignore": ["cd", "ls", "ll", "la", "pwd", "clear", "exit", "history", "man"]
  },
  "redact": {
    "extra": []
  },
  "summary": {
    "format": "markdown"
  },
  "projects": {
    "/Users/me/sandbox/chronicle": "workscribe"
  },
  "integrations": {
    "slackWebhook": "https://hooks.slack.com/services/..."
  }
}

AI Providers

workscribe sends structured event data to your AI provider only when you explicitly run workscribe summary. It never sends raw commands, file contents, or file paths — only event categories and metadata.

Anthropic (Claude)

$ workscribe config set ai.provider anthropic
$ workscribe config set ai.apiKey sk-ant-...

Override the model:

$ workscribe config set ai.model claude-sonnet-4-6

Get an API key at console.anthropic.com.

OpenAI

$ workscribe config set ai.provider openai
$ workscribe config set ai.apiKey sk-...

Override the model:

$ workscribe config set ai.model gpt-4o

Get an API key at platform.openai.com.

Ollama (local)

Run AI summaries entirely on your machine — no API key, no external calls, fully offline.

$ workscribe config set ai.provider ollama

Requirements:

1. Install Ollama: ollama.com
2. Pull a model: ollama pull llama3
3. Start Ollama: ollama serve

Override the model:

$ workscribe config set ai.model mistral

OpenAI-compatible

Works with any endpoint that implements the OpenAI chat completions API — Groq, Together AI, Mistral, and others.

$ workscribe config set ai.provider openai-compatible
$ workscribe config set ai.apiKey <your-key>
$ workscribe config set ai.baseUrl https://api.groq.com/openai/v1
$ workscribe config set ai.model llama-3.1-70b-versatile

Switching providers

Switch at any time — existing summaries are cached in the database and unaffected:

$ workscribe config set ai.provider ollama

Troubleshooting

Privacy & Security

What stays local

Everything. All captured data is stored in ~/.workscribe/ on your machine. Nothing is written to any remote server except what you explicitly send to your AI provider when you run workscribe summary.

Both the database and config file are written with 0600 permissions (owner read/write only).

What gets redacted

Before any event is written to disk, workscribe strips sensitive patterns from the raw command string.

Automatically redacted:

• Bearer tokens (Bearer <token>)
• Authorization headers
• API keys and secrets in common formats
• Passwords passed as flags (--password, -p)
• JWT tokens
• Private keys

Add your own patterns:

$ workscribe config set redact.extra '["MY_INTERNAL_SECRET"]'

Redaction is applied as a regex replace — matched values are replaced with [REDACTED] before the command touches the database.

What is sent to your AI provider

Only when you run workscribe summary. Only structured event categories — never raw commands.

Sent:

Project: api-service
Branch: feature/auth
Duration: 2h 15m
Events:
  - 3x code_commit
  - 2x test_run [failed]
  - test_run
  - dependency_install {"tool":"npm","packages":["bcrypt"]}

Never sent:

• Raw command strings
• File paths or file contents
• Environment variables
• Credentials or tokens
• Hostnames or IP addresses

Using Ollama for full offline operation

If you want zero external data transmission, use Ollama — workscribe summary never makes an external network request. Everything runs on your machine.

$ workscribe config set ai.provider ollama

Pausing capture

To temporarily stop capturing — for example, when working with sensitive data or sharing your screen:

$ workscribe pause
# ... do sensitive work ...
$ workscribe resume

When paused, the shell hook still fires but all events are silently discarded before touching disk.

Removing your data

$ rm -rf ~/.workscribe

This removes the database, config, exports, and cache. The shell hook in your ~/.zshrc or ~/.bashrc will still fire but write nothing. To remove the hook, delete the block between # workscribe:hook:start and # workscribe:hook:end in your shell rc file.

Troubleshooting

Capture isn't working

Check status first:

$ workscribe status

If it shows Capture active but no events are appearing, the shell hook may not be loaded.

$ source ~/.zshrc   # or ~/.bashrc

Then run a command and check:

$ workscribe events

Enable debug mode to see what the capture process is doing:

$ WORKSCRIBE_DEBUG=1 workscribe status
$ cat ~/.workscribe/debug.log

Shell hook is not installed

If workscribe init didn't detect your shell or the hook is missing, re-run init — it's safe and skips steps already completed:

$ workscribe init

If you're using a non-standard shell (fish, nushell), the hook is not currently supported. You can manually trigger capture:

$ workscribe _capture --command "your command" --cwd "$PWD" --exit-code 0

Windows is not supported. The shell hook requires zsh or bash. If you're on Windows, use WSL2 with zsh or bash — workscribe works normally inside WSL2.

"No activity captured for today"

Either no events have been captured yet, or all commands ran were on the ignore list. Check:

$ workscribe events

If events exist but summary shows nothing, check the date:

$ workscribe summary --date $(date +%Y-%m-%d)

Summary looks wrong or generic

Wrong project name:

$ workscribe config set projects./full/path/to/repo correct-name

Bullet points are off-topic: Try --fresh to regenerate without cache:

$ workscribe summary --fresh

For local models (Ollama), try a larger model:

$ workscribe config set ai.model llama3:70b

"AI provider not configured"

$ workscribe config set ai.provider anthropic   # or openai, ollama
$ workscribe config set ai.apiKey <your-key>

Ollama: "connection refused"

$ ollama serve

And ensure the model is pulled:

$ ollama pull llama3

API key errors (401 / 403)

$ workscribe config get ai.apiKey

Reset it:

$ workscribe config set ai.apiKey <new-key>

Webhook not posting

Test your webhook URL directly:

$ curl -X POST <your-webhook-url> \
$   -H "Content-Type: application/json" \
$   -d '{"text":"test"}'

If that works but --slack doesn't, check the config:

$ workscribe config get integrations.slackWebhook

Database errors

If you see SQLite errors, the database may be corrupted. Back up first, then reinitialise — config is unaffected:

# Back up first
$ cp ~/.workscribe/workscribe.db ~/.workscribe/workscribe.db.bak

# Delete and reinitialise
$ rm ~/.workscribe/workscribe.db
$ workscribe status   # triggers reinitialisation

Uninstalling

$ npm uninstall -g @workscribe/cli
$ rm -rf ~/.workscribe

Then remove the hook block from your ~/.zshrc or ~/.bashrc — delete everything between # workscribe:hook:start and # workscribe:hook:end.