Deterministic WIP enforcement that turns workload pressure into guardrails against overload and thrash.
Named after Talos, the bronze guardian of Crete, this project is built around protection through deterministic guardrails.
Talos is a deterministic enforcement engine for work-in-progress pressure.
The public code in this repository currently includes a small Python scoring core that:
- computes enforcement levels from workload and backlog signals
- persists cycle counters across runs
- stays dependency-light and deterministic
The current Talos Python core has been verified in local development on macOS and in a Linux container.
Linux verification currently means:
- the package installs from source in
python:3.12-slim - the current test suite passes in that container
- the public Python core behaves the same there as it does on macOS
This does not currently claim:
- a Linux service wrapper
- a Linux-specific daemon setup
- an MLX deployment on Linux
- broader distribution testing beyond the containerized Python environment above
The currently observed MLX-oriented service deployment is separate from the core package and is still documented as a macOS-specific setup.
This repository currently ships:
- the Python scoring core in
talos/ - automated tests for scoring and persistence behavior
- GitHub Actions CI for test and coverage runs
- Codecov and CodeRabbit configuration files
- repository documentation
- verified notes about the current MLX-oriented deployment shape
It does not currently ship:
- packaged binaries
- a public MLX monitor implementation
- end-to-end production deployment automation
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .[dev]
pytest --cov=talos --cov-report=term-missing --cov-report=xmltalos score --wip-total 10 --global-max 10 --at-cap alpha --backlog-delta 0 --cycles-at-current-level 2cat > snapshot.json <<'JSON'
{
"wip_total": 8,
"global_max": 10,
"at_cap_projects": ["alpha"],
"backlog_total": 12,
"backlog_delta": 1,
"source": "manual"
}
JSON
talos evaluate --snapshot snapshot.json
talos status
talos explain --snapshot snapshot.jsonfrom talos import TalosSnapshot, evaluate_snapshot, load_state
evaluation = evaluate_snapshot(
TalosSnapshot(
wip_total=8,
global_max=10,
at_cap_projects=["alpha"],
backlog_total=12,
backlog_delta=1,
source="manual",
),
prior_state=load_state(),
)
print(evaluation.to_dict())By default, Talos stores state under ~/.config/talos/:
cycles.jsonfor the cross-cycle statestatus.jsonfor the latest structured evaluationhistory.jsonlfor append-only evaluation historypolicy.jsonfor optional policy overrides
To override those locations, set the corresponding environment variables before running Talos:
export TALOS_CYCLES_FILE=/path/to/talos-cycles.json
export TALOS_STATUS_FILE=/path/to/talos-status.json
export TALOS_HISTORY_FILE=/path/to/talos-history.jsonl
export TALOS_POLICY_FILE=/path/to/talos-policy.jsonA Talos process observed on the maintainer's machine is running as a Python service that watches MLX-related logs and writes JSONL summaries.
See Running with MLX.