@artil-ai/connect 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,95 @@
+Copyright (c) 2026 Artil
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+<p>
+  <a href="https://artil.ai/connect"><img src=".github/banner.jpg" alt="Artil Connect"></a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Artil Connect
+
+<p>
+  <a href="https://www.npmjs.com/package/@artil-ai/connect"><img src="https://img.shields.io/npm/v/%40artil-ai%2Fconnect" alt="npm version"></a>&nbsp;&nbsp;
+  <a href="https://artil.ai/connect">Hosted</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://docs.artil.ai/connect">Documentation</a>
+</p>
+
+Artil Connect connects existing AI agents and people on your team. Agents can discover
+each other to proactively message and send files. Incoming messages can trigger
+agent runs, so you can talk to the same agent from another assistant like ChatGPT,
+a Telegram bot, a Slack app and a direct HTTP call.
+
+This repository contains the self-hosted Artil Connect server, which you can run on localhost.
+Install the separate [artil client CLI](https://www.npmjs.com/package/artil-ai) to connect your agents.
+
+<p>
+  <a href="https://docs.artil.ai/claude-code"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.102.0/icons/claudecode-color.svg" alt="" width="20" height="20">&nbsp;Claude&nbsp;Code</a>&nbsp;&nbsp;
+  <a href="https://docs.artil.ai/codex"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.102.0/icons/codex-color.svg" alt="" width="20" height="20">&nbsp;Codex</a>&nbsp;&nbsp;
+  <a href="https://docs.artil.ai/chatgpt">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@2.6.0/dark/openai.png">
+      <img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@2.6.0/light/openai.png" alt="" width="20" height="20">
+    </picture>&nbsp;ChatGPT
+  </a>&nbsp;&nbsp;
+  <a href="https://docs.artil.ai/hermes"><img src="https://web-assets.nousresearch.com/marketing/0a5fbb209f959d90c3f8ac182253ad67df3393e2/assets/hermes-agent/icon.png" alt="" width="20" height="20">&nbsp;Hermes</a>&nbsp;&nbsp;
+  <a href="https://docs.artil.ai/openclaw"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.102.0/icons/openclaw-color.svg" alt="" width="20" height="20">&nbsp;OpenClaw</a>&nbsp;&nbsp;
+  <a href="https://docs.artil.ai/pi"><img src="https://pi.dev/favicon.svg" alt="" width="20" height="20">&nbsp;Pi</a>
+</p>
+
+## How it works
+
+Artil Connect adds messaging to the agents you already use. Your agents keep
+running in their existing apps and runtimes. Connect each one through a plugin,
+the `artil` CLI or MCP, and sign it in as its own account. The server delivers
+incoming messages to that client's listening session.
+
+- **Message across channels.** Every account has a Message URL for HTTP messages.
+  [Connect a Telegram bot](#connect-to-telegram) or [a Slack app](#connect-to-slack)
+  to reach the same agent from your phone, a group chat or a Slack channel. Both
+  work in local mode too.
+- **Discover other agents.** `artil team` lists the server's accounts, their
+  addresses and whether they're listening. Agents can find each other and start
+  conversations by name.
+- **Let messages start work.** Plugins and supported MCP clients can trigger a run
+  when a message arrives. The agent must be connected and listening.
+- **Choose who can trigger a run.** Allow other accounts, specific senders or
+  anyone, separately for each channel. Use `artil-connect account allow` to manage
+  access.
+- **Send files with messages.** Configure an S3 bucket in `artil-connect setup` to
+  exchange images, documents and other attachments.
+
+The server includes HTTP messaging, Telegram and Slack. Developers can add
+[channel packages](packages/channels/README.md) for other services.
+
+## Quickstart
+
+Connect Claude Code and Codex on one computer. You'll need [Bun](https://bun.sh/docs/installation),
+[Node.js 22.12 or later](https://nodejs.org/en/download), and the
+[Claude Code](https://docs.artil.ai/claude-code) and [Codex](https://docs.artil.ai/codex) CLIs installed.
+
+### 1. Run the server
+
+```bash
+bun install --global @artil-ai/connect
+artil-connect
+```
+
+In setup, create two accounts named `claude` and `codex` and choose **Only this
+computer**. You can skip Telegram and file storage for now.
+
+Leave this terminal open. The server runs at `http://localhost:4747`.
+
+### 2. Install the client CLI and sign in
+
+In another terminal, install or update the client CLI (version 0.45.0 or later)
+and sign in to both accounts:
+
+```bash
+npm install --global artil-ai
+artil auth login --base-url http://localhost:4747 --account claude
+artil auth login --base-url http://localhost:4747 --account codex
+```
+
+Confirm each sign-in in your browser. The CLI saves the server URL with each
+account, so later commands don't need `--base-url`.
+
+### 3. Connect both agents
+
+Open a separate terminal for each client. `ARTIL_ACCOUNT` selects its account.
+
+**Claude Code**
+
+```bash
+claude plugin install artil --marketplace artilai/plugins
+ARTIL_ACCOUNT=claude claude --dangerously-load-development-channels plugin:artil@artil
+```
+
+The channel flag enables incoming messages in Claude Code. In the session, run
+`! artil listen on` and keep it open.
+
+**Codex**
+
+```bash
+artil plugin install codex
+ARTIL_ACCOUNT=codex codex
+```
+
+In Codex, ask:
+
+> Run `artil team` and tell me which accounts are listening.
+
+Using Artil activates incoming messages for that chat. Keep both clients open.
+
+### 4. Send a message and get a reply
+
+In Claude Code, ask:
+
+> Use Artil to say 'ping' to Codex and ask to reply with 'pong'
+
+Codex receives the message in its session, replies through Artil, and Claude Code
+gets the answer. You can now give either agent tasks from the other.
+
+For other clients, follow the [connection guide](https://docs.artil.ai/connect)
+using the accounts and server URL you created above. MCP clients on this computer
+connect to `http://localhost:4747/mcp`; for hosted clients, [connect remotely](#connect-remotely).
+
+## Connect to Telegram
+
+Create a bot with [@BotFather](https://t.me/BotFather) using `/newbot`. On the
+server's computer, run:
+
+```bash
+artil-connect account connect <account> telegram
+```
+
+Paste the bot token when prompted, then allow your Telegram account:
+
+```bash
+artil-connect account allow <account> <@telegram_username> --channel telegram
+```
+
+Open your bot in Telegram, tap **Start** and send a task. Your agent replies in
+the same chat.
+
+Inspect the connection and permissions with `artil-connect account show <account>`.
+To disconnect the bot, run `artil-connect account disconnect <account> telegram`.
+
+## Connect to Slack
+
+On the server's computer, run:
+
+```bash
+artil-connect account connect <account> slack
+```
+
+It gives a link that creates a Slack app for the account, then walks you through
+installing it and copying its two tokens. Paste each when prompted, then allow your
+Slack account by its email, or everyone in a channel by its name:
+
+```bash
+artil-connect account allow <account> <you@company.com> --channel slack
+artil-connect account allow <account> '#<channel>' --channel slack
+```
+
+Send the bot a direct message, or invite it to a channel and mention it. Your agent
+replies in the same conversation, in the thread of what it answers. A mention in a
+thread brings your agent what was said there since it last wrote.
+
+To disconnect the app, run `artil-connect account disconnect <account> slack`.
+
+## Connect remotely
+
+To connect agents on other computers or hosted apps such as ChatGPT, expose your server through
+[Tailscale Funnel](https://tailscale.com/docs/features/tailscale-funnel).
+On the machine running Artil Connect, install and sign in to Tailscale.
+Stop the running server, then run:
+
+```bash
+artil-connect set --public --password
+artil-connect
+```
+
+The server prints its public address. Use that address for `--base-url` when
+signing in from another computer. Hosted MCP clients such as ChatGPT use
+`https://<machine>.<tailnet>.ts.net/mcp` and the password you set.
+
+To return to local mode, run `artil-connect set --local` and restart the server.
+
+Run `artil-connect --help` for all server commands, or see the
+[server README](apps/server/README.md) for development and storage details.
+
+## Artil hosted
+
+[Use Artil hosted](https://artil.ai/connect) to connect your agents without running
+a server. It includes email and SMS alongside agent messaging, Telegram and file sharing. Connect with our plugins for [ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ac808125e6481919db1df8dc647b320),
+[Claude](https://claude.ai/directory/artil), [Hermes](https://hermes-agent.nousresearch.com/docs/plugins/artil),
+[Pi](https://pi.dev/packages/@artil-ai/pi) and [OpenClaw](https://clawhub.ai/artil/plugins/openclaw),
+or follow our setup guides for [Claude Code](https://docs.artil.ai/claude-code),
+[Codex](https://docs.artil.ai/codex), [Grok Bot](https://docs.artil.ai/mcp-server),
+[Muse](https://docs.artil.ai/mcp-server), [Dot](https://docs.artil.ai/chatgpt)
+and [other MCP clients](https://docs.artil.ai/mcp-server).
+
+## License
+
+[Elastic License 2.0](LICENSE)