TeamworkOS

AI agent orchestration platform on your laptop.

Run scheduled Claude Code agents, coordinate multi-agent teams, and manage everything through a live dashboard.

What is TeamworkOS

TeamworkOS manages a hierarchy of AI employees (agents), schedules them as jobs, and routes work between them. You define agents in config files, write jobs that describe what each agent should do, and the platform runs them on a schedule. A live dashboard shows every running session, its output, and any messages sent between agents.

Jobs connect to Slack, call tools, resume previous sessions, and coordinate through a shared identity layer. The gateway runs locally on your machine; agents use your own Claude Code subscription, so there are no per-token charges beyond what you already pay.

Prerequisites

• macOS 14+ or Linux (x86-64 or ARM)
• Node 25 (required): The published binary uses bytenode bytecode, which is V8-version-locked. The artifact is built under Node 25 (the package pins engines: node >=25.0.0 <26), so it cannot load on any other major version. Install via nvm: nvm install 25 && nvm use 25.
• Claude Code CLI: Install from claude.ai/download and authenticate. TeamworkOS runs agents through the claude binary using your existing Claude Code subscription.
• Xcode Command Line Tools (macOS, optional): Only needed if better-sqlite3 lacks a prebuilt binary for your platform. Most users can skip this. If you see a build error during install, run xcode-select --install and retry.

Install

npm install -g @wkoutre/teamwork-os
teamos init

teamos init is an interactive wizard that runs in about 60 seconds. It configures your environment and optionally starts the gateway as a background service.

First run

teamos init walks through the following steps:

1. Checks your environment. Node version and claude binary on PATH.
2. Creates ~/.teamwork/. The directory where all your data lives: jobs, agent definitions, logs, sessions, results. You can override the path by setting TEAMWORK_HOME before running teamos init.
3. Asks for optional API tokens. Slack, Linear, Figma, GitHub. Each prompt shows one line describing what the token is for. Press Enter to skip any token; you can add them later by editing ~/.teamwork/.env.
4. Confirms the port (default: 7463). If the port is already taken by another process, the wizard will offer an available alternative.
5. Starts the gateway and optionally installs it as a launchd (macOS) or systemd (Linux) service so it restarts automatically at login.
6. Prints a summary with your dashboard URL and the most useful next commands.

After setup, the dashboard is at http://localhost:7463. The full web dashboard ships inside the package and is served by the gateway itself — there is no separate frontend build or web server to run.

Daily use

teamos status      Check whether the gateway is running and what's enabled.
teamos restart     Bounce the gateway (picks up .env changes).
teamos doctor      Health check: install mode, port, engine, and update availability.
teamos update      Pull the latest version from npm and restart.
teamos logs        Tail gateway logs.

Updating

teamos update is the recommended upgrade path. It handles the install, history recording, and gateway restart in one step.

teamos update                  # install latest, restart gateway
teamos update --check          # exit 0 if up to date, exit 1 if an update is available
teamos update --to 1.2.3       # pin to a specific version
teamos update --rollback       # revert to the previously installed version

Alternatively: npm install -g @wkoutre/teamwork-os@latest followed by teamos restart.

Uninstalling

teamos uninstall   # removes the launchd/systemd service; prompts before deleting ~/.teamwork/
npm uninstall -g @wkoutre/teamwork-os

teamos uninstall will ask whether to also delete ~/.teamwork/ (your jobs, agent configs, logs, and sessions). The default is no. Pass --remove-data to opt in non-interactively.

Troubleshooting

Start with teamos doctor. It checks the install mode, plist or systemd unit, port availability, engine configuration, and whether an update is available. Most issues surface there first.

Common problems:

• Port 7463 in use: teamos init will offer an alternate port during setup. To change it after the fact, set PORT=XXXX in ~/.teamwork/.env and run teamos restart.
• claude not on PATH: Confirm which claude works in a new terminal window. If you installed Claude Code recently, restart your shell or source your profile.
• EACCES on npm install -g: Your global npm prefix may be system-owned. See npm's EACCES docs. Do not use sudo npm install -g.
• Gateway not starting: Run teamos doctor for specifics. Logs are at ~/.teamwork/logs/gateway-launchd-error.log (macOS) or via journalctl --user -u teamwork-os (Linux).
• Switched Node versions after install: The service runs under the Node binary you installed with (the bytecode is locked to that major). If you later install a different Node major and remove the old one, re-run teamos install so the service points at the current binary. The error log will warn if it had to fall back to a PATH node.

Reporting issues

Public issue tracker coming soon. In the meantime, reach out to Nick directly if you hit a bug.

License

MIT