Development Workflow

Prerequisites

Node.js ~20.19.0 — required for development due to an upstream dependency. Use nvm to manage versions.
Git
Rust toolchain (optional — only needed for beads_rust task tracker)

Setup


git clone https://github.com/protoLabsAI/protoCLI.git
cd protoCLI
npm install

Build


npm run build        # build all packages
npm run ship         # build + link globally as `proto`
npm run dev          # run from source (no build needed)

Run


proto                # interactive CLI (after npm run ship)
npm start            # run from source
proto -p "..."       # one-shot mode

Test


npm run test         # unit tests (Vitest)
npm run test:e2e     # integration tests

Integration tests

Integration tests live in integration-tests/. They require proto to be built and available in PATH:


npm run ship
npm run test:e2e

Code quality


npm run preflight    # lint + format + build + test (run before every PR)
npm run lint         # ESLint
npm run format       # Prettier
npm run typecheck    # TypeScript type check

Package structure

Package	Description
`packages/cli`	Terminal UI, command parsing, user interaction
`packages/core`	Backend: API client, tools, agents, memory
`packages/sdk-typescript`	TypeScript SDK (`@protolabsai/sdk`)
`packages/test-utils`	Shared test utilities
`packages/vscode-ide-companion`	VS Code extension
`packages/webui`	Web UI components
`packages/zed-extension`	Zed editor extension

Release process

Releases are managed via GitHub Actions (.github/workflows/release.yml).

Type	Schedule
Nightly	Every day at midnight UTC
Preview	Every Tuesday at 23:59 UTC
Stable	Manual — triggered by maintainers

To trigger a manual release:

Go to Actions → Release.
Click Run workflow.
Enter the version (v0.x.y), ref (main), and dry-run flag.

Install release types


npm install -g proto              # latest stable
npm install -g proto@preview      # preview
npm install -g proto@nightly      # nightly
npm install -g proto@0.5.0        # specific version

Deployment notes

See docs/developers/development/deployment.md (in the old tree, migrated content) for Docker image and CI/CD setup details.

Issue automation

PRs and issues use GitHub Actions for labelling and triage. Configuration is in .github/. See docs/developers/development/issue-and-pr-automation.md in the old tree for details.