y

y answers "why".

Overview

y is a tool for preserving agent intent, decisions, and tribal knowledge accumulated while using coding agents, all in your existing git repository, no out-of-band databases!

y currently supports automated tracking of sanitized Codex session logs, session summaries, and "vibe provenance" while using Codex CLI and/or the Codex desktop app.

Quick Start

# install y
cargo install --git https://github.com/eqtylab/y y

# setup y (in your git repo)
y init

# after running `y init`, vibe provenance will now be logged as git notes in your repo

# to view notes for last 10 commits
y notes list --last 10

# to open interactive GUI to view insights for a specific commit
y notes ui --commit <commit_hash>

Repo layout

• y/: core CLI
• y-schema/: SummaryRoot schema + validation
• y-skills/: Codex skills for session log and summary generation
• y-ui/: summary viewer app scaffold

Justfile

Available recipes:
    ci            # Primary CI entry point.
    readme-check  # Render README and fail if checked-in content is stale.
    readme-update # Regenerate README content in place from present blocks.

CLI Usage

y CLI

Usage: y <COMMAND>

Commands:
  init      Initialize y in the current repository
  commit    Print summary note content for a commit
  notes     Manage notes attached to commits
  validate  Validate artifacts against y-schema
  summary   Check running summary processes
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

y init

Initialize y in the current repository

Usage: y init

Options:
  -h, --help  Print help

y commit

Print summary note content for a commit

Usage: y commit [commit_hash]

Arguments:
  [commit_hash]  Commit hash to print note content for (defaults to HEAD)

Options:
  -h, --help  Print help

y notes add

Add a new note to a commit

Usage: y notes add [OPTIONS]

Options:
      --commit <commit_hash>   The commit hash to which the note will be attached (defaults to HEAD)
      --namespace <namespace>  If set, only execute the provider that matches this namespace
  -h, --help                   Print help

y notes list

List notes for a commit (all namespaces)

Usage: y notes list [OPTIONS]

Options:
      --commit <COMMIT>  List notes for a specified commit hash
      --last <n>         List notes for the last <n> commit hashes
  -h, --help             Print help

y notes ui

Open the UI summary viewer for a commit

Usage: y notes ui [OPTIONS]

Options:
      --commit <commit_hash>  Commit hash to open (defaults to HEAD)
      --port <PORT>           Port for the UI server [default: 4010]
      --demo                  Use demo data instead of git notes
  -h, --help                  Print help

y validate summary

Validate a SummaryRoot JSON file

Usage: y validate summary <path>

Arguments:
  <path>  Path to summary JSON

Options:
  -h, --help  Print help

y summary

Check running summary processes

Usage: y summary

Options:
  -h, --help  Print help