opencode-posthog 0.0.1

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 (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +90 -0
  3. package/dist/index.js +4942 -0
  4. package/package.json +62 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nejc Drobnič
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,90 @@
1
+ # opencode-posthog
2
+
3
+ PostHog LLM Analytics plugin for [OpenCode](https://opencode.ai). Captures LLM generations, tool executions, and conversation traces, sending them to PostHog as structured `$ai_*` events for the LLM Analytics dashboard.
4
+
5
+ ## Installation
6
+
7
+ Add `opencode-posthog` to your `opencode.json`:
8
+
9
+ ```json
10
+ {
11
+ "$schema": "https://opencode.ai/config.json",
12
+ "plugin": ["opencode-posthog"]
13
+ }
14
+ ```
15
+
16
+ The package is installed automatically at startup and cached in `~/.cache/opencode/node_modules/`.
17
+
18
+ ### Local development
19
+
20
+ Place the plugin source in your project's `.opencode/plugins/` directory (or `~/.config/opencode/plugins/` for global use). Add `posthog-node` to `.opencode/package.json` so OpenCode installs it at startup:
21
+
22
+ ```json
23
+ {
24
+ "dependencies": {
25
+ "posthog-node": "^5.0.0"
26
+ }
27
+ }
28
+ ```
29
+
30
+ ## Configuration
31
+
32
+ All configuration is via environment variables:
33
+
34
+ | Variable | Default | Description |
35
+ | ------------------------------ | -------------------------- | ----------------------------------------------- |
36
+ | `POSTHOG_API_KEY` | _(required)_ | PostHog project API key |
37
+ | `POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog instance URL |
38
+ | `POSTHOG_PRIVACY_MODE` | `false` | Redact all LLM input/output content when `true` |
39
+ | `POSTHOG_ENABLED` | `true` | Set `false` to disable |
40
+ | `POSTHOG_DISTINCT_ID` | machine hostname | The `distinct_id` for all events |
41
+ | `POSTHOG_PROJECT_NAME` | cwd basename | Project name in all events |
42
+ | `POSTHOG_TAGS` | _(none)_ | Custom tags: `key1:val1,key2:val2` |
43
+ | `POSTHOG_MAX_ATTRIBUTE_LENGTH` | `12000` | Max length for serialized tool input/output |
44
+
45
+ If `POSTHOG_API_KEY` is not set, the plugin is a no-op.
46
+
47
+ ## Events
48
+
49
+ ### `$ai_generation` — per LLM call
50
+
51
+ Emitted for each LLM roundtrip (step-finish part). Properties include:
52
+
53
+ - `$ai_model`, `$ai_provider` — model and provider identifiers
54
+ - `$ai_input_tokens`, `$ai_output_tokens`, `$ai_reasoning_tokens` — token counts
55
+ - `$ai_cache_read_input_tokens`, `$ai_cache_creation_input_tokens` — cache token counts
56
+ - `$ai_total_cost_usd` — cost in USD
57
+ - `$ai_latency` — not available per-step (use trace-level latency)
58
+ - `$ai_stop_reason` — `stop`, `tool_calls`, `error`, etc.
59
+ - `$ai_input`, `$ai_output_choices` — message content (null in privacy mode)
60
+ - `$ai_trace_id`, `$ai_span_id`, `$ai_session_id` — correlation IDs
61
+
62
+ ### `$ai_span` — per tool execution
63
+
64
+ Emitted when a tool call completes or errors. Properties include:
65
+
66
+ - `$ai_span_name` — tool name (`read`, `write`, `bash`, `edit`, etc.)
67
+ - `$ai_latency` — execution time in seconds
68
+ - `$ai_input_state`, `$ai_output_state` — tool input/output (null in privacy mode)
69
+ - `$ai_parent_id` — span ID of the generation that triggered this tool
70
+ - `$ai_is_error`, `$ai_error` — error status
71
+
72
+ ### `$ai_trace` — per user prompt
73
+
74
+ Emitted on `session.idle` (agent finished responding). Properties include:
75
+
76
+ - `$ai_trace_id`, `$ai_session_id` — correlation IDs
77
+ - `$ai_latency` — total trace time in seconds
78
+ - `$ai_total_input_tokens`, `$ai_total_output_tokens` — accumulated token counts
79
+ - `$ai_input_state`, `$ai_output_state` — user prompt and final response
80
+ - `$ai_is_error` — whether any step/tool errored
81
+
82
+ ## Privacy
83
+
84
+ When `POSTHOG_PRIVACY_MODE=true`, all content fields (`$ai_input`, `$ai_output_choices`, `$ai_input_state`, `$ai_output_state`) are set to `null`. Token counts, costs, latency, and model metadata still flow.
85
+
86
+ Sensitive keys (matching `api_key`, `token`, `secret`, `password`, `authorization`, `credential`, `private_key`) are always redacted in tool inputs/outputs regardless of privacy mode.
87
+
88
+ ## License
89
+
90
+ MIT