Usage

Installation

python -m pip install -e .
python -m pip install -e ".[dev]"

Shell completion

After installing taskledger, install completion for the current shell:

taskledger --install-completion

To print the generated completion script without installing it:

taskledger --show-completion

Restart your shell session after installation.

Agent workflows work best when the taskledger skill is installed in the coding harness. The CLI uses a task-first lifecycle with explicit planning, approval, implementation, validation, locks, and handoff gates; without the skill, an agent may not know the intended command sequence or gate semantics.

Initialize state

taskledger init
taskledger init --taskledger-dir /mnt/cloud/taskledger/project-a

taskledger init writes taskledger.toml in the workspace root. The config defaults to taskledger_dir = ".taskledger" and stores only safe branch-scoped ledger state such as ledger_ref and ledger_next_task_number. .taskledger/ remains ignored and stores operational task state under .taskledger/ledgers/<ledger_ref>/.

Branch-local task work

When creating a long-lived Git branch, fork the Taskledger ledger pointer so active task state, plans, todos, events, indexes, and releases stay isolated from the parent branch:

git checkout -b feature-a
taskledger ledger fork feature-a
git add taskledger.toml

When Git later restores the parent branch’s taskledger.toml, default commands read the parent ledger again. Duplicate logical IDs such as task-0030 in two ledgers are expected. Use taskledger ledger adopt --from feature-a task-0030 to copy branch-local task history into the current ledger. Task-first workflow ——————-

taskledger task create rewrite-v2 --description "Migrate to the task-first design."
taskledger task activate rewrite-v2
taskledger plan start
taskledger question add --text "Should exports include v2?"
taskledger question answer-many --text "q-0001: Yes."
taskledger plan upsert --from-answers --criterion "Accepted workflow is implemented." --file ./plan.md
taskledger plan review --version 1
taskledger plan lint --version 1
taskledger plan accept --version 1 --note "Ready."

Planning guidance profiles

Taskledger supports project-local advisory planning guidance for agents. Configure it in the active project config file discovered for your workspace. Newer projects usually use taskledger.toml. Existing projects may still use .taskledger.toml; if both files exist, .taskledger.toml is discovered first.

Configure [prompt_profiles.planning] in that active config:

[prompt_profiles.planning]
profile = "strict"
question_policy = "always_before_plan"
max_required_questions = 3
min_acceptance_criteria = 2
todo_granularity = "atomic"
require_files = true
require_test_commands = true
require_expected_outputs = true
require_validation_hints = true
plan_body_detail = "detailed"
required_question_topics = ["scope", "compatibility", "test strategy"]
extra_guidance = "Every plan must mention docs, tests, and rollback or repair behavior."

Accepted values:

• profile: compact, balanced, strict, exploratory

• question_policy: ask_when_missing, always_before_plan, minimal

• todo_granularity: minimal, implementation_steps, atomic

• plan_body_detail: terse, normal, detailed

• max_required_questions and min_acceptance_criteria must be positive integers

• require_files, require_test_commands, require_expected_outputs, and require_validation_hints must be booleans

• required_question_topics must be a list of strings

• extra_guidance must be a string up to 4000 characters

Inspect guidance for the active task:

taskledger plan guidance
taskledger plan guidance --task task-0001
taskledger --json plan guidance
taskledger plan guidance --format json

Planning workflow integration:

taskledger plan start
taskledger plan guidance
taskledger plan template --include-guidance --file plan.md
taskledger plan lint --version 1
taskledger plan upsert --file plan.md

Revising a proposed plan safely:

taskledger plan revise
taskledger plan export --version latest --file ./plan.md
# edit ./plan.md (never edit .taskledger/ directly)
taskledger plan upsert --file ./plan.md
taskledger plan diff --from 1 --to 2

For structured scope trims, use:

taskledger plan amend --drop-criterion ac-0007 --drop-todo plan-todo-0010 --reason "User reduced scope."

Guidance output is deterministic and read-only. It is advisory only and does not enforce plan fields by itself. It cannot override lifecycle gates, plan approval, validation requirements, lock rules, required user answers, or higher-priority harness instructions.

