Metadata-Version: 2.4
Name: codealmanac
Version: 0.1.0.dev0
Summary: A local 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: 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: ruamel-yaml>=0.19.1
Requires-Dist: uvicorn>=0.49.0
Dynamic: license-file

# CodeAlmanac

CodeAlmanac is a local codebase wiki maintained by AI coding agents.

It keeps durable project knowledge next to the code: decisions, workflows,
invariants, incidents, gotchas, and context from real engineering sessions.
The wiki is markdown in your repository, backed by a local SQLite index for
fast search.

## Current Status

This Python rewrite is usable as a local alpha. It is not the old Node CLI and
it does not require a hosted service.

- Public command: `codealmanac`
- Default repo wiki root: `almanac/`
- Optional repo wiki root: `docs/almanac/`
- User state root: `~/.codealmanac/`
- Runtime: Python 3.12+
- Storage: local markdown plus a derived SQLite index

## Install

From a published package:

```bash
uv tool install codealmanac
```

or:

```bash
python -m pip install codealmanac
```

From this checkout:

```bash
uv sync
uv run codealmanac --help
```

## Quickstart

Inside a repository:

```bash
codealmanac init
codealmanac search "getting"
codealmanac show getting-started
codealmanac serve
```

`init` creates a local wiki scaffold under the configured Almanac root. New
repos default to `almanac/`.

## Daily Read Surface

Agents and humans use the same local read commands:

```bash
codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
```

Use `--wiki <name>` to read another registered local wiki. By default,
commands resolve the nearest repository wiki from the current directory.

## Updating The Wiki

Lifecycle commands can ask a configured local agent harness to edit wiki pages.
They only allow changes under the configured Almanac root.

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

`ingest` folds selected local material into the wiki. Inputs can include files,
directories, Git diffs, commit ranges, GitHub PRs or issues, URLs, and local
agent transcripts.

`garden` improves the existing wiki graph: stale pages, links, topics, weak
leads, duplicate pages, and unsupported claims.

No-op is valid. If the material adds no durable wiki knowledge, the harness
should leave the wiki unchanged.

## Sync And Automation

`sync` scans local Claude and Codex transcript stores, waits for quiet sessions,
and runs ordinary local ingest for eligible transcript ranges.

```bash
codealmanac sync status --from codex
codealmanac sync --from codex --using codex
codealmanac automation install sync --every 5h --quiet 30m
codealmanac automation status
```

Scheduled automation launches foreground `sync` or `garden` commands with
explicit unattended policy. It is local scheduler state, not cloud sync.

## Jobs

Lifecycle runs are recorded under the configured Almanac root:

```bash
codealmanac jobs
codealmanac jobs show <run-id>
codealmanac jobs logs <run-id>
```

Run logs include source-resolution facts, harness events, safety errors, and
terminal status.

## Providers

CodeAlmanac currently supports local Codex and Claude CLI harnesses.

```bash
codex login
claude auth login
codealmanac doctor
```

Read commands do not need provider credentials. Write-capable lifecycle
commands need the selected harness to be available and authenticated.

## What Gets Created By Init

With the default root:

```text
your-repo/
|-- almanac/
|   |-- README.md
|   |-- topics.yaml
|   |-- pages/
|   |-- manual/
|-- src/
`-- ...
```

Markdown pages, `topics.yaml`, and manual files are the wiki source. `init`
also writes `.gitignore` entries for runtime artifacts.

## Runtime State

Derived local state appears when commands need it:

```text
almanac/index.db
almanac/index.db-wal
almanac/index.db-shm
almanac/jobs/
```

Those runtime files are rebuildable local machine state and should stay out of
commits.

## Configuration

User config lives at:

```text
~/.codealmanac/config.toml
```

Project config lives at:

```text
<almanac-root>/config.toml
```

The first supported defaults are:

```toml
[harness]
default = "codex"

[sync]
quiet = "30m"
```

CLI flags still win over config.

## Local Viewer

```bash
codealmanac serve
```

The viewer is read-only. It renders pages, search, topics, backlinks, and
file-reference navigation from local wiki data.

## Public Contract

This rewrite is local-only for now.

- No hosted login/connect/upload commands.
- No public SDK or MCP package.
- No compatibility aliases.
- No hidden cloud write path.
- No second wiki command name.

Hosted integration can be added later around the same repo-owned wiki artifact,
but it is not part of this release surface.
