Brief

https://github.com/williamagh/brief
Admin
Brief is a terminal-first chat client with a slash-command palette, local tool execution, and OpenAI...
Tokens:9,772
Snippets:80
Trust Score:7.5
Update:8 months ago
Show doc for...
Tokens:
Raw
### Local Development Setup (Bash)

Source: https://github.com/williamagh/brief/blob/dev/docs/environment-variables-api-keys.md

This bash script outlines the steps for setting up a local development environment. It involves copying an example environment file and then running the application using `make run`. The `.env` file is gitignored and only used during local development.

```bash
cp .env-example .env
make run
```

--------------------------------

### Manual Installation and Running Brief

Source: https://context7.com/williamagh/brief/llms.txt

Instructions for manually installing Brief by cloning the repository, setting up environment variables, and building/running the application. Requires Java 25.

```bash
# Download from GitHub releases (requires Java 25)
# https://github.com/WilliamAGH/brief/releases/latest

# Clone and build from source
git clone https://github.com/WilliamAGH/brief.git
cd brief
cp .env-example .env   # Add your API key to .env
make run
```

--------------------------------

### Brief Configuration File Settings (Properties)

Source: https://github.com/williamagh/brief/blob/dev/docs/environment-variables-api-keys.md

This example shows the structure of the Brief configuration file, typically located at `~/.config/brief/config`. It includes settings for the OpenAI API key, base URL, default model, user name, and configuration priority.

```properties
openai.api_key=sk-...
openai.base_url=https://api.openai.com/v1
model=gpt-4o
user.name=Your Name
config.priority=env
```

--------------------------------

### Install Brief using Homebrew (macOS)

Source: https://github.com/williamagh/brief/blob/dev/README.md

This snippet shows how to install the Brief application using the Homebrew package manager on macOS. It then demonstrates how to launch the application. The app will prompt for an API key on first launch, saving it to a configuration file.

```bash
brew install williamagh/tap/brief
brief
```

--------------------------------

### Brief Configuration File Format

Source: https://context7.com/williamagh/brief/llms.txt

Example of the configuration file format for Brief, specifying API keys, base URLs, model names, user information, and summarization settings.

```properties
# ~/.config/brief/config
openai.api_key=sk-your-api-key-here
openai.base_url=https://api.openai.com/v1
model=gpt-4o
user.name=Your Name
config.priority=env

# Optional: Apple Maps for location features
apple_maps.token=your-apple-maps-token

# Summarization settings
summary.disabled=false
summary.target_tokens=8000
```

--------------------------------

### Clone and Run Brief Project

Source: https://github.com/williamagh/brief/blob/dev/README.md

This snippet outlines the steps to clone the Brief project from GitHub, set up the environment by copying an example configuration file and adding an API key, and then run the project using the Make build tool. It also lists available Make commands.

```bash
git clone https://github.com/WilliamAGH/brief.git
cd brief
cp .env-example .env   # add your API key
make run
```

--------------------------------

### Configure LMStudio Local API Endpoint (Bash)

Source: https://github.com/williamagh/brief/blob/dev/docs/environment-variables-api-keys.md

This bash script configures the application to use a local LMStudio instance for serving models. It sets a placeholder API key and the local LMStudio API base URL.

```bash
export OPENAI_API_KEY="lm-studio"
export OPENAI_BASE_URL="http://localhost:1234/v1"
```

--------------------------------

### Configure OpenRouter API Endpoint (Bash)

Source: https://github.com/williamagh/brief/blob/dev/docs/environment-variables-api-keys.md

This bash script configures the application to use OpenRouter as an alternative API provider. It sets the API key and the custom base URL for OpenRouter, along with a specific model.

```bash
export OPENAI_API_KEY="sk-or-..."
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export LLM_MODEL="anthropic/claude-sonnet-4-20250514"
```

--------------------------------

### Configure Ollama Local API Endpoint (Bash)

Source: https://github.com/williamagh/brief/blob/dev/docs/environment-variables-api-keys.md

This bash script configures the application to use a local Ollama instance for serving models. It sets a placeholder API key and the local Ollama API base URL, along with a specified model. Requires `ollama serve` and `ollama pull <model>` to be run beforehand.

```bash
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"
export LLM_MODEL="llama3.2"
```

--------------------------------

### Set OpenAI API Key via Environment Variable (Bash)

Source: https://github.com/williamagh/brief/blob/dev/docs/environment-variables-api-keys.md

