Sith

Turn your context to the dark side.

Standardize and share your OpenCode setup with a fully dockerized environment, designed for seamless collaboration and CI integration.

Quick Start

npm install -g @m14i/sith   # Install CLI
sith --pull                  # Pull prebuilt Docker image
sith                         # Launch TUI

No Docker? Use native Nix:

sith --nix-install && sith --nix

Why?

AI coding tools are powerful in isolation. They become fragile at scale:

• Context drift — every developer has a different CLAUDE.md, different tool versions, different configs. The AI sees a different project depending on who's running it.
• No CI path — running opencode or claude in a pipeline requires wiring tokens, installing tools, and hoping the environment matches local.
• Multiple tools — Claude Code and OpenCode serve different use cases (Anthropic auth vs GitHub Copilot). Switching between them shouldn't require manual setup.

Sith solves this by packaging both tools, all config, and your team's context into a single Docker image. One pull, same environment, everywhere.

| Problem | Sith answer | |---------|-------------| | Inconsistent context across team | Shared ~/.sith/ skills + CLAUDE.md, mounted at runtime | | AI tools hard to run in CI | Prebuilt signed image + token injection via env vars | | Claude Code vs OpenCode friction | Both available, same container, same command | | "Works on my machine" builds | Nix-pinned dependencies inside Docker |

How?

Three modes. Pick based on your trust model, infra constraints, and whether Docker is available. The Docker path is recommended for teams and CI — native Nix is for when you want no container overhead on a machine you control.

| | sith --pull | sith --build | sith --nix | |---|---|---|---| | Setup time | ~1 min (pull) | ~5–10 min (build) | ~2 min (first run) | | Reproducibility | Pinned image digest | Dockerfile-pinned | Nix-pinned (nixos-23.11) | | Trust model | GitHub Actions + Cosign | Your machine only | Your machine only | | SBOM included | ✅ | ❌ | ❌ | | CI/CD ready | ✅ drop-in | ⚠️ needs build step | ❌ | | Requires Docker | ✅ | ✅ | ❌ | | Requires Nix | ❌ | ❌ | ✅ | | Disk usage | ~2–3 GB (image) | ~2–3 GB (image) | ~500 MB (store) | | Cold start | ~1–2s (container spin-up) | ~1–2s (container spin-up) | ~200ms (native) | | Runtime overhead | Low (Linux containers) | Low (Linux containers) | None | | File I/O (macOS) | ⚠️ Slow (volume mounts) | ⚠️ Slow (volume mounts) | ✅ Native speed | | File I/O (Linux) | ✅ Native speed | ✅ Native speed | ✅ Native speed | | Memory overhead | ~50–100MB (Docker daemon) | ~50–100MB (Docker daemon) | None | | Works offline | ✅ after pull | ✅ after build | ⚠️ after store populated | | macOS support | ✅ (amd64 + arm64) | ✅ | ✅ | | Linux support | ✅ | ✅ | ✅ | | Windows support | ✅ Docker Desktop | ✅ Docker Desktop | ❌ | | Ideal for | Teams, CI, daily use | Air-gapped, custom | Local dev, no Docker |

Docker

The recommended path. One image, works locally and in CI.

Install the CLI

npm install -g @m14i/sith

Or without installing:

npx @m14i/sith@latest

Get the image

Prebuilt (recommended) — pull a signed image from GHCR:

sith --pull

Supports linux/amd64 and linux/arm64. Images are signed with cosign and include an SBOM.

Verify the signature (optional):

cosign verify \
  --certificate-identity-regexp="https://github.com/MerzoukeMansouri/sith" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ghcr.io/merzoukemansouri/sith:latest

Build from scratch — full control, no external trust:

sith --build

Use it

Interactive TUI — type a prompt or use slash commands:

sith

| In the TUI | What it does | |------------|-------------| | Type any text + Enter | Starts OpenCode with that prompt | | /shell | Drop into Docker shell (no AI) | | /claude | Switch active tool to Claude Code | | /opencode | Switch active tool to OpenCode | | /config | Pull / build options | | /help | Show commands | | Ctrl+C / Esc | Exit |

