automaker/.planning/codebase/INTEGRATIONS.md

External Integrations

Analysis Date: 2026-01-27

APIs & External Services

AI/LLM Providers:

• Claude (Anthropic)

  • SDK: @anthropic-ai/claude-agent-sdk (0.1.76)
  • Auth: ANTHROPIC_API_KEY environment variable or stored credentials
  • Features: Extended thinking, vision/images, tools, streaming
  • Implementation: apps/server/src/providers/claude-provider.ts
  • Models: Opus 4.5, Sonnet 4, Haiku 4.5, and legacy models
  • Custom endpoints: ANTHROPIC_BASE_URL (optional)

• GitHub Copilot

  • SDK: @github/copilot-sdk (0.1.16)
  • Auth: GitHub OAuth (via gh CLI) or GITHUB_TOKEN environment variable
  • Features: Tools, streaming, runtime model discovery
  • Implementation: apps/server/src/providers/copilot-provider.ts
  • CLI detection: Searches for Copilot CLI binary
  • Models: Dynamic discovery via copilot models list

• OpenAI Codex/GPT-4

  • SDK: @openai/codex-sdk (0.77.0)
  • Auth: OPENAI_API_KEY environment variable or stored credentials
  • Features: Extended thinking, tools, sandbox execution
  • Implementation: apps/server/src/providers/codex-provider.ts
  • Execution modes: CLI (with sandbox) or SDK (direct API)
  • Models: Dynamic discovery via Codex CLI or SDK

• Google Gemini

  • Implementation: apps/server/src/providers/gemini-provider.ts
  • Features: Vision support, tools, streaming

• OpenCode (AWS/Azure/other)

  • Implementation: apps/server/src/providers/opencode-provider.ts
  • Supports: Amazon Bedrock, Azure models, local models
  • Features: Flexible provider architecture

• Cursor Editor

  • Implementation: apps/server/src/providers/cursor-provider.ts
  • Features: Integration with Cursor IDE

Model Context Protocol (MCP):

• SDK: @modelcontextprotocol/sdk (1.25.2)
• Purpose: Connect AI agents to external tools and data sources
• Implementation: apps/server/src/services/mcp-test-service.ts, apps/server/src/routes/mcp/
• Configuration: Per-project in .automaker/ directory

Data Storage

Databases:

• None - This codebase does NOT use traditional databases (SQL/NoSQL)
• All data stored as files in local filesystem

File Storage:

• Local filesystem only
• Locations:
  • .automaker/ - Project-specific data (features, context, settings)
  • ./data/ or DATA_DIR env var - Global data (settings, credentials, sessions)
• Secure file operations: @automaker/platform exports secureFs for restricted file access

Caching:

• In-memory caches for:
  • Model lists (Copilot, Codex runtime discovery)
  • Feature metadata
  • Project specifications
• No distributed/persistent caching system

Authentication & Identity

Auth Provider:

• Custom implementation (no third-party provider)
• Authentication methods:
  1. Claude Max Plan (OAuth via Anthropic CLI)
  2. API Key mode (ANTHROPIC_API_KEY)
  3. Custom provider profiles with API keys
  4. Token-based session authentication for WebSocket

Implementation:

• apps/server/src/lib/auth.ts - Auth middleware
• apps/server/src/routes/auth/ - Auth routes
• Session tokens for WebSocket connections
• Credential storage in ./data/credentials.json (encrypted/protected)

Monitoring & Observability

Error Tracking:

• None - No automatic error reporting service integrated
• Custom error classification: @automaker/utils exports classifyError()
• User-friendly error messages: getUserFriendlyErrorMessage()

Logs:

• Console logging with configurable levels
• Logger: @automaker/utils exports createLogger()
• Log levels: ERROR, WARN, INFO, DEBUG
• Environment: LOG_LEVEL env var (optional)
• Storage: Logs output to console/stdout (no persistent logging to files)

