Sous CLI

This repo builds and ships the Sous CLI.

It includes:

• a build step that writes dist/cli.js
• PROACTIVE, KAIROS, and COORDINATOR_MODE build features enabled
• a custom sous mode for research-style multi-agent orchestration

Requirements

• Bun installed and available in your shell
• Anthropic-compatible credentials

If Bun is not currently on PATH, make sure your shell setup includes Bun.

Example ~/.zshrc lines:

# bun completions
[ -s "/Users/frank/.bun/_bun" ] && source "/Users/frank/.bun/_bun"

# bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
export PATH="$HOME/.bun/bin:$PATH"

Notes:

• The completions line is safe even if Bun is not installed yet. It only runs if /Users/frank/.bun/_bun exists.
• The PATH lines do not install Bun by themselves. Your colleague still needs Bun installed under ~/.bun or another location on disk.
• If Bun is installed somewhere else, adjust the path accordingly.

Then reload your shell:

source ~/.zshrc

Install from npm

Requirements:

• Node.js 20 or newer
• Anthropic-compatible credentials

Install globally:

npm install -g sous-cli

Run the CLI:

sous

Run with credentials set inline:

ANTHROPIC_API_KEY=... ANTHROPIC_BASE_URL=... sous

Upgrade:

npm install -g sous-cli@latest

Uninstall:

npm uninstall -g sous-cli

Local development setup

cd /path/to/sous_cli
bun install

Build

Build output is written to dist/cli.js.

cd /path/to/sous_cli
bun run build

What the build does:

• bundles src/entrypoints/cli.tsx to dist/cli.raw.js
• prepends build/macro.js
• writes the final runnable CLI to dist/cli.js

So the file you actually run is:

dist/cli.js

Publish to npm

This repo is configured to publish the sous-cli package and expose the sous binary.

Before publishing:

• make sure you are logged into npm with an account that can publish the package
• make sure Bun is installed, because npm publish runs prepublishOnly, which runs bun run build
• if you want to preview the package contents first, run npm pack --dry-run

Recommended publish flow:

cd /path/to/sous_cli
bun install
npm whoami
npm pack --dry-run
npm version patch
npm publish

Notes:

• the package is unscoped, so you do not need --access public
• the published package only includes bin/, dist/cli.js, stubs/, and README.md
• if your npm account requires publish-time 2FA, npm will prompt for the OTP during npm publish

Run The CLI

Basic local run:

cd /path/to/sous_cli
bun run dist/cli.js

With auth:

cd /path/to/sous_cli
ANTHROPIC_API_KEY=... ANTHROPIC_BASE_URL=... bun run dist/cli.js

Run Sous Mode

sous mode is a custom leader-driven team mode for research-style projects.

Behavior:

• the leader starts with team context already initialized
• the leader cannot directly do implementation work
• the leader delegates to teammates
• the leader can use team messaging and shared task tools

Run it with:

cd /path/to/sous_cli
ANTHROPIC_API_KEY=... ANTHROPIC_BASE_URL=... sous

Optional fixed team name:

cd /path/to/sous_cli
ANTHROPIC_API_KEY=... ANTHROPIC_BASE_URL=... CLAUDE_CODE_SOUS_TEAM_NAME=sous-test sous

Other Modes

Coordinator mode:

CLAUDE_CODE_COORDINATOR_MODE=1 bun run dist/cli.js

Proactive mode:

bun run dist/cli.js --proactive

Experimental team mode:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 bun run dist/cli.js

Typical Workflow

1. Install dependencies with bun install
2. Build with bun run build
3. Run sous locally, or install the published package with npm install -g sous-cli
4. Use sous --normal to start the previous default mode explicitly

Notes

• node_modules/ and dist/ take most of the disk space in this repo.
• If bun run ... fails because Bun is not found, add the Bun PATH exports to your shell config and reload it.
• dist/cli.js should be rebuilt after source changes.