@mirego/opencode-forra-attribution

OpenCode plugin that attaches Forra usage-attribution headers from the local git context on every outbound LLM request. With this installed, compatible-API usage is attributed to the current repository and branch without per-session configuration.

Requirements

• OpenCode with plugin support (@opencode-ai/plugin ≥ 1.18.0)
• git available on PATH
• A Forra-compatible provider configured in your OpenCode config

Installation (local development)

From the monorepo root:

./tools/opencode-forra-attribution/install.sh

This symlinks the plugin into .opencode/plugins/ so OpenCode auto-loads it at startup. Restart OpenCode after installing.

For all projects (global install during development):

mkdir -p ~/.config/opencode/plugins
ln -sfn "$(pwd)/tools/opencode-forra-attribution/src/index.ts" \
  ~/.config/opencode/plugins/forra-attribution.ts

Soon: publish as @mirego/opencode-forra-attribution on npm. After that, add the package name to the plugin array in ~/.config/opencode/opencode.json and OpenCode will install it automatically.

Headers sent

| Header | Source | |--------|--------| | x-git-project | Normalized owner/repo from git remote get-url origin | | x-git-branch | Current branch from git branch --show-current | | x-opencode-session-id | OpenCode session ID | | x-api-agent-id | OpenCode agent name |

Headers are only attached when the provider baseURL looks like Forra — the URL contains mirego.com, forra-ai.com, or localhost:8000. Other providers (e.g. public OpenAI/Anthropic) are left untouched.

Git context is read on every matching request, so branch switches within a session are reflected immediately.

Project label normalization

Remote URLs are normalized to a stable owner/repo label (lowercased, .git stripped) so SSH and HTTPS clones of the same repository share one report entry:

| Remote | Label | |--------|-------| | [email protected]:mirego/mirego-scout.git | mirego/mirego-scout | | https://github.com/mirego/mirego-scout.git | mirego/mirego-scout | | https://gitlab.com/mirego/mirego-scout.git | mirego/mirego-scout |

Override and disable

| Variable | Effect | |----------|--------| | FORRA_GIT_PROJECT | Override the git-project header value | | FORRA_GIT_BRANCH | Override the git-branch header value | | FORRA_GIT_ATTRIBUTION=off (or 0 / false / no) | Skip all header injection |

Environment variables are read at request time.

Graceful degradation

Outside a git repository, or when origin is missing, git headers are omitted and the session continues normally. Session and agent headers are still sent when available. The plugin never throws from the request path.

Development

cd tools/opencode-forra-attribution
npm install
npm test
npm run type-check