Summary
Koru cannot start on native Windows because koru/init_host_environment.py imports Python's Unix-only grp module unconditionally.
As a result, the CLI fails during module import before command-line arguments are processed. This blocks commands such as:
koru --doctor --project .
koru --help
koru --version
Environment
OS: Windows 11
Windows version: 10.0.26200.0
Shell: Windows PowerShell 5.1.26100.8875
Python: 3.13.14
Koru: 0.1.391
Installation method: PyPI package installed inside a virtual environment
Filesystem: local NTFS filesystem
Project directory: Git repository on native Windows
Installation
py -3.13 -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
..venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install koru
Installed package information:
Name: koru
Version: 0.1.391
Summary: Closed-loop automation across semcod/* repositories.
Home-page: https://github.com/semcod/koru
Location: C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages
Requires: gillm, pyyaml, rich, tillm
Command
koru --doctor --project .
Actual behavior
The CLI exits immediately with:
Traceback (most recent call last):
File "", line 203, in run_module_as_main
File "", line 88, in run_code
File "C:\Users\Praca\fork\koru-windows-test.venv\Scripts\koru.exe_main.py", line 2, in
from koru.cli import main
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\cli_init.py", line 58, in
_legacy = load_legacy_cli_module()
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\cli_init.py", line 49, in _load_legacy_cli_module
spec.loader.exec_module(module)
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\cli.py", line 11, in
import koru.autonomous as _autonomous
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomous.py", line 31, in
from koru import autonomous_cycle as _autonomous_cycle_module
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomous_cycle.py", line 12, in
from koru.autonomy import cycle as module_impl
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle_init.py", line 3, in
from koru.autonomy.cycle.cycle import *
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle\cycle.py", line 21, in
from koru.autonomy.cycle.cycle_orchestrator import handle_autopilot_phase
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle\cycle_orchestrator.py", line 22, in
from koru.autonomy.operator.operator_plugin import plugin_skip_code
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\operator_init.py", line 17, in
from koru.autonomy.operator.operator_resources import *
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\operator\operator_resources.py", line 15, in
from koru.autonomy.cycle.cycle_gate import apply_agent_lane_environ
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle\cycle_gate.py", line 16, in
from koru.init import resolve_project_agent_lane
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\init.py", line 65, in
from koru.init_host_environment import write_host_environment_bundle
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\init_host_environment.py", line 9, in
import grp
ModuleNotFoundError: No module named 'grp'
Expected behavior
The CLI should start successfully on Windows and allow platform-independent commands such as:
koru --help
koru --version
koru --doctor --project .
If some Koru functionality is not supported on Windows, the CLI should still start and display a clear compatibility message for the unsupported functionality.
Root cause
Python's grp module is available only on Unix-like systems.
It is imported unconditionally in:
koru/init_host_environment.py
Because this module is loaded through the main CLI import chain, all Koru CLI commands are unavailable on Windows.
Suggested fix
Guard the platform-specific import:
try:
import grp
except ImportError:
grp = None
Then protect Unix-specific group handling:
if os.name != "nt" and grp is not None:
# Unix group ownership logic
A cleaner alternative would be to move Unix-specific ownership and host-environment logic into a platform-specific implementation that is imported only on supported systems.
Suggested tests
Add a Windows CI job that verifies at minimum:
python -m koru.cli --help
koru --help
koru --version
koru --doctor --project .
The Windows test suite should also detect unconditional use of other Unix-specific modules and APIs, including:
grp
pwd
fcntl
os.chown
Unix domain sockets
Unix file permission assumptions
Bash-specific commands
Impact
This is a blocking issue for native Windows usage.
It prevents testing Koru integration with:
Codex
Cursor or VS Code agents
PowerShell-based repositories
external *-agent workflows
Windows development environments without WSL
Summary
Koru cannot start on native Windows because koru/init_host_environment.py imports Python's Unix-only grp module unconditionally.
As a result, the CLI fails during module import before command-line arguments are processed. This blocks commands such as:
koru --doctor --project .
koru --help
koru --version
Environment
OS: Windows 11
Windows version: 10.0.26200.0
Shell: Windows PowerShell 5.1.26100.8875
Python: 3.13.14
Koru: 0.1.391
Installation method: PyPI package installed inside a virtual environment
Filesystem: local NTFS filesystem
Project directory: Git repository on native Windows
Installation
py -3.13 -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
..venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install koru
Installed package information:
Name: koru
Version: 0.1.391
Summary: Closed-loop automation across semcod/* repositories.
Home-page: https://github.com/semcod/koru
Location: C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages
Requires: gillm, pyyaml, rich, tillm
Command
koru --doctor --project .
Actual behavior
The CLI exits immediately with:
Traceback (most recent call last):
File "", line 203, in run_module_as_main
File "", line 88, in run_code
File "C:\Users\Praca\fork\koru-windows-test.venv\Scripts\koru.exe_main.py", line 2, in
from koru.cli import main
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\cli_init.py", line 58, in
_legacy = load_legacy_cli_module()
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\cli_init.py", line 49, in _load_legacy_cli_module
spec.loader.exec_module(module)
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\cli.py", line 11, in
import koru.autonomous as _autonomous
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomous.py", line 31, in
from koru import autonomous_cycle as _autonomous_cycle_module
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomous_cycle.py", line 12, in
from koru.autonomy import cycle as module_impl
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle_init.py", line 3, in
from koru.autonomy.cycle.cycle import *
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle\cycle.py", line 21, in
from koru.autonomy.cycle.cycle_orchestrator import handle_autopilot_phase
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle\cycle_orchestrator.py", line 22, in
from koru.autonomy.operator.operator_plugin import plugin_skip_code
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\operator_init.py", line 17, in
from koru.autonomy.operator.operator_resources import *
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\operator\operator_resources.py", line 15, in
from koru.autonomy.cycle.cycle_gate import apply_agent_lane_environ
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\autonomy\cycle\cycle_gate.py", line 16, in
from koru.init import resolve_project_agent_lane
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\init.py", line 65, in
from koru.init_host_environment import write_host_environment_bundle
File "C:\Users\Praca\fork\koru-windows-test.venv\Lib\site-packages\koru\init_host_environment.py", line 9, in
import grp
ModuleNotFoundError: No module named 'grp'
Expected behavior
The CLI should start successfully on Windows and allow platform-independent commands such as:
koru --help
koru --version
koru --doctor --project .
If some Koru functionality is not supported on Windows, the CLI should still start and display a clear compatibility message for the unsupported functionality.
Root cause
Python's grp module is available only on Unix-like systems.
It is imported unconditionally in:
koru/init_host_environment.py
Because this module is loaded through the main CLI import chain, all Koru CLI commands are unavailable on Windows.
Suggested fix
Guard the platform-specific import:
try:
import grp
except ImportError:
grp = None
Then protect Unix-specific group handling:
if os.name != "nt" and grp is not None:
# Unix group ownership logic
A cleaner alternative would be to move Unix-specific ownership and host-environment logic into a platform-specific implementation that is imported only on supported systems.
Suggested tests
Add a Windows CI job that verifies at minimum:
python -m koru.cli --help
koru --help
koru --version
koru --doctor --project .
The Windows test suite should also detect unconditional use of other Unix-specific modules and APIs, including:
grp
pwd
fcntl
os.chown
Unix domain sockets
Unix file permission assumptions
Bash-specific commands
Impact
This is a blocking issue for native Windows usage.
It prevents testing Koru integration with:
Codex
Cursor or VS Code agents
PowerShell-based repositories
external *-agent workflows
Windows development environments without WSL