Opencode The Token Company Plugin

OpenCode message-transform plugin + sidebar widget for The Token Company (TTC, YC W26).

TTC compresses LLM prompts by removing low-signal tokens based on context and semantic intent. This plugin wires that into OpenCode so bloated context (long file dumps, verbose tool output, repeated boilerplate) gets shrunk before it hits your LLM provider. You keep the same models, just fewer tokens and faster turns.

The sidebar reads redacted per-session metrics from local state. It never stores prompt text, compressed output, request bodies, or API keys.

Requirements

• OpenCode 1.4.0 or newer (uses the @opencode-ai/plugin peer dep)
• Node.js 20 or newer
• A TTC API key from https://thetokencompany.com/

1) Setup

Option A: Agent-assisted

Paste this into your coding agent:

Install @drfok/opencode-ttc-plugin by following: https://raw.githubusercontent.com/MrFok/opencode-ttc-plugin/main/README.md

Option B: Manual

1. Install and register the plugin:

   npm install -g @drfok/opencode-ttc-plugin
   opencode plugin @drfok/opencode-ttc-plugin --global

   On older OpenCode builds that don't support package plugin targets, fall back to the file installer:

   opencode-ttc-plugin install

2. Set your TTC API key. Pick whichever path fits:

   # Plugin-managed (writes to the opencode auth store, mode 0o600)
   opencode-ttc-plugin login                                                   # interactive TTY prompt, echo off
   printf '%s' "$TTC_API_KEY" | opencode-ttc-plugin login --stdin              # non-interactive / CI
   
    # Inside opencode (TUI slash commands)
    /ttc-login                                                                  # shows safe login instructions
    /ttc-logout                                                                 # removes a saved key
   
    # Through opencode's native auth flow (single place to enter the key)
    opencode auth login                                                         # then pick provider: opencode-ttc-plugin

   Only one prompt. Use opencode auth login (choose the TTC provider) or the direct CLI. /ttc-login does not collect the secret in the TUI because the available prompt dialog displays plain text.

   No --key <value> flag. Passing a secret on the command line leaks it via ps aux and shell history. Use --stdin or the TTY prompt.

3. Verify:

   opencode-ttc-plugin doctor --verbose

4. Restart OpenCode. In a session, the sidebar should show Token Compression with the live status dot. Once a key is present it reads authenticated — send a message to start compressing; you don't have to send a message first to clear stale missing auth state.

For LLMs installing this on behalf of a user

1. Install the package with npm:

   npm install -g @drfok/opencode-ttc-plugin

2. Place the plugin file into ~/.config/opencode/plugins:

   opencode-ttc-plugin install

3. Tell the user to set their TTC API key with one of:

   • printf '%s' "$KEY" | opencode-ttc-plugin login --stdin (CLI, recommended for scripts)
   • opencode-ttc-plugin login (CLI interactive prompt, echo off)
   • opencode auth login then choose provider opencode-ttc-plugin

4. Tell the user to get a key from https://thetokencompany.com/ if they don't have one.

5. Verify with opencode-ttc-plugin doctor --verbose.

6. Tell the user to restart OpenCode and watch the sidebar when they start a session.

2) Sidebar

The Token Compression row in the opencode sidebar shows live per-session state.

Status dot colors

| Color | Meaning | | --- | --- | | green | active, skipped, fallback, or no reduction — all normal operating states | | red | missing auth or disabled |

Status line examples

| Status line | What it means | | --- | --- | | active | Last message compressed successfully | | authenticated — send a message to start compressing | Key present, no message has triggered compression yet (overrides stale missing_auth from a previous state file) | | skipped: code fence, below threshold | Last message had parts that were intentionally not compressed, with reason counts | | fallback: request failed open | TTC API errored; original text was passed through unchanged | | no reduction | TTC returned output that wasn't smaller than the input; original used | | missing TTC auth | No API key found — run opencode-ttc-plugin login or opencode auth login (choose provider opencode-ttc-plugin) | | disabled | enabled: false in config | | waiting for metrics | State file not written yet (e.g. brand-new session, no messages) |

The sidebar shows the configured model next to the title. The model shown is exactly what gets sent to the TTC API — it cannot change on its own. If it ever looks wrong, see Troubleshooting.

3) Slash commands

| Command | Action | | --- | --- | | /ttc | Open the Token Compression settings menu (enable/disable, level, aggressiveness, min chars, model, reset) | | /ttc-login | Show safe API-key login instructions (native auth flow or CLI) | | /ttc-logout | Remove the TTC API key (asks for confirmation) |

