skejj
v0.0.7
Published
Simple schedules
Maintainers
sa2812Readme
skejj
Constraint-based schedule solver -- define tasks, dependencies, and resources; get a timed plan.
$ npx skejj make examples/roast-chicken.yaml
Roast Chicken Dinner
A classic Sunday roast with oven-constrained cooking steps. The oven (capacity …
17:00 17:30 18:00 18:30
─ Mains ────────────────────────────────────────────────────────────────────────
17:00 - Prep chicken 15m
██████████ │ │ │
17:15 - Roast chicken 1h 30m
│ ████████████████████████████████████████████████████████████████
18:45 - Make gravy 10m
│ │ │ │ ███████
18:55 - Plate up 5m
│ │ │ │ ███
─ Sides ────────────────────────────────────────────────────────────────────────
17:00 - Prep potatoes 20m (55m flex)
█████████████ │ │ │
17:00 - Steam vegetables 15m (1h 40m flex)
██████████ │ │ │
18:15 - Roast potatoes 40m (55m flex)
│ │ │ ███████████████████████████
─ Setup ────────────────────────────────────────────────────────────────────────
17:00 - Set table 10m (1h 45m flex)
███████ │ │ │
17:10 - Preheat Oven 5m (10m flex)
│ ███ │ │ │
Total: 2h | Oven: 2/2Quick Start
npx skejj make examples/roast-chicken.yamlNo install needed -- npx downloads and runs skejj directly.
To install globally:
npm install -g skejjThen use skejj instead of npx skejj everywhere.
Start from scratch with the interactive wizard:
skejj newGenerate a schedule from a description using AI:
skejj generate "plan a birthday party for 20 kids"Commands
skejj make <file>
Solve a schedule file and display the timed plan as an ASCII Gantt chart.
Each step is rendered on two lines: a header line (start time, name, duration or flex annotation) and a bar line below. Non-critical steps show flex time in parentheses (e.g. 20m (55m flex)). The summary line shows total time and resource utilization.
| Flag | Default | Description |
| ----------------------------- | -------------- | --------------------------------------------------------------------------------- |
| -o, --output <file> | stdout | Write output to file instead of stdout |
| -q, --quiet | false | Suppress summary stats, show only the schedule |
| -f, --format <type> | -- | Export format: gantt, csv, json (writes a file in addition to ASCII output) |
| --width <cols> | terminal width | Chart width in columns (default: terminal width or 80) |
| -r, --resource <name=value> | -- | Override resource availability (repeatable) |
# Solve and display in the terminal
skejj make examples/roast-chicken.yaml
# Export to CSV alongside ASCII output
skejj make myplan.yaml --format csv
# Write ASCII output to a file, suppress summary
skejj make myplan.yaml --quiet --output schedule.txt
# Export JSON data with a fixed chart width
skejj make myplan.yaml --format json --width 120
# Override a resource capacity
skejj make myplan.yaml --resource oven=2skejj check <file>
Validate a schedule file without solving it. Reports schema errors and constraint warnings.
| Flag | Default | Description |
| ------------- | ------- | ----------------------------------- |
| -q, --quiet | false | Show only errors, suppress warnings |
# Validate and show all errors and warnings
skejj check myplan.yaml
# Show errors only (useful in CI)
skejj check myplan.yaml --quietskejj new
Guided interactive wizard to create a new schedule from scratch. Prompts for schedule name, steps, durations, dependencies, and resources. Requires an interactive terminal (TTY).
skejj newskejj generate <description>
Generate a schedule JSON file from a natural language description using an LLM. Requires an API key configured via skejj config set.
| Flag | Default | Description |
| --------------------- | -------------------------- | -------------------------------------------------------------------------- |
| -o, --output <file> | derived from schedule name | Override output filename |
| -f, --format <type> | -- | Export format in addition to ASCII Gantt: gantt (Mermaid), csv, json |
# Generate and display a birthday party schedule
skejj generate "plan a kids birthday party for 20 children"
# Generate and save to a specific file
skejj generate "weekend trip to Paris" --output paris-trip.yaml
# Generate and export a CSV
skejj generate "home renovation project" --format csvskejj config
Manage LLM provider configuration for the generate command.
Subcommands:
skejj config set <key> <value>
Set a configuration value. Supported keys: provider (e.g. openai, anthropic), apiKey, model.
skejj config show
Display current configuration.
# Set your LLM provider and API key
skejj config set provider openai
skejj config set apiKey sk-...
# Use Anthropic instead
skejj config set provider anthropic
skejj config set apiKey sk-ant-...
# Show current config
skejj config showskejj adjust <file>
Interactively adjust a solved schedule in a re-solve loop. Opens an interactive editor (requires TTY) where you can modify step durations, dependencies, and resources, and see the Gantt chart update live.
skejj adjust examples/roast-chicken.yaml
# Or adjust a schedule you created
skejj adjust myplan.yamlExamples
Roast Chicken Dinner
Demonstrates: equipment resource constraint (Oven, capacity 1 -- chicken and potatoes cannot roast simultaneously), backward scheduling from a target dinner time, and a linear dependency chain (prep -> roast -> gravy -> plate).
$ npx skejj make examples/roast-chicken.yaml
Roast Chicken Dinner
A classic Sunday roast with oven-constrained cooking steps. The oven (capacity …
17:00 17:30 18:00 18:30
─ Mains ────────────────────────────────────────────────────────────────────────
17:00 - Prep chicken 15m
██████████ │ │ │
17:15 - Roast chicken 1h 30m
│ ████████████████████████████████████████████████████████████████
18:45 - Make gravy 10m
│ │ │ │ ███████
18:55 - Plate up 5m
│ │ │ │ ███
─ Sides ────────────────────────────────────────────────────────────────────────
17:00 - Prep potatoes 20m (55m flex)
█████████████ │ │ │
17:00 - Steam vegetables 15m (1h 40m flex)
██████████ │ │ │
18:15 - Roast potatoes 40m (55m flex)
│ │ │ ███████████████████████████
─ Setup ────────────────────────────────────────────────────────────────────────
17:00 - Set table 10m (1h 45m flex)
███████ │ │ │
17:10 - Preheat Oven 5m (10m flex)
│ ███ │ │ │
Total: 2h | Oven: 2/2Kids Birthday Party
Demonstrates: people resource constraint (4 helpers shared across parallel tasks), forward scheduling from a party start time, parallel tracks (food, venue setup, activities), and resource conflict warnings when steps are delayed.
$ npx skejj make examples/birthday-party.yaml
Kids Birthday Party
Planning a kids birthday party with a team of helpers. People resource allocati…
10:00 10:30 11:00 11:30 12:00 12:30 13:00
─ Food ─────────────────────────────────────────────────────────────────────────
10:00 - Bake cake 1h (1h 35m flex)
██████████████████████│ │ │ │ │ │
11:00 - Ice cake 20m (1h 35m flex)
│ │ ███████ │ │ │ │ │
12:55 - Serve cake 15m
│ │ │ │ │ │ █████ │
─ Venue ────────────────────────────────────────────────────────────────────────
10:00 - Buy supplies 1h
██████████████████████│ │ │ │ │ │
11:00 - Decorate venue 45m
│ │ ████████████████ │ │ │ │
11:55 - Blow up balloons 30m (15m flex)
│ │ │ │ ███████████ │ │ │
13:10 - Clean up 30m
│ │ │ │ │ │ │ ███████████
─ Activities ───────────────────────────────────────────────────────────────────
11:45 - Welcome guests 10m
│ │ │ │ ████ │ │ │ │
11:55 - Party games 1h
│ │ │ │ ██████████████████████ │ │
12:25 - Set up games 20m (25m flex)
│ │ │ │ │ ███████ │ │
Total: 3h 40m | Helpers: 4/4
--- Warnings ---
- Step 'Blow up balloons' was delayed beyond its available slack due to resource conflict with 'Helpers'
- Step 'Set up games' was delayed beyond its available slack due to resource conflict with 'Helpers'London Weekend Sightseeing
Demonstrates: ALAP (As Late As Possible) timing for dinner steps, multi-day multi-track scheduling, and a long planning horizon across two days with no resource constraints.
$ npx skejj make examples/london-sightseeing.yaml
London Weekend Sightseeing
A two-day London itinerary covering major landmarks and cultural highlights. Di…
09:00 10:00 11:00 12:00 13:00 14:00 15:00 16:00 17:00 18:00 19:00 20:00
─ Day 1 ────────────────────────────────────────────────────────────────────────
09:00 - Tower of London 2h
█████████████│ │ │ │ │ │ │ │ │ │
11:00 - Borough Market lunch 1h
│ │ ███████│ │ │ │ │ │ │ │ │
12:00 - Thames Southbank walk 45m
│ │ │ █████ │ │ │ │ │ │ │ │
12:45 - Tate Modern 1h 30m
│ │ │ │ ██████████ │ │ │ │ │ │
14:15 - Day 1 dinner 1h
│ │ │ │ │ │ ███████ │ │ │ │ │
─ Day 2 ────────────────────────────────────────────────────────────────────────
15:15 - British Museum 2h 30m
│ │ │ │ │ │ │ ████████████████ │ │ │
17:45 - Covent Garden lunch 45m
│ │ │ │ │ │ │ │ │ █████ │ │
18:30 - Westminster walk 1h
│ │ │ │ │ │ │ │ │ │ ███████ │
19:30 - London Eye 30m
│ │ │ │ │ │ │ │ │ │ │ ███│
20:00 - Day 2 dinner 1h
│ │ │ │ │ │ │ │ │ │ │ ███████
Total: 12hSee Schedule Template Schema Reference for the full field reference, or add a $schema key to your JSON file for editor autocomplete.
Writing Your Own Schedule
Schedules are YAML (or JSON) files. The fastest way to start:
# Interactive wizard -- no schema knowledge required
skejj new
# Or write YAML directly and validate as you go
skejj check myplan.yamlEditor autocomplete: YAML is the recommended format for readability. For JSON Schema validation in editors (VS Code, etc.), use a JSON file with a $schema key -- $schema validation works only with JSON:
{
"$schema": "./docs/schema.json",
"id": "my-schedule",
"name": "My Schedule",
"steps": [
{
"id": "step-1",
"title": "First step",
"durationMins": 30
}
]
}Full field reference: docs/SCHEMA.md
The schema covers: steps, tracks, resources (Equipment, People, Consumable), dependency types (FinishToStart, StartToStart, FinishToFinish, StartToFinish), timing policies (Asap, Alap), and time constraints (forward from startTime, backward from endTime).