Garyx

# Garyx

Garyx is a local-first AI agent gateway. It connects provider-backed agents
to the places where work arrives: Telegram, Feishu / Lark, WeChat, the CLI,
HTTP / WebSocket clients, MCP tools, scheduled automations, and the macOS
desktop app. Every entry point shares the same thread history, workspace
binding, provider sessions, and task state.

Use Garyx when you want an agent to keep working across chat apps, terminals,
desktop sessions, and API calls without moving the conversation into a hosted
control plane.

## Why Garyx

| Capability | What it means |
| --- | --- |
| Local-first gateway | The gateway runs on your machine or server; config and transcripts live under `~/.garyx/`. |
| Multi-channel agents | Built-in Telegram, Feishu / Lark, WeChat, and local API channels share one routing model. |
| Provider choice | Route threads to Claude Code, Codex, Gemini, or custom agent definitions without changing channel setup. |
| Persistent threads | A chat, desktop tab, task, or CLI send can resume the same thread and provider session. |
| Workspace-aware runs | Each thread records the directory the agent should operate in, with optional isolated Git worktrees. |
| MCP integration | Each run gets a scoped Garyx MCP endpoint plus any upstream MCP servers from your config. |
| Tasks and automations | Promote threads into reviewable tasks or schedule recurring prompts that deliver through Garyx. |
| Extensible channels | Install subprocess channel plugins without rebuilding the gateway. |

## Install Garyx

The shell installer downloads the latest release archive, verifies its
checksum, and installs `garyx` to `/usr/local/bin` by default, using `sudo` if
that directory is not writable. The Workflow runtime is embedded in the Garyx
binary and is expanded into Garyx-managed storage only when a Workflow task is
first executed. The installer does not initialize config, start the gateway, or
re-sign the release binary.

```bash
curl -fsSL https://raw.githubusercontent.com/Pyiner/garyx/main/install.sh | bash
garyx --version
```

Other install paths:

```bash
# Homebrew
brew tap pyiner/garyx
brew install pyiner/garyx/garyx

# From source
git clone https://github.com/Pyiner/garyx
cd garyx
scripts/install-local-cli.sh
```

Install and start the managed gateway service, then run onboarding against the
running gateway:

```bash
garyx gateway install
garyx onboard
garyx status
```

`garyx gateway install` writes the launchd plist on macOS or the systemd user
unit on Linux, then starts the gateway. Re-run it after upgrades or service
file changes.

## Connect a Telegram bot

The first concrete Garyx flow should be a real channel bot. Create a Telegram
bot with [@BotFather](https://t.me/BotFather), store the token in an
environment variable, then register that account with Garyx:

```bash
export TELEGRAM_BOT_TOKEN="TOKEN_FROM_BOTFATHER"
garyx channels add telegram main \
  --token "$TELEGRAM_BOT_TOKEN" \
  --agent-id claude
garyx gateway restart --no-wake
```

DM the bot. Garyx will create or resume a thread for that Telegram chat and
route messages to the agent bound by `--agent-id`.

The example above uses the built-in `claude` agent. Pick the provider you plan
to use and make sure its CLI is logged in before expecting the bot to answer:

```bash
claude auth login
codex login
gemini auth login
```

The same account model works for Feishu / Lark, WeChat, and channel plugins:

```bash
garyx channels login feishu --domain feishu
garyx channels login weixin
garyx plugins install ./path/to/garyx-plugin-example
```

## Common workflows

| Workflow | Command or surface |
| --- | --- |
| Chat with a workspace from the terminal | `garyx thread create --workspace-dir "$PWD"` then `garyx thread send ...` |
| Route a channel bot to an agent | `garyx channels add <channel> <account_id> --agent-id <agent_id>` |
| Continue a bot conversation from the CLI | `garyx thread history <thread_id>` and `garyx thread send thread <thread_id> ...` |
| Promote work into a reviewable task | `garyx task create --title "..." --body "..." --notify current-thread` |
| Schedule recurring agent work | `garyx automation create --label "Daily triage" --prompt "..." --every-hours 24` |
| Inspect gateway issues | `garyx status`, `garyx doctor`, `garyx logs tail` |
| Update the CLI | `garyx update` |
| Update channel plugins | `garyx plugins update [<plugin_id>]` |
| Work on the mobile client | `cd mobile/garyx-mobile && swift test` |

## Architecture

```text
Humans and systems
  -> Telegram / Feishu / WeChat / CLI / Desktop / HTTP / WebSocket
  -> Garyx gateway
  -> Router, transcripts, endpoint bindings, tasks, automations
  -> Provider bridge: Claude Code / Codex / Gemini / agent teams
  -> Scoped MCP endpoint and configured upstream MCP servers
```

Important runtime boundaries:

- The gateway is the single writer for channel endpoint bindings and task
  state.
- A thread's `workspace_dir` is fixed once the thread starts; create a new
  thread for a d

... (truncated)