English · 简体中文

OpenTag

opentag.im

Mention any coding agent. Get proof, not promises.

OpenTag is the open, local-first gateway between your team's threads and coding agents. Mention @opentag in Slack or GitHub, and it runs Claude Code, Codex, Cursor, or any Agent Client Protocol agent on your own machine — then replies in the same thread with evidence, not just a summary.

• Any agent, one protocol. Six built-in executors — Codex, Claude Code, Cursor, OpenCode, Hermes, OpenClaw — and custom runners all speak ACP. The mention is never tied to one vendor.
• Local-first by default. Your code, credentials, and full execution traces stay on your machine. Platforms receive only the messages needed to acknowledge, reply, and apply actions you approve.
• "Done" requires evidence. An executor reporting success is not completion. OpenTag can hold a run open until verifiable evidence — a pull request, green checks, a merge — satisfies configured completion gates, with the whole trail recorded in a local audit ledger.

Slack, GitHub, GitLab, Linear, and Lark / Feishu are fully supported today; Telegram, Discord, and Microsoft Teams ship as previews.

Demo

Mention OpenTag in Slack, approve the suggested action, and get a real GitHub pull request.

slack-readme-hero-opentag.mov

Source-Thread Action Receipts

OpenTag treats the thread where a request starts as the approval surface for agent-proposed system-of-record mutations. When an agent suggests a change, OpenTag renders a compact receipt that shows what will change, whether it is ready to apply, and which decision is safe now.

Apply appears only when the dispatcher confirms a configured adapter can execute the action. Otherwise the receipt shows setup or attention needed, and the local audit trail stays available through commands such as opentag status --run <run_id>.

Each run also keeps a local agent work ledger: the source event, admission decision, context packet snapshot, executor capability snapshot, produced artifacts, delivery intent audit, and final outcome stay available through status and dispatcher audit APIs without flooding the human thread. Provider outcomes remain authoritative in the delivery journal rather than being inferred from run events.

Quick Start

Requires Node.js 22.14 or newer.

npm install -g @opentag/cli@latest
opentag setup

No global install for one-off terminal-mode checks:

npx @opentag/cli setup

For background service mode, prefer the global install above so the service definition points at a stable CLI path instead of an npx temporary location.

opentag setup is the main entry point. It walks through the practical choices needed to run OpenTag locally:

1. Which language should the CLI use?
2. Where should OpenTag listen?
3. Which coding agent should OpenTag use?
4. Which local project should OpenTag work on?
5. Which platform credentials should OpenTag save?
6. How should OpenTag keep running?

After setup saves the config, choose how OpenTag should run:

1. Keep running after I close this terminal (recommended)
2. Run only in this terminal
3. Do not start now

For scripted setup, use --service to choose the recommended background mode without the final prompt:

opentag setup --service

--service installs and starts the local background service after setup. Background service mode uses LaunchAgent on macOS and systemd --user on Linux; on other platforms, use terminal mode with opentag start for now. If you skip startup or stop OpenTag later, run opentag start manually for terminal mode or opentag service start for background mode.

Once OpenTag is running, mention it from the connected platform:

@opentag investigate this

OpenTag runs the selected coding agent locally and replies back through that platform.

Ask Your Agent

If you use Codex or Claude Code and do not want to set this up by hand, start a new agent session and paste:

Help me set up OpenTag from https://github.com/amplifthq/opentag.

Use the published OpenTag CLI. Please:
1. Check that Node.js 22.14 or newer is available.
2. Install or run the published OpenTag CLI.
3. Run opentag setup and help me choose Slack, GitHub, GitLab, Linear, Lark / Feishu, Telegram, Discord, or Microsoft Teams, a coding agent, and a local project.
4. When platform credentials are needed, open the matching setup guide in the repository and walk me through it.
5. When setup asks how OpenTag should run, choose the recommended background service option. Then verify with opentag service status and opentag doctor. If service mode is unsupported or I choose terminal mode, use opentag start and keep that terminal open.

Do not invent credentials or secrets. Ask me before entering any token, app ID, channel ID, repository, or project path.

Agents can also follow the full agent-readable setup checklist in Agent-readable install guide.

Platform Guides

Use the guide for the platform you choose in opentag setup.