This snippet demonstrates how to set the OpenAI API key using an environment variable in a bash shell. This is a common method for providing credentials to applications that interact with OpenAI-compatible APIs.

```bash
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Configure and Use OpenAI Client in Java

Source: https://context7.com/williamagh/brief/llms.txt

Demonstrates how to initialize the OpenAiService with configuration, access the underlying OpenAI client, retrieve the base URL, and discover available models. It also shows how to use the client directly for API calls.

```java
import com.williamcallahan.chatclient.Config;
import com.williamcallahan.chatclient.service.OpenAiService;
import com.openai.client.OpenAIClient;
import java.util.List;

// Initialize with config
Config config = new Config();
OpenAiService openAiService = new OpenAiService(config);

// Get the underlying OpenAI client
OpenAIClient client = openAiService.client();

// Get configured base URL (null for default)
String baseUrl = openAiService.baseUrl();

// Discover available models from the API
List<String> availableModels = openAiService.modelChoices();
// Returns: ["gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo", ...]

// Use the client directly for API calls
var response = client.chat().completions().create(params);
```

--------------------------------

### Build and Development Commands (Bash)

Source: https://context7.com/williamagh/brief/llms.txt

Provides Make commands for building, running, testing, and releasing the Brief application. These commands streamline the development workflow, including local development and distribution packaging.

```bash
# Build and run the application
make run

# Build only (creates ./build/install/brief/bin/brief)
make build

# Clean build artifacts
make clean

# Build distribution zip
make dist

# Test a release build
make release-test V=0.1.0

# Create and push a release tag
make release V=0.1.0

# Run with local TUI4J development build
make run-local-tui

```

--------------------------------

### Brief Config Class API Usage (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Demonstrates how to use the `Config` class in Java to manage user preferences for Brief. It covers loading configuration, resolving settings, checking for existence, and getting/setting various preferences like API keys, model names, and summarization options.

```java
import com.williamcallahan.chatclient.Config;

// Create config instance (loads from ~/.config/brief/config)
Config config = new Config();

// Resolve settings (respects env vs config priority)
String apiKey = config.resolveApiKey();      // OPENAI_API_KEY or openai.api_key
String baseUrl = config.resolveBaseUrl();    // OPENAI_BASE_URL or openai.base_url
String model = config.resolveModel();        // LLM_MODEL or model
String appleMapsToken = config.resolveAppleMapsToken();

// Check if settings exist
boolean hasKey = config.hasResolvedApiKey();
boolean hasMaps = config.hasAppleMapsToken();
boolean hasName = config.hasUserName();

// Get/set user preferences (persisted to config file)
String userName = config.userName();
config.setUserName("Alice");
config.setModel("gpt-4o-mini");
config.setApiKey("sk-new-key");
config.setBaseUrl("https://api.openai.com/v1");

// Summary settings
boolean summaryEnabled = config.isSummaryEnabled();
int targetTokens = config.getSummaryTargetTokens();
config.setSummaryDisabled(false);
config.setSummaryTargetTokens(8000);

// Check priority mode
Config.Priority priority = config.priority();  // ENV or CONFIG
```

--------------------------------

### OpenRouter Configuration for Brief

Source: https://context7.com/williamagh/brief/llms.txt

Sets environment variables for using OpenRouter with Brief, including API key, base URL, and a specific model.

```bash
export OPENAI_API_KEY="sk-or-your-openrouter-key"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export LLM_MODEL="anthropic/claude-sonnet-4-20250514"
```

--------------------------------

### Brief Environment Variables Configuration

Source: https://context7.com/williamagh/brief/llms.txt

Demonstrates how to configure Brief using environment variables for API keys, base URLs, model selection, and display options. Supports overriding config file settings.

```bash
# Required - API key for OpenAI or compatible provider
export OPENAI_API_KEY="sk-your-key-here"

# Optional - Custom endpoint for alternative providers
export OPENAI_BASE_URL="https://api.openai.com/v1"

# Optional - Default model selection
export LLM_MODEL="gpt-4o"

# Optional - Priority: "env" (default) or "config"
export BRIEF_CONFIG_PRIORITY="env"

# Optional - Apple Maps integration
export APPLE_MAPS_TOKEN="your-apple-maps-token"

