Skip to main content
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.

​
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:
The three files the CLI reads and writes are:

​
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:
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.