shippie

Shippie implements an agentic loop that routes LLM requests to multiple providers (OpenAI, Anthropic, Google, Azure) via a unified model string parser (e.g., 'openai:gpt-4o', 'anthropic:claude-3-5-sonnet'). The agent uses Vercel's AI SDK abstraction layer to normalize provider APIs, then executes tool calls (readFile, readDiff, suggestChanges) in a loop up to a configurable max step limit (default 25). This enables the LLM to autonomously decide which files to inspect and what feedback to provide without pre-fetching all context.

Shippie provides three core tools (readFile, readDiff, suggestChanges) that the LLM agent can invoke autonomously during the review loop. The readFile tool fetches full file contents from the codebase, readDiff retrieves git diffs for changed files, and suggestChanges outputs structured feedback. The agent decides which files to inspect based on the initial diff summary, enabling selective analysis rather than loading all context upfront. Tools are registered via a schema-based function registry compatible with OpenAI and Anthropic function-calling APIs.

Shippie supports review output in multiple languages via the --reviewLanguage CLI flag (default: English). The language preference is passed to the LLM system prompt, instructing it to generate feedback in the specified language. This enables teams in non-English-speaking regions to receive code review feedback in their native language (Spanish, French, German, Japanese, etc.). Language customization is simple (single flag) and works with any LLM provider that supports the target language.

Shippie includes a --debug flag that enables verbose logging of internal operations: LLM API calls, tool invocations, token counts, platform API interactions, and error traces. Debug output is written to stderr and includes timestamps, component names, and detailed error messages. This enables developers to diagnose issues (API failures, tool errors, platform authentication problems) without modifying code. Debug logs include full LLM request/response payloads (sanitized of sensitive data), making it easier to understand LLM behavior and prompt effectiveness.

Shippie supports the --baseUrl flag to override the default LLM provider API endpoint, enabling integration with custom or self-hosted LLM services. This is useful for organizations using Azure OpenAI (which requires a custom endpoint), local LLM servers (e.g., Ollama, vLLM), or proxy services. The baseUrl is passed to the Vercel AI SDK, which routes all LLM requests to the custom endpoint instead of the default provider URL. This enables Shippie to work with any LLM service compatible with OpenAI or Anthropic APIs.

Shippie abstracts Git platform differences (GitHub, GitLab, Azure DevOps) behind a PlatformProvider interface, enabling the same review logic to run on any platform. The system uses platform-specific SDKs (octokit for GitHub, @gitbeaker/rest for GitLab, azure-devops-node-api for Azure) but normalizes their APIs through a common interface. Platform detection is automatic via the --platform CLI flag or GitHub Actions context. Review comments are posted back to the platform using platform-native APIs (PR comments for GitHub, merge request notes for GitLab, etc.).

Shippie includes a languageMap that maps file extensions to programming languages (JavaScript, TypeScript, Python, Go, Rust, C++, Java, etc.), enabling the LLM to apply language-specific review rules. The language context is passed to the LLM prompt, allowing it to understand language idioms, common pitfalls, and best practices. Language detection is automatic based on file extension; no manual configuration required. The system supports 15+ languages including dynamic languages (Python, Ruby, PHP), compiled languages (Go, Rust, C++, Java), and infrastructure-as-code (Terraform, HCL).

Shippie provides a GitHub Action (action.yml) that integrates into GitHub workflows, automatically triggering code review on pull request creation or updates. The action reads PR metadata from GitHub Actions context (PR number, branch, commit), invokes the Shippie review engine, and posts comments back to the PR using the GitHub API. Configuration is via action inputs (platform, modelString, reviewLanguage, maxSteps, baseUrl, debug) that map to CLI arguments. The action handles credential injection (API keys as secrets) and provides structured output (review summary, token usage) for downstream workflow steps.

Shippie uses a prompt-based architecture (src/review/prompt/prompts.ts) where the LLM receives a system prompt defining review criteria, followed by initial file examples (initialFilesExample.ts) that demonstrate the expected review format. The prompt is customizable via configuration files, enabling teams to define organization-specific review rules (e.g., 'flag all console.log statements', 'require JSDoc comments'). The system includes built-in examples showing the LLM how to structure feedback (severity levels, file references, suggested changes). Prompts are language-aware, adapting to the target language (Python, Go, JavaScript, etc.).

Shippie can run locally via CLI (shippie review) to analyze staged git files without CI/CD infrastructure. The local mode uses the LocalProvider to read git diffs from the current repository, invoke the LLM review engine, and output feedback to stdout. This enables developers to run code review on their machine before pushing to CI/CD, catching issues early. The CLI supports all configuration options (modelString, reviewLanguage, maxSteps, debug) as command-line flags, making it scriptable and composable with other tools. Local mode requires no platform credentials (GitHub token, etc.), only LLM API keys.

Shippie includes an interactive setup command (shippie setup) that guides users through platform-specific configuration. The wizard prompts for LLM API keys, platform selection (GitHub, GitLab, Azure DevOps), and creates platform-specific workflow files (.github/workflows/pr.yml for GitHub, .gitlab-ci.yml for GitLab, etc.). It automatically adds API keys as platform secrets (GitHub Secrets, GitLab CI variables, Azure DevOps secrets) without exposing them in configuration files. The setup flow is defined in src/configure/index.ts and supports multiple platforms with minimal user input.

Shippie tracks LLM token consumption during review (input tokens, output tokens, total cost) and reports it in the review summary. The tracking is implemented in src/common/formatting/usage.ts and aggregates token counts from each LLM provider call. Cost is calculated using provider-specific pricing (e.g., GPT-4o input/output rates) and displayed in the review output. This enables teams to monitor API spending and optimize review configurations (e.g., reducing maxSteps to lower costs). Token usage is reported both in CLI output and GitHub Actions job summaries.

Shippie implements a tool registry (src/common/llm/tools/index.ts) where custom analysis tools can be registered and made available to the LLM agent. Tools are defined as functions with schema metadata (name, description, parameters) that the LLM can invoke during the review loop. The built-in tools (readFile, readDiff, suggestChanges) are registered in the same way, making the system fully extensible. New tools can be added by implementing the tool interface and registering them in the tool registry, enabling teams to add custom analysis (e.g., security scanning, performance profiling, dependency checking) without modifying the core agent logic.