How to Manage Local Distillation Jobs with distilly pending

Use the distilly pending subcommand group to list, inspect, cancel, and clean up unfinished distillation jobs stored as JSON manifests in the .distilly/pending/ directory.

The titanwings/distilly repository provides a local job queue for managing distillation workflows before they are finalized. The distilly pending CLI commands—defined in bin/distilly.mjs—allow you to interact with this queue, giving you precise control over which jobs are processed, cancelled, or removed based on age.

Where Pending Jobs Are Stored

When you initiate a distillation, the CLI creates a JSON manifest inside the hidden directory .distilly/pending/ at your project root. According to the logic in tools/skill_writer.py, each manifest file is named by a unique job‑id (generated via uuid4) and tracks:

• family – the distillation type (colleague, relationship, or celebrity)
• sources – file paths, URLs, or chat exports used as input
• params – runtime settings such as model, temperature, and output format
• timestamps – created and last‑updated fields for lifecycle management

These manifests remain in the queue until you explicitly apply or cancel them.

Listing and Inspecting Jobs

Listing All Pending Jobs

The distilly pending list command iterates over .distilly/pending/ and prints a summary table showing the ID, Family, Created date, and current status.

# Display every job waiting to be processed

$ distilly pending list
┌───────────────────────┬─────────────┬─────────────────────┐
│ ID                    │ Family      │ Created             │
├───────────────────────┼─────────────┼─────────────────────┤
│ 9f7d2c4e-a1b3-4d5e-…  │ colleague   │ 2026-08-22 14:03:12 │
│ a12c9b1f-e8f7-44d2-…  │ celebrity   │ 2026-08-23 09:47:05 │
└───────────────────────┴─────────────┴─────────────────────┘

Viewing Job Details

To audit a specific job before committing resources, run distilly pending show <job-id>. This outputs the full JSON manifest so you can verify source locations and parameters.

# Inspect a single pending job

$ distilly pending show 9f7d2c4e-a1b3-4d5e-...
{
  "id": "9f7d2c4e-a1b3-4d5e-...",
  "family": "colleague",
  "sources": ["./data/lark_export.json"],
  "params": {
    "model": "gpt-4o",
    "temperature": 0.2
  },
  "created": "2026-08-22T14:03:12Z",
  "last_updated": "2026-08-22T14:03:12Z"
}

Cancelling and Pruning Jobs

Cancel a Specific Job

If you need to abort a distillation, distilly pending cancel <job-id> removes the manifest from the queue and deletes any temporary working directories created by tools/skill_writer.py.

# Remove a job from the queue

$ distilly pending cancel a12c9b1f-e8f7-44d2-...
✔ Removed pending job a12c9b1f-e8f7-44d2-...

Clean Up Old Jobs

For automated maintenance, the prune subcommand deletes jobs older than a specified threshold. This is useful in CI pipelines to prevent the queue from growing indefinitely.

# Delete jobs older than 7 days

$ distilly pending prune --older-than 7
🗑 Deleted 3 stale pending jobs

Finalizing Pending Jobs

A job leaves the queue when it is applied. Whether triggered manually via distilly apply <job-id> or automatically after a successful run, the CLI performs three steps defined in the core processing logic:

1. Loads the manifest from .distilly/pending/.
2. Executes the appropriate family pipeline (e.g., the six‑dimension celebrity research chain) to generate the Person Profile.
3. Writes the result to the skill/ directory and deletes the JSON manifest from the queue.

Once this completes, the job no longer appears in distilly pending list because the source files have been removed.

# Finalize a pending job and write output to skill/

$ distilly apply 9f7d2c4e-a1b3-4d5e-...
✔ Applied colleague distillation → skill/colleague_9f7d2c4e.md

Summary

• Storage location – Pending jobs live in .distilly/pending/ as JSON manifests tracked by tools/skill_writer.py.
• Inspection – Use distilly pending list for overviews and distilly pending show for detailed manifests.
• Lifecycle management – Cancel individual jobs with cancel or bulk‑remove stale entries with prune --older-than.
• Completion workflow – Running distilly apply moves the output to skill/ and automatically cleans the queue.

Frequently Asked Questions

Where does distilly store pending job manifests?

The CLI writes every unfinished job to the hidden directory .distilly/pending/ at the project root. Each file is a JSON document named by its UUID and contains the family type, source references, runtime parameters, and timestamps required to resume or cancel the task.

How do I stop a distillation job before it runs?

Execute distilly pending cancel <job-id>. This command—handled by the CLI parser in bin/distilly.mjs—deletes the manifest and any scratch data created by the skill writer, ensuring the job never enters the processing pipeline.

What is the difference between cancel and prune?

Cancel targets a single job by its UUID and removes it immediately, regardless of age. Prune scans the entire .distilly/pending/ folder and deletes every job whose created timestamp exceeds the specified day limit, making it ideal for scheduled cleanup in automated environments.

How does a job move from pending to completed?

When you run distilly apply <job-id> or the system auto‑processes the queue, the CLI reads the manifest, runs the relevant family pipeline (colleague, relationship, or celebrity), writes the resulting Person Profile into the skill/ directory, and removes the JSON file from .distilly/pending/. After this step, the job is no longer listed in the pending queue.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}