The /ttc menu shows one auth row: Add API key when no saved key exists, or Remove API key when a key is saved. Add API key opens the same safe instructions as /ttc-login; it does not render a visible secret input.

The model picker is curated from the TTC docs (bear-2, bear-1.2) plus a custom model id escape hatch for enterprise fine-tunes. See Models.

4) CLI reference

opencode-ttc-plugin install                         # place plugin file in ~/.config/opencode/plugins
opencode-ttc-plugin uninstall                       # remove the installed plugin file
opencode-ttc-plugin doctor                          # setup/auth checks
opencode-ttc-plugin doctor --verbose                # show effective config sources + known models + sidebar state path
opencode-ttc-plugin login                           # interactive TTY prompt (echo off), writes key with mode 0o600
opencode-ttc-plugin login --stdin                   # read key from stdin — use for CI: printf '%s' "$KEY" | opencode-ttc-plugin login --stdin
opencode-ttc-plugin logout                          # remove TTC auth entries (current and legacy IDs)
opencode-ttc-plugin config get                      # print plugin config + effective aggressiveness
opencode-ttc-plugin config set level <level>        # low | balanced | high | max
opencode-ttc-plugin config set aggressiveness <n>   # 0..1 numeric
opencode-ttc-plugin config set <setting> <value>    # any behavior setting from the table below
opencode-ttc-plugin config reset                    # remove plugin config file

5) Configuration

All config is optional. Defaults work for most users.

Aggressiveness

The main knob. Higher = more tokens removed.

opencode-ttc-plugin config set level balanced   # recommended
opencode-ttc-plugin config set aggressiveness 0.15   # exact numeric override

| Level | Aggressiveness | Typical use | | --- | --- | --- | | low | 0.05 | Minimal changes — financial, legal, medical | | balanced | 0.10 | Default. Good savings with stable quality | | high | 0.20 | Stronger compression | | max | 0.30 | Most aggressive preset |

Per TTC's docs (https://thetokencompany.com/docs/compression):

• 0.05–0.15 Light — financial reports, legal contracts, medical records
• 0.15–0.4 Moderate — meeting transcripts, call recordings, scraped page content
• 0.4–0.9 Aggressive — chat history summarization, replacing compact

Resolution order: TTC_AGGRESSIVENESS env → ~/.config/opencode/ttc-plugin.json → built-in default (balanced = 0.1).

Behavior settings

CLI config is the normal path; env vars are advanced overrides.

| Setting | Default | What it does | CLI | | --- | --- | --- | --- | | enabled | true | Master on/off switch for the transform hook | config set enabled true | | model | bear-1.2 | TTC model sent to /v1/compress (see Models) | config set model bear-1.2 | | minChars | 400 | Skip compression for text shorter than this | config set min-chars 400 | | timeoutMs | 2000 | Per-request timeout | config set timeout-ms 2000 | | maxRetries | 1 | Retry count for retryable TTC failures (429, 5xx) | config set max-retries 1 | | retryBackoffMs | 100 | Backoff base between retries (linear) | config set retry-backoff-ms 100 | | useGzip | true | gzip the request body to TTC | config set use-gzip true | | compressSystem | false | Also compress eligible system messages | config set compress-system false | | compressHistory | false | Also compress older user turns, not just the latest | config set compress-history false | | debug | false | Emit extra plugin debug logs | config set debug false | | cacheMaxEntries | 1000 | Max in-memory dedupe cache entries | config set cache-max-entries 1000 | | toastOnActive | false | One activation toast per session (sidebar is primary UI) | config set toast-on-active true | | toastOnIdleSummary | false | Idle summary toast with savings stats | config set toast-on-idle-summary true |

The only TTC API parameters this plugin sends are model and compression_settings.aggressiveness. Everything else is plugin-side control.

Env overrides (optional): TTC_ENABLED, TTC_MODEL, TTC_MIN_CHARS, TTC_TIMEOUT_MS, TTC_MAX_RETRIES, TTC_RETRY_BACKOFF_MS, TTC_USE_GZIP, TTC_COMPRESS_SYSTEM, TTC_COMPRESS_HISTORY, TTC_DEBUG, TTC_CACHE_MAX_ENTRIES, TTC_TOAST_ON_ACTIVE, TTC_TOAST_ON_IDLE_SUMMARY, TTC_AGGRESSIVENESS.

6) Models

Per https://thetokencompany.com/docs/compression:

| Model | Status | Notes | | --- | --- | --- | | bear-2 | Recommended | Most accurate compression. Best quality preservation. | | bear-1.2 | Available | Faster compression. Lower latency per request. |

