Configuration

Holocron looks for holocron.config.ts (preferred) or holocron.config.json in the current working directory (or the path passed to --cwd). TypeScript configs require @theholocron/holocron-config as a dev dependency.

Full schema

import { defineConfig } from "@theholocron/holocron-config";

export default defineConfig({
  // Project name. Derived from package.json#name when absent.
  name: "my-project",

  // Short description. Written to package.json#description and the GitHub repo by `holocron sync`.
  description: "Short description",

  // Project homepage. Synced to package.json#homepage and the GitHub repo's website field.
  homepage: "https://github.com/my-org/my-project",

  // Repository identity and metadata.
  repo: {
    // "owner/name" — injected into every plugin's context so --repo isn't needed on every call.
    name: "my-org/my-project",

    // Branch protection preset applied by `holocron setup`.
    // "balanced" — squash merge only, delete branch on merge, no force-push.
    // "strict"   — same + required status checks. The required-check list is
    //              derived from the manifest: every `{ required: true }` task's
    //              workflow check context (in CI order), plus `extraRequiredChecks`
    //              below and a hard-prepended "DCO". No hand-maintained list.
    // "none"     — no protection applied.
    protection: "balanced",

    // GitHub teams granted repo access. String shorthand → push (Write) permission.
    teams: ["my-org/engineers", { slug: "my-org/bots", permission: "push" }],

    // GitHub repository topics.
    topics: ["typescript", "node", "cli"],

    // GitHub org-level custom properties synced by `holocron setup`.
    properties: {
      lifecycle: "active", // "active" | "experimental" | "deprecated"
      open_source: true,
      runtime_environment: "node", // "node" | "browser" | "universal" | "none"
      uses_external_packages: true,
    },
  },

  // The task manifest — what this repo runs. `@theholocron/astromech` reads it
  // for `holocron run` / `holocron ci` / the generated CI workflow thin callers.
  // String form: default inputs. Object form: pass custom `with:` inputs.
  // Supported: "lint" | "test" | "typecheck" | "codeql" | "review" |
  //            "release" | "stale" | "greetings" | "dependencies" | "bookkeeping" | "audit"
  // The `lint` entry takes an optional `linters` array — the one list that
  // drives both the CI super-linter env and `holocron run lint` locally.
  // Omitted → auto-detected from the config files present (eslint.config.*,
  // .markdownlint*, …) plus the org always-on set (prettier, yamllint,
  // actionlint, gitleaks, editorconfig, commitlint, merge-conflict-markers).
  // `required: true` marks a task merge-gating: `holocron ci` runs it by
  // default and `holocron setup` (strict) adds its workflow check context to
  // branch protection.
  tasks: [
    { name: "lint", required: true, linters: ["eslint", "prettier", "yamllint", "actionlint", "gitleaks"] },
    { name: "test", required: true },
    { name: "typecheck", required: true },
    { name: "release", with: { "run-build": false } },
    "stale",
    "greetings",
  ],

  // Required status-check contexts **not** backed by a `{ required: true }` task
  // — codecov gates, a docs/storybook publish job, etc. `holocron setup`
  // (strict) appends these to the task-derived list.
  extraRequiredChecks: ["codecov/patch", "codecov/project"],

  // `holocron sync` reconciles package.json#scripts (merge, never clobber): the
  // `holocron` entry + a `holocron run <task>` wrapper per runnable task.
  // `syncScripts: false` disables it; `holocronScript` sets the `holocron`
  // entry's command (default "holocron", the installed bin).
  // syncScripts: false,
  // holocronScript: "node packages/cli/dist/cli.mjs",

  // Git hooks installed by `holocron setup`. `true` / `{ prePush: true }`
  // writes `.husky/pre-push` (runs `holocron ci` before every push) and adds
  // `prepare: "husky"` to package.json; `false` / `{ prePush: false }` opts out.
  // Omitted → on for `protection: "strict"`, off otherwise. `holocron setup
  // --hooks` / `--no-hooks` override per-run. Bypass a single push with
  // `git push --no-verify`.
  // hooks: true,

  // Agent runtime — determines where skills are installed.
  // "claude" → .claude/skills/<name>  (symlinks to .agents/skills/<name>)
  agent: "claude",

  // Skill names from @theholocron/skills to install via `holocron setup`.
  // Installed to .agents/skills/<name>/ — gitignored and regenerated each run.
  skills: ["git-safety", "pr-workflow", "commit-standards", "security-review"],

  // Capability → provider bindings.
  providers: {
    source: "github",
    ci: "github",
    secrets: "github",
    environments: "github",
    issues: "github",
    vault: ["1password", { vault: "acme-app" }],
    deployment: ["vercel", { teamId: "team_xxx" }],
    storage: "neon",
    auth: "clerk",
    tooling: ["postman"],
    // errors and logs are env-var-activated at runtime (HOLOCRON_SENTRY_DSN / HOLOCRON_AXIOM_TOKEN).
    // The provider entry is used by `holocron setup` and `holocron doctor` only.
    errors: "sentry",
    logs: "axiom",
  },

  // Structured-logging config. `level` is the lowest-priority level source:
  // --verbose/--quiet and HOLOCRON_LOG_LEVEL both outrank it. `axiom.dataset`
  // opts local runs into Axiom shipping without exporting HOLOCRON_AXIOM_DATASET
  // — the token still comes from an env var or the OS keyring, never here.
  log: { level: "info", axiom: { dataset: "holocron-local" } },

  // CLI self-telemetry override layer (see /telemetry). Env
  // (HOLOCRON_TELEMETRY=false) still wins and is checked first; this is the
  // committed way to opt a repo out or drop usage analytics only. No
  // credentials here — the Sentry DSN / PostHog key come from env or ship as
  // fallbacks.
  //   enabled: false      → no-ops Sentry + PostHog for every command
  //   analytics: "none"   → PostHog off, Sentry error reporting unaffected
  telemetry: { enabled: true, analytics: "posthog" },
});

