| name | open-knowledge-bug-report |
| description | Use when the user reports a problem with Open Knowledge, asks for help debugging OK, or wants to file a bug report. This skill guides the agent to capture diagnostic information via the ok bug-report CLI command. |
| compatibility | Any MCP host (Claude Code, Cursor, Codex, Windsurf) with Open Knowledge MCP server registered. |
| metadata | {"version":"0.6.0","author":"Inkeep","repository":"https://github.com/inkeep/open-knowledge"} |
Bug Report — agent guidance
When a user reports a problem with Open Knowledge or asks for debugging help, use the ok bug-report command to capture a structured diagnostic bundle.
Quick path
ok bug-report --no-reveal
The --no-reveal flag suppresses the Finder reveal (use it when running as an agent — you want the file path, not a Finder window).
What the command does
- Gathers all structured log files from
~/.ok/logs/ (NDJSON format, pino)
- When invoked inside an OK project directory, filters logs to that project's records
- Collects system info: OK version, Node/Bun versions, macOS version, locale, timezone, free disk space
- Collects lock directory contents (server.lock, spawn-error-log) when a project context exists
- Extracts recent IPC error records from desktop logs
- Runs an auto-redaction pass over all content (home paths, API tokens, credentials are scrubbed)
- Writes
~/.ok/bug-reports/<timestamp>-bugreport.zip
- Prints the bundle path to stdout
What's in the bundle
<timestamp>-bugreport.zip
├── MANIFEST.json — what's inside, redaction audit report
├── sysinfo.json — versions, locale, disk, build channel
├── README.md — what's safe to share, discipline version
├── logs/ — NDJSON log files (auto-redacted)
├── lockdir/ — server.lock, spawn-error-log (if project)
└── recent-ipc-errors.json — last 50 structured IPC errors
Agent workflow
- Run
ok bug-report --no-reveal in the user's project directory (or home if no project)
- Read the path from stdout
- Unzip to a temp directory:
unzip -o <path> -d /tmp/ok-diag-<timestamp>/
- Read
MANIFEST.json — check the redactions array (if non-empty, some content was scrubbed)
- Read
sysinfo.json — check versions, disk space, build channel
- Grep the log files for errors:
grep '"level":50' logs/*.log | head -20 (level 50 = error in pino)
- Read
recent-ipc-errors.json for IPC-layer failures
- Report findings to the user with actionable next steps
If the command is not available
The ok bug-report command ships with @inkeep/open-knowledge >= 0.7.0. If the user's version is older:
- Check version:
ok --version
- If < 0.7.0: suggest
npm install -g @inkeep/open-knowledge@latest to update
- Fallback: manually inspect
~/.ok/logs/ for recent .log files (NDJSON format, greppable)
Privacy
The bundle auto-redacts:
- macOS home paths (
/Users/<name>/ → ~/)
- GitHub PAT prefixes (
ghp_, gho_, ghu_, ghs_, ghr_)
- AWS access keys, Anthropic tokens, OpenAI tokens
- Bearer authorization headers
The MANIFEST.json redactions array lists every file and pattern that was scrubbed. The bundle is safe for the user to attach to a GitHub issue.