This plugin's default is bear-1.2 to preserve existing behavior. To switch: /ttc → Model → bear-2 (Recommended), or opencode-ttc-plugin config set model bear-2.

There is no TTC API endpoint for listing models at runtime, so the /ttc picker is curated from the docs above plus a custom model id escape hatch for enterprise fine-tunes.

7) What gets compressed

Selection:

• By default, only the latest user turn is compressed (avoids re-compressing unchanged history every turn).
• compressSystem: true adds eligible system messages.
• compressHistory: true adds older user turns.
• assistant messages are never compressed.

Skip patterns (a part that matches is passed through unchanged):

| Reason | What triggers it | | --- | --- | | below threshold | Text shorter than minChars | | code fence | Contains a ``` fence | | diff | Looks like a diff --git blob, +++/---/@@ hunks | | stack trace | Python-style traceback or Exception: line | | JSON | Whole message is a JSON object or array | | schema | JSON Schema markers ($schema, tool_calls, properties, etc.) | | synthetic | Opencode-internal synthetic parts | | empty / non-text | Empty string or non-text part |

These protect content where compression could mangle semantics. They are hardcoded; there is no per-pattern toggle today.

8) Troubleshooting

missing TTC auth after I logged in The sidebar polls the opencode auth store every 2s, so it should clear on its own. If it doesn't, run opencode-ttc-plugin doctor and confirm the key is detected under either opencode-ttc-plugin (new) or the-token-company-plugin (legacy) — both are read.

Sidebar shows a model I didn't configure (e.g. bear-2.0) The sidebar shows exactly what the plugin is configured to send. bear-2.0 is not a real model id. Common causes:

• A model key left in ~/.config/opencode/ttc-plugin.json from a previous /ttc selection
• TTC_MODEL exported in your shell
• A typo from the old free-text prompt

Run opencode-ttc-plugin doctor --verbose to see the effective model and its source. Reset with opencode-ttc-plugin config reset, then re-pick from the curated list via /ttc.

opencode auth login keeps asking for two keys That's expected — one is your LLM provider key (OpenAI/Anthropic/etc), the other is the TTC key. They're separate flows. Use opencode-ttc-plugin login (CLI) or opencode auth login → pick provider opencode-ttc-plugin. There is no separate custom prompt in the TUI.

Compression isn't firing Check the sidebar status line. If it says skipped: ..., the message matched a skip pattern or was below minChars. Lower minChars (config set min-chars 100) or check that your message isn't mostly code/JSON.

Sidebar metrics reset after switching sessions or restarting OpenCode Metrics are keyed by OpenCode session id and persisted under the hashed state path shown by opencode-ttc-plugin doctor --verbose. Switching sessions may show new session or waiting for first compression for sessions TTC has not processed yet, but returning to a processed session should restore its sidebar totals. After restarting OpenCode, the next compression in that session hydrates from the persisted state before writing new totals, so cumulative metrics should not reset.

Doctor says auth store ... set under 'the-token-company-plugin' That's the legacy provider id from before v0.1.5. It still works — the plugin reads both. Your next login writes under the new opencode-ttc-plugin id and also clears the legacy entry; you can logout once to clear the legacy entry if you want a clean store.

A non-TTC provider key disappeared from auth.json The auth store is written with atomic temp+rename (no partial files) but is not serialized across concurrent writers. If you ran opencode-ttc-plugin login at the exact moment opencode auth login was rotating another provider's key, the slower writer wins and the other's update can be dropped. Rare in practice (both are user-initiated, single-shot). Recovery: re-enter the dropped key via opencode auth login.

9) Security and network policy

• Egress pinned to https://api.thetokencompany.com/v1/compress. Custom/invalid TTC_BASE_URL is ignored.
• Redirects rejected. Fetch follows no redirects.
• Auth store writes are atomic. Temp file + rename(2), file mode 0o600, directory mode 0o700. A corrupt existing file is refused, never silently overwritten. A symlink at the target path is replaced, not followed, so a planted symlink can't exfiltrate the key.
• No key in argv. login never accepts --key <value> (would leak via ps aux and shell history). Use the TTY prompt (echo off) or --stdin.
• XDG fallback. A relative or non-absolute XDG_DATA_HOME is ignored and falls back to $HOME/.local/share to prevent the key being written to the working directory.
• Sidebar state is metadata only. Written under ${XDG_STATE_HOME:-~/.local/state}/opencode/ttc-plugin with hashed session filenames. Contains aggregate counts and token/character savings only — no prompts, compressed output, request bodies, or API keys.
• First compression request may trip a firewall prompt. That's expected outbound traffic to api.thetokencompany.com.

License

ISC — see LICENSE.