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:

{
  "projectName": "my-app",
  "mode": "local+global",
  "globalRepo": "git@github.com:my-org/specs.git",
  "tool": "claude-code",
  "skills": "both"
}

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

contextBudget

Maximum number of tokens to include when injecting betterspec context into AI tool prompts. Lower values reduce cost; higher values give agents more project awareness.

betterspec config set 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.