Platform	Status	Best first path	Guide
Slack	✅ Full	Use Socket Mode for local development	Slack setup
GitHub	✅ Full	Use a repository webhook and GitHub token	GitHub setup
GitLab	✅ Full	Use a project Note Hook and GitLab access token	GitLab setup
Linear	✅ Full	Use a workspace webhook and OAuth App install	Linear setup
Lark / Feishu	✅ Full	Scan the Personal Agent QR code from setup	Lark / Feishu setup
Telegram	🧪 Preview	Use BotFather token with local getUpdates polling	Telegram setup
Discord	🧪 Preview	Use a bot token with local Gateway delivery (slash command only)	Discord setup
Microsoft Teams	🧪 Preview	Use an Azure Bot and public HTTPS tunnel to the local dispatcher (relay mode is not supported)	Microsoft Teams setup

What Runs Locally

opentag setup can install and start the recommended background service, run OpenTag in the current terminal, or save config without starting. opentag setup --service skips the final prompt and installs plus starts the background service on macOS or Linux. Both service and terminal modes start:

• a local dispatcher
• a local runner for the project you selected
• the selected platform listener

Stop terminal mode with:

Ctrl-C

Stop background service mode with:

opentag service stop

OpenTag stores local config here:

~/.config/opentag/config.json

Runtime state and isolated worktrees default to:

~/.local/state/opentag

Privacy

OpenTag's CLI path is local-first.

• There is no OpenTag cloud service in the local CLI flow.
• Platform credentials are stored on your computer with private file permissions.
• Codex, Claude Code, Cursor, OpenCode, Hermes, and OpenClaw run through ACP against your local checkout. OpenClaw cancellation is currently best effort.
• Platform APIs receive only the messages needed to acknowledge, reply, and apply actions you approve.

Optional Control Plane

OpenTag also contains an optional open-source Control Plane for teams that need shared identity, runner pairing, public ingress, tenant-scoped hosted-run coordination, governed permissions, retained evidence, and audit views. It is not required by the local CLI path and it never becomes the custodian of local repositories, source-control credentials, agent credentials, worktrees, or coding-agent execution.

The clean implementation is a Node/Hono application with PostgreSQL, a static Vite/React operator console, and a Docker Compose self-hosting profile. It does not require Cloudflare, TanStack Start, Redis, object storage, or a message broker. Start with the Control Plane README and deployment runbook. A managed deployment or production service is not implied by the source implementation.

GitHub ingress remains default-disabled: the local foundation proves signed delivery reservation and replay, but production activation is blocked until audited binding-secret rotation and disable/re-enable recovery are implemented.

To validate the complete self-hosted profile, install Chromium once and run the production-shaped browser E2E:

corepack pnpm --dir apps/control-plane e2e:install
corepack pnpm e2e:control-plane

The E2E builds the production OCI image, starts an isolated PostgreSQL 17 Compose project, applies migrations, bootstraps the owner, runs the HTTP and jobs processes, and drives Chromium through authentication, API-key, runner, Project Target, and GitHub-binding journeys. It pairs the runner through the public @opentag/client package entry point, then completes signed local ingress, hosted claim, permission, material evidence, cancellation, credential reprovisioning, and recurring jobs before verifying exact durable records with psql. It then restarts the HTTP and jobs services, verifies HTTP readiness and a new jobs settlement, creates a byte-preserving PostgreSQL backup, restores it into a fresh database, and checks the restored migrations, durable records, and a non-ASCII data canary. Successful runs remove their containers, network, volume, generated secrets, and Playwright output; failed runs retain bounded browser artifacts for diagnosis.

This is a local production-shape test. It does not contact GitHub, use a production database, deploy the service, or prove a managed environment is active. See the browser E2E catalog for the exact acceptance journeys and boundaries.

Supported Coding Agents

Coding agent	Status	Notes
Codex	Ready when npx and login are available	Pinned Registry package @agentclientprotocol/[email protected]
Claude Code	Ready when npx and login are available	Pinned Registry package @agentclientprotocol/[email protected]
Cursor	Ready when Cursor CLI is installed and logged in	Uses the installed cursor-agent acp command
OpenCode	Ready when npx and provider configuration are available	Pinned official package [email protected]; ACP launches in pure mode so external plugins cannot write non-protocol data to stdout
Hermes	Ready when installed	Uses hermes -p <profile> acp with a configured local provider
OpenClaw	Ready when installed and its Gateway is configured	Uses the local openclaw acp bridge; cancellation is currently best effort and does not claim termination of Gateway-owned tool subprocesses
Echo	Dev/test only	Does not run a real coding agent

Commands

