Agent setup

TeamShare is the coordination hub. Agents are registered in the app — identity, capabilities, assignments, and a run history — while the AI itself runs on your computer. Three methods connect the two, all powered by the teamshare-bridge package:

Every method shares the same core: heartbeat the agent as working, fetch a task brief (task, comments, project files), drive a harness (opencode, Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Goose, OpenHands, Aider, Cline, OpenRouter, or the built-in headless LLM loop), report back with a summary comment, and return the agent to online. See the full harness comparison at https://teamshare-frontend.vercel.app/docs or docs/harness-headless.md.

TeamShare exposes 16+ MCP tools (create_task, update_task, add_comment, list_documents, search, etc.) that any MCP-compatible client can call. But MCP alone is not enough to run an agent autonomously. Here is what each provides:

The key distinction

MCP alone = a tool box. The agent can do work if someone manually asks it to. The frontend cannot trigger or control it — there is no daemon listening for wake events.

Bridge = an agent runtime. It receives wake events from the backend via WebSocket, spawns the agent session, feeds it the task context, and streams output back.

Without the bridge, this flow breaks

// Frontend assigns task to agent
// Backend sends wake event via WS
// ??? (no bridge daemon listening)
// Agent never starts

With MCP only, the agent can work if: (1) the user manually runs opencode and gives it a prompt, (2) the user pastes in task context manually, or (3) the LLM calls MCP tools to do the work. But the frontend's Run button, wake events, live console, and online status will not work.

• Node.js 18+ (v22 recommended) — the bridge and harnesses run on it. Install at https://nodejs.org
• A TeamShare account — sign up at the app or your hosted deployment
• A harness (opencode, Claude Code) or an LLM API key for headless mode — see Harnesses below

1. 1Sign up at /register (email or Google) and verify your email address.
2. 2Create a company workspace or use your personal workspace — onboarding walks you through it.
3. 3Create a project, then a task. Agents work on tasks; you will point them at a task id.
4. 4Open Agents in the sidebar and choose New agent.
5. 5Give it a name, an optional model hint, and its capabilities — tasks:read, tasks:create, tasks:update, comments:create, chat:read, chat:write, documents:read, search, projects:read.
6. 6Copy the ts_... API key now. It is shown exactly once and never again.

The bridge is a separate package that runs sessions on your machine. Install it globally so the teamshare-agent and teamshare-bridge commands are on your PATH.

npm i -g teamshare-bridge

Now save your agent to this machine. The connect command tests the connection and stores the key in ~/.teamshare/config.json:

teamshare-agent connect --agent <agent-id> --key ts_...
teamshare-bridge status

Run the daemon

The daemon listens for wake events (task assigned, @mention in chat/comments/documents) and spawns a session for each. One bridge serves your whole system — it is not per-project.

teamshare-bridge start
teamshare-bridge status
teamshare-bridge autostart on   # start at login
teamshare-bridge stop

The one-off path. Run a single task explicitly, or let the agent pick its next assigned task from its inbox (highest priority first, then oldest, skipping in_review/resolved/closed).

teamshare-agent run --task <task-id> --agent <agent-id> --key ts_...

# or pick the next assigned task automatically:
teamshare-agent run --agent <agent-id> --key ts_...

1. 1The agent heartbeats working — the status dot in the app turns amber.
2. 2The CLI fetches the task brief: description, comment thread, project name, and project files (text truncated to ~20k chars; links return their URL). The brief is written to the temp folder and printed as a preview.
3. 3The harness runs (auto picks opencode, then claude; --harness none prints the brief for manual work).
4. 4A closing summary comment is posted (skip with --no-report).
5. 5The CLI polls the task every 15s (up to 20 min) until it leaves open/in_progress, then heartbeats back to online.

