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.

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.

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

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.

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

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.

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

Requirements: NPM_TOKEN secret in repository settings.