Metadata-Version: 2.4
Name: codealmanac
Version: 0.1.2
Summary: A codebase wiki maintained by AI coding agents.
Author: Almanac
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/AlmanacCode/codealmanac
Project-URL: Issues, https://github.com/AlmanacCode/codealmanac/issues
Keywords: agents,codebase,documentation,wiki
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: charset-normalizer>=3.4.7
Requires-Dist: claude-agent-sdk>=0.2.110
Requires-Dist: fastapi>=0.138.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: humanfriendly>=10.0
Requires-Dist: jsonlines>=4.0
Requires-Dist: markdown-it-py>=4.2.0
Requires-Dist: pathspec>=1.1.1
Requires-Dist: pydantic>=2.8
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: python-frontmatter>=1.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=15.0.0
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Dist: uvicorn>=0.49.0
Dynamic: license-file

<p align="center">
  <img src="docs/assets/readme-hero.png" alt="Almanac — A living wiki for your codebase">
</p>

<p align="center">
  <a href="https://pypi.org/project/codealmanac/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/codealmanac?label=pypi&color=2ea043"></a>
  <a href="https://pypi.org/project/codealmanac/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/codealmanac?color=1f6feb"></a>
  <a href="https://github.com/AlmanacCode/codealmanac/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/AlmanacCode/codealmanac?style=flat&logo=github"></a>
  <a href="https://github.com/AlmanacCode/codealmanac/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/AlmanacCode/codealmanac"></a>
  <a href="./LICENSE.md"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-df7b40"></a>
  <a href="https://www.codealmanac.com"><img alt="Website" src="https://img.shields.io/badge/website-codealmanac.com-24292f"></a>
</p>

CodeAlmanac is a self-updating wiki for your codebase.

Your agent sessions die the moment they end. The decisions, architecture, and
dead-ends inside them never compile into anything the next session can
reference. CodeAlmanac is that reference layer: a wiki that lives in your
repository, written for your agents, and kept up to date from the work itself.

## At a glance

- Public command: `codealmanac`
- Python 3.12+
- Default repo wiki root: `almanac/`
- Custom repo wiki roots: any safe repo-relative directory via `--root`
- User state root: `~/.codealmanac/`
- Cloud commands: `setup`, `login`, `whoami`, `logout`, `capture`.

## Get started

Install the CLI (Python 3.12+):

```bash
uv tool install codealmanac
# or: python -m pip install codealmanac
```

**On your machine** — your repo, your agent credentials:

```bash
codealmanac init            # build the first wiki for this repo
codealmanac local setup     # keep it updating from your commits
codealmanac search "getting"
codealmanac show getting-started
```

**With your team (cloud)** — one shared wiki, updated from everyone's
sessions, delivered back to the repo as PRs or commits:

```bash
codealmanac setup           # GitHub sign-in + agent instructions
codealmanac capture enable  # capture Codex/Claude sessions as source
```

Agents can run setup too: `codealmanac setup --no-browser` prints the login
URL for a human to approve, and `codealmanac whoami` confirms the identity.

## What gets created

The wiki is plain markdown committed to your repository, under `almanac/` by
default (`docs/almanac/` or any repo-relative directory via `--root`):

```text
your-repo/
|-- almanac/
|   |-- README.md          # this repo's notability bar and conventions
|   |-- topics.yaml        # topic graph
|   |-- manual/            # packaged guidance copied for agents
|   |-- pages/
|   |   |-- checkout-flow.md
|   |   |-- stripe-webhook-deadlock.md
|   |   `-- jwt-vs-sessions.md
|-- src/
`-- ...
```

Every page is one stable concept — a flow, a decision, a gotcha — linked into
a topic graph with `[[wikilinks]]`. Browse it locally with `codealmanac
serve`, or in the cloud with `codealmanac open`.

A folder counts as a CodeAlmanac wiki only when it has both `topics.yaml` and `pages/`.
Derived local state appears when commands need it: `index.db` and
user-level job records are runtime state, not part of the init scaffold.

## Principles

1. **Written for your agents.** The primary reader is the AI agent working in
   your repo. Pages carry what the code can't say — decisions, invariants,
   gotchas, flows — so the next session starts with context instead of
   archaeology.
2. **It's part of your repository.** Plain markdown, committed next to the
   code, every change reviewable in git. This is
   [docs as code](https://www.writethedocs.org/guide/docs-as-code/): you own
   the wiki, and it travels with every clone.
3. **Maintained, not just generated.** One page per stable concept, a
   notability bar for what deserves a page, edits in place when facts change.
   If a session adds no durable knowledge, the wiki is left unchanged —
   silence is a valid outcome.

## Built for retrieval

The markdown is the source of truth; a derived SQLite index makes it
queryable, so the right context reaches the agent at the right moment:

```bash
codealmanac search --mentions src/checkout/   # every page about these files,
                                              # before the agent edits them
codealmanac search "auth"                     # full-text search over the wiki
codealmanac show checkout-flow                # read one page
```

The instruction files installed by `setup` teach Codex and Claude Code to
query the wiki before touching unfamiliar code. Read commands never invoke a
model and need no credentials.

## Commands

| Command | Purpose |
|---|---|
| `codealmanac init` | Build the first wiki for the current repo. |
| `codealmanac local setup` | Configure local self-updating: branch policy + git hooks. |
| `codealmanac local setup --branch main` | Configure a specific maintained branch locally. |
| `codealmanac local update` | Run a local wiki update now. |
| `codealmanac local update --using codex` | Run a local update with Codex. |
| `codealmanac local triggers enable dev --delivery commit` | Maintain a branch locally. |
| `codealmanac local jobs list` | Inspect local update jobs. |
| `codealmanac search` / `show` / `topics` / `health` | Query the wiki. |
| `codealmanac serve` | Local wiki viewer. |
| `codealmanac setup` | Cloud sign-in plus agent instructions. |
| `codealmanac login` / `whoami` / `logout` | Manage cloud auth. |
| `codealmanac capture status` | Show capture status. |
| `codealmanac capture enable --target codex` | Enable Codex session capture. |
| `codealmanac capture disable` | Disable capture hooks. |
| `codealmanac repo triggers enable <branch> --delivery pr\|commit` | Choose how cloud updates land. |
| `codealmanac runs list\|show\|logs` | Inspect cloud update runs. |
| `codealmanac doctor` | Check install, auth, and wiki health. |

Run `codealmanac <command> --help` for the full flag surface.
Local schedules stay behind explicit local or automation commands.
`codealmanac uninstall --yes` removes setup-owned local artifacts;
`codealmanac uninstall --yes --keep-automation` leaves local scheduled
automation in place.

## Privacy

Capture is opt-in, per provider, and reversible — `capture status` shows
exactly what is on, `capture disable` removes hooks and revokes the stored
credential. CodeAlmanac never stores your Codex or Claude provider
credentials, and wiki content is canonical in your repository: every change
arrives as a commit or PR you can review, amend, or reject.

## Contributing

```bash
git clone https://github.com/AlmanacCode/codealmanac.git
cd codealmanac
uv sync
uv run pytest
uv run ruff check .
```

If CodeAlmanac helps your agents understand a codebase faster, please
consider giving the repo a star.

## Status

CodeAlmanac is pre-1.0 and under active development. Breaking changes are
possible before 1.0 and will be called out in release notes.

## License

Apache License 2.0. See [LICENSE.md](./LICENSE.md).
