Reference

SpecSync is configured via .specsync/config.toml (v4) or legacy specsync.json / .specsync.toml in your project root. All fields are optional; sensible defaults apply.

Getting Started

specsync init

Creates .specsync/config.toml (v4) with defaults. SpecSync also works without a config file.

TOML Config

Config resolution order: .specsync/config.toml → .specsync/config.json → .specsync.toml (legacy) → specsync.json (legacy) → defaults. If .specsync/config.local.toml exists (gitignored), it's merged on top for per-developer overrides.

Example:

specs_dir = "specs"
source_dirs = ["src"]
schema_dir = "db/migrations"
ai_provider = "anthropic"
ai_model = "claude-sonnet-4-6"
ai_timeout = 120
export_level = "member"
required_sections = ["Purpose", "Public API", "Invariants", "Behavioral Examples", "Error Cases", "Dependencies", "Change Log"]
exclude_dirs = ["__tests__"]
exclude_patterns = ["**/__tests__/**", "**/*.test.ts"]
task_archive_days = 30

[rules]
max_changelog_entries = 20
require_behavioral_examples = true
min_invariants = 1

[github]
drift_labels = ["spec-drift"]
verify_issues = true

Config resolution order: .specsync/config.toml → .specsync/config.json → .specsync.toml (legacy) → specsync.json (legacy) → defaults. Per-developer overrides via .specsync/config.local.toml are merged on top.

Full Config

{
  "specsDir": "specs",
  "sourceDirs": ["src"],
  "schemaDir": "db/migrations",
  "schemaPattern": "CREATE (?:VIRTUAL )?TABLE(?:\\s+IF NOT EXISTS)?\\s+(\\w+)",
  "requiredSections": ["Purpose", "Public API", "Invariants", "Behavioral Examples", "Error Cases", "Dependencies", "Change Log"],
  "excludeDirs": ["__tests__"],
  "excludePatterns": ["**/__tests__/**", "**/*.test.ts", "**/*.spec.ts"],
  "sourceExtensions": [],
  "exportLevel": "member",
  "aiProvider": "anthropic",
  "aiModel": "claude-sonnet-4-6",
  "aiCommand": null,
  "aiApiKey": null,
  "aiBaseUrl": null,
  "aiTimeout": 120,
  "taskArchiveDays": 30,
  "modules": {},
  "rules": {
    "maxChangelogEntries": 20,
    "requireBehavioralExamples": true,
    "minInvariants": 1,
    "maxSpecSizeKb": 50,
    "requireDependsOn": false
  },
  "github": {
    "repo": "owner/repo",
    "driftLabels": ["spec-drift"],
    "verifyIssues": true
  }
}

Options

AI Provider Resolution

AI calls go through the shared corvid-ai crate over plain HTTP, with no CLI tool required. The provider is resolved flag > env > config:

1. --provider CLI flag
2. SPECSYNC_AI_PROVIDER env var
3. aiProvider/ai_provider in config: shared config.toml first, then .specsync/config.local.toml (gitignored, per-developer overrides)

With nothing set, generate auto-detects:

• No <PROVIDER>_API_KEY anywhere → keyless local Ollama (http://localhost:11434), the zero-config default
• Exactly one <PROVIDER>_API_KEY set → that provider
• Several keys set → an interactive picker on a TTY, otherwise a deterministic order: Ollama, Anthropic, OpenAI, OpenRouter, Gemini, DeepSeek, Groq, Mistral, xAI, Together

The model follows the same flag > env > config precedence: --model > SPECSYNC_AI_MODEL > aiModel/ai_model config > provider default (anthropic → claude-sonnet-4-6, Ollama → llama3.3; openai and together require an explicit model).

aiTimeout (default 120s) controls the per-module AI timeout. aiBaseUrl (or OLLAMA_HOST for Ollama) points a provider at a custom endpoint.

Multi-agent teams: Don't put ai_provider or ai_command in the shared config.toml. Instead, each contributor creates .specsync/config.local.toml with their preferred AI settings. This file is automatically gitignored.

API Providers

Every provider calls its HTTP API directly, with no CLI tool needed. Just set the provider and its key:

{
  "aiProvider": "anthropic"
}

Then set ANTHROPIC_API_KEY (or the relevant <PROVIDER>_API_KEY) in your environment, or use aiApiKey in config for local use (not recommended for shared repos). Local Ollama needs no key at all.

Shell escape hatch (aiCommand)

aiCommand/SPECSYNC_AI_COMMAND remain as an explicit, trusted shell escape hatch: a command that reads a prompt on stdin and writes markdown to stdout. It is deprecated and never auto-selected; prefer the HTTP providers above.

Validation Rules

Fine-tune validation behavior with the rules object:

{
  "rules": {
    "maxChangelogEntries": 20,
    "requireBehavioralExamples": true,
    "minInvariants": 2,
    "maxSpecSizeKb": 50,
    "requireDependsOn": false
  }
}

GitHub Config

Configure GitHub integration for drift detection and issue verification:

{
  "github": {
    "repo": "owner/repo",
    "driftLabels": ["spec-drift"],
    "verifyIssues": true
  }
}

Custom Module Definitions

Map custom module names to specific files when auto-detection doesn't fit your layout:

{
  "modules": {
    "auth": {
      "files": ["src/auth/service.ts", "src/auth/middleware.ts"],
      "dependsOn": ["database"]
    },
    "api": {
      "files": ["src/routes/"],
      "dependsOn": ["auth", "database"]
    }
  }
}

Module definitions override the default subdirectory/flat-file discovery for specsync generate and specsync coverage.

Example Configs

TypeScript project

{
  "specsDir": "specs",
  "sourceDirs": ["src"],
  "excludePatterns": ["**/__tests__/**", "**/*.test.ts", "**/*.spec.ts", "**/*.d.ts"]
}

Rust project

{
  "specsDir": "specs",
  "sourceDirs": ["src"],
  "sourceExtensions": ["rs"]
}

Monorepo

{
  "specsDir": "docs/specs",
  "sourceDirs": ["packages/core/src", "packages/api/src"],
  "schemaDir": "packages/db/migrations"
}

Minimal

{
  "requiredSections": ["Purpose", "Public API"]
}