CodeAlmanac: An AI-Powered Knowledge Base for Your Codebase

The Core Mission: CodeAlmanac serves as a living wiki designed specifically for AI coding agents. It captures the critical context that code alone cannot express is invisible in the source: architectural decisions, complex logic flows, system invariants, and common pitfalls.

The wiki consists of plain Markdown files stored directly within your repository. This ensures that knowledge is indexed locally and undergoes the same Git-based review process as your actual code.

---

🚀 Getting Started

To get up and running quickly, use the following commands:

• Install the tool:

  uv tool install codealmanac@latest
  

• Configure the environment:

  codealmanac setup
  

  (Refer to the Setup section for detailed configuration options).

Basic Usage

Once configured, navigate to your project directory and run:

cd your-repo
codealmanac init              # Initializes the wiki if it doesn't exist
codealmanac search "query"    # Finds relevant wiki pages
codealmanac show page-name    # Displays a page in the terminal
codealmanac serve             # Launches the local web-based viewer

---

⚙️ Setup & Configuration

The setup command installs global instructions for your AI tools and configures three local launchd jobs on macOS to automate maintenance.

Automation Schedule

The frequency of these tasks can be expressed as $\Delta t$:

Installation Variants

Depending on your preferred AI runner, use these flags:

• Default (Codex): codealmanac setup --yes
• Claude: codealmanac setup --yes --runner claude

Note: The --target flag (e.g., --target codex) only specifies which instruction files to install, not the active AI runner.

Customizing Automation

You can modify the default behavior during setup:

• codealmanac setup --yes --sync-every 5h $\rightarrow$ Adjust sync frequency.
• codealmanac setup --yes --sync-off $\rightarrow$ Disable transcript syncing.
• codealmanac setup --yes --garden-off $\rightarrow$ Disable automatic cleanup.
• codealmanac setup --yes --no-auto-update $\rightarrow$ Disable CLI auto-updates.

To remove all local artifacts: codealmanac uninstall --yes.

---

🛡️ Privacy & Telemetry

CodeAlmanac requests anonymous telemetry to improve the CLI. This is handled via a random install UUID.

What is sent:

• Lifecycle outcomes and command success/failure.
• Sanitized crash reports.

What is $\textit{never}$ sent:

• Code, Paths, Arguments, Queries, Prompts, Transcripts, Credentials, or GeoIP data.

How to opt-out:

1. Select No during interactive setup.
2. Use setup --no-telemetry.
3. Set telemetry.enabled = false in config.
4. Set the environment variable DO_NOT_TRACK=1.

---

📖 Reading the Wiki

Both humans and AI agents utilize the same set of read commands:

• codealmanac search "term": General keyword search.
• codealmanac search --mentions path/to/file: Search for mentions of specific files.
• codealmanac show page-name: Read a specific entry.
• codealmanac topics: List high-level categories.
• codealmanac health / codealmanac validate: Check wiki integrity.

Tip: Use the --wiki [name] flag to access a different registered local wiki.

---

🛠️ Updating the Wiki (Lifecycle)

The wiki is maintained by three specialized agents—Build, Ingest, and Garden—powered by the Yoke SDK.

Key Lifecycle Commands

• codealmanac ingest [source] --using [runner]: Integrates new data.
  • Supported Sources: Local files/directories, Git diffs, commit ranges, GitHub PRs/Issues, URLs, and AI transcripts.
• codealmanac garden --using [runner]: Optimizes the wiki by removing duplicates, fixing weak links, and updating stale claims.

Trust & Security

The agents operate with broad filesystem permissions to function effectively. The almanac/ directory is a policy boundary, not a security sandbox.

Warning: Only run lifecycle commands in repositories where you trust the AI agent's access. If automatic commits are disabled, always review the Git diff before merging.

To monitor these processes visually, use codealmanac serve.