Optional worker pipelines

Projects may optionally configure worker pipelines in taskledger.toml to guide fresh-context handoffs without changing the underlying task lifecycle. Worker pipelines are advisory overlays on the existing planning, implementation, and validation lifecycle. They can be three steps, four steps, five steps, or custom. When no worker pipeline is configured, taskledger behavior is unchanged.

Example configuration:

[worker_pipeline]
enabled = true
name = "api-contract-first"
mode = "guided"

[[worker_pipeline.steps]]
id = "planner"
lifecycle_stage = "planning"
base_context = "planner"

[[worker_pipeline.steps]]
id = "tester"
label = "Test Writer"
lifecycle_stage = "implementation"
base_context = "implementer"
actor_role = "implementer"
kind = "check"
description = "Add or update failing tests before code changes."
required_output = ["New or updated failing tests with a short summary."]
must_not = ["Do not change production code in this step."]
todo_tag = "tests"
test_command_policy = "may_fail"

[[worker_pipeline.steps]]
id = "coder"
lifecycle_stage = "implementation"
base_context = "implementer"
kind = "todo"
description = "Implement the approved change and make the tests pass."
required_output = ["Code changes plus passing targeted checks."]
must_not = ["Do not skip required validation evidence."]
todo_tag = "implementation"
test_command_policy = "must_pass"

[[worker_pipeline.steps]]
id = "domain-reviewer"
lifecycle_stage = "review"
base_context = "spec-reviewer"
kind = "review"

Supported top-level keys are enabled, name, mode, and steps. Supported step keys are id, label, lifecycle_stage, base_context, actor_role, kind, description, required_output, must_not, todo_tag, and test_command_policy. guided mode remains advisory: it does not add new planning, implementation, or validation gates. Instead it augments taskledger next-action with worker-step metadata plus ready-to-run worker context and handoff commands for the pending step.

Inspect and use the configured overlay explicitly:

taskledger pipeline show
taskledger pipeline list
taskledger pipeline next
taskledger next-action
taskledger pipeline context tester
taskledger context --worker tester
taskledger handoff create --worker tester --summary "Add failing tests only."
taskledger handoff create --worker domain-reviewer --scope task --summary "Review the implementation."

To include worker-step todo hints in a plan template, enable a worker pipeline with mode = "template" or mode = "guided" and opt in per task:

taskledger plan template --with-worker-pipeline --file ./plan.md

Use worker_step only on plan todos for projects that have an enabled worker pipeline:

todos:
  - id: plan-todo-0001
    text: "Add failing regression tests."
    worker_step: "tester"
    validation_hint: "pytest -q tests/test_parser.py"

Release tagging and changelog context

Use durable release tags to mark completed task boundaries and generate provider-neutral changelog source context from done tasks:

taskledger release tag 0.4.1 --at-task task-0030 --note "0.4.1 released"
taskledger release changelog 0.4.2 --since 0.4.1 --until-task task-0035 --output /tmp/taskledger-0.4.2-changelog-source.md
taskledger release show 0.4.1
taskledger release list

release changelog renders Markdown or JSON context for an external LLM or human changelog drafting step. It does not call a model provider directly.

Recording manually completed work

For work completed outside the task-first lifecycle (operational tasks, exploratory work, or manual testing), use task record to create a done task directly without acquiring locks or lifecycle gates. Never use task record as a shortcut for active task management.

taskledger task record "Deploy v0.4.1" --summary "Deployed to production" --change "deploy.sh:run:Updated config" --evidence "Monitoring shows no errors"
taskledger task record "Manual testing" --summary "Tested new API endpoints" --allow-empty-record --reason "Exploratory testing"

Archiving tasks

Archiving hides tasks from default list/tree/dashboard views without deleting history. It is a visibility operation, not an export archive operation.

taskledger task archive task-0030 --reason "Hide historical task"
taskledger task list --archived
taskledger task unarchive task-0030 --reason "Reopen historical task" --slug task-0030-reopened
taskledger tree --include-archived

