---
slug: "pi-chronicle"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/eiei114/pi-chronicle@main/README.md"
repo: "https://github.com/eiei114/pi-chronicle"
source_file: "README.md"
branch: "main"
---
# Pi Chronicle

[![CI](https://github.com/eiei114/pi-chronicle/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-chronicle/actions/workflows/ci.yml)
[![Publish](https://github.com/eiei114/pi-chronicle/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-chronicle/actions/workflows/publish.yml)
[![npm version](https://img.shields.io/npm/v/pi-chronicle.svg)](https://www.npmjs.com/package/pi-chronicle)
[![npm downloads](https://img.shields.io/npm/dm/pi-chronicle.svg)](https://www.npmjs.com/package/pi-chronicle)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>

> Record conscious markers and typed beats during work sessions, then write chronicle markdown to your vault.

## What this is

A Pi extension that captures **intentional session logs** — not automated transcripts. Mark decisions, blockers, milestones, tries, and reverts as you work, then finalize a single chronicle markdown file into your vault's `Progress/` folder.

For developers and creators who want a lightweight record of *why* they did things in that order — raw material for flow docs, blog posts, or retrospectives.

## Features

- **Auto-start** — session begins when Pi loads; no explicit start command
- **6 colon-flat commands** — no arguments, no flags; prompted after invocation
- **5 beat types** — `decision`, `blocker`, `milestone`, `try`, `revert`
- **Project detection** — auto-resolves output folder from current working directory
- **Vault output** — writes `chronicle-YYYYMMDD-HHmm.md` to your project's `Progress/` folder
- **Novel generation** — `/chronicle:novel` generates a short novel from session marks/beats via Pi agent
- **Distill select** — choose a target format (`flow`, `textbook`, `essay`, `fiction`) for future generation

## Install

Install the published npm package with Pi:

```bash
pi install npm:pi-chronicle
```

Pin a specific version when you want reproducible installs:

```bash
pi install npm:pi-chronicle@0.1.2
```

Install into the current project instead of your user Pi settings:

```bash
pi install npm:pi-chronicle -l
```

Or install from GitHub:

```bash
pi install git:github.com/eiei114/pi-chronicle
```

Try it without permanently installing:

```bash
pi -e npm:pi-chronicle
```

## Quick start

Try this package locally from a clone:

```bash
pi -e .
```

Then run:

```txt
/chronicle:mark    → enter a short label
/chronicle:beat    → pick type → enter label
/chronicle:end     → optional closing note → writes chronicle md
/chronicle:status  → show current session
/chronicle:distill → pick output format
/chronicle:novel   → generate novel from session → writes to project root
```

Session auto-starts when Pi loads — just mark and beat as you work.

## Package contents

| Path | Purpose |
|---|---|
| `extensions/` | Pi TypeScript extension entrypoints |
| `lib/` | Shared session and output logic |
| `docs/` | Supporting docs (`examples.md`, `release.md`, `template-checklist.md`) |

## Development

```bash
npm install
npm run ci
npm pack --dry-run
```

`npm run ci` runs typecheck, tests, and `npm run pack:check` (equivalent to `npm pack --dry-run`).

## Release

npm Trusted Publishing — no `NPM_TOKEN` required.

```bash
npm version patch
git push
```

See [`docs/release.md`](https://github.com/eiei114/pi-chronicle/blob/HEAD/docs/release.md) for setup details.

## Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see [`SECURITY.md`](https://github.com/eiei114/pi-chronicle/blob/HEAD/SECURITY.md).

## Links

- npm: https://www.npmjs.com/package/pi-chronicle
- GitHub: https://github.com/eiei114/pi-chronicle
- Issues: https://github.com/eiei114/pi-chronicle/issues

## License

MIT