prompt-diary 0.1.0

Review user prompts for evidence-backed improvement in AI coding collaboration.

Prompt Diary

Language: English | 简体中文

Prompt Diary prepares bounded workspaces from local assistant session history and generates evidenced prompt diary reports that help users review and improve how they collaborate with AI coding agents.

The tool targets Python 3.10 and newer. The package exposes report and prompt-diary console commands after installation.

Usage

Install Prompt Diary from PyPI as an isolated uv tool:

uv tool install prompt-diary

Then run:

report --help
prompt-diary --help
report prepare --date 2026-05-12 --timezone Asia/Shanghai
report generate --date 2026-05-12 --timezone Asia/Shanghai
report render notion --date 2026-05-12 --timezone Asia/Shanghai

Generation is an artifact-first pipeline with standalone phase commands:

report generate evidence --date 2026-05-12 --timezone Asia/Shanghai --project-key <project> --session-ref S0001
report generate project --date 2026-05-12 --timezone Asia/Shanghai --project-key <project>
report generate daily --date 2026-05-12 --timezone Asia/Shanghai

Once Notion is configured, report render notion can publish an already-generated report as a new row in the Notion database. It resolves the existing workspace, requires daily-report.json, regenerates the deterministic report.notion.json payload beside report.md, and publishes that payload. report generate delegates to the same render path after a successful pipeline: by default it publishes when Notion is configured; pass --no-notion to skip publishing, or --notion to require it (which errors if Notion is not configured). Configure the Notion integration token and target database id once with prompt-diary config init (see Configuration); credentials never pass on the command line. Each run appends a new dated row; re-publishing never edits or deletes existing rows.

Generation drives a three-phase, artifact-first pipeline — evidence extraction, then project synthesis, then daily report synthesis — through the Codex CLI, producing daily-report.json, the rendered report.md, and report.notion.json. It requires the codex CLI to be installed and authenticated; the subcommands above run each phase standalone against an already-prepared workspace.

Prepared workspaces and generated reports are written under a per-user data directory by default (~/.local/share/prompt-diary/ on Linux; the platform equivalent on macOS and Windows), organized by date as <reports-root>/work/<YYYY-MM-DD>/. Override the location with --reports-root <path> on prepare, generate, and render notion, PROMPT_DIARY_HOME, or the stored config (see Configuration); precedence is --reports-root over PROMPT_DIARY_HOME over the stored config over the default data directory. (Earlier versions wrote to ./.reports in the current directory — pass --reports-root .reports to keep using an existing local directory.)

Both prepare and generate show a live progress dashboard when running on a TTY and write append-only log lines when output is piped, redirected, or running in CI. Pass --quiet to either command to suppress the live output and print only the final summary.

Configuration

Run prompt-diary config init once to set up credentials and settings interactively. It prompts for the Notion integration token, an optional data folder, the Notion database id, and an optional reporter name (a free-form label, like git config user.name, written into the 汇报人 column at publish time). Each credential is validated live against the Notion API and saved the moment it passes — the token check reports the authenticated integration and workspace, and the database check reports the connected database's name — so an interrupted run keeps whatever was already verified. Everything is written to a single config file with 0600 permissions. The token is read only from that file or the environment — never passed on the command line, and never printed (config show masks it).

prompt-diary config init   # interactive setup; validates the token and database live
prompt-diary config show   # print the configuration (token masked) and the file location
prompt-diary config path   # print the config file location

The config file lives under the per-user config directory (~/.config/prompt-diary/config.json on Linux; the platform equivalent on macOS and Windows), overridable with PROMPT_DIARY_CONFIG. Each setting is resolved from the first source that provides it: a CLI flag (where one exists), then the environment, then the stored config, then a built-in default (where one exists). So NOTION_API_KEY / NOTION_PAGE_ID and --reports-root / PROMPT_DIARY_HOME still override the stored config (useful in CI). Once Notion is configured — including via those environment variables — a bare report generate publishes by default; pass --no-notion in CI or any pipeline that should not publish.

Development

This project uses uv for Python version, environment, dependency, build, and release workflows.

Read docs/src/product.md before designing new features, changing report content, or modifying the generation pipeline. It defines the tool's purposes and principles that downstream design must satisfy.

For environment setup, build commands, type checking, testing, coverage, linting, and pre-submit checks, including the optional Ubuntu 24.04 devcontainer, see the Development Guide. For codebase architecture and API design, see Architecture.