# Display options
export BRIEF_ALT_SCREEN=1     # Use alternate screen buffer
export BRIEF_MOUSE=select     # Mouse mode: select, 1, 0
export BRIEF_SHOW_TOOLS=1     # Show tool call messages
export BRIEF_SCROLLBACK=1     # Print to terminal scrollback
```

--------------------------------

### Ollama (Local) Configuration for Brief

Source: https://context7.com/williamagh/brief/llms.txt

Configures Brief to use a local Ollama instance for AI model interaction, specifying API key, local base URL, and model name. Assumes Ollama is running and the model is pulled.

```bash
# Requires: ollama serve && ollama pull llama3.2
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"
export LLM_MODEL="llama3.2"
```

--------------------------------

### Execute LLM Tools within a Conversation Loop in Java

Source: https://context7.com/williamagh/brief/llms.txt

Shows how to set up and use the ToolExecutor to handle LLM tool calls. It covers registering tools, creating a conversation, adding user messages, and obtaining responses where the executor automatically manages tool execution.

```java
import com.williamcallahan.chatclient.Config;
import com.williamcallahan.chatclient.domain.Conversation;
import com.williamcallahan.chatclient.service.*;
import com.williamcallahan.chatclient.service.tools.*;
import java.util.List;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;

// Set up services
Config config = new Config();
OpenAiService openAiService = new OpenAiService(config);
ChatCompletionService chatService = new ChatCompletionService(openAiService);

// Register tools
List<Tool> tools = List.of(
    new WeatherForecastTool()
    // Add PlaceSearchTool and GeocodeAddressTool if Apple Maps is configured
);

ToolExecutor executor = new ToolExecutor(chatService, tools);

// Create a conversation
Conversation conversation = Conversation.builder()
    .id("conv_001")
    .createdAt(OffsetDateTime.now(ZoneOffset.UTC))
    .updatedAt(OffsetDateTime.now(ZoneOffset.UTC))
    .defaultModel("gpt-4o")
    .build();

// Add a user message asking about weather
conversation.addMessage(new ChatMessage(
    "msg_001", conversation.getId(), 0,
    Role.USER, ChatMessage.Source.USER_INPUT,
    "What's the weather like in San Francisco?",
    OffsetDateTime.now(ZoneOffset.UTC),
    "gpt-4o", "openai", null, null, null, null, null
));

// Get response (executor handles tool calls automatically)
String response = executor.respond(conversation, "gpt-4o");
// The executor will:
// 1. Send the message to the LLM
// 2. If LLM requests get_weather_forecast tool, execute it
// 3. Return tool results to LLM
// 4. Return final text response

System.out.println(response);
// Output: "The current weather in San Francisco is 62°F with partly cloudy skies..."
```

--------------------------------

### Use WeatherForecastTool for Weather Information (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Shows how to use the built-in `WeatherForecastTool` to retrieve weather forecasts. This tool requires instantiation and then can be executed with arguments such as city, days, country code, and admin1. The output is a map containing current weather conditions and a forecast list.

```java
import com.williamcallahan.chatclient.service.tools.WeatherForecastTool;
import java.util.Map;

WeatherForecastTool weatherTool = new WeatherForecastTool();

// Tool name for LLM function calling
String name = weatherTool.name();  // "get_weather_forecast"

// Execute the tool with arguments
Map<String, Object> args = Map.of(
    "city", "San Francisco",
    "days", 5,
    "country_code", "US",
    "admin1", "California"
);

Object result = weatherTool.execute(args);
// Returns a Map with structure:
// {
//   "current": {
//     "location": "San Francisco, United States",
//     "temp_F": 62.5,
//     "wind_mph": 12,
//     "condition": "Partly cloudy"
//   },
//   "forecast": [
//     {"date": "2024-01-15", "high_F": 65.0, "low_F": 52.0, "condition": "Clear sky"},
//     {"date": "2024-01-16", "high_F": 63.0, "low_F": 50.0, "condition": "Mainly clear"},
//     ...
//   ]
// }
```

--------------------------------

### Implement Custom Tool Interface for LLM Function Calling (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Demonstrates how to implement the `Tool` interface in Java to create custom tools for LLM function calling. This involves defining the tool's name, its function definition (including parameters and descriptions), and the execution logic. Dependencies include `com.williamcallahan.chatclient.service.tools.Tool` and OpenAI client libraries.

```java
import com.williamcallahan.chatclient.service.tools.Tool;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.core.JsonValue;
import java.util.List;
import java.util.Map;

public class CustomTool implements Tool {

    @Override
    public String name() {
        return "my_custom_tool";
    }

