codealmanac: three launchd jobs, an opt-out telemetry prompt and a boundary made of instructions

Supported today means macOS, while the package classifier says OS Independent

The support statement is one line and it is narrow: macOS with Codex or Claude Code, requiring Python 3.12 or newer. Nothing else is claimed.

The package metadata says something different. The classifier list includes `Operating System :: OS Independent`, and the build section has no platform-specific machinery at all. A Linux or Windows user reading the package index sees an operating-system-neutral classifier and a Python floor of 3.12, which is consistent. The one-sentence support statement in the documentation is where the narrower claim lives.

The reason the automation can only be macOS is concrete rather than a policy choice. Setup installs three local `launchd` jobs, and `launchd` is the macOS scheduler. There is no equivalent described for systemd or for the Windows task scheduler, so the scheduled half of the product is macOS-only while the read commands are not.

Version 0.4.7 is in the project file, and the distribution carries a Development Status of 3, Alpha. Two console entry points are declared, `ca` and `codealmanac`, both pointing at the same module.

The project file says 0.4.7 and the newest release tag is v0.4.4

Three release tags are visible, and all three landed on a single day. v0.4.2 was published at 07:31:43 on 2026-07-11, v0.4.3 at 08:16:38 the same morning, and v0.4.4 at 19:44:00 that evening. Three versions in twelve hours reads as a hotfix sequence rather than a release cadence.

The project file declares 0.4.7, which is three patch versions ahead of the newest tag. So a `pip install codealmanac` resolves to whatever is on the index, and a checkout of the newest tag is not the same code as the checked-out source. If you pin versions, pin the index and be aware that the repository default branch runs ahead of the tags.

The last push to the repository is dated 2026-07-25, two weeks after the last release. Between them there is a `CHANGELOG.md` and a `RELEASE.md`, so the gap between tagged and pushed work is documented rather than invisible.

The install path is a single uv command, which sidesteps the version question by always taking the latest:

uv tool install codealmanac@latest
codealmanac setup

--target and --runner do different things under confusingly similar names

Setup has two flags that look interchangeable and are not. `--target` chooses which global agent instruction files get installed. `--runner` chooses which AI runs the work. Passing one does not imply the other.

codealmanac setup --yes --target codex
codealmanac setup --yes --target claude

codealmanac setup --yes --runner claude

The quick path with `--yes` uses Codex as the AI runner. So `--yes --target claude` installs Claude's instruction files and still leaves Codex doing the work, unless you also pass `--runner claude`. That combination is the one to use when you do not have Codex installed, and the documentation flags it as the alternative but does not tie the two flags together anywhere.

The other setup flags are independent toggles rather than values of one option: `--sync-every 5h` changes how often recent agent conversations are scanned, while `--sync-off`, `--garden-off` and `--no-auto-update` remove the corresponding behaviour entirely. Uninstalling is a single command, `codealmanac uninstall --yes`, described as removing CodeAlmanac-owned local artifacts.

Config set rewrites the TOML and re-registers launchd, and manual edits need config apply

Three scheduled jobs are installed, with defaults fixed at setup time. Sync runs every 5 hours and scans recent Codex and Claude conversations, queueing anything worth keeping for the relevant registered wiki. Garden runs every 24 hours and reviews every registered wiki for stale, duplicated or poorly connected knowledge. Update runs every 24 hours and installs CLI updates when it is safe to do so.

Schedules are changed through one command shape:

codealmanac config set automation.sync.every 5h
codealmanac config set automation.garden.every 24h
codealmanac config set automation.update.every 24h

and disabled or re-enabled with `automation.sync.enabled false` and `automation.sync.enabled true`. The behaviour to know is that `config set` updates the user TOML and immediately makes launchd match, whereas editing the TOML by hand changes nothing until you run `codealmanac config apply`. Two paths, one of which does nothing on its own.

The automation section also stops partway through its last paragraph, after describing that automation creates individual background runs and begins a sentence about inspecting those runs. What follows that point is not written here, so the inspection command for a background run has to come from the manual rather than from this page.

