opencode-leaner

An opencode plugin that reduces the context sent to the model — shorter tool descriptions and lean agent definitions (some of them are more like experiments).

Features

Trimmed tool descriptions

Opencode's builtin tool descriptions are verbose. The plugin hooks tool.definition and replaces/trim the descriptions of tools with short, minimal versions (see src/tools/*.txt)

The rules applied "the tools should have the essential to execute the tool, other instructions should be pruned from tools".

Examples:

• "Use gh for GitHub tasks, including PRs, issues, checks, and releases; return the PR URL when done." from bash/shell tool - it should not be in the shell/bash tool description, it is too specific and out of the scope of the tool description or usage.

• "ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required." from write tool - if need this, it should be a agents.md or custom agent prompt instruction.

• "Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked." from write tool - if need this, it should be a agents.md or custom agent prompt instruction. This sentence overlap if other tools and system prompt too.

Tool parameters, output format, truncation caps, and permission prompts are untouched — only the description text changes.

Lean agents

The plugin hooks config and injects five agent definitions (defined in src/agents as markdown with YAML frontmatter):

[1] Tokens at start was calculated in a empty folder, with not project or personal AGENTS.md, and but with various skills (about ~2600 tokens in skill descriptions). Base Build agent in the same enviroment uses ~10,300 tokens.

If an agent with the same id already exists in your config, the plugin's definition is deep-merged over it (your config wins on conflict).

Set OPENCODE_LEANER_AGENT_PREFIX surpass the conflicts name, e.g. OPENCODE_LEANER_AGENT_PREFIX=lean inject lean-bash instead of bash.

Install

Npm package

Register the plugin in your opencode config (e.g. opencode.json):

{
  "plugin": ["opencode-leaner"]
}

Manual

git clone <repo-url> opencode-leaner
cd opencode-leaner
bun install

Register the plugin in your opencode config (e.g. opencode.json), pointing at the plugin entrypoint:

{
  "plugin": ["file:///absolute/path/to/opencode-leaner/index.ts"]
}

Development

# Typecheck
bunx tsc

# Run the log proxy
bun run log-proxy

There is no test suite yet; validate by loading the plugin in opencode and inspecting the debug context dump or the proxy log.

Debug context

With OPENCODE_LEANER_DEBUG_CONTEXT=1, the plugin appends the outgoing messages, system prompt, chat params, and headers for every request to a file (default: /tmp/opencode-context-debug.txt), so you can inspect offline what was actually sent to the model.

Log proxy

scripts/log-proxy.mjs is a small Bun HTTP proxy for OpenAI-compatible endpoints. It forwards requests to an upstream server and logs the (pretty-printed) request body — and optionally the response — to a file. Useful for measuring context size at the wire level.

Configuration

All options are environment variables read by the plugin (and the log proxy):

License

MIT