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.

https://github.com/user-attachments/assets/86edc4e1-7de9-4d07-a0ba-847fa6438191

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.

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

Commands

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"]

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.

License

OpenTag is licensed under the MIT License. See LICENSE.