Development Setup

Development Setup

Prerequisites

  • Node.js ≥ 20 (node --version)
  • npm (comes with Node.js)
  • git
  • Claude Code installed and authenticated (for integration testing)

Clone and Install

git clone https://github.com/lespaceman/athena-flow-cli.git
cd athena-flow-cli
npm install

Build

Compile TypeScript to the dist/ directory:

npm run build

Watch Mode

For active development, run the watcher. It rebuilds automatically on file changes:

npm run dev

Run Locally

After building, link the package globally so athena resolves to your local build:

npm link
athena --version

Type Checking

npm run typecheck

Runs tsc --noEmit. Run this before submitting a PR.

Tests

npm test

Runs the full Vitest suite. Watch mode during development:

npm run test:watch

For a specific test file:

npx vitest run src/path/to/file.test.ts

Linting & Formatting

npm run lint        # prettier --check + eslint
npm run format      # prettier --write

Dead Code Check

npm run lint:dead

Runs Knip to detect unused exports, files, and dependencies. Run occasionally to keep the codebase clean.

Performance Profiling

npm run perf:tui -- -- --sessions   # Full: CPU + trace + app instrumentation
npm run perf:cpu -- -- --sessions   # CPU profile only
npm run perf:trace -- -- --sessions # Node trace events only
npm run perf:heap -- -- --sessions  # Heap profiling only

See Performance Profiling for details.

Environment Notes

  • .nvmrc pins the Node.js version. Run nvm use to switch to it if you use nvm.
  • .editorconfig and .prettierignore configure editor and formatter behavior.
  • The .claude/ directory contains Claude Code project instructions for AI-assisted development on the repo itself.
  • Set ATHENA_DEBUG=1 to enable debug logging from the hook registration and socket server.