Usage Tracking:

• Claude API usage: apps/server/src/services/claude-usage-service.ts
• Codex API usage: apps/server/src/services/codex-usage-service.ts
• Tracks: Tokens, costs, rates

CI/CD & Deployment

Hosting:

• Local development: Node.js server + Vite dev server
• Desktop: Electron application (macOS, Windows, Linux)
• Web: Express server deployed to any Node.js host

CI Pipeline:

• GitHub Actions likely (.github/workflows/ present in repo)
• Testing: Playwright E2E, Vitest unit tests
• Linting: ESLint
• Formatting: Prettier

Build Process:

• npm run build:packages - Build shared packages
• npm run build - Build web UI
• npm run build:electron - Build Electron apps (platform-specific)
• Electron Builder handles code signing and distribution

Environment Configuration

Required env vars:

• ANTHROPIC_API_KEY - For Claude provider (or provide in settings)
• OPENAI_API_KEY - For Codex provider (optional)
• GITHUB_TOKEN - For GitHub operations (optional)

Optional env vars:

• PORT - Server port (default 3008)
• HOST - Server bind address (default 0.0.0.0)
• HOSTNAME - Public hostname (default localhost)
• DATA_DIR - Data storage directory (default ./data)
• ANTHROPIC_BASE_URL - Custom Claude endpoint
• ALLOWED_ROOT_DIRECTORY - Restrict file operations to directory
• AUTOMAKER_MOCK_AGENT - Enable mock agent for testing
• AUTOMAKER_AUTO_LOGIN - Skip login prompt in dev

Secrets location:

• Runtime: Environment variables (process.env)
• Stored: ./data/credentials.json (file-based)
• Retrieval: apps/server/src/services/settings-service.ts

Webhooks & Callbacks

Incoming:

• WebSocket connections for real-time agent event streaming
• GitHub webhook routes (optional): apps/server/src/routes/github/
• Terminal WebSocket connections: apps/server/src/routes/terminal/

Outgoing:

• GitHub PRs: apps/server/src/routes/worktree/routes/create-pr.ts
• Git operations: @automaker/git-utils handles commits, pushes
• Terminal output streaming via WebSocket to clients
• Event hooks: apps/server/src/services/event-hook-service.ts

Credential Management

API Keys Storage:

• File: ./data/credentials.json
• Format: JSON with nested structure for different providers

  {
    "apiKeys": {
      "anthropic": "sk-...",
      "openai": "sk-...",
      "github": "ghp_..."
    }
  }
  

• Access: SettingsService.getCredentials() from apps/server/src/services/settings-service.ts
• Security: File permissions should restrict to current user only

Profile/Provider Configuration:

• File: ./data/settings.json (global) or .automaker/settings.json (per-project)
• Stores: Alternative provider profiles, model mappings, sandbox settings
• Types: ClaudeApiProfile, ClaudeCompatibleProvider from @automaker/types

Third-Party Service Integration Points

Git/GitHub:

• @automaker/git-utils - Git operations (worktrees, commits, diffs)
• Codex/Cursor providers can create GitHub PRs
• GitHub CLI (gh) detection for Copilot authentication

Terminal Access:

• node-pty (1.1.0-beta41) - Pseudo-terminal interface
• TerminalService manages terminal sessions
• WebSocket streaming to frontend

AI Models - Multi-Provider Abstraction:

• BaseProvider interface: apps/server/src/providers/base-provider.ts
• Factory pattern: apps/server/src/providers/provider-factory.ts
• Allows swapping providers without changing agent logic
• All providers implement: executeQuery(), detectInstallation(), getAvailableModels()

Process Spawning:

• @automaker/platform exports spawnProcess(), spawnJSONLProcess()
• Codex CLI execution: JSONL output parsing
• Copilot CLI execution: Subprocess management
• Cursor IDE interaction: Process spawning for tool execution

---

Integration audit: 2026-01-27