tau-coding-agent 0.1.6 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/README.md +15 -12
  2. package/extensions/answer.ts +129 -79
  3. package/extensions/branch-term/README.md +7 -0
  4. package/extensions/{branch-term.ts → branch-term/index.ts} +113 -104
  5. package/extensions/btw.ts +17 -2
  6. package/extensions/caffeinate/README.md +5 -0
  7. package/extensions/caffeinate/index.ts +144 -0
  8. package/extensions/fast.ts +292 -0
  9. package/extensions/ghostty.ts +214 -211
  10. package/extensions/git-diff-stats.ts +124 -84
  11. package/extensions/git-pr-status.ts +274 -208
  12. package/extensions/insights.ts +109 -191
  13. package/extensions/loop.ts +149 -145
  14. package/extensions/memory.ts +138 -86
  15. package/extensions/notify.ts +14 -26
  16. package/extensions/openai-verbosity.ts +108 -42
  17. package/extensions/review/fix.ts +15 -6
  18. package/extensions/review/git.ts +93 -103
  19. package/extensions/review/index.ts +60 -62
  20. package/extensions/review/interrupt.ts +117 -0
  21. package/extensions/review/message-queue.ts +45 -12
  22. package/extensions/review/models.ts +79 -3
  23. package/extensions/review/prompts.ts +41 -38
  24. package/extensions/review/review.ts +161 -166
  25. package/extensions/review/runner.ts +139 -147
  26. package/extensions/review/runtime.ts +173 -120
  27. package/extensions/review/triage.ts +41 -44
  28. package/extensions/sandbox/bash.ts +775 -0
  29. package/extensions/sandbox/command.ts +605 -0
  30. package/extensions/sandbox/config.ts +764 -0
  31. package/extensions/sandbox/index.ts +132 -3338
  32. package/extensions/sandbox/permissions/dialog.ts +118 -0
  33. package/extensions/sandbox/permissions/filesystem.ts +559 -0
  34. package/extensions/sandbox/permissions/mach-lookup.ts +186 -0
  35. package/extensions/sandbox/permissions/network.ts +164 -0
  36. package/extensions/sandbox/permissions/unsandboxed.ts +270 -0
  37. package/extensions/sandbox/runtime.ts +616 -0
  38. package/extensions/stash.ts +28 -15
  39. package/extensions/subagent/README.md +73 -0
  40. package/extensions/subagent/index.ts +822 -0
  41. package/extensions/subagent/interrupt.ts +117 -0
  42. package/extensions/subagent/permissions.ts +101 -0
  43. package/extensions/subagent/rpc.ts +177 -0
  44. package/extensions/tool-display-mode.ts +267 -64
  45. package/extensions/usage/index.ts +249 -356
  46. package/extensions/usage/openrouter.ts +10 -2
  47. package/extensions/websearch/README.md +12 -47
  48. package/extensions/websearch/config.ts +5 -2
  49. package/extensions/websearch/index.ts +94 -109
  50. package/extensions/websearch/output.ts +51 -0
  51. package/extensions/websearch/providers/anthropic.pi.ts +27 -44
  52. package/extensions/websearch/providers/gemini.browser.ts +68 -77
  53. package/extensions/websearch/providers/gemini.pi.ts +17 -17
  54. package/extensions/websearch/providers/openai-codex.pi.ts +145 -7
  55. package/extensions/websearch/providers/pi-model.shared.ts +33 -39
  56. package/extensions/websearch/providers/shared.ts +87 -2
  57. package/extensions/websearch/types.ts +0 -3
  58. package/extensions/worktree.ts +132 -172
  59. package/package.json +10 -5
  60. package/skills/browser-tools/SKILL.md +29 -234
  61. package/skills/browser-tools/references/cookies.md +36 -0
  62. package/skills/browser-tools/references/interaction.md +90 -0
  63. package/skills/browser-tools/references/logging.md +34 -0
  64. package/skills/git-clean-history/SKILL.md +6 -6
  65. package/skills/git-commit/SKILL.md +5 -3
  66. package/skills/github-pull-request/SKILL.md +60 -0
  67. package/skills/github-pull-request/references/create.md +40 -0
  68. package/skills/github-pull-request/references/stewardship.md +60 -0
  69. package/skills/oracle/SKILL.md +3 -3
  70. package/skills/oracle/scripts/oracle +10 -1
  71. package/skills/sentry/SKILL.md +15 -185
  72. package/skills/sentry/references/events.md +79 -0
  73. package/skills/sentry/references/issues.md +62 -0
  74. package/skills/sentry/references/logs.md +46 -0
  75. package/skills/update-changelog/SKILL.md +27 -121
  76. package/skills/web-design/SKILL.md +16 -105
  77. package/themes/tau-dark.json +4 -0
  78. package/extensions/openai-fast.ts +0 -229
  79. package/extensions/websearch/providers/openai-codex.browser.ts +0 -77
  80. package/extensions/websearch/providers/openai-codex.shared.ts +0 -123
