npm package: @shakudo/kaji-setup-external
Description: Single-command installer for Kaji AI development environment (OpenCode + MCP servers + skills + vibe-git) - External version with ENV-based configuration
Author: Shakudo
Latest version: 1.2.0

# kaji-setup-external

Single-command installer for Kaji AI development environment - **External version** with environment-based configuration.

> **Note:** This is the external/self-hosted version. All credentials must be provided via environment variables. For Shakudo internal use, see `shakudo-vibe-setup` which has pre-configured shared credentials.

## Quick Start

### Prerequisites

**Required:**
- `bun` installed ([install guide](https://bun.sh/docs/installation))
- Environment variables configured (see `.env.example`)

**Will be auto-installed if missing:**
- git
- gh (GitHub CLI)
- jq (JSON processor)
- uv (Python package manager)

### Step 1: Configure Environment Variables

Copy the example environment file and fill in your credentials:

```bash
cp .env.example .env
# Edit .env with your API keys and credentials
source .env
```

**Required API Keys:**
- `ANTHROPIC_API_KEY` - For Claude AI (main coding assistant)
- `OPENAI_API_KEY` - For GPT models (Oracle agent)

**MCP Server Credentials (optional - services are disabled if not configured):**
- Mattermost, Neo4j, Notion, Supabase, Tavily, Fireflies, ClickUp, Gamma, Gemini

### Step 2: Install

```bash
bunx kaji-setup-external
```

This installs:
- **OpenCode** - AI coding assistant with Claude
- **MCP Servers** - Connections to configured services
- **Skills** - Pre-built workflows for K8s troubleshooting, CI/CD, deployments, etc.
- **kaji alias** - Shell alias for quick access

### Step 3: Start Coding

```bash
kaji
# or
opencode
```

## Environment Variables

See `.env.example` for a complete list. Key variables:

### Required
| Variable | Description |
|----------|-------------|
| `USER_EMAIL` | Your email address |
| `MATTERMOST_USER_ID` | Your Mattermost user ID (26 chars) |
| `GH_TOKEN` | GitHub personal access token |
| `ANTHROPIC_API_KEY` | Claude API key |
| `OPENAI_API_KEY` | OpenAI API key |

### MCP Services (Optional)
| Service | Required Variables |
|---------|-------------------|
| Mattermost | `MATTERMOST_TOKEN`, `MATTERMOST_URL`, `MATTERMOST_WS_URL`, `MATTERMOST_TEAM` |
| Neo4j | `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD` |
| Notion | `NOTION_API_TOKEN` |
| Supabase | `SUPABASE_CONNECTION_STRING` |
| Tavily | `TAVILY_API_KEY` |
| Fireflies | `FIREFLIES_API_KEY` |
| ClickUp | `CLICKUP_API_KEY`, `CLICKUP_TEAM_ID`, `CLICKUP_MCP_LICENSE_KEY` |
| Gamma | `GAMMA_API_KEY` |
| Nanobanana | `GEMINI_API_KEY` |

## What Gets Installed

### OpenCode Configuration
- `~/.config/opencode/opencode.json` - MCP server configs
- `~/.config/opencode/oh-my-opencode.json` - Agent-to-model mappings
- `~/.config/opencode/package.json` - Plugin dependencies

### MCP Servers
- **Shakudo Platform** - Deploy and manage microservices
- **Mattermost** - Team communication
- **Notion** - Documentation access
- **ClickUp** - Task management
- **Playwright** - Browser automation
- **Tavily** - Web search
- **Nanobanana** - Image generation (Gemini)
- **Markitdown** - Document conversion
- **Neo4j** - Knowledge graph queries
- **Dremio** - Data lakehouse queries
- **Fireflies** - Meeting transcripts
- **Supabase** - PostgreSQL database

### Skills (16 total)
Installed to `/root/gitrepos/.claude/skills/`:
- ci-cd, context-optimization, dremio-analytics
- git-workflow, gitops-workflows, iac-terraform
- k8s-troubleshooter, mattermost-notify, monitoring-observability
- neo4j-graph-rag, playwright, project-memory
- recruit-workflow, shakudo-microservice, tmux, zellij

### Shell Alias
The installer adds a `kaji` alias to your shell config (`.bashrc` / `.zshrc`):
```bash
alias kaji='kaji-entry.sh'
```

## CLI Options

```bash
bunx kaji-setup-external --help

Options:
  --skip-deps      Skip dependency installation (git, gh, uv, bun)
  --skip-backup    Skip backing up existing configuration
  --skip-config    Skip OpenCode configuration
  --skip-skills    Skip skills installation
  --skip-speckit   Skip Speckit installation
  --skip-vibe-git  Skip vibe-git installation
  --help           Show help message
```

## Updating

To get the latest version:
```bash
bun pm cache rm && bunx kaji-setup-external
```

## Development

```bash
cd kaji-setup-external
bun install
bun run ./bin/cli.ts --help
```

## Differences from shakudo-vibe-setup

| Feature | shakudo-vibe-setup | kaji-setup-external |
|---------|-------------------|---------------------|
| Credentials | Pre-configured shared keys | All via environment variables |
| Registry | Internal Verdaccio | Public npm (default) |
| Target | Shakudo employees | External/self-hosted users |