Provider entry forms

Holocron supports multiple entry forms for flexibility:

// Short form — single provider, no options
"source": "github"

// Tuple form — single provider with options
"deployment": ["vercel", { teamId: "team_xxx" }]

// Multi form — multiple providers (only for "many" cardinality capabilities)
"tooling": ["postman", "other-tool"]

// Multi with options
"notifications": [
  ["slack",   { channel: "#ops" }],
  ["discord", { webhook: "env:HOOK" }],
]

Short provider names (e.g. "github") are resolved to @theholocron/holocron-plugin-github. Fully-qualified package names and community plugins (prefixed holocron-plugin-) are passed through verbatim.

Agent and engineering knowledge

agent + skills

agent sets the AI runtime ("claude" | "codex" | "gemini"). When set, holocron setup installs the listed skills from @theholocron/skills into .agents/skills/<name>/ with an agent-specific symlink (e.g. .claude/skills/<name> for Claude Code). The installed paths are gitignored and regenerated on every run.

agent: "claude",
skills: ["git-safety", "pr-workflow", "commit-standards", "security-review"],

When agent is set, holocron setup also writes nine AI engineering workflow role prompts to .agents/prompts/ — one file per agent role (discovery.md, design.md, discussion.md, adr.md, spec.md, implementation-plan.md, implement.md, review.md, verify.md). The prompts directory is gitignored and always regenerated from the current CLI version.

docs — decisions structure

When docs is configured, holocron setup also provisions the engineering knowledge structure on first run. Existing files are never overwritten, so existing ADRs are safe.

Path	Created
docs/decisions/template.md	MADR ADR template with required frontmatter
docs/decisions/README.md	Index and usage guide
docs/engineering/README.md	Internal engineering site stub

Any repo with a docs site gets the structure — it costs nothing and is ready when needed, even if ADRs are never written.

Capability cardinality

Capability	Cardinality	Description
source	single	Repository + branch + workflow file operations
ci	single	CI run listing and status
secrets	single	CI/platform secret sync destination
environments	single	Named deployment environments
issues	single	Issue tracker (create, search, transition)
deployment	single	Preview and production deployment
storage	single	Database branch management
auth	single	Identity provider
vault	single	Secret source-of-truth
dns	single	DNS record management
errors	single	Error tracking — env-var-activated (HOLOCRON_SENTRY_DSN); provider entry used by setup/doctor only
logs	single	Log aggregation — env-var-activated (HOLOCRON_AXIOM_TOKEN + HOLOCRON_AXIOM_DATASET); provider entry used by setup/doctor only
tooling	many	Sync external tool state
notifications	many	Send messages
analytics	many	Analytics providers

many capabilities accept a list of providers; single accept exactly one.

errors and logs are self-contained: they activate at runtime when their env vars are present, regardless of whether a provider entry exists in config. The config entry is for holocron setup (provisioning the dataset/project) and holocron doctor (connectivity checks) only.

JSON format

If you prefer not to use TypeScript:

{
  "name": "my-project",
  "description": "Short description",
  "repo": {
    "name": "my-org/my-project",
    "protection": "balanced",
    "topics": ["typescript", "node"]
  },
  "workflows": ["lint", "test"],
  "providers": {
    "source": "github",
    "vault": ["doppler", { "project": "my-project", "config": "prd" }]
  }
}

JSON repos (like .github and .github-private) use holocron.config.json since they have no package.json to install TypeScript.

Global options

All commands accept these flags:

Flag	Default	Description
--dry-run	false	Print mutations without executing them
--token <value>	—	Override provider token for this invocation
--cwd <path>	process.cwd()	Directory to search for config

--token forms

# Bare: fallback token for single-provider commands
holocron setup --token ghp_xxx

# Keyed: target a specific provider
holocron setup --token github=ghp_xxx

# Multiple keyed tokens
holocron setup --token github=ghp_xxx --token vercel=v_yyy