@@ -0,0 +1,60 @@
1
+ # Existing-PR stewardship
2
+
3
+ Resume the existing PR within the requested scope and the [authorization matrix](../SKILL.md#authorization). Monitoring does not require repeating PR creation, and status-only or analysis requests do not authorize changes or publication.
4
+
5
+ ## Establish live context
6
+
7
+ - Confirm GitHub CLI availability/authentication and identify the repository and PR. Fetch its current base, head SHA, draft state, metadata, checks, and review state.
8
+ - Read applicable repository instructions and CI/review conventions. Consult templates and metadata conventions when changing copy, not as a prerequisite to every status check.
9
+ - Track the current head. After each push, monitor the new head rather than carrying forward earlier results.
10
+ - Before changing files or history, ensure the PR's actual head branch is checked out. Inspect the working tree, commits, and complete base-to-head diff, including the parent diff for a stacked PR. Preserve unrelated user work and honor changelog, generated-file, test, hook, and signing requirements.
11
+ - Use the `git-commit` skill for new commits. Do not rewrite commits merely for cleanup. Never push the default branch.
12
+
13
+ ## CI and conflicts
14
+
15
+ - Monitor required and pending checks, including automated-review checks.
16
+ - Never infer success from command errors, missing status, or an earlier head.
17
+ - Rerun clearly flaky or infrastructure-failed checks once, but flag them to the user.
18
+ - Before any review feedback arrives, fold a small, clear CI fix into its originating commit when unambiguous. Use `--force-with-lease` if already pushed. Otherwise create a focused fix commit.
19
+ - Assess large or unclear failures with the user before acting.
20
+ - Resolve trivial base conflicts autonomously. Explain semantic or uncertain conflicts and stop. Changing an existing PR's base, closing it, or reopening it also requires a checkpoint.
21
+ - Run focused validation before pushing stewardship code or conflict changes. Use `--force-with-lease` when an authorized branch update requires a force push.
22
+
23
+ ## Automated reviews
24
+
25
+ Only clearly identified bots or GitHub Apps count as automated; otherwise feedback is human. Request or re-request automated reviewers when the repository workflow calls for it, not human reviewers without explicit authorization.
26
+
27
+ Inspect review summaries and conversation comments. Fetch every unresolved inline thread, paginating when needed. Classify each automated finding:
28
+
29
+ - **Valid**: correct, in scope, and worth fixing.
30
+ - **Already addressed**: fixed by an existing branch commit.
31
+ - **Deferred**: valid but out of scope for this PR.
32
+ - **Dismissed**: incorrect, duplicate, or too low-value.
33
+ - **Unclear**: needs judgment or more information.
34
+
35
+ For valid or deferred findings requiring large, architectural, or scope-expanding changes—or any uncertain finding or fix—assess with the user and leave the feedback untouched.
36
+
37
+ For small, clearly valid findings:
38
+
39
+ 1. Make one focused commit per finding, including any tests.
40
+ 2. Comments with one root cause may share a commit.
41
+ 3. Batch commits into one push to limit CI cycles.
42
+ 4. After pushing, reply briefly inline, link the fixing commit when useful, and resolve the thread.
43
+
44
+ For remaining already addressed, deferred, or dismissed inline findings, reply briefly with the reason and resolve the thread.
45
+
46
+ Avoid top-level responses unless strictly needed or expected by the repository. Never replace inline replies with a top-level summary.
47
+
48
+ ## Human reviews
49
+
50
+ Investigate each human comment and recommend an action, but do not edit, reply, or resolve without explicit direction. When authorized, apply the same focused fix and validation rules. Reply or resolve only when instructions explicitly request it; authorization to implement a fix alone is insufficient.
51
+
52
+ ## Live metadata
53
+
54
+ Treat the live PR as authoritative. Before editing its title or body, fetch the latest content, make the smallest edit through a file, then update and verify. Never overwrite manual edits from a stale draft. Beyond factual corrections, update copy only for material changes to scope or reviewer context, preserving user-supplied or approved copy. Append nothing to copy supplied exactly.
55
+
56
+ Use descriptive labels only when commonly used on comparable PRs. Review/readiness or automation-triggering labels and human reviewer requests remain explicit-authorization actions.
57
+
58
+ ## Finish the current stage
59
+
60
+ Continue authorized stewardship until the [readiness criteria](../SKILL.md#completion-readiness-and-merge-boundaries) are met or a checkpoint/blocker needs user input. Report pending or failed checks, unresolved feedback, or unavailable status honestly. Do not mark ready, enable auto-merge, or merge automatically. After the user marks ready, monitor newly triggered checks and reviews on the current head.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oracle
3
- description: Get a second opinion by bundling a prompt + a curated file set, then asking a strong model from a different family through a separate Pi invocation.
3
+ description: "Get independent reviews, second opinions, or help getting unstuck by asking a strong model from another family with a curated prompt and file set."
4
4
  ---
5
5
 
6
6
  # Oracle
@@ -43,10 +43,10 @@ Run commands from this skill directory:
43
43
  ./scripts/oracle-bundle -p "<task>" --file "src/**" --file "!**/*.test.*"
44
44
 
45
45
  # Show which oracle model would be selected
46
- ./scripts/oracle --list-models --current openai-codex/gpt-5.6-sol
46
+ ./scripts/oracle --list-models --current openai-codex/gpt-6-astra
47
47
 
48
48
  # Ask the automatically selected oracle model
49
- ./scripts/oracle --current openai-codex/gpt-5.6-sol \
49
+ ./scripts/oracle --current openai-codex/gpt-6-astra \
50
50
  -p "<task>" --file "src/**" --file "!**/*.test.*"
51
51
 
52
52
  # Override the oracle model when the automatic choice is wrong
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import { spawnSync } from "node:child_process";
3
3
  import { existsSync, readFileSync } from "node:fs";
4
+ import { homedir } from "node:os";
4
5
  import path from "node:path";
5
- import { getAgentDir } from "@earendil-works/pi-coding-agent";
6
6
  import { fileURLToPath } from "node:url";
7
7
 
8
8
  const THINKING_LEVEL = "max";
@@ -114,6 +114,14 @@ function readSettings() {
114
114
  }
115
115
  }
116
116
 
117
+ function getAgentDir() {
118
+ const configured = process.env.PI_CODING_AGENT_DIR;
119
+ if (!configured) return path.join(homedir(), ".pi", "agent");
120
+ if (configured === "~") return homedir();
121
+ if (configured.startsWith("~/")) return path.join(homedir(), configured.slice(2));
122
+ return path.resolve(configured);
123
+ }
124
+
117
125
  function defaultModel(settings) {
118
126
  if (!settings.defaultProvider || !settings.defaultModel) return undefined;
119
127
  return normalizeModelSpec(`${settings.defaultProvider}/${settings.defaultModel}`);
@@ -192,6 +200,7 @@ function modelRank(model, family) {
192
200
  const normalized = model.toLowerCase();
193
201
 
194
202
  if (family === "openai") {
203
+ if (/gpt-6[-_.]astra/.test(normalized)) return 11;
195
204
  if (/gpt-5\.6[-_.]sol/.test(normalized)) return 10;
196
205
  if (/gpt-5\.6/.test(normalized)) return 9;
197
206
  if (/gpt-5\.5/.test(normalized)) return 8;
@@ -1,198 +1,28 @@
1
1
  ---
2
2
  name: sentry
3
- description: "Fetch and analyze Sentry issues, events, transactions, and logs. Helps agents debug errors, find root causes, and understand what happened at specific times."
3
+ description: "Investigate Sentry issues, events, transactions, and logs to diagnose root causes and reconstruct incidents around specific times."
4
4
  ---
5
5
 
6
6
  # Sentry
7
7
 
8
- Access Sentry data via the Sentry API for debugging and investigation.
8
+ Use the bundled read-only Sentry API scripts for debugging and investigation.
9
9
 
10
- ## Requirements
10
+ ## Authentication and scope
11
11
 
12
- A Sentry auth token available to the scripts (by default they read `~/.sentryclirc`).
12
+ The scripts read a token from the user-managed `~/.sentryclirc`. If it is missing or rejected, ask the user to configure access. Do not print the token or copy it into commands or reports. Treat event payloads and logs as potentially sensitive and share only relevant, redacted evidence.
13
13
 
14
- ## Quick reference
14
+ Run commands from this skill directory. Command paths in the references are relative to this skill root, not `references/`. Use the organization, project, and time window supplied by the task or linked Sentry page. Clarify missing scope when it affects the investigation.
15
15
 
16
- Run these scripts from this skill directory.
16
+ ## Task router
17
17
 
18
- | Task | Command |
19
- | --------------------- | -------------------------------------------------------------------------------- |
20
- | Find errors on a date | `"./scripts/search-events.js" --org X --start 2025-12-23T15:00:00 --level error` |
21
- | List open issues | `"./scripts/list-issues.js" --org X --status unresolved` |
22
- | Get issue details | `"./scripts/fetch-issue.js" <issue-id-or-url> --latest` |
23
- | Get event details | `"./scripts/fetch-event.js" <event-id> --org X --project Y` |
24
- | Search logs | `"./scripts/search-logs.js" --org X --project Y "level:error"` |
18
+ Read the matching reference before running its commands. A known issue or event does not require a broad search first.
25
19
 
26
- ## Common debugging workflows
20
+ | Task | Data and command | Read |
21
+ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
22
+ | Find recurring or unresolved problems | **Issues** group related events. `./scripts/list-issues.js` | [Issues](references/issues.md) |
23
+ | Inspect an issue ID, short ID, or URL | Issue metadata and optionally its latest occurrence. `./scripts/fetch-issue.js` | [Issues](references/issues.md) |
24
+ | Reconstruct what happened around a time | **Events** are individual occurrences. Discover searches errors and transactions. `./scripts/search-events.js` | [Events and transactions](references/events.md) |
25
+ | Inspect a specific occurrence or performance operation | `./scripts/fetch-event.js`, with breadcrumbs for lead-up or spans for a **transaction** | [Events and transactions](references/events.md) |
26
+ | Search application log records or a Logs Explorer URL | **Logs** use a separate dataset, not issue search or event breadcrumbs. `./scripts/search-logs.js` | [Logs](references/logs.md) |
27
27
 
28
- ### “What went wrong at this time?”
29
-
30
- Find events around a specific timestamp:
31
-
32
- ```bash
33
- # Find all events in a 2-hour window
34
- "./scripts/search-events.js" --org myorg --project backend \
35
- --start 2025-12-23T15:00:00 --end 2025-12-23T17:00:00
36
-
37
- # Filter to just errors
38
- "./scripts/search-events.js" --org myorg --start 2025-12-23T15:00:00 \
39
- --level error
40
-
41
- # Find a specific transaction type
42
- "./scripts/search-events.js" --org myorg --start 2025-12-23T15:00:00 \
43
- --transaction process-incoming-email
44
- ```
45
-
46
- ### “What errors have occurred recently?”
47
-
48
- ```bash
49
- # List unresolved errors from last 24 hours
50
- "./scripts/list-issues.js" --org myorg --status unresolved --level error --period 24h
51
-
52
- # Find high-frequency issues
53
- "./scripts/list-issues.js" --org myorg --query "times_seen:>50" --sort freq
54
-
55
- # Issues affecting users
56
- "./scripts/list-issues.js" --org myorg --query "is:unresolved has:user" --sort user
57
- ```
58
-
59
- ### “Get details about a specific issue/event”
60
-
61
- ```bash
62
- # Get issue with latest stack trace
63
- "./scripts/fetch-issue.js" 5765604106 --latest
64
- "./scripts/fetch-issue.js" https://sentry.io/organizations/myorg/issues/123/ --latest
65
- "./scripts/fetch-issue.js" MYPROJ-123 --org myorg --latest
66
-
67
- # Get specific event with all breadcrumbs
68
- "./scripts/fetch-event.js" abc123def456 --org myorg --project backend --breadcrumbs
69
- ```
70
-
71
- ### “Find events with a specific tag”
72
-
73
- ```bash
74
- # Find by custom tag (e.g., thread_id, user_id)
75
- "./scripts/search-events.js" --org myorg --tag thread_id:th_abc123
76
-
77
- # Find by user email
78
- "./scripts/search-events.js" --org myorg --query "user.email:*@example.com"
79
- ```
80
-
81
- ---
82
-
83
- ## Fetch issue
84
-
85
- ```bash
86
- "./scripts/fetch-issue.js" <issue-id-or-url> [options]
87
- ```
88
-
89
- Get details about a specific issue (grouped error).
90
-
91
- **Accepts:**
92
-
93
- - Issue ID: `5765604106`
94
- - Issue URL: `https://sentry.io/organizations/sentry/issues/5765604106/`
95
- - New URL format: `https://myorg.sentry.io/issues/5765604106/`
96
- - Short ID: `JAVASCRIPT-ABC` (requires `--org`)
97
-
98
- **Options:**
99
-
100
- - `--latest` include the latest event with full stack trace
101
- - `--org <org>` organization slug (for short IDs)
102
- - `--json` output raw JSON
103
-
104
- ---
105
-
106
- ## Fetch event
107
-
108
- ```bash
109
- "./scripts/fetch-event.js" <event-id> --org <org> --project <project> [options]
110
- ```
111
-
112
- **Options:**
113
-
114
- - `--org, -o <org>` organization slug (required)
115
- - `--project, -p <project>` project slug (required)
116
- - `--breadcrumbs, -b` show all breadcrumbs (default: last 30)
117
- - `--spans` show span tree for transactions
118
- - `--json` output raw JSON
119
-
120
- ---
121
-
122
- ## Search events (Discover)
123
-
124
- ```bash
125
- "./scripts/search-events.js" [options]
126
- ```
127
-
128
- **Time range options:**
129
-
130
- - `--period, -t <period>` relative time (24h, 7d, 14d)
131
- - `--start <datetime>` start time (ISO 8601: 2025-12-23T15:00:00)
132
- - `--end <datetime>` end time (ISO 8601)
133
-
134
- **Filter options:**
135
-
136
- - `--org, -o <org>` organization slug (required)
137
- - `--project, -p <project>` project slug or ID
138
- - `--query, -q <query>` Discover search query
139
- - `--transaction <name>` transaction name filter
140
- - `--tag <key:value>` tag filter (repeatable)
141
- - `--level <level>` level filter (error, warning, info)
142
- - `--limit, -n <n>` max results (default: 25, max: 100)
143
- - `--fields <fields>` comma-separated fields to include
144
-
145
- **Query syntax (Discover):**
146
-
147
- ```
148
- transaction:process-* Wildcard transaction match
149
- level:error Filter by level
150
- user.email:foo@bar.com Filter by user
151
- environment:production Filter by environment
152
- has:stack.filename Has stack trace
153
- ```
154
-
155
- ---
156
-
157
- ## List issues
158
-
159
- ```bash
160
- "./scripts/list-issues.js" [options]
161
- ```
162
-
163
- **Options:**
164
-
165
- - `--org, -o <org>` organization slug (required)
166
- - `--project, -p <project>` project slug (repeatable)
167
- - `--query, -q <query>` issue search query
168
- - `--status <status>` unresolved, resolved, ignored
169
- - `--level <level>` error, warning, info, fatal
170
- - `--period, -t <period>` time period (default: 14d)
171
- - `--limit, -n <n>` max results (default: 25)
172
- - `--sort <sort>` date, new, priority, freq, user
173
- - `--json` output raw JSON
174
-
175
- ---
176
-
177
- ## Search logs (Logs Explorer)
178
-
179
- ```bash
180
- "./scripts/search-logs.js" [query|url] [options]
181
- ```
182
-
183
- **Options:**
184
-
185
- - `--org, -o <org>` organization slug (required unless URL provided)
186
- - `--project, -p <project>` filter by project slug or ID
187
- - `--period, -t <period>` time period (default: 24h)
188
- - `--limit, -n <n>` max results (default: 100, max: 1000)
189
- - `--json` output raw JSON
190
-
191
- ---
192
-
193
- ## Tips
194
-
195
- 1. Start broad (time window + simple query), then drill into a single event/issue.
196
- 2. Use `--breadcrumbs` on `fetch-event.js` for the full lead-up to an error.
197
- 3. Use `list-issues.js --sort freq` to find recurring problems.
198
- 4. Use tags (`request_id`, `user_id`, etc.) to correlate events.
28
+ Correlate by timestamp, project, environment, and request/trace/user tags where available. Report evidence separately from hypotheses. Empty results are limited to the selected dataset, filters, time range, and result limit, not proof that no incident occurred. Authentication/API failures are not empty results.
@@ -0,0 +1,79 @@
1
+ # Sentry events and transactions
2
+
3
+ Run commands from the Sentry skill root. An event is an individual occurrence. Discover can search error events and transactions. Transactions describe performance operations and can carry spans. Neither search is a Logs Explorer query.
4
+
5
+ ## Investigate a time window
6
+
7
+ Start with the relevant project and a bounded window, then narrow by transaction, level, or correlation tags. Use explicit ISO 8601 timezone offsets or `Z` to avoid an ambiguous incident time.
8
+
9
+ ```bash
10
+ # Events in a two-hour window
11
+ "./scripts/search-events.js" --org myorg --project backend \
12
+ --start 2025-12-23T15:00:00Z --end 2025-12-23T17:00:00Z
13
+
14
+ # Errors since a known time
15
+ "./scripts/search-events.js" --org myorg --start 2025-12-23T15:00:00Z --level error
16
+
17
+ # A transaction name
18
+ "./scripts/search-events.js" --org myorg --project backend \
19
+ --period 24h --transaction process-incoming-email
20
+
21
+ # Correlate by custom tag or user
22
+ "./scripts/search-events.js" --org myorg --tag thread_id:th_abc123
23
+ "./scripts/search-events.js" --org myorg --query "user.email:*@example.com"
24
+ ```
25
+
26
+ Retain event IDs and project context, then fetch the occurrences that support the incident timeline. Matching a transaction name does not by itself establish whether a returned record is an error or transaction. Inspect the event details. For application log records, read `references/logs.md` from the skill root.
27
+
28
+ ### Search options
29
+
30
+ ```bash
31
+ "./scripts/search-events.js" [options]
32
+ ```
33
+
34
+ | Option | Meaning |
35
+ | ------------------------- | ---------------------------------------------------------------------------------------- |
36
+ | `--org, -o <org>` | Organization slug, required |
37
+ | `--project, -p <project>` | Project slug or numeric ID |
38
+ | `--period, -t <period>` | Relative range such as `1h`, `24h`, `7d`, or `14d`. Defaults to `24h` without `--start`. |
39
+ | `--start <datetime>` | Absolute start. Takes precedence over `--period`. |
40
+ | `--end <datetime>` | Absolute end with `--start`. If omitted, end is now. Do not use `--end` alone. |
41
+ | `--query, -q <query>` | Discover search query |
42
+ | `--transaction <name>` | Transaction name filter |
43
+ | `--tag <key:value>` | Tag filter, repeatable |
44
+ | `--level <level>` | Level filter such as `error`, `warning`, or `info` |
45
+ | `--limit, -n <n>` | Maximum results, default 25, capped at 100 |
46
+ | `--fields <fields>` | Comma-separated field names |
47
+ | `--json` | Raw JSON |
48
+
49
+ Default fields are `id,title,timestamp,transaction,message`. The request also includes `project.name`. Use `--json` to inspect returned project context or add fields explicitly, for example `--fields "id,title,timestamp,project.name,user.email"`.
50
+
51
+ Discover query examples:
52
+
53
+ ```text
54
+ transaction:process-* Wildcard transaction match
55
+ level:error Filter by event level
56
+ user.email:foo@bar.com Filter by user
57
+ environment:production Filter by environment
58
+ has:stack.filename Has a stack trace
59
+ ```
60
+
61
+ Results are newest first. The script fetches one limited result set without automatic pagination. Narrow a busy time window rather than treating the first page as a complete timeline.
62
+
63
+ ## Fetch an exact event
64
+
65
+ ```bash
66
+ "./scripts/fetch-event.js" abc123def456 --org myorg --project backend --breadcrumbs
67
+ "./scripts/fetch-event.js" abc123def456 --org myorg --project backend --spans
68
+ ```
69
+
70
+ | Option | Meaning |
71
+ | ------------------------- | --------------------------------------------------------- |
72
+ | `<event-id>` | Required positional event ID, not an issue ID or trace ID |
73
+ | `--org, -o <org>` | Organization slug, required |
74
+ | `--project, -p <project>` | Project slug, required |
75
+ | `--breadcrumbs, -b` | All available breadcrumbs instead of the last 30 |
76
+ | `--spans` | Display transaction spans, up to 50 in formatted output |
77
+ | `--json` | Raw event JSON |
78
+
79
+ Use breadcrumbs for the lead-up to an error and spans for transaction operations. Formatted output is selective, including abbreviated stack traces. Use `--json` when needed for omitted details, and share only relevant, redacted fields. Timestamp rendering differs between search and detail output, so normalize to a stated timezone when assembling a timeline.
@@ -0,0 +1,62 @@
1
+ # Sentry issues
2
+
3
+ Run commands from the Sentry skill root. Issues group related events and summarize recurrence, affected users, and status. Use them to prioritize recurring problems or inspect a known group, not as a substitute for the exact event in an incident window.
4
+
5
+ ## Inspect a known issue
6
+
7
+ ```bash
8
+ "./scripts/fetch-issue.js" 5765604106 --latest
9
+ "./scripts/fetch-issue.js" https://sentry.io/organizations/myorg/issues/123/ --latest
10
+ "./scripts/fetch-issue.js" https://myorg.sentry.io/issues/123/ --latest
11
+ "./scripts/fetch-issue.js" MYPROJ-123 --org myorg --latest
12
+ ```
13
+
14
+ Accepts a numeric issue ID, either URL format above, or a short ID such as `JAVASCRIPT-ABC`. Short IDs require `--org`.
15
+
16
+ | Option | Meaning |
17
+ | ------------- | ----------------------------------------------------------------------- |
18
+ | `--latest` | Include the latest event, exception stack trace, and recent breadcrumbs |
19
+ | `--org <org>` | Organization slug for short IDs |
20
+ | `--json` | Raw issue JSON, or `{ issue, event }` when combined with `--latest` |
21
+
22
+ The latest event may be outside the requested incident window. For a specific occurrence, read `references/events.md` from the skill root and search/fetch that event instead. Formatted output abbreviates stack traces, breadcrumbs, tags, and request bodies. Use raw JSON only when the omitted detail is needed, and redact sensitive fields before reporting.
23
+
24
+ ## List and search issues
25
+
26
+ ```bash
27
+ # Recent unresolved errors
28
+ "./scripts/list-issues.js" --org myorg --project backend \
29
+ --status unresolved --level error --period 24h
30
+
31
+ # High-frequency issues
32
+ "./scripts/list-issues.js" --org myorg --query "times_seen:>50" --sort freq
33
+
34
+ # Issues affecting users
35
+ "./scripts/list-issues.js" --org myorg --query "is:unresolved has:user" --sort user
36
+ ```
37
+
38
+ | Option | Meaning |
39
+ | ------------------------- | --------------------------------------------------------------------- |
40
+ | `--org, -o <org>` | Organization slug, required |
41
+ | `--project, -p <project>` | Project slug or numeric ID, repeatable |
42
+ | `--query, -q <query>` | Sentry issue search query |
43
+ | `--status <status>` | `unresolved`, `resolved`, or `ignored` |
44
+ | `--level <level>` | `error`, `warning`, `info`, or `fatal` |
45
+ | `--period, -t <period>` | Time period, default `14d` |
46
+ | `--limit, -n <n>` | Maximum results, default 25, capped at 100 |
47
+ | `--sort <sort>` | `date` (last seen), `new` (first seen), `priority`, `freq`, or `user` |
48
+ | `--json` | Raw JSON |
49
+
50
+ Issue search examples:
51
+
52
+ ```text
53
+ is:unresolved Unresolved issues
54
+ has:user Has user context
55
+ user.email:*@example.com User email pattern
56
+ lastSeen:-24h Seen in the last 24 hours
57
+ firstSeen:>=2025-12-23 First seen on or after a date
58
+ times_seen:>50 More than 50 occurrences
59
+ error.handled:0 Unhandled errors
60
+ ```
61
+
62
+ Combine filters in a quoted query and narrow by project when known. This script returns one limited result set and does not paginate automatically. Record the scope and limit before drawing conclusions about prevalence.
@@ -0,0 +1,46 @@
1
+ # Sentry logs
2
+
3
+ Run commands from the Sentry skill root. Logs Explorer records are a separate dataset from Discover events and grouped issues. Event breadcrumbs are not a replacement for searching application logs.
4
+
5
+ ## Search logs or use a Logs Explorer URL
6
+
7
+ ```bash
8
+ "./scripts/search-logs.js" "level:error" --org myorg --project backend
9
+ "./scripts/search-logs.js" "message:*timeout*" --org myorg --period 7d
10
+ "./scripts/search-logs.js" "trace:abc123" --org myorg --project backend
11
+ "./scripts/search-logs.js" "https://myorg.sentry.io/explore/logs/?project=123&statsPeriod=7d"
12
+ ```
13
+
14
+ Quote queries and URLs so the shell does not interpret wildcards or `&`. URLs can use `https://myorg.sentry.io/explore/logs/` or `https://sentry.io/organizations/myorg/explore/logs/`.
15
+
16
+ The script extracts organization, the first `project` parameter, `statsPeriod`, and `logsQuery` from a URL. It does not preserve every UI filter, absolute `start`/`end`, or multiple project selections. Put explicit option overrides after the URL and check the resulting scope before relying on it.
17
+
18
+ ### Options
19
+
20
+ ```bash
21
+ "./scripts/search-logs.js" [query|url] [options]
22
+ ```
23
+
24
+ | Option | Meaning |
25
+ | ------------------------- | ------------------------------------------------------- |
26
+ | `--org, -o <org>` | Organization slug, required unless extracted from a URL |
27
+ | `--project, -p <project>` | Project slug or ID, added as a `project:` query filter |
28
+ | `--period, -t <period>` | Relative time range, default `24h` |
29
+ | `--limit, -n <n>` | Maximum results, default 100, capped at 1000 |
30
+ | `--json` | Raw JSON |
31
+
32
+ There are no `--start`, `--end`, or `--query` options on this script. Supply the query positionally. For an incident at a specific time, choose a relative period that includes it and verify returned timestamps. If this cannot represent the required scope, report the limitation instead of silently treating a different time range as equivalent.
33
+
34
+ Query examples supported by the script's help:
35
+
36
+ ```text
37
+ level:error Log severity
38
+ message:*timeout* Message text
39
+ trace:abc123 Trace ID
40
+ project:backend Project filter
41
+ level:error message:*failed* Combined filters
42
+ ```
43
+
44
+ Results are newest first and contain `sentry.item_id`, `trace`, `sentry.severity`, `timestamp`, and `message`. Formatted output shows timestamp, severity, message, and trace when present. Use `--json` for the returned item ID and structured fields.
45
+
46
+ The script fetches one limited result set, without automatic pagination. Narrow the query or period to investigate busy streams. Correlate traces and timestamps with events as needed by reading `references/events.md` from the skill root. Empty logs do not rule out an error event, an issue, or missing log instrumentation.