tgpt

Tgpt implements a multi-provider abstraction layer that routes requests to free AI providers (Phind, Isou, KoboldAI) without requiring API keys, while also supporting optional API-key-based providers (OpenAI, Gemini, Deepseek, Groq) and self-hosted Ollama. The architecture uses a provider registry pattern where each provider implements a common interface for request/response handling, enabling transparent switching between free and paid backends based on user configuration or environment variables (AI_PROVIDER, AI_API_KEY).

Tgpt maintains conversation state across multiple turns using two interactive modes: normal interactive (-i/--interactive) for single-line input with command history, and multiline interactive (-m/--multiline) for editor-like input. The architecture preserves previous messages in memory (PrevMessages field in Params structure) and passes them to the AI provider with each new request, enabling the model to maintain context across turns. This is implemented via the interactive loop in main.go (lines 319-425) which accumulates messages and manages the conversation thread.

Tgpt's image generation mode supports generating multiple images in a single request via ImgCount parameter, with customizable dimensions (Width, Height) and aspect ratios (ImgRatio). The ImageParams structure enables fine-grained control over generation parameters, and the imagegen module handles batch processing and disk output. Multiple images are saved with sequential naming (e.g., image_1.png, image_2.png) to the specified output directory (Out parameter).

Supports local AI model inference via Ollama, a self-hosted model runner that allows users to run open-source models (Llama, Mistral, etc.) on their own hardware. The implementation treats Ollama as a provider in the registry, routing requests to a local Ollama instance via HTTP API. This enables offline operation and full data privacy, as all inference happens locally without sending data to external providers.

Supports configuration through multiple channels: command-line flags (e.g., -p/--provider, -k/--api-key), environment variables (AI_PROVIDER, AI_API_KEY), and configuration files (tgpt.json). The system implements a precedence hierarchy where CLI flags override environment variables, which override config file settings. This enables flexible configuration for different use cases (single invocation, session-wide, or persistent).

Supports HTTP/HTTPS proxy configuration via environment variables (HTTP_PROXY, HTTPS_PROXY) or configuration files, enabling tgpt to route requests through corporate proxies or VPNs. The system integrates proxy settings into the HTTP client initialization, allowing transparent proxy support without code changes. This is essential for users in restricted network environments.

Tgpt's code generation mode (-c/--code) routes prompts to AI providers with a specialized preprompt that instructs models to generate code, then applies syntax highlighting to the output based on detected language. The implementation uses the helper module (src/helper/helper.go) to parse code blocks from responses and apply terminal color formatting. The Preprompt field in Params structure allows customization of the system message, enabling code-specific instructions to be injected before the user's prompt.

Tgpt's shell command mode (-s/--shell) generates executable shell commands from natural language descriptions by routing prompts through AI providers with shell-specific preprompts. The architecture separates generation from execution — commands are displayed to the user for review before running, preventing accidental execution of potentially dangerous commands. The implementation uses the Preprompt field to inject instructions that guide models toward generating safe, idiomatic shell syntax.

Tgpt's image generation mode (-img/--image) routes text descriptions to image generation providers (Pollinations by default, Arta as alternative) via the imagegen module (src/imagegen/imagegen.go). The architecture uses ImageParams structure to configure generation parameters (ImgRatio, ImgNegativePrompt, ImgCount, Width, Height, Out) and supports multiple model options within Arta provider. Generated images are saved to disk (Out parameter specifies path) or displayed via terminal image protocols if supported.

Tgpt supports piping stdin into prompts, enabling users to provide context (code snippets, error messages, file contents) alongside natural language questions. The architecture reads from stdin when available and concatenates it with command-line arguments before sending to AI providers. This is implemented in main.go's argument handling (lines 209-453) which checks for piped input and merges it with explicit prompt text, allowing seamless integration with Unix pipes and command chaining.

Tgpt is distributed as pre-compiled binaries for Linux, macOS, Windows, and FreeBSD, with a built-in self-update mechanism (-u/--update flag) that checks for new versions and updates the binary in-place. The architecture uses GitHub releases as the distribution source and implements version checking logic (version.txt file) to determine if updates are available. Installation is supported via multiple package managers (Arch Linux, FreeBSD, Scoop, Chocolatey) and direct download scripts, enabling zero-friction deployment across platforms.

Tgpt allows configuration of AI model behavior through command-line flags, environment variables (AI_PROVIDER, AI_API_KEY), and configuration files (tgpt.json). The Params structure includes fields for ApiKey, ApiModel, Temperature, Top_p, Max_length enabling fine-grained control over model behavior. The architecture supports hierarchical configuration: command-line flags override environment variables, which override config file settings, enabling both global defaults and per-invocation customization.

Tgpt streams AI responses in real-time to the terminal by default, displaying a loading animation while waiting for the provider. The quiet mode (-q/--quiet) suppresses the loading animation for cleaner output in scripts or piped contexts. The whole text mode (-w/--whole) returns the complete response as a single block instead of streaming, useful for processing or piping output to other commands. The implementation uses streaming APIs from providers when available, with fallback to buffered output for providers that don't support streaming.

Tgpt uses a modular architecture where each AI provider (Phind, Isou, KoboldAI, OpenAI, Gemini, Deepseek, Groq, Ollama) implements a common interface for request/response handling. The core logic in main.go routes requests to provider-specific modules based on the AI_PROVIDER setting, enabling new providers to be added without modifying core code. The architecture separates concerns: CLI argument parsing (main.go), business logic (helper.go), image generation (imagegen.go), and provider implementations (separate modules per provider).