aven-stellar CLI: Track Work and Submit Sessions

The aven-stellar npm package lets workers track active work time, capture Git statistics, and submit verifiable session reports to Aven.

aven-stellar is the npm package workers run inside a Git repository to track active work time, capture Git statistics, and submit verifiable session reports to Aven. It records what changed during a work period — branch names, commit metadata, and diff statistics — and packages that data into a structured report that stream senders can review and approve on-chain.

Requirements

Before using aven-stellar, make sure you have the following in place:

• Node.js v20 or newer — the CLI uses native async APIs available from Node.js 20
• A Git repository — all session tracking is anchored to Git history and file changes
• An existing Aven payment stream where you are the recipient — create one on the Aven dashboard before starting your first session
• Freighter wallet browser extension — required for the one-time authorization step that connects the CLI to your Stellar address

Installation

You can run aven-stellar without a global install, or install it once and use the shorter aven alias everywhere.

npx (no install)

npx aven-stellar start
npx aven-stellar stop

npm install --global aven-stellar
aven start
aven stop

Typical Workflow

1. Open a terminal inside your Git repository

   Navigate to the root of the project you are being paid to work on. The CLI must be run from within a Git repository.

2. Run `npx aven-stellar start`

   On first use, the CLI prompts for your Aven dashboard URL and stream ID, then opens the dashboard in your browser so you can authorize your Freighter wallet. On subsequent runs in the same repository, it reads the saved configuration and starts immediately.

3. Work normally and make commits

   The CLI spawns a lightweight background watcher that monitors file system activity. Continue coding and committing as you normally would — the watcher tracks active versus idle time automatically.

4. Run `npx aven-stellar stop`

   When your work period ends, run stop to terminate the background watcher, calculate Git change statistics, and display the full session report. Review it, then confirm to submit it to the Aven dashboard.

Local State

The CLI stores all session state in a .aven/ directory at the root of your repository. Do not commit this directory. Add it to your .gitignore:

echo ".aven/" >> .gitignore

The three files the CLI reads and writes are:

File	Purpose
.aven/config.json	Dashboard URL, stream ID, worker address, and auth token — written after the first successful start
.aven/session.json	Active session state — present only while a session is running; deleted after stop
.aven/report.json	Latest generated report — written by stop and overwritten on each run

Configuration File

After the first successful start, the CLI writes .aven/config.json with your dashboard URL, stream ID, and worker address. On every subsequent run in that repository, the CLI reads this file automatically — you do not need to re-enter your settings.

To work on a different stream in the same repository, pass --stream <id> to override the saved stream ID:

npx aven-stellar start --stream 99

The CLI will re-authorize if the new stream ID does not match the saved configuration.

The CLI never asks for or stores your Stellar secret key. Authorization uses a time-limited token obtained via the Aven dashboard when you approve the connection with your Freighter wallet.