Skip to main content

Tickwork CLI

A clock tick starts the work. Tickwork manages scheduled commands on this device, with JSON output for agents and humans. Linux uses systemd user timers, macOS uses launchd GUI agents, and Windows uses Task Scheduler under the current user. MIT licensed.

No daemon, web UI, remote management or AI-specific runtime. Commands, scripts and AI CLIs use the same argv execution model.

Install and discover

Python 3.12+ is required. Until the initial PyPI publication, install from GitHub:

uv tool install git+https://github.com/Kepler452Byte/tickwork-cli.git
tickwork --help
tickwork task --help
tickwork doctor

Every public response, including help and errors, is one UTF-8 JSON object. Success and previews use stdout; errors use stderr and a nonzero exit code. Child output is captured separately in SQLite. No implicit shell is used.

Schedule a command

Write a JSON file with an absolute executable and working directory:

{
  "id": "vault-sync",
  "argv": ["/home/user/.local/bin/campfire", "--workspace", "personal", "workspace", "git", "sync", "--confirm"],
  "cwd": "/home/user/vault",
  "schedule": {"kind": "interval", "seconds": 300},
  "timeout": 240
}
tickwork task create --file task.json
# Inspect the preview; use its actual plan hash:
tickwork task create --file task.json --expected-plan <hash> --confirm
# New tasks are paused. Test the command, then explicitly resume:
tickwork task run vault-sync --confirm
tickwork task resume vault-sync
tickwork task resume vault-sync --expected-plan <hash-from-resume> --confirm
tickwork task show vault-sync
tickwork task history --task vault-sync
tickwork task result <run-id>
tickwork task logs <run-id> --after 0 --limit 20

Update, pause and delete also preview and require the current plan hash. Updates preserve paused state. Busy tasks reject mutations; deletion never force-kills a running command. Same-task runs never overlap. Timeout kills the child process tree. Process exit zero does not prove the expected business artifact exists.

Intervals are native start-to-start, whole minutes 60..86400 seconds. Daily { "kind": "daily", "time": "09:00" } and weekly { "kind": "weekly", "day": "mon", "time": "09:00" } use device-local time and native DST rules. No retries, wake-up or application catch-up. launchd may coalesce missed calendar triggers on wake. See packaged platform notes.

The user scheduler/session must be available. Tickwork does not enable Linux lingering, create privileged services or save Windows credentials. doctor exposes session conditions and native diagnostics. Only matching ownership markers are managed.

Local data and Agent resources

~/.tickwork/ is the default; set TICKWORK_HOME or global --home to override. Back up tasks.yaml, the only durable task definitions. Native deployments are derived; actual enabled state comes from the scheduler. tickwork.db contains disposable run history and streamed stdout/stderr. .locks/ contains OS-held runtime locks, independent of SQLite.

Logs are capped at 10 MiB per run and expose truncation. Finished history retains up to 100 records and 30 days, pruned on new runs. Pagination uses offsets for history and sequence cursors for logs. Delete DB/WAL files only with no running tasks; definitions and native deployments persist, historical logs do not recover. No migration chain or legacy formats.

Install the packaged Hint and single Skill explicitly into chosen destinations:

tickwork agent install --agents-file /absolute/AGENTS.md --skills-dir /absolute/skills
tickwork agent install --agents-file /absolute/AGENTS.md --skills-dir /absolute/skills --expected-plan <hash> --confirm

This preserves unrelated instructions/files, rejects locally edited Skill files, and never creates or enables tasks.

Development and verification

uv sync --locked
uv run python scripts/quality_check.py --release
# Requires a working native user scheduler; creates and cleans only test-owned jobs:
RUN_NATIVE_TEST=1 uv run pytest -q tests/integration

CI runs quality, isolated wheel installation, native deployment and actual timer execution on Linux, macOS and Windows. Native evidence is uploaded per platform. Authenticated AI command execution is a separate local check; CI does not store AI credentials. PyPI publication is pending owner Trusted Publisher configuration.

Metadata

Release files for tickwork-cli 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tickwork-cli 0.1.0
File Size Uploaded Provenance Actions
tickwork_cli-0.1.0.tar.gz 54.4 kB With provenance Details for tickwork_cli-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tickwork-cli 0.1.0
File Interpreter ABI Platform Actions
tickwork_cli-0.1.0-py3-none-any.whl Python 3 none any Details for tickwork_cli-0.1.0-py3-none-any.whl

Total release size: 87.7 kB

Release files / tickwork_cli-0.1.0.tar.gz

Download URL tickwork_cli-0.1.0.tar.gz
Size 54.4 kB
Tags Source
SHA-256 checksum
How to use checksums
355e17c836ae15e9a33c2b0ffc19fa783f520a688972754871bb19e6d705cfe8
BLAKE2b-256 checksum
How to use checksums
c3c247bce192a852e91b1168be797dbe220f27ebb3032ed91277a5ff1d661708
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Release files / tickwork_cli-0.1.0-py3-none-any.whl

Download URL tickwork_cli-0.1.0-py3-none-any.whl
Size 33.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
53d35dde667261d154c1fde815e014892ef92fcc07a28450b0917750ca69c5e2
BLAKE2b-256 checksum
How to use checksums
522fcb5e2aecc8a56c5b11eedbd950d2e032b83f44aeaac3ddfaa961808cceb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Security for tickwork-cli 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tickwork_cli-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page