teamshare-agent run --task <id> --agent <id> --key ts_... `
  --harness opencode|claude|none --self --no-report --api-url <url>

Keep the daemon running in the background and it reacts the moment work lands on the agent. It holds a WebSocket to TeamShare per configured agent and spawns a session on wake events.

teamshare-bridge daemon

The daemon also serves the localhost probe (GET http://localhost:<port>/ping, bound to 127.0.0.1) that the website pings to show the green Bridge detected pill.

What wakes the agent

Every wake also writes a wake_sent row to the agent's run history, so you always know when and why a session was spawned. Anything missed while offline is covered by the agent's durable inbox.

Wake rules and quiet hours

{
  "agents": [{ "agentId": "<agent-id>", "apiKey": "ts_..." }],
  "port": 48242,
  "harness": "auto",
  "quietHours": { "start": "22:00", "end": "07:00" },
  "wakeRules": { "priorities": ["high", "urgent"] }
}

• quietHours — wake events are ignored during this window
• wakeRules.priorities — only wake for tasks with these priorities
• port — probe port, picked at random from the candidate set on first run; override with --port

One click from the app. Register the teamshare:// scheme once, then the Run agent button mints a 10-minute single-use run token and opens a deep link the bridge turns into a session.

teamshare-bridge register

1. 1Open the agent (or the task) in the app — the Bridge detected pill should be green.
2. 2Make sure this agent is connected on this computer (step 2's connect command). The Run button is disabled with an inline connect hint when the agent's key is missing locally.
3. 3Click Run agent. Your browser asks whether to open TeamShare Bridge — accept.
4. 4The bridge redeems the run token server-side, spawns the session in a new terminal, and the run appears in Run history.

The deep link format is teamshare://agent/run?runToken=<token>&task=<taskId>. The long-lived API key never appears in the URL — only the short-lived token does, exchanged for a 1-hour WebSocket credential.

The harness is not part of TeamShare. It is a separate AI coding tool installed on your machine; the bridge just spawns whichever is on your PATH (auto tries opencode first, then claude, then codex, gemini, antigravity, copilot, goose, openhands, aider; Cline is explicit-only). You do not clone it from the TeamShare repository. One option is different: OpenRouter is an API gateway, not a CLI - selecting it installs nothing and runs the built-in headless loop against openrouter.ai.

npm i -g opencode-ai
# or the official installer:
iwr https://opencode.ai/install | iex

Agent LLM keys — never your personal account

By default a harness run uses your machine's normal opencode credentials. To keep agent usage off your personal account, store a dedicated provider key in the bridge — globally for every agent, or per agent. The bridge exports it to each session as OPENCODE_API_KEY, so the harness bills that key, not you.

teamshare-agent key set --key <providerApiKey>          # global default - replaces the previous key
teamshare-agent key set --key <providerApiKey> --agent <agent-id>  # that agent only
teamshare-agent key show
teamshare-agent key clear [--agent <agent-id>]

Headless mode — no harness at all

The --self loop is an OpenAI-compatible function-calling loop. The model receives the task brief plus tools (get_task, list_tasks, create_task, update_task, add_comment, list_documents, read_document, search, ask_human, wait_for_answer, list_subtasks, create_subtask, update_subtask). It is instructed to break the task into concrete subtasks (create_subtask) and check each off (update_subtask done: true) as work progresses — the human sees the live breakdown in the app. It posts milestone comments and finishes by moving the task to in_review or resolved. Chat replies stream token-by-token into the channel (Phase C) when the provider supports streaming.

$env:LLM_BASE_URL = "https://openrouter.ai/api/v1"
$env:LLM_API_KEY = "sk-..."
$env:LLM_MODEL = "deepseek/deepseek-chat"
teamshare-agent run --task <task-id> --agent <agent-id> --key ts_... --self

Model selection — the curated catalog

In the app, an agent's model is chosen from a curated dropdown (never free text). The stored value is a provider:model id such as gemini:gemini-2.5-flash; the bridge resolves the provider to its OpenAI-compatible base URL automatically. The full catalog and the update process live in docs/agent-models.md.

Give opencode direct access to TeamShare through the same key by adding the MCP server to opencode.json. The server lives at the API /mcp endpoint and speaks Streamable HTTP.

{
  "mcp": {
    "teamshare": {
      "type": "remote",
      "url": "https://api.teamshare.name.ng/mcp",
      "headers": { "X-Api-Key": "ts_..." }
    }
  }
}

The full tool catalog — list_tasks, get_task, create_task, update_task, add_comment, create_subtask, update_subtask, list_subtasks, list_documents, read_document, search, get_inbox, list_agents, get_project — is documented on the MCP page. Every tool is gated by the key's scopes, which derive from the agent's capabilities.

• Agent detail page: the status dot turns green (online) when the bridge is connected, amber while a session runs.
• Run history shows Run started then Run completed with the task title, plus wake_sent rows for mentions.
• The spawned terminal prints the brief preview, the harness output, and [done] task <id> final status: ….
• daemon.log records every connect and heartbeat.

Troubleshooting

One session per agent

run/chat/doc sessions take a per-agent lock (~/.teamshare/locks/<agentId>.lock). A second run for a busy agent waits ("agent … is busy — waiting…", polls every 10s) instead of double-working the same task; the daemon queues wakes while busy and spawns them when the agent frees up. Stale locks (crashed session = dead PID, or older than 8h) are reclaimed automatically and can be force-removed with teamshare-bridge clear-lock --agent <id>.

Agents run on your machine, so every session — task assignment, @mention, Run button — resolves its project and refuses to start unless that project is linked to a local folder. Linking is the explicit grant: it says "this project's work happens inside this folder", and the agent never runs anywhere else. Unlinked projects are hard-blocked with a visible hint in the spawned terminal.

teamshare-agent link --project <project-id> --path "C:\Users\you\projects\my-app"

teamshare-agent link --list
teamshare-agent unlink --project <project-id>

• Find the project id in the URL when you open the project in the app (…/projects/<project-id>), or run teamshare-agent link --list to see what is already linked.
• The mapping lives only in ~/.teamshare/config.json on this computer — it never leaves your machine. The agent detail page in the app shows the linked folders through the local bridge probe, so you can copy the exact command from there.
• --path is validated: OneDrive, UNC (\\) and mapped network drive paths are rejected, and the folder must live inside your user profile.
• Unlinking re-blocks the project immediately — sessions that are already running are not interrupted.
• One-off override: teamshare-agent run/chat/doc accept --cwd <folder> to pin the working folder for that single session without touching the project mapping.