Human Token Cost

Human Token Cost is a local-first cognitive load relief tool for people using agents. It helps you keep project load, open decisions, stale work, and parallel context under an explicit capacity budget.

v0.11.3 is a Python 3.11 stdlib-first slice that works from local files and the CLI. JSON is the canonical storage format. A tiny safe YAML subset is also accepted for simple data/projects.yaml or data/config.yaml files when you do not want JSON.

Quickstart

python3 -m human_token_cost init
python3 -m human_token_cost calibrate --focus-hours 4 --context-switches 8 --decision-fatigue 2 --open-loop-tolerance 3 --support-level 2 --recovery-quality 3
python3 -m human_token_cost calibrate --focus-hours 4 --context-switches 8 --decision-fatigue 2 --open-loop-tolerance 3 --support-level 2 --recovery-quality 3 --write
python3 -m human_token_cost capture example-project --name "Example project" --status active --next-action "Finish review" --stop-condition "Review accepted" --human-token-cost 3
python3 -m human_token_cost validate
python3 -m human_token_cost score example-project
python3 -m human_token_cost status
python3 -m human_token_cost sentinel
python3 -m human_token_cost audit
python3 -m human_token_cost gate

init writes sample files:

• data/config.json
• data/projects.json

calibrate estimates the installer's Human Token Cost capacity before setting hard limits. Without --write, it only prints recommended capacity. With --write, it updates data/config.json.

audit writes:

• audits/YYYY-WW.json
• audits/YYYY-WW.md

The package also exposes a console entrypoint named human-token-cost when installed from this repo.

CLI

python3 -m human_token_cost init
python3 -m human_token_cost calibrate [--focus-hours 0-12] [--context-switches 0-30] [--decision-fatigue 0-5] [--open-loop-tolerance 0-5] [--support-level 0-5] [--recovery-quality 0-5] [--write] [--json]
python3 -m human_token_cost capture <project-id> --name "..." --status active --next-action "..." --stop-condition "..." [--human-token-cost 0-5]
python3 -m human_token_cost score <project-id> [--json]
python3 -m human_token_cost status [--json]
python3 -m human_token_cost sentinel [--silent-ok]
python3 -m human_token_cost audit
python3 -m human_token_cost gate

Use --root <path> before the subcommand to point at another workspace:

python3 -m human_token_cost --root /path/to/workspace sentinel --silent-ok

sentinel prints only anomalies. With --silent-ok, it prints nothing when the ledger is clean. It exits 1 when anomalies exist.

gate reports whether starting a new project is currently allowed. It exits 0 for open and 1 for closed.

status prints the current ledger summary: capacity, gate, projects, and anomalies. Use --json when another agent or script needs structured output.

capture records project facts from conversation and execution events into the local Human Token Cost ledger.

Capacity Calibration

Run calibrate before deciding the maximum Human Token Cost that this installation should allow.

Inputs:

• focus_hours: daily deep-focus hours available for agent work, 0-12
• context_switches: daily context switches, 0-30
• decision_fatigue: how costly decisions feel right now, 0-5
• open_loop_tolerance: how many waiting/open loops feel manageable, 0-5
• support_level: available delegation or operational support, 0-5
• recovery_quality: sleep and recovery quality, 0-5

The command recommends:

• max_total_human_token_cost
• max_active_projects
• max_human_token_cost_5_projects
• max_human_token_cost_3_plus_projects
• max_waiting_human

Data Schema

Project ledger path:

• canonical: data/projects.json
• optional tiny YAML subset: data/projects.yaml or data/projects.yml

Canonical shape:

{
  "projects": [
    {
      "id": "prototype-demo",
      "name": "Prototype demo",
      "status": "active",
      "decision_load": 3,
      "taste_load": 3,
      "context_load": 2,
      "risk_load": 2,
      "coordination_load": 1,
      "autonomy_discount": 1,
      "last_progress_at": "2026-05-10",
      "next_action": "Pick one shippable prototype slice",
      "stop_condition": "Playable local demo and notes captured"
    }
  ]
}

Required project fields:

• id: stable unique string
• name: display name
• status: one of active, waiting_human, parked, done, archived

Operational fields:

• next_action: required for active and waiting_human
• stop_condition: required for active and waiting_human
• last_progress_at: ISO date used for active staleness
• waiting_since: ISO date used for waiting_human staleness
• parked_since: ISO date used for parked kill-review

Scoring fields:

• decision_load: 0-3
• taste_load: 0-3
• context_load: 0-3
• risk_load: 0-3
• coordination_load: 0-3
• autonomy_discount: 0-3
• human_token_cost: optional manual override, 0-5

Manual human_token_cost wins over calculated factors.

Scoring

Human Token Cost is deterministic and explainable.

raw_total = decision_load
          + taste_load
          + context_load
          + risk_load
          + coordination_load
          - autonomy_discount

score = ceil(max(raw_total, 0) / 3), clamped to 0..5

python3 -m human_token_cost score <project-id> --json includes the factor breakdown.

Policy

Default capacity:

• max_total_human_token_cost = 12
• max_active_projects = 7
• max_human_token_cost_5_projects = 1
• max_human_token_cost_3_plus_projects = 3
• max_waiting_human = 3

Default staleness:

• active_without_progress_days = 14
• waiting_human_days = 7
• parked_review_days = 45

The policy engine detects:

• overload against capacity limits
• missing next_action
• missing stop_condition
• stale active projects
• stale waiting_human projects
• parked kill-review candidates
• new project gate status

Scope

Included:

• local project ledger
• installer capacity calibration via calibrate
• conversation/event capture via capture
• deterministic Human Token Cost scoring
• policy anomalies
• daily sentinel CLI
• weekly audit JSON and Markdown outputs
• sample config and sample generic projects
• stdlib unittest coverage

Non-goals:

• no external issue tracker sync as a source of truth
• no machine-specific path assumptions