akm-cli/docs/guides/scheduling.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

# Scheduling

This guide covers running akm tasks — `akm improve` and other background
work — through the OS scheduler (cron / launchd / schtasks) safely: how
`akm setup` reviews task definitions before touching the scheduler, how to
verify the result, and how to migrate or repair scheduler bindings after
moving or reinstalling akm.

## Review tasks during setup

Interactive setup reviews every embedded task definition — both the
general-purpose core task-template set and the maintainer-oriented
multi-cadence improve task set — in one pass. See the
[task CLI reference](../reference/cli.md#task) for the full template list.

```sh
akm setup
```

Before any OS scheduler change, setup shows every reviewed task's schedule
and enabled state and asks one explicit activation question. Confirming runs
the scheduler sync; declining leaves both task files and scheduler state
unchanged.

**Safety note:** schedule activation always requires an explicit confirmation
after reviewing the complete task summary. Nothing is written to the OS
scheduler without that review step.

## Verify

```sh
akm task doctor
```

`akm task doctor` reports the scheduler backend, paths, task state, and
warnings — run it after any setup pass, and again after a `--rebind` (below),
to confirm the scheduler state matches what you expect.

## Non-interactive setup never activates schedules

`akm setup --yes`, config-file setup, and CI runs skip the task step
entirely: neither task definitions nor OS scheduler entries are created or
changed. Run interactive `akm setup` to review, prepare, and activate tasks.

## Task definitions vs. scheduler state

Task definitions live under `<bundle>/tasks/` as task source v4 `.yml` sources;
the [task source reference](../reference/tasks.md) defines their executable and
scheduling grammar. A definition cannot enable itself: the refs this host schedules live
separately in `config.json` under `scheduler.enabled`, a list of
fully-qualified refs. Use `akm task enable <bundle>//tasks/<id>` or `akm task
disable <ref>` to change it without editing bundle content. An unscoped `akm
task sync` installs exactly the listed refs from every enabled configured
bundle and removes akm-written bindings for refs that are gone or no longer
listed. Removing a bundle drops its refs from the list; disabling a bundle
leaves them inert.

Native scheduler entries are separate OS state. Activation captures the
installed akm runtime so scheduled execution does not silently switch to a
different checkout or package. Editing definitions and running ordinary `akm
task sync` preserves that captured runtime.

A scheduled fire re-reads the guarded current source and creates a fresh
durable-v4-family freeze at executable `irVersion: 5`.
Scheduler sync/validation evidence is not an executable snapshot and is never reused as the later run plan.

## A scheduled `akm improve` covers one bundle

An `akm improve` run improves one bundle, the one it writes to: `--bundle`,
else `defaultWriteTarget`, else the working bundle. A scheduled row sets
`AKM_BUNDLE_DIR` to the working bundle of the shell that synced it, so a
scheduled `akm improve` covers that bundle (or `defaultWriteTarget`, when set)
and leaves your other bundles alone, even the writable ones. To improve
another bundle on a schedule, give it a task of its own; the `--bundle` inside
the command is `akm improve`'s own:

```sh
akm task add improve-team --schedule "15 3 * * *" \
  --command "akm improve --bundle team --skip-if-locked --require-engines"
```

## Rerunning setup preserves scheduler bindings

Rerunning `akm setup` preserves existing scheduler bindings by design — it
will not silently rebind entries that are already activated.

## Upgrades

A config written before 0.9.17 has no `scheduler.enabled` list. The first
`akm task sync` (or `setup`, `task enable`, `task disable`, `task add`) after
the upgrade takes the akm-written rows already installed in the native
scheduler as this host's choice, writes the list, and says so — a scheduled
task survives an upgrade by any install method with no manual step. An
explicit empty list is a choice: sync then removes every akm-written row.
`akm migrate status` reports anything else that remains pending, and why.

## Migrating or repairing scheduler bindings (`--rebind`)

If akm was moved, reinstalled under a different package prefix, or repaired
after an installation problem, migrate scheduler entries deliberately:

```sh
akm task sync --rebind
akm task doctor
```

Use `--rebind` only for that explicit runtime migration or repair — it
captures the current installed runtime, replacing whatever runtime a prior
activation had captured.

If you change the AKM storage path during reconfiguration, or move or install
akm at a new runtime path, follow setup with `akm task sync --rebind`; setup
never silently rebinds existing entries on your behalf.

## See also

- [Getting Started](getting-started.md) — the first-run path this guide was
  split out of
- [CLI Reference: task](../reference/cli.md#task) — the full `task` command
  group, including `add`, `enable`, `disable`, `run`, `sync`, `doctor`, and
  `history`
- [Task source reference](../reference/tasks.md) — exact file grammar,
  targets, triggers, and migration