English · 简体中文
Your persistent AI teammate in Slack, running on a computer you control.
OpenTag gives an engineering channel a teammate that remains reachable through your self-hosted Control Plane, even when its paired computer is offline. Mention it in Slack to queue work; when the Runner is ready, it invokes your coding agent through ACP against the local checkout and reports status, decisions, and evidence back in the same thread.
Your source code, local checkout and worktrees, coding-agent login/session, and GitHub credential stay on the Runner. Slack credentials and the Control Plane's service credentials stay on the Control Plane. It keeps coordination truth—not a copy of your development machine.
Prerequisites: Docker Compose, PostgreSQL through the included Compose profile, and a public HTTPS origin that Slack can reach.
git clone https://github.com/amplifthq/opentag.git
cd opentag/deploy/compose
cp .env.example .env
docker compose --env-file .env up --buildBefore the last command, replace every placeholder in .env and create the
file-backed Slack and relay-content secrets described in the
Compose guide.
npm install -g @opentag/[email protected]
opentag setup --relay https://relay.example.com
opentag startSetup configures and pairs one Runner, GitHub Project Target, and ACP executor.
The paired-only runtime requires the trusted self-hosted Control Plane URL and
bootstrap pairing credential; it has no standalone local mode.
When prompted, enter the exact OPENTAG_SLACK_PROJECT_TARGET_ID used by the
active Slack binding; setup registers it through the Runner credential and
verifies the Control Plane readback before pairing completes.
If this machine ran a pre-reset OpenTag checkout, point OPENTAG_CONFIG_HOME
and OPENTAG_STATE_DIR at new empty directories. The paired Runner does not
reinterpret or rewrite an earlier config or SQLite database.
Use opentag pair only to finish an interrupted pairing or pair an existing
unpaired configuration. Verify the exact installation before the first real
request:
opentag doctor
opentag status@OpenTag investigate the failing check and propose a fix
If the Runner is offline, the request remains visibly queued. If work needs a
decision, Slack shows the exact action that needs attention. A provider timeout
or ambiguous side effect remains outcome_unknown; OpenTag does not invent a
success or blindly replay it.
- Present in the channel — the self-hosted relay receives Slack requests and can explain that the Runner is offline instead of disappearing with the laptop.
- Works where the code already lives — the coding agent runs on the paired, user-controlled computer with its approved local Project Target.
- Keeps one conversation — requests, queue state, approvals, blockers, and final evidence return to the originating Slack thread.
- Reports facts, not theater — executor output, Run state, GitHub publication, and provider delivery remain separate facts with separate evidence.
- Writes only through explicit authority — draft PR publication is a distinct, governed stage; OpenTag does not auto-merge or let chat text broaden access.
flowchart LR
S[Slack channel] --> C[Self-hosted Control Plane]
C --> P[(PostgreSQL)]
C --> R[Paired Runner]
R --> A[ACP coding agent]
A --> W[Local checkout]
R --> G[GitHub draft PR and readback]
C --> S
Slack is the only Source App in the supported team profile. GitHub is a Project Target plus an optional publication and evidence provider; it is not a second request inbox. One paired Runner is the execution owner. The Control Plane owns the canonical Work, Attempt, lease, approval, Effect evidence, channel projection, and terminal assessment.
The console exposes each active Slack binding as a long-lived Teammate. Its work state is derived from facts that already exist: Project Target, fresh Runner readiness, and the binding's current Work. It adds no Teammate table, second lifecycle, or mutable presence state.
| State | What it means |
|---|---|
ready |
The Teammate's Project Target, Runner, and fresh readiness all exist. |
queued |
A request is durably waiting for the paired Runner. |
working |
The current fenced Attempt is assigned or running on a ready Runner. |
needs_attention |
A decision, reconciliation, or conflicting active work needs a human. |
runner_offline |
The Teammate remains in Slack, but its Runner has no fresh readiness receipt. |
setup_required |
The Slack binding, Project Target, or Runner is incomplete. |
These states are projections, not commands. They cannot claim, retry, cancel, or settle work.
The current product path is:
Slack presence → self-hosted Control Plane → one paired Runner
→ one ACP coding agent → optional GitHub draft PR/evidence → Slack
This repository does not currently claim managed hosting, high availability,
other Source Apps, GitHub webhook ingress, multi-Runner scheduling, ambient
memory, automatic merge, or a general software-factory planner. There is no
local_direct compatibility mode: the supported product always pairs a Runner
with the self-hosted Control Plane.
OpenTag's Runner launches configured coding agents through ACP and keeps raw tool output out of the team thread. The repository includes an agent-readable install guide and an OpenTag skill so Codex, Claude Code, and other coding agents can help with local setup without asking users to paste secrets into chat.
corepack pnpm install --frozen-lockfile
corepack pnpm typecheck
corepack pnpm test
corepack pnpm buildThese checks prove local source behavior only. They do not prove a deployed relay, a live Slack delivery, a GitHub publication, or installation-level availability.
- Compose installation
- Slack Source App setup
- GitHub Project Target and publication
- Control Plane deployment
- Always-on ingress with local execution
- Configuration reference
- Team-relay canary
Contributions are welcome. See CONTRIBUTING.md for the local development workflow and pull-request checks.