AI Commands

DubStack includes an AI assistant for repository-aware questions, AI-generated branch and commit metadata, AI-generated PR descriptions, and conflict-resolution help.

Quick Setup

The easiest setup path is the guided wizard:

dub ai setup
source ~/.zshrc
dub config ai-assistant on

You can then pin the provider for the current repository:

dub config ai-provider gemini
# or:
dub config ai-provider anthropic
# or:
dub config ai-provider gateway
# or:
dub config ai-provider bedrock
# or:
dub config ai-provider openai

Optional repo-local AI defaults:

dub config ai-defaults create on
dub config ai-defaults submit on
dub config ai-defaults flow on

Providers

Gemini

• Auth: DUBSTACK_GEMINI_API_KEY
• Optional global model default: DUBSTACK_GEMINI_MODEL
• Good fit when you want direct Google access from DubStack

AI Gateway

• Auth: DUBSTACK_AI_GATEWAY_API_KEY
• Optional global model default: DUBSTACK_AI_GATEWAY_MODEL
• Good fit when your team standardizes on Vercel AI Gateway

Anthropic Claude

• Auth: DUBSTACK_ANTHROPIC_API_KEY
• Optional global model default: DUBSTACK_ANTHROPIC_MODEL
• Good fit when you want direct Claude access without routing through AI Gateway

Amazon Bedrock

• Required: DUBSTACK_BEDROCK_AWS_REGION
• Required: DUBSTACK_BEDROCK_MODEL
• Optional: DUBSTACK_BEDROCK_AWS_PROFILE
• Good fit for AWS SSO, instance roles, ECS roles, EKS service accounts, and other AWS credential-chain environments

Bedrock support in DubStack is intentionally secure-auth only. DubStack does not introduce its own secret-key environment variable flow for AWS credentials.

OpenAI

• Auth: DUBSTACK_OPENAI_API_KEY
• Optional global model default: DUBSTACK_OPENAI_MODEL
• Good fit when your team wants direct GPT/o-series access from DubStack

Provider Selection and Precedence

DubStack resolves AI providers in this order:

1. Repo-local provider selection from dub config ai-provider ...
2. Repo-local provider-specific model override from dub config ai-model ...
3. Global provider defaults from shell profile exports
4. Auto fallback order: Gemini, then Anthropic, then AI Gateway, then Bedrock, then OpenAI

Examples:

# Inspect current provider choice
dub config ai-provider

# Pin this repo to Bedrock
dub config ai-provider bedrock

# Pin this repo to Anthropic
dub config ai-provider anthropic

# Set a repo-local Bedrock model override
dub config ai-model "us.anthropic.claude-sonnet-4-6" --provider bedrock

# Set a repo-local Anthropic model override
dub config ai-model "claude-opus-4-20250514" --provider anthropic

# Set a repo-local OpenAI model override
dub config ai-model "gpt-5.5" --provider openai

# Clear the repo-local override and fall back to env defaults
dub config ai-model --provider openai --clear

dub ai setup

dub ai setup is the guided onboarding flow for all supported providers.

It helps you:

• choose the repo-local provider
• choose a curated model or enter a custom model ID
• write global provider defaults into your shell profile
• optionally store a repo-local model override

For Bedrock, the wizard prompts for AWS profile and region instead of API secrets. When the wizard writes env vars, DubStack loads them into the current dub process and prints the exact shell command to run so your terminal session can pick them up immediately.

dub ai env

Use dub ai env for explicit shell-profile edits to models and endpoints without the wizard.

API keys are not set here — passing a secret as a CLI flag leaks it into your shell history and the OS process list. Set keys with dub ai setup (masked prompt) or export the env var directly: DUBSTACK_GEMINI_API_KEY, DUBSTACK_ANTHROPIC_API_KEY, DUBSTACK_AI_GATEWAY_API_KEY, or DUBSTACK_OPENAI_API_KEY.

# Gemini
dub ai env --gemini-model "gemini-3-flash-preview"

# AI Gateway
dub ai env --gateway-model "google/gemini-3-flash"

# Anthropic
dub ai env --anthropic-model "claude-sonnet-4-20250514"

# OpenAI
dub ai env --openai-model "gpt-5.5"

# Bedrock
dub ai env \
  --bedrock-profile "bw-sso" \
  --bedrock-region "us-west-2" \
  --bedrock-model "us.anthropic.claude-sonnet-4-6"

Supported automatic profile detection:

• zsh → ~/.zshrc
• bash → ~/.bashrc (or ~/.bash_profile)

After writing exports, DubStack prints the exact activation command to run in your shell so the new values take effect right away.

Direct Assistant Usage

Ask the AI assistant explicitly:

dub ai ask "Summarize what this stack is changing"

Use the top-level shortcut:

dub "what changed on this branch?"

Force shortcut mode even when the first token could look like a command:

dub --ai "summarize terminal work"

The assistant automatically receives stack-aware context such as current branch, stack placement, git status, doctor output, and recent command history.

AI-Assisted Authoring

dub create --ai

Generate a branch name and conventional commit message from staged changes:

dub create --ai
dub create -ai
dub create --no-ai feat/my-change

If AI create defaults are enabled for the repo, --no-ai disables AI for a single invocation.

dub submit --ai

Generate a PR description body while keeping the PR title equal to the last commit message:

dub submit --ai
dub submit --no-ai

AI submit only writes the PR description body. DubStack still owns:

• the stack table
• the hidden metadata block

dub flow and dub f

Use the end-to-end AI workflow for staged changes:

dub flow --ai -a
dub flow -y -u
dub f --dry-run

dub flow previews:

• generated branch name
• generated commit message
• generated PR description
• the commands DubStack will run

Use -y to auto-approve. Use --dry-run to preview without creating or submitting anything.

Templates

DubStack can use repository templates as the formatting contract for AI-generated commit messages and PR descriptions.

Pull Request Templates

Supported locations include:

• .github/pull_request_template.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/PULL_REQUEST_TEMPLATE/*.md
• docs/pull_request_template.md
• pull_request_template.md

Commit Message Templates

DubStack also reads the repository commit message template from git config:

git config commit.template .gitmessage

When templates are present, DubStack asks the model to preserve that structure instead of inventing a generic format.

Conflict Resolution

Use AI to help resolve conflicts:

dub ai resolve

If two providers are configured, DubStack asks both providers in parallel, marks exact agreement as high confidence, and shows lower-confidence files first. Use dub ai resolve --no-adjudicate for the original single-provider path, or dub ai resolve --adjudicate when you want the command to require two providers.

Notes

• AI requires dub config ai-assistant on in the current repository.
• If AI is explicitly requested and unavailable, DubStack fails clearly instead of silently downgrading.
• PR titles remain commit-derived for squash-merge safety.
• dub docs opens the docs site, and dub repo opens the current repository GitHub page in your browser.

Local Evals

DubStack keeps a local Evalite suite for AI-generated flow metadata:

pnpm evals
pnpm evals:watch
pnpm evals:export