Documentation

Status: Active development. Developer: David Cody (Hivemind Studio).

Introduction

Chronos Engine is a YAML‑first life management engine with a scriptable CLI, a background listener (alarms, reminders, timer), and a lightweight dashboard. Build your day from templates, adapt to your status, and automate with simple scripts.

Core Concepts

• Items: Atomic units like task, note, goal, routine, and more. Stored as YAML.
• Fractal Structure: Templates nest logically (week > day > routine > subroutine > microroutine).
• User Status: Variables like emotion, energy, and focus guide the scheduler.
• Templates: Reusable blueprints for days, weeks, and routines.
• Reminders: Time-based notifications handled by the Listener module.

Today Scheduler

The today command is the daily driver.

• today: Loads and displays the persisted schedule for today.
• today reschedule: Regenerates today's schedule, applies manual edits, resolves conflicts (shift/trim/cut), and saves the result.

AI Agents and NLP Interface

Chronos supports an AI-assisted workflow where a helper agent translates natural language into Chronos CLI commands.

• NLP interface: Speak intentions (e.g., “add a task to my morning routine”), the agent emits precise commands (new task ..., add ... to ...).
• Status-aware suggestions: When overloaded, the agent can suggest today reschedule or adjust buffers via status.
• Developer agents: Agents can read modules, propose edits, and automate maintenance. See agents.dev.md.
• Agent guide: See agents.md for the Chronos Warp Drive AI persona and best practices.

Examples the agent can translate:

"Create a weekly review routine and add it to Sunday"
-> new routine "Weekly Review"
-> add "Weekly Review" to "Sunday"

"I'm low energy, lighten my afternoon tasks"
-> status energy:low
-> today reschedule

"Track a new goal and a first milestone"
-> new goal "Ship MVP" priority:high
-> new milestone "Beta Ready" goal:"Ship MVP"

Status

Set your status to inform scheduling decisions. Example: status energy:high focus:good. Chronos can widen buffers, reduce high-energy tasks, or prioritize critical items based on these values.

Data Model

Everything is YAML. Items live in the User/ directory. Templates reference sub-items to form a navigable graph (e.g., a Day template references Routine items, which reference Subroutines, and so on).

Dashboard

Open the Dashboard for a quick, visual overview of time, notes, status, and today's schedule. The new Settings widget lets you edit User/Settings/*.yml directly with YAML validation.

Guides

• Architecture — how Chronos fits together and how to extend it
• Dashboard Guide — views, widgets, and API endpoints
• Settings Guide — file conventions and editing via the Settings widget
• Common Workflows — practical recipes for users and agents
• CHS Scripting — scripts, variables, and control flow
• Conditions Cookbook — examples for if logic

Themes & Console

Chronos supports console themes via theme command and User/Settings/theme_settings.yml presets. User/profile.yml can set theme and explicit background/ overrides. On Windows, colors apply via the color command.

theme list
theme current
theme set hacker
theme set-colors background:#002b36 text:#93a1a1

Welcome Message

Customize the console's welcome banner via User/profile.yml. Define a welcome (or welcome_message) block with line1/line2/line3. Variables like @nickname are expanded.

nickname: "Pilot"
welcome:
  line1: "⌛ Chronos Engine v1"
  line2: "🚀 Welcome, @nickname"
  line3: "🌌 You are the navigator of your reality."

Commitments, Achievements, Rewards

Commitments encode behavioral rules and fire triggers when conditions are met.

• Frequency: frequency: { times: N, period: day|week|month } with associated_items.
• Never: never: true with forbidden_items (fires on incident).
• Triggers: on_met / on_violation can create achievement/reward items or run .chs scripts.

# Example: Exercise twice a week
name: Exercise Twice Weekly
type: commitment
frequency: { times: 2, period: week }
associated_items:
  - { type: habit, name: Exercise }
triggers:
  on_met:
    - { type: achievement, name: Exercise streak! }

# Example: Never smoke
name: Never Smoke
type: commitment
never: true
forbidden_items:
  - { type: habit, name: Smoke }
triggers:
  on_violation:
    - { type: reward, name: Reflection Needed }

Habits: Good vs Bad

Habits support polarity: good|bad. Good habits track positive streaks; bad habits record incident_dates and compute clean streaks (days without incidents). The track command shows appropriate summaries.

Export & Import

Two modes:

• Full backup: export all [filename.zip] zips the entire User/ directory into User/Exports/.
• Table export: export my_tasks.yml list tasks status:pending saves a table as YAML.

Restore with import:

• Zip: import User/Exports/backup.zip overwrite:true extracts into User/.
• YAML list: import User/Exports/items.yml creates items (skips existing).

Scripting & Variables

Chronos supports simple .chs scripts and session variables:

• Variables: set var name:World, then use @name or @{name} in any command; escape with @@.
• Properties: key:value tokens (e.g., priority:high) are parsed into command properties.
• Conditionals: Single-line if ... then ... [else ...] and block form in scripts with operators = != > < >= <= eq ne gt lt ge le matches and logic and or xor nor not !. Parentheses supported.
• Existence checks: exists <type>[:<name>[:<property>]], exists file:<path>, exists dir:<path>, exists env:<NAME>.

See more detailed guides:

• CHS Scripting Guide
• Conditions Cookbook

Philosophy

Chronos favors clarity, portability, and automation: human-readable files, smart scheduling, and a concise CLI. Keep your system simple; iterate with templates; trust the engine's context to fill in gaps.

Open Source & Extensibility

Chronos Engine is open-source on GitHub. Everything is plain Python and YAML, so you can extend it in many ways:

• CLI wrappers: Call the CLI behind the scenes from your app or script. Drive Chronos without exposing commands to end-users.
• Plug-in commands: Drop new Python files into Commands/ or new item modules into Modules/ to add functionality.
• Dashboard widgets/views: Add UI blocks that read YAML and present custom visualizations.
• YAML-first data: Build visualizers, dashboards, or games by reading the item graph directly.

Examples:

# 1) Wrap the CLI from Python (Windows)
import subprocess
subprocess.run([r"Console_Launcher.bat", "new", "task", "Write README", "priority:high"]) 

# 2) Minimal custom command (Commands/hello.py)
def run(args, props):
    name = args[0] if args else "world"
    print(f"Hello, {name} from Chronos!")

# 3) New item type (Modules/Widget/main.py)
ITEM_TYPE = "widget"
def handle_new(name, props):
    # Use ItemManager utilities to persist YAML
    pass