Post-completion follow-up deltas

When a task is already done and the user requests a small later change, do not reopen the completed task. Create a follow-up task linked to the completed parent and run the normal lifecycle on that child:

taskledger task follow-up rewrite-v2 "Rename submit label" --description "Small post-completion delta." --activate
taskledger plan start
taskledger plan upsert --file ./plan.md
taskledger plan review --version 1
taskledger plan accept --version 1 --note "Ready."
taskledger implement start
taskledger validate start

task follow-up keeps done terminal on the parent task while preserving a traceable child record for the new delta.

Fresh-context entrypoint

Use taskledger next-action before a broad context read when you need the next concrete work item instead of a generic stage summary.

taskledger next-action
taskledger --json next-action

Human output now names the next question, todo, criterion, or repair step and includes the primary command hint. JSON output preserves the existing task_next_action fields and also includes next_item, commands, and progress.

Agents should inspect next_item first, run next_command when it is safe, avoid inventing question answers, and only mark todos done after evidence exists.

If next-action reports an orphaned implementation state or an active lock recovery situation, inspect the task and lock first, then choose the recovery path that matches the lock state:

taskledger task show
taskledger task show task-0001
taskledger lock show
taskledger doctor

Lock recovery decision tree:

1. Run taskledger lock show --task TASK. lock show reports a classification field that names the lock state.

2. If there is no lock, run taskledger next-action.

3. If classification is expired and the lock is an implementation lock for a running implementation run: run taskledger implement resume --repair-expired-lock --task TASK --reason "...".

4. If classification is active_dead_local_process: run taskledger repair lock --task TASK --reason "Holder PID ... is no longer running.", then taskledger implement resume --task TASK --reason "...".

5. If classification is active_live_local_process or active_other_actor: do not repair; use a handoff or wait for the holder to release.

6. If classification is active_unverifiable_remote_or_unknown_process: do not infer staleness from local process checks; inspect handoffs or ask the user before repairing.

7. next-action itself returns action=repair-lock with diagnostics and the recommended command sequence when the active implementation lock has a dead local holder PID.

--repair-expired-lock is not a general stale-lock takeover flag. It only handles locks whose expires_at is in the past. For non-expired active locks, use the decision tree above.

If the task is actually cancelled and the user wants to continue, restore it with task uncancel first, then run next-action again. A restored task may return to a safe durable stage such as approved while an implementation run is still running; in that case use implement resume instead of implement start.

Compact implementation loop

For routine same-session implementation, prefer next-action and the next todo over a broad generated context read:

taskledger --json next-action
taskledger --json todo next
taskledger todo show todo-0003
# implement only that todo
pytest tests/...
taskledger todo done todo-0003 --evidence "pytest tests/... passed"
taskledger --json next-action

Rules for agents:

• Install the taskledger skill in the coding harness before relying on agent-driven workflows.

• Prefer next-action and todo next over generated context during normal work.

• Use the todo validation_hint before marking a todo done.

• Record concise evidence with todo done.

• Do not create handoffs or context bundles unless the user asked to switch harness or session.

Human monitoring UI

taskledger serve starts a read-only localhost server-rendered HTML dashboard for a human operator. It re-renders HTML on each request and can add meta refresh when requested.

taskledger report html task-0040 --output task-0040.html
taskledger report html --active --output active-task.html
taskledger report site --output .taskledger-report/
taskledger serve --refresh-seconds 2
taskledger serve --open
taskledger serve --task task-0040 --refresh-seconds 2

Agents should continue to use next-action, todo next, and --json as the canonical machine interface for routine same-session work. Reach for context or handoffs when the task actually needs broader fresh-context transfer.

task report generates a human-readable Markdown report for a single task. It is for humans who want to review, archive, or share a task outside the terminal.

taskledger task report --task task-0030 -o task30.md
taskledger task report --preset planning --without todos -o plan-review.md
taskledger task report --task task-0030 --include command-log
taskledger task report --task task-0030

context is agent-handoff-oriented. task report and root report HTML commands are human-oriented. task dossier remains available as an advanced/compatibility full-context dump; prefer context --for ... for new agent protocols.

