> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Prime Agent
> Beacon support details for Prime Agent (Prime Intellect) endpoint telemetry
## Runtime overview
Beacon supports [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent), Prime Intellect's coding and research harness, through a managed local extension.
Prime Agent is a hard fork of [pi-mono](https://github.com/badlogic/pi-mono), as [Oh My Pi](/runtimes/oh-my-pi) and [Senpi](/runtimes/senpi) are. All four are supported separately and recorded under their own harness names, because they are separately installed products that one machine can run side by side.
Prime Agent fits neither of Beacon's two usual live integration shapes. It has no hooks configuration file to merge a managed hook block into, and no OpenTelemetry export to point at the local collector. Its documented observation surface is the TypeScript extension API it inherited from Pi, so the live integration is extension-shaped: one Beacon-owned extension file forwards runtime events to `beacon-hooks`, the same shape as the [Pi](/runtimes/pi), [Oh My Pi](/runtimes/oh-my-pi), [OpenCode](/cli/supported-runtimes-opencode) and [Cline](/cli/supported-runtimes-cline) integrations.
Beacon can also read Prime Agent's committed JSONL session store after the fact:
```bash theme={null}
beacon endpoint prime sync
```
That poll path is local and offline, checkpointed by file and line number, and marks every event `harness.collection_method=poll`. It complements the extension rather than replacing it: the extension sees live tool details as Prime runs, while the poll path can backfill sessions that happened before the extension was installed or sessions where the extension was not loaded.
```bash theme={null}
beacon endpoint hooks install --harness prime
```
## The single-tool design changes what telemetry looks like
Prime Agent gives the model one tool by default: `ipython`, a persistent Python REPL. The agent reads files, writes files and runs shell commands through that kernel — `bash('cmd')` from inside Python — rather than through separate file and shell tools. `bash` and `edit` tool definitions do ship, but they are opt-in rather than part of the default tool set. Two consequences run through everything below.
**A cell is recorded as a command, not as an anonymous tool call.** The code goes into `command.command`, where the command-scoped rules can read it, and is marked as Python in `raw` so nobody mistakes it for a shell line. `import os; os.system("rm -rf /")` is a shell command wearing a Python hat, and a log that filed it under `tool.completed` would hide essentially every action the agent took. This is the same reading Oh My Pi's operator `$` code gets.
**The kernel's own file writes become file events.** Prime Agent streams a diff display for each file its kernel helpers rewrite, so one cell that edits three files produces three `file.modified` events, each carrying the unified patch and joined back to the cell by `gen_ai.tool.call.id`.
## Prerequisites
Before enabling Prime Agent telemetry, make sure:
* Prime Agent is installed and available as the `prime-agent` executable, or has a local state directory at `~/.prime/agent`.
* `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.
* Prime Agent is restarted after install or removal so new sessions load the updated extension.
## Collection path
Beacon's managed Prime Agent extension is a single TypeScript file at one of two auto-discovered extension locations:
| Level | Extension path |
| ------- | ------------------------------------- |
| User | `~/.prime/agent/extensions/beacon.ts` |
| Project | `./.prime/agent/extensions/beacon.ts` |
User level is the default, because it follows the operator rather than one checkout. `beacon endpoint discover` reports on the user path only, so a project-level extension does not appear in discovery output.
The project path keeps the `agent` segment. Prime Agent's config directory name is the two-segment literal `.prime/agent`, and it joins that whole string under the working directory as well as under the home directory — where [Pi](/runtimes/pi) uses `.pi/extensions` and [Oh My Pi](/runtimes/oh-my-pi) uses `.omp/extensions` at project scope. A file written to `./.prime/extensions/` is never loaded.
`PRIME_AGENT_CODING_AGENT_DIR` replaces the user-level agent directory outright, and Beacon honors it — including a leading `~`, which the runtime expands before use. It does not move the project path, because Prime Agent does not consult it there. Beacon deliberately ignores `PI_CODING_AGENT_DIR`: that is the variable the same upstream code produces for Pi and Oh My Pi, and reading it here would move this install whenever you had set it for a different product.
Beacon identifies its own extension file by the marker `beacon-managed-prime-extension:v1`. The version suffix is part of the contract with the extension source: it is what lets a repair recognize a stale file instead of leaving it in place. A `beacon.ts` without the marker belongs to somebody else, so install will not overwrite it and discovery does not report it as Beacon telemetry. The marker is distinct from Pi's and Oh My Pi's, so a file found at any of the three paths is attributed to the runtime that actually loads it.
Prime Agent has no OpenTelemetry export for Beacon to configure, so there is no OTLP path for this runtime. The poll path reads JSONL transcripts from `~/.prime/agent/sessions` and subagent artifacts from `~/.prime/agent/session-artifacts`; if `PRIME_AGENT_CODING_AGENT_DIR` is set, Beacon reads `sessions` and `session-artifacts` below that directory, matching the runtime's user-level agent directory override. The cursor lives in Beacon state, not in Prime Agent's directory.
## Discovery and status
Beacon detects Prime Agent through the `prime-agent` executable, and treats the `~/.prime/agent` state directory as an additional signal. Prime Agent installed through npm, or through its own installer into `~/.local/share/prime-agent`, is often missing from the `PATH` the endpoint process inherited, because a shell alias, a version manager, or a per-project install can all hide it while the state directory is still present. The Pi, Oh My Pi, OpenCode, Cursor, and Hermes probes use the same fallback.
The bare name `prime` is deliberately not probed for. It is an ordinary word another binary or an internal script could plausibly claim, and a false positive reports a runtime the machine does not have.
```bash title="Show Prime Agent discovery state" theme={null}
beacon endpoint discover --all --json
```
Prime Agent reports as the `prime_agent` harness with capability `plugin`:
| Telemetry status | Meaning |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `missing` | No extension file at the user-level managed path |
| `disabled` | A `beacon.ts` exists but carries no Beacon marker, so it is somebody else's extension sharing the filename |
| `enabled` | Beacon's managed extension is in place |
An unmarked extension file reports `disabled` rather than `enabled`, because reporting it as enabled would show the runtime as covered while no events arrive.
## Install or configuration support
`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is installed separately, because Prime Agent loads it from the user's own profile rather than from a machine-wide location:
```bash theme={null}
beacon endpoint hooks install --harness prime # user level (default)
beacon endpoint hooks install --harness prime --level project
beacon endpoint hooks status --harness prime
beacon endpoint hooks uninstall --harness prime
```
`prime`, `prime-agent`, `prime_agent`, and `primeagent` all resolve to this runtime. Prime Intellect's model names are deliberately not accepted, so nobody can ask to install an extension for a model.
Install writes one file and refuses to touch a `beacon.ts` it did not write, so an extension of your own that happens to share the filename is left alone and the install fails loudly rather than replacing it. Uninstall removes only a file carrying this runtime's marker.
`status` reports `installed=false` when the extension exists but points at a hook binary that is no longer there, which happens after a Beacon uninstall, a partly applied update, or a home directory restored onto a different machine. In each case Prime Agent loads an extension that spawns nothing.
## Telemetry coverage
| Area | Support |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Runtime discovery | Supported through executable and `~/.prime/agent` detection, managed extension path, and telemetry status |
| Harness attribution | Supported. `prime`, `prime_agent`, `prime-agent`, `primeagent`, `prime_cli`, `prime-cli`, `prime_intellect`, and `prime-intellect` all normalize to `prime_agent` |
| Extension install, status, uninstall, and repair | Supported |
| Session-store sync | Supported through `beacon endpoint prime sync`, with `--print`, `--watch`, `--sessions-dir`, and `--artifacts-dir` |
| Session lifecycle | Supported. `session.started` and `session.ended`, carrying why the session started or stopped — a fork and a resume both produce a session with history behind it |
| Prompts | Supported. `prompt.submitted`, with whether the input was typed, delivered over RPC, or injected by another extension |
| Tool use | Supported. `tool.invoked` before execution, then `tool.completed` or `tool.failed` |
| Commands | Supported. `command.executed` for each `ipython` cell, for the optional `bash` tool, and for commands you run with the `!` prefix, which are marked as operator-initiated. A cell's result carries its captured output, the runtime's own duration, and its status |
| File activity | Supported. `file.modified` per file a kernel cell rewrote, with the unified patch; plus `file.modified` for the optional `edit` tool, carrying the unified diff it reports |
| Agent reasoning | Supported. `agent.reasoning` from an assistant message's thinking parts, in the OTel GenAI reasoning-part shape |
| Token usage and cost | Supported. `token.usage` normalized into `gen_ai.usage`, including cache and reasoning tokens and runtime-reported cost |
| Approval decisions | Not available. Prime Agent exposes no operator approval decision to observe. See [Known gaps](#known-gaps) |
| MCP activity | Not separately attributed. Prime Agent does not expose MCP as agent tools. See [Known gaps](#known-gaps) |
| Local JSONL and dashboard | Supported |
| MDM deployment | Supported for the endpoint agent. The Prime Agent extension installs separately in the logged-in user's context |
Harness names are matched against a closed set of spellings rather than by substring. `prime` is an ordinary English word that appears in model ids, file paths, and vendor names, so a substring rule would report any event whose harness attribute merely contained it as a Prime Agent session. Both the hook spelling (`--platform prime`) and the runtime's own name (`prime-agent`) are pinned, so one session cannot be recorded under two names.
## Data handling
Prime Agent content is handled like every other runtime. Prompts, cell code, command output, tool arguments, paths, diffs, and reasoning text are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.
The extension itself sends nothing over the network. It spawns the local `beacon-hooks` binary with a fixed argv and writes the event to its stdin. A send that has not completed in two seconds is abandoned so Beacon cannot stall Prime Agent's agent loop, and a failure to spawn costs the event rather than the run.
## Known gaps
* **No approval telemetry.** Prime Agent's `tool_call` event lets an extension block a call, but that is an extension deciding rather than an operator being asked. It exposes no operator approval decision through the extension API, so Beacon records these as tool activity and writes no approval events. [Pi](/runtimes/pi) and [Cline](/cli/supported-runtimes-cline) work the same way for the same reason; [Oh My Pi](/runtimes/oh-my-pi) is the fork that does report real ones. Detections in `rules/approval-abuse/` do not fire on Prime Agent activity.
* **MCP calls are not separately attributed.** Consistent with its single-tool design, Prime Agent does not expose MCP servers as agent tools: each integration is a Python skill package the model imports and calls from inside the kernel. So an MCP call arrives as part of a cell's code in `command.command` rather than as an `mcp.tool_invoked` event with a server and tool name, and the two questions MCP telemetry usually answers — which server did this agent reach, and what did it call there — have no dedicated field to answer them here. This is a property of the runtime rather than a gap Beacon can close from its side.
* **No per-cell exit code.** A Python cell does not have one. The runtime reports a `status` of `ok`, `error`, or `aborted`, which Beacon records verbatim; deriving a `0`/`1` from it would put a shell's vocabulary on something that is not a shell. An interrupted cell is recorded as aborted rather than failed, so a Ctrl+C does not read as an agent error.
* **No enforcement.** As with every other runtime, enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is not wired to Prime Agent. Its blocking `tool_call` handler makes it a viable target for that seam later.
* **Streaming events are not collected.** The extension subscribes to seven of Prime Agent's event types and ignores the rest — provider request and response internals, streaming message updates, compaction, refinement and tree-navigation signals, and TUI plumbing. Assistant output is recorded once when a message finalizes rather than token by token, so Beacon stays out of the streaming path.
* **Poll sync is after-the-fact.** `beacon endpoint prime sync` can recover committed prompts, assistant messages and reasoning, tool calls and results, context attachments, errors, compactions, refinement state updates, and subagent artifact files from Prime Agent's JSONL store. It cannot block or delay anything, and it does not have every live extension context field. Use it as backfill or scheduled catch-up, not as an enforcement surface.
* **`.agents` and other hosts.** Prime Agent's extension directory is its own (`.prime/agent/extensions`), not a shared one, so unlike [goose](/runtimes/goose) there is no ambiguity about which runtime ran the extension.
## Deployment notes
The extension is loaded when Prime Agent starts, so an install taken while it is running takes effect on the next launch.
Confirm discovery sees the runtime, then generate one Prime Agent event and check the log:
```bash theme={null}
/opt/beacon/bin/beacon endpoint discover --all --json
/opt/beacon/bin/beacon endpoint hooks status --harness prime
/opt/beacon/bin/beacon endpoint doctor --system
grep '"name":"prime_agent"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3
```
## Related
The upstream runtime Prime Agent forked, supported through the same extension shape.
The other pi-mono fork, and the one that reports operator approval decisions.
Return to the runtime support overview.