Windows support (Currently errors with No module named 'termios').

[GOvEy1nw]

Hey, I'd love to use this but currently after installing and trying to run setup it reports:

Traceback (most recent call last): File "<frozen runpy>", line 198, in _run_module_as_main File "<frozen runpy>", line 88, in _run_code File "C:\Users\rais\.local\bin\codealmanac.exe\__main__.py", line 4, in <module> File "C:\Users\rais\pipx\venvs\codealmanac\Lib\site-packages\codealmanac\cli\main.py", line 8, in <module> from codealmanac.cli.dispatch.root import dispatch as dispatch_app File "C:\Users\rais\pipx\venvs\codealmanac\Lib\site-packages\codealmanac\cli\dispatch\root.py", line 4, in <module> from codealmanac.cli.dispatch.admin import dispatch_admin, is_admin_command File "C:\Users\rais\pipx\venvs\codealmanac\Lib\site-packages\codealmanac\cli\dispatch\admin.py", line 8, in <module> from codealmanac.cli.dispatch.setup import dispatch_setup, dispatch_uninstall File "C:\Users\rais\pipx\venvs\codealmanac\Lib\site-packages\codealmanac\cli\dispatch\setup.py", line 9, in <module> from codealmanac.cli.dispatch.setup_tui import ( File "C:\Users\rais\pipx\venvs\codealmanac\Lib\site-packages\codealmanac\cli\dispatch\setup_tui.py", line 23, in <module> from codealmanac.cli.dispatch.setup_wizard.terminal import ( File "C:\Users\rais\pipx\venvs\codealmanac\Lib\site-packages\codealmanac\cli\dispatch\setup_wizard\terminal.py", line 4, in <module> import termios ModuleNotFoundError: No module named 'termios'

Would be great to get this fixed. As far as I can tell, termios isn't available on win apparently.

[kushagrchitkar]

Hey @GOvEy1nw, we don't have Windows support yet (only MacOS). That is why you are facing this issue. Windows support is on the roadmap, and we'll be working towards it (none of the devs have a windows laptop yet lol)

[Hotragn]

Windows 11 here, so I ran the current Python codebase to see where this actually stands. Two things worth recording, since the issue text predates the Python port.

The reported symptom is already fixed on main. cli/dispatch/setup_wizard/terminal.py now guards the import:

try:
    import select
    import termios
    import tty
    _HAVE_TERMIOS = True
except ImportError:
    _HAVE_TERMIOS = False

The CLI starts cleanly for me:

$ codealmanac --version
codealmanac 0.4.7
$ codealmanac --help      # fine

So No module named 'termios' should not reproduce anymore. Worth a quick confirmation from @GOvEy1nw on a current version. The remaining wrinkle is that supports_interactive_setup() returns False on Windows and setup_tui.py then silently falls back to defaults, so a Windows user never sees the wizard and is not told why.

Heads up that the two Windows PRs in the queue can't be merged. #2 and #18 both predate the Python port and target the TypeScript tree — src/commands/automation.ts, src/harness/providers/codex.ts, src/process/exec.ts, test/*.test.ts. Those paths no longer exist, so as far as I can tell no Windows work exists against the Python codebase yet. Both PRs did include a Windows CI job, which is probably the most reusable idea in them.

Current state, measured. uv run pytest on a clean Windows checkout: 13 failed, 550 passed, 1 skipped. The failures group into four causes, not thirteen problems:

1. 5 × launchd — os.getuid() does not exist on Windows. Same root cause as bug: setup --yes crashes on Linux because scheduled automation is macOS/launchd-only #31, details posted there.
2. 2 × test sandbox escape — isolated_home patches $HOME, but ntpath.expanduser reads %USERPROFILE% and ignores $HOME, so the fixture is a no-op here. My run wrote a real registry row into my actual ~/.codealmanac pointing at a pytest temp dir. Opened fix(tests): make isolated_home actually isolate, and apply it to every test #64.
3. 1 × path containment — is_absolute() is not a containment check on Windows (PureWindowsPath("/tmp/x") is not absolute, but C:/repo / "/tmp/x" is C:/tmp/x). This is the existing test_source_runtime_context_rejects_unsafe_ignored_directories[directory0] assertion failing. Opened fix(paths): reject every path anchor in repo-relative guards, not just absolute ones #65.
4. 5 × non-portable fixtures — test_tagging.py writes \r\n through translating text mode so it lands as \r\r\n; test_transcript_discovery.py interpolates a Windows path into a JSON string producing invalid escapes; test_build_workflow.py builds an expected path by string-mixing \ and /. The source under test is correct in all five — frontmatter_rewrite.py in particular is properly byte-level and CRLF-preserving.

I also hit one that is not Windows-specific and affects macOS: iter_page_paths globs rglob("*.md"), which matches case-insensitively on APFS too, then page_id_for_path rejects the suffix exactly — so a single NOTES.MD anywhere under almanac/ makes search/show/health/reindex all fail. Opened #66.

Separately, and outside this repo: almanac-yoke calls shutil.which("codex") and spawns it without shell=True. On Windows codex/claude are npm .cmd shims, which fails with WinError 193. That would still block the product on Windows even after everything above is fixed, so it is probably worth tracking as its own item.

Given the comment above about nobody having a Windows laptop — happy to be the verification box for Windows PRs, and to keep chipping at the list above if that is useful. The three PRs I opened are all verified locally on Windows and each notes what it deliberately left out.

[Hotragn]

Closing the loop on the inventory above, since I have now fixed the four causes and can report the end state rather than just the diagnosis.

I test-merged all five PRs together onto current main and re-ran the suite on Windows:

5 failed, 578 passed, 1 skipped

Down from 13 failed, 550 passed. And the five that remain are exactly one thing:

FAILED tests/test_automation_service.py::test_automation_reconcile_enabled_installs_explicit_task
FAILED tests/test_automation_service.py::test_launchd_adapter_writes_structured_plist
FAILED tests/test_automation_service.py::test_launchd_uninstall_boots_out_loaded_service_without_plist
FAILED tests/test_automation_service.py::test_launchd_uninstall_preserves_plist_on_real_bootout_failure
FAILED tests/test_automation_service.py::test_launchd_uninstall_tolerates_service_not_found

src\codealmanac\integrations\automation\scheduler\launchd.py:147: AttributeError

All five are the os.getuid() call in launchd_target() — i.e. the single root cause tracked in #31, and genuinely macOS-only behaviour rather than portability debt. ruff is clean and ~/.codealmanac is never created.

So the practical position is: the test suite is one root cause away from being runnable on Windows, and that root cause is a macOS-only subsystem that should arguably be skipped off-darwin rather than "fixed". That is the precondition for step 3 of #67 — you cannot add a windows-latest job while 13 tests fail for eight different reasons, but you can once the only reds are five tests that are honestly marked macOS-only.

Merge logistics, so this is not extra work for you: the five PRs touch zero overlapping files and I verified they merge cleanly in any order onto main:

PR	Files
#64	tests/conftest.py
#65	core/paths.py, repositories/roots.py, sources/requests.py, tests/test_core_paths.py
#66	wiki/paths.py, tests/test_wiki_parsing.py
#68	tests/test_tagging.py, test_transcript_discovery.py, test_build_workflow.py
#69	index/schema.py, index/store.py, tests/test_database.py

Three of them now have tracking issues (#70, #71, #72) since I realised I had skipped that step and every other PR here links one.

One thing I cannot do from my side: the workflow runs on all five are sitting in action_required because I am a first-time contributor to this repo, so CI has not actually executed. Everything above is local. If someone approves the runs, Ubuntu should be green on all five — #65 and #66 in particular were written with explicit PureWindowsPath/monkeypatched-glob tests specifically so the Windows-specific behaviour is verifiable on a Linux runner without anyone needing a Windows machine.

No rush on any of it, and happy to split, squash, or drop whichever ones you do not want.