    @Override
    public FunctionDefinition definition() {
        Map<String, Object> props = Map.of(
            "query", Map.of(
                "type", "string",
                "description", "The search query"
            ),
            "limit", Map.of(
                "type", "integer",
                "description", "Maximum results to return",
                "default", 10
            )
        );

        return FunctionDefinition.builder()
            .name(name())
            .description("Search for items matching the query")
            .parameters(
                FunctionParameters.builder()
                    .putAdditionalProperty("type", JsonValue.from("object"))
                    .putAdditionalProperty("properties", JsonValue.from(props))
                    .putAdditionalProperty("required", JsonValue.from(List.of("query")))
                    .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                    .build()
            )
            .build();
    }

    @Override
    public Object execute(Map<String, Object> arguments) throws Exception {
        String query = (String) arguments.get("query");
        int limit = arguments.containsKey("limit")
            ? ((Number) arguments.get("limit")).intValue()
            : 10;

        // Perform the search and return results
        return Map.of(
            "query", query,
            "results", List.of("result1", "result2"),
            "count", 2
        );
    }
}
```

--------------------------------

### Use PlaceSearchTool for Location Search (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Demonstrates the usage of `PlaceSearchTool` for searching places and businesses using Apple Maps integration. It requires an `AppleMaps` client instance, initialized with an API token. The tool is executed with a query and country code, returning a list of results with details like name, address, category, and coordinates.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.chatclient.service.tools.PlaceSearchTool;
import java.util.Map;

// Requires Apple Maps token
String token = System.getenv("APPLE_MAPS_TOKEN");
AppleMaps client = new AppleMaps(token);
PlaceSearchTool searchTool = new PlaceSearchTool(client);

// Search for places
Map<String, Object> args = Map.of(
    "query", "coffee shops in San Francisco",
    "country_code", "US"
);

Object result = searchTool.execute(args);
// Returns:
// {
//   "query": "coffee shops in San Francisco",
//   "count": 10,
//   "results": [
//     {
//       "name": "Blue Bottle Coffee",
//       "address": "66 Mint St, San Francisco, CA 94103",
//       "category": "Coffee Shop",
//       "latitude": 37.7821,
//       "longitude": -122.4062,
//       "place_id": "..."
//     },
//     ...
//   ]
// }
```

--------------------------------

### Perform Chat Completions with Simplified Java Methods

Source: https://context7.com/williamagh/brief/llms.txt

Illustrates how to use the ChatCompletionService to perform simple text completions or more complex chat completions with detailed parameters. It wraps the OpenAI chat completions API for easier use.

```java
import com.williamcallahan.chatclient.Config;
import com.williamcallahan.chatclient.service.ChatCompletionService;
import com.williamcallahan.chatclient.service.OpenAiService;
import com.openai.models.chat.completions.*;
import java.util.List;

// Initialize services
Config config = new Config();
OpenAiService openAiService = new OpenAiService(config);
ChatCompletionService chatService = new ChatCompletionService(openAiService);

// Simple text completion
String response = chatService.complete(
    "Explain quantum computing in one sentence.",
    "gpt-4o-mini"
);
// Returns: "Quantum computing uses quantum bits that can exist in multiple states..."

// Full completion with parameters
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("gpt-4o")
    .temperature(0.7)
    .messages(List.of(
        ChatCompletionMessageParam.ofSystem(
            ChatCompletionSystemMessageParam.builder()
                .content("You are a helpful assistant.")
                .build()
        ),
        ChatCompletionMessageParam.ofUser(
            ChatCompletionUserMessageParam.builder()
                .content("What is the capital of France?")
                .build()
        )
    ))
    .build();

ChatCompletion completion = chatService.complete(params);
String answer = completion.choices().get(0).message().content().orElse("");
// Returns: "The capital of France is Paris."
```

--------------------------------

### Slash Commands Overview (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Lists available slash commands for quick actions within the Brief application. These commands are implemented via the `SlashCommand` interface and provide various functionalities from weather forecasts to application control.

```java
// Available slash commands in Brief:
// /weather [location]  - Get weather forecast
// /locate [query]      - Search places with Apple Maps
// /model               - Switch AI model
// /config              - Edit settings
// /new                 - Start new conversation
// /clear               - Clear conversation
// /about               - Show app info
// /quit                - Exit application

```

--------------------------------

### SummaryService Functionality (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Handles automatic summarization of long pastes and context window management using `SummaryService`. It requires `Config`, `OpenAiService`, and `ChatCompletionService`. It processes pastes, trims conversations to fit context windows, and provides access to summarization settings.

