proj-track

2.0.1 verified Sat Apr 25 auth: no javascript

Auto-capture CLI command history per-project with zero terminal interference. v2.0.1 — active development. Installs as global CLI tool via npm. Per-project isolation via .proj-track.json, smart filtering of noise/sensitive commands, instant replay by ID. Works with Bash and Zsh using PROMPT_COMMAND/preexec — no DEBUG trap footguns. Ships TypeScript types, requires Node >=18. Lightweight alternative to atuin, bashhub, or manual tracking.

Common errors

error Error: Cannot find module 'proj-track' ↓

cause Package not installed or globally installed but not in PATH.

fix

Run npm install -g proj-track and ensure npm global bin directory is in PATH.

error bash: proj-track: command not found ↓

cause Shell not reloaded after install or npm global bin not in PATH.

fix

Run source ~/.bashrc or source ~/.zshrc after install; add npm global bin to PATH if needed.

error TypeError: projTrack is not a function ↓

cause Using default import with old CommonJS require or wrong import style.

fix

Use import projTrack from 'proj-track' (ESM only) or const projTrack = await import('proj-track').

Warnings

gotcha Global install via npm install -g required; local install won't activate shell hooks. ↓

fix Use `npm install -g proj-track` and re-run `proj-track init` in each project.

gotcha .proj-track.json file must be committed or gitignored carefully; contains all commands including sensitive ones filtered by default. ↓

fix Add `.proj-track.json` to `.gitignore` if sensitive commands are a concern, or rely on smart filtering.

gotcha Shell reload (source ~/.bashrc or ~/.zshrc) required after init; otherwise hooks won't fire. ↓

fix Run `source ~/.bashrc` (or `source ~/.zshrc`) after `proj-track init`.

breaking v2.0.0 migrated to ESM-only; CommonJS require() breaks. ↓

fix Use `import` syntax or dynamic import: `const projTrack = await import('proj-track')`.

gotcha Smart filtering may miss environment variable assignments or inline scripts; sensitive data may still be logged. ↓

fix Prefix sensitive commands with a space (shell history ignore) or use explicit `# notrack` comment.

Install

npm install proj-track

yarn add proj-track

pnpm add proj-track

Imports

default

wrong

const projTrack = require('proj-track')

correct

import projTrack from 'proj-track'

ESM-only since v2; no CommonJS module available.

trackCommand

wrong

import trackCommand from 'proj-track/trackCommand'

correct

import { trackCommand } from 'proj-track'

Named export for programmatic command tracking; avoid subpath imports.

initialize

wrong

const initialize = require('proj-track').initialize

correct

import { initialize } from 'proj-track'

initialize is available as named export from main package.

Quickstart

Install globally, initialize in project, reload shell, auto-capture commands, list history, re-run by ID.

cd ~/your-project
npm install -g proj-track
proj-track init
echo 'source ~/.bashrc' >> ~/.bashrc
source ~/.bashrc
ls
docker-compose up --build
proj-track list
proj-track run 1