consultant-cli: A Lightweight Tool to Let AI Assistants Summon Stronger Reasoning Models Anytime

consultant-cli is a command-line tool designed for automated agents (such as Claude Code). Its core goal is to solve the need for developers to quickly obtain suggestions from stronger reasoning models in their existing workflows without switching sessions or modifying environment variables. It supports per-call parameter configuration, capability tag routing, file/image attachments, and is fully pipeline-friendly, providing a flexible and efficient enhancement solution for AI collaboration.

Today, with the popularity of AI-assisted programming and automated workflows, developers often face a dilemma: current AI assistants (like Claude Code) are insufficient in complex reasoning scenarios, and the traditional methods of switching sessions or modifying global variables are cumbersome and disrupt the workflow. consultant-cli was born to allow automated agents to "consult experts" at critical moments without changing their own operating environment.

consultant-cli is designed around four key features:

1. Fine-grained control per call: Allows independent specification of models and reasoning intensity; the same script can flexibly switch between lightweight and deep reasoning modes.
2. Capability tags instead of specific models: Describe requirements via tags like -t reasoning/chinese/vision; the abstraction layer enables flexible switching of underlying models without modifying upper-layer code.
3. Flexible file and image input: Supports --file/--image flags or inline references using @path syntax, meeting both automated and interactive usage needs.
4. Pipeline-friendly output: Answers are output to stdout by default, and the reasoning process is handled independently, allowing seamless integration into the Unix pipeline ecosystem.

Architecture: Adopts a modular design; core modules include cli.py (parameter parsing), tags.py (tag mapping), inputs.py (attachment processing), outputs.py (output management), sessions.py (session persistence), and providers (DeepSeek/OpenRouter clients). Tag Mapping: Maps abstract tags to triples of (provider, model, reasoning intensity). For example, reasoning corresponds to openrouter/openai/gpt-5.5/xhigh; modifying the mapping only requires updating tags.py. Session Persistence: Via the --session NAME parameter, session history is stored in JSONL format at sessions/<NAME>.jsonl. Atomic writes are used to ensure integrity, locking the initial system prompt and requiring tag consistency.

consultant-cli is suitable for multiple scenarios:

1. Code Review and Suggestions: ./consultant -f src/auth.py -f src/db.php "is this safe under concurrent writes?" to get security review opinions in automated scripts.
2. Multilingual Content Generation: ./consultant -t chinese -e max "In-depth review: Are the innovations in this paper sufficient?" to invoke the Chinese capabilities of DeepSeek V4 Pro.
3. Image Understanding and Architecture Analysis: ./consultant -t vision -i diagram.png "explain this architecture" to route to an image-supported model.
4. Iterative Refinement of Complex Tasks: Use the --session parameter to advance creative tasks in stages while maintaining context coherence.

The value of consultant-cli is reflected in:

• Layered Reasoning Architecture: Establishes a lightweight bridge between automated agents and strong reasoning models, externalizing and configuring capability invocation decisions, similar to the concept of microservice orchestration.
• Avoid Vendor Lock-in: Tag abstraction allows switching of underlying model providers without affecting upper-layer business logic, which is beneficial for long-term project maintenance.
• Enhance Existing Toolchains: Does not replace existing tools; instead, it acts as an enhancement layer to work with Claude Code, Cursor, etc., improving workflow efficiency.

consultant-cli provides powerful functions while maintaining simplicity through a concise CLI interface. Its design concepts of per-call control, capability tags, and pipeline-friendliness are worth learning from. For developers building automated workflows, it offers a reference implementation for elegantly upgrading reasoning capabilities. As the multi-model ecosystem matures, this flexible invocation mode will become increasingly important.