Configuration

.chalk/config holds a repository's settings: plain KEY=value lines, with no quotes and no shell expansion. It is read, never executed. chalk init writes it with every key explained in a comment.

• Precedence: an environment variable of the same name wins over the file, even when it is set to an empty value; a key that is unset or empty takes its default.
• Unknown keys are ignored with a warning, so a typo does not go unnoticed.
• Removed keys: the settings of Hindsight, the lesson server that was removed (CHALK_MEMORY=hindsight and CHALK_MEMORY_URL, CHALK_MEMORY_BANK, CHALK_MEMORY_TOKENS, CHALK_MEMORY_IMAGE), are ignored with one warning. Delete them. See Lesson recall.
• Checked values: Chalk stops with a message when CHALK_FORGE, CHALK_PERMISSION_MODE, CHALK_FP_RULES, CHALK_FP_FEEDBACK, CHALK_MAX_PARALLEL, CHALK_SANDBOX_MEM_MB or one of the CHALK_DECIDER* settings has a value it does not accept, or when auto mode is combined with a Haiku CHALK_MODEL.

The rest of this page lists every key in the order of the template, share/templates/config, with the template's own explanation. It is generated from that file when the site is built, and the build fails if the template and the defaults in lib/config.sh disagree.

Repository

CHALK_BASE_BRANCH

Default: main

Branch that workstreams start from and merge back into.

CHALK_FORGE

Default: auto

Where the repository is hosted: github, gitlab, or auto (GitHub when the origin remote is on github.com, otherwise GitLab). Set github for GitHub Enterprise.

The rubric

CHALK_TEST_CMD

Default: none

The rubric. Must exit 0 only when the work is acceptable. Runs with bash -c in the sandbox after every agent loop, and again in CI.

CHALK_SETUP_CMD

Default: none

Runs once in a fresh sandbox (and in CI) before the rubric, e.g. npm ci. The sandbox runs as you, not root: it can install into the repository or $HOME (npm ci, go mod download, a Python venv), never system packages.

CHALK_RUBRIC_TIMEOUT

Default: 900

Seconds before a hung rubric is killed.

CHALK_AGENT_TIMEOUT

Default: 1800

Seconds an agent call may take before it is stopped and counted as a timeout, which is retried like other failures.

CHALK_TEST_REPORT

Default: none

Optional test report the rubric writes, as a path inside the repo: JUnit XML, go test -json output or a jest --json report, told apart by content. Names the failing tests more reliably than the rubric's output. The rubric must still print its failures: a retry is told the last lines of its output. For example, CHALK_TEST_CMD, then CHALK_TEST_REPORT:

pytest --junitxml=report.xml                                    report.xml
go test -json ./... > report.json || { go test ./...; exit 1; }  report.json
npx jest --json --outputFile=report.json                        report.json

go test -json prints only JSON, so that rubric keeps it in the report and, when the tests fail, runs them again for output a person can read.

Loops, spend and verdicts

CHALK_BUDGET_USD

Default: 1.00

Spend cap per agent loop, in USD, enforced by Claude Code.

CHALK_MAX_LOOPS

Default: 20

Loops per run before detention. Worst-case spend per run is CHALK_BUDGET_USD x CHALK_MAX_LOOPS.

CHALK_MAX_RETRIES

Default: 2

Consecutive failed loops tolerated before detention.

CHALK_FP_RULES

Default: shadow

Each loop that makes no progress gets a verdict from its failing tests, first error and working tree (see chalk dashboard):

shadow  record the verdicts only
on      also detain at once when a loop repeats itself, changes nothing,
or fails like an open detention on another ticket
off     compute nothing

CHALK_FP_FEEDBACK

Default: false

What a retry is told about the failed loop before it:

false  the reason and the last 60 lines of the rubric's output
true   the failing tests and first error, normalized, and the last 20
lines (needs CHALK_FP_RULES shadow or on). The dashboard's prompt
sets compare the two.

CHALK_MAX_PARALLEL

Default: auto

Agents chalk fleet will run at once on one machine. auto picks the smallest of 8, half of Docker's CPUs, and Docker's memory less 1 GiB divided by CHALK_SANDBOX_MEM_MB (4 when Docker cannot be asked).

CHALK_SANDBOX_MEM_MB

Default: 2048

Memory one sandbox needs, in MiB, for CHALK_MAX_PARALLEL=auto.

The decider

CHALK_DECIDER

Default: off

A decider: a small, fast model that judges the loops the verdicts cannot settle (stuck or not?) and which past lessons apply. By default the local service from chalk decider up; it receives failing test names, first error lines, file names with line counts and lesson texts, never your files. One on another machine (CHALK_DECIDER_URL, set in the environment) gets nothing until chalk decider trust URL, which lists what it gets.

off     ask nothing
shadow  ask, and record the answers only (see `chalk dashboard`)
on      also act on answers at CHALK_DECIDER_THRESHOLD or above: detain
a stuck loop at once, and choose the lessons a loop is given

CHALK_DECIDER_THRESHOLD

Default: 0.9

The confidence, from 0.5 to 1, an answer needs before the decider acts.

CHALK_DECIDER_MIN_LESSONS

Default: 30

Resolved lessons needed before recall uses embeddings and the decider.

