> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# beacon endpoint opencode

> Collect endpoint telemetry from OpenCode session records

## Command overview

`beacon endpoint opencode` supplements the live [OpenCode](/runtimes/opencode) plugin by reading OpenCode's committed local session store and converting those records into Beacon [endpoint events](/concepts/core-concepts#endpoint-event).

```bash title="Command syntax" theme={null}
beacon endpoint opencode [command]
```

Beacon reads `opencode.db` when present and falls back to OpenCode's legacy `storage/session`, `storage/message`, `storage/part`, and `storage/project` tree. This path is useful for historical sessions and sessions that ran before Beacon's OpenCode plugin was installed or loaded.

Every event is marked `harness.collection_method=poll`. Beacon sees what OpenCode already wrote, so nothing here can hold or deny a tool call. Keep the managed plugin installed when you need live approval telemetry and richer hook timing.

Reading is local and offline. Nothing this command does reaches the network.

## Commands

| Command                           | Description                                                  |
| --------------------------------- | ------------------------------------------------------------ |
| `beacon endpoint opencode sync`   | Read new OpenCode session records into the runtime log       |
| `beacon endpoint opencode status` | Show OpenCode local sessions and how much has been collected |

## Flags

Both subcommands accept:

| Flag                | Description                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--data-dir <path>` | OpenCode data directory or `opencode.db` path. Defaults to `~/.config/opencode`                                                               |
| `--state <path>`    | Collector cursor file. Defaults to `~/.beacon/endpoint/state/opencode-sessions.json`, or a file beside the system runtime log with `--system` |
| `--json`            | Print the result as JSON                                                                                                                      |
| `--user`            | Use per-user endpoint paths. Enabled by default                                                                                               |
| `--system`          | Use system endpoint paths                                                                                                                     |

`sync` also accepts:

| Flag                    | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `--log-path <path>`     | Runtime JSONL log path. Defaults to the resolved endpoint log            |
| `--print`               | Print mapped events as JSON without writing them or advancing the cursor |
| `--watch`               | Sweep continuously on `--interval` instead of sweeping once and exiting  |
| `--interval <duration>` | Sweep interval for `--watch`. Defaults to `1m`, with a 5-second floor    |

## Sweeping

```bash title="Sweep once" theme={null}
beacon endpoint opencode sync
```

```bash title="Preview without writing anything" theme={null}
beacon endpoint opencode sync --print
```

`--print` is a dry run in both directions: it neither writes the runtime log nor advances the cursor.

```bash title="Sweep continuously" theme={null}
beacon endpoint opencode sync --watch --interval 5m
```

Nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running in the user context that owns OpenCode's data directory.

A tool call that OpenCode has started but not finished is written twice: once as the invocation, and again with its output, exit code, and diff when it returns. Beacon emits both. The invocation arrives as `tool.invoked` on the sweep that first sees it, and the completion arrives on a later sweep as `command.executed`, `file.modified`, or whichever action the finished call turns out to be. OpenCode rewrites the record in place for the second one, so the cursor tracks the events it has already written by id rather than how far it read: a repeated sweep over an unchanged session writes nothing, and one over a session whose call has since returned writes only the completion.

## Status

```bash title="Show OpenCode sessions and collection progress" theme={null}
beacon endpoint opencode status
```

`collected` means the cursor is level with the records Beacon read from that OpenCode session source. SQLite-backed sessions and legacy JSON sessions are tracked separately so upgrading OpenCode's storage format does not confuse the cursor.

## Related

<Columns cols={2}>
  <Card title="OpenCode" icon="code" href="/runtimes/opencode">
    Telemetry coverage, plugin setup, and known gaps for the runtime.
  </Card>

  <Card title="Hooks" icon="plug" href="/cli/hooks">
    Install the live OpenCode plugin for hook-time telemetry.
  </Card>
</Columns>