Configuration

betterspec is configured through a betterspec.json file at the root of your project. This file is created by betterspec init and controls how betterspec stores and syncs specs.

betterspec.json

A minimal config looks like this:

{
  "projectName": "my-app",
  "mode": "local"
}

A full config with global sync and AI:

{
  "projectName": "my-app",
  "mode": "local+global",
  "globalRepo": "git@github.com:my-org/specs.git",
  "tool": "claude-code",
  "skills": "both",
  "ai": {
    "provider": "auto",
    "model": "auto",
    "autoDigest": false,
    "contextBudget": 8000
  }
}

Config Values

mode

Controls where specs are stored. Three options:

# Set the mode via CLI
betterspec config set mode local+global

globalRepo

The git URL of the global spec repository. Required when mode is local+global or global.

betterspec config set globalRepo git@github.com:my-org/specs.git

projectName

The name of the project. Used as a namespace when syncing to a global repository, so multiple projects can share a single global repo without collisions.

betterspec config set projectName my-app

tool

The AI coding tool adapter to use. Set during betterspec init (Step 2). Controls which tool-specific files are scaffolded.

betterspec config set tool claude-code

skills

Controls where skill files are installed. Set during betterspec init (Step 3).

betterspec config set skills both

ai

Configuration for AI-powered commands (digest, search, impact, onboard, explain).

{
  "ai": {
    "provider": "auto",
    "model": "auto",
    "autoDigest": false,
    "contextBudget": 8000
  }
}

betterspec config set ai.provider anthropic
betterspec config set ai.contextBudget 12000

Directory Structure

After running betterspec init, your project will have this structure:

your-project/
  betterspec.json              # Project configuration
  betterspec/
    changes/                  # Active and proposed changes
      auth-oauth/
        proposal.md
        specs/
          requirements.md
          scenarios.md
        design.md
        tasks.md
        .betterspec-meta.json
    knowledge/                # Accumulated project knowledge
      patterns.md
      decisions.md
      lessons.md
    capabilities/             # Registered project capabilities
      auth.md
      api.md

betterspec/changes/

Contains all active changes. Each change gets its own subdirectory with the full set of spec files. Archived changes are moved out of this directory.

betterspec/knowledge/

Stores persistent knowledge that accumulates across changes. When a change is archived, betterspec extracts patterns, decisions, and lessons into this directory. AI agents read these files to build context before starting new work.

betterspec/capabilities/

Tracks what your project can do. Each file describes a capability (e.g., authentication, API endpoints, background jobs). These help AI agents understand existing functionality and avoid duplicating work.

Reading Config Programmatically

You can read the config from TypeScript using @betterspec/core:

import { readConfig } from "@betterspec/core";

const config = await readConfig("/path/to/project");
console.log(config.mode);        // "local"
console.log(config.projectName); // "my-app"

See the Programmatic API for more details.