@teamx-sh/agent

Watches your local git activity and syncs it to your TeamX team feed.

The TeamX agent runs on your dev machine and quietly turns your work into real-time activity for the rest of the team: commits, file changes, focus shifts, and doc edits.

What it does

• git-watcher: polls your repo for new commits and posts them to your team's activity feed.
• doc-scanner: finds and indexes AGENTS.md, CLAUDE.md, SKILL.md, README.md, and similar docs.
• task-mapper: links commits to tasks via branch names and commit prefixes like TMX-123: ....
• daily-digest: a once-a-day summary of what shipped.
• deadline-checker: flags overdue tasks before standup.

It runs as a single long-lived process per repo. One config file (.teamx-config.json) lives at the repo root.

Install

npx @teamx-sh/agent connect --token=<your token>

You get the token from the Connect Agent flow in the TeamX dashboard. The token is a signed TeamX bearer token scoped to your member and team, plus the URLs the agent needs to call TeamX's edge functions.

Commands

| Command | What it does | |---|---| | npx @teamx-sh/agent connect --token=<token> | Decode the token, write .teamx-config.json, and test the connection. | | npx @teamx-sh/agent watch | Start the long-lived watcher. Sync every 5 minutes by default. | | npx @teamx-sh/agent sync | Run a one-shot sync without staying resident. | | npx @teamx-sh/agent listen --agent=claude-code | Accept DMs from TeamX Messages into your local agent. | | npx @teamx-sh/agent supervise listen --agent=claude-code | Wrap a subcommand in a respawn loop. What install-service registers. | | npx @teamx-sh/agent install-service [--agent=claude-code] | Register the supervisor with launchd / systemd / Task Scheduler so the listener auto-starts at login. | | npx @teamx-sh/agent uninstall-service | Unregister the service for this platform. | | npx @teamx-sh/agent self-update | Install the latest @teamx-sh/agent globally; exits 42 so a wrapping supervisor restarts on the new binary. | | npx @teamx-sh/agent status | Show the current connection. | | npx @teamx-sh/agent disconnect | Mark the agent disconnected and remove .teamx-config.json. |

Run automatically at startup

Once your listener is connected once, register it with your OS so it comes back every time you log in:

npx @teamx-sh/agent install-service --agent=claude-code

This drops a service file in the right place per platform and starts the listener now — no logout/login required:

| Platform | What lands where | |---|---| | macOS | ~/Library/LaunchAgents/sh.teamx.agent.plist — loaded via launchctl bootstrap gui/$UID. Logs to ~/Library/Logs/teamx-agent.log. | | Linux | ~/.config/systemd/user/teamx-agent.service — enabled via systemctl --user. Logs to journald (journalctl --user -u teamx-agent -f). For boot-time start, run sudo loginctl enable-linger $USER once. | | Windows | Scheduled task "TeamX Agent" with LogonTrigger + RestartOnFailure. Logs to %LOCALAPPDATA%\teamx-agent\teamx-agent.log. May prompt for UAC the first time. |

The service file always points at teamx-agent supervise listen .... The supervisor wraps your listener and handles:

• Clean exits (code 0): restart immediately.
• Self-update (code 42): pause 2 s so the new binary is on disk, then restart from it.
• Crashes (any other exit): exponential backoff from 1 s to 60 s, resetting after a child that lived ≥ 30 s.

If you ever need to remove it: npx @teamx-sh/agent uninstall-service.

Keeping the agent up to date

Three layers, from least to most intrusive:

1. Startup version check. Every time the listener starts, it hits the npm registry once (cached for 24 h at ~/.teamx-agent/version-check.json) and prints a banner if there's a newer @teamx-sh/agent published. Silent on offline.
2. Self-update on demand. npx @teamx-sh/agent self-update runs npm install -g @teamx-sh/agent@latest (auto-detects pnpm / yarn if you use them; override with --pm=npm|pnpm|yarn), then exits 42. Under the supervisor, that means a clean swap onto the new binary.
3. Server-driven update push. From TeamX → Mission Control, the row for each connected agent shows its installed version. When a newer version is out, the badge turns amber and clicking it pushes a self-update to that agent (idempotent: 10-minute throttle per member).

Vulnerability scanning (automated)

Ship the bundled .github/workflows/teamx-vuln-scan.yml into any repo you want monitored. Daily + on every push it scans with the native audit tool for each ecosystem it detects (npm, pypi, go, cargo, rubygems) and POSTs findings to TeamX. TeamX creates tasks for unseen findings — agent-kind for patch/minor bumps it can safely handle, human-kind for majors that need judgement — and auto-closes tasks whose CVE no longer shows up.

Setup (per repo):

1. Copy the workflow file from this package into <your-repo>/.github/workflows/teamx-vuln-scan.yml.
2. Create a repo secret TEAMX_TOKEN with your signed TeamX agent token (grab one from the Connect Agent page).
3. Commit + push. The first scan runs on the next push or at 14:00 UTC; manual trigger also available via Actions → Run workflow.

No laptop, no cron daemon, no Supabase access. Runs on GitHub's cloud.

Configuration

The agent reads its config from .teamx-config.json in the current directory. You can override any field with an environment variable:

| Field | Env var | Default | |---|---|---| | supabaseUrl | TEAMX_SUPABASE_URL | from connect token | | functionsUrl | TEAMX_FUNCTIONS_URL | ${TEAMX_SUPABASE_URL}/functions/v1 | | agentToken | TEAMX_AGENT_TOKEN | from connect token | | memberId | TEAMX_MEMBER_ID | from connect token | | teamId | TEAMX_TEAM_ID | from connect token | | repoPath | TEAMX_REPO_PATH | process.cwd() | | syncIntervalMs | TEAMX_SYNC_INTERVAL_MS | 300000 (5 min) |

Security note

The main watcher path now talks to TeamX's edge functions using a signed per-member token rather than a raw database key. A leaked .teamx-config.json is still a credential leak, but it only authorises that member/team scope and no longer carries the Supabase service-role secret.

Auxiliary local scripts in this package are still mid-migration and may continue to use project-level credentials until the remaining security tasks land. Treat them as trusted-operator tooling, not hosted SaaS auth.

License

MIT $