Install
Install the bridge globally on your platform:
Windows
npm i -g teamshare-bridgeYou now have two commands: teamshare-agent (the CLI session runner) and teamshare-bridge (the daemon + protocol handler). Runtime dependency: socket.io-client only — everything else is Node built-ins.
teamshare-agent
| Command | Purpose |
|---|---|
| teamshare-agent connect --agent <id> --key ts_... | Test the connection and save the key in ~/.teamshare/config.json |
| teamshare-agent run --task <taskId> --agent <id> --key ts_... | Work a specific task |
| teamshare-agent run --agent <id> --key ts_... | Pick the next assigned task from the inbox (priority first, then oldest) |
| teamshare-agent build --project <id> --agent <id> --key ts_... | Run the build agent loop (works ready-for-dev tasks in order) |
| teamshare-agent build ... --draft "<goal>" | Plan a build queue from a free-text goal using an LLM (creates ready-for-dev tasks) |
| teamshare-agent build ... --draft "<goal>" --go | Plan the queue and immediately start executing it |
| teamshare-agent link --project <id> --path <folder> [--guard true|false] | Project guard: bind a project to a local folder (the agent refuses unlinked projects; OneDrive/UNC/mapped/outside-profile paths are rejected) |
| teamshare-agent link --list | Show every linked project and its folder |
| teamshare-agent unlink --project <id> | Remove a link — the project is hard-blocked again |
| teamshare-agent key set --key <providerApiKey> [--agent <id>] | LLM provider key for harness runs (e.g. an opencode-go API key). Without --agent it becomes the GLOBAL default for every agent; with --agent it overrides that agent only. Replaces the previous global key. |
| teamshare-agent key show | clear [--agent <id>] | Show (masked, never the full key) or clear the provider key — cleared agents fall back to your default opencode credentials |
| --harness auto|opencode|claude|codex|gemini|antigravity|copilot|goose|openhands|aider|cline|openrouter|none | Session driver — defaults to config or auto (detects first on PATH; cline is explicit-only) |
| --self | Headless LLM loop (requires LLM_API_KEY) |
| --no-report | Skip the closing summary comment |
| --cwd <folder> | Work inside this folder for this one session (bypasses the project mapping) |
| --api-url <url> | TeamShare API base override |
teamshare-bridge
| Command | Purpose |
|---|---|
| teamshare-bridge daemon [--port N] | Auto-wake listener + localhost probe; spawns sessions on wake events (queues them while the agent is busy) |
| teamshare-bridge register | Register the teamshare:// scheme (per-user, no admin) |
| teamshare-bridge serve "<teamshare://url>" | OS-invoked — redeem the run token and spawn the session |
| teamshare-bridge add-agent --agent <id> --key ts_... | Save a key without testing the connection |
| teamshare-bridge status [--port N] | Config path, port, per-agent BUSY/idle (stale locks flagged), harness, quiet hours, scheme |
| teamshare-bridge clear-lock --agent <id> | Force-remove a stale session lock (dead sessions are auto-reclaimed; this is the manual override) |
| teamshare-bridge probe [--port N] | Start just the probe server (testing) |
Configuration
~/.teamshare/config.json
{
"agents": [
{ "agentId": "<agent-id>", "apiKey": "ts_...", "opencodeKey": "sk-..." }
],
"port": 48242,
"harness": "auto",
"quietHours": null,
"wakeRules": null,
"opencodeKey": "sk-..."
}| Key | Meaning |
|---|---|
| agents | Agent id + key pairs the daemon listens for |
| port | Probe port; random pick from [48231, 48242, 48253, 48264, 48275, 48286, 48297] on first run |
| harness | Preferred driver: auto, opencode, claude, codex, gemini, antigravity, copilot, goose, openhands, aider, cline, openrouter, none |
| quietHours | { start: "22:00", end: "07:00" } — ignore wakes in this window |
| wakeRules | { priorities: ["high", "urgent"] } — only wake for these priorities |
| opencodeKey | Global LLM provider key for agent harness runs (exported to the session as OPENCODE_API_KEY). Set with teamshare-agent key set --key <key>; per-agent override lives on an agents[] entry. Never logged or printed in full |
| projects | { "<project-id>": { "path": "C:\\...", "guard": true } } — project guard links; managed with teamshare-agent link, never by hand |
Environment variables
| Variable | Default | Used by |
|---|---|---|
| TEAMSHARE_API_URL | https://api.teamshare.name.ng/ | All commands |
| TEAMSHARE_WS_URL | wss://api.teamshare.name.ng | Daemon WebSocket |
| LLM_BASE_URL | https://api.openai.com/v1 | --self |
| LLM_API_KEY | — (required) | --self |
| LLM_MODEL | deepseek-chat | --self |
Platform notes
| Platform | Terminal spawn | Scheme registration |
|---|---|---|
| Windows | cmd /c start cmd /k — detached window, stays open after the session | HKCU\Software\Classes\teamshare via reg.exe (per-user) |
| macOS | Terminal.app via osascript (always present) — real window, no installs needed | ~/Applications/TeamShareBridge.app (CFBundleURLTypes); open the bundle once to finish registration |
| Linux (desktop) | xdg-terminal-exec → gnome-terminal → konsole → xterm (first one on PATH wins) | ~/.local/share/applications/teamshare-bridge.desktop + update-desktop-database |
| Linux (server / SSH) | Headless fallback — session runs with no window; watch it via the web live console | Not applicable (no deep-link UI) |
The session window (or the web live console when running headless) shows the same output either way — the CLI heartbeats, streams its transcript to the backend, and reports the closing summary comment regardless of where the window lives. The bridge picks a working launcher automatically; you never configure it.
Troubleshooting
| Symptom | Fix |
|---|---|
| EADDRINUSE on probe | --port <candidate> or remove the port key; the website probes all candidates |
| Agent not configured locally on a deep link | teamshare-agent connect --agent <id> --key ts_... |
| No harness found on run | Install opencode or Claude, or use --self |
| Wake events never arrive | teamshare-bridge status; daemon must be running with the key saved |
| Sessions blocked: "project … has no linked folder" | The project guard refuses unlinked projects by design — link a folder: teamshare-agent link --project <id> --path <folder>, then assign/mention again |
| Probe shows agents: [] | teamshare-bridge add-agent --agent <id> --key ts_... |
| Session opens but exits instantly | Run teamshare-agent run … manually; check the API URL and key scopes |
Build mode
The build command runs the build agent loop — it works through ready-for-dev tasks in strict order. The --draft flag lets the agent plan the queue from a free-text goal using an LLM.
examples
teamshare-agent build --project <id> --agent <id> --key ts_...
teamshare-agent build --project <id> --agent <id> --key ts_... --draft "Build a Next.js landing page"
teamshare-agent build --project <id> --agent <id> --key ts_... --draft "Build a REST API" --go| Flag | Purpose |
|---|---|
| --draft "<goal>" | Use an LLM to plan ready-for-dev tasks from a free-text goal |
| --draft "<goal>" --go | Plan the queue and immediately start executing it |
| --dry-run | Show what would be built without executing |
| --on-fail ask|stop | What to do when a task fails (ask human or stop the build) |
| --blocked-wait | Wait for human answers instead of skipping blocked tasks |
Prerequisites for --draft
The build agent must have a provider API key (teamshare-agent key set), a linked project folder (teamshare-agent link), and the bridge daemon running.