AppLedger The application, written down.

Text record and CLI for application context

Keep the decisions your next session will need.

Text record and CLI for application context

Keep the decisions your next session will need.

When a new agent session loses the reasons behind your code, AppLedger gives it a record to read. Keep purpose, decisions, structure, and evidence in portable files beside the application.

Create a first ledgerSee a small example

The ledger needs curation. Records can be incomplete, disputed, or stale.

Illustrative example

Starting point
A fresh session asks why the app has no database.

What you get
Decision: use local files for the initial scope. Rationale: a small offline tool. Rejected alternative: a hosted database.

The next session can read the reason before reopening the decision.

Synthetic example from the minimal ledger.

One system, three parts

ForgeTrail guides the work through phases with approval gates, and keeps that record in AppLedger, in appledger/. xFacts labels describe what was built and keep their own schemas. AppLedger and those labels can be used without ForgeTrail.

Phases, decisions, and the session handoff are on ForgeTrail.

The normative specification is the spec/ directory in the repository. The checker is appledger on npm. Start a ledger in an app folder with pnpm dlx appledger init --name "Your app name", then pnpm dlx appledger check.

A small example

The synthetic minimal ledger has a decision record with these fields (excerpt, not a complete record):

id: decision-local-files
kind: decision
title: Keep notes in local files
data:
  status: accepted
  choice: Use local files for initial scope
  rationale: The synthetic brief calls for a small offline tool
  alternatives:
    - Hosted database
  authority: Synthetic scenario owner

In your app folder, pnpm dlx appledger orient prints an orientation from the ledger. A later agent can then read the linked decision and say: “Local files were chosen for the small offline scope. Before proposing a database, check whether that scope has changed.” That response is illustrative, not a generated guarantee.

The record preserves the choice and its reason across sessions. It declares the owner's intent; it does not prove how storage was implemented. init does not create this decision for you: you or your agent curate it.

In the docs