Command	What it does
opentag setup	Create or update local OpenTag config, then offer to start it
opentag setup --service	Create or update local OpenTag config, then install and start the background service
opentag start	Start the local OpenTag stack in the current terminal
opentag pair	Pair this local runner with a remote relay
opentag service install	Install the OpenTag background service
opentag service start	Start the installed background service
opentag service stop	Stop the installed background service
opentag service restart	Restart the installed background service
opentag service status	Show background service status and runtime readiness
opentag service logs	Show recent background service logs
opentag service uninstall	Uninstall the OpenTag background service
opentag service autostart enable	Enable background service login autostart
opentag service autostart disable	Disable background service login autostart
opentag status	Show local config and runtime status; add --run <run_id>, --channel provider:account/conversation, or --workstream <id> for scoped detail
opentag factory ...	Create or inspect immutable recipes and WorkThread-only workstreams, then submit or retrieve restart-safe admission batches from JSON
opentag cancel	Request cancellation for a run or the active run in a source container
opentag completion escalations --run <run_id>	List structured human escalations, audiences, options, expiry, and attribution for a run
opentag completion acknowledge --escalation <id> ...	Attribute acknowledgement without resolving the blocking escalation
opentag completion resolve --escalation <id> ...	Record an attributed bounded resolution; resume work through a new source-thread task
opentag doctor	Check dispatcher, bindings, checkouts, and executors
opentag ingest	Ingest a fenced local external agent progress or completion event
opentag ingest-template	Print a shell template or manifest for local external agent hook ingest
opentag platforms	List platform setup support and runtime capabilities
opentag executors	List available coding agents and runtime capabilities
opentag maintenance prune-source-deliveries	Prune stale source delivery replay keys after their runs are terminal
opentag config path	Print the local config path
opentag config show	Print redacted local config

Uninstall

Remove the global CLI package:

npm uninstall -g @opentag/cli

Remove local OpenTag config and state:

rm -rf ~/.config/opentag ~/.local/state/opentag

How It Works

flowchart LR
    A["Slack, GitHub, GitLab, Linear, Lark / Feishu, Telegram, Discord, or Microsoft Teams"] --> B["OpenTag listener"]
    B --> C["Local dispatcher"]
    C --> D["Local runner"]
    D --> E["Built-in or custom ACP executor"]
    E --> F["Reply back to the platform"]

Loading

The important boundary: platforms receive messages, OpenTag coordinates the run, and the coding agent executes on your machine.

The default loop is artifact-first rather than chat-first: a final reply should compress the outcome, link to artifacts such as reports, patches, pull request intents, or next actions, and point back to local audit/status for detail.

Developer Docs

• Platform setup guides
• Configuration
• Hook ingest contract
• Adapter authoring
• Real integration smoke test
• Live E2E smoke harness
• Replay harness
• Agent Work Protocol
• ACP-First Agent Runtime and Channel Integration
• Local npm release guide
• npm prerelease candidate guide

Development

From source:

corepack pnpm install
corepack pnpm test
corepack pnpm typecheck
corepack pnpm build

Install the local development command:

corepack pnpm opentag-dev
opentag-dev setup

Packages

Package source release: v0.11.0. This source state is prepared for local release validation only; it is not evidence that the release was published. npm dist-tags remain authoritative for public channel versions, and 0.10.0 remains the documented stable release until registry evidence says otherwise. The coordinated package family contains 18 public packages under the @opentag scope.

Package	Purpose
@opentag/control-protocol	Canonical Control V1 schemas, types, and digest helpers
@opentag/cli	Setup and local runtime command line interface
@opentag/local-runtime	In-process local dispatcher, runner, and platform runtime
@opentag/core	Protocol schemas, types, mention parsing, and JSON Schema exports
@opentag/delivery-contract	Canonical delivery-observation fixtures and receipt contracts
@opentag/governance	Deterministic completion, routing, and workstream evaluation
@opentag/client	Dispatcher HTTP client
@opentag/slack	Slack Socket Mode, Events API handling, and thread replies
@opentag/github	GitHub webhook handling, comments, PR helpers, and action application
@opentag/gitlab	GitLab webhook handling, note replies, merge request helpers, and action application
@opentag/linear	Linear webhook handling, read-only project backlog queries, issue comments, and issue action application
@opentag/lark	Lark / Feishu ingress, Personal Agent registration, and replies
@opentag/telegram	Telegram polling/webhook normalization, bot replies, and source-thread controls
@opentag/discord	Discord Gateway/webhook slash-command interactions and channel replies
@opentag/teams	Microsoft Teams Bot Framework ingest, channel replies, and action apply
@opentag/runner	Executor contracts plus the generic ACP host and built-in launch profiles
@opentag/store	SQLite persistence
@opentag/dispatcher	Embeddable dispatcher, delivery producer, and side-effect kernel

License

OpenTag is licensed under the MIT License. See LICENSE.