Sandbox

CHALK_IMAGE

Default: chalk-sandbox:local

Sandbox image. Needs bash 5.2 or newer, git, coreutils and the claude CLI. The default is Node 22. For another stack, build an image FROM chalk-sandbox:local (chalk sandbox build) with your toolchain, and set CHALK_CI_IMAGE in CI as well: see "Use your own stack" in the docs.

CHALK_TMPFS_SIZE

Default: 4g

RAM disk size for the working copy and its dependencies.

Checks and submission

CHALK_TEXTBOOK

Default: .chalk/textbook.md

Global engineering rules appended to the agent's system prompt.

CHALK_AUTO_MR

Default: true

Push and open the pull or merge request automatically when a run completes.

CHALK_SPEC_CHECK

Default: true

Before the first loop, a cheap model checks that every checkpoint is small, testable and unambiguous, and stops the run if not.

CHALK_REVIEW

Default: true

When all checkpoints are done, an independent agent reviews the change for stubs, weakened tests and drift from the spec before the merge request.

CHALK_REVIEW_ROUNDS

Default: 1

Fix-and-review-again rounds allowed before the work goes to detention.

CHALK_REVIEW_REQUIRED

Default: true

When the review cannot run (its call fails, or it gives no verdict), the work goes to detention (true), or the request opens and says the review did not run (false).

CHALK_REVIEW_MODEL

Default: none

Model for the review (empty: same as the loop).

CHALK_CHEAP_MODEL

Default: haiku

Model for the spec check and lesson distillation.

CHALK_DISTILL

Default: true

At office hours, turn the engineer's note and fix into a general lesson.

Permissions

CHALK_PERMISSION_MODE

Default: auto

How loops are permitted to act inside the sandbox:

auto    Claude Code's auto mode: a safety classifier reviews actions.
bypass  --dangerously-skip-permissions. Only where your organisation allows it.

The spec check, review and distillation are always read-only.

Model

CHALK_MODEL

Default: none

Optional model override, passed to claude --model. Auto mode needs a model that supports it (not Haiku).

Machine settings

These are read from the environment only, never from a repository, so a repository cannot point your agents' telemetry, or the test output a decider receives, somewhere else. Generated from CHALK_ENV_DEFAULTS in lib/config.sh. See The decider for the CHALK_DECIDER_* and CHALK_EMBED_URL settings.

• CHALK_OTEL_ENDPOINT (default none), CHALK_OTEL_PROTOCOL (default grpc), CHALK_OTEL_SIGNALS (default traces): OpenTelemetry export from the agents; off unless an endpoint is set.
• CHALK_DB_TIMEOUT (default auto): Seconds to wait for the database; auto adapts to the machine.
• CHALK_DECIDER_URL (default http://127.0.0.1:8471): Where the decider is (docs/decider-protocol.md): by default the local service that chalk decider up installs. A repository cannot point it elsewhere, since the decider receives test output. One on another machine is sent nothing until chalk decider trust URL.
• CHALK_DECIDER_TOKEN (default none): Bearer token for a hosted decider. Never logged.
• CHALK_EMBED_URL (default http://127.0.0.1:8472): Where semantic recall gets embeddings: the local chalk-embed.
• CHALK_DECIDER_IDLE_MINUTES (default 30): Minutes without a request after which the local decider stops; a run starts it again.
• CHALK_DECIDER_TIMEOUT (default auto): Seconds a run's start of the local decider waits for it; auto adapts to the machine.
• CHALK_EXTRA_CA_CERTS (default none): An absolute path to a PEM file of extra CA certificates, for a network that intercepts TLS, such as a corporate proxy. The sandbox image build and every sandbox trust it, as well as the CAs the image already has.

See OpenTelemetry for the CHALK_OTEL_* settings.

Other environment variables Chalk reads:

Variable	Meaning
ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN	Agent credentials; one is required. CLAUDE_CODE_OAUTH_TOKEN comes from claude setup-token and uses your Claude subscription; ANTHROPIC_API_KEY wins when both are set. Passed into each sandbox by name, so the value never appears in ps. See Sign in to Claude.
ANTHROPIC_BASE_URL	Passed into the sandbox when set, for a gateway (usually with ANTHROPIC_AUTH_TOKEN).
OTEL_EXPORTER_OTLP_HEADERS	Passed into the sandbox when set, for a collector that needs credentials.
CHALK_BASH	The bash 5.3 or newer to re-run Chalk under, when the one that started it is older.
XDG_STATE_HOME	Where run logs, plans and the report card go: $XDG_STATE_HOME/chalk, by default ~/.local/state/chalk.

Custom sandbox images

The default image, chalk-sandbox:local, is built from share/sandbox/Dockerfile by chalk sandbox build or the first run: Node 22 on Debian 12, with git, jq, ripgrep and the claude CLI. For other stacks, build an image FROM chalk-sandbox:local with your toolchain and set CHALK_IMAGE, and set CHALK_CI_IMAGE for the CI rubric. Use your own stack has worked Python and Go examples.

A sandbox image needs bash 5.2 or newer, git, coreutils and claude on PATH. Chalk checks the bash version when a sandbox starts, and chalk doctor checks it for the configured image. An image other than the default is never built by Chalk; pull or build it first.