task transcript renders a per-task command transcript from the ledger-level agent log store:

taskledger task transcript --task task-0030 -o task30-transcript.md
taskledger task transcript --task task-0030 --include-output
taskledger task transcript --task task-0030 --raw
taskledger task transcript --task task-0030 --failures
taskledger --json task transcript --task task-0030

task export writes a single Markdown file containing a curated archive report, raw record files from the taskledger bundle, and optional source-file snapshots. Use it when handing a completed task to an LLM or coding agent for review, documentation updates, or follow-up implementation work.

taskledger task export task-0030 -o task-0030.llm.md
taskledger task export task-0030 --no-source-files -o task-0030.records.md
taskledger task export task-0030 --source-file README.md -o task-0030.llm.md
taskledger --json task export task-0030 -o task-0030.llm.md

Distinction:

• task report: human-readable review/archive report.

• context: canonical fresh continuation context for an active agent.

• handoff show: durable transfer context created for another session or actor.

• task dossier: advanced/compatibility full-context dump.

• task transcript: command audit trail.

• task export: single-file LLM handoff/archive of one complete task bundle.

todo-work: Implementation is in progress; 1 todos remain.
Next todo: todo-0001 -- Update next-action JSON payload.
Command: taskledger todo show todo-0001
Mark todo done after evidence exists: taskledger todo done todo-0001 --evidence "..."
Progress: 0/1 todos done

{
  "kind": "task_next_action",
  "action": "todo-work",
  "next_command": "taskledger todo show todo-0001",
   "next_item": {
     "kind": "todo",
     "id": "todo-0001",
     "text": "Update next-action JSON payload.",
     "validation_hint": "Run: pytest tests/test_todo_implementation_gate.py -q; Expected: pass",
     "done_command_hint": "taskledger todo done todo-0001 --evidence \"...\""
   },
   "commands": [
     {
       "kind": "inspect",
       "label": "Show next todo",
       "command": "taskledger todo show todo-0001",
       "primary": true
     },
     {
       "kind": "complete",
       "label": "Mark todo done after evidence exists",
       "command": "taskledger todo done todo-0001 --evidence \"...\"",
       "primary": false
     }
   ],
  "progress": {
    "todos": {
      "total": 1,
      "done": 0,
      "open": 1,
      "open_ids": ["todo-0001"]
    }
  },
  "blocking": []
}

All approval escape hatches require --reason:

taskledger plan approve --version 1 --actor user --approval-source explicit_chat --note "Ready." --no-materialize-todos --reason "trivial task"
taskledger plan approve --version 1 --actor user --approval-source explicit_chat --note "Ready." --allow-empty-criteria --reason "no criteria needed"
taskledger plan approve --version 1 --actor user --approval-source explicit_chat --note "Ready." --allow-lint-errors --reason "user accepted rough plan"

Use plan command to record diagnostic commands during planning:

taskledger plan command -- pytest tests/ -q
taskledger plan command --allow-failure -- pytest tests/ -q
taskledger implement command -- ruff check --config=.ruff.toml .
taskledger implement command --allow-failure -- python -c "raise SystemExit(7)"

When [agent_logging].enabled = true in taskledger.toml, taskledger records CLI invocations and managed command outputs. Keep logging opt-in because stdout/stderr may contain sensitive data. Route task-relevant commands through plan command and implement command so their output is included in task transcripts and reports.

taskledger context –for implementation –format markdown taskledger implement start taskledger implement log –message “Started implementation.” taskledger implement change –path taskledger/storage/task_store.py –kind edit –summary “Updated storage semantics.” taskledger implement scan-changes –from-git –summary “Implementation diff summary.” taskledger implement finish –summary “Implemented the approved plan.” taskledger review record –result pass –summary “No blocking code-quality issues.”

taskledger context –for validation –format markdown taskledger validate start taskledger validate check –criterion ac-0001 –status pass –evidence “pytest -q tests/test_taskledger_v2_cli.py” taskledger validate finish –result passed –summary “Validated the rewrite.”