The read side is unaffected by any of it. `codealmanac automation status` shows what is installed, and logs land under `~/.codealmanac/logs/`.

Telemetry is a prompt whose recommended answer is yes, on a posthog dependency

The final setup step asks about anonymous telemetry and recommends Yes, with the stated reason being to see which commands work and where the CLI breaks. That is a recommendation to opt in, presented inside the installer rather than as a default buried in a settings file.

What is sent is bounded and worth reading closely: controlled command and lifecycle outcomes, plus sanitized unhandled crashes, under a random install UUID. What is not sent is enumerated too: code, paths, arguments, queries, prompts, transcripts, repository and run identifiers, locals, and credentials. GeoIP is disabled. The UUID profile has no name or email unless you later log in.

There are four ways to refuse it, and all four are equivalent: choose No during setup, pass `setup --no-telemetry`, set `telemetry.enabled` to `false`, or set `DO_NOT_TRACK=1` at any time, which means the switch works after installation as well as during it.

The dependency list confirms the transport, since `posthog>=7,<8` sits among the runtime requirements rather than in the development group. Anyone with a policy against third-party analytics should treat the opt-out as a first-step decision rather than something to revisit later.

The almanac/ boundary is an instruction and a commit policy, not a sandbox

This is the most important paragraph in the documentation, and it is unusually blunt. Lifecycle agents are described as trusted local coding agents running with the same broad, non-interactive filesystem permissions the tool has historically provided. The consequence is stated directly: the `almanac/` boundary is an instruction and commit policy, not an OS sandbox.

The guidance that follows is to run lifecycle commands only in repositories where you accept that trust model, and to review the resulting Git diff when automatic commits are disabled. So the containment is a review step and a convention about where agents are pointed, not a permission boundary enforced by the operating system.

The work itself runs through a separate public SDK, Yoke, with three explicit agents: build, ingest and garden. The packaged prompt files are described as the complete task instructions, and they direct agents to edit the wiki under `almanac/`. Because the instructions live in packaged prompts rather than in your repository, reviewing them is separate from reviewing your diff.

codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude
codealmanac garden --using codex

One more thing is stated as valid behaviour: no-op. If the material adds no durable wiki knowledge, the wiki is supposed to be left unchanged.

Read commands target the exact current directory, so a subdirectory reads nothing

The read surface is short and shared between agents and humans:

codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac health
codealmanac validate

`--mentions` filters by path prefix, `show` opens a single page, and `topics`, `health` and `validate` cover structure and consistency. Another registered wiki is reachable with `--wiki <name>`.

The targeting rule is the sharp edge. By default, commands target the exact current directory when it is a registered repository root, which means running from a subdirectory does not resolve upward to the repository. A script that changes directory before reading gets nothing rather than the repository wiki.

What can be folded in is broader than file paths. Ingest inputs can be files, directories, Git diffs, commit ranges, GitHub pull requests or issues, URLs, and local agent transcripts. `init`, `ingest` and `garden` create queued runs and start a local worker, followed visually through `codealmanac serve` and the Jobs sidebar, or in the terminal with `codealmanac jobs attach <run-id>`.

The repository maintains its own wiki, with `.almanac.yaml`, an `almanac/` directory, `notes.md`, `implementation-tickets.md` and an `archive/` folder, which is the clearest available example of how the layout is meant to look.

Editorial conclusion

codealmanac fits a team on macOS with Codex or Claude Code that keeps losing the reasoning behind its own code, and the read surface is genuinely small: search, show, topics, health, validate, all against markdown in the repository. Three things to weigh first. The lifecycle agents are trusted local coding agents with broad filesystem permissions, and the documentation is explicit that the wiki directory is an instruction and commit policy rather than a sandbox, so point it only at repositories where you accept that. Telemetry is presented with a recommendation to accept, and the opt-out exists but you have to choose it. And the automation section describes the background runs it creates and then stops mid-sentence, so what those runs write is not something the documentation finishes telling you. Read the diff after a garden run.

Frequently asked questions

Official sources

1. AlmanacCode/codealmanac on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases