Configuration

Configuration

Project configuration lives in .handoff/config.toml. It is human-editable, but every section can also be patched through handoff_update_config with dot-notation keys (e.g. "calendar.work_hours_per_day": 7). The VSCode extension and the MCP server write the same file, so the GUI and the agent stay in full parity. All writes are atomic (temp file + rename), so a concurrent reader never sees a half-written file.

Full schema

[project]
name = "my-project"                   # required
description = "Project description"    # optional

[settings]
history_limit = 20            # max closed sessions to keep
done_task_limit = 10          # max completed tasks shown in load_context
auto_git_summary = true       # capture git state automatically
require_estimate_hours = true # require estimate_hours on leaf tasks
ai_estimate_multiplier = 0.2  # human estimate → AI-effort hours multiplier
context_files = []            # files always loaded into context (relative paths)
custom_fields = {}            # user-defined key/value pairs

[dashboard]
scan_dirs = ["~/pro/"]                            # dirs the dashboard scans
exclude_patterns = ["*/target", "*/node_modules"] # patterns to skip

[calendar]
work_hours_per_day = 8
closed_weekdays = ["sat", "sun"]
closed_dates = ["2026-12-25"]
open_dates = []
schedule_mode = "auto"        # "auto" or "manual"
overwork_limit_percent = 150

[calendar.day_hours]
fri = 4                       # per-weekday hour overrides

[effort_budget]
total_hours = 500             # total project effort cap

[assignees.alice]
display_name = "Alice Chen"
color = "#4A90D9"
work_hours_per_day = 8
closed_weekdays = [1, 2]      # per-assignee overrides

[assignees.bob]
display_name = "Bob Martinez"
color = "#E74C3C"
work_hours_per_day = 6

[milestones.v1]
date = "2026-09-30"
color = "#27AE60"
description = "First public release"

[gantt_view]
sort = "start"                # start, id, id-desc, status
zoom = "week"                 # day, week, month
mode = "compare"              # plan, actual, compare

[settings]

Key	Type	Default	Meaning
history_limit	int	20	How many closed session files to retain.
done_task_limit	int	10	How many completed tasks to include in the load_context index.
auto_git_summary	bool	true	Include git branch / log / dirty files in loaded context.
require_estimate_hours	bool	true	Require schedule.estimate_hours > 0 on leaf tasks. See Estimates and Capacity.
ai_estimate_multiplier	number	0.2	Factor applied to raw estimates to model AI-effort hours. Negative values are rejected.
context_files	list	[]	Relative file paths always loaded into context.
custom_fields	table	{}	Free-form user key/value pairs.

[calendar]

Defines working time for scheduling and capacity. closed_weekdays and closed_dates mark non-working time; open_dates re-opens specific dates; [calendar.day_hours] overrides hours for individual weekdays. schedule_mode chooses automatic vs. manual scheduling, and overwork_limit_percent caps how far a day can be overbooked.

[assignees.<key>]

Each team member is a table keyed by a short identifier (the value used in a task's assignee field). Per-assignee work_hours_per_day and closed_weekdays override the project calendar. Manage members with handoff_add_assignee / handoff_update_assignee / handoff_remove_assignee (removal unassigns them from every task).

[milestones.<key>]

Milestones group tasks by target date. Manage with handoff_add_milestone / handoff_update_milestone / handoff_remove_milestone; reference one from a task via schedule.milestone.

[effort_budget] and [gantt_view]

[effort_budget].total_hours sets a project-wide effort cap that handoff_get_metrics reports against. [gantt_view] stores the GUI's gantt display preferences (sort, zoom, mode).