pi-deepseek-tools

Pi extension that improves DeepSeek V4 behavior in Pi.

It has two scoped feature areas:

1. Direct deepseek provider request compatibility for deepseek-v4-flash and deepseek-v4-pro.
2. opencode-go DeepSeek V4 tool-selection guidance so the model is more likely to use Serena and dedicated Pi file tools instead of defaulting to read, grep, or bash.

The extension does not print prompts, tool schemas, API keys, or response bodies.

Direct DeepSeek payload compatibility

For direct deepseek/deepseek-v4-flash and deepseek/deepseek-v4-pro requests only, the extension rewrites the provider payload immediately before Pi sends it:

• copies max_completion_tokens to DeepSeek's documented max_tokens field and removes max_completion_tokens;
• sets tool_choice: "auto" when tools are present and Pi did not set a tool choice;
• sets reasoning_effort: "max" for tool-enabled requests unless thinking was explicitly disabled.

These payload rewrites are intentionally not applied to opencode-go, because live tests showed opencode-go tool calls already work at the provider-protocol level.

opencode-go DeepSeek tool-selection guidance

For opencode-go/deepseek-v4-flash and opencode-go/deepseek-v4-pro, the extension injects structured, model-specific guidance before each agent turn when relevant tools are active:

• call exactly one of the provided Pi tool names; never invent names such as read_file;
• prefer Serena semantic tools for code-symbol, declaration, reference, implementation, rename, and refactor work;
• use read after Serena identifies the relevant region, or for docs/config/non-code files;
• use ls, grep, or find for exact listing, text search, and filename search;
• use bash only for commands that genuinely need a shell, not as a substitute for dedicated Pi tools;
• for edits, read first if context is needed and then call edit.

The extension also has an optional reminder/strict mode for obvious semantic misses, such as reading code files or running shell code-search commands when Serena tools are active.

Local verification

Run unit tests from the repository root:

npm test --prefix extensions/pi-deepseek-tools

Run the root TypeScript check from the repository root:

npx tsc --noEmit

Enable for testing

Direct DeepSeek provider:

pi -e ./extensions/pi-deepseek-tools/index.ts --provider deepseek --model deepseek-v4-pro

opencode-go DeepSeek:

pi -e ./extensions/pi-deepseek-tools/index.ts --provider opencode-go --model deepseek-v4-pro
pi -e ./extensions/pi-deepseek-tools/index.ts --provider opencode-go --model deepseek-v4-flash

JSON-mode tool-selection smoke test:

pi -e ./extensions/pi-deepseek-tools/index.ts \
  --provider opencode-go --model deepseek-v4-pro --thinking high \
  --mode json --no-session --no-context-files \
  --tools read,bash,grep,find,ls,serena_get_symbols_overview,serena_find_symbol \
  "Inspect symbols in extensions/pi-deepseek-tools/index.ts and summarize them."

Inspect tool_execution_start events in JSON mode. For semantic code prompts, opencode-go DeepSeek should prefer serena_get_symbols_overview, serena_find_symbol, or serena_find_referencing_symbols before raw code reads or shell searches.

DeepSeek vs GPT-5.5 tool-selection eval

Use short, read-only JSON-mode prompts with --no-session --no-context-files. Compare the first tool selected, whether an unavailable tool was hallucinated, whether bash was used where a dedicated tool exists, and whether Serena precedes raw code reads for semantic tasks.

Semantic-symbol prompt with DeepSeek V4 Pro:

pi -e ./extensions/pi-deepseek-tools/index.ts \
  --provider opencode-go --model deepseek-v4-pro --thinking high \
  --mode json --no-session --no-context-files \
  --tools read,bash,grep,find,ls,serena_get_symbols_overview,serena_find_symbol,serena_find_referencing_symbols \
  "Inspect symbols in extensions/pi-deepseek-tools/index.ts and summarize them."

Same prompt with the GPT-5.5 Codex baseline:

pi -e ./extensions/pi-deepseek-tools/index.ts \
  --provider openai-codex --model gpt-5.5 --thinking xhigh \
  --mode json --no-session --no-context-files \
  --tools read,bash,grep,find,ls,serena_get_symbols_overview,serena_find_symbol,serena_find_referencing_symbols \
  "Inspect symbols in extensions/pi-deepseek-tools/index.ts and summarize them."

Suggested eval matrix:

Prompt category	Expected DeepSeek behavior	GPT-5.5 baseline
Inspect symbols in index.ts	First tool is serena_get_symbols_overview or serena_find_symbol.	Same or better.
Find adjustDeepSeekToolPayload definition	Uses serena_find_symbol.	Same or another semantic tool.
Find references before changing behavior	Uses serena_find_referencing_symbols before raw read/search.	Same.
List extension files	Uses ls, not bash.	Same.
Exact env-var search in README/config	Uses grep/read, not Serena.	Same.
Read README	Uses read.	Same.

The guidance is scoped to opencode-go DeepSeek V4 only. It should not change openai-codex/gpt-5.5 behavior; GPT-5.5 is the comparison baseline.

Enable globally

Add the package path to /Users/bacnh/.pi/agent/settings.json:

"../../../../Volumes/Dev/agents/skills/extensions/pi-deepseek-tools"

Then restart Pi or run /reload in an existing session.

Environment variables

Variable	Default	Effect
PI_DEEPSEEK_TOOLS_DEBUG=1	off	Show a concise notification when a direct deepseek payload is adjusted.
PI_DEEPSEEK_TOOLS_MAX_REASONING=0	on	Keep direct-provider payload fixes but avoid forcing reasoning_effort: "max".
PI_DEEPSEEK_TOOLS_SELECTION_GUIDANCE=0	on	Disable opencode-go DeepSeek tool-selection system-prompt guidance.
PI_DEEPSEEK_TOOLS_STRICT_SERENA=1	off	Block obvious semantic-miss read/bash calls for opencode-go DeepSeek when Serena tools are active.

Strict mode is opt-in because normal workflows sometimes legitimately need read or bash.

Scope

Direct payload rewrites apply only when all of the following are true:

• the active provider is deepseek;
• the payload model is deepseek-v4-flash or deepseek-v4-pro;
• the payload is an object shaped like an OpenAI Chat Completions request.

Tool-selection guidance applies only when all of the following are true:

• the active provider is opencode-go;
• the active model is deepseek-v4-flash or deepseek-v4-pro;
• relevant tools are active.

Other models and providers are left unchanged.