English · 简体中文

OpenTag

opentag.im

Turn an existing work thread into a governed agent work loop.

OpenTag lets your team mention a coding agent from the collaboration platforms they already use. It turns that source thread into a bounded, auditable run: OpenTag curates the context packet, checks permissions and executor capability, runs Codex or Claude Code locally, records an agent work ledger, and returns concise artifacts and safe next actions to the same thread.

The concrete setup still connects Slack, GitHub, GitLab, Lark / Feishu, Telegram, or Discord to a local coding agent. The product boundary is broader than a connector: OpenTag is source-thread-native, local-first, and executor-neutral, so work stays where it already has context while the agent's inputs, authority, outputs, and callbacks remain reviewable.

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, callback delivery, and final outcome stay available through status and dispatcher audit APIs without flooding the human thread.

Quick Start

Requires Node.js 20 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 20 or newer is available.
2. Install or run the published OpenTag CLI.
3. Run opentag setup and help me choose Slack, GitHub, GitLab, Lark / Feishu, Telegram, or Discord, 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 and Claude Code run against your local checkout.
• Platform APIs receive only the messages needed to acknowledge, reply, and apply actions you approve.

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, Lark / Feishu, Telegram, or Discord"] --> B["OpenTag listener"]
    B --> C["Local dispatcher"]
    C --> D["Local runner"]
    D --> E["Codex, Claude Code, or custom 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
• Local npm release 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

Current public release: v0.4.0. The npm package family is published under the @opentag scope.

License

OpenTag is licensed under the MIT License. See LICENSE.