Configuration

Configure Stoa with config files, environment variables, ignore patterns, and workspace-level overrides. Every option, documented.

Stoa uses a layered configuration system: environment variables take highest priority, followed by project-level config, then global config.

Configuration Hierarchy

Environment variables (highest priority)
Project config: .stoa/config.json
Global config: ~/.stoa/config.json

Project Configuration

Located at .stoa/config.json in your project root:

{
  "version": "1.0",
  "projectRoot": "/path/to/project",
  "debug": false,
  "disableMaterializer": false,
  "rename": {
    "pendingCreateTTLMillis": 500,
    "pendingDeleteTTLMillis": 500
  },
  "crdtDebug": {
    "enabled": false,
    "includeContent": true,
    "prettyPrint": true
  },
  "remote": {
    "enabled": false,
    "url": "stoa://server.example.com/project-id"
  }
}

Field	Type	Description
`version`	string	Config schema version
`projectRoot`	string	Absolute path to project root
`debug`	boolean	Enable debug logging
`rename.pendingCreateTTLMillis`	number	Time to wait for rename detection on creates
`rename.pendingDeleteTTLMillis`	number	Time to wait for rename detection on deletes
`crdtDebug.enabled`	boolean	Enable Automerge debug logging
`crdtDebug.includeContent`	boolean	Include file content in debug logs
`crdtDebug.prettyPrint`	boolean	Pretty-print debug output
`remote.enabled`	boolean	Enable remote sync
`remote.url`	string	Remote server URL

LLM Configuration

Configure the Anthropic API key used for enrichment:

# Interactive setup
stoa configure llm

# Set directly
stoa configure llm --api-key sk-ant-...

# Set model
stoa configure llm --model claude-sonnet-4-5-20250929

# Show current config
stoa configure llm --show

# Use team's API key
stoa configure llm --from-org

Configuration is stored in .stoa/config.json (project) or ~/.stoa/config.json (global):

{
  "llm": {
    "anthropicApiKey": "sk-ant-...",
    "anthropicModel": "claude-sonnet-4-5-20250929"
  }
}

Fallback: If no API key is configured, the CLI will use the Claude CLI binary if available on your PATH.

Slack Configuration

Send notifications to Slack channels:

# Interactive setup
stoa configure slack

# Direct configuration
stoa configure slack --oauth-token xoxb-... --channel "#stoa-topics"

# Enable/disable
stoa configure slack --enable
stoa configure slack --disable

# Project or global scope
stoa configure slack --scope project
stoa configure slack --scope global

# Show current config
stoa configure slack --show

{
  "slack": {
    "enabled": true,
    "channel": "#stoa-topics",
    "postExchangeDetails": true,
    "docSync": {
      "enabled": true,
      "watchedDirs": ["docs/", "README.md"]
    }
  }
}

Shell Configuration

Located at ~/.stoa/shell-config.yaml:

theme: auto                    # auto, dark, light
editor: vim                    # Default editor
maxHistorySize: 100            # Shell history limit
autocompleteEnabled: true      # Tab completion
showTimestamps: false          # Show timestamps in output
markdownTheme: auto            # Markdown rendering theme

Configure interactively:

stoa configure shell

Ignore Patterns

`.stoaignore`

Project-specific ignore file using .gitignore syntax:

# Dependencies
node_modules/
vendor/
.venv/

# Build output
dist/
build/
*.o
*.pyc

# IDE files
.idea/
.vscode/
*.swp

# Large files
*.zip
*.tar.gz
*.dmg

# Secrets
.env
.env.local

Global Ignore

Located at ~/.stoaignore. Applies to all projects.

Built-in Patterns

These are always excluded regardless of configuration:

.git/
.stoa/
node_modules/
__pycache__/
*.pyc
.DS_Store

Manage via CLI

stoa ignore add "*.log"
stoa ignore remove "*.log"
stoa ignore list
stoa ignore test path/to/file.log

Environment Variables

Core

Variable	Description
`NO_COLOR`	Disable colored output

LLM

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key (overrides config)
`ANTHROPIC_MODEL`	Model to use (overrides config)

Slack

Variable	Description
`SLACK_OAUTH_TOKEN`	Slack bot token (xoxb-...)
`SLACK_CHANNEL`	Default Slack channel
`INTENT_SLACK_DISABLED`	Set to `1` to disable Slack

Web Platform

Variable	Description
`STOA_API_URL`	Override API URL (default: `https://stoa.specstory.com`)
`STOA_WEB_URL`	Override web URL

Actor Identity

Configure your identity for attribution:

stoa configure actor [--username NAME] [--hostname HOST] [--show] [--clear]

This sets the identity (username@hostname) used for provenance tracking and commit attribution.

Global Daemon Registry

All running daemons are tracked in ~/.stoa/daemons.json. Manage them with:

stoa service daemon list       # See all daemons
stoa service daemon kill-all   # Stop all daemons
stoa service daemon clean-all  # Remove stale entries