Chronicle

From every session to a story you can prove.

한국어

---

Chronicle is a local-first project memory plugin for Claude Code, Codex, and Agent Skills-compatible agents. It turns completed agent sessions into project evidence, STAR stories, resume bullets, and interview practice. Its TIL skill remains a lightweight learning lane on the same vault, configuration, and local runtime.

  agent session ends
       │  SessionEnd hook, metadata only
       ↓
  local pending queue
       │  SessionStart, up to 3 sessions
       ↓
  ┌─ Capture ───────────────┐
  │  capture-session        │
  └────────────┬────────────┘
               ↓
  ┌─ Organize ──────────────┐
  │  update-project         │
  └────────────┬────────────┘
               ├──────────────────────┐
               ↓                      ↓
  ┌─ Prove ─────────────────┐   ┌─ Practice ─────┐
  │  audit-career-evidence  │   │  quiz-project  │
  │  craft-star             │   └───────┬────────┘
  │  export-resume          │           ↓
  └────────────┬────────────┘    interview practice
               ↓
        resume sections

At SessionEnd, Chronicle quickly queues session metadata in local state. A session whose transcript holds no agent turn and no tool call — one that only ran slash commands such as /clear — is skipped instead of queued. An absent or unreadable transcript is still queued, since it is not proof of an empty session. At the next SessionStart, Chronicle offers up to three sessions from the same agent for evidence-aware capture. The til skill runs as a separate lane on the same vault.

Features

Skill	Purpose
init	Discover and confirm a vault, save configuration, and initialize local storage.
capture-session	Capture goals, work, decisions, verification, failures, and follow-ups from a completed session.
update-project	Merge session records into a project ledger without hiding conflicts or ownership gaps.
audit-career-evidence	Flag unsupported claims, uncertain metrics, sensitive details, and stale evidence.
craft-star	Create evidence-backed STAR stories, resume bullets, and 30/60-second answers.
export-resume	Export reviewed stories as Korean or English Markdown resume sections.
quiz-project	Practice Why, What, How, alternatives, trade-offs, failures, and ownership.
til	Keep a guided Today I Learned note with related-vault context.

Claude Code invokes skills as /chronicle:<skill>; Codex uses $chronicle:<skill>.

What a record looks like

Every claim carries an evidence grade, and the grade decides how far it travels.

---
type: session
project: acme-billing
status: captured          # automatic records are never marked `reviewed`
---

## Decisions

- [confirmed] Moved retry logic out of the API client into a queue consumer.
  - Why: client-side retries amplified load during the incident.
  - Evidence: `git:4f2a9c1`

- [needs-evidence] Cut p99 checkout latency roughly in half.
  - Evidence: none yet — number quoted from memory

export-resume draws only on [confirmed] claims inside records you have reviewed. The second bullet stays out of your resume until you supply the measurement — which is the point.

Requirements

• Python 3.9 or later — required. Lifecycle hooks and scripts/chronicle.py are invoked as python3. If python3 is not on PATH, the hook may exit with code 127 and no session is queued. Verified on 3.9 and 3.12.
• ripgrep (rg) — optional, recommended. Related-note search uses it when available and falls back to a slower directory walk otherwise.
• git — optional. Used read-only (rev-parse, config --get) to match a session to a registered project.
• A local directory for the vault — an Obsidian vault is typical, but any existing directory works; .obsidian is not required.

Install

Current prerelease: 1.0.0-beta.2.

Claude Code

claude plugin marketplace add r-jelly/chronicle
claude plugin install chronicle@chronicle

Run /reload-plugins in Claude Code after installation or an update. Then run /chronicle:init.

Codex

codex plugin marketplace add r-jelly/chronicle
codex plugin add chronicle@chronicle

Start a new Codex thread after installation. Review and trust lifecycle hooks only after inspecting this repository. Then run $chronicle:init.

Other Agent Skills clients

Clone the repository and add its skills/ directory to the client's skill search path. Skills work from the cloned repository; automatic session capture requires lifecycle-hook support, otherwise run capture-session manually.

Initialize local data

Run the guided skill:

/chronicle:init   # Claude Code
$chronicle:init   # Codex

It checks configured paths, the nearest .obsidian directory, the macOS Obsidian registry, and common locations. It always asks before saving. As a manual fallback, set CHRONICLE_VAULT before launching the agent or persist it from a source checkout:

export CHRONICLE_VAULT="/path/to/your/obsidian-vault"
python3 scripts/chronicle.py init \
  --vault "/path/to/your/obsidian-vault" \
  --save-config

New records live under <vault>/chronicle/; existing TIL notes remain under <vault>/til/. Existing ~/.claude/til-config.json paths can be confirmed and copied into the common Chronicle config without deleting the legacy file.

Local-first data policy

• Markdown in your vault is the source of truth.
• TIL and project skills share the same vault resolver, related-note search, and Markdown records.
• Raw transcripts stay in agent storage. Their paths and the transient queue stay under CHRONICLE_STATE_DIR, separated by computer, vault, and agent.
• New session Markdown stores the source session ID and content hash, not local transcript or working-directory paths.
• Automatic records begin as captured; only user-reviewed records become reviewed.
• Resume output uses reviewed claims or claims with direct evidence.
• Chronicle never commits or pushes personal records automatically.

See the product plan and data model for the full contracts. Release changes are tracked in the changelog.

Contributing

Issues and focused pull requests are welcome. Preserve backward compatibility for til, keep personal data out of fixtures, and add tests for behavior changes.

python3 -m unittest discover -s tests -v

By contributing, you agree that your work is released under the MIT License.