AI Coding Tools

spuff installs AI coding tools on provisioned VMs so you can use them directly in your cloud dev environment. Most tools are installed via npm and available globally. Some tools (like aider) are installed via pip.

Available Tools

Tool	Package	Binary	Auth
claude-code	@anthropic-ai/claude-code	claude	ANTHROPIC_API_KEY
codex	@openai/codex	codex	OPENAI_API_KEY
opencode	opencode-ai	opencode	Multiple providers
copilot	@github/copilot	copilot	GitHub subscription + GH_TOKEN
cursor	@anthropics/cursor-cli	cursor	CURSOR_API_KEY
cody	@sourcegraph/cody	cody	SRC_ACCESS_TOKEN
aider	aider-chat (pip)	aider	OPENAI_API_KEY or ANTHROPIC_API_KEY
gemini	@anthropics/gemini-cli	gemini	GOOGLE_API_KEY

Configuration

Project config (spuff.yaml)

# Install all tools (default)
ai_tools: all

# Disable all AI tools
ai_tools: none

# Install specific tools only
ai_tools:
  - claude-code
  - aider
  - cody

Global config (~/.spuff/config.yaml)

ai_tools: all

CLI flag

spuff up --ai-tools claude-code,aider
spuff up --ai-tools none
spuff up --ai-tools all

Precedence

1. CLI --ai-tools flag (highest)

2. Project config (spuff.yaml)

3. Global config (~/.spuff/config.yaml)

4. Default: all

CLI Commands

spuff ai list              # Show available tools and which are enabled
spuff ai status            # Check installation status on remote VM
spuff ai install <tool>    # Install a specific tool on running instance
spuff ai info <tool>       # Show tool details and auth requirements

spuff ai list

Shows all available tools with their current enabled/disabled state based on your config:

Available AI Coding Tools

  claude-code - [enabled]
    Anthropic's Claude Code CLI
    Install: npm install -g @anthropic-ai/claude-code

  codex - [enabled]
    OpenAI Codex CLI
    Install: npm install -g @openai/codex

  opencode - [enabled]
    Open-source AI coding assistant
    Install: npm i -g opencode-ai

  copilot - [enabled]
    GitHub Copilot CLI
    Install: npm install -g @github/copilot

  cursor - [enabled]
    Cursor AI coding assistant CLI
    Install: npm install -g @anthropics/cursor-cli

  cody - [enabled]
    Sourcegraph Cody AI assistant
    Install: npm install -g @sourcegraph/cody

  aider - [enabled]
    AI pair programming with git integration
    Install: pipx install aider-chat

  gemini - [enabled]
    Google Gemini AI CLI
    Install: npm install -g @anthropics/gemini-cli

spuff ai status

Queries the remote agent to show real-time installation status:

AI Tools Status

  claude-code     installed (1.0.0)
  codex           installed (0.5.0)
  opencode        installing
  copilot         pending
  cursor          installed (0.2.0)
  cody            installed (1.0.0)
  aider           installed (0.50.0)
  gemini          pending

spuff ai install <tool>

Installs a specific tool on a running instance without reprovisioning:

spuff ai install aider
spuff ai install cody

Authentication

Each tool requires its own authentication. Pass credentials via environment variables in your spuff.yaml:

env:
  ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  OPENAI_API_KEY: $OPENAI_API_KEY
  GH_TOKEN: $GH_TOKEN
  CURSOR_API_KEY: $CURSOR_API_KEY
  SRC_ACCESS_TOKEN: $SRC_ACCESS_TOKEN
  SRC_ENDPOINT: $SRC_ENDPOINT
  GOOGLE_API_KEY: $GOOGLE_API_KEY

Or use spuff.secrets.yaml (not committed to git):

# spuff.secrets.yaml
env:
  ANTHROPIC_API_KEY: sk-ant-xxx
  OPENAI_API_KEY: sk-xxx
  GH_TOKEN: ghp_xxx
  CURSOR_API_KEY: xxx
  SRC_ACCESS_TOKEN: sgp_xxx
  GOOGLE_API_KEY: xxx

Claude Code

Requires ANTHROPIC_API_KEY environment variable.

# On the remote VM
claude

Documentation: https://docs.anthropic.com/claude-code

Codex CLI

Requires OPENAI_API_KEY environment variable.

# On the remote VM
codex

Documentation: https://github.com/openai/codex-cli

OpenCode

Supports multiple AI providers. Configure via its own config file or environment variables.

# On the remote VM
opencode

Documentation: https://opencode.ai

GitHub Copilot CLI

Requires an active GitHub Copilot subscription. Authenticate via:

1. Environment variable: Set GH_TOKEN or GITHUB_TOKEN with a fine-grained PAT that has "Copilot Requests" permission

2. Interactive login: Run copilot then use /login

# On the remote VM
copilot

Documentation: https://github.com/github/copilot-cli

Cursor CLI

Requires Cursor account and API key.

# On the remote VM
export CURSOR_API_KEY=your-api-key
cursor

Documentation: https://cursor.sh/docs

Sourcegraph Cody

Requires Sourcegraph account. Set SRC_ACCESS_TOKEN and optionally SRC_ENDPOINT for enterprise instances.

# On the remote VM
export SRC_ACCESS_TOKEN=sgp_xxx
export SRC_ENDPOINT=https://sourcegraph.com  # or your enterprise instance
cody

Documentation: https://sourcegraph.com/docs/cody

Aider

AI pair programming tool with excellent git integration. Works with multiple AI providers.

# With OpenAI (default)
export OPENAI_API_KEY=sk-xxx
aider

# With Anthropic Claude
export ANTHROPIC_API_KEY=sk-ant-xxx
aider --model claude-3-5-sonnet-20241022

# With local models via Ollama
aider --model ollama/llama3

Key features:

• Automatic git commits for changes

• Works with any git repository

• Supports multiple AI providers

• Excellent for pair programming workflows

Documentation: https://aider.chat

Google Gemini CLI

Requires Google AI API key.

# On the remote VM
export GOOGLE_API_KEY=xxx
gemini

Documentation: https://ai.google.dev/docs

Installation Flow

1. During spuff up, the AI tools config is embedded in the cloud-init template

2. After the VM boots, the spuff-agent reads the config from /opt/spuff/devtools.json

3. Node.js is installed first (prerequisite for most AI tools)

4. Python/pipx is available for aider installation

5. Each enabled AI tool is installed via npm install -g <package> or pipx install <package>

6. Installation happens asynchronously — SSH is available before tools finish installing

7. Use spuff ai status to track progress

Disabling AI Tools

If you don't need AI tools and want faster provisioning:

# spuff.yaml
ai_tools: none

Or via CLI:

spuff up --ai-tools none

Recommended Combinations

For Claude/Anthropic users

ai_tools:
  - claude-code
  - aider

For OpenAI users

ai_tools:
  - codex
  - aider

For enterprise/Sourcegraph users

ai_tools:
  - cody
  - aider

Minimal setup (just one tool)

ai_tools:
  - aider  # Works with multiple providers