just-prompt Documentation

When working with reasoning models (like the OpenAI o-series), use a different prompting mental model than you would for standard GPT models:

• Reasoning Models (Senior Co-worker): Provide high-level goals and objectives. Trust the model to work out the implementation details and logical steps autonomously.
• Standard GPT Models (Junior Co-worker): Provide explicit, precise, and step-by-step instructions to ensure the output matches a specific format or requirement.

For more detailed best practices, refer to the OpenAI reasoning best practices guide.

Reasoning models generate reasoning tokens to "think" through a prompt. While these tokens are not visible in the final response, they have two critical implications:

1. Context Window: Reasoning tokens occupy space in the model's context window. If the model generates too many reasoning tokens, it may hit the context limit.
2. Billing: Reasoning tokens are billed as output tokens.

Important Lifecycle Note: In a multi-step conversation, input and output tokens are carried over to the next turn, but reasoning tokens are discarded by the model after the response is generated. However, when performing function calling, you must include all reasoning items between the function call and the last user message in the next request to maintain the model's reasoning continuity.

For Anthropic Claude models (claude-opus-4-20250514, claude-sonnet-4-20250514, and claude-3-7-sonnet-20250219), you can specify a thinking token budget by adding a suffix to the model name.

Format: provider:model:budget (where budget can be in 'k' notation or exact numbers).

Valid Budgets: 1024 to 16000 tokens.

Examples:

• anthropic:claude-opus-4-20250514:1k (1024 tokens)
• anthropic:claude-sonnet-4-20250514:4k (4096 tokens)
• anthropic:claude-opus-4-20250514:8000 (8000 tokens)

When using prompt_from_file_to_file_w_context, the {{context_files}} placeholder in your prompt file is replaced by an XML block structured as follows:

<context_files>
    <file name="absolute/path/to/file1.py">
        ... file1 content ...
    </file>
    <file name="absolute/path/to/file2.md">
        ... file2 content ...
    </file>
</context_files>

For OpenAI o-series models (o4-mini, o3-mini, o3), you can control the level of internal reasoning by appending a suffix to the model name:

• :low – Minimal reasoning (faster, cheaper)
• :medium – Balanced (default)
• :high – Thorough reasoning (slower, more tokens)

Examples:

• openai:o4-mini:low
• o:o3:high

just-prompt automatically maps these suffixes to the OpenAI reasoning.effort parameter.

o:o4-mini:high
openai:o4-mini:low

After setting up the environment and installing the package, you can verify that the MCP server is working correctly by checking its help output.

uv run just-prompt --help

When performing multiple filtering operations on Gemini models (e.g., filtering for generateContent and embedContent), avoid making redundant network calls. Fetch the model list once, store it in a variable, and reuse that variable for all subsequent filtering logic.

models = client.models.list()

print("List of models that support generateContent:\n")
for m in models:
    # Filter for generateContent
    pass

print("List of models that support embedContent:\n")
for m in models:
    # Filter for embedContent
    pass

To install just-prompt locally, clone the repository and use uv sync to set up the environment.

# Clone the repository
git clone https://github.com/yourusername/just-prompt.git
cd just-prompt

# Install with pip
uv sync

To ensure the ceo_and_board tool is working correctly, you should run the specific test suite and verify the tool is exposed in the MCP server help menu.

Testing commands:

1. Run the unit tests using uv:

uv run pytest src/just_prompt/tests/molecules/test_ceo_and_board_prompt.py

2. Verify the tool is correctly registered in the MCP server by checking the help output:

uv run just-prompt --help

To use just-prompt with Claude Code, you can add it using mcp add-json or mcp add.

Using mcp add-json

Copy the following JSON and paste it into Claude Code (replace the directory path if necessary):

{
    "command": "uv",
    "args": ["--directory", ".", "run", "just-prompt"]
}

Using mcp add with project scope

To add it to a specific project scope:

claude mcp add just-prompt -s project -- uv --directory . run just-prompt

Customizing Default Models

You can use the --default-models flag to specify which models to use when none are provided. This is a comma-separated list. The first model in the list is used for automatic model name correction.

# Example with a custom default model
claude mcp add just-prompt -s project -- uv --directory . run just-prompt --default-models "openai:gpt-4o"

The gemini-2.5-flash-preview-04-17 model supports extended reasoning via a 'thinking budget'. To enable this, append a suffix to the model name using the format gemini:<model_name>:<budget>.

Constraints:

• Only supported for the gemini-2.5-flash-preview-04-17 model.
• Valid budget range is 0 to 24576 tokens.
• Values outside this range are automatically adjusted to fit the valid range.
• You can use 'k' notation (e.g., 1k, 4k) or exact integers (e.g., 1024, 4096).

gemini:gemini-2.5-flash-preview-04-17:1k
gemini:gemini-2.5-flash-preview-04-17:4k
gemini:gemini-2.5-flash-preview-04-17:8000

The server requires API keys for the providers you wish to use. Create a .env file in the project root (you can copy .env.sample to .env) and add your keys:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GEMINI_API_KEY
• GROQ_API_KEY
• DEEPSEEK_API_KEY
• OLLAMA_HOST (e.g., http://localhost:11434)

If a key is missing, the server will still start but the corresponding provider will be listed as unavailable.

OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
GROQ_API_KEY=your_groq_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
OLLAMA_HOST=http://localhost:11434