The setup file is goal.toml. It answers a few plain questions:

You may see these short names in the config and deeper docs:

Example:

name = "paper-ready"
state_dir = ".goal"
runs_dir = ".goal/runs"

[artifact]
path = "outputs/writing/full_paper.pdf"
copy_as = "full_paper.pdf"

[producer]
command = "python3 scripts/orchestrator.py --full"

[tik]
provider = "codex_file"
timeout_seconds = 1800
max_file_size_bytes = 25000000
max_output_tokens = 4096

[tok]
provider = "codex_goal"
write_dirs = ["src", "data"]
run_cwd = "."
runtime_write_dirs = ["outputs", "build", "logs"]
sandbox = "workspace-write"
codex_features = ["goals"]

[safety]
generated_dirs = ["outputs", "build", "logs"]
max_blocker_repeats = 3

To run several reviewers at once, move provider-specific fields into [[tik.providers]]. The heartbeat runs them in parallel and hands tok one aggregate tik.md containing every provider result.

[tik]
timeout_seconds = 1800

[[tik.providers]]
label = "codex"
provider = "codex_file"

[[tik.providers]]
label = "claude"
provider = "claude_code_file"

[[tik.providers]]
label = "checklist"
provider = "checklist"
command = "python3 scripts/checklist_review.py"

Use codex_app_server instead of codex_goal when tok should drive Codex through codex app-server --stdio rather than codex exec. Swap codex_file for claude_code_file and codex_goal for claude_code_goal to run the same loop through Claude Code instead of Codex; examples/scientificity-claude/goal.toml is the all-Claude version of this setup.

Use checklist for command-backed checklist reviews that should appear as their own tik provider in ledgers and state.

The important boundary is simple: the fixing agent edits source, but the final result has to be rebuilt and checked before the work counts as done.

Perpetual mode is explicit opt-in. It keeps one fixed substantive goal alive through bounded heartbeats, sleeps when the artifact is healthy, and applies model or producer changes only through an exact file-operation lease:

[perpetual]
enabled = true
substantive_goal = "Resolve the fixed substantive objections in the paper."

[lease]
version = "paper-v1"
allow_shell = true
allow_network = false

[[lease.rules]]
effect = "allow"
operations = ["create", "modify", "delete", "rename"]
paths = ["manuscript/**", "analysis/**"]

[[lease.rules]]
effect = "allow"
operations = ["create", "modify"]
paths = ["output/paper.pdf"]

Healthy inspection defaults to 6 hours, active or blocked work to 30 minutes, and provider failures to 5 minutes, 30 minutes, then 2 hours capped. The OS timer wakes every 5 minutes by default for perpetual goals, but next_due_at short-circuits work that is not due. goal-cli state shows the immutable goal binding, bounded attempt evidence, and transaction recovery journal. Use goal-cli stop and goal-cli resume for durable operator control without terminal completion. See the full perpetual and lease schema.

If you are working inside the goal-cli repository itself:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e '.[openai]'
goal-cli --help

Use the basic install without OpenAI support when you only need local checks:

python3 -m pip install -e .

If your coding agent supports skills, install the setup skill:

mkdir -p "$HOME/.codex/skills"
cp -R skills/goal-cli-project-setup "$HOME/.codex/skills/"

Use goal-cli-project-setup for real projects. Use goal-cli-template-author only when you are improving reusable examples or docs in this repository.

goal-cli is early local tooling, currently version 0.1.0.

The project is distributed under the MIT License. See SECURITY.md for vulnerability reporting and CHANGELOG.md for release notes.