npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

pi-agent-journal

v0.10.0

Published

A journal written by your agent, autonomously. One small markdown file per milestone, written as the work happens, in a format built to be scanned with grep and ls.

Readme

Agent Journal for Pi

Agent Journal is a journal that your agent writes itself: one small markdown file for each milestone, in a format that is easy to read and to search with grep. This package is the extension for Pi. It gives each session the rules for the journal and three tools to read and write it, and syncs the journal with git when you turn sync on.

Note: this page describes only the Pi extension. For the entry format, the configuration, git sync and the CLI, see the main README.

Install

pi install npm:pi-agent-journal

Then open a new session and ask Pi to write a journal entry. By default, it writes to the directory ~/agent-journal/. To use a different directory, see Configuration.

Update

pi update npm:pi-agent-journal

Then restart Pi or run /reload to load the new version.

Tools

The model reads and writes the journal with three tools of the extension:

  • agent_journal_list lists entries by project, date, directory, host, user or agent, searches the summaries and bodies with regex terms, and counts the matches per project, day, host, user or agent.
  • agent_journal_read returns entries in full: the latest, one or more by ID, or all the entries of a day, a month or a year.
  • agent_journal_write adds one entry. The model gives only the summary and the body. The tool sets the date, the project, the directory, the host, the user, the agent and the session.

Only a session with a UI (the terminal UI or RPC mode) gets the tools and the rules. A session in print mode (pi -p) or JSON mode gets neither, so a subagent that runs as a pi process does not write entries.

Permissions

Pi does not ask for approval before a tool call, so there is no permission step. A permission extension can decide from the tools' annotations: agent_journal_list and agent_journal_read are read-only, and agent_journal_write only adds a file and does not reach the network.

Rules

The extension adds the rules for the journal to the system prompt of each run. Pi builds the system prompt again for each run, so the rules stay after a compaction, /new, /resume and /fork.

Git sync

When sync is on (see Git sync for the setup), the extension runs a sync when the session starts, after each entry that agent_journal_write makes, and when the session ends. The sync at the start pulls the entries of your other machines. The sync runs in the background, so the session and the turn do not wait for the network. When a sync fails, the footer shows the reason.

What the extension runs, reads and sends

  • Programs. The extension runs one program, its own scripts/agent-journal. This is a readable POSIX shell script, not a compiled program. The extension finds it in its own package and never runs an agent-journal from your PATH. The script uses standard shell tools (such as awk, grep and ls) and git. For git sync, it runs git add, git commit, git pull --rebase and git push with your own git setup (your SSH key or your credential helper), and never asks for a password.
  • Reads. The extension does not read the conversation. It reads the session ID, the working directory and the model ID from Pi. Through the script, it reads ~/.config/agent-journal/config and the journal folder.
  • Sends. The extension sends no text from the conversation anywhere. The rules go into your own session's system prompt. Entries leave your machine only through git sync, to the remote that you set. Git sync is off until you turn it on.
  • Hooks. The extension watches no tool call and changes no tool result.
  • Tools and commands. The extension registers the three journal tools and no command. A tool gets only the parameters that the model gives it.