@pipeline-studio/local-agent (psa)

Local agent for Pipeline Studio. Runs Claude CLI pipelines on your machine and syncs status, logs, and events with the cloud dashboard in real time.

Architecture

Browser (Dashboard)
    |  HTTP / SSE
Cloud Backend (Railway + PostgreSQL)
    |  poll commands / post events
Local Agent (psa)          <-- this package
    |  spawn + signals
Claude CLI (child process)

The agent polls the cloud for commands (start, stop, pause, resume), spawns Claude CLI as a child process, watches the filesystem for phase reports and human tasks, and streams everything back to the cloud via buffered event posting.

Install

npm install -g @pipeline-studio/local-agent

Usage

# 1. Connect to your cloud instance
psa connect https://your-instance.up.railway.app

# 2. Start the agent daemon
psa start

# 3. Check status
psa status

# 4. Stop the daemon
psa stop

Commands

| Command | Description | |---------|-------------| | psa connect <url> | Authenticate and link this machine to a Pipeline Studio cloud instance | | psa start | Start the agent daemon (background by default) | | psa start -f | Start in foreground mode (useful for debugging) | | psa stop | Stop the running agent daemon | | psa status | Show connection status and agent health | | psa --version | Show installed version |

Publishing a New Version

Step-by-step guide for deploying a new version of psa to npm.

Prerequisites

• Node.js >= 18
• npm account with publish access to the @pipeline-studio scope

Step 1: Login to npm

If this is your first time publishing, or your session expired, authenticate first:

npm login

The CLI will open your browser at https://www.npmjs.com/login. Log in with your npm account, authorize the session, and return to the terminal. Verify it worked:

npm whoami
# should print your npm username

If your account has 2FA enabled, npm will ask for the OTP code during npm publish (step 4).

Step 2: Make your changes

Edit source files inside packages/local-agent/src/. The CLI entry point is src/cli.ts.

Step 3: Bump the version

Edit packages/local-agent/package.json and increment the version field following semver:

0.1.2 -> 0.1.3  (patch: bug fixes)
0.1.3 -> 0.2.0  (minor: new features)
0.2.0 -> 1.0.0  (major: breaking changes)

Step 4: Build and publish

cd /path/to/pipeline-studio/packages/local-agent
npm publish --access public

The prepublishOnly script runs npm run build automatically before publishing, so you don't need to build manually.

If your npm account has 2FA enabled, you'll be prompted for an OTP code from your authenticator app.

Expected output:

> @pipeline-studio/[email protected] prepublishOnly
> npm run build

CLI Building entry: src/cli.ts
ESM Build start
ESM dist/cli.js 26.66 KB
ESM Build success in 39ms
DTS Build start
DTS Build success in 663ms
DTS dist/cli.d.ts 13.00 B

npm notice @pipeline-studio/[email protected]
npm notice Tarball Contents
npm notice   README.md
npm notice   bin/psa.js
npm notice   dist/cli.d.ts
npm notice   dist/cli.js
npm notice   package.json
npm notice + @pipeline-studio/[email protected]

Step 5: Verify publication

npm view @pipeline-studio/local-agent version
# should print the version you just published

Step 6: Update your global install

npm install -g @pipeline-studio/local-agent@latest

Confirm:

psa --version
# should print the new version

Quick Reference (copy-paste)

cd /path/to/pipeline-studio/packages/local-agent
npm publish --access public
npm install -g @pipeline-studio/local-agent@latest
psa --version

Project Structure

packages/local-agent/
  bin/
    psa.js              # Entry point (shebang, imports dist/cli.js)
  src/
    cli.ts              # Commander setup, defines commands
    commands/
      connect.ts        # psa connect — auth + link to cloud
      start.ts          # psa start — daemon + command polling
      stop.ts           # psa stop — kill daemon
      status.ts         # psa status — show health
    client/
      cloud-client.ts   # HTTP client for cloud API
    runner/
      pipeline-runner.ts # Spawn + manage Claude CLI process
  dist/                 # Build output (git-ignored)
  package.json
  tsconfig.json
  .npmignore

License

MIT