Direct commands — skip the TUI:

sith shell                        # Raw Nix shell inside Docker (alias: sith --it)
sith opencode -p "fix the bug"    # OpenCode starts immediately with your task
sith claude -p "fix the bug"      # Claude Code starts immediately with your task

Cleanup

sith --docker-cleanup    # Remove sith Docker images (sith:latest + prebuilt GHCR image)
sith --uninstall         # Remove ~/.sith/ (skills, config, nix files)

CI / GitHub Actions

- name: Run sith
  env:
    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    docker run --rm \
      -e CLAUDE_CODE_OAUTH_TOKEN=$CLAUDE_CODE_OAUTH_TOKEN \
      -e GITHUB_TOKEN=$GITHUB_TOKEN \
      ghcr.io/merzoukemansouri/sith:latest "claude auth status"

See Authentication for how to generate the tokens.

Direct Nix

No Docker. Runs the same Nix environment natively on your machine.

sith --nix-install    # Install Nix package manager (once)
sith --nix            # Launch Nix shell directly

Or via the nix subcommand:

sith nix --install    # Install Nix
sith nix --shell      # Run Nix shell

Maintenance:

sith --nix-update       # Update Nix channels and upgrade installed packages
sith --nix-cleanup      # Remove ~/.sith/nix/ + run nix-collect-garbage -d
sith --nix-uninstall    # Fully remove Nix from system (daemon, /nix/store) — needs sudo

See doc/NIX_INSTALLATION.md for full setup guide.

Skills

Skills are AI instruction sets installed to ~/.sith/skills/ and automatically mounted into the container at runtime. They shape how Claude Code and OpenCode behave — tone, workflow, shortcuts.

sith skills    # Browse and install / uninstall skills from catalog

Installed skills are synced to ~/.sith/CLAUDE.md (Claude Code) and ~/.sith/opencode.json (OpenCode) automatically.

| Skill | What it does | Auto-loaded | |-------|-------------|-------------| | caveman | Ultra-compressed responses (~75% token reduction) | ✅ |

Skills are loaded from ~/.sith/skills/<name>/ and can be toggled individually. Community skills can be installed from any Git URL.

Authentication

Two AI providers, two token setups:

• Claude Code (Anthropic OAuth) → doc/AUTH_CLAUDE.md
• OpenCode (GitHub Copilot) → doc/AUTH_OPENCODE.md

Command Reference

| Command / Flag | Description | |---|---| | sith | Launch interactive TUI | | sith shell | Raw Nix shell inside Docker | | sith opencode -p "<prompt>" | Launch OpenCode with prompt | | sith claude -p "<prompt>" | Launch Claude Code with prompt | | sith skills | Manage skills from catalog | | sith nix --install | Install Nix package manager | | sith nix --shell | Run Nix shell | | sith --pull | Pull prebuilt Docker image from GHCR | | sith --build | Build Docker image from scratch | | sith --it | Interactive shell in Docker container | | sith --nix | Launch native Nix shell (no Docker) | | sith --nix-install | Install Nix package manager | | sith --nix-update | Update Nix channels + upgrade packages | | sith --nix-cleanup | Remove ~/.sith/nix/ + garbage collect store | | sith --nix-uninstall | Fully remove Nix from system (needs sudo) | | sith --docker-cleanup | Remove sith Docker images from local machine | | sith --uninstall | Remove ~/.sith/ config directory | | sith --update | Check for CLI updates |

Development

pnpm install       # Install dependencies
pnpm dev           # Run in development mode (no build)
pnpm dev:build     # Build and run CLI
pnpm dev:shell     # Build and launch shell
pnpm typecheck     # Type checking
pnpm clean         # Clean build artifacts

Publishing

Automated via semantic-release and conventional commits.

| Prefix | Effect | |--------|--------| | feat: | Minor version bump | | fix: | Patch version bump | | BREAKING CHANGE: | Major version bump | | chore: docs: style: | No release |

Push to main → GitHub Action bumps version, generates CHANGELOG, publishes to npm.

Requirements: NPM_TOKEN secret in repository settings.