```java
import com.williamcallahan.chatclient.Config;
import com.williamcallahan.chatclient.domain.Conversation;
import com.williamcallahan.chatclient.service.*;

Config config = new Config();
OpenAiService openAiService = new OpenAiService(config);
ChatCompletionService chatService = new ChatCompletionService(openAiService);
SummaryService summaryService = new SummaryService(chatService, config);

// Process a paste (summarizes if over ~8k tokens)
String longText = "...very long pasted content...";
SummaryService.PasteSummary result = summaryService.processPaste(longText, 1);
String displayText = result.displayText();  // "[Pasted text 1 (summarized)]"
String actualText = result.actualText();    // Summarized content sent to LLM
boolean wasSummarized = result.wasSummarized();
boolean wasTruncated = result.wasTruncated();

// Trim conversation if context window is exceeded
SummaryService.TrimResult trimResult = summaryService.trimIfNeeded(
    conversation,
    "gpt-4o",
    4000  // Reserve tokens for response
);

// Check settings
boolean enabled = summaryService.isSummaryEnabled();
int targetTokens = summaryService.getTargetTokens();

```

--------------------------------

### Conversation and ChatMessage Domain Model (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Models the conversation state using `Conversation` and `ChatMessage` classes. It allows for creating conversations, adding messages with various roles and sources, and accessing conversation details. Dependencies include domain classes and Java time utilities.

```java
import com.williamcallahan.chatclient.domain.*;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.util.UUID;

// Create a new conversation
Conversation conversation = Conversation.builder()
    .id("c_" + UUID.randomUUID())
    .createdAt(OffsetDateTime.now(ZoneOffset.UTC))
    .updatedAt(OffsetDateTime.now(ZoneOffset.UTC))
    .provider(Conversation.Provider.OPENAI)
    .apiFamily(Conversation.ApiFamily.CHAT_COMPLETIONS)
    .defaultModel("gpt-4o")
    .build();

// Add messages to the conversation
ChatMessage userMessage = new ChatMessage(
    "msg_001",                              // id
    conversation.getId(),                   // conversationId
    0,                                      // index
    Role.USER,                              // role
    ChatMessage.Source.USER_INPUT,          // source
    "Hello, how are you?",                  // content
    OffsetDateTime.now(ZoneOffset.UTC),     // createdAt
    "gpt-4o",                               // model
    "openai",                               // provider
    null,                                   // providerMessageId
    null,                                   // toolCalls
    null,                                   // toolCallId
    null,                                   // usage
    null                                    // error
);
conversation.addMessage(userMessage);

// Access conversation state
String model = conversation.getDefaultModel();
int messageCount = conversation.getMessages().size();
ChatMessage lastMessage = conversation.getMessages().get(messageCount - 1);

// Message sources:
// - USER_INPUT: User typed message
// - LLM_OUTPUT: Assistant response
// - SYSTEM: System prompts
// - TOOL_OUTPUT: Tool execution results
// - INTERNAL: Hidden context messages
// - LOCAL: Local display only (not sent to LLM)

```

--------------------------------

### Use GeocodeAddressTool for Address to Coordinates (Java)

Source: https://context7.com/williamagh/brief/llms.txt

Illustrates how to use `GeocodeAddressTool` for converting addresses into geographic coordinates using Apple Maps. Similar to `PlaceSearchTool`, it requires an initialized `AppleMaps` client. The tool takes an address and country code as input and returns detailed address components along with latitude and longitude.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.chatclient.service.tools.GeocodeAddressTool;
import java.util.Map;

String token = System.getenv("APPLE_MAPS_TOKEN");
AppleMaps client = new AppleMaps(token);
GeocodeAddressTool geocodeTool = new GeocodeAddressTool(client);

// Geocode an address
Map<String, Object> args = Map.of(
    "address", "880 Harrison St, San Francisco, CA 94107",
    "country_code", "US"
);

Object result = geocodeTool.execute(args);
// Returns:
// {
//   "query": "880 Harrison St, San Francisco, CA 94107",
//   "count": 1,
//   "results": [
//     {
//       "formatted_address": "880 Harrison St, San Francisco, CA 94107",
//       "address_components": {
//         "street": "880 Harrison St",
//         "city": "San Francisco",
//         "state": "CA",
//         "postal_code": "94107"
//       },
//       "latitude": 37.7784,
//       "longitude": -122.3982,
//       "place_id": "..."
//     }
//   ]
// }
```
Tokens:
Raw