Metadata-Version: 2.4
Name: codealmanac
Version: 0.3.1
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: 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

# 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`
- Repo wiki root: `almanac/` only
- Alternate repo wiki roots: none
- User state root: `~/.codealmanac/`
- Runtime: Python 3.12+
- Storage: local markdown plus derived state under `~/.codealmanac/`

## 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
```

## Setup

Install global agent instructions for the local tools you use:

```bash
codealmanac setup --yes
codealmanac setup --yes --target codex
codealmanac setup --yes --target claude
```

Plain setup installs local agent instructions plus the default local automation:
sync, Garden, and daily package update. It does not connect to a hosted service.

```bash
codealmanac setup --yes --sync-every 5h
codealmanac setup --yes --sync-off
codealmanac setup --yes --garden-off
codealmanac setup --yes --no-auto-update
```

During interactive onboarding, setup asks whether to keep CodeAlmanac up to
date automatically. `--yes` chooses the default happy path and enables it.

To uninstall CodeAlmanac-owned local artifacts:

```bash
codealmanac uninstall --yes
```

## Quickstart

Inside a repository:

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

`init` creates a local wiki scaffold under `almanac/`. CodeAlmanac does not
support alternate repo wiki roots.

## 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
codealmanac validate
```

Use `--wiki <name>` to read another registered local wiki. By default,
commands target the exact current directory when it is a registered repository
root.

## Updating The Wiki

Lifecycle commands can ask a configured local agent harness to edit wiki pages.
They only allow source edits under `almanac/`.

```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.

`ingest` and `garden` create queued runs and start a local worker. Use
`codealmanac jobs` and `codealmanac jobs attach <run-id>` to follow them.

## Sync And Automation

`sync` scans local Claude and Codex transcript stores, finds conversations active
since the last completed sync, and queues ordinary local ingest runs.

```bash
codealmanac sync status --from codex
codealmanac sync --from codex --using codex
codealmanac automation install sync --every 5h
codealmanac automation install update --every 24h
codealmanac automation status
```

Scheduled automation launches local `sync`, `garden`, or `update` commands with
explicit unattended policy. It is local scheduler state, not cloud sync.
Scheduler logs live under `~/.codealmanac/logs/`.

## Jobs

Lifecycle runs are recorded under `~/.codealmanac/`:

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

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

## Providers

CodeAlmanac currently supports local Codex app-server and Claude Agent SDK
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
|   |-- architecture/
|   |   |-- README.md
|   |   `-- indexer.md
|   |-- decisions/
|   |   `-- local-first.md
|   `-- guides/
|       `-- setup.md
|-- src/
`-- ...
```

Markdown pages live directly under `almanac/` in meaningful folders.
`topics.yaml` organizes pages across folders. `README.md` files act as landing
pages for their folder routes.

For auto-detection, a repository counts as a CodeAlmanac wiki when
`almanac/topics.yaml` and `almanac/README.md` exist.

## Runtime State

Derived local state lives under `~/.codealmanac/`:

```text
~/.codealmanac/codealmanac.db
~/.codealmanac/repos/<repo-id>/index.db
```

The local database records repositories, runs, run events, worker locks, and
sync state. Per-repository runtime files contain derived indexes. They do not
belong in the committed `almanac/` tree.

## Configuration

User config lives at:

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

Project config lives at:

```text
almanac/config.toml
```

The first supported defaults are:

```toml
auto_commit = true

[harness]
default = "codex"
```

CLI flags still win over config.

`auto_commit` means lifecycle prompts may tell the selected agent to use normal
Git commands for wiki source changes. CodeAlmanac does not stage files, split
diffs, or commit internally.

```bash
codealmanac setup --no-auto-commit
codealmanac config set auto_commit false
codealmanac config set auto_commit true
```

## Local Viewer

```bash
codealmanac serve
```

The viewer is read-only. It renders pages, search, topics, backlinks, and
file-reference navigation from local wiki data. By default it can switch across
available registered local wikis. Use `codealmanac serve --wiki <name>` to
narrow the viewer to one wiki.

## 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 alternate wiki roots.
- 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.
