Contributing to Agent CLI Menu

June 5, 2026 · View on GitHub

Thanks for your interest in improving Agent CLI Menu! Contributions of all kinds are welcome — bug reports, feature ideas, docs, and code.

Ground rules

  • main is protected. No direct pushes. All changes land via Pull Request and are reviewed/merged by the maintainer (@roypadina).
  • Be respectful — see the Code of Conduct.
  • Keep changes focused. One logical change per PR.

Getting started

git clone https://github.com/roypadina/AgentCliMenu.git
cd AgentCliMenu
npm install

npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # tsup → dist/

# run from source without building:
npx tsx src/cli/index.ts        # agent-cli-menu (New; -r for Resume)
# build the Mac GUI:
bash gui/build-app.sh && open "gui/Agent CLI Menu.app"

Requirements: Node 18+, macOS 12+ (Swift 5.9 / Xcode 15+ for the GUI).

Architecture

A strict two-layer split — please keep it intact:

  • src/core/ — pure data, zero React/ink imports. New core modules ship with a tests/core/<name>.test.ts.
  • src/cli/ — the ink TUI and the non-interactive subcommands. The only layer that touches presentation. UI in tui.tsx / screens gets smoke tests only; full UX validation is manual in a real terminal.
  • gui/ — a native SwiftUI app that is a thin client over agent-cli-menu gui …. It imports none of the Node code.

See CLAUDE.md for the full module map and conventions.

Conventions

  • ESM only. Import siblings with the .js extension even from .ts (moduleResolution: Bundler).
  • Streaming, never load whole files. Session .jsonl can be MB-scale — use readline + for await.
  • Tiny dependencies. The runtime dep list is intentionally small (chalk, commander, ink, ink-text-input, react, smol-toml). Adding one needs justification.
  • Match the surrounding code style. No force-unwraps in non-test Swift.

Workflow

  1. Fork and branch: git checkout -b feature/my-thing.
  2. Make your change. Add or update tests.
  3. npm test && npm run typecheck && npm run build — everything must pass. (Touching the GUI? swift build in gui/AgentCliMenuBar too.)
  4. Commit with a clear message and open a Pull Request against main.
  5. CI must be green and the maintainer must approve before merge.

Reporting bugs / requesting features

Use the issue templates. For bugs, include your macOS + Node versions and how you launched it (agent-cli-menu / acm / GUI).