This release is a pre-release and may not be stable for production use.
inkd
inkd is a contract-driven skill runner for a local vault. You bring your own skills; inkd discovers, schedules, executes, and tracks them.
What It Does
- Discovers skills from
<skills_dir>/*/SKILL.md. - Loads optional per-skill contracts from
<skills_dir>/*/contract.json. - Runs skills manually (
inkd run) or on triggers (inkd tick). - Supports dependency and follow-up chains (
depends_on,followed_by). - Stores run history, prompt snapshots, and agent logs.
- Exposes observability commands (
log,runs,stats,doctor).
Requirements
- Python
>=3.10 - Anthropic Agent SDK credentials/environment (for skill execution)
- Optional:
claudeCLI inPATHforinkd chat
Install
pip install -e .
Quick Start
# 1) First-run setup (writes config.json)
inkd config
# 2) Inspect discovered skills
inkd skills list --verbose
# 3) Run one skill now
inkd run weekly-review --reason "manual run"
# 4) Evaluate scheduled triggers once
inkd tick
# 5) Inspect recent activity
inkd log --limit 20
inkd stats --days 14
Skill Layout
skills/
weekly-review/
SKILL.md
contract.json # optional
Minimal SKILL.md:
---
name: weekly-review
description: Summarize weekly progress and blockers.
---
Write the report to `notes/weekly.md`.
Example contract.json:
{
"version": 1,
"enabled": true,
"risk_level": "medium",
"triggers": [
{ "type": "cron", "expr": "0 9 * * 1", "reason": "weekly schedule" }
],
"depends_on": [{ "skill": "collect-metrics", "max_age_minutes": 120 }],
"followed_by": [{ "skill": "publish-report", "on": "success" }],
"default_payload": { "audience": "team" },
"executor": {
"type": "anthropic_agent_sdk",
"timeout_seconds": 1800,
"options": {}
},
"permissions": {
"mode": "enforcing",
"read": ["notes/**", "data/**"],
"write": ["notes/**"]
},
"context": {}
}
Notes:
executor.typecurrently supportsanthropic_agent_sdk.permissions.modeispermissiveby default;enforcingis default-deny.
Configuration
inkd config writes JSON like:
{
"vault_root": "/absolute/path/to/vault",
"skills_dir": "/absolute/path/to/vault/skills",
"agent_timeout_seconds": 1800,
"agent_options": {
"permission_mode": "acceptEdits"
}
}
Environment variables:
INKD_ROOT: override runtime root (legacy:VAULT_ROOT)INKD_CONFIG_PATH: explicit config file pathINKD_SKILLS_DIR: explicit skills directory (absolute or relative to root)INKD_DATA_DIR: override runtime data directory
Runtime root resolution order:
INKD_ROOT(orVAULT_ROOT)vault_rootfrom<cwd>/config.jsonvault_rootfrom user config- nearest parent with
skills/orconfig.json - current working directory
User config default path:
- macOS:
~/Library/Application Support/inkd/config.json - Linux:
$XDG_CONFIG_HOME/inkd/config.jsonor~/.config/inkd/config.json - Windows:
%APPDATA%\\inkd\\config.json
Commands
inkd config
inkd config --show
inkd config --vault-root /path/to/vault --skills-dir /path/to/skills
inkd skills list [--verbose]
inkd skills show <skill>
inkd skills graph
inkd skills enable <skill>
inkd skills disable <skill>
inkd skills new <name>
inkd run <skill> [--reason TEXT] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--dry-run]
inkd tick [--now ISO-8601] [--dry-run]
inkd log [--limit N]
inkd runs show <run_id> [--raw]
inkd runs grep <pattern> [--limit N] [--scan N] [-i]
inkd stats [--days N] [--skill NAME] [--json]
inkd doctor
inkd chat [session]
inkd chat --list
inkd chat --delete <session>
inkd llm catalog [--json]
Runtime Data
Runtime data is stored outside the repo:
- macOS:
~/Library/Application Support/inkd/ - Linux:
$XDG_DATA_HOME/inkd/or~/.local/share/inkd/ - Windows:
%APPDATA%\\inkd\\
Key artifacts:
state/runs.db: run history, trigger state, chat sessionsruns/*-prompt.md: prompt snapshotsruns/*-agent.log: extracted output and raw agent messages
Shell Completion
# zsh
eval "$(_INKD_COMPLETE=zsh_source inkd)"
# bash
eval "$(_INKD_COMPLETE=bash_source inkd)"
# fish
eval (env _INKD_COMPLETE=fish_source inkd)
Scheduling On macOS (launchd)
- Copy
launchd/com.inkd.tick.plistto~/Library/LaunchAgents/com.inkd.tick.plist. - Replace
__INKD_BIN__,__INKD_ROOT__, and__USER__. - Load it:
launchctl unload ~/Library/LaunchAgents/com.inkd.tick.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.inkd.tick.plist
launchctl start com.inkd.tick
Runtime Semantics
Execution guarantees and trigger semantics are documented in docs/harness-semantics.md.
Metadata
Release files for inkd-cli 0.1.1.dev23
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| inkd_cli-0.1.1.dev23.tar.gz | 55.2 kB | Without provenance | Details for inkd_cli-0.1.1.dev23.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| inkd_cli-0.1.1.dev23-py3-none-any.whl | Python 3 | none | any | Details for inkd_cli-0.1.1.dev23-py3-none-any.whl |
Total release size: 106.8 kB
Release files / inkd_cli-0.1.1.dev23.tar.gz
| Download URL | inkd_cli-0.1.1.dev23.tar.gz |
|---|---|
| Size | 55.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f8287effbe1d1d4f95763f2ce0e46c1ce4bc61cea6d6f7a626f2bef9ed5a6345
|
|
BLAKE2b-256 checksum How to use checksums |
feb1ce89df7422bed2e470a5403a2824cdf0e0757ccee3d875b728c71e0c8814
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.11
|
Release files / inkd_cli-0.1.1.dev23-py3-none-any.whl
| Download URL | inkd_cli-0.1.1.dev23-py3-none-any.whl |
|---|---|
| Size | 51.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63c00468ac84421cfbca9f3c92e12c27f2728babc725c755a6cee6314585433d
|
|
BLAKE2b-256 checksum How to use checksums |
53cf4d40ba0f03373688071d3a0c35147956ead0ee46a30d38f15660b5a55468
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.11
|
Security for inkd-cli 0.1.1.dev23
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.