Code review evidence can also be recorded after validate finish has moved the task to done. This appends durable review evidence to the task and does not reopen or otherwise mutate the task lifecycle stage.

If validation finds an implementation bug and the accepted plan is still correct, restart implementation instead of replanning:

taskledger validate finish --result failed --summary "Parser edge case still fails."
taskledger next-action
taskledger context --for implementation --format markdown
taskledger implement restart --summary "Fix failed validation findings."

If validation finds an implementation bug and the accepted plan is still correct, restart implementation instead of replanning:

taskledger validate finish --result failed --summary "Parser edge case still fails."
taskledger next-action
taskledger context --for implementation --format markdown
taskledger implement restart --summary "Fix failed validation findings."

Machine-readable output

taskledger --json status --full
taskledger --json task active
taskledger --json task show
taskledger --json task show task-0001
taskledger --json context --for validation --format json
taskledger --json review list --task task-0001

{
  "ok": true,
  "command": "status",
  "result": {
    "kind": "taskledger_status",
    "workspace_root": "/workspace",
    "config_path": "/workspace/taskledger.toml",
    "taskledger_dir": "/workspace/.taskledger",
    "project_dir": "/workspace/.taskledger",
    "counts": {
      "tasks": 1,
      "introductions": 0,
     "plans": 1,
     "questions": 1,
     "runs": 2,
     "changes": 1,
     "locks": 0
   },
   "active_task": null,
   "healthy": true
  },
  "events": []
}

Cloud-backed storage

Use one storage root per source project:

taskledger init --taskledger-dir /mnt/cloud/taskledger/project-a

Do not point two unrelated repositories at the same taskledger_dir. See Sync taskledger state across PCs for the recommended private-Git workflow when you want to use the same Taskledger state across multiple PCs without committing .taskledger/.

Integrity and recovery

taskledger doctor
taskledger doctor locks
taskledger lock show
taskledger repair lock --reason "recover stale planning lock"
taskledger implement resume --reason "Reacquire implementation lock for existing running run."
taskledger task uncancel --task TASK_REF --reason "Restore the task to a safe durable stage."
taskledger next-action
taskledger repair index

Export and snapshots

taskledger init --project-name "Taskledger"
taskledger export
taskledger export --task task-0040
taskledger export task-0040
taskledger sync export --output ./taskledger-transfer.tar.gz
taskledger import ./taskledger-transfer.tar.gz --dry-run
taskledger sync import ./taskledger-transfer.tar.gz --dry-run
taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz --id-policy fail-on-conflict
taskledger import ./taskledger-transfer.tar.gz --replace

For private multi-PC full-state sync with external storage, use:

taskledger sync git init --repo ../taskledger-state --project-path project-a
taskledger sync git status
taskledger sync git pull
taskledger sync git push
taskledger sync git push --message "Sync project-a taskledger state"
taskledger snapshot ./artifacts

When no explicit output path is passed, default export archives are written inside the resolved workspace root. Filenames are project-specific:

taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz
taskledger-task-{project_slug}-{ledger_ref}-{task_id}-{timestamp}.tar.gz

project_slug is derived from project_name in taskledger.toml. If unset, taskledger falls back to the workspace directory name. UUID safety checks still use project_uuid only.

Export include flags are content-affecting:

• --no-include-bodies removes record body fields from the exported payload.

• --include-run-artifacts embeds artifact files under artifacts/ in the archive.

Cross-machine imports preserve durable task/run records but quarantine imported runtime locks by default. For an imported in-progress implementation, run:

taskledger next-action
taskledger implement resume --reason "Continue imported implementation."

Use --lock-policy keep only when you explicitly want diagnostic lock restoration behavior.

Single-task transfer from a config-only checkout

# fresh checkout on another PC
taskledger init
taskledger task create "Fix import edge case" --slug fix-import-edge-case --description "..."
# ... normal plan / implementation / validation lifecycle ...
taskledger export task-0040

# main dev repo
taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
taskledger task list
taskledger task show task-0040